@manhquy/flow-skill 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to `@manhquy/flow-skill`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/).
 
+## [0.3.0] — 2026-08-11 — ships skill v0.26.0 (hollow-done trust floor)
+
+Skill-content release; **installer code unchanged** vs 0.2.1. Ships skill product **v0.26.0**
+(mechanical multi-signal done Evidence floor, ready/graph re-validate, fcdc residual fixture;
+see root `CHANGELOG.md` `## 0.26.0`). Publishes to dist-tag **`latest`**.
+
+### Changed
+- Bundled skill tree re-synced from monorepo `skills/flow/` (48 test suites green at ship).
+- Install command remains **`npx @manhquy/flow-skill@latest`**.
+
+## [0.2.1] — 2026-08-01 — docs sync (`@latest` canonical, `rc` retired)
+
+Docs-only installer release. **No CLI, detection, lock, or target change** vs 0.2.0 — same
+tarball behavior; this exists so npmjs.com renders the corrected README.
+
+### Changed
+- Canonical install command is now **`npx @manhquy/flow-skill@latest`** everywhere. Bare
+  `npx @manhquy/flow-skill` can re-run a stale npx cache; `@latest` forces the newest release.
+- Dropped the `@rc` channel from user-facing docs. The `rc` dist-tag had drifted to
+  `0.1.0-rc.3` (behind `latest`), so following `@rc` silently downgraded users. `rc` is
+  retired on the registry (`npm dist-tag rm @manhquy/flow-skill rc`); use `@next` for any
+  future pre-release.
+- Clarified that `npm i` never installs the skill — the CLI must be **run**.
+
+## [0.2.0] — 2026-07-27 — ships skill v0.25.0
+
+Skill-content release; **installer code unchanged** vs 0.1.0. Ships skill product **v0.25.0**
+(graph executor, opt-in and dark until `FLOW_GRAPH_EXECUTOR=1`; see root `CHANGELOG.md`
+`## 0.25.0`). Publishes to dist-tag `latest`.
+
 ## [0.1.0] — 2026-07-19 — GA (first stable, `latest`)
 
 First stable release of the installer. Graduates the rc.1→rc.3 line after two live OIDC

package/README.md

