@manhquy/flow-skill 0.1.0-rc.3 → 0.1.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_VN.md

@@ -10,13 +10,15 @@ 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)
+# Kênh pre-release (hiện tại — v0.1.0-rc.3, ships skill v0.22.0)
 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).
+> **Giai đoạn RC**: pin `@rc` (dist-tag) hoặc phiên bản cụ thể `@0.1.0-rc.3`. `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).
+>
+> **`npm i` alone chưa đủ** — phải **chạy** CLI (`npx @manhquy/flow-skill@rc`). Hai trục version: package npm vs skill product (`ships skill v…` / `skillVersion` trong JSONL).
 
 ## Non-interactive
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manhquy/flow-skill",
-  "version": "0.1.0-rc.3",
+  "version": "0.1.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.24.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,41 @@
+# 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 |
+
+## 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 | not ported | 006–013 | Out of scope (FOMO red line) |
+| `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). Never unfreeze on `.flow/harness.db` without schema re-home ≥014 (separate epic).

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 |
@@ -23,12 +33,36 @@ 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).
 
+### 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 +94,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.

package/skills/flow/harness/flow_harness.py

@@ -160,6 +160,21 @@ def cmd_intake(con, a):
     return 0
 
 
+_PROOF_SOURCES = ("card_markdown_gate", "manual", "verify_command")
+_SECRET_RE = re.compile(
+    r"(?i)(token|secret|passwd|password|credential|api[_-]?key|bearer|authorization|-----begin)"
+)
+
+
+def _mask_evidence(text):
+    """Redact secret-shaped free text before durable store (trust-align RT)."""
+    if text is None:
+        return None
+    if _SECRET_RE.search(text):
+        return "***redacted***"
+    return text
+
+
 def cmd_story(con, a):
     if a.story_cmd == "add":
         if a.lane not in D.LANES:
@@ -169,11 +184,58 @@ def cmd_story(con, a):
         print(f"PASS: story {a.id} added (lane={a.lane})")
         return 0
     if a.story_cmd == "update":
+        # Trust boundary (US-101 spirit, flow-native): bare implemented is forbidden.
+        if a.status == "implemented":
+            print(
+                "FAIL: story update --status implemented is rejected.\n"
+                "  Use: story complete --id <id> --proof-source card_markdown_gate|manual|verify_command\n"
+                "  (honest proof provenance; never forge last_verified_result without story verify)"
+            )
+            return 1
         n = _db.update(con, "story", "id", a.id, status=a.status,
                        unit_proof=a.unit, integration_proof=a.integration,
-                       e2e_proof=a.e2e, platform_proof=a.platform, evidence=a.evidence)
+                       e2e_proof=a.e2e, platform_proof=a.platform,
+                       evidence=_mask_evidence(a.evidence))
         print(f"{'PASS' if n else 'FAIL'}: story {a.id} {'updated' if n else 'not found'}")
         return 0 if n else 1
+    if a.story_cmd == "complete":
+        s = _db.one(con, "SELECT * FROM story WHERE id=?", (a.id,))
+        if not s:
+            print(f"FAIL: story {a.id} not found"); return 1
+        src = (a.proof_source or "").strip()
+        if src not in _PROOF_SOURCES:
+            print(
+                "FAIL: --proof-source required: card_markdown_gate|manual|verify_command\n"
+                "  card_markdown_gate = /flow check markdown gate (does NOT set last_verified=pass)\n"
+                "  verify_command     = requires prior story verify pass"
+            )
+            return 1
+        if src == "verify_command":
+            if s.get("last_verified_result") != "pass":
+                print(
+                    f"FAIL: proof-source verify_command requires last_verified_result=pass "
+                    f"(got {s.get('last_verified_result')!r}). Run: story verify --id {a.id}"
+                )
+                return 1
+        # Honest provenance: card/manual never forge last_verified_result=pass
+        ev = _mask_evidence(a.evidence) or s.get("evidence") or ""
+        note = (s.get("notes") or "").strip()
+        prov = f"proof_source={src}"
+        if prov not in note:
+            note = (note + "\n" + prov).strip() if note else prov
+        if src == "card_markdown_gate" and "last_verified_result=pass" not in (note or ""):
+            # explicit honesty marker for auditors
+            note = note + "\nverify_stamp=not_shell"
+        fields = dict(status="implemented", notes=note)
+        if ev:
+            fields["evidence"] = ev
+        # only keep last_verified_* when real verify already passed
+        n = _db.update(con, "story", "id", a.id, **fields)
+        print(
+            f"PASS: story {a.id} complete (status=implemented, proof_source={src})"
+            + ("" if src == "verify_command" else " [no shell-verify stamp]")
+        )
+        return 0 if n else 1
     if a.story_cmd in ("verify", "verify-all"):
         if a.story_cmd == "verify":
             stories = [_db.one(con, "SELECT * FROM story WHERE id=?", (a.id,))]
