@manhquy/flow-skill 0.5.0 → 0.6.0

package/skills/flow/references/converge.md

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

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

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

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

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

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

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

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

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