diff --git a/plugins/ultraplan-local/examples/02-real-cli/REGENERATED.md b/plugins/ultraplan-local/examples/02-real-cli/REGENERATED.md index a5cf2f3..a17a230 100644 --- a/plugins/ultraplan-local/examples/02-real-cli/REGENERATED.md +++ b/plugins/ultraplan-local/examples/02-real-cli/REGENERATED.md @@ -3,20 +3,41 @@ | Field | Value | |-------|-------| | Calibrated against | ultraplan-local v3.4.1 | -| Last regenerated | TBD — filled in after the B3 pipeline run | +| Last regenerated | 2026-05-04 (B3 session) | | Source brief author | Hand-authored by operator (B1 session, 2026-05-04) | -| Baseline author | B2 session, 2026-05-04 | -| Pipeline run | TBD — B3 will run `/ultraresearch-local`, `/ultraplan-local`, `/ultraexecute-local` | +| Baseline author | B2 session, 2026-05-04 (commit `c8146c1`) | +| Pipeline run | B3 session, 2026-05-04 (commits `c4cf49f` → `da68c2f`) | ## What this example demonstrates -(Placeholder — fylles ut når B3-pipeline-runet er ferdig. Skal forklare -hvorfor 02-real-cli er en *runnable* fixture, i motsetning til 01-add-verbose-flag -som kun er artifacts.) +`examples/02-real-cli/` is the first **runnable** ultraplan-local example. +Unlike `examples/01-add-verbose-flag/` (which ships a frozen brief, plan, +and research as artifacts but no executable code), this example ships a +working ~80-line Node.js CLI (`tally`), a passing test suite, and known +fixture data — all designed to be the input for a real pipeline run. -## Baseline (delivered by B2, 2026-05-04) +The fixture's purpose is twofold: -`tally` — a ~80-line zero-dep Node.js CLI that counts literal-substring +1. **End-to-end pipeline validation:** running `/ultraresearch-local`, + `/ultraplan-local`, and `/ultraexecute-local` against `brief.md` must + produce green commits that satisfy all 10 brief Success Criteria. This + is the controlled environment used to verify pipeline correctness on + release-validation passes (see "Regeneration triggers" below). + +2. **Cache-prefix measurement target (Spor C, planned):** the next track + in the post-v3.4.0 roadmap will use this fixture under + `CLAUDE_CODE_FORK_SUBAGENT` to measure cache-prefix preservation + semantics. The fixture is small enough to fit comfortably under the + 150-250K context window where Path C measurements need to happen. + +The brief deliberately picks a small, well-scoped feature (single boolean +flag with regex semantics) so the pipeline output is predictable and +testable, while still exercising the full plan/execute machinery +(manifest YAML, plan-critic, scope-guardian, per-step verify, progress.json). + +## Baseline (delivered by B2, 2026-05-04, commit `c8146c1`) + +`tally` — an 80-line zero-dep Node.js CLI that counts literal-substring occurrences of a pattern in a text file. Three flags (`--json`, `-i`/`--ignore-case`, `--lines`), `--help`, exit codes 0/1/2. @@ -24,50 +45,165 @@ Layout: ``` examples/02-real-cli/ -├── tally.mjs # CLI (≈ 80 lines, hand-rolled argv parser) -├── tests/tally.test.mjs # 10 node:test cases (all pass < 3s) +├── tally.mjs # CLI (80 lines, hand-rolled argv parser) +├── tests/tally.test.mjs # 10 node:test cases (all pass ~2.2s) ├── fixtures/ -│ ├── sample.txt # 9-line input with known counts (foo×7, Foo×1, fo+ regex × 9) -│ └── poem.txt # 5-line input for --lines vs total distinction +│ ├── sample.txt # 9 lines, known counts (foo×7, Foo×1, /fo+/g×9, .×4) +│ ├── poem.txt # 5 lines, "foo" --lines = 3, total = 4 └── REGENERATED.md # this file ``` -(Placeholder — utvides med en mini-walk-through av baseline når B3 har -sluttført pipeline-runet.) +Baseline preconditions verified by B2: -## Pipeline run (delivered by B3, TBD) +- `grep -c 'foo' fixtures/sample.txt` returns 4 lines containing `foo` + (literal `foo` count = 7 across those lines). +- regex `/fo+/g` matchAll on `sample.txt` = 9 (greater than literal `foo` + count, as required by brief SC #1). +- `--lines foo poem.txt` = 3, total `foo` in `poem.txt` = 4 (exercises + `--lines` distinction in baseline tests). + +## Pipeline run (delivered by B3, 2026-05-04) + +The pipeline ran against `brief.md` (research_topics: 0, hand-authored). +Each phase produced an artifact in +`.claude/projects/2026-05-04-examples-02-real-cli/`. ### `/ultraresearch-local` -(Placeholder — research-swarmen forventes å rapportere 0 topics og produsere -en kort placeholder-brief. Fyll inn faktisk output her.) +**Outcome: skipped (intentionally).** + +Brief declares `research_topics: 0` and `research_status: complete`. +The brief's "Research Plan" section is explicit: + +> No external research needed — this is a pure Node.js stdlib + `node:test` +> task, the codebase fixture is self-contained, and the regex semantics +> needed (`new RegExp(p)` + `String.prototype.matchAll`) are well-documented +> MDN material. + +Following the prompt's guidance ("Ikke kjør Gemini-bridge eller +community-researcher for trivielle Node-stdlib-spørsmål"), the swarm was +not invoked. No research file was written; `research/` directory does not +exist for this project. Downstream commands (`/ultraplan-local`) auto-discover +research files but do not require them — the missing directory is fine +per the soft-mode `research-validator` contract. ### `/ultraplan-local` -(Placeholder — plan.md forventes med 3–5 steg som målretter `tally.mjs` -+ `tests/tally.test.mjs`. Lim inn step-overskrifter + manifest-summary.) +**Outcome: plan.md with 4 steps; plan-validator strict PASS; +plan-critic 0 BLOCKER (4 MAJOR fixed in revision); scope-guardian +PASS — ALIGNED.** + +`plan.md` headers: + +``` +# Add `--regex`/`-r` mode to the `tally` CLI fixture +plan_version: 1.7 + +## Context +## Codebase Analysis +## Research Sources +## Implementation Plan +### Step 1: Add `--regex`/`-r` parsing and `compileRegex` helper +### Step 2: Wire regex counting path in `main()` +### Step 3: Update `--help` text to document `--regex`/`-r` +### Step 4: Add 4 new tests covering the regex path +## Verification +## Plan-critic notes +## Scope-guardian notes +## Execution Strategy +``` + +Adversarial-review summary: + +| Reviewer | Verdict | Findings | +|----------|---------|----------| +| `plan-critic` | REVISE → re-run after fixes | 0 BLOCKER, 4 MAJOR (non-assertive verify in step 1; unchained verify in step 2; SC #9 final-block mismatch; `compileRegex` 'g' flag rationale missing). All 4 fixed. | +| `scope-guardian` | PASS — ALIGNED | 0 creep, 0 material gaps. Every brief SC and Non-Goal mapped to a step or manifest constraint. | + +Manifest YAML on every step uses `forbidden_paths: examples/02-real-cli/package.json` +to enforce the brief's "no package.json" Non-Goal. `must_contain` patterns +require named symbols (`flags.regex`, `compileRegex`, `--regex 'fo+'`, +`-r short form`, `invalid regex`) so the verifier confirms substantive +changes, not just file modifications. ### `/ultraexecute-local` -(Placeholder — `progress.json` forventes med `verify_passed: true` på alle -steg. Lim inn commit-SHA-ene + steg-tellingen.) +**Outcome: 4 commits, all green, all `verify_passed: true`.** + +`progress.json` summary: + +```json +{ + "schema_version": "1", + "plan_version": "1.7", + "mode": "single-session", + "status": "completed", + "total_steps": 4, + "current_step": 4 +} +``` + +Step-by-step: + +| Step | Commit | Title | Verify | +|------|--------|-------|--------| +| 1 | `c4cf49f` | feat(tally): parse --regex/-r flag and add compileRegex helper | flag parsed, literal count = 7 | +| 2 | `44d7f33` | feat(tally): wire regex counting path in main with invalid-regex exit-2 | OK1, OK2, OK3, OK4 (4 chained assertions) | +| 3 | `c6ff4fa` | docs(tally): document --regex / -r in --help text | `--help \| grep -c -- "--regex"` = 1 | +| 4 | `da68c2f` | test(tally): add 4 tests for --regex/-r path covering SC #1, #2, #4, #5 | tests 14, pass 14, fail 0, duration_ms 3162.74 | + +Constraint compliance: + +- `tally.mjs`: 93 lines (under 100-line cap, +13 from 80-line baseline) +- `tests/tally.test.mjs`: 14 tests (exactly at 14-test cap, +4 from 10-test baseline) +- Test wall-clock: 3.16 s (under 5 s cap) +- `package.json`: not created (Non-Goal enforced) +- Files outside `examples/02-real-cli/`: zero +- Hook safety: zero shutdown/halt/reboot/poweroff/mkfs words in commit + bodies or verify commands + +### Success Criteria status (10/10 PASS) + +| SC | Verifier | Result | +|----|----------|--------| +| #1 | flag in 3 positions, all exit 0, same count | PASS (all = 9) | +| #2 | `-r 'fo+' sample.txt` == long form | PASS (both = 9) | +| #3 | `tally '.' sample.txt` (= 4) << `tally --regex '.' sample.txt` (= 209) | PASS | +| #4 | `tally --regex '[' sample.txt` exits 2, stderr `^tally: invalid regex` | PASS | +| #5 | `--json --regex 'fo+'` includes `flags.regex: true` | PASS | +| #6 | `tally 'foo' sample.txt` = 7 (= B2 baseline) | PASS | +| #7 | tests ≥ 12, ≥ 2 names contain `--regex` or `-r` | PASS (14 tests, 4 named) | +| #8 | `tally --help` contains `--regex` line | PASS | +| #9 | `REGENERATED.md` walk-through filled in | PASS (this file) | +| #10 | no `package.json` created | PASS | ## How to re-run this example ```bash cd /path/to/ultraplan-local + # 1. Re-run the pipeline against the existing brief -/ultraresearch-local --project .claude/projects/2026-05-04-examples-02-real-cli +# (research is skipped — research_topics: 0) /ultraplan-local --project .claude/projects/2026-05-04-examples-02-real-cli /ultraexecute-local --project .claude/projects/2026-05-04-examples-02-real-cli -# 2. Verify all 10 Success Criteria from brief.md hold: -node --test examples/02-real-cli/tests/tally.test.mjs +# 2. Verify all 10 Success Criteria from brief.md hold (commands above) +node --test examples/02-real-cli/tests/tally.test.mjs # 14 pass + +# 3. Smoke-test individual SC commands: node examples/02-real-cli/tally.mjs --regex 'fo+' examples/02-real-cli/fixtures/sample.txt -node examples/02-real-cli/tally.mjs --json --regex 'fo+' examples/02-real-cli/fixtures/sample.txt +# expected: 9 +node examples/02-real-cli/tally.mjs -r 'fo+' examples/02-real-cli/fixtures/sample.txt +# expected: 9 +node examples/02-real-cli/tally.mjs --json --regex 'fo+' examples/02-real-cli/fixtures/sample.txt | python3 -m json.tool +# expected: {"pattern": "fo+", "count": 9, "flags": {..., "regex": true}} +node examples/02-real-cli/tally.mjs --help | grep -- "--regex" +# expected: " -r, --regex Interpret as a JavaScript regular expression" ``` -(Placeholder — utvides med eksakte forventede verdier etter B3.) +If any of those expected values changes, the pipeline output has drifted +and `examples/02-real-cli/` should be re-baselined (see "Regeneration +triggers" below). ## Regeneration triggers @@ -80,6 +216,9 @@ When to re-run this example: - Pipeline-output format change (brief / research / plan / progress) When regenerating: re-run the pipeline against the existing `brief.md` and -update this file plus `examples/02-real-cli/` artifacts. The fixture itself -(`tally.mjs`, fixtures, baseline tests) stays stable across regenerations — -only the pipeline outputs change. +update this file plus the `examples/02-real-cli/` artifacts. The +"baseline" portion of the fixture (`tally.mjs` minus the regex feature, +the fixture text files, and the original 10 baseline tests) stays stable +across regenerations — only the pipeline outputs and any drift in the +extended `tally.mjs` change. If you want a clean re-run, reset to commit +`c8146c1` (B2 baseline) before invoking the pipeline.