@@ -10,44 +10,42 @@ One-command installer that copies the [flow](https://github.com/manhquydev/flow-
 ## Install
 
 ```
-# Stable (latest) — current: v0.1.0, ships skill v0.24.0
-npx @manhquy/flow-skill
-
-# Pre-release channel (opt-in)
-npx @manhquy/flow-skill@rc
+# Newest GA — current: v0.3.0, ships skill v0.26.0
+npx @manhquy/flow-skill@latest
 ```
 
 An interactive prompt asks which agents to install to. Pick one or more, confirm, done.
 
-> **Stable is on `latest`**: bare `npx @manhquy/flow-skill` (or `@0.1.x`) resolves the GA release.
-> Pin `@rc` only if you want the pre-release channel. See [SECURITY.md](./SECURITY.md).
+> **Always use `@latest`.** npx caches by bare name, so a plain `npx @manhquy/flow-skill` can
+> re-run a stale cached copy; `@latest` forces npx to fetch the newest GA release. See
+> [SECURITY.md](./SECURITY.md).
 >
 > **`npm i` alone is not enough.** `npm install @manhquy/flow-skill` only adds the installer
-> package to `node_modules`. You must **run** it (`npx @manhquy/flow-skill` or
+> package to `node_modules`. You must **run** it (`npx @manhquy/flow-skill@latest` or
 > `npx flow-skill` after install) to copy the skill into agent homes.
 >
-> **Two version axes:** package `version` in this folder is the **installer** (e.g. `0.1.0`).
-> Skill product version lives in `skills/flow/SKILL.md` (`metadata.version`, e.g. `0.24.0`).
+> **Two version axes:** package `version` in this folder is the **installer** (e.g. `0.3.0`).
+> Skill product version lives in `skills/flow/SKILL.md` (`metadata.version`, e.g. `0.26.0`).
 > `--help` and the JSONL `plan` event expose both (`version` + `skillVersion`).
 
 ## Non-interactive
 
 ```
 # Default selection (Claude + anything detected)
-npx @manhquy/flow-skill@rc --yes
+npx @manhquy/flow-skill@latest --yes
 
 # Explicit targets
-npx @manhquy/flow-skill@rc --yes -t claude -t codex
-npx @manhquy/flow-skill@rc --yes -t claude,codex           # comma form OK
+npx @manhquy/flow-skill@latest --yes -t claude -t codex
+npx @manhquy/flow-skill@latest --yes -t claude,codex           # comma form OK
 
 # Force all five targets even if not detected
-npx @manhquy/flow-skill@rc --yes --all
+npx @manhquy/flow-skill@latest --yes --all
 
 # Project scope (Claude only — see below)
-npx @manhquy/flow-skill@rc --yes --project --dir .
+npx @manhquy/flow-skill@latest --yes --project --dir .
 
 # CI-friendly JSONL output
-npx @manhquy/flow-skill@rc --yes --all --dry-run --json
+npx @manhquy/flow-skill@latest --yes --all --dry-run --json
 ```
 
 ## Targets
@@ -97,8 +95,8 @@ rm -rf <project>/.claude/skills/flow
 
 - **Windows `EBUSY` / `EPERM` mid-install**: an agent (Claude Code, Codex, Antigravity IDE) is holding a file inside the destination. Close the agent and re-run. The installer already retries with 100/300/900 ms backoff before surfacing the error.
 - **Stale advisory lock**: a prior run crashed. The next run detects the dead PID and reclaims the lock automatically. If it does not (very rare — the recorded PID was recycled by another live process), delete `<parent-of-dest>/.flow-skill.installing.lock`.
-- **`No matching version found` on `@0.24.0`**: that is the **skill product** version, not the npm package version. Install the installer by its own version (bare / `@0.1.x` / `@rc`) — skill content version is printed by `--help` as `ships skill v…`.
-- **Installed package but agent has no `/flow`**: `npm i` does not run the installer. Run `npx @manhquy/flow-skill@rc` (or `npx flow-skill` if already installed) and restart the agent.
+- **`No matching version found` on `@0.26.0`**: that is the **skill product** version, not the npm package version. Install the installer by its own version (`@latest` / `@0.2.x`) — skill content version is printed by `--help` as `ships skill v…`.
+- **Installed package but agent has no `/flow`**: `npm i` does not run the installer. Run `npx @manhquy/flow-skill@latest` (or `npx flow-skill` if already installed) and restart the agent.
 - **Node too old** (`requires Node.js >=22.14.0`): upgrade with your preferred version manager (`nvm install 22`, `fnm install 22`, or Node's official installer). Node 20 reached end-of-life April 2026; npm OIDC Trusted Publishing needs npm >=11.5.1 which bundles with Node 22.14+.
 
 ## JSONL contract
@@ -106,7 +104,7 @@ rm -rf <project>/.claude/skills/flow
 `--json` streams one JSON object per line:
 
 ```jsonl
-{"event":"plan","version":"0.1.0","skillVersion":"0.24.0","dryRun":false,"scope":"global","targets":["claude","codex"]}
+{"event":"plan","version":"0.3.0","skillVersion":"0.26.0","dryRun":false,"scope":"global","targets":["claude","codex"]}
 {"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":2,"attempted":2,"installed":2,"failed":0,"skipped":0,"aborted":false}

package/README_VN.md

@@ -10,37 +10,36 @@ Trình cài đặt một-lệnh sao chép skill [flow](https://github.com/manhqu
 ## Cài đặt
 
 ```
-# Stable (latest) — hiện tại: v0.1.0, ships skill v0.24.0
-npx @manhquy/flow-skill
-
-# Kênh pre-release (tùy chọn)
-npx @manhquy/flow-skill@rc
+# Newest GA — hiện tại: v0.3.0, ships skill v0.26.0
+npx @manhquy/flow-skill@latest
 ```
 
 Prompt tương tác hỏi cài vào agent nào. Chọn một hoặc nhiều, xác nhận, xong.
 
-> **Stable ở `latest`**: bare `npx @manhquy/flow-skill` (hoặc `@0.1.x`) lấy bản GA. Pin `@rc` nếu muốn kênh pre-release. Xem [SECURITY.md](./SECURITY.md).
+> **Luôn dùng `@latest`.** npx cache theo bare name nên `npx @manhquy/flow-skill` có thể chạy
+> bản cache cũ; `@latest` ép lấy GA mới nhất. Kênh `rc` đã retire — không dùng `@rc`.
 >
-> **`npm i` alone chưa đủ** — phải **chạy** CLI (`npx @manhquy/flow-skill`). Hai trục version: package npm vs skill product (`ships skill v…` / `skillVersion` trong JSONL).
+> **`npm i` alone chưa đủ** — phải **chạy** CLI. Hai trục version: package npm vs skill product
+> (`ships skill v…` / `skillVersion` trong JSONL). Xem [SECURITY.md](./SECURITY.md).
 
 ## Non-interactive
 
 ```
 # Chọn mặc định (Claude + những agent detect được)
-npx @manhquy/flow-skill@rc --yes
+npx @manhquy/flow-skill@latest --yes
 
 # Target rõ ràng
-npx @manhquy/flow-skill@rc --yes -t claude -t codex
-npx @manhquy/flow-skill@rc --yes -t claude,codex           # Dạng comma OK
+npx @manhquy/flow-skill@latest --yes -t claude -t codex
+npx @manhquy/flow-skill@latest --yes -t claude,codex           # Dạng comma OK
 
 # Ép cài cả 5 target dù không detect
-npx @manhquy/flow-skill@rc --yes --all
+npx @manhquy/flow-skill@latest --yes --all
 
 # Project scope (chỉ Claude — xem bên dưới)
-npx @manhquy/flow-skill@rc --yes --project --dir .
+npx @manhquy/flow-skill@latest --yes --project --dir .
 
 # JSONL cho CI
-npx @manhquy/flow-skill@rc --yes --all --dry-run --json
+npx @manhquy/flow-skill@latest --yes --all --dry-run --json
 ```
 
 ## Targets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manhquy/flow-skill",
-  "version": "0.2.0",
+  "version": "0.3.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

@@ -8,7 +8,7 @@ keywords: [flow, buildflow, gate, build, ship, scope, prd, contract, card, deplo
 license: MIT
 metadata:
   author: flow-skill
-  version: "0.25.0"
+  version: "0.26.0"
   attribution: "Methodology from ai20k-build-phase/buildflow (Tony, arealisticdreamer.com); harness/agent layers from repository-harness, claudekit-engineer, BMAD-METHOD. v0.22 concierge routing pattern adapted from BMAD-METHOD's bmad-help; forge-idea ritual adapted from BMAD-METHOD's bmad-forge-idea (both MIT, BMad Code LLC)."
 ---
 

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

@@ -0,0 +1,39 @@
+# 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` — all green in CI logs pasted below
+- [x] Staging URL opened once by the author
+- [x] PR approved by two teammates
+
+## Done-evidence (world-state proof, named BEFORE building)
+
+A live staging URL where a 4-person group's balance screen shows the simplified nudge
+instead of a raw pairwise list.
+
+## Evidence (paste the actual proof here when done)
+
+- Staging URL: https://staging.householdsplit.app/g/demo-4person/balance
+- CI / test paste:
+  ```
+  PASS src/balance/simplify.test.ts
+  Tests: 14 passed, 14 total
+  ```
+- The pull request went through normal review, picked up two required approvals, and the
+  release notes list the nudge under "new features." The team is confident this covers
+  the card; no separate live user verification of the nudge math is attached beyond the
+  URL and CI paste above (process narrative coexists with multi-signal paste).

package/skills/flow/eval/manifest.tsv

@@ -5,3 +5,4 @@ f02a	02-scope	flow/02-scope.md	PASS
 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

package/skills/flow/harness/graph_executor.py

@@ -795,6 +795,132 @@ def _card_id(tok):
     return "C-%03d" % int(tok.split("-")[1])  # C-1 == C-001
 
 
+def _evidence_body_from_text(text):
+    """Extract ## Evidence section body (mirrors flow.sh _evidence_body)."""
+    lines, in_ev = [], False
+    for line in text.splitlines():
+        s = line.replace("\r", "")
+        if s.startswith("## Evidence"):
+            in_ev = True
+            continue
+        if in_ev and s.startswith("## "):
+            break
+        if in_ev and s.strip():
+            lines.append(s)
+    return "\n".join(lines)
+
+
+def _evidence_is_empty(ev):
+    if not ev or not ev.strip():
+        return True
+    low = ev.lower().strip()
+    if "(empty until done)" in low or low in ("---", "--"):
+        return True
+    return False
+
+
+_URL_HOST_RE = re.compile(r"https?://([^/\s]+)", re.IGNORECASE)
+_DENY_HOSTS = {
+    "example.com", "www.example.com", "example.org", "www.example.org",
+    "localhost", "127.0.0.1", "0.0.0.0", "[::1]", "invalid", "test", "example",
+}
+
+
+def _normalize_url_host(host):
+    """Lower, strip userinfo/port/trailing dots (mirrors flow.sh _evidence_url_host)."""
+    if not host:
+        return ""
+    h = host.lower()
+    if "@" in h:
+        h = h.rsplit("@", 1)[-1]
+    if h.startswith("["):
+        end = h.find("]")
+        if end != -1:
+            h = h[: end + 1]
+    else:
+        if h.count(":") == 1:
+            h = h.rsplit(":", 1)[0]
+    while h.endswith("."):
+        h = h[:-1]
+    return h
+
+
+def _url_host_ok(host):
+    if not host:
+        return False
+    h = _normalize_url_host(host)
+    if h in _DENY_HOSTS:
+        return False
+    for suf in (".invalid", ".test", ".example", ".localhost",
+                ".example.com", ".example.org"):
+        if h.endswith(suf) or h == suf.lstrip("."):
+            return False
+    return True
+
+
+def _evidence_signal_score(ev, root):
+    """Multi-signal score ≥2 required for done trust (mirrors flow.sh table v2)."""
+    if not ev:
+        return 0
+    score = 0
+    low = ev.lower()
+    # Strip URLs before C-token matching (https://ok.dev must not award C).
+    ev_c = re.sub(r"https?://\S+", "", low)
+    m = _URL_HOST_RE.search(ev)
+    if m and _url_host_ok(m.group(1)):
+        score += 1
+    if re.search(r"curl|(^|\s)\$\s|exit 0|exit code|->\s*200|http/[0-9]", low):
+        score += 1
+    if re.search(r"(^|[^a-z])(pass|passed|ok)([^a-z]|$)", ev_c):
+        score += 1
+    else:
+        # fence awards C only when body has positive tokens
+        fence = False
+        for line in ev.splitlines():
+            if line.strip().startswith("```"):
+                fence = not fence
+                continue
+            if fence and re.search(r"(^|[^a-z])(pass|passed|ok)([^a-z]|$)", line.lower()):
+                score += 1
+                break
+    for p in re.findall(r"[A-Za-z0-9_./-]+\.(?:png|jpg|jpeg|webp|gif|log|txt)", ev):
+        if p.startswith("/") or p.startswith("~"):
+            continue
+        if os.path.isfile(os.path.join(root, p)) or os.path.isfile(p):
+            score += 1
+            break
+    if re.search(r"rows?=[0-9]+|select\s+[a-z_*]|sqlite|inserted\s+[a-z0-9]", low):
+        score += 1
+    if re.search(r"~/\.claude/skills|~/\.codex/skills|~/\.agents/skills|skills/flow", ev):
+        score += 1
+    return score
+
+
+def _card_done_evidence_ok(path, root):
+    """status=done + multi-signal Evidence + no unchecked Verify + no [FILL]
+    (parity with flow.sh _card_done_evidence_ok / cmd_check done branch)."""
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            text = fh.read()
+    except OSError:
+        return False
+    status = ""
+    for line in text.splitlines():
+        if line.startswith("status:"):
+            status = line.split(":", 1)[1].strip().split()[0] if line.split(":", 1)[1].strip() else ""
+            break
+    if status != "done":
+        return False
+    if "[FILL" in text:
+        return False
+    if re.search(r"^\s*- \[ \]", text, re.M):
+        return False
+    ev = _evidence_body_from_text(text)
+    if _evidence_is_empty(ev):
+        return False
+    return _evidence_signal_score(ev, root) >= 2
+
+
 def _read_cards(cards_dir):
     """Parse the REAL card format (no YAML frontmatter): a `deps:` body line whose
     free text is scraped for C-NNN ids (mirrors flow.sh:1310-1319) and a
@@ -808,8 +934,9 @@ def _read_cards(cards_dir):
         if not m:
             continue
         cid = _card_id(m.group(1))
+        path = os.path.join(cards_dir, name)
         status, deps, files, in_allowed, fill = "", [], set(), False, False
-        with open(os.path.join(cards_dir, name), encoding="utf-8", errors="replace") as fh:
+        with open(path, encoding="utf-8", errors="replace") as fh:
             for line in fh:
                 s = line.rstrip("\n")
                 if s.startswith("## Allowed files"):
@@ -837,7 +964,7 @@ def _read_cards(cards_dir):
         # A self-dep is kept (not silently dropped): cmd_ready blocks such a card, so the
         # compiler must too - dropping it would advertise an undispatchable card as ready.
         cards[cid] = {"id": cid, "status": status, "deps": sorted(set(deps)),
-                      "files": sorted(files), "fill": fill}
+                      "files": sorted(files), "fill": fill, "path": path}
     return cards
 
 
@@ -865,10 +992,11 @@ def _dep_cycles(cards):
 
 
 def compile_cards(root, active_files=()):
-    """Card DAG + ready-set. deps-met mirrors cmd_ready (status of each dep == done);
-    overlap serialization is NEW deliberate behavior (legacy `ready` only advises,
-    flow.sh:1302): cards sharing an allowed-file token, or overlapping a currently
-    active worktree's tokens, are held back so two agents never edit one file."""
+    """Card DAG + ready-set. deps-met mirrors cmd_ready: each dep is status=done AND
+    Evidence passes the multi-signal world-state floor (hollow hand-edit cannot unblock).
+    overlap serialization is NEW deliberate behavior (legacy `ready` only advises):
+    cards sharing an allowed-file token, or overlapping a currently active worktree's
+    tokens, are held back so two agents never edit one file."""
     cards = _read_cards(os.path.join(root, "cards"))
     cycles = _dep_cycles(cards)
     # Only `todo` is buildable - cmd_ready's exact semantics (an invalid/blank status is
@@ -877,7 +1005,13 @@ def compile_cards(root, active_files=()):
     in_cycle = {n for cyc in cycles for n in cyc}
     deps_met, blocked = [], {}
     for c in sorted(todo, key=lambda x: x["id"]):
-        missing = [d for d in c["deps"] if cards.get(d, {}).get("status") != "done"]
+        missing = []
+        for d in c["deps"]:
+            dep = cards.get(d, {})
+            if dep.get("status") != "done":
+                missing.append(d)
+            elif not _card_done_evidence_ok(dep.get("path") or "", root):
+                missing.append(d)
         if c["id"] in in_cycle:
             blocked[c["id"]] = {"reason": "dep cycle",
                                 "cycle": next("->".join(x) for x in cycles if c["id"] in x)}

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

@@ -39,7 +39,10 @@ for each todo card in card-number order:
   4. flow.sh check C-NNN must PASS (mechanical) + gate-rules semantic check
      [records: card-review, with the gate exit as the evidence]
   5. merge to main in card order; deploy; VERIFY ON LIVE URL (merge != shipped)
-  6. paste world-state evidence into the card; status: done
+  6. paste world-state evidence into the card; prefer **`/flow card done C-NNN`** (CLI-owned
+     flip + evidence multi-signal floor). Hand-edit `status: done` is allowed to coexist but
+     **must** re-run `flow.sh check C-NNN` before dependents are trusted — `ready`/graph
+     deps re-validate Evidence (hollow process prose cannot unblock parallel).
      [records: card-verify-live, via '/flow card done C-NNN' (evidence gate = the done boundary)]
   7. flow.sh harness story complete --id … --proof-source manual (or card_markdown_gate) + trace; log AUTO-LOG.md
   8. remove worktree: /flow workspace remove card/C-NNN

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

@@ -25,14 +25,32 @@ rule text is enforceable by *a* judge," not "this build's self-review caught eve
 
 ## Fixtures and thresholds
 
-Six shipped fixtures (`skills/flow/eval/fixtures/`, manifest `skills/flow/eval/manifest.tsv`):
+Seven 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).
+grade laundering, a real C quietly graded B), and the card gate:
+- **fcda** — sound multi-signal Evidence (mechanical PASS, semantic PASS)
+- **fcdb** — process-only hollow (mechanical **FAIL** after hollow-done floor; still listed for
+  historical FLAG text / offline inspection)
+- **fcdc** — hollow-with-decoy multi-signal (mechanical PASS, semantic **FLAG** — the residual
+  attack class the mechanical floor does not claim to close)
+
 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).
 
