@manhquy/flow-skill 0.7.1-next.0 → 0.7.3

package/skills/flow/_templates/card.md

@@ -1,9 +1,11 @@
 # C-NNN — [FILL: one-line scope, ONE thing]
 
 status: todo
+<!-- status: todo|done (in-flight is cards/.inflight, not a status value) -->
 deps: [FILL: card ids this depends on, e.g. "C-001, C-002" — or "none"]
 implements: [FILL: PRD feature ids this card delivers, e.g. "FR1, FR2" — or "infra"/"none" for non-feature cards]
 risk: unknown
+<!-- risk: unknown|standard|security-class -->
 risk-reason:
 risk-ack: none
 
@@ -13,6 +15,7 @@ risk-ack: none
 
 ## Independent test
 
+<!-- PASS: a user opens /g/demo-4person/balance and sees "Alice owes Bob $12.50". FLAG: unit tests pass -->
 [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
@@ -21,7 +24,7 @@ risk-ack: none
 
 ## Verify (run these before calling the card done)
 
-- [ ] [FILL: a concrete check — a curl, a click, a command + expected output]
+- [ ] [FILL: command + expected output OR URL/path + observable user fact. Not "tests pass"]
 
 ## Done-evidence (world-state proof, named BEFORE building)
 
@@ -30,4 +33,5 @@ a curl output, a deployed page. "Tests pass" / "code merged" are NOT done-eviden
 
 ## Evidence (paste the actual proof here when done)
 
+<!-- Paste the re-run command output or re-read the path/URL. Do not quote the agent claiming tests passed. -->
 (empty until done)

package/skills/flow/law/CLAUDE.md

@@ -8,9 +8,8 @@ no advance. Read `README.md` once for the method; THESE rules govern every sessi
 
 `/flow` (status) · `/flow next` (gate-check + unlock stage) · `/flow card` (new card) ·
 `/flow check C-NNN` (validate card) · `/flow mode teach|work` (who writes the plan) ·
-`/flow retro` (3 questions → RETRO.md / playbooks/ / FLOW-FEEDBACK.md) ·
 `/flow ready` (what's buildable now, parallel-safe groups) · `/flow auto` (autonomous
-build run — preflight via runner, then drive per SKILL.md AUTO PRINCIPLES: subagent per
+build run — preflight via runner, then drive per `references/auto-run.md`: subagent per
 card, planner reviews + verifies, worktree isolation for parallel groups, operator-gated
 cards halt by design, state in card files + AUTO-LOG.md).
 Runner: `bash .claude/skills/flow/runner/flow.sh <cmd>`.
@@ -37,10 +36,12 @@ done-rules are identical in both modes.
    into `## Evidence`. Only then set `status: done`, then run `/flow check C-NNN`.
 4. Done-evidence = world-state (deployed URL, curl output, DB row). "Tests pass" /
    "code merged" are mid-pipeline, never done.
-5. Never check a gate box or write a planning artifact on the user's behalf.
+5. Before coding a card, read `law/CODING.md`.
+6. Never check a gate box or write a planning artifact on the user's behalf (teach).
+   In work mode the host drafts after the interview; gates still bind.
    Never set a card `done` without pasted evidence.
-6. Read any file flow.sh just created before first editing it.
-7. **Playbooks** (`playbooks/`): paid-for stack knowledge. Before building a card that
+7. Read any file flow.sh just created before first editing it.
+8. **Playbooks** (`playbooks/`): paid-for stack knowledge. Before building a card that
    touches a stack with a playbook (check `playbooks/README.md` index), READ it and run
    its smoke tests before committing to a design on that stack. After a card pays for a
    non-obvious lesson, HARVEST it back into a playbook — the card review isn't done

package/skills/flow/law/CODING.md

@@ -0,0 +1,37 @@
+# Coding law — buildflow projects
+
+LAW for product code on every card. Read before implementing. If a change
+conflicts, this rule wins — or amend this file with a dated note. Portable
+only: no stack, no runtime.
+
+1. **Explicit resolve.** MUST run a named `resolve` (or equivalent) before
+   the handler. NEVER hide `??` / `||` defaults inside the handler.
+   - Good: `spec = resolve(req); handle(spec)`
+   - Bad: `handle({ port: req.port ?? 8080 })`
+
+2. **Fail loud.** MUST throw a named error at the first resolvable point.
+   NEVER silently default a missing required referent.
+   - Good: `raise MissingConfig("DATABASE_URL")`
+   - Bad: `url = env.DATABASE_URL or "postgres://localhost/app"`
+
+3. **Tests name behavior.** MUST title tests by the observable fact they pin.
+   NEVER "works correctly", "handles edge case", or "unit tests pass".
+   - Good: `GET /healthz returns 200 {ok:true} when the process is up`
+   - Bad: `health check works correctly`
+
+4. **No empty catch.** NEVER swallow with an empty `catch` / `except`. If
+   the body is empty, MUST name what it swallows and why nothing else can
+   reach it; keep the try to one statement.
+   - Good: `except AbortError:  # timeout cancelled the fetch; nothing else lands here`
+   - Bad: `catch (_) {}`
+
+5. **Cite the seam.** MUST cite `flow/05-contract.md`, an ADR path, or card
+   id `C-NNN` for a product decision. NEVER "as discussed" / "as agreed".
+   - Good: `// C-012 / 05-contract GET /healthz — empty: none`
+   - Bad: `// as discussed, skip the empty list`
+
+6. **Library over hand-roll.** MUST prefer a maintained library named in an
+   ADR when the swap deletes owned parser code and its tests. NEVER keep a
+   hand-rolled parser beside that library.
+   - Good: ADR names `zod`; delete `parseJsonLoose` and its tests
+   - Bad: keep `parseJsonLoose()` "just in case" after adopting zod

package/skills/flow/references/agent-detection.md

@@ -4,11 +4,11 @@
 built-in behavior when none are present. It stays portable: rich where agents exist,
 unbroken where they don't.
 
-## Detection (at runtime, by the skill = Claude)
+## Detection (built-in-first)
 
-You already know which agents and skills the host exposes (the Task tool's
-`subagent_type` registry + the available Skills list). Detect by checking that registry —
-do NOT assume. Also glob for project-local definitions when unsure:
+The host's inline/generic path is always available. Overlay named specialists only when the
+host registry actually lists them — do not assume a Task tool, ck: agents, or any one vendor.
+Detect by checking that registry. Also glob for project-local definitions when unsure:
 - ck: agents: `.claude/agents/*.md` (project) and the host agent registry.
 - bmad skills: the Skills list (`bmad-*`) and `.claude/skills/bmad-*`.
 
@@ -17,7 +17,7 @@ do NOT assume. Also glob for project-local definitions when unsure:
 For each stage, pick the FIRST available:
 1. **ck: agent** (primary) — planner, researcher, architect, fullstack-developer, code-reviewer, typescript-reviewer, python-reviewer, tester, ui-ux-designer, docs-manager, git-manager, debugger, scout.
 2. **bmad-* skill** (alternative) — bmad-prd, bmad-create-architecture, bmad-spec, bmad-create-story, bmad-dev-story, bmad-code-review, bmad-check-implementation-readiness, bmad-market-research, bmad-technical-research, bmad-qa-generate-e2e-tests.
-3. **built-in fallback** — you (Claude) do it inline, or spawn a generic `Explore`/`general-purpose` agent. Output shape must match the agent path so the gate is identical.
+3. **built-in fallback** — the host drafts inline, or spawns a generic `Explore`/`general-purpose` agent. Output shape must match the agent path so the gate is identical.
 
 ## Codex — the cross-vendor second engine (a tier that crosses the ladder, not just sits under it)
 
@@ -75,11 +75,13 @@ Manager / real `agy` terminal, paste the ReviewResult back); an empty Gemini res
   contract. An agent fills an artifact; the gate still judges it. A missing agent never
   lowers a gate — it only changes who drafts.
 - **No named mux required.** Absence of any multiplexer never fails a gate. Parallel occupancy is host-owned — `host-agnostic-parallel.md`.
