cclaw-cli 7.7.1 → 8.1.0

package/README.md

@@ -1,197 +1,273 @@
 # cclaw
 
-**cclaw is a file-backed flow runtime for coding agents.** It turns Claude Code, Cursor, OpenCode, and Codex into one repeatable path from idea to shipped change: visible stages, hard gates, real subagent evidence, and resumable closeout in your repo.
+**cclaw is a lightweight harness-first flow toolkit for coding agents.** It installs three slash commands, six on-demand specialists, twelve auto-trigger skills (including TDD cycle and conversation-language), ten artifact templates, four stage runbooks, eight reference patterns, five research playbooks, five recovery playbooks, thirteen worked examples, an antipatterns library, a decision protocol, a meta-skill, and a tiny runtime — together a deep content layer wrapped around a runtime under 1 KLOC — so Claude Code, Cursor, OpenCode, or Codex can move from idea to shipped change with a clear plan, AC traceability, TDD per AC, and almost no ceremony.
 
 ```text
         idea
-         |
-         v
-   +-------------+      +--------+      +--------+      +------+      +------+      +-----+
-   | brainstorm  | ---> | scope  | ---> | design | ---> | spec | ---> | plan | ---> | tdd |
-   +-------------+      +--------+      +--------+      +------+      +------+      +-----+
-                                                                                       |
-                                                                                       v
-                                                                                  +--------+      +------+
-                                                                                  | review | ---> | ship |
-                                                                                  +--------+      +------+
-                                                                                                      |
-                                                                                                      v
-                                                                                         post_ship_review -> archive
+         │
+         ▼
+     /cc <task>
+         │
+   ┌─────┴─────────────────────────────────────┐
+   │ Phase 0 calibration:                      │
+   │ targeted change or multi-component?       │
+   └─────┬─────────────────┬───────────────────┘
+         │trivial          │small/medium       │large/risky
+         ▼                 ▼                   ▼
+    edit + commit     plan → build       brainstormer →
+    per AC            → review → ship    architect → planner
+                                         (each is optional)
+                              │
+                              ▼
+                     compound (auto, gated)
+                              │
+                              ▼
+                  active artifacts → shipped/<slug>/
 ```
 
