@manhquy/flow-skill 0.1.0-rc.3 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to `@manhquy/flow-skill`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/).
 
+## [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
+publishes + independent verification; publishes to dist-tag **`latest`** so bare
+`npx @manhquy/flow-skill` / `npm i` resolves it (no manual dist-tag promotion needed).
+
+### Changed
+- Ships skill product **v0.24.0** (harness trust-align — honest `proof_source`, STRICT durable
+  modes, canonical harness skill; see root `CHANGELOG.md` `## 0.24.0`). rc.1–rc.3 shipped v0.22.0.
+- No installer code change vs rc.3 — same CLI, detection, lock, and five install targets
+  (Claude, Codex, Antigravity, Cursor, universal `~/.agents/skills`).
+
 ## [0.1.0-rc.3] — 2026-07-18
 
 Ships the same skill product **v0.22.0** as rc.2, plus pipeline/UX fixes found after the first

package/README.md

@@ -10,20 +10,24 @@ One-command installer that copies the [flow](https://github.com/manhquydev/flow-
 ## Install
 
 ```
-# Pre-release channel (current — v0.1.0-rc.3, ships skill v0.22.0)
+# 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
 ```
 
 An interactive prompt asks which agents to install to. Pick one or more, confirm, done.
 
-> **RC phase**: pin `@rc` (dist-tag) or a specific version like `@0.1.0-rc.3`. `npx @manhquy/flow-skill@0.1.x` will start working after stable `0.1.0` is published — semver ranges do **not** match pre-release tuples by default. See [SECURITY.md](./SECURITY.md).
+> **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).
 >
 > **`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@rc` or
+> package to `node_modules`. You must **run** it (`npx @manhquy/flow-skill` 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-rc.3`).
-> Skill product version lives in `skills/flow/SKILL.md` (`metadata.version`, e.g. `0.22.0`).
+> **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`).
 > `--help` and the JSONL `plan` event expose both (`version` + `skillVersion`).
 
 ## Non-interactive
@@ -93,8 +97,7 @@ 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.1.x`**: you are trying to install a pre-release version through a stable range. Use `@rc` (dist-tag) or an explicit `@0.1.0-rc.N` until stable `0.1.0` ships.
-- **`No matching version found` on `@0.22.0`**: that is the **skill product** version, not the npm package version. Use `@rc` / `@0.1.0-rc.N` (installer) — skill content version is printed by `--help` as `ships skill v…`.
+- **`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.
 - **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+.
 
@@ -103,7 +106,7 @@ rm -rf <project>/.claude/skills/flow
 `--json` streams one JSON object per line:
 
 ```jsonl
-{"event":"plan","version":"0.1.0-rc.3","skillVersion":"0.22.0","dryRun":false,"scope":"global","targets":["claude","codex"]}
+{"event":"plan","version":"0.1.0","skillVersion":"0.24.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,13 +10,18 @@ Trình cài đặt một-lệnh sao chép skill [flow](https://github.com/manhqu
 ## Cài đặt
 
 ```
-# Kênh pre-release (hiện tại — v0.1.0-rc.2)
+# 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
 ```
 
 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.
 
-> **Giai đoạn RC**: pin `@rc` (dist-tag) hoặc phiên bản cụ thể `@0.1.0-rc.2`. `npx @manhquy/flow-skill@0.1.x` chỉ dùng được sau khi stable `0.1.0` publish — semver range **không** match pre-release theo mặc định. Xem [SECURITY.md](./SECURITY.md).
+> **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).
+>
+> **`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).
 
 ## Non-interactive
 
@@ -95,7 +100,7 @@ Hợp đồng additive trong `0.1.x` — field mới có thể thêm, field cũ
 
 - **`EBUSY`/`EPERM` giữa install trên Windows**: một agent đang giữ handle vào file trong destination. Đóng agent + re-run. Installer đã retry 100/300/900 ms trước khi báo error.
 - **Advisory lock cũ**: run trước crash. Run mới tự phát hiện PID dead → reclaim. Trường hợp hiếm (PID được recycle bởi process khác đang chạy): xóa `<parent-of-dest>/.flow-skill.installing.lock`.