@@ -983,6 +1045,13 @@ def build_parser():
     a2.add_argument("--evidence")
     a3 = pss.add_parser("verify"); a3.add_argument("--id", required=True)
     pss.add_parser("verify-all")
+    # flow-native complete (trust-align D7): not protocol-v1 positional parity
+    ac = pss.add_parser("complete", help="mark implemented with honest proof_source (not bare update)")
+    ac.add_argument("--id", required=True)
+    ac.add_argument("--proof-source", dest="proof_source",
+                    choices=("card_markdown_gate", "manual", "verify_command"),
+                    help="card_markdown_gate never forges last_verified=pass")
+    ac.add_argument("--evidence")
 
     pt = sub.add_parser("trace", help="record an agent task execution trace (auto-scored)")
     pt.add_argument("--summary", required=True); pt.add_argument("--intake", type=int); pt.add_argument("--story", "--card")

package/skills/flow/harness/pins/harness-cli-v0.1.17.sha256sums

@@ -0,0 +1,9 @@
+# Digests from GitHub Release harness-cli-v0.1.17 (fetched for pin policy)
+# TAG harness-cli-v0.1.17
+# PROTOCOL_FLOOR harness-cli-v0.1.14
+# DO_NOT_USE harness-cli-v0.1.16
+5d13f0a024d9d69701534a879581c9433bc0069e04d052e5aacd93b91b3b7a43  harness-cli-linux-x64
+128c42c251fb31b58582342c09c68be6ed3329340fb1d8f179c88590a4539c97  harness-cli-linux-arm64
+902968f1383d45eb60e202eb98f8ce6c143cff73cb6f2ccc159a743ca5a70819  harness-cli-macos-x64
+71217dbe03d111775c5016ab751f8bedbff66e7fd6a4d90f5c8d7e0e4a205b47  harness-cli-macos-arm64
+2d7edff22ae25308c2ba23ab85bb9acb18d87eea28a9ca4efb2014a0f11a51a6  harness-cli-windows-x64.exe

package/skills/flow/references/agent-stage-mapping.md

@@ -54,7 +54,7 @@ gate): **`ck-predict` at ADR** (5-persona pre-decision debate) and **`ck-scenari
 | UI card | `ui-ux-designer` | — | inline + `law/DESIGN.md` | review vs DESIGN.md |
 | Repair / diagnostic | `debugger` | — | inline root-cause + fresh same-ladder subagent | `harness intervention add` |
 | Review | `code-reviewer` (+ `typescript-reviewer` or `python-reviewer` layered — see language-specialist lens) | `bmad-code-review` (3-layer adversarial) | inline | `harness intervention add` on red |
-| Deploy / git ship | `git-manager` | — | inline commit + PR guide | `harness story update --status implemented` |
+| Deploy / git ship | `git-manager` | — | inline commit + PR guide | `harness story complete --id … --proof-source manual` (never bare `update --status implemented`) |
 | Docs sync | `docs-manager` | — | inline doc update | — |
 | Verify-live | `tester` / `web-testing` | `bmad-qa-generate-e2e-tests` | curl/Playwright | `harness story update --e2e 1` + `trace` |
 

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

@@ -34,7 +34,7 @@ for each todo card in card-number order:
   4. flow.sh check C-NNN must PASS (mechanical) + gate-rules semantic check
   5. merge to main in card order; deploy; VERIFY ON LIVE URL (merge != shipped)
   6. paste world-state evidence into the card; status: done
-  7. flow.sh harness story update --status implemented + trace; log AUTO-LOG.md
+  7. flow.sh harness story complete --id … --proof-source manual (or card_markdown_gate) + trace; log AUTO-LOG.md
   8. remove worktree
 ```
 

