@manhquy/flow-skill 0.5.1 → 0.7.0

package/skills/flow/references/clarify.md

@@ -0,0 +1,191 @@
+# Clarify ritual — resolve leftover open decisions (Scope / PRD / Contract)
+
+Bounded, sequential write-back for open product decisions. Ported in *shape* from
+Spec Kit's `/speckit.clarify` protocol; rewritten in Flow nouns. Open decisions
+are unchecked `- [ ]` bullets under `## Open decisions` on `02-scope.md`,
+`03-prd.md`, and `05-contract.md`. The existing line-anchored box scanner in
+`scan_gate` already fails `next` / `gate` / `planning_complete` on those bullets.
+This file is how you *clear* them.
+
+**Not a planning stage. Not a `next` prerequisite command.** `flow.sh clarify`
+only prints leftover bullets (section-scoped). The interview is this ritual.
+Never auto-fired. Offer it (opt-in-with-prompt) when `scan_gate` lists unchecked
+boxes under `## Open decisions`, the same way forge-idea is offered at Idea/Scope.
+
+Does **not** replace:
+- `forge-idea.md` — persona pressure-test of the *idea* (kill/harden), not write-back
+- `mode-work.md` — one batch interview up front; leftover open decisions are the
+  *only* reason to ask more after that batch
+- `native-rituals.md` §2 — edge-case *generation* for the contract
+- `gate-rules.md` material-authority stop — detect invented policy; this ritual
+  *asks* then writes the answer
+
+Informs, never judges: a finished clarify session does not pass the gate.
+`flow.sh next` still has to see zero `[FILL]` / unchecked boxes, and you still
+run the stage's semantic challenge.
+
+## When
+
+- Stage 02, 03, or 05 has one or more unchecked `- [ ]` bullets under
+  `## Open decisions` (mechanical fail), **or**
+- The operator asks to pin a Decision-required item before it gets invented into
+  the artifact.
+- Skip at 00 / 01 / 04 — those stages have forge-idea / research / ADR rituals.
+
+Cap: **at most 5 questions asked** in one session (retries on the same question
+do not count). There is no mechanical cap on how many open-decision bullets a
+file may carry (every leftover `- [ ]` already fails the gate). If the section
+is a pile, that is a **semantic** "too many — assume or cut" judgment (see
+`gate-rules.md`), not a runner count.
+
+## Token rules (authoring, before this ritual)
+
+When drafting 02 / 03 / 05 (especially in `mode work`):
+
+1. **Write it** if the operator said it or the previous stage locked it.
+2. **Assume + record** if a reasonable industry default exists and the choice
+   does not change scope, security/privacy, or UX. On 02/03 record it under
+   `## Assumptions`. On **05 (contract) there is no `## Assumptions` section** —
+   do not invent one (`gate-rules.md` forbids it); assume by writing the
+   access/effects cell or shared shape, or cut.
+   Reasonable defaults (do **not** open-decide these): data retention for the
+   domain, ordinary error-message tone, session/OAuth2 for a standard web app
+   unless tenancy/SSO is the product, REST vs GraphQL when the stack is already
+   picked.
+3. **Add a line like `- [ ] which tenant key?` under `## Open decisions`** only
+   when: the choice changes scope, security/privacy, or UX; several
+   interpretations have different implications; **and** no honest default exists.
+   Priority: scope > security/privacy > UX > technical.
+4. Never invent auth, tenancy, retention, billing, or enforcement-owner to clear
+   `[FILL]`. That is the failure this section exists to stop.
+
+## Taxonomy (coverage scan — internal)
+
+Walk the current artifact. Mark each category Clear / Partial / Missing. Do not
+print the raw map unless you will ask zero questions (then print a one-line
+"all Clear" summary).
+
+| Category | Look for |
+|---|---|
+| Functional scope | who it is for, v1 vs cut list, GO/KILL still standing |
+| Domain & data | entities, identity/uniqueness, lifecycle |
+| Interaction / UX | critical journey, empty/error/loading |
+| Non-functional | latency, scale, availability — only if v1-load-bearing |
+| Integration | external services, failure modes |
+| Edge / failure | negative path, conflict, throttle |
+| Constraints / tradeoffs | stack already locked in ADR? rejected alternatives |
+| Terminology | one canonical noun (`ticket` vs `issue`) |
+| Completion | numeric success metric; observable result per FRn |
+| Placeholders | leftover open-decision bullets, vague adjectives ("robust", "secure") |
+
+Skip a candidate question if answering it would not change implementation,
+validation, or the cut list — or if it belongs in ADR (stage 04), not here.
+
+Queue at most 5, ranked Impact × Uncertainty. Prefer one high-impact security
+or tenancy question over two low-impact wording questions.
+
+## Sequential loop
+
+Present **exactly one** question at a time. Never reveal the rest of the queue.
+
+**Question writing:**
+- Lead with `**Question:**` and a full interrogative that ends in `?`.
+- Optional suffix after the `?`: `(FR3)` or `(scope)`. Never use a label as the
+  question (`Acceptance device matrix` is invalid).
+- Next line: one plain "Why it matters" sentence (the stake for shipping).
+- Everyday wording. A reader who does not know Flow must be able to answer
+  from the Question line alone.
+
+**Multiple choice (preferred):**
+- Pick a **Recommended** option first (best default given project type, risk
+  reduction, anything already locked in scope/ADR). One or two sentences why.
+- Then a table:
+
+  | Option | Description |
+  |--------|-------------|
+  | A | … |
+  | B | … |
+  | C | … (D/E if needed, max 5) |
+  | Short | different answer, ≤5 words |
+
+- After the table: `Reply with the letter, "yes"/"recommended" to accept, or a short answer.`
+
+**Short answer (no honest discrete options):**
+- `**Suggested:** <≤5 words> — <one-line why>`
+- `Format: ≤5 words. Reply "yes"/"suggested" to accept, or your own answer.`
+
+After the operator answers:
+- "yes" / "recommended" / "suggested" → use your stated recommendation.
+- Otherwise map to one option or accept a ≤5-word phrase.
+- Ambiguous → re-ask (does not consume a new slot).
+- Then write back (next section) **before** asking the next question.
+
+**Stop when:**
+- remaining queued items are no longer necessary, or
+- the operator says done / good / no more / stop / proceed, or
+- you have asked 5 questions, or
+- no valid question existed at the start.
+
+If the quota is hit with high-impact leftovers, list them under **Deferred**
+with a one-line rationale (better as an Assumption, a cut-list item, or a later
+ADR). Do not leave them as unchecked open-decision bullets if you can honestly
+assume or cut.
+
+## Write-back (after EACH accepted answer)
+
+Target file = the stage you are clarifying (`flow/02-scope.md` / `03-prd.md` /
+`05-contract.md`). Teach mode: the operator writes; you propose the exact
+patch. Work mode: you write, then self-challenge.
+
+1. Ensure a `## Clarifications` section exists. Create it **just above**
+   `## Assumptions` (or at the end if Assumptions is missing). Under it, a
+   `### Session YYYY-MM-DD` subheading for today.
+2. Append `- Q: <question> → A: <final answer>`.
+3. Patch the *real* section — do not leave the answer only in the log:
+   - scope / cut / GO-KILL → Features in v1, Cut list, or Decision
+   - actor / journey → Target users or Features (`FRn:`)
+   - data / entity → Shared shapes (contract) or Features
+   - NFR / metric → Success metric or Non-functional requirements (must stay
+     numeric / observable)
+   - edge / failure → a named bullet, or a contract failure shape
+   - term → one canonical noun everywhere you just touched
+4. **Remove the `- [ ]` bullet** this answer resolved (or tick it only if you
+   keep a resolved record in-place — prefer delete so the section stays empty
+   when work is done). Leave no contradictory earlier sentence.
+5. Save after each answer (overwrite the file). Do not reorder unrelated
+   headings. Keep each insertion short and testable.
+
+Allowed new headings: `## Clarifications`, `### Session YYYY-MM-DD` only.
+
+## Assumptions challenge (after the loop, and after a mechanical PASS)
+
+Read `## Assumptions` on the artifact you just touched. For each bullet:
+
+- Is this a real default (industry-standard, or already locked by the operator
+  / ADR), or is it **product law** (who can access what, tenancy, retention,
+  billing, enforcement owner) wearing an assumption hat?
+- If it is product law with no operator/ADR authority → treat it as
+  Decision-required: either add an open-decision bullet (and ask it) or
+  **stop** and list it the same way `gate-rules.md` material-authority stop
+  does. Do not silently keep it.
+
+A clean mechanical gate with a sneaky assumption is the exact hollow-pass this
+ritual exists to catch.
+
+## Completion report (to the operator)
+
+- Questions asked & answered (count).
+- File(s) patched.
+- Sections touched.
+- Open-decision bullets remaining (should be zero on the file you cleared;
+  say so if not).
+- Coverage one-liner per taxonomy row: Resolved / Deferred / Clear / Outstanding.
+- Suggested next: `/flow next` if open decisions are gone; otherwise another
+  clarify pass or an honest cut/assume.
+
+## Done when
+
+Every accepted answer is in `## Clarifications` *and* in the real section.
+Resolved open-decision bullets are gone from the file. Assumptions were
+challenged for silent policy invention. No `cmd_next` / `cmd_clarify` coupling
+was implied — the operator (or you, after they agree) runs `next` themselves.