-- **`No matching version found` với `@0.1.x`**: cài pre-release qua stable range. Dùng `@rc` hoặc `@0.1.0-rc.N` cho tới khi stable `0.1.0` ship.
+- **`No matching version found` với `@0.24.0`**: đó là version **skill product**, không phải version npm package. Cài installer theo version của nó (bare / `@0.1.x` / `@rc`) — version skill in ra ở `--help` (`ships skill v…`).
 - **Node quá cũ** (`requires Node.js >=22.14.0`): update bằng `nvm install 22`, `fnm install 22`, hoặc installer chính thức của Node. Node 20 hết vòng đời từ 4/2026; npm OIDC Trusted Publishing cần npm >=11.5.1 (bundle theo Node 22.14+).
 
 ## Yêu cầu

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manhquy/flow-skill",
-  "version": "0.1.0-rc.3",
+  "version": "0.2.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.22.0"
+  version: "0.25.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)."
 ---
 
@@ -235,7 +235,7 @@ Hard stops (iteration/token/time caps) and ground-truth gates (`flow.sh` exit, r
 - `references/gate-eval.md` — `/flow eval` behavioral proof for the semantic layer: what it
   measures (a fresh-judge lower bound, NOT the work-mode self-challenge), cost, thresholds,
   and the honest authorship-bias limitation. Read before running or relaying a scorecard.
-- `harness/` — durable layer (`flow.sh harness ...`): intake/story/trace/decision/backlog. See `harness/README.md`. Read it back with `/flow recall` (open debt, retro, previous-card, friction, backlog, playbooks) — this is the capture→reuse loop.
+- `harness/` — durable layer (`flow.sh harness ...`): intake/story/**complete**/trace/decision/backlog. Pins: protocol floor `harness-cli-v0.1.14`, trust CLI `0.1.17` (never `0.1.16`). See `harness/README.md` + `harness/GAP-MATRIX-0.1.17.md`. Never `story update --status implemented` — use `story complete --proof-source …`.
 - `playbooks/` — paid-for stack knowledge: read before building a card on that stack, harvest the lesson after.
 - `_templates/` — the 7 artifacts the runner copies into `flow/` and `cards/`. Never edit during a run.
 

package/skills/flow/harness/GAP-MATRIX-0.1.17.md

@@ -0,0 +1,42 @@
+# Gap matrix: flow durable layer vs repository-harness CLI 0.1.17
+
+**Authority:** `repository-harness` (local `D:\project\flow\repository-harness`).  
+**Pins:** protocol floor **`harness-cli-v0.1.14`** · trust/consumer CLI **`harness-cli-v0.1.17`** · **never** install/use **`0.1.16`** release assets (tag without published proof).  
+**Scope:** inventory only — does **not** claim US-101 bit-identical or protocol-v1 parity for flow Python.
+
+Supersedes: brainstorm 260703 Thread1 (“nothing to upgrade”).
+
+## Schema
+
+| Ver | Flow | Harness 0.1.17 | Notes |
+|-----|------|----------------|-------|
+| 001–004 | present (shared) | present | Hash-identical at last measure (2026-07-18) |
+| 005 | present | present | File hash may differ on comments only — do not overclaim DDL fork |
+| 006–008 | **absent** (reserved gap) | changesets / deps / hierarchy | Not adopted this plan |
+| 009–012 | **usage/accessed** (flow-only) | improvement identity / links / closure | **Semantic collision** — same numbers, different DDL |
+| 013 | absent | changeset content sha | Not adopted — stays reserved/absent |
+| 014+ | **graph-executor** (flow-owned band) | absent | Flow-owned since the 2026-07-26 supersession (plan `260726-1718-harness-graph-executor-langgraph-port`) |
+
+## Commands / invariants
+
+| Surface | Flow status | Harness 0.1.17 | Trust note |
+|---------|-------------|----------------|------------|
+| `story update --status implemented` | rejected (trust-align) | rejected (US-101) | Use `story complete` |
+| `story complete` | flow-native flags + honest `proof_source` | `story complete` + live verify | Flow may complete via `card_markdown_gate` **without** setting `last_verified_result=pass` |
+| `story verify` | optional shell verify_command | required for shell-proven complete | shell=True = operator-authored only |
+| `query sql` | **not exposed** | read-only connection | Do not add mutating SQL |
+| Rust forward | refused on flow-lineage DB | n/a | `FLOW_HARNESS_BACKEND=rust` → exit 2 when usage mirror / schema≥9 |
+| Changesets / work-graph | **flow-owned graph executor** (schema band 014+) | 006–013 | **Superseded 2026-07-26** (was: out of scope, FOMO red line) — flow builds its own work-graph; upstream 006–013 will NOT be adopted. Decision record: plan `260726-1718-harness-graph-executor-langgraph-port` |
+| `query contract --json` | not on Python CLI | protocol v1 discovery | Optional external binary smoke only |
+
+## Pins (consumer)
+
+```
+HARNESS_PROTOCOL_V1_TAG = harness-cli-v0.1.14   # floor
+HARNESS_CLI_TRUST_TAG   = harness-cli-v0.1.17   # trust features + release proof
+DO_NOT_USE              = harness-cli-v0.1.16   # no assets / failed promotion
+```
+
+## Rust refuse-forward
+
+Any DB with `usage_event` or `MAX(schema_version) >= 9` is **flow-lineage**. Python entrypoint must refuse forwarding to external `harness-cli` (exit 2). `graph` verbs are NEVER forwarded regardless of DB state (flow-only surface, band 014+). The former "schema re-home ≥014 (separate epic)" note is superseded 2026-07-26: 014+ is now the flow-owned graph-executor band; 013 remains reserved/absent.

package/skills/flow/harness/README.md

@@ -2,10 +2,20 @@
 
 The durable memory of `/flow`: intake classification, story packets with proof status,
 auto-scored execution traces, decision records, and the growth-rule backlog. Ported from
-`repository-harness` (same SQLite schema, `schema/00N-*.sql` verbatim). State lives at
+`repository-harness` (shared base schema + flow-only usage extensions). State lives at
 `<project>/.flow/harness.db` and survives across sessions — this is the "external memory"
 that fights context rot.
 
+## Authority pins (repository-harness)
+
+| Pin | Tag | Use |
+|-----|-----|-----|
+| Protocol floor | **`harness-cli-v0.1.14`** | protocol v1 discovery floor |
+| Trust / consumer | **`harness-cli-v0.1.17`** | US-101 spirit + release proof |
+| **Do not use** | `harness-cli-v0.1.16` | tag without published assets |
+
+Gap inventory: [`GAP-MATRIX-0.1.17.md`](./GAP-MATRIX-0.1.17.md). Flow does **not** claim bit-identical US-101.
+
 ## Backends
 
 | Backend | When | How |
@@ -22,13 +32,61 @@ message). Use the Python backend for flow projects. The seam stays in code as a
 power-path for non-flow DBs; flow does not build or ship the binary.
 
 Disable the durable layer entirely with `FLOW_HARNESS_DISABLE=1` (engine still runs).