-- **Context isolation (orchestration-protocol).** Give each subagent ONLY: the task, the
-  specific files to read/modify, acceptance criteria, and relevant law/contract excerpts.
+- **Context isolation (orchestration-protocol).** Spawn-not-fork: the brief is whole context.
+  Give each subagent ONLY: the task, the specific files to read/modify, acceptance criteria, and relevant law/contract excerpts.
   Never the full session history. One card = one scoped brief.
-- **Status protocol.** Every subagent returns DONE / DONE_WITH_CONCERNS / BLOCKED /
-  NEEDS_CONTEXT. Handle BLOCKED/NEEDS_CONTEXT before retry (more context → simpler task →
+- **Status protocol.** Every subagent returns the structured block in `agent-stage-mapping.md`
+  (summary / evidence / nextSteps / blocker, last line `STATUS: DONE|DONE_WITH_CONCERNS|BLOCKED|NEEDS_CONTEXT`).
+  Missing STATUS = BLOCKED in the brief contract; the parent treats the child as BLOCKED.
+  The runner does not parse STATUS. Handle BLOCKED/NEEDS_CONTEXT before retry (more context → simpler task →
   escalate). Two-strikes: a second red result → **Codex rescue if the tier is eligible**
   (`codex:codex-rescue`, a different engine), else fresh subagent, else escalate to operator.
 - **Durable record hook.** After a stage/card agent finishes, write the durable record via

package/skills/flow/references/agent-stage-mapping.md

@@ -11,12 +11,12 @@ ladder below: (1) **rescue** — if the chosen path is BLOCKED twice, hand the s
 the primary drafter for **research** and **build** stages (`codex:codex-rescue --write` /
 `codex-companion.mjs task --write`). **Default stays ck:**; Codex-as-primary is operator-selected,
 never automatic. The scope/PRD/ADR/Contract judgment stages stay Claude by default (Codex may
-still rescue them). The stage gate is identical on the Codex path — Codex drafts, the gate judges. In `teach` mode you do NOT author — you
-gatekeep; agents assist the operator. In `work`/`auto` mode you (or the agent) draft, then
+still rescue them). The stage gate is identical on the Codex path — Codex drafts, the gate judges. In `teach` mode the host does NOT author — it
+gatekeeps; agents assist the operator. In `work`/`auto` mode the host (or a specialist) drafts, then
 the gate still judges.
 
-Artifact language: **Vietnamese for user-facing copy** (per `law/DESIGN.md`: VN native,
-`₫` prices, VietQR), **English for code identifiers/endpoints**.
+Artifact language: **English for code identifiers/endpoints**. User-facing copy is Vietnamese
+**when the project is Vietnamese-facing** (`law/DESIGN.md` VN block: VN native, `₫` prices, VietQR); otherwise match the product language.
 
 ## Brownfield pre-stage (existing codebase)
 
