@manhquy/flow-skill 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to `@manhquy/flow-skill`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/).
 
+## [0.7.0] — 2026-08-14 — ships skill v0.30.0 (discipline-layer identity + CI/eval hardening)
+
+Skill-content release. Ships skill product **v0.30.0**: identity ADR (gates and
+receipts, never the runtime), keyless `eval --record`/`--replay`, pack-rehearsal,
+`all-checks-passed`, macOS live-eval refuse-guard, B1-S `fcdd`/`fcde` (see root
+`CHANGELOG.md` `## 0.30.0`). Installer CLI contract unchanged. Publishes to
+dist-tag **`latest`**.
+
+### Changed
+- Bundled skill tree re-synced from monorepo `skills/flow/`.
+- Install: **`npx @manhquy/flow-skill@latest`**.
+
+## [0.6.0] — 2026-08-13 — ships skill v0.29.0 (spec-kit imports + converge)
+
+Skill-content release. Ships skill product **v0.29.0**: `/flow clarify`, card
+independent-test field, `/flow converge`, converge eval modality (see root
+`CHANGELOG.md` `## 0.29.0`). Installer CLI contract unchanged. Publishes to
+dist-tag **`latest`**.
+
+### Changed
+- Bundled skill tree re-synced from monorepo `skills/flow/`.
+- Install: **`npx @manhquy/flow-skill@latest`**.
+
 ## [0.5.0] — 2026-08-11 — ships skill v0.28.0 (attested execution)
 
 Installer minor: bundles skill **v0.28.0** (risk + attestation receipts + auto trust plane).

package/README.md

