@manhquy/flow-skill 0.1.0-rc.2 → 0.1.0

package/CHANGELOG.md

@@ -2,7 +2,42 @@
 
 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-rc.2] — 2026-07-17 (not yet published — see release command below)
+## [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
+OIDC publish + independent verification.
+
+### Fixed
+- **Nightly registry health false-red:** `scripts/smoke.mjs` ran `npx` from inside
+  `npm-wrapper/`, so npx resolved the **local workspace package** instead of the registry
+  (`flow-skill: not found`) even when the published package was healthy. Smoke now uses an
+  empty temp cwd + `npx --package=… flow-skill`; nightly runs from `$RUNNER_TEMP`.
+- **CI bash-suite Windows cancelled at 15m:** full 33-suite run needs ~20–25m on Windows Git
+  Bash (measured run `29630992330` — mid-`test_flow_eval` when cut). `timeout-minutes` is now
+  **30 on windows-latest**, 15 elsewhere. `tests/run_all.sh` prints per-suite `wall_s`.
+- **`promote_to`:** early-exit before install/test (no full job burn); input description states
+  it is **manual-only** (OIDC cannot `npm dist-tag add` — E401 on run `29556075144`).
+
+### Added
+- Dual-version UX: `--help` shows `flow-skill v<pkg> (ships skill v<skill>)`; JSONL `plan`
+  event gains additive `skillVersion`. Unit tests pin values from `package.json` + `SKILL.md`.
+
+### Changed
+- `bin/cli.mjs` git mode `100755` (executable bit in tarball).
+
+## [0.1.0-rc.2] — 2026-07-17 — LIVE (published 2026-07-17, `latest` + `rc` both point here)
 
 Ships `skills/flow` v0.22.0 (concierge front-door + standalone native rituals — see the root
 repo's CHANGELOG.md `## 0.22.0` entry for the full skill-content changelog). This wrapper
@@ -68,10 +103,38 @@ two hardening items found while verifying it all.
   both `install.sh` and `install.ps1` carry the Antigravity restart/reload hint, and the old
   hardcoded Claude+Codex-only Done line is gone from both.
 
-### Release command (operator-gated — not run by this change)
+### Fixed — CI publish guard (found on the actual first real run of this workflow)
+- `publish-npm-wrapper.yml`'s `Guard — assert no NODE_AUTH_TOKEN present (OIDC only)` step
+  **hard-failed every run, including this release's first attempt** (run `29554226397`,
+  2026-07-17). Root-caused via a temporary diagnostic step (added, run 3×, removed same
+  session): `NODE_AUTH_TOKEN` is unset right after `actions/checkout@v4` but becomes a real
+  short-lived OIDC-exchanged value the instant `actions/setup-node@v4` runs with
+  `registry-url` set — that's the current `actions/setup-node@v4` (a moving tag) doing its own
+  native npm OIDC handling, not a leaked static secret. The guard's 2026-07-12 design assumed
+  the older model where `npm publish` alone performed the OIDC exchange with nothing set
+  beforehand; it never matched real `actions/setup-node@v4` behavior and had a 0% pass rate
+  since the day it was written. **Removed** — see the workflow file's inline comment for the
+  full evidence chain.
+- **npm Trusted Publisher was never actually bound** on npmjs.com for this package (confirmed:
+  first real publish attempt after the guard fix still 404'd — `PUT
+  .../@manhquy%2fflow-skill — Not found`). The 2026-07-12 runbook flagged this config as `TBD`
+  and it was never closed out. Configured now: `owner=manhquydev`, `repo=flow-skill`,
+  `workflow=publish-npm-wrapper.yml`, `environment=npm-publish`. `npm publish --provenance`
+  now succeeds via pure OIDC — confirmed live, SLSA attestation present.
+- **`npm dist-tag add` does NOT work via OIDC** (confirmed live: `E401 Unable to authenticate`
+  even immediately after a successful OIDC-authenticated publish in the same job). npm has not
+  extended Trusted Publishing to this endpoint yet (matches
+  `plans/reports/researcher-260712-1006-npm-trusted-publisher-first-publish-edge-cases-report.md`
+  item #12, "OIDC support in development", no ship date). Promoting `0.1.0-rc.2` to `latest`
+  required the same manual Granular-Access-Token-with-Bypass-2FA flow used for the rc.1
+  bootstrap publish — see `RELEASE_CHECKLIST.md` for the exact steps and why this account
+  (created 2026-07-11, after npm's Sept-2025 TOTP-enrollment cutoff) has no other CLI-auth path
+  for write operations.
+
+### Release command (already run for this release)
 ```
-cd npm-wrapper && npm test   # confirm green first
-git tag npm@0.1.0-rc.2 && git push --tags   # triggers .github/workflows/publish-npm-wrapper.yml
+cd npm-wrapper && npm test   # confirmed green first
+git tag npm@0.1.0-rc.2 && git push origin npm@0.1.0-rc.2   # triggered the workflow (after the guard fix + TP config above)
 ```
 
 ## [0.1.0-rc.1] — 2026-07-12

package/README.md

@@ -10,13 +10,21 @@ One-command installer that copies the [flow](https://github.com/manhquydev/flow-
 ## Install
 
 ```
-# Pre-release channel (current — v0.1.0-rc.2)
+# Pre-release channel (current — v0.1.0-rc.3, ships skill v0.22.0)
 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.2`. `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).
