@manhquy/flow-skill 0.5.0 → 0.6.0

package/README.md

@@ -5,7 +5,7 @@ Install the **flow** skill into coding agents with one command.
 | | |
 |---|---|
 | **Package** | [`@manhquy/flow-skill`](https://www.npmjs.com/package/@manhquy/flow-skill) (installer CLI) |
-| **Current GA** | **0.5.0** — ships skill product **v0.28.0** |
+| **Current GA** | **0.5.1** — ships skill product **v0.28.1** |
 | **Platforms** | macOS · Linux · Windows (same Node path) |
 | **Requirement** | Node.js **≥ 22.14** |
 | **Source** | [github.com/manhquydev/flow-skill](https://github.com/manhquydev/flow-skill) |
@@ -89,7 +89,7 @@ npx @manhquy/flow-skill@latest --yes --all --dry-run --json
 |----|--------|
 | `npx @manhquy/flow-skill@latest` | Bare `npx @manhquy/flow-skill` (stale npx cache) |
 | **Run** the CLI to copy the skill | `npm i` alone (package only; no skill files in agent homes) |
-| Pin installer `@0.5.0` if needed | Pin npm `@0.28.0` (skill version ≠ package version) |
+| Pin installer `@0.5.1` if needed | Pin npm `@0.28.1` (skill version ≠ package version) |
 | Prefer `@latest` | `@rc` (retired / behind) |
 
 **Two version axes:** `package.json` version = installer; `SKILL.md` metadata = skill product. Both appear in `--help` and in the `plan` JSONL event (`version` + `skillVersion`).
@@ -137,7 +137,7 @@ rm -rf <project>/.claude/skills/flow
 |---------|-----|
 | Agent has no `/flow` after `npm i` | Run `npx @manhquy/flow-skill@latest` (install must **execute**) |
 | Old skill after reinstall | Always use `@latest`; avoid bare package name |
-| `No matching version found` for `@0.28.0` | That is the **skill** version. Use `@latest` or `@0.5.x` |
+| `No matching version found` for `@0.28.1` | That is the **skill** version. Use `@latest` or `@0.5.x` |
 | Node too old | Install Node ≥ 22.14 (`nvm install 22`, etc.) |
 | Windows `EBUSY` / `EPERM` | Close the agent holding files under the skill dir; re-run |
 | Stale install lock | Delete `<parent>/.flow-skill.installing.lock` if reclaim fails |
@@ -147,7 +147,7 @@ rm -rf <project>/.claude/skills/flow
 ## JSONL (`--json`)
 
 ```jsonl
-{"event":"plan","version":"0.5.0","skillVersion":"0.28.0","dryRun":false,"scope":"global","targets":["claude"]}
+{"event":"plan","version":"0.5.1","skillVersion":"0.28.1","dryRun":false,"scope":"global","targets":["claude"]}
 {"event":"install:start","target":"claude","dests":["~/.claude/skills/flow"]}
 {"event":"install:done","target":"claude","dests":["~/.claude/skills/flow"],"result":"success","error":null,"warnings":[]}
 {"event":"summary","success":true,"total":1,"attempted":1,"installed":1,"failed":0,"skipped":0,"aborted":false}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manhquy/flow-skill",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Install the flow skill (buildflow gated build process) into your coding agent(s) via one npx command",
   "type": "module",
   "bin": {

package/skills/flow/SKILL.md

@@ -3,12 +3,12 @@ name: flow
 description: Run the buildflow gated build process from idea to real done-evidence. Walk gated stages (Idea->Research->Scope->PRD->ADR->Contract->Cards->Build->Review->Deploy/Ship->Verify->Retro), each with a honest gate that must pass before advancing. Adapts to project type (web|cli|library|skill). Use when starting or driving a real product build, when the user types /flow, /flow next, /flow card, /flow check, or asks to scope/plan/ship a project through gates. Kill at any gate is a valid outcome.
 user-invocable: true
 when_to_use: "User wants to build a real product end-to-end with discipline (idea -> a deployed URL for web, or installs+runs for a CLI/library/skill), or types any /flow command, or asks for a gated build process, scope decision, contract-first plan, or card-based shipping."
-argument-hint: "[ resume | next | card | check C-NNN | project-type web|cli|library|skill | mode teach|work | skip <stage> | ready | workspace add|list|enter|remove|check|doctor | auto [stop] | attest semantic|live-verify|status|recover | doctor | retro | eval --stage 01|02|05|card|routing --fixture <id> --n 3 --keep-going --report | or just say what you want in plain language ]"
+argument-hint: "[ resume | next | card | check C-NNN | project-type web|cli|library|skill | mode teach|work | skip <stage> | ready | workspace add|list|enter|remove|check|doctor | auto [stop] | attest semantic|live-verify|status|recover | doctor | retro | eval --stage 01|02|05|card|routing|converge --fixture <id> --n 3 --keep-going --report | clarify | converge | or just say what you want in plain language ]"
 keywords: [flow, buildflow, gate, build, ship, scope, prd, contract, card, deploy, vertical-slice, cli, library, skill, worktree, parallel-agents, workspace, multi-agent]
 license: MIT
 metadata:
   author: flow-skill
-  version: "0.28.0"
+  version: "0.29.0"
   attribution: "Methodology from ai20k-build-phase/buildflow (Tony, arealisticdreamer.com); durable-layer ancestry and improve-ritual spirit from repository-harness (protocol v1 EOL — flow-owned fork); agent patterns from claudekit-engineer, BMAD-METHOD. v0.22 concierge from BMAD bmad-help; forge-idea from bmad-forge-idea (MIT, BMad Code LLC)."
 ---
 
@@ -29,9 +29,11 @@ Idea -> Research -> Scope -> PRD -> ADR -> Contract -> Cards -> Build -> Review
 `/flow` is **two layers working together**:
 
 1. **Mechanical layer — `runner/flow.sh`** (deterministic, exit 0/1). It manages the
-   stage/card lifecycle and checks the *cheatable* things: unchecked gate boxes,
-   leftover `[FILL]` placeholders, card status validity, empty done-evidence. Always run
-   it first — its exit code is ground truth, never your own judgment.
+   stage/card lifecycle and checks the *cheatable* things: unchecked gate boxes
+   (including leftover `- [ ]` bullets under `## Open decisions` — same scanner), leftover
+   `[FILL]` placeholders, card status validity, empty done-evidence. Always run it first
+   — its exit code is ground truth, never your own judgment. `/flow clarify` is an
+   advisory printer of those open-decision bullets, not a second gate.
 2. **Semantic layer — YOU (Claude), via this skill** (quality gatekeeper). The script
    cannot tell a real competitor quote from a fabricated one, or a grade-laundered C
    feature from an honest B. **That is your job.** After the script passes, apply the
@@ -103,6 +105,8 @@ takes over a lock you're sure is dead; `/flow unlock` clears it.
 | `/flow coherence` | `flow.sh coherence` — flag version drift across declared version fields (doc-vs-code coherence; advisory) |
 | `/flow consistency` | `flow.sh consistency` — audit cross-artifact coverage: every PRD `FRn` is claimed by a card (`implements:`) and served by a contract interface; numeric success metric; no leftover placeholders (advisory; run after the contract gate, before cards) |
 | `/flow constitution` | `flow.sh constitution` — check operator-authored per-project invariants in `flow/constitution.md` (structure + optional grep-markers); **advisory and NOT a `next` gate** — run it at the scope/PRD/contract seam, then apply the semantic challenge in `gate-rules.md` |
+| `/flow clarify` | `flow.sh clarify` — list leftover `- [ ]` bullets under `## Open decisions` on scope/PRD/contract (section-scoped, always exit 0); **advisory and NOT a `next` gate**. Write-back is the ritual in `references/clarify.md` (opt-in). |
+| `/flow converge` | `flow.sh converge [--file <payload>]` — **append-only** remainder cards reconciling present code vs plan. Assess per `references/converge.md`, write a `flow-converge/v1` payload, then run: transactional (all cards or none), never edits an existing card, prints `CONVERGED` + writes nothing when there is no gap. Semantic proof: `flow.sh eval --stage converge`. |
 | `/flow eval [--stage 01\|02\|card] [--fixture <id>] [--n 3] [--timeout <s>] [--keep-going]` | `flow.sh eval` — **behavioral eval**: does the LLM semantic gate (`gate-rules.md`) actually flag a hollow-but-mechanically-clean fixture? Opt-in, **billable** (skips cleanly, zero calls, if `claude` CLI absent); prints a per-stage scorecard. v0.21: on a final-INVALID vote, raw stdout + stderr + rc are persisted to `.flow/eval-raw/<run_id>/` (git-ignored, envelope-stripped) so an INVALID storm is postmortemable; the first UNRELIABLE fixture aborts the batch (`--keep-going` forces full-batch, worst-case ~37 calls at `--n 3`); the retry backoff is env-injectable (`FLOW_EVAL_RETRY_BACKOFF`, default 5s, set 0 in tests). See `references/gate-eval.md` for scope/cost/limitations. |
 | `/flow eval --report` | `flow.sh eval --report` — **offline**, zero calls: last complete batch's scorecard + drift vs the prior complete batch |
 | `/flow promote <file>` | `flow.sh promote <file>` — copy a playbook into the cross-project KB (`~/.claude/flow/playbooks`); `recall` then surfaces it everywhere |
@@ -219,11 +223,14 @@ Hard stops (iteration/token/time caps) and ground-truth gates (`flow.sh` exit, r
 - `law/RETRO.md` — one honest line per run.
 - `references/gate-rules.md` — the per-stage semantic challenges (the heart of your gatekeeping).
 - `references/stage-state-machine.md` — stage order, unlock conditions, what each artifact must contain.
+- `references/artifact-lifecycle.md` — named mutation models (living plan + append-only cards default; cycle-forward; flow-back). Converge is the flow-back closer. Prevents a `specs/` import. Not a `next` gate.
 - `references/project-types.md` — per-type (web|cli|library|skill) adaptations of the stages, gate lenses, and done-evidence.
 - `references/command-dispatch.md` — exact mapping of each `/flow` command to runner call + your duties.
 - `references/concierge.md` — the default conversational entry: routing loop, May-run/Must-ask default-deny classification, new-user consent script.
 - `references/flow-catalog.tsv` — the intent-class × state → action routing table the concierge reads (source of truth for automated checks).
 - `references/forge-idea.md` — the Idea/Scope persona-interrogation ritual (adapted from BMAD-METHOD's `bmad-forge-idea`, MIT, opt-in, never a gate condition).
+- `references/clarify.md` — bounded sequential write-back for leftover `## Open decisions` bullets on Scope/PRD/Contract (opt-in, never a `next` prereq).
+- `references/converge.md` — the flow-back closer: assess code vs plan, append remainder cards transactionally (`/flow converge`); gap taxonomy + `flow-converge/v1` payload schema. Semantic proof via `eval --stage converge`.
 - `references/agent-detection.md` — detect ck:/bmad agents + priority + fallback.
 - `references/agent-stage-mapping.md` — stage→agent map, scoped prompt template, durable hooks.
 - `references/claudekit-skills.md` — the **skill layer** on top of the agents: the curated per-stage ck-skill whitelist ("what to use when"), the 6 deep-wired high-ROI skills (ck-predict@ADR, ck-scenario@Contract, review-pr@Review/Ship, ck-security@security-cards, retro@Retro, ck-loop@Build/Verify), the binding rules (skill INFORMS / gate JUDGES; Claude-side detection + silent degrade; opt-in-with-prompt, off the hot path), and the loop-vs-two-strikes decision matrix (`flow.sh loop-prep`/`loop-log` plumbing, ck-loop as the untouched execution engine).

package/skills/flow/_templates/02-scope.md

@@ -43,6 +43,7 @@ When a C feature is the real need, three honest paths:
 - [ ] The cut list is written (what I am NOT building in v1)
 - [ ] GO / KILL decision is written below
 - [ ] No FILL placeholders remain in this file
+- [ ] No unresolved open decisions (resolve via /flow clarify, or assume/cut)
 
 ## Time budget
 
@@ -69,3 +70,11 @@ decision.
 ## Decision
 
 [FILL: GO or KILL — one sentence why]
+
+## Open decisions
+
+Record unresolved product choices here (add a line like `- [ ] which tenant key?`). Do not invent auth, tenancy, retention, or billing to clear FILL. Resolve via /flow clarify, or assume/cut.
+
+## Assumptions
+
+Informed defaults (industry-standard or already locked by the operator or an ADR). A bullet that encodes product law (who can access what, tenancy, retention, billing) with no operator/ADR authority is an open decision or a stop, not a silent default.

package/skills/flow/_templates/03-prd.md

@@ -9,6 +9,9 @@
 - [ ] Pain & gain is a MAPPING TABLE: every pain cites evidence (a stage-01 quote or a named observation), and names the v1 feature that kills it; every v1 feature kills at least one pain
 - [ ] A stranger could build v1 from this without asking me anything
 - [ ] No FILL placeholders remain in this file
+- [ ] No unresolved open decisions (resolve via /flow clarify, or assume/cut)
+- [ ] No unquantified adjectives (fast / secure / intuitive / robust / prominent) in Features or NFRs — a number, a named constraint, or cut the word
+- [ ] Every `FRn` names the failure or empty case (what the user sees when it fails or there is nothing), or an explicit `none`
 
 ## Context
 
@@ -55,3 +58,11 @@ interface in the contract (`FRn →`); `/flow consistency` checks this mechanica
 ## Success metric (numbers only)
 
 [FILL: e.g. "10 tickets filed by real residents in week 1; median first-response < 2h"]
+
+## Open decisions
+
+Record unresolved product choices here (add a line like `- [ ] which tenant key?`). Do not invent auth, tenancy, retention, or billing to clear FILL. Resolve via /flow clarify, or assume/cut.
+
+## Assumptions
+
+Informed defaults (industry-standard or already locked by the operator or an ADR). A bullet that encodes product law (who can access what, tenancy, retention, billing) with no operator/ADR authority is an open decision or a stop, not a silent default.

package/skills/flow/_templates/05-contract.md

@@ -15,6 +15,10 @@ another, both look green. This file is the cheap fix.
 - [ ] Every interface has its INPUT and OUTPUT shapes written (web: request+response · cli: flags+output/exit code · library: args+return)
 - [ ] Access/effects column filled for every interface (web: public/token/admin · non-web: writes/side-effects, or "none")
 - [ ] No FILL placeholders remain in this file
+- [ ] No unresolved open decisions (resolve via /flow clarify, or assume/cut)
+- [ ] Every write interface names the failure shape (status or exit + body), not only the happy path
+- [ ] Every interface that can return empty names the empty shape (empty list / 404 / exit 2), or an explicit `none`
+- [ ] Access/effects is a concrete token (web: public/token/admin · non-web: writes/side-effects or "none") — not a vibe word (secure, authenticated, restricted)
 
 ## OpenAPI / Swagger rule  (web only — N/A for cli/library/skill)
 
@@ -57,3 +61,7 @@ Reference each PRD feature by its `FRn` id so the mapping is machine-checkable
 (`/flow consistency` flags any `FRn` with no interface here).
 
 - [FILL: FR1 → interface(s) that serve it]
+
+## Open decisions
+
+Record unresolved product choices here (add a line like `- [ ] which tenant key?`). Do not invent auth, tenancy, retention, or billing to clear FILL. Resolve via /flow clarify, or assume/cut.

package/skills/flow/_templates/card.md

@@ -11,6 +11,10 @@ risk-ack: none
 
 [FILL: exactly what this card builds. If it's two things, split it.]
 
+## Independent test
+
+[FILL: one sentence — if only this card shipped, what can a user do? Or `infra` / `none` for scaffold/CI/contract-test/e2e plumbing. "Unit tests pass" is not an independent test.]
+
 ## Allowed files
 
 [FILL: which files/dirs this card may touch — keeps the diff reviewable]

package/skills/flow/eval/fixtures/converge/conv-01/cards/C-001.md

@@ -0,0 +1,21 @@
+# C-001 - greet
+status: done
+implements: FR1
+
+## Scope
+greet(name) returns a greeting string.
+
+## Independent test
+A caller runs greet("Ada") and reads back a greeting naming Ada.
+
+## Allowed files
+src/app.py
+
+## Verify (run these before calling the card done)
+- [x] greet("Ada") contains "Ada"
+
+## Done-evidence (world-state proof)
+the shipped module returns the greeting
+
+## Evidence (paste the actual proof here when done)
+verified by running the module

package/skills/flow/eval/fixtures/converge/conv-01/flow/03-prd.md

@@ -0,0 +1,7 @@
+# PRD - greeting service
+
+## Features
+- FR1: a caller gets a greeting for a name via greet(name) and reads it back.
+
+## Success metric
+- greet returns in under 10ms for any name.

package/skills/flow/eval/fixtures/converge/conv-01/src/app.py

@@ -0,0 +1,3 @@
+# Greeting service. Implements FR1: greet(name) returns a greeting naming the caller.
+def greet(name):
+    return "Hello, " + name + "!"

package/skills/flow/eval/fixtures/converge/gap-01/cards/C-001.md

@@ -0,0 +1,21 @@
+# C-001 - task create + list
+status: done
+implements: FR1
+
+## Scope
+POST /tasks and GET /tasks.
+
+## Independent test
+A user creates a task at /tasks and sees it returned by the list.
+
+## Allowed files
+src/app.py
+
+## Verify (run these before calling the card done)
+- [x] POST /tasks returns 201
+
+## Done-evidence (world-state proof)
+the deployed service returns the created task
+
+## Evidence (paste the actual proof here when done)
+verified against the running service

package/skills/flow/eval/fixtures/converge/gap-01/cards/C-002.md

@@ -0,0 +1,21 @@
+# C-002 - mark task done
+status: done
+implements: FR2
+
+## Scope
+POST /tasks/{id}/done flips a task to done.
+
+## Independent test
+A user marks a task done and then reads it back as done.
+
+## Allowed files
+src/app.py
+
+## Verify (run these before calling the card done)
+- [x] POST /tasks/1/done returns 200
+
+## Done-evidence (world-state proof)
+the deployed service reports the task as done
+
+## Evidence (paste the actual proof here when done)
+verified against the running service

package/skills/flow/eval/fixtures/converge/gap-01/flow/03-prd.md

@@ -0,0 +1,8 @@
+# PRD - task list service
+
+## Features
+- FR1: a user creates a task via POST /tasks and sees it in GET /tasks.
+- FR2: a user marks a task done via POST /tasks/{id}/done and it then reads as done.
+
+## Success metric
+- 95% of task creates succeed in under 300ms.

package/skills/flow/eval/fixtures/converge/gap-01/flow/05-contract.md

@@ -0,0 +1,7 @@
+# Contract
+
+| FRn | interface | request | response | failure | access |
+|-----|-----------|---------|----------|---------|--------|
+| FR1 | POST /tasks | {title} | 201 {id,title,done:false} | 400 {error} | token |
+| FR1 | GET /tasks | - | 200 [task] | - | token |
+| FR2 | POST /tasks/{id}/done | - | 200 {id,done:true} | 404 {error} | token |

package/skills/flow/eval/fixtures/converge/gap-01/src/app.py

@@ -0,0 +1,11 @@
+# Task service. Implements FR1 (create + list) only.
+# FR2 (mark a task done) has no route here - the done endpoint was never written.
+tasks = []
+
+def create_task(title):
+    t = {"id": len(tasks) + 1, "title": title, "done": False}
+    tasks.append(t)
+    return t
+
+def list_tasks():
+    return tasks

package/skills/flow/eval/fixtures/converge/manifest.tsv

@@ -0,0 +1,3 @@
+id	stage	repo-dir	allow-list	expected
+gap-01	converge	gap-01	src/app.py	GAP
+conv-01	converge	conv-01	src/app.py	CONVERGED

package/skills/flow/law/CLAUDE.md

@@ -48,6 +48,12 @@ done-rules are identical in both modes.
 
 ## Standard card sequence
 
+The first *value* card after the vertical slice must be independently demoable.
+Do not emit a models-only (or services-only, or migrations-only) card: if it
+cannot name a user-visible `## Independent test`, it is not a card — fold the
+work into the slice that ships the value, or write `infra` / `none` only for
+scaffold/CI/contract-test/e2e plumbing.
+
 1. **Scaffold + CI/CD** — repo, deploy pipeline, `/healthz` on a public URL. The scaffold
    picks the spec-serving mechanism (FastAPI: free at `/docs` + `/openapi.json`; other
    stacks: choose the generator in the ADR) — API docs are plumbing, not a later feature.
@@ -138,3 +144,4 @@ in parallel. The runner advises; the OPERATOR dispatches. Rules:
   marking them safe (planning all cards up front is fine).
 - Editing `_templates/` or `flow.sh` during a project run.
 - Frontend code before the UI mock card is approved.
+- A models-only (or layer-only) card whose Independent test is empty or "unit tests pass".

package/skills/flow/references/artifact-lifecycle.md

@@ -0,0 +1,58 @@
+# Artifact lifecycle — what moves after a change
+
+Unlock order (`stage-state-machine.md`) says how a plan is *built the first time*.
+This file says what happens to the artifacts *after* a requirement changes. It is
+a naming convention, not a runner feature — there is no `flow.sh lifecycle`. Not a
+`next` gate.
+
+## Default: living plan + append-only cards
+
+Flow runs **one product cycle** in `flow/` + `cards/`:
+
+- **Living plan.** `flow/00…05` are amended in place. A changed requirement edits
+  `03-prd.md` / `05-contract.md` where the requirement lives (plus a
+  `## Clarifications` note if it came from `/flow clarify`). You do not fork a new
+  planning tree.
+- **Append-only cards.** Issued `cards/C-NNN.md` are **not** rewritten to chase a
+  plan change. New or changed work becomes **new** cards (`C-NNN+1`), with
+  `deps:` on the cards they build on. A "v2" is more cards + a plan amendment —
+  **not** a parallel `specs/002-…/` universe.
+
+This keeps one source of truth for *planning* (PRD + contract) and one for *done*
+(world-state evidence in card `## Evidence`). It is why the mechanical scanner can
+stay simple: there is exactly one `flow/` and one `cards/` to gate.
+
+## The three models (name the one you are using)
+
+| Model | What moves first | When |
+|---|---|---|
+| **living** (default) | the plan artifact is edited in place; new cards append | ordinary requirement change mid-cycle |
+| **cycle-forward** | a fresh set of cards (and a PRD amendment) opens a new increment; old cards stay immutable as the shipped record | a v2 / next milestone on top of a shipped v1 |
+| **flow-back** | code already drifted ahead of (or behind) the plan; you reconcile plan↔tree, then append remainder cards | after an out-of-band change, or to catch a hollow-complete plan |
+
+All three keep the **append-only cards** rule. They differ only in what you touch
+first. Pick one deliberately; do not silently rewrite issued cards to hide drift.
+
+## Flow-back closer = converge
+
+The flow-back model needs a step that reads the present code against the plan
+(PRD `FRn`, contract interfaces, cards, constitution `INV-n`) and **appends**
+remainder cards for whatever is `missing` / `partial` / `contradicts` /
+`unrequested` — without rewriting history. That closer is `/flow converge`.
+
+The skill assesses code vs plan per `references/converge.md` and writes a
+`flow-converge/v1` payload; `/flow converge` then **appends** the remainder cards
+transactionally (all-or-nothing, never editing an existing card, byte-identical
+`cards/` when nothing remains). The semantic gap-detection has its own eval
+modality (`flow.sh eval --stage converge`) proving it flags a declared `FRn` the
+code never built. The appended cards are `[FILL]` stubs — build them through the
+normal `/flow ready` + `/flow check` path.
+
+## What not to do
+
+- **Do not add a `specs/NNN-slug/` tree** (spec-kit style) or a `feature.json`.
+  Flow numbers work with card ids, not a second spec universe; a parallel tree is
+  how you get two sources of truth that drift.
+- Do not rewrite or renumber an issued card to match a plan edit — append instead.
+- Do not treat the plan as immutable and pile all change into cards — the plan is
+  living; keep PRD/contract honest so a stranger can still build v1 from them.

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,6 +20,8 @@ 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 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** (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 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 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. |

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.