@@ -60,7 +60,7 @@ gate): **`ck-predict` at ADR** (5-persona pre-decision debate) and **`ck-scenari
 
 **Portability degrade rungs for git-manager and docs-manager:**
 - `git-manager` absent → inline: operator runs `git commit` + `git push` + opens PR manually following the durable-hook pattern. Gate (PR merged, SHA logged in `AUTO-LOG.md`) is identical.
-- `docs-manager` absent → inline: Claude updates docs directly after card implementation; gate (impacted docs under `docs/` match the code change) is identical.
+- `docs-manager` absent → inline: the host updates docs directly after card implementation; gate (impacted docs under `docs/` match the code change) is identical.
 
 **Portability degrade rungs for the language-specialist Review lens** (`adversarial-review.md` §Language-specialist lens selection):
 - `typescript-reviewer` or `python-reviewer` AGENT present → run it layered with `code-reviewer` for `.ts/.tsx/.js/.jsx` or `.py` cards respectively. Gate (triage table, adversarial verdict) is identical.
@@ -69,7 +69,7 @@ gate): **`ck-predict` at ADR** (5-persona pre-decision debate) and **`ck-scenari
 
 ## Scoped prompt template (use for EVERY delegation)
 
-Keep it small. No session history. Fill every slot from the live artifacts.
+Keep it small. Spawn-not-fork: the brief is whole context. No session history. Fill every slot from the live artifacts.
 
 ```
 Task: <one stage/card goal>
@@ -78,8 +78,43 @@ Read for context: flow/05-contract.md (shapes), law/DESIGN.md (UI only),
 Files to modify: <card ## Allowed files ONLY>
 Acceptance criteria: <the stage gate from gate-rules.md, or the card ## Verify steps>
 Constraints: contract is the seam (never improvise a shape); done = world-state evidence;
-  Vietnamese user-facing copy; touch only allowed files
-Return: the drafted artifact + status (DONE/DONE_WITH_CONCERNS/BLOCKED/NEEDS_CONTEXT)
+  Vietnamese user-facing copy when the project is Vietnamese-facing (law/DESIGN.md VN block); touch only allowed files
+  Child MUST NOT resolve Tier-C, write DEBT, skip a gate, merge, or run flow.sh check.
+  Child complete = this report. Parent still runs flow.sh check.
+Return — last line MUST be STATUS. Missing STATUS = BLOCKED (brief contract; runner does not parse STATUS):
+summary: <one sentence what changed>
+evidence: <paths, commands, live proof>
+nextSteps: <parent-only; never skip/debt/merge>
+blocker: <empty unless BLOCKED or NEEDS_CONTEXT>
+STATUS: DONE|DONE_WITH_CONCERNS|BLOCKED|NEEDS_CONTEXT
+```
+
+Cross-field (docs-only; runner does not parse STATUS): DONE requires non-empty evidence + empty blocker. BLOCKED and NEEDS_CONTEXT require a non-empty blocker. nextSteps never skip, debt, or merge.
+
+Filled DONE (evidence paths, empty blocker). Child complete = this report; parent still `flow.sh check`:
+```
+summary: C-012 checkout POST matches contract and returns live 200
+evidence: cards/C-012.md; src/api/checkout.ts; curl -sS https://app.example/api/checkout -> 200
+nextSteps: parent runs flow.sh check C-012
+blocker:
+STATUS: DONE
+```
+
+Missing last-line STATUS — parent treats BLOCKED:
+```
+summary: wired checkout handler
+evidence: src/api/checkout.ts
+nextSteps: parent runs flow.sh check C-012
+blocker:
+```
+
+Invalid — `STATUS: DONE` with empty evidence (not a pass; parent still `flow.sh check`):
+```
+summary: checkout done
+evidence:
+nextSteps: parent runs flow.sh check C-012
+blocker:
+STATUS: DONE
 ```
 
 ## Stage notes
@@ -95,17 +130,17 @@ Return: the drafted artifact + status (DONE/DONE_WITH_CONCERNS/BLOCKED/NEEDS_CON
 - **Build via fullstack-developer:** one card = one scoped session. Pass the card's Scope +
   Allowed files + the contract shapes it consumes. It must honor shapes exactly.
 - **Repair / diagnostic via debugger:** detect-first ladder entry — NOT a hard dependency.
-  Dispatch `Task(subagent_type="debugger")` with a scoped brief: task description, the failing
+  Debugger if present else inline + fresh scoped brief: task description, the failing
   card file, test output, and `## Verify` acceptance criteria. NO session history (context
-  isolation per orchestration-protocol). If `debugger` is ABSENT in the host, degrade to inline
-  root-cause analysis + a fresh same-ladder (Claude) subagent for the redraw. A missing agent
+  isolation per orchestration-protocol). A missing agent
   changes WHO diagnoses, never whether `## Verify` + `flow.sh check` must pass for real.
-  Escalation order: debugger (Claude diagnostic) -> Codex (if USABLE) -> Antigravity (if USABLE)
+  Escalation order: debugger (host diagnostic) -> Codex (if USABLE) -> Antigravity (if USABLE)
   -> operator.
 - **Verify-live:** the proof is the LIVE surface (deployed URL, real curl), not "tests pass".
   Record `story update --e2e 1` + a `trace` only after the live check.
 
 ## After any delegation