+> **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).
+>
+> **`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
+> `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`).
+> `--help` and the JSONL `plan` event expose both (`version` + `skillVersion`).
 
 ## Non-interactive
 
@@ -58,7 +66,7 @@ line tells you exactly what to do for whichever targets you installed:
 - Claude Code: type `/flow`.
 - Codex CLI: type `$flow` (restart Codex once to load a new skill).
 - Antigravity: restart/reload the IDE (or restart `agy`) to load the new skill, then type `/flow`.
-- Agents home: restart/reload your tool if it does not auto-detect new skills.
+- Agents home (`~/.agents/skills/`): restart/reload your tool if it does not auto-detect new skills.
 - Cursor: **install verified, live runner execution not yet independently confirmed** — Cursor
   has no headless CLI probe available for automated verification (unlike Antigravity's `agy -p`
   or Codex's `codex exec`); restart/reload Cursor after install and check the Agent panel for
@@ -86,6 +94,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.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…`.
+- **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+.
 
 ## JSONL contract
@@ -93,7 +103,7 @@ rm -rf <project>/.claude/skills/flow
 `--json` streams one JSON object per line:
 
 ```jsonl
-{"event":"plan","version":"0.1.0-rc.1","dryRun":false,"scope":"global","targets":["claude","codex"]}
+{"event":"plan","version":"0.1.0-rc.3","skillVersion":"0.22.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}
@@ -105,7 +115,7 @@ rm -rf <project>/.claude/skills/flow
 
 | Event | Required fields | Notes |
 |---|---|---|
-| `plan` | `version` (string), `dryRun` (bool), `scope` (`global`\|`project`), `targets` (string[]) | Always the first event. |
+| `plan` | `version` (string), `dryRun` (bool), `scope` (`global`\|`project`), `targets` (string[]), optional `skillVersion` (string\|null) | Always the first event. `version` = npm package; `skillVersion` = bundled `SKILL.md` product version. |
 | `install:start` | `target` (string), `dests` (string[]) | One per selected target. |
 | `install:done` | `target`, `dests`, `result` (`success`\|`failed`), `error` (string\|null), `warnings` (string[]) | Fired after each target. `error` is `null` on success. |
 | `summary` | `success` (bool), `total`, `attempted`, `installed`, `failed`, `skipped`, `aborted` (bool) | Always the last event. Counts sum: `attempted = installed + failed`; `skipped = total - attempted`. |

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
 
@@ -110,6 +112,11 @@ Mỗi phiên bản publish có [npm provenance](https://docs.npmjs.com/generatin
 npm view @manhquy/flow-skill@<version> dist.attestations.provenance
 ```
 
+> **Ngoại lệ RC-window**: `v0.1.0-rc.1` được publish thủ công từ máy developer để bootstrap npm
+> Trusted Publisher (TP không thể bind tới package chưa tồn tại) — bản này không có provenance.
+> Từ `v0.1.0-rc.2` trở đi, mọi bản publish đều qua CI workflow với OIDC và có attestation
+> SLSA Build Level 2 đầy đủ.
+
 ## Bảo mật
 
 Threat model + WILL/WON'T list + kênh report — xem [SECURITY.md](./SECURITY.md). Tóm tắt: pure Node, không network call, không spawn shell/PowerShell, không postinstall hook, không chạm settings/hooks/MCP config.

