@chief-clancy/plan 0.4.2 → 0.5.1

package/src/workflows/workflows.test.ts

@@ -863,8 +863,16 @@ describe('approve-plan local marker (Step 4a)', () => {
     );
   });
 
-  it('after writing the marker, Step 4a jumps to Step 7 (log) and skips board flow', () => {
-    expect(content).toContain('jump to Step 7');
+  it('after writing the marker, Step 4a continues to Step 4c (PR 9 — was Step 7 in PR 7b)', () => {
+    // PR 7b's "jump to Step 7" was rewritten in PR 9 slice 1 / DA H2 fix:
+    // the post-marker tail now hands off to Step 4c (Optional board push),
+    // which is best-effort and gates on board credentials. Steps 5/5b/6
+    // remain unreachable in plan-file stem mode regardless.
+    const afterMarkerIdx = content.indexOf('### After writing the marker');
+    const tailEnd = content.indexOf('---', afterMarkerIdx);
+    const tail = content.slice(afterMarkerIdx, tailEnd);
+    expect(tail).toMatch(/Step 4c/);
+    expect(tail).toMatch(/Steps 5, 5b, and 6[^.]*skipped/i);
   });
 });
 
@@ -1006,3 +1014,651 @@ describe('approve-plan board mode preserved unchanged', () => {
     expect(content).toContain('Notion');
   });
 });
