fix(examples): the verbose-content test moves into the step that wires it [skip-docs]

Operator 2026-10-09: step 6 of examples/01-add-verbose-flag only added a
test for behaviour step 5 delivered - the pattern PLAN_STEP_TESTS_ONLY
warns on. It now lands in step 5 (Verify: the new test, red before the
wiring; Regression: the stability harness), the help-text step becomes
step 6, and progress.json follows (6 steps). Steps 1-2 (golden capture and
stability harness, tests of today's behaviour that cannot be red) keep
the warning; a step type for them is a wave 3 question.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

examples/01-add-verbose-flag/plan.md

@@ -150,16 +150,17 @@ or stability harness comes before behavior change.
 
 ### Step 5: Wire verbose output in `login`, `token-refresh`, `users-list`, `users-create`, `logout`
 
-- **Files:** `src/commands/login.mjs`, `src/commands/token-refresh.mjs`, `src/commands/users-list.mjs`, `src/commands/users-create.mjs`, `src/commands/logout.mjs`
+- **Files:** `src/commands/login.mjs`, `src/commands/token-refresh.mjs`, `src/commands/users-list.mjs`, `src/commands/users-create.mjs`, `src/commands/logout.mjs`, `tests/cli-verbose-flag.test.mjs` (new file)
-- **Changes:** At each internal step (3 for login, 4 for token-refresh, 2 for users-list, 3 for users-create, 2 for logout — 14 call sites total), add `if (ctx.verbose) ctx.stderr.write(\`[verbose] <step description>\\n\`);`. Step descriptions per file:
+- **Changes:** First the test, `tests/cli-verbose-flag.test.mjs`: spawn `node src/cli.mjs login --verbose alice`, capture stderr, assert exit 0, assert stderr contains all three expected verbose lines: "[verbose] parsing argv", "[verbose] credential lookup", "[verbose] issuing session token", in that order. It fails before the wiring below (no verbose lines yet): the test for a behaviour lands in the step that builds it. Then, at each internal step (3 for login, 4 for token-refresh, 2 for users-list, 3 for users-create, 2 for logout — 14 call sites total), add `if (ctx.verbose) ctx.stderr.write(\`[verbose] <step description>\\n\`);`. Step descriptions per file:
   - login: "parsing argv", "credential lookup", "issuing session token"
   - token-refresh: "parsing argv", "validating refresh token", "rotating session token", "persisting new token"
   - users-list: "parsing argv", "querying user store"
   - users-create: "parsing argv", "validating input", "writing user record"
   - logout: "parsing argv", "invalidating session token"
-- **Verify:** `node --test tests/cli-no-verbose-stability.test.mjs` → expected: 3 pass (stdout unchanged when flag absent)
+- **Verify:** `node --test tests/cli-verbose-flag.test.mjs` → expected: 1 pass
+- **Regression:** `node --test tests/cli-no-verbose-stability.test.mjs` → expected: 3 pass (stdout unchanged when flag absent)
 - **Checkpoint:** `git commit -m "feat(commands): emit verbose stderr trace for 5 commands"`
-- **On failure:** retry — stability tests fail → likely a stray `console.log` or `ctx.stdout.write` instead of `ctx.stderr.write`. Re-grep all five files for `stdout` mentions added in this step.
+- **On failure:** retry — stability tests fail → likely a stray `console.log` or `ctx.stdout.write` instead of `ctx.stderr.write`. Re-grep all five files for `stdout` mentions added in this step. If the verbose test misses a line, check the `[verbose]` strings for typos; if its exit code != 0, check that login still works without verbose.
 - **Manifest:**
   ```yaml
   manifest:
@@ -169,7 +170,8 @@ or stability harness comes before behavior change.
       - src/commands/users-list.mjs
       - src/commands/users-create.mjs
       - src/commands/logout.mjs
-    min_file_count: 5
+      - tests/cli-verbose-flag.test.mjs
+    min_file_count: 6
     commit_message_pattern: "^feat\\(commands\\): emit verbose"
     bash_syntax_check: []
     forbidden_paths: []
@@ -178,30 +180,11 @@ or stability harness comes before behavior change.
         pattern: "ctx\\.verbose"
       - path: src/commands/token-refresh.mjs
         pattern: "ctx\\.verbose"
-  ```
-
-### Step 6: Add verbose-content test for `login`
-
-- **Files:** `tests/cli-verbose-flag.test.mjs` (new file)
-- **Changes:** Single test: spawn `node src/cli.mjs login --verbose alice`, capture stderr, assert exit 0, assert stderr contains all three expected verbose lines: "[verbose] parsing argv", "[verbose] credential lookup", "[verbose] issuing session token", in that order.
-- **Verify:** `node --test tests/cli-verbose-flag.test.mjs` → expected: 1 pass
-- **Checkpoint:** `git commit -m "test(small-auth): assert --verbose emits expected stderr trace"`
-- **On failure:** retry — if assertion misses a line, check step 5 for typos in the `[verbose]` strings; if exit code != 0, check that login still works without verbose (regression).
-- **Manifest:**
-  ```yaml
-  manifest:
-    expected_paths:
-      - tests/cli-verbose-flag.test.mjs
-    min_file_count: 1
-    commit_message_pattern: "^test\\(small-auth\\): assert --verbose"
-    bash_syntax_check: []
-    forbidden_paths: []
-    must_contain:
       - path: tests/cli-verbose-flag.test.mjs
         pattern: "\\[verbose\\] credential lookup"
   ```
 
-### Step 7: Update `--help` text
+### Step 6: Update `--help` text
 
 - **Files:** `src/cli.mjs`
 - **Changes:** At the help-text constant (`src/cli.mjs:78`), add a line under "Global flags": `  -v, --verbose       emit per-step trace to stderr (single level only)`.
@@ -224,7 +207,7 @@ or stability harness comes before behavior change.
 
 ## Verification
 
-Final acceptance run after step 7:
+Final acceptance run after step 6:
 
 ```bash
 node --test tests/                                   # all 26 tests pass (24 + 2 new)
@@ -239,13 +222,14 @@ node src/cli.mjs --help | grep -c "\-v, --verbose"   # 1
 
 - No deferred decisions: every step names its files, lines, and exact
   string changes.
-- TDD: stability harness (step 2) precedes behavior changes (steps 3-5).
+- TDD: stability harness (step 2) precedes behavior changes (steps 3-5),
+  and the verbose-content test lands in step 5, with the code it tests.
 - Verify commands are runnable, not "test it works".
-- Steps 5 wires 5 files in one commit; this is over the 1–2 file
+- Step 5 wires 5 files (and their test) in one commit; this is over the 1–2 file
   guideline but is justified by symmetry — the change is mechanical
   and atomic across the five files; splitting would create five tiny
   commits with no test value between them.
 
 ## Execution Strategy
 
-Single session, 7 steps, ~15-20 minutes. No parallel decomposition needed.
+Single session, 6 steps, ~15-20 minutes. No parallel decomposition needed.

examples/01-add-verbose-flag/progress.json

@@ -9,8 +9,8 @@
   "started_at": "2026-05-01T10:14:32Z",
   "updated_at": "2026-05-01T10:31:08Z",
   "status": "completed",
-  "current_step": 7,
+  "current_step": 6,
-  "total_steps": 7,
+  "total_steps": 6,
   "steps": [
     {
       "n": 1,
@@ -67,31 +67,20 @@
       "title": "Wire verbose output in login, token-refresh, users-list, users-create, logout",
       "status": "completed",
       "started_at": "2026-05-01T10:22:13Z",
-      "completed_at": "2026-05-01T10:27:34Z",
+      "completed_at": "2026-05-01T10:29:51Z",
       "commit_sha": "a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4",
       "files_changed": [
         "src/commands/login.mjs",
         "src/commands/token-refresh.mjs",
         "src/commands/users-list.mjs",
         "src/commands/users-create.mjs",
-        "src/commands/logout.mjs"
+        "src/commands/logout.mjs",
-      ],
-      "verify_passed": true
-    },
-    {
-      "n": 6,
-      "title": "Add verbose-content test for login",
-      "status": "completed",
-      "started_at": "2026-05-01T10:27:34Z",
-      "completed_at": "2026-05-01T10:29:51Z",
-      "commit_sha": "b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5",
-      "files_changed": [
         "tests/cli-verbose-flag.test.mjs"
       ],
       "verify_passed": true
     },
     {
-      "n": 7,
+      "n": 6,
       "title": "Update --help text",
       "status": "completed",
       "started_at": "2026-05-01T10:29:51Z",

tests/lib/retterunde.test.mjs

@@ -19,7 +19,7 @@ import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { validatePlan, validatePlanContent } from '../../lib/validators/plan-validator.mjs';
-import { stepTestsOnly } from '../../lib/parsers/plan-schema.mjs';
+import { parseStepFields, sliceSteps, stepTestsOnly } from '../../lib/parsers/plan-schema.mjs';
 import { proveRed } from '../../lib/verification/red-proof.mjs';
 import { runCriteria } from '../../lib/verification/criteria-runner.mjs';
 import { buildPlan } from '../helpers/plan-v18-builder.mjs';
@@ -191,6 +191,26 @@ test('5: a nested `node --test` on a failing test is red even when NODE_TEST_CON
   }
 });
 
+// Operator 2026-10-09: the example's verbose-content test moves into the step
+// that wires the verbose output; steps 1-2 (golden capture and the stability
+// harness: tests of today's behaviour, never red) keep the warning, and a step
+// type for them is a wave 3 question.
+test('1: the example plan warns only on its two golden/stability steps; the verbose test sits with the code', () => {
+  const r = validatePlan(join(ROOT, 'examples', '01-add-verbose-flag', 'plan.md'));
+  const w = r.warnings.filter((x) => x.code === 'PLAN_STEP_TESTS_ONLY').map((x) => x.message.match(/Step (\d+)/)[1]);
+  assert.deepEqual(w, ['1', '2']);
+  const text = readFileSync(join(ROOT, 'examples', '01-add-verbose-flag', 'plan.md'), 'utf8');
+  const step = sliceSteps(text).find((s) => /tests\/cli-verbose-flag\.test\.mjs/.test(parseStepFields(s.body).get('Files')?.text ?? ''));
+  assert.ok(step, 'a step lists tests/cli-verbose-flag.test.mjs in Files');
+  assert.match(parseStepFields(step.body).get('Files').text, /src\/commands\/login\.mjs/);
+  // The run record follows the plan: one entry per step.
+  const progress = JSON.parse(readFileSync(join(ROOT, 'examples', '01-add-verbose-flag', 'progress.json'), 'utf8'));
+  const n = r.parsed.steps.length;
+  assert.equal(progress.total_steps, n);
+  assert.equal(progress.current_step, n);
+  assert.deepEqual(progress.steps.map((s) => s.n), Array.from({ length: n }, (_, i) => i + 1));
+});
+
 // Guard against a reading of the example that counts nothing: it has steps.
 test('3: the example plan is read (six or more steps)', () => {
   const text = readFileSync(join(ROOT, 'examples', '01-add-verbose-flag', 'plan.md'), 'utf8');