package/skills/flow/references/command-dispatch.md

@@ -10,7 +10,7 @@ install dir; run from the project root so `flow/` and `cards/` resolve.
 | `/flow resume` | `bash <skill>/runner/flow.sh resume` | Read-only, no lock. Relay all four sections verbatim (last session, in-flight + dwell, gate state, NEXT ->). Run this FIRST when entering a project mid-cycle with no prior context this session. Never expand on or guess at raw args it didn't print — it deliberately shows command names only. |
 | `/flow next` | `bash <skill>/runner/flow.sh next` | If FAIL: relay the exact violations + line numbers; offer help, don't author/tick in teach mode. If PASS: run the stage's challenge in `gate-rules.md`; flag hollow content, let operator decide. |
 | `/flow assess` | `bash <skill>/runner/flow.sh assess` | Brownfield only: fill `flow/00-inspect.md` from EVIDENCE (read the code) — functionality/UI/UX vs product, risks, test baseline, **Evidence ledger** claim tags. After mechanical PASS, apply gate-rules **Brownfield assess** challenge (no Observed→product-law promotion). Reuse `scout`/`researcher`. Gate is operator-reviewed; then proceed to `/flow next`. |
-| `/flow card` | `bash <skill>/runner/flow.sh card` | Confirm the new card id; remind: fill Scope (one thing) / Allowed files / Verify / Done-evidence per `law/CLAUDE.md`. |
+| `/flow card` | `bash <skill>/runner/flow.sh card` | Confirm the new card id; remind: fill Scope (one thing) / Independent test / Allowed files / Verify / Done-evidence per `law/CLAUDE.md`. |
 | `/flow card start C-NNN` | `bash <skill>/runner/flow.sh card start C-NNN` | Optional: mark the card in flight (operator-visible in-progress, shown in `/flow status`). Portable `cards/.inflight` registry; does NOT touch the gated `status:` field. Coexists with hand-edit. |
 | `/flow card done C-NNN` | `bash <skill>/runner/flow.sh card done C-NNN` | Optional convenience: CLI-owned flip to `done`, gated by the SAME done-rules as `check` (reverts on fail — never a hollow done). Then still apply the semantic card review (diff-vs-scope, contract shapes, real evidence) as with `check`. |
 | `/flow check C-NNN` | `bash <skill>/runner/flow.sh check C-NNN` | If PASS mechanically: review diff-vs-scope, allowed-files drift, contract-shape match, DESIGN.md for UI, evidence = real world-state. |