+Child complete is a worker report, not a gate. Missing STATUS = BLOCKED. Then:
 1. Run the gate (`flow.sh next` for stages, `flow.sh check C-NNN` for cards).
 2. Apply the semantic challenge from `gate-rules.md`.
 3. Write the durable hook above. NOTE: the engine now AUTO-fires some — `flow next` past 01 seeds

package/skills/flow/references/auto-run.md

@@ -4,17 +4,46 @@
 `flow.sh auto` requires planning complete, classified card **risk** (no `unknown`),
 valid security-class DEBT acknowledgement when needed, a reliable live supervisor, and a
 current Stage 05 `semantic_gate` receipt — then writes shared `.flow/auto-state`. Full
-contract: `references/attestations.md`. Then YOU (Claude) orchestrate per the principles
+contract: `references/attestations.md`. Then the hosting agent orchestrates per the principles
 below. Operator chose: **Tier-A auto-merge green cards; halt at security-class.**
 While auto is active, mechanical transitions require current card semantic/live receipts;
 there is no hidden bypass — use `flow auto stop` for deliberate manual continuation.
 
+## AutoDecision (docs vocabulary only)
+
+Closed enum — this file is the only home. `cmd_auto` is unchanged and does not parse it.
+Do not add `FLOW_AUTO_OK`.
+
+`auto-merge | repair | halt | blocked | needs-operator`
+
+| Decision | When |
+|---|---|
+| **auto-merge** | Tier-A: card built, review green, verify-live passed, no security-class concern |
+| **repair** | Tier-B: review/verify fixable; first repair = debugger if present else inline + fresh scoped brief; deadlock then USABLE Codex then Antigravity |
+| **halt** | Tier-C, hard-stop cap, parallel merge conflict, or security DEBT needed |
+| **blocked** | Child report missing `STATUS` (treat as BLOCKED), or `STATUS: BLOCKED`/`NEEDS_CONTEXT` that more context cannot resolve |
+| **needs-operator** | Two-strikes with no USABLE cross-vendor engine, or work the parent must not auto-act |
+
+Child complete = worker report. Parent still runs `flow.sh check`. Child `STATUS: DONE` is not a card pass. Runner does not parse `STATUS`. Missing last-line STATUS → parent BLOCKED.
+
+```
+summary: C-012 checkout live 200
+evidence: cards/C-012.md; curl -sS https://app.example/api/checkout -> 200
+nextSteps: parent runs flow.sh check C-012
+blocker:
+STATUS: DONE
+```
+
+## Default-deny (no scoped subagents)
+
+Hosts that cannot spawn a scoped subagent with an isolated brief (Flash and similar) must not run `/flow auto`. Use `/flow next` + `/flow check`. Default-deny. Absence of scoped subagents never lowers a gate.
+
 ## Tiers (decide per card before acting)
 
 | Tier | What | Action |
 |---|---|---|
 | **A** | Card built, review green, verify-live passed, no security-class concern | **Auto-merge without asking.** Log PR URL + merged SHA in `AUTO-LOG.md`. |
-| **B** | Built but review found fixable issues, or verify ambiguous | First repair = **`Task(subagent_type="debugger")`** with scoped brief (task + card + test output + acceptance; no session history). If `debugger` is absent, degrade to inline root-cause + fresh same-ladder (Claude) subagent. If THAT repair is still red — the **two-strikes deadlock** — THEN try the next USABLE cross-vendor engine: **Codex** (`codex:codex-rescue`) first, then **Antigravity/Gemini-3** (`antigravity-integration.md`) if Codex is unusable or also red; else escalate to operator. (A cross-vendor engine may come in earlier ONLY on a security-class card or explicit operator opt-in — the cost gate. Do NOT call a billable engine on the first red of an ordinary card.) |
+| **B** | Built but review found fixable issues, or verify ambiguous | First repair = **debugger if present else inline + fresh scoped brief** (task + card + test output + acceptance; no session history). If THAT repair is still red — the **two-strikes deadlock** — THEN try the next USABLE cross-vendor engine: **Codex** (`codex:codex-rescue`) first, then **Antigravity/Gemini-3** (`antigravity-integration.md`) if Codex is unusable or also red; else escalate to operator. (A cross-vendor engine may come in earlier ONLY on a security-class card or explicit operator opt-in — the cost gate. Do NOT call a billable engine on the first red of an ordinary card.) |
 | **C** | Security-class touch (auth, authorization, admin exposure, tenancy, payments, data migration, removing validation) OR a debt skip | **HALT.** Operator must accept the exposure in writing in `DEBT.md`. Never planner-decided. |
 
 ## Loop per card (serial by default; parallel only when `/flow ready` says safe)
@@ -25,6 +54,9 @@ for each todo card in card-number order:
      [records: flow harness graph record --execution "$(flow.sh harness graph session)" \
                  --ns card:C-NNN --node card-review --interrupt --security-class]
   1. spawn ONE scoped subagent (agent-stage-mapping.md) in its own worktree
+     spawn-not-fork: the brief is whole context (no session history).
+     Child MUST NOT resolve Tier-C, write DEBT, skip a gate, or merge. Parent still `flow.sh check`.
+     Docs-only; runner does not refuse child `debt`/`skip`.
      /flow workspace add card/C-NNN --card C-NNN     [records: card-dispatch]
      (a raw `git worktree add` records NOTHING — use the verb, or the journal has a hole)
   2. agent builds to contract, touches only allowed files, runs ## Verify for real
