@manhquy/flow-skill 0.1.0-rc.1

package/skills/flow/references/claudekit-skills.md

@@ -0,0 +1,128 @@
+# claudekit skills — the per-stage capability map (the seam)
+
+`/flow` already orchestrates claudekit at the **agent layer** (`agent-detection.md` +
+`agent-stage-mapping.md`: 13 ck: agents, ck:→bmad→built-in degrade). This file extends that
+same seam to the **skill layer** — the curated set of ck *skills* worth reaching for at each
+stage, beyond the wired agents. It is a **whitelist, not a dump**: the kit has ~87 skills and
+~60% are marketing/content noise for a build harness. Only the skills below ever get surfaced.
+
+This is the single source of truth for the skill map; `agent-stage-mapping.md` points here.
+
+## The two rules that bind every skill suggestion
+
+1. **A skill INFORMS a stage; the gate JUDGES it.** Same as the Codex/Antigravity rule
+   (`agent-detection.md`, `codex-integration.md`): a skill's output feeds your triage — it
+   **never auto-passes and never auto-fails** a gate. The `flow.sh` exit code + the
+   `gate-rules.md` challenge remain the only deciders. A skill that "looks good" is not a PASS.
+2. **Detection is Claude-side, and degrades silently.** You already know the host Skills list
+   (the available-skills registry) — check it; do not assume. `flow.sh` **cannot** see which
+   skills are loaded (bash has no view of the registry, and the 5 install homes — Claude,
+   Codex, Antigravity ×2, project — differ), so skill detection is never put in the runner. A
+   missing skill **never lowers a gate** — it only changes whether the enrichment is offered.
+   Rich where the skill exists, unbroken where it doesn't.
+
+## Cost gate — offer, don't impose
+
+The high-value skills below are **opt-in-with-prompt**: at the matching gate you *offer* the
+skill and the operator confirms — you do not auto-fire it on every stage (the constitution /
+Codex cost-gate discipline: advisory, off the hot path, no token-tax on trivial work). Skip the
+offer on a trivial decision/card. Never wire a skill into `cmd_next`/`cmd_check`.
+
+## The whitelist — what to use when
+
+Each skill is pinned to the stage where it pays off and the **distinct verb** it adds beyond the
+already-wired agent. Pure skill/agent twins are deliberately absent (see "Don't surface").
+
+| Skill | Stage | Distinct verb it adds (why it's not a twin) |
+|---|---|---|
+| **ck-predict** | ADR (04) | 5-persona pre-decision debate — no agent equivalent |
+| **ck-scenario** | Scope/PRD/**Contract** (02–05) | 12-dimension edge-case → acceptance criteria + contract tests |
+| **repomix** | Assess | packed single-file repo snapshot for LLM context |
+| **ck-graphify** | Assess/Build | queryable knowledge graph (code+docs) for impact analysis |
+| **review-pr** | Review/Ship | PR-context review: AI-slop, CI-blocker, breaking-change, `--fix` |
+| **ck-security** | Review (security-class cards) | STRIDE+OWASP threat-model with attacker personas |
+| **security-scan** | Review/Deploy | mechanical secrets/deps/OWASP scan (tip-level, cheap) |
+| **retro** | Retro | git-history numeric retrospective (vs narrative journal) |
+| **xia** | Research/Build | port/compare/adapt a feature from another repo |
+| **ghpm** | Verify/Deploy | bind work to GitHub Issues/Projects/CI status |
+| **deploy** | Deploy | platform auto-detect publish |
+| **web-testing** | Verify-live | Playwright/k6 e2e/load/a11y (distinct from `tester` unit verb) |
+| **docs-seeker** | Research/Build | fetch current library docs (llms.txt/context7) — version-drift guard |
+| **scout** | Assess/any | fast parallel file discovery (distinct from inline read) |
+| **ck-loop** | Build/Verify (Implement→Test→Audit→Fix) | mechanical iterate-to-numeric-target with per-iteration git commit/revert — the loop-engineering primitive flow lacked natively |
+
+> Graph tool: **ck-graphify** is the chosen impact-analysis tool (operator decision, 2026-06-23
+> — polyglot/doc-heavy brownfield fit, e.g. CMC Odoo). `gkg` is NOT wired; do not surface both.
+
+## The 6 deep-wired skills (offered inside the gate ritual)
+
+These are wired into the per-stage prose because each sits at a gate where a miss is most
+expensive and adds a verb no wired agent provides. **Wired ≠ required**: each is offered
+(opt-in-with-prompt), degrades silently, and only informs the gate. Wiring locations:
+ck-predict/ck-scenario → `gate-rules.md` (stages 04/05); review-pr + ck-security →
+`adversarial-review.md` (the Review gate); retro → `law/RETRO.md`; ck-loop → the Build/Verify
+tail, plumbing via `flow.sh loop-prep`/`loop-log` (this file).
+
+1. **ck-predict @ ADR** — before locking a non-trivial architecture decision, offer a 5-persona
+   debate. Catches arch/security/perf/UX defects when reversal is cheapest. Output informs the
+   ADR challenge; it does not pass it.
+2. **ck-scenario @ Contract** (and Scope/PRD) — offer 12-dimension edge-case decomposition to
+   harden the seam (`flow/05-contract.md`): the cases become acceptance criteria + the per-type
+   no-drift checks. Complements `/flow consistency` (it *generates* cases; consistency checks
+   *coherence*).
+3. **review-pr @ Review/Ship** — when the change lives as a GitHub PR, offer PR-context review
+   (AI-slop, CI-blocker, breaking-change) on top of the wired `code-reviewer` diff review.
+4. **ck-security @ security-class cards** — on the exact card class flow already halts at
+   (auth, authz, tenancy, payments, data migration, removing validation), offer a STRIDE+OWASP
+   threat-model. It informs; the **Tier-C operator HALT is never auto-passed** by a clean scan.
+5. **retro @ Retro** — offer a git-history numeric retrospective so the Retro line is backed by
+   real commit/velocity numbers, not prose.
+6. **ck-loop @ Build/Verify (Implement→Test→Audit→Fix tail)** — when a fix needs more than one
+   experimental attempt against a single numeric target (failing-test count, lint errors, etc.),
+   offer `flow.sh loop-prep <card>` to set up an isolated worktree + Verify/Guard commands, then
+   invoke the `ck-loop` skill with the printed block (ck-loop stays the untouched execution
+   engine — flow supplies plumbing only). See "Loop vs two-strikes" below for when to reach for
+   this instead of the default repair path. The finished run is recorded via `flow.sh loop-log`
+   (NOT the `intervention` channel below — recording it twice would double-count the same event).
+
+## Loop vs two-strikes — the one "fix it" decision tree
+
+flow already has a bounded repair mechanism (two-strikes: one fresh-subagent repair attempt on a
+review deadlock, then escalate to a cross-model lens — `adversarial-review.md`). `ck-loop` is a
+different tool for a different situation; do not let operators reach for the wrong one:
+
+| Situation | Use | Why |
+|---|---|---|
+| Review BLOCKED twice, same model, no metric | two-strikes → cross-model lens | bounded disagreement, not a number |
+| One numeric verify command, needs >1 experimental attempt | `flow.sh loop-prep` + ck-loop | open iterate-to-target, git-tracked/revertable |
+| Drive failing-tests / lint / perf count to a threshold | ck-loop | Verify is a single number; Direction lower |
+| Single obvious fix, one retry | default auto repair | cheaper than spinning up a worktree+loop |
+
+## Don't surface (cut on purpose — these add noise, not signal)
+
+- **Skill/agent twins** — the wired agent already covers these; surfacing the duplicate skill
+  doubles the "what do I use" confusion: research/researcher, ck-code-review/code-reviewer,
+  ck-debug/debugger, test/tester, git/git-manager, ck-plan/planner, docs/docs-manager,
+  journal/journal-writer, ask, brainstorm. Prefer the **agent** for in-stage execution; reach
+  for the skill only for a distinct verb the agent lacks (already captured above).
+- **Competing orchestrators (cook, vibe, ship, bootstrap)** — each is its own end-to-end
+  pipeline with its own gates; invoking one inside a flow stage double-gates and fights flow's
+  stage authority. Cherry-pick a sub-step (e.g. ship's merge/PR) at the matching stage only.
+- **`worktree` skill** — flow already ships `flow.sh workspace` (git-worktree-per-agent). Pure
+  duplicate; never wire it.
+- **`bmad-spec` as a gate** — overlaps flow's own `/flow consistency` cross-artifact audit.
+  Keep it only as the optional Contract drafter already named in `agent-stage-mapping.md`.
+- **Marketing/content/media skills** (ads, seo, social, email, video, branding, copywriting,
+  the `ckm:*`/`bmad-*` marketing families, cti-expert) — never relevant to a build gate.
+- **Stack adapters** (backend/frontend/db/auth/payment/mobile/ui-* …) — surface only via
+  `playbooks/<stack>.md` by project-type, never as a flat global menu.
+
+## Lazy capture (ON — only at the 5 wired gates)
+
+Skill-invocation telemetry is **enabled, lazily**: after a deep-wired skill runs at its gate,
+record the use via the existing `flow.sh harness intervention add` (the same durable-metric
+channel the Codex/Antigravity lenses use — `adversarial-review.md` §S2). **Only at the 5 wired
+gates** — never on every skill, never on the `cmd_next`/`cmd_check` hot path, no new runner verb.
+Note whether the skill caught a class the wired agent missed; that signal lets a later phase rank
+the whitelist by what this operator actually reaches for (the `accessed_count` signal flow already
+uses). The whitelist stays hand-curated until then.

package/skills/flow/references/codex-integration.md

@@ -0,0 +1,104 @@
+# Codex — cross-vendor second engine (the seam)
+
+`/flow` reaches OpenAI **Codex (GPT-5.x)** through the `openai-codex` Claude Code plugin
+(detected, never required). Codex is a *second engine*, not a replacement for the ck:→bmad→
+built-in ladder: a genuinely different model used at the moments where that is worth more than
+another Claude pass. This file is the single source of truth for the seam; `agent-detection.md`
+(detection + priority), `agent-stage-mapping.md` (per-stage use), `adversarial-review.md`
+(cross-model review), and `auto-run.md` (Tier-B escalation) point here for the shapes.
+
+## Why a second vendor (the measured gap)
+
+A single-vendor harness makes the builder and the reviewer share one model → correlated blind
+spots pass green gates (this project's own review-pass-#4 caught an auth-skip a same-model pass
+missed — `docs/quality-metrics.md`). Cross-model review empirically catches markedly more (a
+gemini-cli study: single-model review 43% merge-ready vs cross-model iteration 91%). A different
+engine is the cheapest way to close a same-vendor gate without weakening any gate.
+
+## Detection (I1) — two states: INSTALLED vs USABLE (never route on "installed" alone)
+
+Detection has **two states**, because "installed" does not mean "works" — a plugin can be present
+with no valid auth (common in headless/CI — see Codex issue #9253) or a broken companion script.
+Routing into Codex on mere presence would spend a billable repair/review attempt and then fail at
+invocation — that violates "absence never breaks a run". So:
+
+- **INSTALLED** — `codex:codex-rescue` is in the host agent registry, OR the plugin dir exists
+  (`~/.claude/plugins/cache/openai-codex` / `.../marketplaces/openai-codex`). Necessary, not sufficient.
+- **USABLE** — INSTALLED **and** a cheap, non-billable liveness/auth check passes:
+  `codex-companion.mjs setup --json` reports `ready === true` AND `auth.loggedIn === true`
+  (or a confirmed prior successful Codex call this session). Run this check **before the first
+  time** you would route work to Codex. NOTE: use `setup --json`, NOT `status` — `status` reports
+  runtime/job state but carries **no auth field**, so it passes even when Codex is unauthenticated
+  (it would route then fail at the real call). `setup --json` is the auth-aware, non-billable probe.
+
+**Selection rule:** only select the Codex tier when state = **USABLE**. If INSTALLED-but-not-USABLE
+(or absent): **degrade** to ck:→bmad→built-in, announce `"codex tier unavailable (installed but
+not authenticated / not reachable) — degraded to <path>"`, and record the reason (durable metric).
+Never select Codex on INSTALLED alone. Degrading is silent-but-announced, never an error, never a
+gate change. Downstream docs (`agent-detection.md`, `auto-run.md`, `adversarial-review.md`) all
+mean **USABLE** wherever they say "eligible".
+
+## Cost gate (F-D) — when Codex is allowed to fire
+
+Codex calls are **billable** external GPT-5.x. Fire them ONLY at high-value moments:
+- a **two-strikes deadlock** (a same-model agent BLOCKED twice),
+- a **security-class card review** (auth/authorization/tenancy/payments/data-migration), or
+- an **explicit operator opt-in** (e.g. "draft this stage on Codex", "/flow ... codex").
+
+Never call Codex on every stage by default. Default engine stays ck:.
+
+## Invocation surfaces (from flow/05-contract.md — do not improvise other shapes)
+
+| Use | Invocation | Effects | Returns |
+|---|---|---|---|
+| **Handoff / rescue / primary-draft** | `Task(subagent_type="codex:codex-rescue", prompt=<ScopedBrief>)` | writes code (`--write` default), billable | stdout + status line |
+| **Cross-model review** | `node "$CODEX/scripts/codex-companion.mjs" review\|adversarial-review [--wait\|--background] [--base <ref>] [--scope auto\|working-tree\|branch] [focus]` | read-only review, billable | `ReviewResult` JSON |
+| **Task (non-interactive)** | `node "$CODEX/scripts/codex-companion.mjs" task [--background] [--write] [--model <m\|spark>] [--effort <none..xhigh>] <prompt>` | writes if `--write`, billable | stdout + job id |
+| **Job control** | `... status [job-id] [--all] [--json]` · `result [job-id] [--json]` · `cancel [job-id]` | read-only / cancel | job/result JSON |
+
+`$CODEX` = the plugin root (`~/.claude/plugins/cache/openai-codex/codex/<ver>`). Prefer the
+`codex:codex-rescue` **subagent** for handoffs (it owns prompt-shaping + foreground/background
+choice); use `codex-companion.mjs` directly only for `review`/`adversarial-review`/job-control.
+
+### ScopedBrief (context isolation — orchestration-protocol)
+Give Codex ONLY: `task` (one goal) · `read_for_context` (contract, law, the card, playbook) ·
+`files_to_modify` (the card's Allowed files ONLY) · `acceptance` (the stage gate / card Verify) ·
+`constraints` (contract is the seam; Vietnamese user-facing copy; touch only allowed files) ·
+`return` (artifact + status). **Never** the session history.
+
+### ReviewResult (verbatim from `schemas/review-output.schema.json`)
+```
+{ verdict: "approve"|"needs-attention", summary: string,
+  findings: [ { severity:"critical"|"high"|"medium"|"low", title, body,
+                file, line_start>=1, line_end>=1, confidence:0..1, recommendation } ],
+  next_steps: [ string ] }
+```
+
+### Status protocol (handoff return)
+`DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT` — handle BLOCKED/NEEDS_CONTEXT before retry.
+
+## Gate parity (absolute) & auth (delegated)
+
+- **Gate parity.** Codex DRAFTS or CRITIQUES; the identical stage gate (`flow.sh` + `gate-rules.md`)
+  still judges. A cross-model review INFORMS triage — it never auto-passes or auto-fails a card.
+- **Auth.** Delegated entirely to the plugin (`codex login` / `OPENAI_API_KEY` / ChatGPT
+  subscription). `/flow` never reads, stores, or logs Codex credentials.
+- **Data boundary (the other half of trust).** Selecting Codex SENDS the ScopedBrief — the source
+  diff plus the contract / PRD / law excerpts — to OpenAI's API, governed by the operator's OpenAI
+  plan and its data-retention/training terms. This is distinct from the credential clause above:
+  even with perfect secret handling, the *code and specs* leave the machine. For a sensitive,
+  regulated, or NDA'd codebase, the operator must opt in knowingly; the cost gate (high-value
+  moments only) keeps the exposure surface small by default.
+
+## Durable metric (S2)
+
+After a Codex tier use, log it so the quality loop can read the trend (no new schema):
+`flow.sh harness intervention add` (e.g. cross-model review found a class same-model missed) or
+`intake` / `decision add`. This is the "thông số" that drives skill upgrades — see
+`docs/quality-metrics.md` (cross-model-catch rate, rescue deflection rate).
+
+## Announce the path
+
+Always tell the operator which engine ran: `"review via Codex cross-model lens (needs-attention,
+2 findings)"` / `"rescue via codex:codex-rescue after two strikes"` / `"codex tier unavailable —
+degraded to code-reviewer"`. A run must stay legible.

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

@@ -0,0 +1,54 @@
+# Command dispatch
+
+Exact mapping: user input -> runner call -> your (Claude) 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 |
+|---|---|---|
+| `/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. 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 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 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 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. |
+| `/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, drive the autonomous run per SKILL.md AUTO principles (subagent/card, planner review, worktree, Tier-C halt on security debt). |
+| `/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.
+
+## 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>`

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

@@ -0,0 +1,41 @@
+# Debt & halts
+
+Reordering or skipping a gate is a legitimate OPERATOR call (demo-first, riskiest-first).
+But a skipped gate is a loan, and loans get written down. (buildflow CLAUDE.md "Debt".)
+
+## The DEBT.md ledger
+Every deliberate skip opens one line (create `DEBT.md` on first use). Use the runner:
+```
+bash <skill>/runner/flow.sh debt add "<what was skipped>" "<the exposure, concretely>" "<close before: named condition>"
+bash <skill>/runner/flow.sh debt list      # open debts
+```
+Line shape:
+```
+- [ ] DEBT: <what was skipped> -- <exposure> -- close before: <named condition> -- opened <date> (cards: C-NNN...)
+```
+
+## 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.
+- 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.
+
+## Close conditions
+Checked at every `/flow retro` and before ANY real user touches the build. A card blocked
+by a debt stays `todo` with PARTIAL evidence naming the debt — never half-done, never
+rounded up to done.
+
+## Halts (when the run stops itself)
+A run HALTS and reports — never silently continues — on any of:
+- A hard-stop cap exceeded (iterations/tokens/wall-clock). (`loop-harness-2026-principles.md`)
+- A red ground-truth signal that can't be repaired in two strikes. (`adversarial-review.md`)
+- 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.
+
+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.

package/skills/flow/references/design-review-checklist.md

@@ -0,0 +1,42 @@
+# Design review checklist (UI cards)
+
+Every mock/frontend card is reviewed against `law/DESIGN.md` the same way backend cards are
+reviewed against the contract. Two parts: a **mechanical** part (`flow.sh design <file>`,
+grep-able, deterministic) and a **semantic** part (you, against DESIGN.md's structure laws).
+
+## Mechanical (run `flow.sh design <htmlfile>` — catches the never-do list)
+Flags, with line numbers:
+- **Emoji** anywhere (DESIGN.md: "No emojis. Anywhere. Ever.").
+- **Raw `{{ }}` templates or visible JSON** outside a power surface.
+- **Gradients on inputs / table rows / body bg** (gradients are hero-surface only).
+- **Engine words** in user-facing copy: workflow, trigger, queue, webhook, agent, prompt,
+  cron, payload, endpoint (users think in THEIR objects, not engine concepts).
+- **Design comments left in HTML.**
+A flag is a strong signal, not always a verdict (an engine word inside a `<code>` sample is
+fine) — you confirm. Exit 1 if any flag fires.
+
+## Semantic (you review against DESIGN.md — the script can't judge these)
+- **Object-first:** the home page of a thing IS the thing; tabs are lenses on one object,
+  not separate features.
+- **WYSIWYG / edit-in-place:** 80% of edits inline on the object page; a separate edit page
+  only for structural 20%. No multi-step wizard for editing.
+- **Defaults beat configuration:** creatable in <=6 visible fields; the rest behind "More options".
+- **Plain language:** "4 days after it ends", a field-picker chip — never cron, never raw templates.
+- **Power behind a door:** any power surface is a `Simple | Pro` toggle that loses no data,
+  with a visible path back to simple.
+- **Affordance ladder:** the field uses the lightest rung its shape allows (inline text ->
+  inline control -> popover composite -> modal). Empty value renders as `+ Add {label}`.
+- **Luma object page:** calm pulse strip (no stat-tile cards), <=3 gradient-tinted hero
+  action cards (one click, no kebab), tabs as lenses, modal-first sub-actions.
+- **Tokens:** Editorial Minimal tokens (or a deliberate, documented, whole-cluster override).
+  Inter body / Fraunces only for h1+titles+prominent stats / JetBrains Mono only for
+  IDs/dates/counts. 1px borders, no stacked shadows.
+- **VN conventions:** Vietnamese native copy, `₫750,000` (symbol leading, comma groups),
+  VietQR as default pay, Zalo as a first-class support channel.
+
+## Process
+1. The UI **mock card** (static HTML, real copy, no logic) IS the design review — render it,
+   operator approves in a browser. Iterate here (mock retries cost seconds; framework retries
+   cost deploys). No frontend code before the mock is approved.
+2. Run `flow.sh design <file>` (mechanical) + this semantic pass on the mock and on every
+   frontend card. A violation blocks the card the same as a failing `## Verify`.

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

@@ -0,0 +1,186 @@
+# Gate eval — behavioral proof for the semantic layer (`flow.sh eval`)
+
+`gate-rules.md` is the semantic layer: after the mechanical gate passes, an LLM applies a
+per-stage challenge and can flag a mechanically-clean artifact as substantively hollow. Until
+this verb existed, nothing measured whether that actually happens — a hollow-but-well-formed
+artifact passes the mechanical gate BY DESIGN (`flow.sh:scan_gate`/`cmd_check`), and the
+semantic layer's only proof was operator trust. `flow.sh eval` runs the real per-stage ritual
+text against curated hollow/sound fixture pairs and majority-votes a nonce-protected verdict,
+so gate erosion (CLI update, model swap, prose edit) shows up as a number, not a vibe.
+
+## What it measures — and the honest limit on what it does NOT
+
+The eval judge is a **fresh** LLM call: it receives the gate-rules.md challenge text plus one
+fixture's content, cold, with no memory of authoring anything. This proves a **necessary, not
+sufficient**, lower bound: if a fresh judge can't catch an obvious hollow artifact when
+explicitly asked to, the semantic layer has failed outright. A green scorecard proves that
+floor holds — it does **not** prove the semantic layer works during a real build.
+
+The gap: in a real `/flow` session, the SAME model that just authored a stage artifact is the
+one applying the challenge to it (`gate-rules.md:11` — "in `work` mode you authored it, so you
+self-challenge before presenting"). That is a self-review, with the sunk-cost/authorship bias a
+fresh judge never has. This eval does not reproduce that condition, and closing that gap is out
+of scope for v1 (recorded design boundary, not an oversight). Read a green scorecard as "the
+rule text is enforceable by *a* judge," not "this build's self-review caught everything."
+
+## Fixtures and thresholds
+
+Six 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 ("merge ≈ shipped" evidence).
+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
+accepts a caller-supplied artifact path; widening that is a v2 change that reopens security
+review (an unvetted artifact reaching an LLM judge is a different trust boundary).
+
+Per fixture, N=3 judge calls (`--n`), majority vote: **healthy = hollow fixtures flagged at
+≥2/3 majority, sound fixtures passed at majority**. More than 1/3 of a fixture's runs coming
+back unparseable/timed-out makes that fixture's result `UNRELIABLE` (an infra failure, reported
+separately from a real mismatch — never silently counted as a gate pass or fail).
+
+## Cost
+
+`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 6 fixtures × N=3 = 18
+judge calls + the 1 probe = 19 calls.
+
+**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
+call**, driven almost entirely by this repo's large global `CLAUDE.md` + skill/agent/MCP
+declarations loading as system-prompt context on every call (~50–60K cache-creation tokens),
+not by the judging prompt itself. A full 19-call baseline batch is real money, order **$6–7**
+on this setup — not the trivial "a token or two" a casual reader might assume from "opt-in".
+Forcing a cheaper model (`--model haiku` on the underlying CLI, not currently plumbed as a flow
+flag) cuts this roughly 5x, but changes what the eval measures (a cheaper, possibly weaker judge)
+and was deliberately left as an operator choice rather than a default, since the point of a
+fresh-judge eval is to reflect a realistic judge, not the cheapest one that passes.
+
+`--report` (below) is the free, offline way to re-read a prior batch's numbers without spending
+anything.
+
+## Running it
+
+```
+flow.sh eval                          # full manifest, N=3 per fixture
+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
+```
+
+Exit code: `0` = every evaluated fixture majority-matched its expected verdict (or a clean
+skip); `1` = any mismatch, any `UNRELIABLE` fixture, or nothing matched the given filters. This
+exit code is **informative only** — it is never wired into `next`/`check` gating. A red `eval`
+run does not block a build; it tells the operator the semantic layer needs attention.
+
+## Results, scorecard, and drift
+
+Every batch appends to `$FLOW_PROJECT_ROOT/.flow/eval-results.jsonl` (per-fixture rows plus a
+`batch:"start"`/`batch:"done"` header/trailer pair). A batch with no trailer — Ctrl-C mid-run,
+the only signal handled is best-effort (see Limitations) — is simply excluded from `--report`
+and drift comparisons; that absence of a trailer IS the completeness signal, not a positive
+"torn" flag. Reruns append a new `run_id`; there is no in-place dedup or pruning (personal
+volume, same stance as the existing global usage-log rotation backlog — documented, not built).
+
+Each result row carries `cli_version` (from `claude --version` — the CLI's own version string,
+**not** a model id) and `model` (the served model id, parsed from the JSON response's own
+`model` field — falls back to `"unknown"` if that source is ever unavailable; the two are kept
+strictly separate so a CLI update is never mistaken for a model swap or vice versa), plus
+`flow_version` and a CRLF-normalized `gate_rules_sha` (so a checkout's line-ending convention
+never produces a false "the rules changed" alarm).
+
+`--report` prints the last complete batch's scorecard (per-fixture MATCH/MISMATCH/UNRELIABLE,
+per-stage hollow-flag-rate/sound-pass-rate) and an advisory drift line against the prior
+complete batch: changes in `cli_version`/`model`/`gate_rules_sha`, plus the per-stage flag-rate
+delta. Drift is advisory text only, never an exit-code signal. If the two compared batches
+evaluated different fixture sets for a stage (e.g. a quick `--fixture`-filtered check against an
+earlier full baseline), the delta is flagged as "not directly comparable" rather than presented
+as a clean number — a shrinking/growing denominator is not the same signal as a judge's answer
+changing. With `model:"unknown"` on either side, drift is explicitly narrowed to the
+`cli_version`/prose axes.
+
+## Why `eval` is not `read_only` in telemetry
+
+`eval` is the only verb that makes billable network calls AND writes a results file
+(`eval-results.jsonl`); every other read-only verb (`status`, `usage`, `doctor`, ...) only reads
+existing state. Marking it `read_only:true` in the standard usage-log would be a telemetry lie,
+so it is deliberately excluded from `_log_is_readonly`'s whitelist. `--report` alone genuinely
+is read-only (zero calls, offline) but is not special-cased in telemetry, since the standard
+event still correctly reflects "a build-affecting command ran" at the `eval`-verb level.
+
+## v2 engine seam (documented, not built)
+
+`_eval_engine_run()` is the single call site that invokes the judge CLI. A second/third engine
+(Codex, Antigravity) would implement the same nonce-in/verdict-out contract behind that one
+function, without touching the fixture loop, majority-vote, or scorecard logic. Not built in v1
+— Claude-only was the approved scope, and no other engine's headless contract has been spiked
+yet (the same "measure, don't assume" discipline that gated this build in the first place).
+
+## Limitations (recorded, not hidden)
+
+- **Fixture authorship bias**: the same people who wrote `gate-rules.md`'s challenges also wrote
+  the fixtures meant to test it. Mitigated by sourcing every hollow fixture's failure mode
+  verbatim from the rule text it's tested against (never an invented taxonomy); residual risk is
+  accepted for v1 and disclosed here.
+- **Interrupt cleanup is best-effort, not guaranteed**, on at least this build's development
+  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 (six)**: 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)
+
+### INVALID storms — the 260710 case
+
+The first real batch after v0.19 shipped came back **17/18 INVALID** (run `…-1783695631-…`). The
+retry doubled cost without recovery — attempt 2 landed in the same window — and the CLI's
+`session-lifecycle-hook cancelled` stderr line, the only diagnostic the storm actually produced,
+was thrown away because the pre-v0.21 seam captured stdout only. A single-call retry cleared the
+window; the mechanism was never confirmed at the time (rate-limit vs hook contention).
+
+**v0.21 changes that make the next storm postmortemable and cost-safe:**
+
+1. **Raw capture on final-INVALID.** Both attempts' stdout, stderr, and rc are persisted to
+   `.flow/eval-raw/<run_id>/<fixture>-v<vote>-a<attempt>.{out,err,rc}` (git-ignored via
+   `_ignore_run_state`; envelope stripped down to `result`/`assistant`/`rate_limit_event`
+   records — cwd, session_id, plugin/memory paths are removed).
+2. **Injectable backoff.** `FLOW_EVAL_RETRY_BACKOFF` env (default 5s) delays the retry so it
+   doesn't hammer the same window. Tests set `0` to keep CI fast.
+3. **Retry skip on rate-limit.** If attempt 1 carried a non-`allowed` `rate_limit_info.status`,
+   the retry is skipped (retry is documented for a *formatting slip*, not infra; retrying into a
+   live rate-limit window just doubles spend).
+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 6 × 3).
+
+### Rate-limit visibility (advisory, best-effort)
+
+The rows persisted after v0.21 gain `retries` (0/1 per fixture) and `rate_limited`
+(`true`/`false` per fixture). `rate_limited` is anchored to the `rate_limit_info` record's own
+`status` value — this is important because on cli 2.1.201 a **healthy** `allowed` event carries
+`"overageStatus":"rejected"` as a separate field in the same envelope, and a naive
+`grep '"status":"' | grep -v allowed` false-positives on it. A genuinely-throttled shape has not
+yet been captured; treat `rate_limited` as best-effort advisory (absence ≠ not-throttled) until a
+real throttled sample is added to the corpus.
+
+### Concurrency caveat
+
+`cmd_eval` takes **no** flow lock (it is a read-mostly verb, and the raw/prune writes are the
+only cross-run writes it does). The pre-batch raw-prune keys off the epoch embedded in `run_id`
+(deterministic, mount-independent, unforgeable by `touch`) and honors a `FLOW_LOCK_TTL`-second
+guard so an in-flight or in-postmortem run's dir cannot be pruned under the operator's feet.
+
+### INVALID-storm playbook
+
+1. If `flow.sh eval` exits `2` and prints `ABORT after first fixture UNRELIABLE`, do NOT rerun
+   without `--keep-going` — read the named `raw capture` dir first.
+2. Attempt-1 `.err` is usually the diagnostic (hook-cancelled / rate-limit line lands there).
+3. If the storm was rate-limit: wait past the window (typically minutes), then rerun.
+4. If persistent: capture the `.err` line in a comment, escalate — this is when a throttled
+   `rate_limit_info` sample would land in the corpus and let `rate_limited` become authoritative.