@@ -20,8 +20,11 @@ install dir; run from the project root so `flow/` and `cards/` resolve.
 | `/flow coherence` | `bash <skill>/runner/flow.sh coherence` | Flags version drift across declared version fields (package.json / pyproject / src app_version). The cheap doc-vs-code slice; semantic contradictions stay a human gate-challenge. |
 | `/flow consistency` | `bash <skill>/runner/flow.sh consistency` | After the contract gate, before cards: every PRD `FRn` is claimed by a card (`implements:`) and served by a contract interface; numeric success metric; no leftover placeholders. Then apply the semantic cross-artifact passes in `gate-rules.md` (hollow coverage, conflicting requirements, terminology drift). Advisory. |
 | `/flow constitution` | `bash <skill>/runner/flow.sh constitution` | At the scope/PRD/contract seam: checks `flow/constitution.md` is well-formed (no placeholder, every invariant has an ID) + scans declared grep-markers. **Advisory, NOT a `next` gate** — then apply the semantic challenge in `gate-rules.md`. |
-| `/flow eval [--stage 01\|02\|card] [--fixture <id>] [--n 3] [--timeout <s>]` | `bash <skill>/runner/flow.sh eval [...]` | **Billable** (skips cleanly, zero calls, if `claude` CLI absent). Relay the scorecard verbatim. See `references/gate-eval.md` before running: what it measures (a fresh-judge lower bound, not the work-mode self-challenge), cost, and thresholds. Never wired into `next`/`check` gating — informative only. |
+| `/flow clarify` | `bash <skill>/runner/flow.sh clarify` | List leftover `- [ ]` bullets under `## Open decisions` on 02/03/05 (section-scoped). **Advisory, NOT a `next` gate** — write-back is `references/clarify.md` (opt-in). Never invent auth/tenancy/retention/billing to clear FILL. |
+| `/flow converge` | `bash <skill>/runner/flow.sh converge [--file <payload>]` | Flow-back closer: assess present code vs plan per `references/converge.md`, write a `flow-converge/v1` payload to `.flow/converge-pending.md`, then run to **append** remainder cards. Transactional (all or none), append-only (never edits an existing card), prints `CONVERGED` + writes nothing when there is no gap. Present the findings table to the operator first. |
+| `/flow eval [--stage 01\|02\|card] [--fixture <id>] [--n 3] [--timeout <s>]` | `bash <skill>/runner/flow.sh eval [...]` | **Billable** (live mode skips cleanly, zero calls, if `claude` CLI absent). `--replay` does **not** inherit that SKIP — missing fixtures exit 1. Relay the scorecard verbatim. See `references/gate-eval.md` before running: what it measures (a fresh-judge lower bound, not the work-mode self-challenge), cost, and thresholds. Never wired into `next`/`check` gating — informative only. |
 | `/flow eval --report` | `bash <skill>/runner/flow.sh eval --report` | Offline, zero calls. Relay the last complete batch's scorecard + drift vs the prior complete batch. |