-The promise is simple: at any point you can ask **where are we, what is blocked, what evidence exists, and what should run next?**
+Three slash commands. Four stages (`plan → build → review → ship`, where **build IS a TDD cycle**: RED → GREEN → REFACTOR per AC). Six specialists. Eleven skills (including a TDD-cycle skill that's always-on while building). Ten templates. Four runbooks. Eight reference patterns. Five research playbooks. Five recovery playbooks. Thirteen worked examples. Two mandatory gates (AC traceability + TDD phase chain).
 
-## First 5 Minutes
+## What changed in v8
 
-Requirements: Node.js 20+ and a git project root.
+cclaw v8.0 is a breaking redesign. We dropped the 7.x stage machine: no more `brainstorm` / `scope` / `design` / `spec` / `tdd` mandatory stages, no more 18 specialists, no more 9 state files, no more 30 stage gates. v7.x runs are not migrated; see [docs/migration-v7-to-v8.md](docs/migration-v7-to-v8.md).
+
+What we kept and made deeper:
+
+- plans with **acceptance criteria + YAML frontmatter** (`slug`, `stage`, `status`, `ac[]`, `last_specialist`, `refines`, `shipped_at`, `ship_commit`, `review_iterations`, `security_flag`);
+- **build is a TDD stage** — every AC goes through RED → GREEN → REFACTOR; `commit-helper.mjs --phase=red|green|refactor` enforces the cycle (production files in RED are rejected, GREEN without prior RED is rejected, REFACTOR is mandatory);
+- **AC ↔ commit traceability** enforced by `commit-helper.mjs`;
+- **artifact templates** for every stage (`plan`, `build`, `review`, `ship`, `decisions`, `learnings`, `manifest`, `ideas`, `iron-laws`);
+- **twelve auto-trigger skills** — plan-authoring, AC traceability, refinement, parallel-build, security-review, review-loop, commit-message-quality, AC-quality, refactor-safety, breaking-changes, conversation-language (always-on), anti-slop (always-on), plus a meta-skill that ties them together;
+- **stage runbooks** (`.cclaw/lib/runbooks/{plan,build,review,ship}.md`) — strict checklists per stage with common pitfalls;
+- **reference patterns** (`.cclaw/lib/patterns/`) — eight task-type playbooks (api-endpoint, auth-flow, schema-migration, ui-component, perf-fix, refactor, security-hardening, doc-rewrite) the orchestrator opens before authoring AC;
+- **research playbooks** (`.cclaw/lib/research/`) — reading the codebase (files + tests + integration boundaries), time-boxing, using prior shipped slugs;
+- **recovery playbooks** (`.cclaw/lib/recovery/`) — AC traceability break, review hard cap reached, parallel-build slice conflict, frontmatter corruption, schemaVersion mismatch;
+- **examples library** (`.cclaw/lib/examples/`) — eight real-looking plan / build / review / ship / decision / learning / commit-helper artifacts;
+- **antipatterns** (`.cclaw/lib/antipatterns.md`) — twelve known failure modes the reviewer cites as findings;
+- **decision protocol** (`.cclaw/lib/decision-protocol.md`) — short-form digest of "is this even a decision?"; full D-N schema lives in `lib/agents/architect.md`, worked decisions in `lib/examples/`;
+- **resumable refinement** via frontmatter on shipped slugs (`refines: <old-slug>`);
+- durable artifacts your team and graph tools (Graphify, GitNexus, etc.) can index.
+
+## First 5 minutes
+
+Requirements: Node.js 20+ and a git project.
 
 ```bash
 cd /path/to/your/repo
-npx cclaw-cli
+npx cclaw-cli init                            # auto-detect harness from project root
+npx cclaw-cli init --harness=claude,cursor,opencode,codex   # explicit selection
 ```
 
-Then work from your coding harness:
-
-```text
-/cc <idea>          start, resume, or continue a tracked flow
-/cc-idea          generate or refresh an idea backlog
-/cc-cancel          end the current run cleanly with a reason
-```
+`init` resolves harnesses in this order:
 
-`/cc-idea` is a utility command for backlog discovery. It is distinct from
-`.cclaw/artifacts/00-idea.md`, which is the stage artifact created by
-`/cc <idea>`.
+1. `--harness=<id>[,<id>]` flag if passed.
+2. Existing `.cclaw/config.yaml` (so subsequent `init` / `sync` / `upgrade` are deterministic).
+3. Auto-detect from project root markers: `.claude/`, `.cursor/`, `.opencode/`, `.codex/`, `.agents/skills/`, `CLAUDE.md`, `opencode.json`, `opencode.jsonc`.
+4. If nothing detected and no flag passed → exit with an actionable error. cclaw never silently picks a harness for you.
 
-For scripted setup:
+Then work entirely inside your harness:
 
-```bash
-npx cclaw-cli init --harnesses=claude,cursor --no-interactive
+```text
+/cc <task>          plan / build / review / ship — orchestrator routes everything
+/cc-cancel          stop the active run cleanly (artifacts move to .cclaw/flows/cancelled/<slug>/)
+/cc-idea            drop a half-formed idea into .cclaw/ideas.md (no flow started)
 ```
 
-If generated files or hooks look stale, run `npx cclaw-cli sync`.
+There is no `cclaw plan`, `cclaw status`, `cclaw ship`, or `cclaw migrate` CLI command. Flow control lives in `/cc` inside the harness.
+
+## Six specialists, all on demand
+
+| id | modes | when |
+| --- | --- | --- |
+| `brainstormer` | frame / scope / alternatives | ambiguous request, need a frame and scope |
+| `architect` | architecture / feasibility | structural decisions or feasibility check |
+| `planner` | research / work-breakdown / topology | breaking work into AC and choosing topology |
+| `reviewer` | code / text-review / integration / release / adversarial | reviews of any kind |
+| `security-reviewer` | threat-model / sensitive-change | auth / secrets / supply chain / data exposure |
+| `slice-builder` | build / fix-only | implementing AC and applying scoped fixes |
+
+Specialists are proposed only when the task is large, abstract, risky, security-sensitive, or spans multiple components. Trivial and small/medium tasks run inline. Each prompt is 150-280 lines and includes an explicit output schema, two or more worked examples, edge cases, common pitfalls, and hard rules (see `.cclaw/lib/agents/*.md` after install). The orchestrator pulls additional context from runbooks, patterns, examples, and recovery playbooks as needed; see [docs/skills.md](docs/skills.md) for the auto-trigger layer that wraps every invocation.
+
+## Plan artifact, by example
+
+```yaml
+---
+slug: approval-page
+stage: plan
+status: active
+ac:
+  - id: AC-1
+    text: "User sees an approval status pill on the dashboard."
+    status: pending
+  - id: AC-2
+    text: "Pending approvals show a tooltip with the approver's name."
+    status: pending
+last_specialist: null
+refines: null
+shipped_at: null
+ship_commit: null
+review_iterations: 0
+security_flag: false
+---
+
+# approval-page
+
+> One paragraph: what we are doing and why.
+
+## Acceptance Criteria
+
+| id | text | status | commit |
+| --- | --- | --- | --- |
+| AC-1 | User sees an approval status pill on the dashboard. | pending | — |
+| AC-2 | Pending approvals show a tooltip with the approver's name. | pending | — |
+```
 
-## Why cclaw
+The same shape applies to `build.md` (commit log), `review.md` (findings + Five Failure Modes pass), `ship.md` (release notes + push/PR refs), `decisions.md` (architect output), `learnings.md` (compound output). Templates live in `.cclaw/lib/templates/`.
 
-AI coding sessions fail when decisions live only in chat. cclaw puts the operating truth in files:
+## Artifact tree
 
-```text
+```
 .cclaw/
-  artifacts/              active stage docs: 00-idea.md through 09-retro.md
-  state/flow-state.json   current stage, gates, stale markers, closeout.shipSubstate
-  state/delegation-log.json
-                           subagent dispatches, waivers, evidence refs
-  knowledge.jsonl         reusable lessons harvested from stage artifacts
-  archive/                archived run snapshots (durable closeout proof)
+  config.yaml               cclaw config (harness, flow defaults)
+  ideas.md                  append-only idea backlog (/cc-idea)
+  knowledge.jsonl           cross-feature learnings index, append-only
+  state/
+    flow-state.json         ~500 bytes, schemaVersion: 2
+  hooks/
+    session-start.mjs       rehydrates flow state on harness boot
+    stop-handoff.mjs        short reminder when stopping mid-flow
+    commit-helper.mjs       atomic commit per AC + traceability + TDD phase gate
+  flows/                    everything that comes out of a /cc run
+    <slug>/                 one folder per active flow
+      plan.md               current work + AC
+      build.md              implementation log + TDD evidence
+      review.md             Concern Ledger + iteration logs
+      ship.md               preflight + AC↔commit map + rollback + finalization
+      decisions.md          architect output (optional; only when architect ran)
+      learnings.md          compound output (optional; only when gated)
+    shipped/<slug>/         plan.md, build.md, review.md, ship.md,
+                            decisions.md, learnings.md, manifest.md
+    cancelled/<slug>/       when /cc-cancel is invoked
+  lib/                      reference content shipped by the installer
+    agents/                 6 specialist prompts (each ends with a Composition footer
+                            locking it to its lane — no nested orchestration)
+    skills/                 12 auto-trigger skills (2 always-on: conversation-language,
+                            anti-slop; 10 stage- or event-gated)
+    templates/              9 templates (plan, build, review, ship, decisions,
+                            learnings, manifest, ideas, iron-laws)
+    runbooks/               4 stage runbooks (plan, build, review, ship)
+    patterns/               8 task-type playbooks
+    research/               3 research playbooks
+    recovery/               5 recovery playbooks
+    examples/               8 worked examples
+    antipatterns.md         12 named failure modes
+    decision-protocol.md    short-form digest; full schema in lib/agents/architect.md
 ```
 
-That gives you:
+`.cclaw/state/` and `.cclaw/worktrees/` are appended to `.gitignore` on init (transient per-session data). The rest of `.cclaw/` is committable; graphify, team review, and the next agent all need it.
 
-- **One path** from idea to ship, with one user-chosen discovery mode (`lean`, `guided`, `deep`) and internal `quick` / `medium` / `standard` tracks.
-- **Real gates** for evidence, tests, review, delegation, stale-stage recovery, and closeout.
-- **Adaptive TDD execution**: feature-atomic slices carry internal 2-5 minute RED/GREEN/REFACTOR steps; cclaw routes them inline, through one builder, through parallel builders, or through strict micro-slices when risk demands it.
-- **Subagents with accountability**: controller owns state, workers do bounded implementation units, overseers validate, evidence lands in `delegation-log.json`.
-- **Recovery instead of confusion**: `npx cclaw-cli sync` tells you blockers and next fixes.
-- **Portable harness behavior** across Claude Code, Cursor, OpenCode, and Codex.
+The split is deliberate. Active and archived flow artifacts go under `flows/` so the orchestrator never confuses them with the read-only library under `lib/`. Runtime (`state/`, `hooks/`) stays at the top so harness hooks can find it without traversal. Active flows are grouped by slug — open `flows/<slug>/` and every artifact for that flow is right there, instead of scattered across six per-stage subdirectories.
 
-## The Daily Loop
+## AC traceability gate (mandatory)
 
-```text
-1. Start or resume
-   /cc <idea>
+Ship is blocked unless every AC in the active plan is `status: committed` with a real commit SHA. The `commit-helper.mjs` hook is the only supported way to commit during `/cc`:
+
+```bash
+git add path/to/changed/file
+node .cclaw/hooks/commit-helper.mjs --ac=AC-1 --message="implement approval pill"
+```
 
-2. Work the current stage
-   The agent writes/updates per-stage files like .cclaw/artifacts/00-idea.md, 01-brainstorm-<slug>.md, 02-scope-<slug>.md
+The hook checks that `AC-1` is declared in `plan.md`, refuses to run when `flow-state.json` schemaVersion is not `2`, runs `git commit`, captures the new SHA, and writes it back into `flow-state.json`. If you commit by hand, AC traceability breaks and ship will refuse.
 
-3. Prove the gate
-   stage-complete records evidence in flow-state.json
+## Compound learnings (automatic, gated)
 
-4. Inspect when stuck
-   npx cclaw-cli sync
+After ship, cclaw automatically checks whether the run produced something worth remembering:
 
-5. Close out after ship
-   /cc continues post_ship_review -> archive
-```
+- a non-trivial decision was recorded by `architect` or `planner`, **or**
+- review needed three or more iterations, **or**
+- a security review ran or `security_flag` is true, **or**
+- the user explicitly asked to capture (`/cc <task> --capture-learnings`).
 
-Tracks keep the flow proportional:
+If yes → `flows/<slug>/learnings.md` is written from the template, and one line is appended to `knowledge.jsonl` recording the slug, ship_commit, signals, and `refines` chain. If no → silently skipped, so the index stays signal-rich. Then everything moves to `flows/shipped/<slug>/` with a `manifest.md`.
 
-```text
-quick     spec -> tdd -> review -> ship
-medium    brainstorm -> spec -> plan -> tdd -> review -> ship
-standard  brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship
-```
+## Parallel-build (cap: 5 slices, git worktree)
 
-At `/cc <idea>`, the user picks **one discovery mode** (`lean`, `guided`, `deep`) for upstream shaping. Track selection remains **model-guided and advisory** during start-up; runtime enforcement begins after state is written: subsequent `/cc` turns follow the selected internal track, persisted `discoveryMode`, required gates, delegation rules, stale-stage markers, and `closeout.shipSubstate`.
+Inline is the default. Parallel-build is opt-in and only when planner declares it. Pre-conditions: ≥4 AC, ≥2 distinct touchSurface clusters, every AC `parallelSafe: true`, no AC depends on outputs of another AC in the same wave.
 
-## When Blocked
+A **slice = 1+ AC with a shared touchSurface**. If planner produces more than 5 slices, planner must merge thinner slices into fatter ones — never generate "wave 2", "wave 3". The 5-slice cap is the v7-era constraint kept on purpose: orchestration cost grows non-linearly past 5 sub-agents, and 5 fits comfortably under every harness's sub-agent quota.
 
-Start here:
+When the harness supports sub-agent dispatch, each parallel slice runs in its own worktree:
 
-```text
-npx cclaw-cli sync
+```bash
+git worktree add .cclaw/worktrees/<slug>-slice-1 -b cclaw/<slug>/slice-1
+git worktree add .cclaw/worktrees/<slug>-slice-2 -b cclaw/<slug>/slice-2
+git worktree add .cclaw/worktrees/<slug>-slice-3 -b cclaw/<slug>/slice-3
 ```
 
-A useful status should read like an operator note, not a raw dump:
+Each slice-builder runs RED → GREEN → REFACTOR for every AC it owns sequentially inside its worktree. After the wave, `reviewer` in `integration` mode reads from each worktree's branch and the orchestrator merges them in. If the harness does not support sub-agent dispatch (or worktree creation fails), parallel-build degrades silently to inline-sequential — recorded but not an error.
 
-```text
-Current: tdd (standard)
-Blocked by: NO_SOURCE_CONTEXT
-Next: cclaw internal rewind plan "add bootstrap slice", then /cc
-Evidence needed: fresh RED/GREEN/REFACTOR slice and verification output
-```
+For ≤4 AC the orchestrator picks `inline` even when AC look "parallelSafe". Dispatch overhead is not worth saving 1-2 AC of wall-clock.
 
-Common exits:
+## When sub-agents help (and when they don't)
 
+Use a sub-agent for:
 
-| Situation                                         | Next action                                                                          |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| Missing gates                                     | Run `/cc`, finish the stage, then complete with evidence.                            |
-| Mandatory delegation missing evidence             | Dispatch the worker/overseer or waive explicitly with rationale.                     |
-| `NO_SOURCE_CONTEXT` or `NO_TEST_SURFACE`          | Rewind to `plan`/`spec`, define the source or test surface, then resume TDD.         |
-| `NO_IMPLEMENTABLE_SLICE` or `RED_NOT_EXPRESSIBLE` | Rework `design`/`spec`/`plan` until one vertical slice is testable.                  |
-| `NO_VCS_MODE`                                     | Restore git, set `vcs: none` with hash evidence, or configure `tdd.verificationRef`. |
-| Review blocked                                    | `cclaw internal rewind tdd "review_blocked_by_critical <finding-ids>"`.              |
-| Stale stage after rewind                          | Redo the marked stage, then `cclaw internal rewind --ack <stage>`.                   |
-| Broken hooks or generated files                   | `npx cclaw-cli sync`, then follow the fail-fast error guidance if it still fails. |
+- **Parallel slice dispatch** during `parallel-build` (cap: 5).
+- **Specialist context isolation** for `architect`, `security-reviewer`, integration `reviewer` when the harness supports it. A fresh sub-agent reads a small focused filebag instead of the orchestrator's full history.
 
+Don't use a sub-agent for:
 
-## Subagents Without Theater
+- Trivial / small / medium slugs (≤4 AC). Run inline.
+- Sequential work that doesn't actually parallelize.
+- Routine work the orchestrator can finish in 1-2 turns.
 
-```text
-user goal
-   |
-   v
-controller ---------------> worker: bounded implementation/test/doc task
-   |                         |
-   |                         v
-   +----------------------> overseer: read-only validation
-                             |
-                             v
-                     evidence refs + terminal status
-                             |
-                             v
-                 .cclaw/state/delegation-log.json
-```
+## Five Failure Modes + review Ralph loop
 
-The controller owns `flow-state.json`, sequencing, synthesis, and the final answer. Workers own scoped work. Overseers verify. A waiver means the work was **not** done by a real worker and must say why proceeding is acceptable.
+Reviews check the Five Failure Modes — hallucinated actions, scope creep, cascading errors, context loss, tool misuse — every iteration. The Five Failure Modes pass is wrapped by the `review-loop` auto-trigger skill so the agent cannot skip it.
 
-## What Is Enforced
+Reviews are not single-shot. They are a Ralph loop with an explicit ledger:
 
-Enforced by generated helpers and state checks:
+1. Iteration 1 lists every finding as F-1, F-2, … in an append-only **Concern Ledger** at the top of `flows/<slug>/review.md`. Each row carries severity (`block` / `warn`), status (`open` / `closed` / `superseded`), and a `file:line` citation.
+2. Iteration N+1 must reread every open row, mark it `closed | open | superseded by F-K`, and append new findings as F-(max+1). It cannot delete or rewrite earlier rows.
+3. The loop ends when (a) every row is `closed`, (b) two consecutive iterations record zero new `block` findings AND every open row is `warn`, or (c) the 5-iteration hard cap fires with at least one open block row — at which point `/cc` stops and reports instead of looping forever.
 
-- Stage completion goes through `node .cclaw/hooks/stage-complete.mjs <stage>`.
-- Required gates need evidence before advancement.
-- Mandatory delegations need terminal evidence or explicit waiver.
-- Stale stages block until redone and acknowledged.
-- Review criticals route back to TDD.
-- Ship continues through `post_ship_review -> archive` with `closeout.shipSubstate`.
+A typical run converges in 1-3 iterations. The hard cap is a circuit breaker, not a target.
 
-Advisory/model-guided:
+## Conversation language
 
-- Initial track heuristic wording.
-- Proactive subagents that are not mandatory for the active stage/tier.
-- Reference patterns that shape prompts but do not add runtime states.
+cclaw replies in the user's language for prose. It NEVER translates wire-protocol identifiers — slugs, `AC-N`, `D-N`, `F-N`, frontmatter keys, file paths, hook output, specialist names, or commit tags. This is enforced by the always-on `conversation-language` skill so a Russian-speaking user, for example, gets Russian explanations but still sees `flow-state.json` and `AC-1` verbatim.
 
-## The Deeper Contract
+## Hooks (default profile: minimal)
 
-The README is the front door. The full operating contract lives here:
+Three hooks ship by default and only `commit-helper.mjs` is mandatory:
 
-- [Scheme of Work](./docs/scheme-of-work.md): stages, gates, recovery, closeout, state files.
-- [Configuration](./docs/config.md): strictness, tracks, TDD, compound, language packs, hooks.
-- [Harnesses](./docs/harnesses.md): Claude, Cursor, OpenCode, Codex capabilities and fallbacks.
-- [Generated Agent Block Example](./docs/agents-block.example.md): what gets injected into harness guidance.
+- `session-start.mjs` — rehydrates flow state and prints active slug
+- `stop-handoff.mjs` — short reminder when stopping mid-flow
+- `commit-helper.mjs` — atomic commit per AC + traceability check
 
-## CLI Reference
+## CLI commands
 
 ```bash
-npx cclaw-cli                   # interactive setup or installed status hint
-npx cclaw-cli init --harnesses=<list> --no-interactive
-npx cclaw-cli sync              # regenerate managed runtime files
-npx cclaw-cli upgrade           # refresh generated files while preserving config
-npx cclaw-cli archive           # explicit archive/reset; normal closeout uses /cc
-npx cclaw-cli uninstall         # remove .cclaw and generated harness shims
-npx cclaw-cli --version
+cclaw init                 # install assets in the current project
+cclaw sync                 # reapply assets to match the current code
+cclaw upgrade              # sync after upgrading the npm package
+cclaw uninstall            # remove cclaw assets from the project
+cclaw version              # print version
+cclaw help                 # short help
 ```
 
+Flow-control commands (`plan`, `status`, `ship`, `migrate`, `build`, `review`) are intentionally **not** part of the CLI. They live as `/cc` instructions inside the harness.
+
+## More docs
+
+- [docs/v8-vision.md](docs/v8-vision.md) — locked decisions, full kill-list, references review
+- [docs/scheme-of-work.md](docs/scheme-of-work.md) — flow walk-through with all checkpoints
+- [docs/skills.md](docs/skills.md) — six auto-trigger skills and what they enforce
+- [docs/config.md](docs/config.md) — `.cclaw/config.yaml` reference
+- [docs/harnesses.md](docs/harnesses.md) — what each harness installs
+- [docs/quality-gates.md](docs/quality-gates.md) — AC traceability + Five Failure Modes
+- [docs/migration-v7-to-v8.md](docs/migration-v7-to-v8.md) — from cclaw 7.x
+
 ## License
 
-[MIT](./LICENSE)
+MIT. See [LICENSE](LICENSE).

package/dist/artifact-frontmatter.d.ts

@@ -0,0 +1,51 @@
+import type { AcceptanceCriterionState, FlowStage, DiscoverySpecialistId, ArtifactStatus } from "./types.js";
+export interface ArtifactFrontmatter {
+    slug: string;
+    stage: FlowStage | "shipped" | "cancelled";
+    status: ArtifactStatus | "cancelled";
+    ac?: AcceptanceCriterionState[];
+    last_specialist?: DiscoverySpecialistId | null;
+    refines?: string | null;
+    shipped_at?: string | null;
+    ship_commit?: string | null;
+    review_iterations?: number;
+    security_flag?: boolean;
+    [key: string]: unknown;
+}
+export interface ParsedArtifact {
+    frontmatter: ArtifactFrontmatter;
+    body: string;
+    raw: string;
+}
+export declare class FrontmatterError extends Error {
+    readonly path?: string | undefined;
+    constructor(message: string, path?: string | undefined);
+}
+export declare function parseArtifact(raw: string, sourcePath?: string): ParsedArtifact;
+export declare function renderArtifact(parsed: ParsedArtifact): string;
+export declare function readArtifact(filePath: string): Promise<ParsedArtifact>;
+export declare function writeArtifact(filePath: string, parsed: ParsedArtifact): Promise<void>;
+export declare function extractAcceptanceCriteriaFromBody(body: string): Array<{
+    id: string;
+    text: string;
+    commit?: string;
+    status: AcceptanceCriterionState["status"];
+}>;
+export declare function mergeAcceptanceCriteria(fromBody: Array<{
+    id: string;
+    text: string;
+    commit?: string;
+    status: AcceptanceCriterionState["status"];
+}>, fromFrontmatter: AcceptanceCriterionState[] | undefined): AcceptanceCriterionState[];
+export interface SyncFrontmatterPatch {
+    ac?: AcceptanceCriterionState[];
+    last_specialist?: ArtifactFrontmatter["last_specialist"];
+    review_iterations?: number;
+    security_flag?: boolean;
+    shipped_at?: string | null;
+    ship_commit?: string | null;
+    refines?: string | null;
+}
+export declare function syncFrontmatter(projectRoot: string, slug: string, stage: FlowStage, patch: SyncFrontmatterPatch): Promise<ParsedArtifact>;
+export declare function isFrontmatterCancelled(frontmatter: ArtifactFrontmatter): boolean;
+export declare function isFrontmatterShipped(frontmatter: ArtifactFrontmatter): boolean;

package/dist/artifact-frontmatter.js

@@ -0,0 +1,131 @@
+import fs from "node:fs/promises";
+import YAML from "yaml";
+import { activeArtifactPath } from "./artifact-paths.js";
+import { exists, writeFileSafe } from "./fs-utils.js";
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/u;
+const AC_LINE_RE = /^[\s>*+-]*\*{0,2}\s*(AC-\d+)\s*[:\-—)]\s*(.+?)\s*$/iu;
+const AC_COMMIT_RE = /\(?(commit\s*[:=]?\s*([0-9a-f]{7,40})|sha\s*[:=]?\s*([0-9a-f]{7,40})|@([0-9a-f]{7,40}))\)?/iu;
+const AC_PENDING_RE = /\(commit\s*[:=]?\s*pending\)/iu;
+export class FrontmatterError extends Error {
+    path;
+    constructor(message, path) {
+        super(message);
+        this.path = path;
+        this.name = "FrontmatterError";
+    }
+}
+export function parseArtifact(raw, sourcePath) {
+    const trimmed = raw.replace(/^\uFEFF/u, "");
+    const match = FRONTMATTER_RE.exec(trimmed);
+    if (!match) {
+        throw new FrontmatterError(`Artifact is missing the required YAML frontmatter block (---).${sourcePath ? ` (${sourcePath})` : ""}`, sourcePath);
+    }
+    const yamlBody = match[1] ?? "";
+    const body = match[2] ?? "";
+    let parsed;
+    try {
+        parsed = YAML.parse(yamlBody);
+    }
+    catch (err) {
+        throw new FrontmatterError(`Invalid YAML frontmatter: ${err.message}`, sourcePath);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new FrontmatterError("Frontmatter must be a YAML object.", sourcePath);
+    }
+    const frontmatter = parsed;
+    if (typeof frontmatter.slug !== "string" || frontmatter.slug.length === 0) {
+        throw new FrontmatterError("Frontmatter must declare a non-empty `slug`.", sourcePath);
+    }
+    if (typeof frontmatter.stage !== "string") {
+        throw new FrontmatterError("Frontmatter must declare a `stage` (plan/build/review/ship/shipped/cancelled).", sourcePath);
+    }
+    if (typeof frontmatter.status !== "string") {
+        throw new FrontmatterError("Frontmatter must declare a `status` (active/shipped/cancelled).", sourcePath);
+    }
+    if (frontmatter.ac !== undefined && !Array.isArray(frontmatter.ac)) {
+        throw new FrontmatterError("Frontmatter `ac` must be an array.", sourcePath);
+    }
+    return { frontmatter, body, raw };
+}
+export function renderArtifact(parsed) {
+    const yaml = YAML.stringify(parsed.frontmatter, { indent: 2 }).trim();
+    const body = parsed.body.startsWith("\n") ? parsed.body : `\n${parsed.body}`;
+    return `---\n${yaml}\n---\n${body.replace(/^\n/u, "")}\n`;
+}
+export async function readArtifact(filePath) {
+    const raw = await fs.readFile(filePath, "utf8");
+    return parseArtifact(raw, filePath);
+}
+export async function writeArtifact(filePath, parsed) {
+    await writeFileSafe(filePath, renderArtifact(parsed));
+}
+export function extractAcceptanceCriteriaFromBody(body) {
+    const results = [];
+    const seen = new Set();
+    for (const rawLine of body.split(/\r?\n/u)) {
+        const line = rawLine.replace(/<[^>]+>/gu, "").trim();
+        const match = AC_LINE_RE.exec(line);
+        if (!match)
+            continue;
+        const id = match[1].toUpperCase();
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        let text = match[2].trim();
+        let commit;
+        let status = "pending";
+        const commitMatch = AC_COMMIT_RE.exec(text);
+        if (commitMatch && !AC_PENDING_RE.test(text)) {
+            commit = commitMatch[2] ?? commitMatch[3] ?? commitMatch[4];
+            if (commit)
+                status = "committed";
+        }
+        text = text.replace(AC_COMMIT_RE, "").replace(AC_PENDING_RE, "").replace(/\s{2,}/gu, " ").replace(/[\s\-:—]+$/u, "").trim();
+        results.push({ id, text, commit, status });
+    }
+    return results;
+}
+export function mergeAcceptanceCriteria(fromBody, fromFrontmatter) {
+    const fmIndex = new Map();
+    for (const ac of fromFrontmatter ?? [])
+        fmIndex.set(ac.id, ac);
+    const merged = [];
+    for (const item of fromBody) {
+        const fm = fmIndex.get(item.id);
+        const commit = item.commit ?? fm?.commit;
+        const status = commit ? "committed" : (fm?.status ?? "pending");
+        merged.push({
+            id: item.id,
+            text: item.text || fm?.text || item.id,
+            commit,
+            status
+        });
+    }
+    for (const [id, ac] of fmIndex) {
+        if (!merged.some((entry) => entry.id === id))
+            merged.push(ac);
+    }
+    return merged;
+}
+export async function syncFrontmatter(projectRoot, slug, stage, patch) {
+    const filePath = activeArtifactPath(projectRoot, stage, slug);
+    if (!(await exists(filePath))) {
+        throw new FrontmatterError(`Artifact flows/${slug}/${stage}.md not found.`, filePath);
+    }
+    const parsed = await readArtifact(filePath);
+    const next = { ...parsed.frontmatter };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === undefined)
+            continue;
+        next[key] = value;
+    }
+    const updated = { ...parsed, frontmatter: next };
+    await writeArtifact(filePath, updated);
+    return updated;
+}
+export function isFrontmatterCancelled(frontmatter) {
+    return frontmatter.status === "cancelled" || frontmatter.stage === "cancelled";
+}
+export function isFrontmatterShipped(frontmatter) {
+    return frontmatter.status === "shipped" || frontmatter.stage === "shipped";
+}

package/dist/artifact-paths.d.ts

@@ -1,28 +1,8 @@
-import type { FlowStage, FlowTrack } from "./types.js";
-export type ArtifactPathIntent = "read" | "write";
-export interface ResolveArtifactPathContext {
-    projectRoot: string;
-    track?: FlowTrack;
-    /**
-     * Optional brainstorm topic used for `<slug>` interpolation.
-     * When omitted, the resolver attempts to infer it from `00-idea.md`.
-     */
-    topic?: string;
-    /**
-     * - read: locate an existing artifact first (new slug shape, then legacy fallback).
-     * - write: return a non-colliding writable path for a new artifact.
-     */
-    intent?: ArtifactPathIntent;
-}
-export interface ResolvedArtifactPath {
-    stage: FlowStage;
-    fileName: string;
-    relPath: string;
-    absPath: string;
-    source: "existing" | "generated";
-    legacy: boolean;
-}
-export declare function isSlugArtifactPattern(filePattern: string): boolean;
-export declare function legacyArtifactFileName(filePattern: string): string;
+import type { FlowStage } from "./types.js";
+export type ArtifactStage = FlowStage | "decisions" | "learnings";
+export declare const ARTIFACT_FILE_NAMES: Record<ArtifactStage, string>;
 export declare function slugifyArtifactTopic(topic: string): string;
-export declare function resolveArtifactPath(stage: FlowStage, context: ResolveArtifactPathContext): Promise<ResolvedArtifactPath>;
+export declare function activeArtifactDir(projectRoot: string, slug: string): string;
+export declare function activeArtifactPath(projectRoot: string, stage: ArtifactStage, slug: string): string;
+export declare function shippedArtifactDir(projectRoot: string, slug: string): string;
+export declare function shippedArtifactPath(projectRoot: string, slug: string, stage: ArtifactStage): string;