package/SECURITY.md

@@ -55,7 +55,7 @@ These match the behavior of the upstream `install.sh`; they are documented rathe
   ```
   npm view @manhquy/flow-skill@<version> dist.attestations.provenance
   ```
-  **`v0.1.0-rc.1` exception**: this bootstrap version was published manually (Trusted Publisher requires the package to already exist before it can bind) and carries no attestation. All subsequent versions publish via CI and are attested. If provenance is a hard requirement for you, wait for `v0.1.0-rc.2` or later.
+  **`v0.1.0-rc.1` exception**: this bootstrap version was published manually (Trusted Publisher requires the package to already exist before it can bind) and carries no attestation. `v0.1.0-rc.2` (2026-07-17) is the first version published from CI via OIDC — confirmed live with an SLSA Build Level 2 attestation. All versions from rc.2 onward are attested; if provenance is a hard requirement, pin `@0.1.0-rc.2` or later.
 - **Publisher account.** npm 2FA `auth-and-writes` is enabled as defense-in-depth for the git + npm identity behind the workflow.
 - **Pin your version.** During the RC window use `@rc` (dist-tag) or an explicit `@0.1.0-rc.N`. After stable ships, pin `@0.1.x` (or a specific version). `@latest` invites blind updates on a package that writes to your agent home.
 - **Completeness signal (not tamper detection).** The tarball ships `skills-manifest.json` recording the synced skill's file count + list. The publish workflow re-counts the checked-out tree against this manifest to catch an incomplete sync. It is **not** a supply-chain integrity proof — that role belongs to npm provenance above. `.integrity` SHA-256 sidecar was intentionally not adopted because it would have been generated from the same source it hashed (circular trust).

package/bin/cli.mjs

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { join, resolve } from 'node:path';
 import { existsSync } from 'node:fs';
 
-import { TARGETS, TARGET_NAMES, PKG_VERSION } from '../src/constants.mjs';
+import { TARGETS, TARGET_NAMES, PKG_VERSION, SKILL_VERSION } from '../src/constants.mjs';
 import { defaultSelection, detectAll } from '../src/detect.mjs';
 import { renderHelp } from '../src/help.mjs';
 import { install, installAntigravity } from '../src/installer.mjs';