+| `/flow eval --replay` | `bash <skill>/runner/flow.sh eval --replay` | Keyless. Replay recorded stripped transcripts through parse → vote → per-fixture match lines (no scorecard; replay writes no results rows). Not a fresh-judge; verdicts never count toward the eval floor. Stale `gate_rules_sha` → exit 1 (re-record live). |
 | `/flow project-type <web\|cli\|library\|skill>` | `bash <skill>/runner/flow.sh project-type [t]` | Set/read the project type that selects the per-type gate lens + done-evidence definition (`references/project-types.md`). Confirm the type matches reality before planning. |
 | `/flow usage [--global\|--prune]` | `bash <skill>/runner/flow.sh usage [...]` | Roll up the JSONL usage log and relay the analytics (cycle-time, gate fail-rate, per-stage + per-card dwell, command breakdown). Local-only; `--prune [--keep N]` caps the log. Read-only — nothing to author. |
 | `/flow skip <stage> --reason ...` | `bash <skill>/runner/flow.sh skip <stage> --reason ...` | Advance past a gate that has a matching open `DEBT.md` line. **Security-class skips are operator-only and HALT** — never auto-skip; the operator accepts the exposure in writing first. |

package/skills/flow/references/concierge.md

@@ -45,6 +45,7 @@ SKILL.md's Forbidden list). When a brand-new user's ask requires you to draft so
 - contract
 - tokens
 - constitution
+- clarify
 - design
 - doctor
 - ready
@@ -68,6 +69,7 @@ operator-authority-only):
 - unlock
 - retro
 - eval
+- converge
 
 **Default-deny:** any verb not explicitly listed under May-run above is must-ask — this
 includes any verb added to flow after this file was written. When in doubt, ask.

package/skills/flow/references/converge.md

@@ -0,0 +1,109 @@
+# Converge — append-only remainder cards (plan vs present code)
+
+Flow can prove a *card* is not hollow (Verify + world-state Evidence). It cannot prove the
+*plan* was fully expressed in the card tree. `converge` closes that gap: assess present code
+against the plan, then **append** remainder cards for whatever is still missing. It never
+rewrites history and never touches application code.
+
+`converge` is the **flow-back closer** named in `references/artifact-lifecycle.md`.
+
+## When
+- After the originally planned cards are `done` but you want to confirm the codebase actually
+  expresses every PRD `FRn`, contract interface, and constitution `INV-n`.
+- Mid-cycle when code drifted ahead of (or behind) the plan and you need to reconcile.
+- Not a `next` gate. Opt-in. The runner half only *appends* cards from a payload you produce.
+
+## Operating constraints (non-negotiable)
+- **Append-only.** Never edit, renumber, or delete an existing `cards/C-*.md`.
+- **Never touch application code.** `converge` emits cards; a human/`auto` builds them later.
+- **Byte-identical when converged.** If nothing remains, write nothing and print `CONVERGED`.
+- **Assess present code, not a diff.** Read what the tree does now vs what the plan requires;
+  this is not a git-diff or branch comparison.
+- **Transactional.** Either every remainder card is written, or none is (no partial append).
+
+## Intent inventory (what you load)
+From the plan: PRD `## Features` (`FRn` + observable result), `05-contract.md` interfaces
+(request/response/failure shapes, access), constitution `INV-n` MUST rows, the card set and
+their claimed scope. This is the set of promises the code must keep.
+
+## Code-scope map (what you check it against)
+Read the source the cards claim to have built. For each promise, decide whether the present
+code keeps it. Judge behaviour and interfaces, not line counts.
+
+## Gap taxonomy (closed set)
+- **missing** — a promised `FRn` / interface / MUST has no implementation in the tree.
+- **partial** — implemented but incomplete against its observable result / failure shape.
+- **contradicts** — the code does something the plan/contract forbids or specifies differently.
+- **unrequested** — code surface exists that no `FRn`/interface/decision asked for.
+
+## Severity (closed set)
+- **CRITICAL** — a constitution MUST or a P1/baseline `FRn` is missing or contradicted.
+- **HIGH** — a non-baseline `FRn` or a named contract interface missing/partial.
+- **MED / LOW** — partials with a workaround; cosmetic contradictions.
+
+## Disposition
+- `missing` / `partial` / `contradicts` → a remainder card (`implements:` the `FRn`/interface,
+  `## Scope` citing the source-ref + gap-type, `deps:` on the last related card).
+- `unrequested` → a **review card** (or a `DEBT` line), never an instruction to delete code.
+
+## Present the findings first
+Emit a findings table (id, gap-type, severity, source-ref, one-line) to the operator BEFORE
+any card is written. Then hand the payload to the runner, which appends the cards.
+
+## Payload schema (`flow-converge/v1`)
+Write findings to `.flow/converge-pending.md` (run-state, gitignored — so a `CONVERGED` run
+never dirties `cards/`), then run `/flow converge` (or `flow.sh converge --file <path>`). The
+runner is transactional: it appends every card or none. Format — a header, then one `---`-fenced
+block per finding:
+
+```
+schema: flow-converge/v1
+findings: 2
+
+---
+gap-type: missing
+severity: HIGH
+implements: FR2
+source-ref: 03-prd.md:FR2
+title: implement the mark-task-done endpoint
+deps: C-002
+allowed: src/app.py
+---
+gap-type: unrequested
+severity: LOW
+implements: none
+source-ref: src/app.py:debug_dump
+title: the debug_dump surface no feature asked for
+deps:
+allowed: src/app.py
+```
+
+Each block: `gap-type` (missing|partial|contradicts|unrequested — the runner rejects anything
+else and writes nothing), `title` (required), and optional `severity`/`implements`/`deps`/
+`source-ref`/`allowed`. `unrequested` becomes a **review** card (`implements: none`) — never a
+delete instruction. Zero findings (or no payload) → the runner prints `CONVERGED` and writes
+nothing. Appended cards ship with `[FILL]` Verify/Done-evidence (they are not built yet).
+
+## Converge challenge
+
+*(Sliced by the converge eval judge. This section is the criteria a reviewer applies when
+asked whether a codebase still owes work against its plan.)*
+
+A codebase is **converged** only when every promise in the plan is kept by the present code:
+
+- Every PRD `FRn` has code that produces its stated observable result — not a stub, not a
+  handler that returns the shape without the behaviour, not a sibling feature standing in.
+- Every contract interface exists with its request/response **and failure** shape.
+- Every constitution MUST is honoured.
+- No code contradicts a stated decision, and no unrequested surface is silently load-bearing.
+
+Report a **GAP** when at least one promise is not kept by the present code — most commonly a
+declared `FRn` that the source never implements while its card is marked done. Report
+**CONVERGED** only when the present code keeps every declared promise. When the evidence is
+ambiguous, prefer **GAP** — an unflagged missing feature is the failure this check exists to
+catch. A card marked done is not evidence the feature exists; read the source.
+
+## Done when
+- [ ] Findings table presented before any write
+- [ ] Remainder cards appended (or `CONVERGED` printed and nothing written)
+- [ ] No existing card edited; no application code touched