+**Python floor: 3.7** (measured, not asserted — `subprocess.run(capture_output=, text=)`;
+no walrus/match/builtin generics). `scripts/release-preflight.sh` enforces it, and
+`docs/migration-v1.md` records what a python-mandatory v1 would change.
+
+**Topology pin.** `pins/flow-topology.sha256` pins the canonical-JSON sha256 of
+`references/flow-topology.json`; graph verbs refuse to run on a mismatch (topology is
+executable-adjacent data). After an INTENTIONAL topology edit, run `graph lint` and
+regenerate from the repo root:
+
+```
+PY="$(command -v python3 || command -v python)"   # same cascade flow.sh _python() uses
+"$PY" -c "import json,hashlib;print(hashlib.sha256(json.dumps(json.load(open('skills/flow/references/flow-topology.json')),sort_keys=True,separators=(',',':')).encode()).hexdigest()+'  flow-topology.json')" > skills/flow/harness/pins/flow-topology.sha256
+```
+
+**DB location.** `<FLOW_PROJECT_ROOT>/.flow/harness.db`, with two graph-era rules: a root inside
+a LINKED git worktree is translated to its main-worktree equivalent (all parallel cards share one
+DB). Not translated — each worktree keeps its own DB — for submodules and for
+`--separate-git-dir` repos, where git reports the separate git dir as the main worktree and the
+checkout path is not discoverable; guessing there would put durable state inside `.git`.
+`FLOW_HARNESS_DB=<path>`
+is a narrow test/tool override of the DB path only — never repurpose `FLOW_PROJECT_ROOT` for
+this. Worktree telemetry merges at workspace-remove time via
+`rollup --src <sink> --src-key "<main events.jsonl>#<branch>#<created_at>"` (lifecycle-unique;
+prefixed with the destination sink so `usage`/`prune` see the rows).
+
+### STRICT durable writes (`flow.sh`)
+
+| Env | Behavior |
+|-----|----------|
+| unset | soft: engine exit 0; one-line `flow-harness: warn` on fail |
+| `FLOW_HARNESS_STRICT=1` | soft exit; louder stderr |
+| `FLOW_HARNESS_STRICT=fail` | propagate nonzero from durable ops on card/check |
+
+## Story completion (trust boundary)
+
+- **Rejected:** `story update --status implemented`
+- **Use:** `story complete --id <id> --proof-source card_markdown_gate|manual|verify_command [--evidence …]`
+- `card_markdown_gate` / `manual` set status implemented with **honest** `proof_source=…` in notes — **never** forge `last_verified_result=pass`
+- `verify_command` requires prior `story verify` pass
+
+## Versioning (harness vs npm)
+
+- Telemetry / usage events carry **`flow_version` from the installed skill product**
+  (`SKILL.md` metadata), not from the npm installer package version.
+- When you change harness schema or CLI behavior, bump the **skill product** version
+  (SKILL.md + plugin.json + portable-manifest) and run `flow.sh coherence`.
+- Publishing a new npm tarball is a separate step (`npm-wrapper` sync + tag `npm@…`) —
+  see [`docs/release-process.md`](../../../docs/release-process.md).
 
 ## Commands ↔ Runtime-Substrate responsibility
 
 | Command | Responsibility (of 11) |
 |---|---|
 | `intake --type <t> --summary <s> [--flags ...] [--lane ...] [--narrow-scope]` | Task specification + risk classification |