@@ -32,12 +64,10 @@ for each todo card in card-number order:
       gate/step boundaries — the next `check` is what proves it]
   3. review the diff (code-reviewer or bmad-code-review 3-layer; see adversarial-review.md).
        On a security-class card, add a USABLE cross-vendor lens (Codex, and/or Antigravity/Gemini-3).
-       red (strike 1) -> repair: spawn Task(subagent_type="debugger") with a SCOPED BRIEF
+       red (strike 1) -> repair: debugger if present else inline + fresh scoped brief
          (task + failing card file + test output + ## Verify acceptance; NO session history).
-         Debugger diagnoses root cause and returns a fix recommendation or revised implementation.
-         Degrade rung: if `debugger` is ABSENT in the host, run inline root-cause analysis then
-         spawn a FRESH same-ladder (Claude) subagent for the redraw. A missing `debugger` changes
-         WHO diagnoses, never whether ## Verify + flow.sh check must pass for real.
+         Diagnose root cause and return a fix recommendation or revised implementation.
+         A missing `debugger` changes WHO diagnoses, never whether ## Verify + flow.sh check must pass for real.
        still red (strike 2 / deadlock) -> Codex fresh-engine repair if USABLE, then Antigravity if
          USABLE, else escalate
        green -> continue

package/skills/flow/references/clarify.md

@@ -17,7 +17,7 @@ Does **not** replace:
 - `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
+- `gate-shared.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.
@@ -33,10 +33,10 @@ run the stage's semantic challenge.
 - 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.
+do not count). **More than 5 markdown bullets under `## Open decisions` fails
+`scan_gate`.** Leftover `- [ ]` still fails boxes. If the section is a pile after
+that floor, assume or cut rather than interview everything. Offer this ritual
+(opt-in, never a `next` prereq) when any open decision remains. See `gate-shared.md`.
 
 ## Token rules (authoring, before this ritual)
 
@@ -46,7 +46,7 @@ When drafting 02 / 03 / 05 (especially in `mode work`):
 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