package/skills/flow/runner/flow.sh

@@ -180,15 +180,71 @@ _python() {
   return 1
 }
 
-harness_call() {
-  # best-effort durable-layer write; NEVER breaks the engine if python/harness absent.
+# Durable write honesty (plan trust-align D5/D8):
+#   unset FLOW_HARNESS_STRICT  → soft: engine stays 0; one-line stderr warn on fail
+#   FLOW_HARNESS_STRICT=1      → soft exit; louder multi-line stderr
+#   FLOW_HARNESS_STRICT=fail   → propagate nonzero from harness (card/check paths)
+# harness_call_checked always returns the real harness exit (for callers that care).
+_harness_run() {
+  # runs harness; prints stderr (masked lightly); echoes nothing; returns real rc
+  # usage: _harness_run <args...>   sets _HARNESS_LAST_RC
+  _HARNESS_LAST_RC=0
   [ -n "${FLOW_HARNESS_DISABLE:-}" ] && return 0
   [ -f "$HARNESS_PY" ] || return 0
   local py; py="$(_python)"; [ -n "$py" ] || return 0
-  FLOW_PROJECT_ROOT="$ROOT" "$py" "$HARNESS_PY" "$@" >/dev/null 2>&1
+  local errf out rc=0
+  errf="$(mktemp 2>/dev/null || echo "$ROOT/.flow/.harness-err.$$")"
+  mkdir -p "$ROOT/.flow" 2>/dev/null || true
+  # capture rc without flipping the caller's set -e state
+  out="$(FLOW_PROJECT_ROOT="$ROOT" "$py" "$HARNESS_PY" "$@" 2>"$errf")" || rc=$?
+  _HARNESS_LAST_RC=$rc
+  if [ "$rc" -ne 0 ]; then
+    local errline summary
+    errline="$(tr -d '\r' <"$errf" 2>/dev/null | head -n 3 | tr '\n' ' ')"
+    # light redact of secret-shaped stderr / never dump free-text evidence args
+    case "$errline" in
+      *token*|*secret*|*passwd*|*password*|*credential*|*api_key*|*bearer*) errline="***redacted***" ;;
+    esac
+    summary="$1"
+    [ -n "${2:-}" ] && summary="$summary $2"
+    [ -n "${3:-}" ] && summary="$summary $3"
+    local mode="${FLOW_HARNESS_STRICT:-}"
+    if [ "$mode" = "1" ] || [ "$mode" = "fail" ]; then
+      printf 'flow-harness: durable command failed (rc=%s) cmd=%s\nflow-harness: %s\n' \
+        "$rc" "$summary" "$errline" >&2
+    else
+      printf 'flow-harness: warn durable write failed (rc=%s)\n' "$rc" >&2
+    fi
+  fi
+  rm -f "$errf" 2>/dev/null || true
+  return "$rc"
+}
+
+harness_call() {
+  # soft durable write: NEVER breaks engine unless STRICT=fail
+  _harness_run "$@" || true
+  if [ "${FLOW_HARNESS_STRICT:-}" = "fail" ] && [ "${_HARNESS_LAST_RC:-0}" -ne 0 ]; then
+    return "${_HARNESS_LAST_RC}"
+  fi
   return 0
 }
 