-| `story add\|update\|verify\|verify-all` | Task state + Verification (mechanical proof) |
+| `story add\|update\|complete\|verify\|verify-all` | Task state + Verification (mechanical proof) |
 | `trace --summary ... [--story\|--card C-NNN] [--agent ...] [--actions ...] [--files-changed ...] --outcome ...` | Observability + Failure attribution (auto-scored tier). Flags accept `-` or `_` (`--actions_taken`, `--files_changed`, `--files_read`) and `--card` is an alias of `--story`. A bad/missing flag prints a guiding "common forms" hint (not a silent exit-2). |
 | `decision add\|verify\|outcome` | Project memory (durable ADR row + companion markdown); `outcome` closes the predicted-vs-actual loop |
 | `backlog add\|close` | Entropy auditing + harness self-improvement (growth rule) |
@@ -60,7 +118,7 @@ Linking a trace to an unverified story prints a **pre-close gate** warning.
 - `/flow next` past **stage 04 (ADR)** → reminds you to record each decision durably (`decision add`) — the ADR markdown is not a durable record.
 - `/flow card` creates a card → seeds a `story` row (tracking handle).
 - `/flow check C-NNN` (todo) → `story update --status in_progress`.
-- `/flow check C-NNN` (done) → `story update --status implemented` + a `trace` (its **tier verdict is shown**, so thin traces are visible).
+- `/flow check C-NNN` (done) → `story complete --proof-source card_markdown_gate` + a `trace` (tier verdict shown; honest provenance, no shell-verify stamp).
 - `/flow recall` → reads the durable layer back (friction + backlog + audit health) into your working context — the capture→reuse loop.
 - `/flow retro` → surfaces `propose` (deterministic improvement proposals from repeated friction/interventions + audit drift) for you to commit.
 - `/flow harness <args>` exposes the full CLI directly.