@@ -288,6 +288,9 @@ async function main() {
     {
       event: 'plan',
       version: PKG_VERSION,
+      // Additive: skill product version (SKILL.md). `version` stays the npm package version
+      // for back-compat with existing JSONL consumers.
+      skillVersion: SKILL_VERSION,
       dryRun: opts.dryRun,
       scope,
       targets: plan.map((p) => p.target),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manhquy/flow-skill",
-  "version": "0.1.0-rc.2",
+  "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,14 +94,14 @@ 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.
 All wiring degrades gracefully: if python is absent or `FLOW_HARNESS_DISABLE=1`, the
 mechanical engine runs unchanged.
 
-## Usage signal: accessed_count (read-only, schema 005)
+## Usage signal: accessed_count (read-only, schema 009 — see Backends re-homing note above)
 `query decisions|friction|backlog` increment an `accessed_count` on every surfaced row and order
 output **most-reused-first**, so `recall` floats the knowledge you actually reuse to the top. It is
 a **read-only ordering signal** — never used to prune, delete, or archive a row. Low count is not
@@ -76,7 +110,7 @@ rare*. Security-class rows (`auth|authoriz|admin|tenan|payment|migrat|valid|secr
 always sort first and are never deprioritized. The story `matrix` view is intentionally left
 ordered by id (it is a status table, not recalled knowledge).
 
-## Usage log: mechanical flight-recorder (schema 006)
+## Usage log: mechanical flight-recorder (schema 010 — see Backends re-homing note above)
 Distinct from the curated, agent-authored records above: `flow.sh` itself self-records **every
 invocation** (no agent action needed) to append-only JSONL — `.flow/events.jsonl` (full, per-project)
 plus `~/.claude/flow/usage.jsonl` (compact, device-global). Fields: ts/epoch_s, session_id, cycle_id
@@ -93,7 +127,7 @@ stage_from→to, card, project_type, mode, flow_version, tier, host, read_only.
 - JSONL is the source of truth; `usage_event` is a derived, queryable mirror. Semantic events keep
   using `trace`/`intervention`/`decision` — the usage log does not duplicate them.
 
-**Closed feedback loop (schema 007).** The recorded data feeds the surfaces where you already act:
+**Closed feedback loop (schema 011 — see Backends re-homing note above).** The recorded data feeds the surfaces where you already act:
 - `recall` appends a one-line digest (`flow_harness.py usage --summary`): cycles, cycle-time, gate
   fail-rate, top gate-fail stage — so build history reaches you at stage/card start (silent if no data).
 - `propose` (`_build_proposals`) emits a backlog proposal when a stage's gate fail-rate ≥ 50% across

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")
@@ -1034,7 +1103,7 @@ def build_parser():
     q1 = pqs.add_parser("matrix"); q1.add_argument("--json", action="store_true"); q1.add_argument("--numeric", action="store_true")
     q2 = pqs.add_parser("backlog"); q2.add_argument("--open", action="store_true"); q2.add_argument("--closed", action="store_true"); q2.add_argument("--json", action="store_true")
     q3 = pqs.add_parser("friction"); q3.add_argument("--json", action="store_true")
-    q4 = pqs.add_parser("tools"); q4.add_argument("--responsibility"); q4.add_argument("--json", action="store_true"); q4.add_argument("--summary", action="store_true")
+    q4 = pqs.add_parser("tools"); q4.add_argument("--responsibility"); q4.add_argument("--json", action="store_true")
     q4.add_argument("--capability"); q4.add_argument("--status", choices=D.TOOL_STATUSES)
     q5 = pqs.add_parser("decisions"); q5.add_argument("--json", action="store_true")
 

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-17T04:53:07.141Z",
+  "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",

package/src/constants.mjs

@@ -72,11 +72,26 @@ export const CLI_NAME = 'flow-skill';
 
 // F3 fix: read version from package.json at runtime so `npm version` bumps propagate to the
 // JSON `plan` event without a hand-edit here.
-import { readFileSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = resolve(__dirname, '..');
 const pkgJson = JSON.parse(
-  readFileSync(resolve(__dirname, '..', 'package.json'), 'utf8')
+  readFileSync(resolve(pkgRoot, 'package.json'), 'utf8')
 );
 export const PKG_VERSION = pkgJson.version;
+
+// Skill product version (SKILL.md metadata.version) is a SEPARATE axis from the npm
+// installer package version. Surface both so `npx … --help` / plan events cannot be
+// misread as "stale skill" when the user expected 0.22.x and saw 0.1.0-rc.N.
+function readSkillVersion() {
+  const skillMd = resolve(pkgRoot, 'skills', 'flow', 'SKILL.md');
+  if (!existsSync(skillMd)) return null;
+  const text = readFileSync(skillMd, 'utf8');
+  // Frontmatter only — first `version: "x.y.z"` under metadata (or any YAML version line).
+  // Indented under `metadata:` in YAML frontmatter (two spaces typical).
+  const m = text.match(/^\s*version:\s*["']?([0-9][0-9A-Za-z.+-]*)["']?\s*$/m);
+  return m ? m[1] : null;
+}
+export const SKILL_VERSION = readSkillVersion();

package/src/help.mjs

@@ -1,16 +1,18 @@
-import { CLI_NAME, PKG_VERSION, TARGETS } from './constants.mjs';
+import { CLI_NAME, PKG_VERSION, SKILL_VERSION, TARGETS } from './constants.mjs';
 
 export function renderHelp() {
   const targetRows = TARGETS.map((t) => `    ${t.name.padEnd(12)} ${t.label}`).join('\n');
   // v0.23 H5 (red-team): derive the count from TARGETS.length so a future target addition can
   // never again leave a stale hardcoded number in the help text.
   const targetCount = TARGETS.length;
-  return `${CLI_NAME} v${PKG_VERSION}
+  const skillBit = SKILL_VERSION ? ` (ships skill v${SKILL_VERSION})` : '';
+  return `${CLI_NAME} v${PKG_VERSION}${skillBit}
 
 Install the flow skill into your coding agent(s).
 
 USAGE
-  npx @manhquy/flow-skill [options]
+  npx @manhquy/flow-skill@rc
+  # or after stable ships: npx @manhquy/flow-skill
 
 OPTIONS
   -y, --yes                    Skip prompts; install to default selection (detected + Claude)