+   do not invent one (`gate-shared.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
@@ -166,7 +166,7 @@ Read `## Assumptions` on the artifact you just touched. For each bullet:
   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
+  **stop** and list it the same way `gate-shared.md` material-authority stop
   does. Do not silently keep it.
 
 A clean mechanical gate with a sneaky assumption is the exact hollow-pass this

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

@@ -1,60 +1,60 @@
 # Command dispatch
 
-Exact mapping: user input -> runner call -> your (Claude) duties. Always run the runner
+Exact mapping: user input -> runner call -> host duties. Always run the runner
 first, relay its output faithfully, then do the semantic part. `<skill>` = this skill's
 install dir; run from the project root so `flow/` and `cards/` resolve.
 
-| User input | Runner call | Your duties after |
+Seekable: `#verb-next`, `#verb-card` (humans). This file is still loaded whole — there
+is no fragment loader (ADR-0001).
+
+| User input | Runner call | Host duties after |
 |---|---|---|
-| `/flow` | `bash <skill>/runner/flow.sh status` | Runner now prints its own `NEXT ->` line (same helper as `resume`) plus stage dwell and, past 10 cards, a compact done/in-flight/todo summary. Relay it; nothing to author. |
-| `/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) / 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. |
-| `/flow gate <stage>` (or `--card C-NNN`) | `bash <skill>/runner/flow.sh gate <stage\|--card C-NNN>` | Read-only mechanical scan (unchecked boxes + `[FILL]`) with NO unlock, NO template copy, NO durable writes — the only flow.sh verb the graph executor runs from topology `cmd` position. Relay findings; `next`/`check` still own real progression + durable hooks. |
-| `/flow contract` | `bash <skill>/runner/flow.sh contract` | After the contract gate / before UI cards (web): flags client base-URL vs served-path prefix drift (double-`/api`, mixed-prefix) — the class spec-diff tools miss. Advisory; confirm on the running app. |
-| `/flow tokens` | `bash <skill>/runner/flow.sh tokens` | On/after UI cards: flags DESIGN.md tokens the CSS never uses + VALUE mismatches (same name, drifted value) + orphan CSS vars (info). Advisory; if the swap is intentional, record a dated DESIGN.md amendment. |
-| `/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** (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. |
-| `/flow debt add\|list` | `bash <skill>/runner/flow.sh debt add\|list` | Record/list deliberate gate-skips in `DEBT.md`. Security-class debt is operator-authored only; surface it at retro and before any real user touches the surface. |
-| `/flow design <file>` | `bash <skill>/runner/flow.sh design <file>` | Mechanical DESIGN.md check on a UI file (emoji / `{{}}` / engine-words / gradient). Advisory; pair with the semantic `design-review-checklist.md` for mock/frontend cards. |
-| `/flow harness <args>` | `bash <skill>/runner/flow.sh harness <args>` | Passthrough to the durable-layer CLI (intake/story/trace/decision/backlog/query). Visible output + real exit code. Use to write the durable hook after a stage/card; read it back with `recall`. |
-| `/flow doctor` | `bash <skill>/runner/flow.sh doctor` | Environment/install self-check (bash/python/grep/git across macOS/Linux/Windows, runner path, Git Bash). Relay any FAIL as the fix list. Read-only. |
-| `/flow promote <file>` | `bash <skill>/runner/flow.sh promote <file>` | Copy a hard-won playbook into the cross-project KB (`~/.claude/flow/playbooks`) so its lesson is surfaced by `recall` in every project, not just this one. |
-| `/flow mode teach` | `bash <skill>/runner/flow.sh mode teach` | Confirm; you only gatekeep, operator authors. |
-| `/flow mode work` | `bash <skill>/runner/flow.sh mode work` | Interview once, draft 00-05, pause for scope sign-off, deliver card set; still pass every gate. |
-| `/flow ready` | `bash <skill>/runner/flow.sh ready` | Relay buildable cards; confirm allowed-files truly don't overlap before suggesting parallel. Operator dispatches. |
-| `/flow workspace <verb>` | `bash <skill>/runner/flow.sh workspace add\|list\|enter\|remove\|check\|doctor [...]` | Multi-agent worktree isolation (human-driven, cross-vendor). Relay the runner output faithfully: on `add`, hand the operator the printed cd/env block (one worktree per agent — Claude `--worktree`/`-w`, Codex CLI manual + `CODEX_HOME`, Antigravity = open the dir as a workspace); on `check`/`doctor` exit 1, surface the collision/drift, don't auto-`--force` a `remove`. git is the source of truth; the `.flow/workspaces.jsonl` side-file only adds vendor/card/port/task. Advisory — not a `next` gate. |
-| `/flow auto` | `bash <skill>/runner/flow.sh auto` | On preflight PASS (risk + Stage 05 receipt), shared auto-state is active — drive the autonomous run per SKILL.md AUTO principles + `attestations.md`. |
+| `/flow` | `bash <skill>/runner/flow.sh status` | Relay prose `NEXT ->`, dwell, and (past 10 cards) the compact summary; nothing to author. Optional `status --json` prints one `flow_context/v1` object (`v,stage,gate,next_verb,card,dwell,load`) — **display-only**. Hosts MUST NOT dispatch `next_verb` (`next`/`card`/`card-start`/`check`/`fix-gate`/`auto`/`skip`). Default `/flow` stays prose status. |
+| `/flow resume` | `bash <skill>/runner/flow.sh resume` | Read-only session-story; no lock. Optional `resume --json` same closed schema as status; display-only, never exec `next_verb`. FAIL/PASS/Never: SKILL.md STOP + Dispatch. |
+| `/flow next` | `bash <skill>/runner/flow.sh next` | After PASS, compare to `gate-examples.md` (not a second always-on load). FAIL/Never: SKILL.md STOP + Dispatch. |
+| `/flow assess` | `bash <skill>/runner/flow.sh assess` | Fill `flow/00-inspect.md` from EVIDENCE; Brownfield challenge in `gate-rules.md`. |
+| `/flow card` | `bash <skill>/runner/flow.sh card` | Fill per `law/CLAUDE.md`; before coding, `law/CODING.md`. |
+| `/flow card start C-NNN` | `bash <skill>/runner/flow.sh card start C-NNN` | Optional in-flight mark (`cards/.inflight`); does not touch gated `status:`. |
+| `/flow card done C-NNN` | `bash <skill>/runner/flow.sh card done C-NNN` | CLI `done` under the same rules as `check`; then semantic review. |
+| `/flow check C-NNN` | `bash <skill>/runner/flow.sh check C-NNN` | After PASS, semantic card review (`law/CLAUDE.md`). FAIL/Never: SKILL.md STOP + Dispatch. |
+| `/flow gate <stage>` (or `--card C-NNN`) | `bash <skill>/runner/flow.sh gate <stage\|--card C-NNN>` | Read-only mechanical scan; relay findings. `next`/`check` own progression. |
+| `/flow contract` | `bash <skill>/runner/flow.sh contract` | Advisory client base-URL vs served-path drift; confirm on the running app. |
+| `/flow tokens` | `bash <skill>/runner/flow.sh tokens` | Advisory DESIGN.md token unused/mismatch; dated amendment if intentional. |
+| `/flow coherence` | `bash <skill>/runner/flow.sh coherence` | Advisory version-field drift; semantic contradictions stay a human challenge. |
+| `/flow consistency` | `bash <skill>/runner/flow.sh consistency` | Advisory PRD FRn coverage; then `gate-rules.md` cross-artifact passes. |
+| `/flow constitution` | `bash <skill>/runner/flow.sh constitution` | Advisory constitution form + markers; then `gate-rules.md`. Not a `next` gate. |
+| `/flow clarify` | `bash <skill>/runner/flow.sh clarify` | List leftover Open-decision boxes; write-back `references/clarify.md`. Not a `next` gate. |
+| `/flow converge` | `bash <skill>/runner/flow.sh converge [--file <payload>]` | Assess vs plan per `references/converge.md`; present the findings table first. |
+| `/flow eval [--stage 01\|02\|05\|card] [--fixture <id>] [--n 3] [--timeout <s>]` | `bash <skill>/runner/flow.sh eval [...]` | Billable; live mode skips if `claude` absent. `--replay` does not inherit that SKIP. See `references/gate-eval.md`. |
+| `/flow eval --report` | `bash <skill>/runner/flow.sh eval --report` | Offline; relay last complete batch + drift. See `references/gate-eval.md`. |
+| `/flow eval --replay` | `bash <skill>/runner/flow.sh eval --replay` | Keyless replay; missing/stale fixtures exit 1. Verdicts never count toward the eval floor. |
+| `/flow project-type <web\|cli\|library\|skill>` | `bash <skill>/runner/flow.sh project-type [t]` | Set/read type per `references/project-types.md`. Confirm before planning. |
+| `/flow usage [--global\|--prune]` | `bash <skill>/runner/flow.sh usage [...]` | Relay local JSONL analytics; `--prune` caps the log. Nothing to author. |
+| `/flow skip <stage> --reason ...` | `bash <skill>/runner/flow.sh skip <stage> --reason ...` | Advance only with matching `DEBT.md`. Security-class: operator-only HALT. |
+| `/flow debt add\|list` | `bash <skill>/runner/flow.sh debt add\|list` | Record/list skips in `DEBT.md`. Security-class is operator-authored only. |
+| `/flow design <file>` | `bash <skill>/runner/flow.sh design <file>` | Advisory DESIGN.md mechanical check; pair `design-review-checklist.md` for UI cards. |
+| `/flow harness <args>` | `bash <skill>/runner/flow.sh harness <args>` | Passthrough to the durable-layer CLI; visible output + real exit. Use `recall` to read back. |
+| `/flow doctor` | `bash <skill>/runner/flow.sh doctor` | Relay FAIL as the fix list. Read-only. |
+| `/flow promote <file>` | `bash <skill>/runner/flow.sh promote <file>` | Copy playbook into `~/.claude/flow/playbooks` for cross-project `recall`. |
+| `/flow mode teach` | `bash <skill>/runner/flow.sh mode teach` | Confirm; host gatekeeps, operator authors. |
+| `/flow mode work` | `bash <skill>/runner/flow.sh mode work` | Interview once, draft 00-05, pause for scope sign-off; same gates. See `references/mode-work.md`. |
+| `/flow ready` | `bash <skill>/runner/flow.sh ready` | Relay buildable cards; operator dispatches. Confirm allowed-files don't overlap. |
+| `/flow workspace <verb>` | `bash <skill>/runner/flow.sh workspace add\|list\|enter\|remove\|check\|doctor [...]` | Relay worktree isolation output; don't auto-`--force` a `remove`. Advisory. |
+| `/flow auto` | `bash <skill>/runner/flow.sh auto` | Load `references/auto-run.md`. |
 | `/flow auto stop` | `bash <skill>/runner/flow.sh auto stop` | Clear auto policy; return to warning-only manual path. |
-| `/flow attest …` | `bash <skill>/runner/flow.sh attest semantic\|live-verify\|status\|recover …` | Mint/inspect receipts. Must-ask before mint/recover; `attest status` is read-only. |
-| `/flow recall` | `bash <skill>/runner/flow.sh recall` | Read back prior knowledge (open debt, recent retro, previous-card scope, harness friction/backlog, playbooks). Run at the START of a stage/card; apply it, don't re-learn known pain. |
-| `/flow unlock` | `bash <skill>/runner/flow.sh unlock` | Clear this project's concurrency lock after a crashed/abandoned session. Confirm the other session is really gone first. |
-| `/flow retro` | `bash <skill>/runner/flow.sh retro` | Ask the 3 questions; the operator writes the RETRO.md line — never you. |
-
-## Behavioral invariants (all commands)
-1. The runner's exit code is ground truth. Don't override it with optimism.
-2. In `teach` mode never tick a box or write an artifact for the operator.
-3. Never set a card `done` without pasted world-state evidence.
-4. Read any file the runner just created before editing it.
-5. Never edit `_templates/` or `runner/flow.sh` during a project run.
-6. Relay failures verbatim (line numbers included) — they are the operator's to-do list.
-7. If the runner reports BLOCKED by another session's lock, STOP and coordinate — never `FLOW_FORCE` past a live session; concurrent runs corrupt the plan. Set `FLOW_SESSION_ID` per session for hard protection.
-8. At the start of a stage or build card, run `/flow recall` first — its output (prior debt / retro / friction / previous-card scope) is context to apply, not noise. `status` shows a one-line memory summary; `card` injects the previous card's scope automatically.
+| `/flow attest …` | `bash <skill>/runner/flow.sh attest semantic\|live-verify\|status\|recover …` | Mint/inspect receipts (`references/attestations.md`). Must-ask before mint/recover. |
+| `/flow recall` | `bash <skill>/runner/flow.sh recall` | Read back prior knowledge; apply at start of a stage/card. |
+| `/flow unlock` | `bash <skill>/runner/flow.sh unlock` | Clear lock after crashed session. Confirm the other session is gone first. |
+| `/flow retro` | `bash <skill>/runner/flow.sh retro` | Ask the 3 questions; operator writes RETRO.md (`law/RETRO.md`). |
+
+## verb-next
+
+Table row `/flow next`. After mechanical PASS, `gate-examples.md` (examples; not a second always-on file).
+
+## verb-card
+
+Table row `/flow card`. Fill per `law/CLAUDE.md`; before coding, `law/CODING.md`.
 
 ## Install-path note
-- Project install: `bash .claude/skills/flow/runner/flow.sh <cmd>`
-- Global install: `bash ~/.claude/skills/flow/runner/flow.sh <cmd>`
-- Override project root: `FLOW_PROJECT_ROOT=/path bash <skill>/runner/flow.sh <cmd>`
+
+SKILL.md "Run `flow.sh` first". Windows: `<skill>\runner\flow.cmd <cmd>` (not bare `bash`).

package/skills/flow/references/concierge.md

@@ -10,16 +10,18 @@ ask routes through this loop before you consider typing a verb for the operator.
 
 1. On any natural-language ask, run `flow.sh status` first (or `resume` when entering a
    project cold mid-cycle — see SKILL.md dispatch rule 1). **Never guess state.**
-   `status`/`resume` output is human-readable prose, not a machine token contract — you
-   (the model) parse it. Reliable on Claude; treat routing on other engines (Codex,
-   Antigravity/Gemini) as best-effort, not guaranteed.
+   Default `status`/`resume` is human-readable prose. Optional `--json` is **display-only**:
+   `next_verb` is not executable. Hosts MUST NOT dispatch `next`, `card`, `card-start`,
+   `check`, `fix-gate`, `auto`, or `skip` from it. Concierge stays on prose (May-run);
+   do not switch the chat entry to `status --json`. Reliable on Claude; treat routing on
+   other engines (Codex, Antigravity/Gemini) as best-effort, not guaranteed.
 2. Look up the closest `intent-class` row in `flow-catalog.tsv` for the parsed state.
 3. Propose exactly **ONE** next action in plain language. Explain any gate concept in
    one short sentence the first time it comes up (zero-jargon default — assume the user
    has never read a flow doc).
 4. Offer to run it now, using the May-run / Must-ask classification below. A typed verb
    from the operator always wins — never intercept or reinterpret an explicit
-   `/flow <verb>` command; dispatch it exactly as SKILL.md's Commands table says.
+   `/flow <verb>` command; dispatch it exactly as the `command-dispatch.md` verb row says.
 
 ## New-user consent (teach-mode boundary)
 
@@ -90,7 +92,7 @@ gate discipline exists to prevent.
 - One proposal at a time — never dump the full verb list on someone who just wants to
   chat.
 - Power-user verbs pass through untouched: a typed `/flow next` dispatches exactly as
-  SKILL.md's Commands table describes, with zero concierge interpretation.
+  the `command-dispatch.md` verb row describes, with zero concierge interpretation.
 
 ## First-run script (new-user acceptance path)
 

package/skills/flow/references/debt-and-halts.md

@@ -17,8 +17,9 @@ Line shape:
 ## Security-class skips (never silent, never planner-decided)
 auth · authorization · admin-surface exposure · tenancy · payments · data loss/migration ·
 removing/weakening validation.
-- The OPERATOR explicitly accepts the exposure, in writing, in the DEBT line. You do not
-  decide it for them.
+- The OPERATOR explicitly accepts the exposure, in writing, in the DEBT line. The host does not
+  decide it for them. Children MUST NOT resolve Tier-C, open/close DEBT, or skip — parent/operator
+  only. Docs-only; the runner does not refuse child `debt`/`skip` this wave.
 - In `/flow auto` this is a **Tier-C HALT** — stop and ask.
 - Closing a run with open security debt requires explicit operator acknowledgment.
   "Temporary" is one forgotten step from production.
@@ -35,9 +36,23 @@ A run HALTS and reports — never silently continues — on any of:
 - A Tier-C security-class touch. (above)
 - A merge conflict during parallel builds (the allowed-files overlap check was gamed —
   stop and re-plan). (`auto-run.md`)
-- `BLOCKED` / `NEEDS_CONTEXT` from a subagent that more context can't resolve.
+- `BLOCKED` / `NEEDS_CONTEXT` from a subagent that more context can't resolve, or a child report missing `STATUS` (treat as BLOCKED).
 
-On halt: state what stopped it, what's done so far, the open debt/blocker, and the 2-4
-concrete options for the operator. Let them decide — don't patch around a regression.
+## Halt report template
+
+On halt, emit this block (docs contract; runner does not parse it):
+```
+whatStopped: <cap | red-after-two-strikes | Tier-C | merge-conflict | child-BLOCKED>
+doneSoFar: <cards/stages complete>
+openDebtOrBlocker: <DEBT line or child blocker>
+options:
+1. <operator accepts exposure in DEBT.md>
+2. <re-plan / shrink the card>
+3. <repair with a fresh scoped brief>
+4. <stop the run (`flow auto stop`)>
+see auto-run.md AutoDecision
+STATUS: BLOCKED
+```
+Let the operator pick — don't patch around a regression.
 
 See also: `references/attestations.md` for security-class **risk-ack** auto contract (v0.28).

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

@@ -0,0 +1,10 @@
+## Stage 00 — Idea
+Mechanical: pitch present, one real person named, no FILL.
+**Challenge:** Is the pitch really 3 sentences (who / pain / what)? Is the named person a
+*real, specific* person or group ("my uncle's 20-unit building"), not "people who..." or
+"users"? Is the pain concrete, not a category?
+- **Offer the forge-idea ritual (opt-in-with-prompt — `native-rituals.md`'s sibling
+  `references/forge-idea.md`).** Before drafting the pitch, or when the operator sounds
+  unsure, offer to pressure-test the idea through persona interrogation until it
+  hardens, proves out, or dies cheaply. Never auto-fired; never a condition this gate
+  checks for — a killed idea and a hardened idea both still go through the normal gate.