@@ -113,5 +171,8 @@ stage_from→to, card, project_type, mode, flow_version, tier, host, read_only.
 - `schema/00N-*.sql` — DDL. **001-005 are a faithful port of repository-harness** (005 =
   tool-extensions, kind-aware tool registry). **009-012 are flow-specific** (accessed-count +
   usage-log mirror), re-homed off 005-008 so the upstream 005 number is free and the lineages no
-  longer collide. Migrations are column-idempotent and safe to re-run; an old DB built under the
-  pre-005 numbering is reconciled automatically on the next `init`.
+  longer collide. **014+ is the flow-owned graph-executor band** (2026-07-26 supersession of the
+  work-graph red line — see GAP-MATRIX; 013 stays reserved/absent). Migrations are
+  column-idempotent and safe to re-run; an old DB built under the pre-005 numbering is
+  reconciled automatically on the next `init`.
+- `graph_ids.py` — monotonic, lexicographically sortable ids for graph-executor rows (stdlib).

package/skills/flow/harness/_db.py

@@ -1,19 +1,113 @@
 """SQLite durable layer for the flow harness (stdlib sqlite3 only).
 
 Schema lives in schema/00N-*.sql (001-005 a faithful port of repository-harness; 009-012
-flow-specific: accessed-count + usage-log mirror) and is applied by missing-version set; each
-migration bumps schema_version and statements are idempotent, so init/upgrade is safe to re-run.
-DB path defaults to <FLOW_PROJECT_ROOT>/.flow/harness.db.
+flow-specific: accessed-count + usage-log mirror; 014+ flow-owned graph-executor band) and is
+applied by missing-version set; each migration bumps schema_version and statements are
+idempotent, so init/upgrade is safe to re-run. DB path defaults to
+<FLOW_PROJECT_ROOT>/.flow/harness.db, translated to the MAIN worktree when the root sits
+inside a linked git worktree so every parallel card shares one DB.
 """
 
+import contextlib
 import os
 import re
 import sqlite3
+import subprocess
+import time
 
 SCHEMA_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "schema")
 
 