package/skills/flow/references/flow-catalog.tsv

@@ -16,3 +16,5 @@ adr-decision-ask	stage-04	next	offers the native persona-debate ritual before lo
 contract-hardening-ask	stage-05	contract	offers the native edge-case decomposition ritual to harden the seam before the Contract gate	ck-scenario	flow
 security-review-ask	security-class-card	check	runs the native STRIDE ritual on every security-class card (guaranteed baseline)	ck-security	flow
 loop-fix-ask	build-verify-numeric-gap	status	offers the native loop protocol (flow.sh loop-prep/loop-log) when a fix needs more than one attempt against a numeric target	ck-loop	flow
+open-decision-ask	stage-02-or-03-or-05	clarify	lists ## Open decisions bullets; skill offers references/clarify.md write-back (opt-in, never a next prereq)	-	flow
+close-the-gap-ask	cards-done-verify-plan	converge	assess present code vs plan per references/converge.md, then append-only remainder cards (transactional; CONVERGED writes nothing)	-	flow

package/skills/flow/references/gate-eval.md

@@ -25,14 +25,18 @@ rule text is enforceable by *a* judge," not "this build's self-review caught eve
 
 ## Fixtures and thresholds
 
-Seven shipped fixtures (`skills/flow/eval/fixtures/`, manifest `skills/flow/eval/manifest.tsv`):
+Eleven shipped fixtures (`skills/flow/eval/fixtures/`, manifest `skills/flow/eval/manifest.tsv`):
 sound/hollow pairs for Stage 01 (Research — fabricated quotes, vague "users"), Stage 02 (Scope —
-grade laundering, a real C quietly graded B), and the card gate:
+grade laundering, a real C quietly graded B), Stage 05 (listed; heading map does not yet judge
+them), and the card gate:
 - **fcda** — sound multi-signal Evidence (mechanical PASS, semantic PASS)
 - **fcdb** — process-only hollow (mechanical **FAIL** after hollow-done floor; still listed for
   historical FLAG text / offline inspection)
 - **fcdc** — hollow-with-decoy multi-signal (mechanical PASS, semantic **FLAG** — the residual
   attack class the mechanical floor does not claim to close)
+- **fcdd** — B1-S artifact-less Evidence prose (mechanical PASS, semantic **FLAG** — names no
+  path/URL/command; the semantic-only catch for `ground-truth-gates.md` rule 8)
+- **fcde** — B1-S same story with concrete artifact refs (mechanical PASS, semantic PASS)
 
 Fixture content maps 1:1 to the failure modes already documented in `gate-rules.md`, not an
 invented taxonomy. The v1 input set is **manifest-listed shipped fixtures only** — `eval` never
@@ -61,8 +65,10 @@ separately from a real mismatch — never silently counted as a gate pass or fai
 `eval` is **opt-in and billable** — it makes real `claude -p` API calls. Zero cost when the
 `claude` CLI isn't on `PATH` (clean skip, exit 0). When present, exactly one minimal probe call
 is made to confirm the CLI runs headless before any real judging starts; a probe failure means