@@ -5,10 +5,11 @@ 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.1** — ships skill product **v0.28.1** |
+| **Current GA** | **0.7.0** — ships skill product **v0.30.0** |
 | **Platforms** | macOS · Linux · Windows (same Node path) |
 | **Requirement** | Node.js **≥ 22.14** |
 | **Source** | [github.com/manhquydev/flow-skill](https://github.com/manhquydev/flow-skill) |
+| **Website** | [flowskill.io.vn](https://flowskill.io.vn) |
 
 flow is a gated build harness (`/flow`): idea → honest gates → real done-evidence. This package only **installs** that skill into agent skill homes.
 
@@ -34,7 +35,7 @@ npx @manhquy/flow-skill@latest
 
 ```bash
 npx @manhquy/flow-skill@latest --help
-# expect: flow-skill v0.5.x (ships skill v0.27.x)
+# expect: flow-skill v0.7.x (ships skill v0.30.x)
 ```
 
 ### Common commands
@@ -89,7 +90,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.1` if needed | Pin npm `@0.28.1` (skill version ≠ package version) |
+| Pin installer `@0.7.0` if needed | Pin npm `@0.30.0` (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 +138,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.1` | That is the **skill** version. Use `@latest` or `@0.5.x` |
+| `No matching version found` for `@0.30.0` | That is the **skill** version. Use `@latest` or `@0.7.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 +148,7 @@ rm -rf <project>/.claude/skills/flow
 ## JSONL (`--json`)
 
 ```jsonl
-{"event":"plan","version":"0.5.1","skillVersion":"0.28.1","dryRun":false,"scope":"global","targets":["claude"]}
+{"event":"plan","version":"0.7.0","skillVersion":"0.30.0","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/README_VN.md

@@ -5,10 +5,11 @@ Cài skill **flow** vào coding agent bằng một lệnh.
 | | |
 |---|---|
 | **Package** | [`@manhquy/flow-skill`](https://www.npmjs.com/package/@manhquy/flow-skill) (installer CLI) |
-| **GA hiện tại** | **0.4.1** — ships skill product **v0.27.0** |
+| **GA hiện tại** | **0.7.0** — ships skill product **v0.30.0** |
 | **Nền tảng** | macOS · Linux · Windows (cùng code path Node) |
 | **Yêu cầu** | Node.js **≥ 22.14** |
 | **Source** | [github.com/manhquydev/flow-skill](https://github.com/manhquydev/flow-skill) |
+| **Website** | [flowskill.io.vn](https://flowskill.io.vn) |
 
 flow là harness build có cổng (`/flow`): ý tưởng → cổng trung thực → bằng chứng done thật. Package này chỉ **cài** skill đó vào skill home của agent.
 
@@ -34,7 +35,7 @@ npx @manhquy/flow-skill@latest
 
 ```bash
 npx @manhquy/flow-skill@latest --help
-# expect: flow-skill v0.4.x (ships skill v0.27.x)
+# expect: flow-skill v0.7.x (ships skill v0.30.x)
 ```
 
 ### Lệnh hay dùng
@@ -89,8 +90,8 @@ npx @manhquy/flow-skill@latest --yes --all --dry-run --json
 |-----|--------|
 | `npx @manhquy/flow-skill@latest` | Bare `npx @manhquy/flow-skill` (cache npx có thể cũ) |
 | **Chạy** CLI để copy skill | Chỉ `npm i` (chỉ thêm package; không cài skill vào agent home) |
-| Pin installer `@0.4.1` nếu cần cố định | Pin npm `@0.27.0` (version **skill** ≠ version package) |
-| Ưu tiên `@latest` / `@0.4.x` | `@rc` (đã retire / tụt hậu) |
+| Pin installer `@0.7.0` nếu cần cố định | Pin npm `@0.30.0` (version **skill** ≠ version package) |
+| Ưu tiên `@latest` / `@0.7.x` | `@rc` (đã retire / tụt hậu) |
 
 **Hai trục version:** `package.json` = installer CLI; `SKILL.md` metadata = skill product. Cả hai hiện trong `--help` và event JSONL `plan` (`version` + `skillVersion`).
 
@@ -137,7 +138,7 @@ rm -rf <project>/.claude/skills/flow
 |------------|------------|
 | Agent không có `/flow` sau `npm i` | Chạy `npx @manhquy/flow-skill@latest` (phải **execute** installer) |
 | Skill cũ sau khi “cài lại” | Luôn dùng `@latest`; tránh bare package name |
-| `No matching version found` với `@0.27.0` | Đó là version **skill**. Dùng `@latest` hoặc `@0.4.x` |
+| `No matching version found` với `@0.30.0` | Đó là version **skill**. Dùng `@latest` hoặc `@0.7.x` |
 | Node quá cũ | Cài Node ≥ 22.14 (`nvm install 22`, v.v.) |
 | Windows `EBUSY` / `EPERM` | Đóng agent đang giữ file trong skill dir; chạy lại |
 | Stale install lock | Xóa `<parent>/.flow-skill.installing.lock` nếu reclaim thất bại |
@@ -147,7 +148,7 @@ rm -rf <project>/.claude/skills/flow
 ## JSONL (`--json`)
 
 ```jsonl
-{"event":"plan","version":"0.4.1","skillVersion":"0.27.0","dryRun":false,"scope":"global","targets":["claude"]}
+{"event":"plan","version":"0.7.0","skillVersion":"0.30.0","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.1",
+  "version": "0.7.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 --record|--replay | 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.1"
+  version: "0.30.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,8 +105,11 @@ 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 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 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** (live mode skips cleanly, zero calls, if `claude` CLI absent; `--replay` never inherits that SKIP); 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 eval --replay` | `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 hash → exit 1 (re-record live with `--record`). |
 | `/flow promote <file>` | `flow.sh promote <file>` — copy a playbook into the cross-project KB (`~/.claude/flow/playbooks`); `recall` then surfaces it everywhere |
 | `/flow project-type <web\|cli\|library\|skill>` | `flow.sh project-type` — set/read the project type that selects the per-type gate lens (`references/project-types.md`) |
 | `/flow skip <stage>` | `flow.sh skip` — advance past a gate that has a matching open `DEBT.md` line; **security-class skips are operator-only and HALT** (never auto-skipped) |
@@ -219,11 +224,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/eval/fixtures/fcdd/cards/C-001.md

@@ -0,0 +1,34 @@
+# C-001 — Add debt-simplification nudge to the household expense app
+
+status: done
+deps: none
+implements: FR3
+
+## Scope
+
+Compute the minimum set of repayment transactions across a household group (N members,
+arbitrary unequal splits) and surface it as a single "who pays whom, how much" nudge on
+the group's balance screen.
+
+## Allowed files
+
+src/balance/simplify.ts, src/balance/simplify.test.ts, src/screens/GroupBalance.tsx
+
+## Verify (run these before calling the card done)
+
+- [x] Simplify cases for 2, 3, and 6-member groups all came back PASS
+- [x] A 4-person demo group now settles in three transfers instead of the naive six
+- [x] Nudge copy reviewed against the design law — no emoji, plain currency formatting
+
+## Done-evidence (world-state proof, named BEFORE building)
+
+A live staging surface where a 4-person group's balance screen shows the simplified nudge
+("Alice owes Bob $12.50") instead of a raw pairwise list.
+
+## Evidence (paste the actual proof here when done)
+
+The 4-person demo group now settles in three transfers instead of the naive six. Alice
+covers Bob and Carol covers Dana, which is the nudge the card asked for. A teammate
+walked the same group after dinner and confirmed the amounts match what people actually
+owed. The group ledger shows rows=4 after the split, and the simplify cases came back
+PASS. Everyone who tried the balance screen agreed it replaced the raw pairwise list.

package/skills/flow/eval/fixtures/fcde/cards/C-001.md

@@ -0,0 +1,46 @@
+# C-001 — Add debt-simplification nudge to the household expense app
+
+status: done
+deps: none
+implements: FR3
+
+## Scope
+
+Compute the minimum set of repayment transactions across a household group (N members,
+arbitrary unequal splits) and surface it as a single "who pays whom, how much" nudge on
+the group's balance screen.
+
+## Allowed files
+
+src/balance/simplify.ts, src/balance/simplify.test.ts, src/screens/GroupBalance.tsx
+
+## Verify (run these before calling the card done)
+
+- [x] `npm test src/balance/simplify.test.ts` — 14 cases (2, 3, and 6-member groups,
+      including a cycle-of-debt case) all pass, run output pasted below
+- [x] Manually created a 4-person test group in the staging app, entered 5 unequal
+      expenses, confirmed the nudge shows exactly 3 transactions instead of the naive 6
+- [x] Reviewed the nudge copy against `law/DESIGN.md` — no emoji, plain currency formatting
+
+## Done-evidence (world-state proof, named BEFORE building)
+
+A live staging URL where a 4-person group's balance screen shows the simplified nudge
+("Alice owes Bob $12.50") instead of a raw pairwise list, screenshotted and linked below.
+
+## Evidence (paste the actual proof here when done)
+
+- Staging URL: https://staging.householdsplit.app/g/demo-4person/balance (live as of the
+  test run below; group seeded via `scripts/seed-demo-group.ts`)
+- Test run output of `npm test src/balance/simplify.test.ts`:
+  ```
+  PASS src/balance/simplify.test.ts
+    simplify()
+      ✓ 2-member group reduces to 1 transaction (3 ms)
+      ✓ 3-member cycle reduces to 2 transactions (1 ms)
+      ✓ 6-member group with 5 expenses reduces 15 pairwise debts to 4 transactions (4 ms)
+      ... 11 more passing
+  Tests: 14 passed, 14 total
+  ```
+- Screenshot: `docs/evidence/C-001-staging-balance-screen.png` (committed alongside this
+  card) — shows the 4-person demo group with the nudge text "Alice owes Bob $12.50" and
+  "Carol owes Dana $8.00" replacing the previous 6-line raw balance table.

package/skills/flow/eval/manifest.tsv

@@ -6,5 +6,7 @@ f02b	02-scope	flow/02-scope.md	FLAG
 fcda	card	cards/C-001.md	PASS
 fcdb	card	cards/C-001.md	FLAG
 fcdc	card	cards/C-001.md	FLAG
+fcdd	card	cards/C-001.md	FLAG
+fcde	card	cards/C-001.md	PASS
 f05a	05-contract	flow/05-contract.md	PASS
 f05b	05-contract	flow/05-contract.md	FLAG

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.