@chief-clancy/plan 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chief-clancy/plan",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "private": false,
   "description": "Implementation planner for Claude Code — decompose briefs into actionable plans",
   "author": "Alex Clapperton",

package/src/workflows/plan.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Fetch backlog tickets from the board, explore the codebase, and generate structured implementation plans. In board mode, plans are posted as comments on the ticket for human review. With `--from`, plans from local brief files are saved to `.clancy/plans/`, with an optional board comment when credentials are available. Does not implement anything — planning only. In **terminal mode**, use `/clancy:approve-plan` to promote plans. In **standalone mode** or **standalone+board mode**, install the full pipeline (`npx chief-clancy`) to promote plans.
+Fetch backlog tickets from the board, explore the codebase, and generate structured implementation plans. In board mode, plans are posted as comments on the ticket for human review. With `--from`, plans from local brief files are saved to `.clancy/plans/`, with an optional board comment when credentials are available. Does not implement anything — planning only. Use `/clancy:approve-plan` to approve plans in any install mode — it ships with this package, writes a local `.approved` marker for plan-file stems, and runs the board transport flow for ticket keys only when board credentials are available.
 
 ---
 
@@ -24,7 +24,7 @@ Check for `.clancy/.env`:
 If `.clancy/.env` is present, check for `.clancy/clancy-implement.js`:
 
 - **Present** → **terminal mode**. Full Clancy pipeline installed.
-- **Absent** → **standalone+board mode**. Board credentials available via `/clancy:board-setup`. Board ticket mode works. Step 5 works. But `/clancy:approve-plan` is not available (requires full pipeline).
+- **Absent** → **standalone+board mode**. Board credentials available via `/clancy:board-setup`. Board ticket mode works. Step 5 works. `/clancy:approve-plan` also works in this mode — it ships with the plan package and runs the board transport flow for ticket keys or writes a local `.approved` marker for plan-file stems.
 
 ### 2. Terminal-mode preflight (skip in standalone mode and standalone+board mode)
 
@@ -822,7 +822,7 @@ Write the plan in this exact template:
 
 ---
 