+_worktree_main_cache = {}
+
+
+def _git_env():
+    """Strip inherited GIT_DIR/GIT_WORK_TREE (exported by every git hook, `rebase -x`,
+    `bisect run`, `submodule foreach`): with them set, git answers about a FOREIGN repo
+    and the worktree translation silently splits the journal."""
+    env = dict(os.environ)
+    for k in ("GIT_DIR", "GIT_WORK_TREE", "GIT_COMMON_DIR", "GIT_INDEX_FILE",
+              "GIT_OBJECT_DIRECTORY", "GIT_ALTERNATE_OBJECT_DIRECTORIES"):
+        env.pop(k, None)
+    return env
+
+
+def _linked_worktree_main_root(root):
+    """Map `root` inside a LINKED git worktree to its main-worktree equivalent path, else None.
+
+    Card worktrees are full checkouts (they contain flow/ + cards/), so without this
+    translation every parallel card mints its own throwaway .flow/harness.db that
+    `git worktree remove` then deletes. Keys on the RESOLVED ROOT (never CWD — flow.sh
+    passes FLOW_PROJECT_ROOT per call and the two are independent). Cached per process:
+    this runs on every connect and an uncached `git` spawn multiplies on Windows.
+    Any failure (git absent, git < 2.31, not a repo) returns None = current behavior.
+    """
+    if root in _worktree_main_cache:
+        return _worktree_main_cache[root]
+    out = None
+    try:
+        r = subprocess.run(
+            ["git", "-C", root, "rev-parse", "--path-format=absolute",
+             "--git-dir", "--git-common-dir", "--show-toplevel"],
+            capture_output=True, text=True, timeout=10, env=_git_env(),
+        )
+        git_dir = common_dir = worktree_top = None
+        if r.returncode == 0:
+            vals = [ln.strip() for ln in r.stdout.splitlines() if ln.strip()]
+            if len(vals) >= 3:
+                git_dir, common_dir, worktree_top = vals[0], vals[1], vals[2]
+        elif "not a git repository" not in (r.stderr or "").lower():
+            # git < 2.31 lacks --path-format (declared floor); best-effort re-derive.
+            # Gated on the failure NOT being "not a repo" so non-git roots cost one spawn.
+            def _rp(flag):
+                q = subprocess.run(["git", "-C", root, "rev-parse", flag], env=_git_env(),
+                                   capture_output=True, text=True, timeout=10)
+                return q.stdout.strip() if q.returncode == 0 and q.stdout.strip() else None
+            git_dir = _rp("--absolute-git-dir")
+            common_dir = _rp("--git-common-dir")
+            worktree_top = _rp("--show-toplevel")
+            if common_dir and not os.path.isabs(common_dir):
+                common_dir = os.path.abspath(os.path.join(root, common_dir))
+        if git_dir and common_dir and worktree_top:
+            # Linked worktree iff the per-worktree git dir differs from the shared common
+            # dir. Submodules and --separate-git-dir repos have git_dir == common_dir (both
+            # live OUTSIDE the worktree) and must never be translated - dirname(common_dir)
+            # is git internals there, not a project root. realpath everywhere: macOS mktemp
+            # and symlinked checkouts otherwise fail the containment compare silently.
+            if os.path.realpath(git_dir) != os.path.realpath(common_dir):
+                wt = subprocess.run(["git", "-C", root, "worktree", "list", "--porcelain"], env=_git_env(),
+                                    capture_output=True, text=True, timeout=10)
+                first = next((ln for ln in wt.stdout.splitlines()
+                              if ln.startswith("worktree ")), "") if wt.returncode == 0 else ""
+                main_top = first[len("worktree "):].strip()  # main worktree is always first
+                # --separate-git-dir: the main `.git` is a FILE, so git itself reports the
+                # separate git dir as the "main worktree" and does not record the checkout
+                # anywhere discoverable (core.worktree is unset). Translating would put the
+                # DB inside git internals, so REFUSE instead of guessing: the worktree keeps
+                # its own DB (pre-graph behavior), documented in README, rather than
+                # corrupting state. A real checkout always has a `.git` entry.
+                if main_top and not os.path.exists(os.path.join(main_top, ".git")):
+                    main_top = ""
+                rr = os.path.realpath(root)
+                wtop = os.path.realpath(worktree_top)
+                inside = rr == wtop or rr.startswith(wtop + os.sep)
+                if main_top and inside:
+                    main_top = os.path.realpath(main_top)
+                    rel = os.path.relpath(rr, wtop)
+                    out = main_top if rel == "." else os.path.join(main_top, rel)
+    except Exception:
+        out = None  # best-effort: never break the python path over the resolver
+    _worktree_main_cache[root] = out
+    return out
+
+
 def default_db_path(root=None):
+    # Narrow override for tests/tools: DB path ONLY. Never FLOW_PROJECT_ROOT — that is
+    # the global root override and repurposing it would hijack CARDS_DIR/lock/DEBT
+    # resolution for every flow.sh call in a worktree.
+    override = os.environ.get("FLOW_HARNESS_DB")
+    if override:
+        return override
     root = root or os.environ.get("FLOW_PROJECT_ROOT") or os.getcwd()
     # On native Windows Python, translate a Git Bash POSIX root like /c/proj -> c:/proj
     # so the db lands under the project (not relative to the current drive root). Only
@@ -22,6 +116,9 @@ def default_db_path(root=None):
         m = re.match(r"^/([a-zA-Z])/(.*)$", root)
         if m:
             root = m.group(1) + ":/" + m.group(2)
+    main_equiv = _linked_worktree_main_root(root)
+    if main_equiv:
+        root = main_equiv
     return os.path.join(root, ".flow", "harness.db")
 
 
@@ -100,6 +197,9 @@ def connect(db_path=None, root=None, auto_migrate=True):
     con = sqlite3.connect(db_path)
     con.row_factory = sqlite3.Row
     con.execute("PRAGMA foreign_keys = ON")
+    # Explicit 5s wait for the write lock: two parallel card workers share one DB
+    # (worktree-translated path), so contention must queue, not raise `database is locked`.
+    con.execute("PRAGMA busy_timeout = 5000")
     if auto_migrate:
         migrate(con)
     return con