+
+// PR 9 — Slice 0/6: drift-prevention for the duplicated push curl blocks.
+// Slice 0 declared the start/end anchors in both files. Slice 6 promotes
+// this suite to a byte-equality check between the wrapped regions: the
+// canonical curl blocks live in plan.md Step 5b; approve-plan.md Step 4c
+// holds an identical duplicate.
+describe('approve-plan board push drift anchors (PR 9 Slice 0/6)', () => {
+  const planContent = readFileSync(new URL('plan.md', import.meta.url), 'utf8');
+  const approveContent = readFileSync(
+    new URL('approve-plan.md', import.meta.url),
+    'utf8',
+  );
+
+  const startAnchor = '<!-- curl-blocks:approve-plan-push:start -->';
+  const endAnchor = '<!-- curl-blocks:approve-plan-push:end -->';
+
+  const extractRegion = (source: string): string => {
+    const startIdx = source.indexOf(startAnchor);
+    const endIdx = source.indexOf(endAnchor);
+    if (startIdx === -1 || endIdx === -1 || startIdx > endIdx) {
+      throw new Error('curl-blocks anchors missing or out of order');
+    }
+    return source.slice(startIdx + startAnchor.length, endIdx);
+  };
+
+  it('plan.md declares the start anchor exactly once', () => {
+    const matches = planContent.split(startAnchor).length - 1;
+    expect(matches).toBe(1);
+  });
+
+  it('plan.md declares the end anchor exactly once', () => {
+    const matches = planContent.split(endAnchor).length - 1;
+    expect(matches).toBe(1);
+  });
+
+  it('plan.md start anchor precedes end anchor', () => {
+    expect(planContent.indexOf(startAnchor)).toBeLessThan(
+      planContent.indexOf(endAnchor),
+    );
+  });
+
+  it('approve-plan.md declares the start anchor exactly once', () => {
+    const matches = approveContent.split(startAnchor).length - 1;
+    expect(matches).toBe(1);
+  });
+
+  it('approve-plan.md declares the end anchor exactly once', () => {
+    const matches = approveContent.split(endAnchor).length - 1;
+    expect(matches).toBe(1);
+  });
+
+  it('approve-plan.md start anchor precedes end anchor', () => {
+    expect(approveContent.indexOf(startAnchor)).toBeLessThan(
+      approveContent.indexOf(endAnchor),
+    );
+  });
+
+  it('the duplicated curl-blocks region is byte-equal between the two files', () => {
+    const planRegion = extractRegion(planContent);
+    const approveRegion = extractRegion(approveContent);
+    expect(approveRegion).toBe(planRegion);
+  });
+
+  it('the duplicated region is non-empty (slice 6 populated it)', () => {
+    const planRegion = extractRegion(planContent);
+    expect(planRegion.length).toBeGreaterThan(100);
+    // Sanity: region must contain at least one of the six platform headings.
+    expect(planRegion).toMatch(/### Jira/);
+  });
+});
+
+// PR 9 — Slice 1: Step 4c heading + run conditions. Step 4c is the optional
+// board push, gated on (a) Step 4a having written a marker AND (b) board
+// credentials being present in .clancy/.env. Either gate failing → skip
+// silently and continue to Step 7. Step 4b's tail must now route through 4c
+// instead of jumping straight to Step 7.
+describe('approve-plan Step 4c run conditions (PR 9 Slice 1)', () => {
+  const content = readFileSync(
+    new URL('approve-plan.md', import.meta.url),
+    'utf8',
+  );
+
+  it('defines Step 4c — Optional board push', () => {
+    expect(content).toContain('## Step 4c — Optional board push (best-effort)');
+  });
+
+  it('Step 4c is positioned after Step 4b and before Step 5', () => {
+    const stepFourB = content.indexOf('## Step 4b — Update brief marker');
+    const stepFourC = content.indexOf('## Step 4c — Optional board push');
+    const stepFive = content.indexOf('## Step 5 — Update ticket description');
+    expect(stepFourB).toBeGreaterThan(-1);
+    expect(stepFourC).toBeGreaterThan(stepFourB);
+    expect(stepFive).toBeGreaterThan(stepFourC);
+  });
+
+  it('Step 4c gates on Step 4a having written the marker', () => {
+    const fourCStart = content.indexOf('## Step 4c — Optional board push');
+    const fourCEnd = content.indexOf('## Step 5 — Update ticket description');
+    const fourCBody = content.slice(fourCStart, fourCEnd);
+    // Run-condition prose must reference the marker write from 4a.
+    expect(fourCBody).toMatch(/Step 4a/);
+    expect(fourCBody).toMatch(/marker/i);
+  });
+
+  it('Step 4c gates on board credentials being available', () => {
+    const fourCStart = content.indexOf('## Step 4c — Optional board push');
+    const fourCEnd = content.indexOf('## Step 5 — Update ticket description');
+    const fourCBody = content.slice(fourCStart, fourCEnd);
+    expect(fourCBody).toContain('.clancy/.env');
+    expect(fourCBody).toMatch(/board credentials/i);
+  });
+
+  it('Step 4c skips silently when either gate fails and continues to Step 7', () => {
+    const fourCStart = content.indexOf('## Step 4c — Optional board push');
+    const fourCEnd = content.indexOf('## Step 5 — Update ticket description');
+    const fourCBody = content.slice(fourCStart, fourCEnd);
+    // "skip silently" + onward routing to Step 7.
+    expect(fourCBody).toMatch(/skip[^.]*silent/i);
+    expect(fourCBody).toMatch(/Step 7/);
+  });
+
+  it('Step 4c is best-effort and never rolls back the local marker', () => {
+    const fourCStart = content.indexOf('## Step 4c — Optional board push');
+    const fourCEnd = content.indexOf('## Step 5 — Update ticket description');
+    const fourCBody = content.slice(fourCStart, fourCEnd);
+    expect(fourCBody).toMatch(/best-effort/i);
+    // Marker is authoritative; push failure must not roll back.
+    expect(fourCBody).toMatch(
+      /never[^.]*rolls?[- ]?back|do(?:es)? not rolls?[- ]?back/i,
+    );
+  });
+
+  it('Step 4b tail now routes through Step 4c instead of jumping to Step 7', () => {
+    const fourBStart = content.indexOf('## Step 4b — Update brief marker');
+    const fourCStart = content.indexOf('## Step 4c — Optional board push');
+    const fourBBody = content.slice(fourBStart, fourCStart);
+    // 4b should hand off to 4c, not directly to Step 7.
+    expect(fourBBody).toMatch(/Step 4c/);
+    // The old "skip Steps 5, 5b, and 6 entirely" line must be gone — push
+    // can still run via Step 4c when board credentials are present.
+    expect(fourBBody).not.toMatch(/Skip Steps 5, 5b, and 6 entirely/);
+  });
+
+  it('no stale "jump to Step 7" routing prose remains in Steps 4a/4b', () => {
+    // DA review H2/L2: the stale routing prose ("jump to Step 7" / "Steps
+    // 5, 5b, 6 are skipped entirely") existed in BOTH Step 4a's "After
+    // writing the marker" subsection AND Step 4b's tail. Slice 1 only
+    // rewrote 4b. This regression test scans the whole 4a→4c span and
+    // asserts no leftover prose still implies a direct 4a/4b → 7 jump.
+    const fourAStart = content.indexOf('## Step 4a — Write local marker');
+    const fourCStart = content.indexOf('## Step 4c — Optional board push');
+    const span = content.slice(fourAStart, fourCStart);
+    expect(span).not.toMatch(/jump to Step 7/i);
+    expect(span).not.toMatch(/Skip Steps 5, 5b, and 6 entirely/);
+  });
+
+  it('Step 4a "After writing the marker" continues to Step 4c', () => {
+    // DA review H2: the Step 4a tail must explicitly hand off to 4c so
+    // an LLM reading 4a in order doesn't internalise the old PR 7b flow.
+    const afterMarkerIdx = content.indexOf('### After writing the marker');
+    const nextHeadingIdx = content.indexOf('---', afterMarkerIdx);
+    const afterMarkerBody = content.slice(afterMarkerIdx, nextHeadingIdx);
+    expect(afterMarkerBody).toMatch(/Step 4c/);
+  });
+});
+
+// PR 9 — Slice 2: Source field is read directly from the local plan file's
+// **Source:** header (NOT chased through the brief file the way Step 4b does).
+// The plan header is the single source of truth for Step 4c.
+describe('approve-plan Step 4c source-field read (PR 9 Slice 2)', () => {
+  const content = readFileSync(
+    new URL('approve-plan.md', import.meta.url),
+    'utf8',
+  );
+  const fourCStart = content.indexOf('## Step 4c — Optional board push');
+  const fourCEnd = content.indexOf('## Step 5 — Update ticket description');
+  const fourCBody = content.slice(fourCStart, fourCEnd);
+
+  it('Step 4c reads the **Source:** header from the plan file', () => {
+    expect(fourCBody).toContain('**Source:**');
+    expect(fourCBody).toContain('.clancy/plans/{stem}.md');
+  });
+
+  it('Step 4c does NOT open the brief file to find Source', () => {
+    // The brief-file path pattern (.clancy/briefs/) appears in Step 4b but
+    // must not appear in Step 4c — slice 2 reads Source from the plan file
+    // directly to avoid a second filesystem hop.
+    expect(fourCBody).not.toContain('.clancy/briefs/');
+  });
+
+  it('Step 4c documents the read order (after marker, before Source parse)', () => {
+    // The read happens inside Step 4c body, after the run-condition gates
+    // and before the (slice 3) format detection. Test the prose calls out
+    // "read" and "**Source:**" together so the order is unambiguous.
+    expect(fourCBody).toMatch(/read[^.]*\*\*Source:\*\*/i);
+  });
+
+  it('Step 4c handles a missing **Source:** header gracefully', () => {
+    // If the plan file has no **Source:** line, Step 4c must skip silently
+    // (same semantics as the run-condition gates). No crash, no warning.
+    expect(fourCBody).toMatch(
+      /missing[^.]*\*\*Source:\*\*|no \*\*Source:\*\*/i,
+    );
+    expect(fourCBody).toMatch(/skip/i);
+  });
+});
+
+// PR 9 — Slice 3: three-format Source parser. Brief writes Source in one of
+// three formats (per brief.md ~806-810): [KEY] Title (bracketed, pushable),
+// "text" (inline quoted, no ticket), or path/to/file.md (file path, no
+// ticket). Bracketed → continue to slice 4 validation. Other two →
+// BOARD_PUSH_SKIPPED_NO_TICKET log token + stdout note + continue to Step 7.
+describe('approve-plan Step 4c source-format parser (PR 9 Slice 3)', () => {
+  const content = readFileSync(
+    new URL('approve-plan.md', import.meta.url),
+    'utf8',
+  );
+  const fourCStart = content.indexOf('## Step 4c — Optional board push');
+  const fourCEnd = content.indexOf('## Step 5 — Update ticket description');
+  const fourCBody = content.slice(fourCStart, fourCEnd);
+
+  it('Step 4c documents the three brief Source formats', () => {
+    // Bracketed key — the only pushable format.
+    expect(fourCBody).toMatch(/\[#?\d+\]|\[[A-Z]+-\d+\]|\[\{KEY\}\]/);
+    // Inline-quoted text format.
+    expect(fourCBody).toMatch(/inline[- ]quoted|"[^"]+"/i);
+    // File-path format.
+    expect(fourCBody).toMatch(/file[- ]path|\.md/);
+  });
+
+  it('Step 4c only pushes for the bracketed-key format', () => {
+    // Prose must explicitly say bracketed is the only pushable format.
+    expect(fourCBody).toMatch(
+      /bracket[^.]*only[^.]*push|only[^.]*bracket[^.]*push/i,
+    );
+  });
+
+  it('Step 4c logs BOARD_PUSH_SKIPPED_NO_TICKET for non-bracketed Source', () => {
+    expect(fourCBody).toContain('BOARD_PUSH_SKIPPED_NO_TICKET');
+  });
+
+  it('Step 4c skip-token logs to .clancy/progress.txt', () => {
+    // The skip token is a progress.txt row, not just stdout — same audit
+    // surface as LOCAL_APPROVE_PLAN.
+    expect(fourCBody).toMatch(
+      /BOARD_PUSH_SKIPPED_NO_TICKET[\s\S]*progress\.txt|progress\.txt[\s\S]*BOARD_PUSH_SKIPPED_NO_TICKET/,
+    );
+  });
+
+  it('Step 4c skip-token row uses the {stem} | TOKEN | {detail} convention', () => {
+    // Matches plan.md Step 6 / Step 7 LOCAL_APPROVE_PLAN convention:
+    //   {stem} | BOARD_PUSH_SKIPPED_NO_TICKET | {source_format}
+    expect(fourCBody).toMatch(
+      /\{stem\}\s*\\?\|\s*BOARD_PUSH_SKIPPED_NO_TICKET\s*\\?\|\s*\{source_format\}/,
+    );
+  });
+
+  it('Step 4c surfaces the skip in the local-mode success block', () => {
+    // Stdout note so the user knows why no push happened. Not a warning —
+    // an info line under the marker write success.
+    expect(fourCBody).toMatch(/stdout|success block|local[- ]mode/i);
+    expect(fourCBody).toMatch(/no pushable[^.]*ticket|no ticket[^.]*push/i);
+  });
+
+  it('Step 4c continues to Step 7 after a skip-no-ticket', () => {
+    // After logging the skip token, flow continues normally — not an error.
+    const skipRegion = fourCBody.slice(
+      fourCBody.indexOf('BOARD_PUSH_SKIPPED_NO_TICKET'),
+    );
+    expect(skipRegion).toMatch(/Step 7|continue|proceed/i);
+  });
+});
+
+// PR 9 — Slice 4: per-platform key validation. Once Source has been parsed
+// into a bracketed-key form, the extracted key must match the configured
+// board's regex BEFORE any push attempt. Six platforms, six inline regexes,
+// hard-error on mismatch — no second-chance fallback. Single-board env, no
+// cross-board disambiguation.
+describe('approve-plan Step 4c key validation (PR 9 Slice 4)', () => {
+  const content = readFileSync(
+    new URL('approve-plan.md', import.meta.url),
+    'utf8',
+  );
+  const fourCStart = content.indexOf('## Step 4c — Optional board push');
+  const fourCEnd = content.indexOf('## Step 5 — Update ticket description');
+  const fourCBody = content.slice(fourCStart, fourCEnd);
+
+  it('Step 4c declares all six per-platform key regexes inline', () => {
+    // Each assertion requires a literal `\d` (escaped backslash + d) so a
+    // doc that accidentally drops the backslash from the regex table fails
+    // the test instead of silently passing on a bare `d`. The Jira and
+    // Linear assertions match on the [A-Za-z] character class (their first
+    // distinguishing feature — lowercase allowed for parity with Step 2)
+    // and tighten with \\d for the digits.
+    // Jira: ^[A-Za-z][A-Za-z0-9]+-\d+$
+    expect(fourCBody).toMatch(/Jira[\s\S]{0,200}\[A-Za-z\]\[A-Za-z0-9\]\+-\\d/);
+    // GitHub: ^#?\d+$ — optional # so bare numbers are accepted (Step 2 parity)
+    expect(fourCBody).toMatch(/GitHub[\s\S]{0,200}#\?\\d/);
+    // Linear: ^[A-Za-z]{1,10}-\d+$
+    expect(fourCBody).toMatch(/Linear[\s\S]{0,200}\[A-Za-z\]\{1,10\}-\\d/);
+    // Azure DevOps: ^\d+$
+    expect(fourCBody).toMatch(/Azure DevOps[\s\S]{0,200}\\d/);
+    // Shortcut: ^(?:[A-Za-z]{1,5}-)?\d+$ — optional alpha prefix
+    expect(fourCBody).toMatch(
+      /Shortcut[\s\S]{0,200}\(\?:\[A-Za-z\]\{1,5\}-\)\?\\d/,
+    );
+    // Notion: ^(?:notion-[a-f0-9]{8}|[a-f0-9]{32}|[a-f0-9-]{36})$
+    // Match the full alternation structure literally so a partially deleted
+    // or malformed Notion regex (e.g. dropped one of the three branches,
+    // dropped the non-capturing group, lost the anchors) fails the test
+    // instead of passing on incidental notion- / [a-f0-9] tokens elsewhere.
+    expect(fourCBody).toMatch(
+      /Notion[\s\S]{0,400}\^\(\?:notion-\[a-f0-9\]\{8\}\|\[a-f0-9\]\{32\}\|\[a-f0-9-\]\{36\}\)\$/,
+    );
+  });
+
+  it('Step 4c selects the regex from the configured board (single-board env)', () => {
+    // Detection mirrors Step 1's three-state preflight — same .env reads.
+    expect(fourCBody).toMatch(/configured board|board.*configured/i);
+    expect(fourCBody).toMatch(/single[- ]board/i);
+  });
+
+  it('Step 4c validates the extracted key BEFORE any push attempt', () => {
+    // Validation must happen before the curl region — not after.
+    const validateIdx = fourCBody.search(/validat/i);
+    const anchorIdx = fourCBody.indexOf(
+      '<!-- curl-blocks:approve-plan-push:start -->',
+    );
+    expect(validateIdx).toBeGreaterThan(-1);
+    expect(anchorIdx).toBeGreaterThan(-1);
+    expect(validateIdx).toBeLessThan(anchorIdx);
+  });
+
+  it('Step 4c hard-errors on key/board mismatch (no fallback)', () => {
+    // Mismatch is a hard error — not a silent skip, not a warning. The
+    // user explicitly asked to push something the board can't accept.
+    expect(fourCBody).toMatch(/hard[- ]error|hard error/i);
+    // No second-chance — the test must reject prose suggesting a fallback
+    // platform attempt or a "try the other regex" path.
+    expect(fourCBody).not.toMatch(/try the other|fall ?back to[^.]*platform/i);
+  });
+
+  it('Step 4c key-mismatch error names the key and the configured board', () => {
+    // Error message must be actionable: which key, which board.
+    expect(fourCBody).toMatch(
+      /\{KEY\}[\s\S]{0,400}\{board\}|\{board\}[\s\S]{0,400}\{KEY\}/,
+    );
+  });
+
+  it('Step 4c key-mismatch DOES NOT roll back the local marker', () => {
+    // Same best-effort rule as push failure — the marker is authoritative.
+    // A bad --ticket override should never undo a successful Step 4a.
+    const mismatchRegion = fourCBody.slice(fourCBody.search(/hard[- ]error/i));
+    expect(mismatchRegion).toMatch(
+      /marker[^.]*(stays|preserved|kept|authoritative)|never[^.]*rolls?[- ]?back/i,
+    );
+  });
+});
+
+// PR 9 — Slice 5: decision matrix. Three orthogonal axes — --push, --afk,
+// --ticket — produce six meaningful cells. Default prompt is [y/N] (default
+// No, never surprise-write). Two interactive prompts in non-afk flow is
+// intentional (Step 4 confirms approval, Step 4c confirms push).
+describe('approve-plan Step 4c decision matrix (PR 9 Slice 5)', () => {
+  const content = readFileSync(
+    new URL('approve-plan.md', import.meta.url),
+    'utf8',
+  );
+  const fourCStart = content.indexOf('## Step 4c — Optional board push');
+  const fourCEnd = content.indexOf('## Step 5 — Update ticket description');
+  const fourCBody = content.slice(fourCStart, fourCEnd);
+
+  it('Step 4c declares the new --push and --ticket flags', () => {
+    expect(fourCBody).toContain('`--push`');
+    expect(fourCBody).toContain('`--ticket');
+  });
+
+  it('Step 4c interactive prompt defaults to [y/N] (default No)', () => {
+    expect(fourCBody).toContain('[y/N]');
+    expect(fourCBody).toMatch(/default[^.]*No|never surprise[- ]write/i);
+  });
+
+  it('Step 4c interactive prompt text names the resolved KEY', () => {
+    // The prompt must show which ticket the push will hit.
+    expect(fourCBody).toMatch(
+      /Push approved plan to[^.]*\{KEY\}[^.]*comment\?[^.]*\[y\/N\]/,
+    );
+  });
+
+  it('Step 4c covers interactive without --push (prompt the user)', () => {
+    expect(fourCBody).toMatch(
+      /interactive[^.]*no `--push`|no `--push`[^.]*interactive/i,
+    );
+    // Interactive cell explicitly prompts.
+    expect(fourCBody).toMatch(/prompt[\s\S]{0,300}\[y\/N\]/);
+  });
+
+  it('Step 4c covers interactive + --push (skip prompt and push)', () => {
+    expect(fourCBody).toMatch(
+      /interactive[^.]*`--push`[^.]*skip[^.]*prompt|`--push`[^.]*skip[^.]*prompt[^.]*push/i,
+    );
+  });
+
+  it('Step 4c covers --afk without --push (LOCAL_ONLY skip)', () => {
+    expect(fourCBody).toContain('LOCAL_ONLY');
+    expect(fourCBody).toMatch(
+      /--afk[^.]*without[^.]*--push|--afk[^.]*no[^.]*--push/i,
+    );
+  });
+
+  it('Step 4c LOCAL_ONLY token logs to .clancy/progress.txt with stem', () => {
+    // {stem} | TOKEN | {detail} convention:
+    //   {stem} | LOCAL_ONLY | afk-without-push
+    expect(fourCBody).toMatch(
+      /\{stem\}\s*\\?\|\s*LOCAL_ONLY\s*\\?\|\s*afk-without-push/,
+    );
+  });
+
+  it('Step 4c covers --afk --push (push without prompting)', () => {
+    expect(fourCBody).toMatch(
+      /--afk\s*--push|--afk[^.]*--push[^.]*without[^.]*prompt/i,
+    );
+  });
+
+  it('Step 4c covers --ticket KEY override (auto-detect bypassed)', () => {
+    expect(fourCBody).toMatch(/--ticket[^.]*override|override[^.]*--ticket/i);
+    // --ticket wins over Source auto-detect.
+    expect(fourCBody).toMatch(
+      /wins over[^.]*auto[- ]detect|override[^.]*auto[- ]detect/i,
+    );
+  });
+
+  it('Step 4c documents --ticket is ignored under --afk-without-push', () => {
+    // The LOCAL_ONLY skip cell ignores --ticket entirely (no push happens).
+    const localOnlyRegion = fourCBody.slice(fourCBody.indexOf('LOCAL_ONLY'));
+    expect(localOnlyRegion.slice(0, 800)).toMatch(
+      /--ticket[^.]*ignored|ignored[^.]*--ticket/i,
+    );
+  });
+
+  it('Step 4c calls out the two-prompt flow as intentional', () => {
+    // Step 4 confirms approval, Step 4c confirms push — semantically distinct.
+    expect(fourCBody).toMatch(/two[- ]prompt|two prompts|second prompt/i);
+    expect(fourCBody).toMatch(/intentional|distinct|semantically/i);
+  });
+});
+
+// PR 9 — Slice 7: failure semantics for actual push failures (HTTP non-2xx,
+// network/timeout/dns/auth). Marker stays, BOARD_PUSH_FAILED logged, exact
+// retry command printed. No rollback.
+describe('approve-plan Step 4c push failure semantics (PR 9 Slice 7)', () => {
+  const content = readFileSync(
+    new URL('approve-plan.md', import.meta.url),
+    'utf8',
+  );
+  const fourCStart = content.indexOf('## Step 4c — Optional board push');
+  const fourCEnd = content.indexOf('## Step 5 — Update ticket description');
+  const fourCBody = content.slice(fourCStart, fourCEnd);
+
+  it('Step 4c handles push failure as best-effort (marker preserved)', () => {
+    // Distinct from the slice 4 key-mismatch path — this is the
+    // post-validation, post-curl HTTP failure path.
+    expect(fourCBody).toMatch(/push fail/i);
+    expect(fourCBody).toMatch(
+      /marker[^.]*(stays|preserved|kept|authoritative)/i,
+    );
+  });
+
+  it('Step 4c logs BOARD_PUSH_FAILED with stem and status class', () => {
+    // {stem} | TOKEN | {detail} convention:
+    //   {stem} | BOARD_PUSH_FAILED | {http_status_or_error_class}
+    expect(fourCBody).toContain('BOARD_PUSH_FAILED');
+    expect(fourCBody).toMatch(
+      /\{stem\}\s*\\?\|\s*BOARD_PUSH_FAILED\s*\\?\|\s*\{http_status_or_error_class\}/,
+    );
+  });
+
+  it('Step 4c defines the error-class vocabulary', () => {
+    // Locked spec: HTTP status code on non-2xx, OR lowercase error class
+    // on transport failure: network, timeout, dns, auth.
+    expect(fourCBody).toMatch(/network/);
+    expect(fourCBody).toMatch(/timeout/);
+    expect(fourCBody).toMatch(/dns/);
+    expect(fourCBody).toMatch(/auth/);
+    // HTTP status path also documented.
+    expect(fourCBody).toMatch(/HTTP[^.]*status|status code|non-2xx/i);
+  });
+
+  it('Step 4c prints the exact retry command on push failure', () => {
+    // Exact command pattern: /clancy:approve-plan {stem} --push --ticket {KEY}
+    expect(fourCBody).toMatch(
+      /\/clancy:approve-plan\s+\{stem\}\s+--push\s+--ticket\s+\{KEY\}/,
+    );
+  });
+
+  it('Step 4c push-failure path continues to Step 7 (does not exit non-zero)', () => {
+    // Push failure is best-effort — workflow still continues to render the
+    // local-mode success block in Step 7.
+    const failRegion = fourCBody.slice(fourCBody.search(/push fail/i));
+    expect(failRegion).toMatch(/Step 7|continue|proceed/i);
+  });
+
+  it('Step 4c push-failure NEVER rolls back the marker', () => {
+    expect(fourCBody).toMatch(
+      /never[^.]*rolls?[- ]?back|do(?:es)? not rolls?[- ]?back/i,
+    );
+  });
+
+  it('Step 4c logs LOCAL_APPROVE_PLAN_PUSH success row with stem and KEY', () => {
+    // DA review H1: the success path needs a second progress.txt row
+    // distinct from LOCAL_APPROVE_PLAN. Two-row audit is unambiguous.
+    expect(fourCBody).toContain('LOCAL_APPROVE_PLAN_PUSH');
+    expect(fourCBody).toMatch(
+      /\{stem\}\s*\\?\|\s*LOCAL_APPROVE_PLAN_PUSH\s*\\?\|\s*\{KEY\}/,
+    );
+  });
+
+  it('Step 4c documents the BOARD_PUSH_FAILED reason-field disambiguation', () => {
+    // DA review L1: HTTP status, error-class, and key-mismatch:{KEY} share
+    // the token. The contract that disambiguates them must be explicit.
+    expect(fourCBody).toMatch(
+      /key-mismatch:[^.]*reserved|reserved[^.]*key-mismatch/i,
+    );
+  });
+});
+
+// PR 9 — Slice 8: retry path. EEXIST + --push falls through to Step 4c
+// instead of stopping. Without --push, EEXIST stops as today (PR 7b).
+// This is the only mechanism to re-attempt a failed push — no new flag,
+// no marker deletion.
+describe('approve-plan Step 4a EEXIST retry path (PR 9 Slice 8)', () => {
+  const content = readFileSync(
+    new URL('approve-plan.md', import.meta.url),
+    'utf8',
+  );
+
+  // Step 4a's EEXIST handling section is the load-bearing region for slice 8.
+  const eexistStart = content.indexOf('### Handle EEXIST');
+  const eexistEnd = content.indexOf('### Marker is the gate');
+  const eexistBody = content.slice(eexistStart, eexistEnd);
+
+  it('Step 4a EEXIST handling references the --push retry path', () => {
+    expect(eexistBody).toContain('--push');
+  });
+
+  it('EEXIST + --push falls through to Step 4c (does not stop)', () => {
+    expect(eexistBody).toMatch(
+      /EEXIST[\s\S]*--push[\s\S]*(falls?[- ]through|continue)[\s\S]*Step 4c/i,
+    );
+  });
+
+  it('EEXIST without --push still stops with the PR 7b message', () => {
+    // PR 7b's existing behaviour preserved — bare EEXIST without --push
+    // still hits the "Plan already approved" stop branch.
+    expect(eexistBody).toMatch(
+      /without[^.]*--push|no `--push`|`--push`\s+is\s+NOT\s+set|NOT\s+set/i,
+    );
+    expect(eexistBody).toContain('Plan already approved');
+  });
+
+  it('EEXIST + --push does NOT re-write the marker', () => {
+    // The marker is preserved as-is. The retry only re-runs Step 4c.
+    expect(eexistBody).toMatch(
+      /(?:does not|never|do not|is not|not) re[- ]?written|marker[^a-z]*(stays|preserved|unchanged)/i,
+    );
+  });
+
+  it('EEXIST + --push retry skips Step 4b (brief marker already updated)', () => {
+    // Step 4b ran on the original approval; the brief marker is already
+    // updated. The retry path goes EEXIST → Step 4c directly, not via 4b.
+    expect(eexistBody).toMatch(/skip[^.]*Step 4b|Step 4b[^.]*skip/i);
+  });
+
+  it('Step 4c documents the retry entry path from EEXIST', () => {
+    // Symmetry test: Step 4c should mention the retry entry path from
+    // 4a's EEXIST branch so a reader of 4c knows where re-runs come from.
+    const fourCStart = content.indexOf('## Step 4c — Optional board push');
+    const fourCEnd = content.indexOf('## Step 5 — Update ticket description');
+    const fourCBody = content.slice(fourCStart, fourCEnd);
+    expect(fourCBody).toMatch(
+      /EEXIST[^.]*--push|--push[^.]*EEXIST|retry[^.]*Step 4a/i,
+    );
+  });
+});
+
+// PR 9 — Slice 9: Notion flat-text note + commands/approve-plan.md flag docs.
+// Notion comments render as flat text — surface in the local-mode success
+// block so Notion users aren't surprised. Command file gets the new flag
+// surface (--push, --ticket).
+describe('approve-plan Step 7 Notion flat-text note (PR 9 Slice 9)', () => {
+  const content = readFileSync(
+    new URL('approve-plan.md', import.meta.url),
+    'utf8',
+  );
+  const stepSevenStart = content.indexOf('## Step 7');
+  const stepSevenBody = content.slice(stepSevenStart);
+
+  it('Step 7 local-mode block surfaces a Notion flat-text note', () => {
+    expect(stepSevenBody).toMatch(
+      /Notion[^.]*flat[- ]text|flat[- ]text[^.]*Notion/i,
+    );
+  });
+
+  it('Notion note is conditional on the push target (only when Notion)', () => {
+    expect(stepSevenBody).toMatch(
+      /only[^.]*Notion|when[^.]*Notion|Notion[^.]*only/i,
+    );
+  });
+
+  it('Notion note explicitly says structure will not be styled', () => {
+    expect(stepSevenBody).toMatch(
+      /won.?t be styled|no[^.]*styling|plain text/i,
+    );
+  });
+});
+
+describe('approve-plan command file flag surface (PR 9 Slice 9)', () => {
+  const content = readFileSync(
+    new URL('../commands/approve-plan.md', import.meta.url),
+    'utf8',
+  );
+
+  it('command file documents --push flag', () => {
+    expect(content).toContain('`--push`');
+  });
+
+  it('command file documents --ticket flag', () => {
+    expect(content).toContain('`--ticket');
+  });
+
+  it('command file --push doc references board push target', () => {
+    const pushIdx = content.indexOf('`--push`');
+    expect(pushIdx).toBeGreaterThan(-1);
+    const pushParagraph = content.slice(pushIdx, pushIdx + 400);
+    expect(pushParagraph).toMatch(/push|board/i);
+  });
+
+  it('command file --ticket doc references KEY override of Source', () => {
+    const ticketIdx = content.indexOf('`--ticket');
+    expect(ticketIdx).toBeGreaterThan(-1);
+    const ticketParagraph = content.slice(ticketIdx, ticketIdx + 400);
+    expect(ticketParagraph).toMatch(/override|Source|KEY/i);
+  });
+
+  it('command file preserves --afk from PR 7b', () => {
+    expect(content).toContain('`--afk`');
+  });
+});