+harness_call_checked() {
+  # returns real harness exit code (and still prints STRICT-aware warnings)
+  _harness_run "$@"
+}
+
+# When STRICT=fail, surface durable failure from card/check call sites (D5).
+_harness_or_fail() {
+  harness_call "$@" || {
+    if [ "${FLOW_HARNESS_STRICT:-}" = "fail" ]; then
+      echo "FAIL: durable harness write failed (FLOW_HARNESS_STRICT=fail)."
+      return 1
+    fi
+    return 0
+  }
+}
+
 harness_available() { # 0 = durable layer usable (python + harness present, not disabled)
   [ -n "${FLOW_HARNESS_DISABLE:-}" ] && return 1
   [ -f "$HARNESS_PY" ] || return 1
@@ -973,7 +1029,7 @@ cmd_card_start() { # mark a card actively in progress (operator-visible in_progr
   local id; id="$(basename "$file" .md)"; FLOW_LOG_CARD="$id"
   if [ "$(card_status "$file")" = "done" ]; then echo "FAIL: $id is already done — nothing to start."; return 1; fi
   _inflight_set "$id"
-  harness_call story update --id "$id" --status in_progress   # durable mirror (best-effort)
+  _harness_or_fail story update --id "$id" --status in_progress   # durable mirror (STRICT=fail propagates)
   echo "PASS: $id marked in flight. Build it, then '/flow card done $id' (or hand-edit status: done + '/flow check $id')."
   return 0
 }
@@ -1033,7 +1089,7 @@ cmd_card() {
     [ -n "$pc" ] && printf '%s\n' "$pc" | sed 's/^/  /'
     [ -n "$dbt" ] && { echo "  open debt:"; printf '%s\n' "$dbt" | sed 's/^/    /'; }
   fi
-  harness_call story add --id "$id" --title "$id" --lane normal   # durable tracking handle
+  _harness_or_fail story add --id "$id" --title "$id" --lane normal   # durable tracking handle
   return 0
 }
 
@@ -1106,9 +1162,22 @@ cmd_check() {
   if [ "$found" -eq 0 ]; then
     echo "PASS: $id is valid (status: $st)."
     case "$st" in
-      todo) harness_call story update --id "$id" --status in_progress ;;
-      done) harness_call story update --id "$id" --status implemented
-            local tr; tr="$(harness_emit trace --summary "card $id reached done-evidence" --story "$id" --outcome completed)"
+      todo) _harness_or_fail story update --id "$id" --status in_progress || return 1 ;;
+      done)
+            # trust-align: complete with honest card_markdown_gate provenance (D3/D7/D8)
+            if ! harness_call_checked story complete --id "$id" \
+                  --proof-source card_markdown_gate \
+                  --evidence "card $id markdown gate PASS"; then
+              if [ "${FLOW_HARNESS_STRICT:-}" = "fail" ]; then
+                echo "FAIL: durable story complete failed (FLOW_HARNESS_STRICT=fail)."
+                return 1
+              fi
+            fi
+            # auto-trace: enrich tier-2 fields from known card context (do not fake --lane tiny)
+            local tr
+            tr="$(harness_emit trace --summary "card $id reached done-evidence" --story "$id" \
+                  --outcome completed --agent flow-check \
+                  --actions "check $id gate PASS" --files-changed "cards/$id.md" --friction none)"
             [ -n "$tr" ] && printf '%s\n' "$tr" | grep -iE 'tier|to reach' | sed 's/^/  harness: /' ;;
     esac
     return 0

package/skills-manifest.json

@@ -1,8 +1,8 @@
 {
   "source": "../skills/flow",
   "destRelative": "skills/flow",
-  "fileCount": 74,
-  "syncedAt": "2026-07-18T07:42:58.153Z",
+  "fileCount": 76,
+  "syncedAt": "2026-07-19T14:46:19.032Z",
   "fileList": [
     "SKILL.md",
     "_templates/00-idea.md",
@@ -31,11 +31,13 @@
     "eval/fixtures/routing/states/state-review-pending.txt",
     "eval/fixtures/routing/states/state-scope-stage.txt",
     "eval/manifest.tsv",
+    "harness/GAP-MATRIX-0.1.17.md",
     "harness/README.md",
     "harness/_db.py",
     "harness/_domain.py",
     "harness/_presence.py",
     "harness/flow_harness.py",
+    "harness/pins/harness-cli-v0.1.17.sha256sums",
     "harness/repo_map.py",
     "harness/schema/001-init.sql",
     "harness/schema/002-story-verify.sql",