@@ -126,9 +226,25 @@ def _apply_migration(con, sql):
     pragmas = [s for s in stmts if s.upper().startswith("PRAGMA")]
     ddl = [s for s in stmts if not s.upper().startswith("PRAGMA")]
     for p in pragmas:
-        con.execute(p)
+        # Belt-and-braces retry (a pragma can still meet a busy DB on a cold start).
+        for attempt in range(20):
+            try:
+                con.execute(p)
+                break
+            except sqlite3.OperationalError as e:
+                if "locked" not in str(e).lower() and "busy" not in str(e).lower():
+                    raise
+                if attempt == 19:
+                    raise
+                time.sleep(0.05 * (attempt + 1))
     try:
-        con.execute("BEGIN")
+        # IMMEDIATE, not deferred: a deferred BEGIN takes SHARED on the first read probe
+        # (_idempotent_statement inspects sqlite_master/table_info) and the later DDL must
+        # upgrade SHARED->RESERVED - an upgrade SQLite refuses with SQLITE_BUSY IMMEDIATELY,
+        # bypassing the busy handler, so busy_timeout never applies. Taking RESERVED up
+        # front puts the wait where busy_timeout can cover it. This is what made cold-start
+        # parallel card workers lose records.
+        con.execute("BEGIN IMMEDIATE")
         for s in ddl:
             stmt = _idempotent_statement(con, s)
             if stmt is None:
@@ -136,7 +252,10 @@ def _apply_migration(con, sql):
             con.execute(stmt)
         con.execute("COMMIT")
     except Exception:
-        con.execute("ROLLBACK")
+        # rollback(), not execute("ROLLBACK"): if BEGIN IMMEDIATE itself failed there is no
+        # active transaction, and the raw statement would raise "cannot rollback", masking
+        # the original lock error.
+        con.rollback()
         raise
 
 
@@ -219,6 +338,56 @@ def update(con, table, id_col, id_val, **cols):
     return cur.rowcount
 
 
+def update_where(con, table, where, **cols):
+    # SECURITY INVARIANT: `table` and every key in `where`/`cols` must be code literals,
+    # never user input. Composite-key variant of update() for the graph tables whose
+    # primary keys span (execution_id, ns, ...); update()'s single id_col cannot address them.
+    sets, vals = [], []
+    for k, v in cols.items():
+        if v is not None:
+            sets.append(f"{k} = ?")
+            vals.append(v)
+    if not sets:
+        return 0
+    conds = []
+    for k, v in where.items():
+        if v is None:
+            # `col = NULL` never matches in SQL - a None key would silently update nothing.
+            raise ValueError(f"update_where: where[{k!r}] is None")
+        conds.append(f"{k} = ?")
+        vals.append(v)
+    sql = f"UPDATE {table} SET {', '.join(sets)} WHERE {' AND '.join(conds)}"
+    cur = con.execute(sql, vals)
+    con.commit()
+    return cur.rowcount
+
+
+@contextlib.contextmanager
+def transaction(con):
+    """Multi-row atomicity: BEGIN IMMEDIATE ... COMMIT/ROLLBACK.
+
+    IMMEDIATE takes the write lock up front so concurrent worktree writers queue on
+    busy_timeout instead of failing mid-transaction. Do NOT call insert()/update()/
+    update_where() inside this block — their per-call con.commit() would end the
+    transaction early; use con.execute directly. An already-open transaction at entry
+    RAISES (this helper never commits or discards a caller's pending work). The
+    except-path uses con.rollback(), a no-op when SQLite already auto-rolled-back
+    (disk full / IO error), so the ORIGINAL exception always propagates.
+    """
+    if con.in_transaction:
+        raise sqlite3.ProgrammingError(
+            "transaction(): connection already has an open transaction - "
+            "commit or roll it back before entering this block"
+        )
+    con.execute("BEGIN IMMEDIATE")
+    try:
+        yield con
+        con.commit()
+    except Exception:
+        con.rollback()
+        raise
+
+
 def rows(con, sql, params=()):
     return [dict(r) for r in con.execute(sql, params).fetchall()]