+### Scorecard policy (CI vs offline)
+
+| Suite | Where | Blocks merge? |
+|-------|-------|---------------|
+| Mechanical done-evidence + auto-path + ready re-validate | `tests/run_all.sh` / GHA | **Yes** |
+| Fixture structure / manifest paths | CI shell tests | **Yes** |
+| LLM semantic `flow.sh eval` batch | Operator offline (billable) | **No** by default |
+| Offline `eval --report` drift | Local | Advisory |
+
+CI-measurable process-only catch rate: process-only fixtures must exit 1 from `flow.sh check`.
+Billable LLM catch-rate is never a default CI gate (see `flow.sh` eval header).
+
 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
@@ -43,14 +61,14 @@ separately from a real mismatch — never silently counted as a gate pass or fai
 `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.
+one billable call was made, then a clean skip. A full default batch is 7 fixtures × N=3 = 21
+judge calls + the 1 probe = 22 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**
+not by the judging prompt itself. A full 22-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)
@@ -128,7 +146,7 @@ yet (the same "measure, don't assume" discipline that gated this build in the fi
   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
+- **Small fixture corpus (seven)**: 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.
 
@@ -157,7 +175,7 @@ window; the mechanism was never confirmed at the time (rate-limit vs hook conten
    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).
+   default 7 × 3).
 
 ### Rate-limit visibility (advisory, best-effort)
 

package/skills/flow/references/ground-truth-gates.md

@@ -14,6 +14,8 @@ and used only to add color, never to pass a gate.
 | Story proof | `flow.sh harness story verify <id>` -> `verify_command` exit 0 | "I wrote tests" |
 | Build merged-safe | review green (adversarial) + `flow.sh check` pass | "the diff is small" |
 | Card DONE | deploy ran + **live URL verified as a user** (world-state evidence pasted) | "merged" / "deploy succeeded" / "tests pass" |
+| Card DONE (mechanical floor) | `flow.sh check` / `card done`: `## Evidence` multi-signal score ≥2 (URL + curl/command/test-log/path/DB/skill categories; denylist example.com etc.) | process-only prose (PR approvals, CI green, release notes alone); empty/placeholder |
+| Dep ready / parallel | `ready` + graph deps-met: dep `status=done` **and** same Evidence multi-signal floor | hand-edit `status: done` with hollow Evidence |
 | Contract not drifted | contract-test card asserts every endpoint exists in live `/openapi.json` with matching shape | "backend and UI agree" (they don't, silently) |
 
 ## Rules
@@ -26,6 +28,15 @@ and used only to add color, never to pass a gate.
 4. **A red signal stops the run.** No "probably fine" override. Fix or open debt.
 5. **Capture the proof.** Paste the real curl/URL/exit into the card `## Evidence` and the
    harness `trace` — so the next session sees ground truth, not a claim.
+6. **Mechanical multi-signal is a floor, not a ceiling.** A decoy URL + genuine positive
+   tokens (e.g. staging host + `PASS` log) can still score ≥2; that residual is for the
+   **offline semantic** layer (`flow.sh eval` / fcdc), never claimed closed by regex alone.
+   C-tokens are **not** matched inside URLs; `fail`/`failed` do not award C; denylist hosts
+   ignore `:port` spoofing. Durable `card_markdown_gate` only records that the markdown floor
+   passed — it is not stronger than that floor.
+7. **Hand-edit `status: done` is not trusted for deps** until Evidence **and** Verify boxes
+   pass the same floor (`ready` re-validates Evidence + unchecked Verify + `[FILL]`; graph
+   executor mirrors).
 
 ## Bug-fix cards: prove the test was tied to the bug
 When a card's job is fixing a bug/regression (not new behavior), a passing test is not yet

package/skills/flow/runner/flow.sh

@@ -1171,8 +1171,17 @@ cmd_card_done() { # CLI-owned flip to done, gated by the SAME done-rules as '/fl
   if [ -z "$file" ] || [ ! -f "$file" ]; then echo "FAIL: card not found for '$arg' (looked for ${file:-?})"; return 1; fi
   local id orig; id="$(basename "$file" .md)"; FLOW_LOG_CARD="$id"; orig="$(card_status "$file")"
   if [ -z "$orig" ]; then echo "FAIL: $id has no 'status:' line — run '/flow check $id' to see what's missing."; return 1; fi
-  if ! _set_card_status "$file" done; then echo "FAIL: could not write status for $id"; return 1; fi
+  # On INT/TERM after flip-to-done: restore todo and abort (fail-closed). Never continue
+  # into durable complete after a partial restore.
+  # shellcheck disable=SC2064
+  trap '_set_card_status "'"$file"'" "todo" 2>/dev/null || true; trap - INT TERM; exit 130' INT TERM
+  if ! _set_card_status "$file" done; then
+    trap - INT TERM
+    echo "FAIL: could not write status for $id"
+    return 1
+  fi
   if cmd_check "$id"; then            # cmd_check enforces evidence/verify AND records the durable done-trace
+    trap - INT TERM
     _inflight_clear "$id"
     # card-verify-live: the done boundary is the EVIDENCE gate passing, not the merge
     # (merge != shipped) - dependents unblock on card status, matching cmd_ready.
@@ -1180,9 +1189,11 @@ cmd_card_done() { # CLI-owned flip to done, gated by the SAME done-rules as '/fl
     _graph_record "$id" card-verify-live --gate-exit 0 --card-status done
     return 0
   fi
-  _set_card_status "$file" "${orig:-todo}"   # NOT done — never leave a hollow 'done'
+  trap - INT TERM
+  # Always force todo on gate fail (even if orig was hollow done) — never leave hollow done.
+  _set_card_status "$file" todo
   echo
-  echo "REVERTED: $id left at status '${orig:-todo}' — the done-gate above must pass first."
+  echo "REVERTED: $id left at status 'todo' — the done-gate above must pass first."
   return 1
 }
 
@@ -1226,6 +1237,131 @@ cmd_card() {
   return 0
 }
 
+# ---- done-evidence world-state signal (hollow-done trust floor; plan 260811) ----
+# When status=done, ## Evidence must score ≥2 distinct categories (A–F). Process-only
+# prose (PR/CI/release notes) without that floor fails. Decoy multi-signal may still
+# pass mechanically — residual for offline semantic eval (fcdc). Pure bash, no python.
+
+_evidence_body() { # $1=card file → Evidence section body (non-empty lines)
+  awk '/^## Evidence/{f=1; next} f && /^## /{f=0} f{print}' "$1" | tr -d '\r' | sed '/^[[:space:]]*$/d'
+}
+
+_evidence_is_empty() { # $1=evidence body; return 0 if empty/placeholder
+  local ev="$1" ev_lc
+  [ -z "$ev" ] && return 0
+  ev_lc="$(printf '%s' "$ev" | tr '[:upper:]' '[:lower:]')"
+  case "$ev_lc" in *"(empty until done)"*|"---"|"--") return 0 ;; esac
+  return 1
+}
+
+# Host from first http(s) URL; empty if none. Normalize: lower, strip userinfo/port/trailing dots.
+_evidence_url_host() {
+  local ev="$1" u host
+  u="$(printf '%s\n' "$ev" | grep -oiE 'https?://[^[:space:]/]+' | head -1 | tr '[:upper:]' '[:lower:]')"
+  [ -z "$u" ] && return 0
+  host="${u#http://}"; host="${host#https://}"; host="${host%%/*}"
+  # userinfo@host
+  case "$host" in *@*) host="${host##*@}" ;; esac
+  # [ipv6] or [ipv6]:port
+  case "$host" in
+    \[*\])
+      host="$(printf '%s' "$host" | sed 's/^\(\[[^]]*\]\).*/\1/')"
+      ;;
+    *)
+      # hostname:port (single colon) — leave bare IPv6 alone (multiple colons)
+      case "$host" in
+        *:*)
+          # if exactly one colon, treat as port
+          case "${host#*:}" in *:*) : ;; *) host="${host%%:*}" ;; esac
+          ;;
+      esac
+      ;;
+  esac
+  # trailing dots
+  while [ "${host%.}" != "$host" ]; do host="${host%.}"; done
+  printf '%s' "$host"
+}
+
+_evidence_url_host_ok() { # $1=host; 0=counts for category A
+  local h="$1"
+  [ -z "$h" ] && return 1
+  h="$(printf '%s' "$h" | tr '[:upper:]' '[:lower:]')"
+  case "$h" in
+    example.com|www.example.com|example.org|www.example.org) return 1 ;;
+    *.example.com|*.example.org) return 1 ;;
+    localhost|127.0.0.1|0.0.0.0|'[::1]') return 1 ;; # need B/C — no A alone
+    *.invalid|*.test|*.example|*.localhost) return 1 ;;
+  esac
+  case "$h" in invalid|test|example) return 1 ;; esac
+  return 0
+}
+
+# Echo integer score 0..6 for distinct categories hit. $1=evidence $2=project root for path exists.
+_evidence_signal_score() {
+  local ev="$1" root="${2:-.}"
+  local score=0 ev_lc host ev_c
+  ev_lc="$(printf '%s' "$ev" | tr '[:upper:]' '[:lower:]')"
+  # Strip URLs before C-token matching so https://ok.dev/x does not award C.
+  ev_c="$(printf '%s' "$ev_lc" | sed -E 's|https?://[^[:space:]]+||g')"
+
+  # A: non-denylist URL
+  host="$(_evidence_url_host "$ev")"
+  if _evidence_url_host_ok "$host"; then score=$((score + 1)); fi
+
+  # B: command / curl / exit / HTTP status / line-leading $ prompt
+  if printf '%s' "$ev_lc" | grep -qE 'curl|(^|[[:space:]])\$[[:space:]]|exit 0|exit code|->[[:space:]]*200|http/[0-9]'; then
+    score=$((score + 1))
+  fi
+
+  # C: positive test-log tokens only (not fail/failed); never match inside stripped URLs
+  if printf '%s' "$ev_c" | grep -qE '([^a-z]|^)(pass|passed|ok)([^a-z]|$)'; then
+    score=$((score + 1))
+  elif printf '%s' "$ev" | awk '
+      /^[[:space:]]*```/ {fence=!fence; next}
+      fence {
+        low=tolower($0)
+        if (low ~ /(^|[^a-z])(pass|passed|ok)([^a-z]|$)/) { print "yes"; exit }
+      }
+    ' | grep -q yes; then
+    # fence awards C only when body contains positive tokens (not bare 2-line blob)
+    score=$((score + 1))
+  fi
+
+  # D: repo-relative media/log path that exists
+  local p
+  for p in $(printf '%s\n' "$ev" | grep -oE '[A-Za-z0-9_./-]+\.(png|jpg|jpeg|webp|gif|log|txt)' | head -20); do
+    case "$p" in /*|~*) continue ;; esac
+    if [ -f "$root/$p" ] || [ -f "$p" ]; then score=$((score + 1)); break; fi
+  done
+
+  # E: DB-ish row proof (no bare id=1; need rows=N / SELECT / sqlite / inserted <id>)
+  if printf '%s' "$ev_lc" | grep -qE 'rows?=[0-9]+|select[[:space:]]+[a-z_*]|sqlite|inserted[[:space:]]+[a-z0-9]'; then
+    score=$((score + 1))
+  fi
+
+  # F: skill install path
+  if printf '%s' "$ev" | grep -qE '~/.claude/skills|~/.codex/skills|~/.agents/skills|skills/flow'; then
+    score=$((score + 1))
+  fi
+
+  printf '%s' "$score"
+}
+
+# Done dep trust: status=done + multi-signal Evidence + no unchecked Verify + no [FILL].
+# Mirrors the done branch of cmd_check (ready/graph must not be weaker).
+_card_done_evidence_ok() { # $1=card file
+  local file="$1" st ev score root
+  st="$(card_status "$file")"
+  [ "$st" = "done" ] || return 1
+  if grep -q '\[FILL' "$file" 2>/dev/null; then return 1; fi
+  if grep -qE '^[[:space:]]*- \[ \]' "$file" 2>/dev/null; then return 1; fi
+  ev="$(_evidence_body "$file")"
+  if _evidence_is_empty "$ev"; then return 1; fi
+  root="${FLOW_PROJECT_ROOT:-$PWD}"
+  score="$(_evidence_signal_score "$ev" "$root")"
+  [ "$score" -ge 2 ]
+}
+
 cmd_check() {
   local arg="${1:-}"
   if [ -z "$arg" ]; then echo "usage: /flow check C-NNN"; return 1; fi
@@ -1270,7 +1406,7 @@ cmd_check() {
     fi
   done
 
-  # 5) if done: all Verify boxes checked AND Evidence is real world-state
+  # 5) if done: all Verify boxes checked AND Evidence is real world-state (multi-signal floor)
   if [ "$st" = "done" ]; then
     local unchecked; unchecked="$(grep -nE '^[[:space:]]*- \[ \]' "$file" 2>/dev/null || true)"
     if [ -n "$unchecked" ]; then
@@ -1279,16 +1415,20 @@ cmd_check() {
       found=1
     fi
     # Evidence body: lines between the '## Evidence' header and the next '## ' heading (or EOF).
-    # Bounded awk avoids counting a stray later '## Evidence' as content. tr consumes all stdin
-    # (no SIGPIPE); case-glob instead of 'grep -q' which closes the pipe early.
-    local ev ev_lc empty_ev=0
-    ev="$(awk '/^## Evidence/{f=1; next} f && /^## /{f=0} f{print}' "$file" | tr -d '\r' | sed '/^[[:space:]]*$/d')"
-    ev_lc="$(printf '%s' "$ev" | tr '[:upper:]' '[:lower:]')"
-    [ -z "$ev" ] && empty_ev=1
-    case "$ev_lc" in *"(empty until done)"*|"---"|"--") empty_ev=1 ;; esac
+    local ev empty_ev=0 score=0
+    ev="$(_evidence_body "$file")"
+    if _evidence_is_empty "$ev"; then empty_ev=1; fi
     if [ "$empty_ev" -eq 1 ]; then
       echo "  [x] status is 'done' but ## Evidence is empty (paste world-state proof: URL/curl/DB row)"
       found=1
+    else
+      score="$(_evidence_signal_score "$ev" "${FLOW_PROJECT_ROOT:-$PWD}")"
+      if [ "$score" -lt 2 ]; then
+        echo "  [x] status is 'done' but ## Evidence has no world-state signal for type '$(get_project_type)' (score $score/2)"
+        echo "      (need ≥2 of: URL/curl-or-command/test-log/existing-path/DB-row/skill-path — not only PR/CI/process prose)"
+        echo "      hint: done means: $(done_def_for_type "$(get_project_type)")"
+        found=1
+      fi
     fi
   fi
 
@@ -1350,6 +1490,16 @@ cmd_project_type() {
   fi
   case "$arg" in
     web|cli|library|skill)
+      # After planning is complete AND an explicit type file exists, refuse silent
+      # type flips unless FLOW_FORCE=1 (D6). Default-web with no file is not "locked".
+      if planning_complete 2>/dev/null && [ -f "$PROJECT_TYPE_FILE" ]; then
+        local cur; cur="$(get_project_type)"
+        if [ -n "$cur" ] && [ "$cur" != "$arg" ] && [ "${FLOW_FORCE:-0}" != "1" ]; then
+          echo "FAIL: project type is locked to '$cur' after planning completes (would change done-evidence lens)."
+          echo "  re-set with FLOW_FORCE=1 if intentional, and record a DEBT.md line for the change."
+          return 1
+        fi
+      fi
       printf '%s\n' "$arg" > "$PROJECT_TYPE_FILE"; _ignore_run_state
       echo "PASS: project type set to '$arg'."
       echo "  done-evidence now means: $(done_def_for_type "$arg")"
@@ -1475,19 +1625,25 @@ cmd_ready() {
     [ "$st" = "todo" ] || continue
     deps="$(grep -m1 -E '^deps:' "$f" | sed 's/^deps:[[:space:]]*//' | tr -d '\r')"
     ok=1
-    # deps met if every referenced card is status done (normalize C-1 / C-001 to canonical path)
+    # deps met if every referenced card is status done AND Evidence passes world-state
+    # signal floor (hand-edit done without multi-signal cannot unblock dependents).
     for dep in $(printf '%s' "$deps" | grep -oiE 'C-[0-9]+' || true); do
       local depnum depfile
       depnum="${dep#C-}"; depnum="${depnum#c-}"
       case "$depnum" in (*[!0-9]*) continue;; esac
       depfile="$(printf '%s/C-%03d.md' "$CARDS_DIR" "$((10#$depnum))")"
-      if [ ! -f "$depfile" ] || [ "$(card_status "$depfile")" != "done" ]; then ok=0; fi
+      if [ ! -f "$depfile" ] || [ "$(card_status "$depfile")" != "done" ]; then
+        ok=0
+      elif ! _card_done_evidence_ok "$depfile"; then
+        ok=0
+        echo "  note: dep $(basename "$depfile" .md) is status=done but ## Evidence fails world-state signal (re-check or paste real proof)"
+      fi
     done
     if [ "$ok" -eq 1 ]; then
       echo "  BUILDABLE $id  (deps: ${deps:-none})"
       _card_allowed_files "$f" | sed 's/^/      allowed: /'
     else
-      echo "  blocked   $id  (deps not all done: ${deps:-none})"
+      echo "  blocked   $id  (deps unmet or evidence floor failed: ${deps:-none})"
     fi
   done
   return 0

package/skills-manifest.json

@@ -1,8 +1,8 @@
 {
   "source": "../skills/flow",
   "destRelative": "skills/flow",
-  "fileCount": 82,
-  "syncedAt": "2026-07-27T03:21:41.774Z",
+  "fileCount": 84,
+  "syncedAt": "2026-08-11T06:03:43.844Z",
   "fileList": [
     "SKILL.md",
     "_templates/00-idea.md",
@@ -22,6 +22,8 @@
     "eval/fixtures/fcda/cards/C-001.md",
     "eval/fixtures/fcdb/.flow/.gitkeep",
     "eval/fixtures/fcdb/cards/C-001.md",
+    "eval/fixtures/fcdc/.flow/.gitkeep",
+    "eval/fixtures/fcdc/cards/C-001.md",
     "eval/fixtures/routing/manifest.tsv",
     "eval/fixtures/routing/states/state-any-midproject.txt",
     "eval/fixtures/routing/states/state-cards-todo.txt",