-_Generated by [Clancy](https://github.com/Pushedskydiver/chief-clancy). To request changes: comment on this ticket, then re-run `/clancy:plan` to revise. To start over: `/clancy:plan --fresh`. To approve: `/clancy:approve-plan {KEY}` (requires full pipeline — `npx chief-clancy`)._
+_Generated by [Clancy](https://github.com/Pushedskydiver/chief-clancy). To request changes: comment on this ticket, then re-run `/clancy:plan` to revise. To start over: `/clancy:plan --fresh`. To approve: `/clancy:approve-plan {KEY}`._
 ```
 
 **If re-planning with feedback**, prepend a section before Summary:
@@ -885,7 +885,7 @@ Replace the `**Ticket:** [{KEY}] {Title}` line from the board template with `**S
 **Local plan footer:** Replace the board-specific footer with:
 
 ```
-_Generated by [Clancy](https://github.com/Pushedskydiver/chief-clancy). To request changes: add a ## Feedback section to this file, then re-run `/clancy:plan --from {path}` to revise. To start over: `/clancy:plan --fresh --from {path}`. To approve: install the full pipeline — npx chief-clancy._
+_Generated by [Clancy](https://github.com/Pushedskydiver/chief-clancy). To request changes: add a ## Feedback section to this file, then re-run `/clancy:plan --from {path}` to revise. To start over: `/clancy:plan --fresh --from {path}`. To approve: `/clancy:approve-plan {plan-id}`._
 ```
 
 **Re-planning:** If `--fresh` was used, the existing plan file is overwritten (same slug + row number = same filename).
@@ -1052,8 +1052,7 @@ Planned {N} ticket(s):
   ⏭️  [{KEY4}] {Title} — not a codebase change
 
 Plans written to your board. After review:
-  Terminal mode: /clancy:approve-plan {KEY}
-  Standalone: install the full pipeline — npx chief-clancy
+  /clancy:approve-plan {KEY}
 
 "Let me dust this for prints..."
 ```
@@ -1068,7 +1067,7 @@ Single row:
 
   ✅ Saved to .clancy/plans/{slug}-{row-number}.md
 
-  To approve: install the full pipeline — npx chief-clancy
+  To approve: /clancy:approve-plan {slug}-{row-number}
 
 "Let me dust this for prints..."
 ```
@@ -1083,7 +1082,7 @@ Multi-row (`--afk`):
   ✅ Row 2: {title} — Saved to .clancy/plans/{slug}-2.md
   ⏭️  Row 3: {title} — already planned
 
-  To approve: install the full pipeline — npx chief-clancy
+  To approve: /clancy:approve-plan {slug}-{row-number} (or use /clancy:plan --list to see all plans)
 
 "Let me dust this for prints..."
 ```
@@ -1101,35 +1100,47 @@ Scan `.clancy/plans/` for all `.md` files. For each file, parse the local plan h
 - **Row** — value of the `**Row:**` line (e.g. `#2 — Add toggle component`). Display `?` if absent or empty.
 - **Source** — value of the `**Source:**` line (the brief's Source field). Display `?` if absent or empty.
 - **Planned** — value of the `**Planned:**` line (the YYYY-MM-DD planned date). Display `?` if absent or unparseable as a date.
-- **Status** — for now this is always `Planned`. Reserved for `/clancy:approve-plan` (a future PR) which will write a sibling `.approved` marker file (e.g. `.clancy/plans/add-dark-mode-2.approved`). When that marker exists for a given plan, Status becomes `Approved`. The column is included in the listing today so the format will not change when approval markers ship.
+- **Status** — derived live from the sibling `.approved` marker written by `/clancy:approve-plan` (PR 7b). The reader is filesystem-only — no `.clancy/.env` or board access required. For each plan file, follow this procedure (every numbered step either branches to a verdict or feeds the next step):
+  1. Check whether `.clancy/plans/{plan-id}.approved` exists. If marker absent → `Planned` (verdict)
+  2. Marker exists. Read and validate its `sha256=` line (the marker body is two `key=value` lines: `sha256={hex}` and `approved_at={ISO 8601}`) AND hash the current plan file's bytes the same way `/clancy:approve-plan` Step 4a does (lowercase hex SHA-256, no normalisation, no line-ending fix)
+  3. If the marker exists but is malformed, missing its `sha256=` line, has a non-hex or wrong-length `sha256` value, or otherwise cannot be parsed deterministically → `Stale (re-approve)` (verdict). Print a hint after the table: `Marker .clancy/plans/{plan-id}.approved is malformed. Delete it and re-run /clancy:approve-plan {plan-id} to recreate.` Folding this into `Stale` (rather than inventing a new state) keeps the inventory deterministic — the user's remediation is the same as for a hash drift: delete the marker and re-approve
+  4. If the marker's valid `sha256` matches the current plan file's hash → `Approved` (verdict)
+  5. If the marker exists and its valid `sha256` differs from the current hash → `Stale (re-approve)` (verdict) — the plan file was edited after approval. `/clancy:implement-from` (PR 8) will refuse to run against a stale plan until it is re-approved
+
+  A future `Implemented` state — derived from `LOCAL_IMPLEMENT` entries in `.clancy/progress.txt` — will be added by PR 8. Today the inventory shows three states (`Planned`, `Approved`, `Stale (re-approve)`), with malformed `.approved` markers folded into `Stale (re-approve)`; the table format is stable so PR 8's addition will be a one-line extension.
 
 A field is considered missing if the line is absent or its value is empty after the colon. Plans missing all expected fields are still listed (with `?` placeholders) so the user can find and clean them up.
 
 **Sort:** by `**Planned**` date, newest first. Tie-break on same date by Plan ID, alphabetical ascending. Files with a missing or unparseable date sort last (after all dated plans), and tie-break among themselves by Plan ID alphabetical ascending. The sort must be deterministic across runs.
 
-Display:
+**Summary line:** after the table, print one line in the format `{N} local plan(s). {A} approved, {S} stale, {P} planned.` where the counts match the rows above. Omit zero-count states for brevity (e.g. `3 local plan(s). 2 approved, 1 planned.` if no plans are stale). A `Stale (re-approve)` row means the plan file was edited after approval — re-running `/clancy:approve-plan {plan-id}` (after deleting the existing marker) will refresh the SHA.
+
+Display the inventory as a pipe-delimited table so each Status value is unambiguous to scan and parse:
 
 ```
 Clancy — Plans
 ================================================================
 
-  [1] add-dark-mode-2          2026-04-08  Planned  Row #2 — Add toggle component  Brief: 2026-04-01-add-dark-mode.md  Source: #50
-  [2] add-dark-mode-1          2026-04-07  Planned  Row #1 — Wire theme context    Brief: 2026-04-01-add-dark-mode.md  Source: #50
-  [3] customer-portal-3        2026-04-05  Planned  Row #3 — Billing page          Brief: 2026-03-28-customer-portal.md  Source: PROJ-200
+  | # | Plan ID            | Planned    | Status              | Row                              | Brief                              | Source    |
+  |---|--------------------|------------|---------------------|----------------------------------|------------------------------------|-----------|
+  | 1 | add-dark-mode-2    | 2026-04-08 | Approved            | #2 — Add toggle component        | 2026-04-01-add-dark-mode.md        | #50       |
+  | 2 | add-dark-mode-1    | 2026-04-07 | Stale (re-approve)  | #1 — Wire theme context          | 2026-04-01-add-dark-mode.md        | #50       |
+  | 3 | customer-portal-3  | 2026-04-05 | Planned             | #3 — Billing page                | 2026-03-28-customer-portal.md      | PROJ-200  |
 
-3 local plan(s).
+3 local plan(s). 1 approved, 1 stale, 1 planned.
 
-To revise: add a `## Feedback` section to the plan file, then re-run /clancy:plan --from <brief>.
-To start over: /clancy:plan --fresh --from <brief>.
-To approve: install the full pipeline — npx chief-clancy.
+To approve a plan:           /clancy:approve-plan {plan-id}
+To re-approve a stale plan:  delete .clancy/plans/{plan-id}.approved, then /clancy:approve-plan {plan-id}
+To revise:                   add a `## Feedback` section to the plan file, then re-run /clancy:plan --from {brief}
+To start over:               /clancy:plan --fresh --from {brief}
 ```
 
-The first column in the listing is the Plan ID (filename without `.md`), not the brief slug.
+The first column (after `#`) is the Plan ID (filename without `.md`), not the brief slug. Pipe-table format is intentional — Status values like `Stale (re-approve)` contain spaces, and a column-aligned space-delimited layout would make them ambiguous to read.
 
 If `.clancy/plans/` does not exist or contains no `.md` files:
 
 ```
-No plans found. Run /clancy:plan --from .clancy/briefs/<brief>.md to create one.
+No plans found. Run /clancy:plan --from .clancy/briefs/{brief}.md to create one.
 ```
 
 Stop after display. The `--list` step never logs to `.clancy/progress.txt` and never modifies any file — it is purely a read-only inventory view of the local plans directory.

package/src/workflows/workflows.test.ts

@@ -595,13 +595,75 @@ describe('plan inventory step', () => {
     expect(content).toContain(
       '**Plan ID** — the plan filename minus the `.md` extension',
     );
-    expect(content).toContain('first column in the listing is the Plan ID');
+    expect(content).toContain('first column (after `#`) is the Plan ID');
   });
 
-  it('reserves a Status column for the future approve-plan PR', () => {
+  it('Status column reads sibling .approved marker for live state', () => {
     expect(content).toContain('**Status**');
-    expect(content).toContain('always `Planned`');
-    expect(content).toContain('`.approved` marker');
+    expect(content).toContain('sibling `.approved` marker');
+  });
+
+  it('Status is Planned when no marker exists', () => {
+    expect(content).toContain('marker absent → `Planned`');
+  });
+
+  it('Status is Approved when marker sha256 matches the current plan file', () => {
+    expect(content).toContain('sha256` matches the current plan file');
+    expect(content).toContain('→ `Approved`');
+  });
+
+  it('Status is Stale (re-approve) when marker sha256 drifts from the plan file', () => {
+    expect(content).toContain('Stale (re-approve)');
+    expect(content).toContain('sha256` differs');
+  });
+
+  it('inventory example shows at least one Approved row', () => {
+    // Match a pipe-delimited table cell on both sides (literal `|`s with
+    // tolerant whitespace) so the test proves the example output is in the
+    // pipe-delimited table format, not just that the word `Approved` happens
+    // to appear in nearby prose.
+    expect(content).toMatch(/\|\s*Approved\s*\|/);
+  });
+
+  it('inventory example shows at least one Stale row', () => {
+    expect(content).toMatch(/\|\s*Stale \(re-approve\)\s*\|/);
+  });
+
+  it('inventory example still shows at least one Planned row', () => {
+    expect(content).toMatch(/\|\s*Planned\s*\|/);
+  });
+
+  it('inventory documents the summary line format and zero-count omission', () => {
+    expect(content).toContain('Summary line');
+    expect(content).toContain(
+      '{N} local plan(s). {A} approved, {S} stale, {P} planned.',
+    );
+    expect(content).toContain('Omit zero-count states');
+  });
+
+  it('explains that Stale means the plan was edited after approval', () => {
+    expect(content).toContain('plan file was edited after approval');
+  });
+
+  it('reserves an Implemented state for PR 8 without claiming it exists today', () => {
+    expect(content).toContain('Implemented');
+    expect(content).toContain('PR 8');
+    expect(content).toContain('shows three states');
+  });
+
+  it('folds malformed .approved markers into Stale (re-approve)', () => {
+    expect(content).toContain('marker exists but is malformed');
+    expect(content).toContain('non-hex or wrong-length');
+    expect(content).toContain('cannot be parsed deterministically');
+  });
+
+  it('uses {plan-id} placeholder consistently in the footer (no <plan-id>)', () => {
+    expect(content).not.toContain('<plan-id>');
+    expect(content).toContain('/clancy:approve-plan {plan-id}');
+  });
+
+  it('inventory footer hint points at /clancy:approve-plan', () => {
+    expect(content).toContain('/clancy:approve-plan');
   });
 
   it('sort is deterministic with explicit tie-breakers', () => {