-one billable call was made, then a clean skip. A full default batch is 7 fixtures × N=3 = 21
-judge calls + the 1 probe = 22 calls.
+one billable call was made, then a clean skip. The artifact manifest is 11 rows; a full
+default batch judges the 9 heading-mapped fixtures (01 / 02 / card) × N=3 = 27 judge calls
++ the 1 probe = 28 calls. The two Stage 05 rows fail closed before a call. Plan accounting
+for a complete re-record is 11 × 3 = 33 + probe.
 
 **Measured real cost** (this machine, 2026-07-10, default/unforced model, no `--bare` available
 under an OAuth/subscription session — see the build's spike notes): roughly **$0.30–0.37 per
@@ -78,6 +84,39 @@ fresh-judge eval is to reflect a realistic judge, not the cheapest one that pass
 `--report` (below) is the free, offline way to re-read a prior batch's numbers without spending
 anything.
 
+**macOS without `timeout`/`gtimeout`:** live `flow.sh eval` (not `--report`, not `--replay`) refuses
+by default. The watchdog fallback cannot bound a stuck `claude` call, so a hung judge is an
+unbounded-billing risk. Install GNU coreutils (`gtimeout`) or export `FLOW_EVAL_UNBOUNDED=1` to
+accept that risk for one run. `--report` and `--replay` never hit this guard. `--record` is live
+and does.
+
+## Modes
+
+| Mode | Calls | What it proves |
+|------|-------|----------------|
+| live (default) | Billable `claude -p` | Fresh-judge catch-rate (eval floor) |
+| `--report` | Zero | Last complete **live** batch + advisory drift |
+| `--record` | Same as live | Writes stripped transcripts under `eval/replay/` |
+| `--replay` | Zero | Parse → vote → per-fixture match lines (no scorecard; no results rows) + gate-rules **hash** staleness |
+
+`--record|--replay` are artifact-modality only (not `--stage routing|converge`, not `--report`).
+
+**Replay is not a fresh-judge.** Gate-rules text is embedded in the live prompt; recorded
+responses are frozen. Replay cannot test rules *effectiveness* — that stays live and billable.
+What it can do: hard-fail when `_eval_gate_rules_sha` ≠ the recorded hash (`fixtures stale —
+re-record live per ADR re-baseline rule`). Replay verdicts **never count toward the eval floor**.
+
+**Refresh protocol:** edit both sides of a rules change, run a live `--record` batch (11 × `--n 3`
+= 33 judge calls + 1 probe; 9 heading-mapped fixtures bill 27 + probe today) on a host with
+real `timeout`/`gtimeout`, commit the stripped `eval/replay/` tree (verdict lines only — no
+`session_id` / `cwd` envelopes) **in the same change** as the `gate-rules.md` edit. No
+operator-recorded batch exists yet — the `eval-replay` CI job skip-with-notice until then;
+the recorded-sha staleness check is unchanged.
+
+**B1 escalation:** if hollow-done decoys that name no artifact/command recur in dogfood or
+live eval after the B1-S addendum lands, escalate to full structured lineage evidence. Replay
+verdicts never count toward that trigger.
+
 ## Running it
 
 ```
@@ -86,6 +125,8 @@ flow.sh eval --stage card              # only the card-gate fixtures
 flow.sh eval --fixture fcdb --n 1       # one fixture, one run (cheap smoke check)
 flow.sh eval --timeout 180              # override the per-call timeout (default 120s)
 flow.sh eval --report                   # OFFLINE: last complete batch's scorecard + drift
+flow.sh eval --record --n 3             # LIVE: write stripped replay fixtures (billable)
+flow.sh eval --replay --n 3             # KEYLESS: replay recorded transcripts
 ```
 
 Exit code: `0` = every evaluated fixture majority-matched its expected verdict (or a clean
@@ -146,9 +187,10 @@ yet (the same "measure, don't assume" discipline that gated this build in the fi
   platform: a signal arriving while the runner is blocked on a foreground judge call was not
   observed to preempt that call promptly. Cleanup between fixtures/calls fires reliably; a
   normal (uninterrupted) run always cleans up its temp files immediately.
-- **Small fixture corpus (seven)**: enough to prove the mechanism and give a real number, not
-  enough for statistical confidence across every stage/failure-mode combination. Widening the
-  corpus is a natural v1.x follow-up, not a v1 blocker.
+- **Small fixture corpus (eleven manifest rows, nine heading-mapped)**: enough to prove the
+  mechanism and give a real number, not enough for statistical confidence across every
+  stage/failure-mode combination. Widening the corpus is a natural v1.x follow-up, not a
+  v1 blocker.
 
 ## Failure modes and postmortem (v0.21)
 
@@ -174,8 +216,8 @@ window; the mechanism was never confirmed at the time (rate-limit vs hook conten
 4. **Circuit breaker.** The FIRST evaluated fixture coming back UNRELIABLE (`invalid_count*3 > n`)
    aborts the batch with a distinct nonzero exit code (2) and NO `done` trailer written — the
    junk batch is invisible to `--report`/drift, so it cannot poison the baseline. `--keep-going`
-   forces the full batch; document worst case (≤ N_fixtures × n × 2 + 1 probe ≈ 37 calls at
-   default 7 × 3).
+   forces the full batch; document worst case (≤ N_fixtures × n × 2 + 1 probe ≈ 55 calls at
+   default 9 heading-mapped × 3).
 
 ### Rate-limit visibility (advisory, best-effort)
 

package/skills/flow/references/gate-rules.md

@@ -79,6 +79,15 @@ GO/KILL, no FILL.
 - **Offer the forge-idea ritual (opt-in-with-prompt — `references/forge-idea.md`)** when a
   GO/KILL call is genuinely close. It informs the decision; it never decides it — the
   operator still calls GO or KILL.
+- **Assumption vs open decision:** read `## Assumptions`. A bullet that encodes product
+  law (who can access what, tenancy, retention, billing, enforcement owner) with no
+  operator/ADR authority is an **open decision or a stop**, not a silent default — move
+  it under `## Open decisions` (a line like `- [ ] which tenant key?`) or halt. Do not
+  invent auth/tenancy/retention/billing to clear `[FILL]`.
+- **Too many open decisions** is a semantic judgment (there is no mechanical cap): if
+  the section is a pile, assume or cut rather than interview everything. Offer the
+  clarify ritual (`references/clarify.md`, opt-in, never a `next` prereq) when any
+  open decision remains.
 
 ## Stage 03 — PRD
 Mechanical: filled from stage 02, numeric success metric, pain&gain table, no FILL.
@@ -90,6 +99,14 @@ Mechanical: filled from stage 02, numeric success metric, pain&gain table, no FI
   named observation) AND name the v1 feature that kills it? Does *every v1 feature* kill at
   least one pain? Orphans on either side = scope drift.
 - Could a stranger build v1 from this without asking the operator anything?
+- Read Features and NFRs as a reviewer of English, not of code: any unquantified adjective (fast/secure/intuitive) or an `FRn` with no named failure/empty case is a rewrite, not a vibe.
+- **Assumption vs open decision:** read `## Assumptions`. A bullet that encodes product
+  law (who can access what, tenancy, retention, billing, enforcement owner) with no
+  operator/ADR authority is an **open decision or a stop**, not a silent default — move
+  it under `## Open decisions` or halt. Do not invent policy to clear `[FILL]`.
+- **Too many open decisions** is a semantic judgment (no mechanical cap): assume or
+  cut rather than interview a pile. Offer the clarify ritual (`references/clarify.md`,
+  opt-in, never a `next` prereq) when any open decision remains.
 
 ## Stage 04 — ADR
 Mechanical: each decision has why + rejected, NOT-doing list, covers storage/auth/deploy.
@@ -118,6 +135,15 @@ cli=command+flags+output/exit, library=public function+args+return, skill=comman
   the cli equivalent: `--out` vs `--output`)?
 - Is the access/effects column real for every interface (web: public/token/admin · non-web:
   writes/side-effects or "none")? Do NOT let a web product blank the access column.
+- Read each write interface as a reviewer of English, not of code: if the failure shape is missing or Access/effects is a vibe word (secure/authenticated/restricted), the seam is not written yet.
+- **Assumption vs open decision:** access/effects or shared shapes that encode product
+  law (tenancy, auth, retention, billing) with no operator/ADR authority are an **open
+  decision or a stop**, not a silent default — add a `## Open decisions` bullet or halt.
+  (Contract has no `## Assumptions` section; do not invent one.) Do not invent
+  tenancy/auth from convenience to clear `[FILL]`.
+- **Too many open decisions** is a semantic judgment (no mechanical cap): assume or
+  cut rather than interview a pile. Offer the clarify ritual (`references/clarify.md`,
+  opt-in, never a `next` prereq) when any open decision remains.
 - One-way rule: this file is planning source of truth. For web the served spec
   (`/openapi.json`) is the runtime artifact of the SAME contract (amend file -> code -> spec).
   For non-web there is no served spec — the no-drift check is the per-type done-evidence.
@@ -143,6 +169,12 @@ Mechanical: no FILL, valid status, required sections, if done -> verify boxes ch
 evidence non-empty.
 **Challenge:**
 - Is the scope ONE thing? If it's two, split the card.
+- **Independent test:** if the field is empty, missing on a value card, or is
+  "unit tests pass" / "code merged", split or rewrite. A value card names a
+  user-visible proof ("resident files a ticket at /new and sees it on /tickets").
+  Scaffold/CI/contract-test/e2e may say `infra` or `none`. Mechanical leftover
+  `[FILL]` fails `check` only while the heading remains (the heading is not a
+  required `cmd_check` section — §1.6 is cut).
 - Does the diff touch only `## Allowed files`? Drift outside = stop, amend the card first.
 - Do request/response shapes match `flow/05-contract.md` exactly? No improvised shapes.
 - For UI cards: reviewed against `law/DESIGN.md` (tokens, affordance ladder, object-first,
@@ -150,6 +182,9 @@ evidence non-empty.
 - **Is `## Evidence` real world-state** — a clickable URL, real curl output, a DB row — and
   NOT "tests pass" / "code merged" / "deployed successfully"? Merge != shipped: the proof is
   the live surface changing, verified as a user.
+- **Does every `## Evidence` item name its artifact (path/URL) or the command that produced
+  it?** Plausible prose that names neither is still hollow even when the mechanical floor
+  passes (`ground-truth-gates.md` rule 8).
 - **If this card fixes a bug/regression**, the evidence includes the red→green proof that the
   new test was actually tied to the bug (`ground-truth-gates.md` → "Bug-fix cards"), not just a
   green run.

package/skills/flow/references/ground-truth-gates.md

@@ -40,6 +40,13 @@ and used only to add color, never to pass a gate.
 7. **Hand-edit `status: done` is not trusted for deps** until Evidence **and** Verify boxes
    pass the same floor (`ready` re-validates Evidence + unchecked Verify + `[FILL]`; graph
    executor mirrors).
+8. **Every done-evidence item names its artifact or command.** Each `## Evidence` item must
+   name the path/URL of the artifact or the command that produced it. Plausible prose that
+   names neither is hollow even when the mechanical multi-signal floor passes — the card
+   gate's semantic challenge catches it (`gate-rules.md` → Card gate). Old prose-only
+   evidence still passes `flow.sh check` (the floor is unchanged). **Escalate to full
+   structured lineage evidence (B1)** only if hollow-done decoys of this class recur in
+   dogfood or live eval after this addendum lands.
 
 ## Bug-fix cards: prove the test was tied to the bug
 When a card's job is fixing a bug/regression (not new behavior), a passing test is not yet

package/skills/flow/references/mode-work.md

@@ -21,10 +21,15 @@
    in work mode — scope is the operator's call, and killing here is cheap.
 4. **Draft 03 -> 05.** PRD (numeric metric, pain->feature mapping), ADR (delegate to
    `architect`/`bmad-create-architecture`), Contract (the seam; consider `bmad-spec` kernel).
-   Run each gate.
+   Run each gate. After drafting 02 / 03 / 05, leftover bullets under `## Open decisions`
+   are the **only *scheduled*** reason to ask more (via `/flow clarify` + `references/clarify.md`);
+   the assumption challenge after a mechanical PASS can still halt (see Rules below).
+   Never invent auth, tenancy, retention, or billing to clear `[FILL]`.
 5. **Deliver the card set as one summary.** After stage 05 passes, run `/flow card` to
    create the cards, fill their scopes, and present the whole set + build order + which are
    parallel-safe (`/flow ready`) in a single summary for the operator to review.
+   Group cards under PRD `FRn` (the user-visible story), not under layer (all models, then
+   all services). Every value card fills `## Independent test`.
 
 ## Rules that still hold in work mode
 - Every gate must pass mechanically (`flow.sh`) AND semantically (`gate-rules.md`). Drafting
@@ -33,5 +38,10 @@
 - Research must be real (opened competitors, quoted complaints with links) — no fabrication.
   This is the highest-risk stage for an AI author; verify every quote has a source.
 - Scope honesty: do not grade-launder your own C features to B. Call C a C, justify the path.
+- After 02 / 03 / 05, leftover open decisions are the only *scheduled* reason to ask more (via
+  clarify). Even with none, the assumption-vs-open-decision challenge after a mechanical PASS
+  can still halt or add a bullet (a policy-encoding `## Assumptions` line with no operator/ADR
+  authority is an open decision, not a silent default). Never invent auth / tenancy / retention
+  / billing to clear FILL.
 - Done is still world-state evidence; you cannot mark a card done without real proof.
 - Write durable records (intake/decision/story) as you go, same as teach mode.

package/skills/flow/references/stage-state-machine.md

@@ -32,7 +32,7 @@ honored outcome, not a failure of the flow.
 | 03 PRD | `flow/03-prd.md` | numeric success metric, pain&gain mapping table, user-action->observable-result features |
 | 04 ADR | `flow/04-adr.md` | decisions with why+rejected covering storage/auth/deploy, NOT-doing list |
 | 05 Contract | `flow/05-contract.md` | every feature->endpoint, request+response shapes, auth per endpoint |
-| Card | `cards/C-NNN.md` | one-thing scope, deps, allowed files, verify steps, named done-evidence, pasted evidence when done |
+| Card | `cards/C-NNN.md` | one-thing scope, Independent test (user-visible sentence or infra/none), deps, allowed files, verify steps, named done-evidence, pasted evidence when done |
 
 ## Shipping stages live inside cards
 Build -> Review -> Deploy -> Verify-live are NOT `/flow next` stages. They happen inside
@@ -40,6 +40,14 @@ each card: the `## Verify` checklist (run for real) and `## Evidence` (world-sta
 Card sequence (scaffold/CI -> vertical slice -> backend -> contract-tests -> UI mock ->
 frontend -> e2e) is governed by `law/CLAUDE.md`.
 
+## After a change (artifact lifecycle)
+
+Unlock order is not a mutation policy. Default: **living plan + append-only
+cards** — amend `flow/*.md` in place; never rewrite issued cards; a v2 cycle
+is new cards + a plan amendment, not a `specs/` tree. The three named models
+(living / cycle-forward / flow-back) and the converge closer live in
+`references/artifact-lifecycle.md`.
+
 ## Runner contract
 - `flow.sh` exit `0` = pass/advanced, `1` = gate fail or usage error.
 - Reads/writes `flow/`, `cards/`, `MODE`, `RETRO.md`, and seeds `DESIGN.md` once, under `FLOW_PROJECT_ROOT` (default `$PWD`).