@manhquy/flow-skill 0.4.1 → 0.5.1

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to `@manhquy/flow-skill`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/).
 
+## [0.5.0] — 2026-08-11 — ships skill v0.28.0 (attested execution)
+
+Installer minor: bundles skill **v0.28.0** (risk + attestation receipts + auto trust plane).
+Installer CLI contract unchanged. Prerelease dist-tag policy: **`next`**.
+
 ## [0.4.1] — 2026-08-11 — README + CLI help install UX
 
 Docs-only installer release (same skill **v0.27.0**). Professional install section, full

package/README.md

@@ -5,7 +5,7 @@ Install the **flow** skill into coding agents with one command.
 | | |
 |---|---|
 | **Package** | [`@manhquy/flow-skill`](https://www.npmjs.com/package/@manhquy/flow-skill) (installer CLI) |
-| **Current GA** | **0.4.1** — ships skill product **v0.27.0** |
+| **Current GA** | **0.5.1** — ships skill product **v0.28.1** |
 | **Platforms** | macOS · Linux · Windows (same Node path) |
 | **Requirement** | Node.js **≥ 22.14** |
 | **Source** | [github.com/manhquydev/flow-skill](https://github.com/manhquydev/flow-skill) |
@@ -34,7 +34,7 @@ npx @manhquy/flow-skill@latest
 
 ```bash
 npx @manhquy/flow-skill@latest --help
-# expect: flow-skill v0.4.x (ships skill v0.27.x)
+# expect: flow-skill v0.5.x (ships skill v0.27.x)
 ```
 
 ### Common commands
@@ -89,7 +89,7 @@ npx @manhquy/flow-skill@latest --yes --all --dry-run --json
 |----|--------|
 | `npx @manhquy/flow-skill@latest` | Bare `npx @manhquy/flow-skill` (stale npx cache) |
 | **Run** the CLI to copy the skill | `npm i` alone (package only; no skill files in agent homes) |
-| Pin installer `@0.4.1` if needed | Pin npm `@0.27.0` (skill version ≠ package version) |
+| Pin installer `@0.5.1` if needed | Pin npm `@0.28.1` (skill version ≠ package version) |
 | Prefer `@latest` | `@rc` (retired / behind) |
 
 **Two version axes:** `package.json` version = installer; `SKILL.md` metadata = skill product. Both appear in `--help` and in the `plan` JSONL event (`version` + `skillVersion`).
@@ -137,7 +137,7 @@ rm -rf <project>/.claude/skills/flow
 |---------|-----|
 | Agent has no `/flow` after `npm i` | Run `npx @manhquy/flow-skill@latest` (install must **execute**) |
 | Old skill after reinstall | Always use `@latest`; avoid bare package name |
-| `No matching version found` for `@0.27.0` | That is the **skill** version. Use `@latest` or `@0.4.x` |
+| `No matching version found` for `@0.28.1` | That is the **skill** version. Use `@latest` or `@0.5.x` |
 | Node too old | Install Node ≥ 22.14 (`nvm install 22`, etc.) |
 | Windows `EBUSY` / `EPERM` | Close the agent holding files under the skill dir; re-run |
 | Stale install lock | Delete `<parent>/.flow-skill.installing.lock` if reclaim fails |
@@ -147,7 +147,7 @@ rm -rf <project>/.claude/skills/flow
 ## JSONL (`--json`)
 
 ```jsonl
-{"event":"plan","version":"0.4.1","skillVersion":"0.27.0","dryRun":false,"scope":"global","targets":["claude"]}
+{"event":"plan","version":"0.5.1","skillVersion":"0.28.1","dryRun":false,"scope":"global","targets":["claude"]}
 {"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":1,"attempted":1,"installed":1,"failed":0,"skipped":0,"aborted":false}

package/README_VN.md

@@ -10,7 +10,7 @@ Cài skill **flow** vào coding agent bằng một lệnh.
 | **Yêu cầu** | Node.js **≥ 22.14** |
 | **Source** | [github.com/manhquydev/flow-skill](https://github.com/manhquydev/flow-skill) |
 
-flow là harness build có cổng (`/flow`). Package này chỉ **cài** skill đó vào skill home của agent.
+flow là harness build có cổng (`/flow`): ý tưởng → cổng trung thực → bằng chứng done thật. Package này chỉ **cài** skill đó vào skill home của agent.
 
 ---
 
@@ -23,12 +23,12 @@ npx @manhquy/flow-skill@latest
 
 | Bước | Chi tiết |
 |------|----------|
-| 1 | Tải dist-tag **`latest`** từ npm |
-| 2 | Multi-select agent (Claude luôn được đề xuất) |
-| 3 | Copy `skills/flow` vào từng đích |
-| 4 | In hướng dẫn gọi sau reload (`/flow`, `$flow`, …) |
+| 1 | Tải dist-tag **`latest`** từ npm registry |
+| 2 | Multi-select tương tác các agent detect được (Claude luôn được đề xuất) |
+| 3 | Copy cây `skills/flow` vào từng đích đã chọn |
+| 4 | In hướng dẫn sau reload (`/flow`, `$flow`, …) |
 
-**Sau cài:** restart/reload agent (xem [Sau khi cài](#sau-khi-cài)).
+**Sau cài:** restart hoặc reload agent (xem [Sau khi cài](#sau-khi-cài)).
 
 ### Xác nhận version
 
@@ -43,18 +43,18 @@ npx @manhquy/flow-skill@latest --help
 # Không prompt (Claude + agent đã detect)
 npx @manhquy/flow-skill@latest --yes
 
-# Target rõ ràng
+# Một hoặc nhiều target
 npx @manhquy/flow-skill@latest --yes --target claude
 npx @manhquy/flow-skill@latest --yes -t claude -t codex
 npx @manhquy/flow-skill@latest --yes -t claude,codex
 
-# Cả 5 target
+# Mọi target được hỗ trợ
 npx @manhquy/flow-skill@latest --yes --all
 
-# Skill trong repo (chỉ Claude)
+# Skill Claude trong repo (dễ commit)
 npx @manhquy/flow-skill@latest --yes --project --dir .
 
-# Chỉ xem kế hoạch + JSONL (CI)
+# Chỉ xem kế hoạch, không ghi đĩa + JSONL (CI)
 npx @manhquy/flow-skill@latest --yes --all --dry-run --json
 ```
 
@@ -62,37 +62,37 @@ npx @manhquy/flow-skill@latest --yes --all --dry-run --json
 
 | Flag | Ý nghĩa |
 |------|---------|
-| `-y`, `--yes` | Bỏ prompt; cài selection mặc định |
-| `-t`, `--target <name>` | Target (lặp hoặc comma) |
+| `-y`, `--yes` | Bỏ prompt; cài selection mặc định (detected + Claude) |
+| `-t`, `--target <name>` | Target (lặp được hoặc comma-separated) |
 | `--all` | Mọi target, kể cả chưa detect |
 | `--project` | Scope project — chỉ Claude → `<dir>/.claude/skills/flow` |
-| `--dir <path>` | Thư mục project (kéo theo `--project`) |
-| `--json` | JSONL events |
-| `--dry-run` | Không ghi đĩa |
+| `--dir <path>` | Thư mục project (kéo theo `--project`; mặc định: cwd) |
+| `--json` | JSONL events (`plan`, `install:*`, `summary`) |
+| `--dry-run` | In plan; không ghi đĩa |
 | `-h`, `--help` | Help |
 
 ### Targets
 
 | Tên | Đích | Detection |
 |-----|------|-----------|
-| `claude` | `~/.claude/skills/flow` | `~/.claude` |
+| `claude` | `~/.claude/skills/flow` | `~/.claude` (luôn được đề xuất) |
 | `codex` | `~/.codex/skills/flow` | `~/.codex/skills` |
 | `agents` | `~/.agents/skills/flow` | `~/.agents/skills` |
-| `antigravity` | 2 path dưới `~/.gemini/…` | CLI hoặc IDE skills |
+| `antigravity` | `~/.gemini/antigravity-cli/skills/flow` **và** `~/.gemini/config/skills/flow` | một trong hai path |
 | `cursor` | `~/.cursor/skills/flow` | `~/.cursor/skills` |
 
-`--project` **chỉ** hỗ trợ `claude` (exit `2` nếu kết hợp target khác).
+`--project` **chỉ** hỗ trợ `claude`. Kết hợp target khác → exit `2`.
 
 ### Quy tắc
 
 | Nên | Không |
 |-----|--------|
-| `npx @manhquy/flow-skill@latest` | Bare package name (cache npx) |
-| **Chạy** CLI | Chỉ `npm i` |
-| Pin `@0.4.0` nếu cần | Pin `@0.27.0` trên npm (version skill) |
-| `@latest` | `@rc` |
+| `npx @manhquy/flow-skill@latest` | Bare `npx @manhquy/flow-skill` (cache npx có thể cũ) |
+| **Chạy** CLI để copy skill | Chỉ `npm i` (chỉ thêm package; không cài skill vào agent home) |
+| Pin installer `@0.4.1` nếu cần cố định | Pin npm `@0.27.0` (version **skill** ≠ version package) |
+| Ưu tiên `@latest` / `@0.4.x` | `@rc` (đã retire / tụt hậu) |
 
-**Hai trục version:** package = installer; skill = `SKILL.md`. Cả hai hiện trong `--help` và event `plan` (`version` + `skillVersion`).
+**Hai trục version:** `package.json` = installer CLI; `SKILL.md` metadata = skill product. Cả hai hiện trong `--help` và event JSONL `plan` (`version` + `skillVersion`).
 
 ---
 
@@ -101,10 +101,13 @@ npx @manhquy/flow-skill@latest --yes --all --dry-run --json
 | Agent | Bước tiếp |
 |-------|-----------|
 | Claude Code | Gõ `/flow` |
-| Codex | Restart Codex → `$flow` |
-| Antigravity | Restart IDE/`agy` → `/flow` |
-| Agents / Cursor | Reload tool; kiểm panel skill |
-| Bất kỳ | `/flow doctor` |
+| Codex CLI | Restart Codex một lần → `$flow` |
+| Antigravity | Restart IDE / `agy` → `/flow` |
+| Agents home | Reload tool nếu không tự nhận skill mới |
+| Cursor | Reload Cursor; kiểm panel agent skills |
+| Bất kỳ | `/flow doctor` (hoặc `runner/flow.sh doctor`) |
+
+### Kiểm tra trên đĩa (Claude global)
 
 ```bash
 grep -E '^\s*version:' ~/.claude/skills/flow/SKILL.md | head -1
@@ -116,9 +119,13 @@ bash ~/.claude/skills/flow/runner/flow.sh doctor
 ## Gỡ cài
 
 ```bash
-rm -rf ~/.claude/skills/flow ~/.codex/skills/flow ~/.agents/skills/flow
+rm -rf ~/.claude/skills/flow
+rm -rf ~/.codex/skills/flow
+rm -rf ~/.agents/skills/flow
 rm -rf ~/.cursor/skills/flow
-rm -rf ~/.gemini/antigravity-cli/skills/flow ~/.gemini/config/skills/flow
+rm -rf ~/.gemini/antigravity-cli/skills/flow
+rm -rf ~/.gemini/config/skills/flow
+# project scope:
 rm -rf <project>/.claude/skills/flow
 ```
 
@@ -128,16 +135,34 @@ rm -rf <project>/.claude/skills/flow
 
 | Hiện tượng | Cách xử lý |
 |------------|------------|
-| Có package nhưng không có `/flow` | Chạy `npx @manhquy/flow-skill@latest` |
-| Skill cũ sau khi “cài lại” | Luôn `@latest` |
-| `No matching version` với `@0.27.0` | Dùng `@latest` / `@0.4.x` (version skill ≠ package) |
-| Node quá cũ | Nâng Node ≥ 22.14 |
-| Windows EBUSY | Đóng agent đang giữ file skill; chạy lại |
+| Agent không có `/flow` sau `npm i` | Chạy `npx @manhquy/flow-skill@latest` (phải **execute** installer) |
+| Skill cũ sau khi “cài lại” | Luôn dùng `@latest`; tránh bare package name |
+| `No matching version found` với `@0.27.0` | Đó là version **skill**. Dùng `@latest` hoặc `@0.4.x` |
+| Node quá cũ | Cài Node ≥ 22.14 (`nvm install 22`, v.v.) |
+| Windows `EBUSY` / `EPERM` | Đóng agent đang giữ file trong skill dir; chạy lại |
+| Stale install lock | Xóa `<parent>/.flow-skill.installing.lock` nếu reclaim thất bại |
 
 ---
 
-## JSONL · provenance · license
+## JSONL (`--json`)
+
+```jsonl
+{"event":"plan","version":"0.4.1","skillVersion":"0.27.0","dryRun":false,"scope":"global","targets":["claude"]}
+{"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":1,"attempted":1,"installed":1,"failed":0,"skipped":0,"aborted":false}
+```
+
+Exit codes: `0` success · `1` target failure · `2` bad usage · `130` SIGINT.
+
+Contract additive: field mới có thể xuất hiện; field hiện có không đổi tên/xóa.
+
+---
+
+## Provenance & bảo mật
+
+Bản publish từ CI có [npm provenance](https://docs.npmjs.com/generating-provenance-statements). Mô hình đe dọa và báo cáo: [SECURITY.md](./SECURITY.md).
 
-Xem bản [English README](./README.md) cho bảng event JSONL, provenance, và [SECURITY.md](./SECURITY.md).
+## License
 
 MIT © 2026 manhquy

package/package.json

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

@@ -3,12 +3,12 @@ name: flow
 description: Run the buildflow gated build process from idea to real done-evidence. Walk gated stages (Idea->Research->Scope->PRD->ADR->Contract->Cards->Build->Review->Deploy/Ship->Verify->Retro), each with a honest gate that must pass before advancing. Adapts to project type (web|cli|library|skill). Use when starting or driving a real product build, when the user types /flow, /flow next, /flow card, /flow check, or asks to scope/plan/ship a project through gates. Kill at any gate is a valid outcome.
 user-invocable: true
 when_to_use: "User wants to build a real product end-to-end with discipline (idea -> a deployed URL for web, or installs+runs for a CLI/library/skill), or types any /flow command, or asks for a gated build process, scope decision, contract-first plan, or card-based shipping."
-argument-hint: "[ resume | next | card | check C-NNN | project-type web|cli|library|skill | mode teach|work | skip <stage> | ready | workspace add|list|enter|remove|check|doctor | auto | doctor | retro | eval --stage 01|02|card|routing --fixture <id> --n 3 --keep-going --report | or just say what you want in plain language ]"
+argument-hint: "[ resume | next | card | check C-NNN | project-type web|cli|library|skill | mode teach|work | skip <stage> | ready | workspace add|list|enter|remove|check|doctor | auto [stop] | attest semantic|live-verify|status|recover | doctor | retro | eval --stage 01|02|05|card|routing --fixture <id> --n 3 --keep-going --report | or just say what you want in plain language ]"
 keywords: [flow, buildflow, gate, build, ship, scope, prd, contract, card, deploy, vertical-slice, cli, library, skill, worktree, parallel-agents, workspace, multi-agent]
 license: MIT
 metadata:
   author: flow-skill
-  version: "0.27.0"
+  version: "0.28.1"
   attribution: "Methodology from ai20k-build-phase/buildflow (Tony, arealisticdreamer.com); durable-layer ancestry and improve-ritual spirit from repository-harness (protocol v1 EOL — flow-owned fork); agent patterns from claudekit-engineer, BMAD-METHOD. v0.22 concierge from BMAD bmad-help; forge-idea from bmad-forge-idea (MIT, BMad Code LLC)."
 ---
 
@@ -94,7 +94,8 @@ takes over a lock you're sure is dead; `/flow unlock` clears it.
 | `/flow mode teach\|work` | set who writes the artifacts (default `teach`) |
 | `/flow ready` | `flow.sh ready` — which todo cards are buildable + parallel-safety hint |
 | `/flow workspace add\|list\|enter\|remove\|check\|doctor` | `flow.sh workspace …` — **multi-agent worktree isolation** for running several agents (Claude/Codex/Antigravity, many terminals) in parallel WITHOUT the "one agent switches branch → every terminal flips" trap. Each agent gets its own `git worktree` (own HEAD/index/files, shared object store); git is the live registry (`git worktree list`) and a 10-field JSONL side-file (`.flow/workspaces.jsonl`) adds vendor/card/port/task. `add <branch> [--card C-NNN] [--vendor …] [--task …] [--copy-env]` provisions a worktree + distinct port-offset + paste-ready cd/env block; `list` shows who-is-where; `enter <branch>` re-prints a crashed terminal's env; `check <branch> [--card]` flags branch-claim + allowed-files overlap before you launch; `remove <branch> [--force]` tears down safely (never auto-forces); `doctor` reconciles orphan trees/records. Advisory layer; git's refusal to check out one branch twice is the real lock. |
-| `/flow auto` | `flow.sh auto` preflight, then drive the autonomous run (see AUTO principles) |
+| `/flow auto` | `flow.sh auto` — attested preflight (risk + Stage 05 receipt) activates shared auto policy; then drive the autonomous run (see AUTO principles). `auto stop` clears it. |
+| `/flow attest …` | `flow.sh attest semantic\|live-verify\|status\|recover` — mint/inspect fingerprint-bound receipts (`references/attestations.md`) |
 | `/flow recall` | `flow.sh recall` — read back durable memory (open debt, recent retro, previous-card scope, harness friction/backlog, playbooks) **at the start of a stage/card** so you don't re-learn known pain |
 | `/flow usage` | `flow.sh usage` — roll up the mechanical usage log (JSONL flight-recorder of every invocation) into `usage_event` and print build analytics: cycle-time, gate fail-rate, per-stage dwell, cycle completion, command breakdown. `--global` for the device-wide view; `--prune [--keep N]` caps the log (crash-safe). Local-only; disable with `FLOW_LOG_DISABLE=1`/`DO_NOT_TRACK=1`. `recall` now surfaces a one-line usage digest and `retro`'s `propose` flags chronically-failing stages. |
 | `/flow contract` | `flow.sh contract` — flag client base-URL vs served-path prefix drift (web; advisory; run after the contract gate) |
@@ -189,11 +190,16 @@ deliver the card set as one summary. Gates bind the same as `teach`.
 
 ## AUTO principles
 
-`/flow auto` drives the build phase autonomously (`references/auto-run.md`). Operator
-setting: **Tier-A auto-merge green cards; halt at security-class.** Per card: tier-classify
-→ one scoped subagent in its own worktree → build to contract → adversarial review →
-`flow.sh check` PASS → merge in card order → deploy → **verify on the LIVE URL** (merge ≠
-shipped) → world-state evidence → `status: done` → durable trace + `AUTO-LOG.md`.
+`/flow auto` drives the build phase autonomously (`references/auto-run.md`) under the
+**attested-execution** trust control plane (`references/attestations.md`). Mechanical
+preflight persists auto policy only when every card has classified risk (security-class
+needs a distinct-author DEBT ack) and Stage 05 has a current `semantic_gate` receipt.
+While auto is active, `check` / `card done` / ready deps / merged worktree remove require
+fingerprint-bound semantic and live receipts; `auto stop` returns to warning-only manual
+mode. Operator setting: **Tier-A auto-merge green cards; halt at security-class.** Per
+card: tier-classify → scoped subagent in its own worktree → build → adversarial review →
+owner-backed semantic receipt → `flow.sh check` PASS → merge → deploy → live_verify
+receipt → world-state evidence → `card done` → durable trace + `AUTO-LOG.md`.
 - **Tier A**: green + no security-class → auto-merge, no ask.
 - **Tier B**: fixable issues → one repair by a FRESH subagent (two-strikes), else escalate.
   If the fix needs >1 experimental attempt against a single numeric target (not a review

package/skills/flow/_templates/card.md

@@ -3,6 +3,9 @@
 status: todo
 deps: [FILL: card ids this depends on, e.g. "C-001, C-002" — or "none"]
 implements: [FILL: PRD feature ids this card delivers, e.g. "FR1, FR2" — or "infra"/"none" for non-feature cards]
+risk: unknown
+risk-reason:
+risk-ack: none
 
 ## Scope
 

package/skills/flow/eval/fixtures/f05a/flow/05-contract.md

@@ -0,0 +1,22 @@
+# 05 — Contract
+
+## Interfaces
+
+| Method | Path | Request | Response | Errors | Owner |
+|---|---|---|---|---|---|
+| GET | /healthz | none | `{ "ok": true }` | 503 if deps down | platform |
+
+## Auth
+
+- Public: `/healthz` only.
+- All other routes: bearer session token; 401 if missing/invalid.
+
+## Error model
+
+- `code` (string), `message` (string), `request_id` (string).
+- 4xx client; 5xx server; no silent 200 on failure.
+
+## Gate
+- [x] Every endpoint has method, path, request, response, errors, owner.
+- [x] Auth boundary is explicit for each route class.
+- [x] Error shape is machine-readable and stable.

package/skills/flow/eval/fixtures/f05b/flow/05-contract.md

@@ -0,0 +1,11 @@
+# 05 — Contract
+
+## Interfaces
+
+We will expose some APIs as needed. Endpoints are flexible and will evolve.
+Auth might be optional depending on context. Errors should be helpful.
+
+## Gate
+- [x] Interfaces sketched
+- [x] Auth considered
+- [x] Errors mentioned

package/skills/flow/eval/manifest.tsv

@@ -6,3 +6,5 @@ f02b	02-scope	flow/02-scope.md	FLAG
 fcda	card	cards/C-001.md	PASS
 fcdb	card	cards/C-001.md	FLAG
 fcdc	card	cards/C-001.md	FLAG
+f05a	05-contract	flow/05-contract.md	PASS
+f05b	05-contract	flow/05-contract.md	FLAG

package/skills/flow/references/attestations.md

@@ -0,0 +1,307 @@
+# Attestations — risk, receipts, and auto trust (v0.28)
+
+Canonical owner for **card risk**, **attestation receipts**, **subject
+fingerprints**, and **auto-active policy state**. Other docs link here; do not
+duplicate full schemas.
+
+Fingerprints detect **staleness** of a reviewed/verified subject. They do **not**
+authenticate a human or model. Actor/engine labels and unsigned receipt files
+are forgeable by a filesystem/repository owner. This layer is workflow integrity,
+not a hostile-host or cryptographic identity boundary.
+
+## Risk fields (card markdown)
+
+```text
+risk: standard|security-class|unknown
+risk-reason: <single line, 1..256 bytes once classified>
+risk-ack: none|git:<full repository object id>
+```
+
+Rules:
+
+- Missing legacy fields normalize to `unknown`, empty reason, `none` (compat).
+- Duplicate anchored fields are **invalid** (not last-wins).
+- `standard` requires a non-placeholder reason and `risk-ack: none`.
+- `security-class` requires a non-placeholder reason; auto validates `risk-ack`.
+- `unknown` requires `risk-ack: none`.
+- New cards scaffold `risk: unknown` / empty reason / `risk-ack: none`.
+
+### Security acknowledgement (auto only)
+
+`risk-ack: git:<full-oid>` is accepted only when:
+
+1. OID shape matches repository object format (`sha1` or `sha256`).
+2. Commit exists and is an ancestor of current integration `HEAD`.
+3. `git show <oid>:<project-prefix>DEBT.md` succeeds.
+4. The blob contains exactly one open line beginning
+   `- [ ] DEBT: security-class <card-id> --`.
+5. `git blame --line-porcelain` at that commit yields `author-mail` **distinct**
+   (normalized lowercase, no angle brackets) from `git var GIT_AUTHOR_IDENT`.
+6. Missing / ambiguous / same identity → fail closed for auto.
+
+Residual: Git identity is forgeable by a repository/config owner.
+
+### Semantic override (auto, semantic_gate only)
+
+`verdict: override` requires an ancestor DEBT open line:
+
+```text
+- [ ] DEBT: semantic-override <00-idea|01-research|02-scope|03-prd|04-adr|05-contract|C-NNN> -- <reason> -- close before: <condition>
+```
+
+Same author-distinct rule as security-class. Auto never accepts
+`live_verify: override`.
+
+## Committed producer manifests
+
+Pass cannot be minted from caller-supplied verdict/argv alone. Subjects reference
+a committed, repo-relative owner:
+
+```text
+schema: flow-attestation-owner/v1
+kind: semantic_gate|live_verify
+subject_id: <closed stage name or C-NNN>
+target_id: none|<lowercase [a-z0-9._-], 1..64 bytes>
+command: repo:<repo-relative executable>
+revision_oracle: none|repo:<repo-relative executable>
+```
+
+- `semantic_gate`: `target_id: none`, `revision_oracle: none`.
+- `live_verify`: non-`none` target and revision oracle.
+- Executables must be tracked regular files at `subject_revision`, inside the
+  project, stable object/mode, invoked directly (no shell re-parse).
+
+Runner-constructed argv only:
+
+```text
+<command> --subject-id <id> --subject-revision <oid> --subject-fingerprint <fp>
+<revision_oracle> --subject-id <id> --subject-revision <oid> --target-id <target>
+```
+
+Semantic producer stdout (strict):
+
+```text
+schema: flow-semantic-result/v1
+subject_fingerprint: <exact requested fingerprint>
+verdict: pass|fail
+critical_count: <0..999>
+high_count: <0..999>
+evidence_ref: none|repo:<relative-path>
+```
+
+`pass` requires both counts zero. `override` is never producer output.
+
+Live revision oracle stdout: exactly one full repository-format OID equal to the
+requested deployed revision.
+
+## Receipt schema (`flow-attestation/v1`)
+
+Path layout under main state root:
+
+```text
+<main-state-root>/.flow/attestations/
+  semantic_gate/stage-05-contract.receipt
+  semantic_gate/card-C-001.receipt
+  live_verify/card-C-001.receipt
+  live_verify/card-C-001.attempt
+```
+
+Required keys, **canonical order**, single-line `key: value`:
+
+```text
+schema: flow-attestation/v1
+kind: semantic_gate|live_verify
+subject_type: stage|card
+subject_id: <closed stage name or C-NNN>
+subject_fingerprint: git-<sha1|sha256>:<object-id>
+verdict: pass|fail|override
+actor: <sanitized, <=128 bytes>
+engine: <sanitized, <=128 bytes>
+evidence_ref: none|repo:<relative-path>
+timestamp: <UTC YYYY-MM-DDTHH:MM:SSZ>
+override_ref: none|git:<full-object-id>
+owner_ref: repo:<repo-relative owner manifest>
+owner_fingerprint: git-<sha1|sha256>:<object-id>
+```
+
+Kind-specific (also required when present):
+
+- stage `semantic_gate`: `subject_revision`
+- card `semantic_gate`: `subject_base`, `subject_revision`, `subject_tree`
+- `live_verify`: `subject_revision`, `command_fingerprint`, `result_code`,
+  `result_fingerprint`, `duration_ms`, `target_id`, `revision_oracle_ref`,
+  `revision_oracle_fingerprint`
+
+`result_code` closed set:
+`exit:<0..255>|timeout|output-cap|signal:<1..64>|spawn-error`.
+
+`result_fingerprint` hashes outcome metadata (status, byte counts, argv digest,
+duration bucket) — **never** stdout/stderr bytes.
+
+Parser rules:
+
+- Reject blank/unknown keys, duplicates, missing required keys, multiline
+  values, NUL/control chars, oversized values, path traversal.
+- Never source/eval receipt content.
+- CRLF normalized on read.
+- Invalid CLI/schema input does **not** overwrite an existing receipt.
+
+Atomic write: temp in destination dir → `chmod 600` best-effort → rename.
+Latest assessment wins: valid semantic `fail` and terminal live red replace
+older `pass`. Pre-spawn live attempt marker is fail-closed until dead-owner
+recovery or Must-ask `flow attest recover C-NNN --mark-failed`.
+
+### Scalar grammar
+
+- `actor` / `engine` / `activated_by`:
+  `[A-Za-z0-9][A-Za-z0-9._@/-]{0,127}`
+- `evidence_ref`: `none` or `repo:<normalized relative path>`, ≤256 UTF-8 bytes,
+  no `.` / `..` / empty segment / symlink escape
+- `target_id`: `[a-z0-9][a-z0-9._-]{0,63}`
+- Absent optional refs use literal `none`
+- Integers: no signs, spaces, leading plus, or overflow
+- Subject IDs: six stage names
+  (`00-idea`…`05-contract`) or normalized `C-NNN`
+
+## Subject projections and fingerprints
+
+| Subject | Canonical projection |
+|---|---|
+| Stage semantic | Exact committed Git blob bytes for the stage path |
+| Card semantic | `deps`, `implements`, risk fields, Scope, Allowed files, Verify, Done-evidence + base/head/tree OIDs |
+| Card live | Verify + Done-evidence + owner manifest + target + deployed revision + argv digest |
+
+Mutable `status` and `Evidence` are **excluded** from card semantic projection
+so CLI-owned completion updates do not invalidate a still-current review.
+
+Cleanliness for mint/consume (auto):
+
+- Fail closed on dirty tracked, index, or untracked files **except** skill-owned
+  `.flow/` run-state and CLI-owned card `status`/`Evidence` projection fields.
+- Do **not** mutate `.gitignore` to achieve cleanliness.
+
+### Stage fingerprint
+
+1. Validate stage name against closed set.
+2. Resolve revision to full commit; require clean tracked artifact.
+3. Blob OID for stage path at that commit; prefix `git-<format>:`.
+
+### Card semantic fingerprint
+
+1. Git repo + explicit base + head.
+2. Clean worktree including untracked (with `.flow` / status-Evidence exclusions).
+3. Canonical card-contract projection + base/head/tree OIDs + sorted
+   changed-path manifest (`base..head`, excluding card markdown path).
+4. Hash via `git hash-object --stdin`.
+
+Currentness after ancestry-preserving merge: reviewed revision is ancestor of
+integration HEAD; projection still matches; every reviewed changed path
+(except card md) has same object/mode at HEAD. Squash/rebase or code-path edit
+→ stale.
+
+### Live fingerprint
+
+Deployed revision + Verify/Done-evidence projection + owner/oracle object/mode
++ target + argv digest. Oracle must return exact deployed OID before probe may
+pass.
+
+## Auto-active state
+
+```text
+<main-state-root>/.flow/auto-state
+```
+
+```text
+schema: flow-auto/v1
+status: active
+activated_at: <UTC RFC3339>
+activated_by: <sanitized <=128>
+integration_branch: <validated branch name>
+risk_fingerprint: git-<sha1|sha256>:<object-id>
+contract_fingerprint: git-<sha1|sha256>:<object-id>
+```
+
+Activation (`flow auto`) requires, atomically after full preflight:
+
+- Git repo; main worktree on attached integration branch (linked/detached refuse)
+- Reliable process-group supervisor capability (else refuse live auto)
+- Planning complete + ≥1 card
+- Full risk set valid (no `unknown`, valid security ack)
+- Current accepted Stage 05 `semantic_gate` receipt
+
+Card/live receipts are later transition gates, not activation prerequisites.
+`flow auto stop` clears state. Status/resume show `INACTIVE|ACTIVE|STALE|INVALID`.
+
+### Enforcement matrix
+
+| Boundary | Auto inactive | Auto active/current | Auto stale/invalid |
+|---|---|---|---|
+| `next` | Warn on stage receipt | Warn only | Warn only |
+| `check` todo | Warn | Require card semantic pass/override | Block |
+| `check` done | Warn | Semantic + live pass | Block |
+| `card done` | Existing + warn | Same hard checks; validate before status mutation | Block |
+| `ready` | Existing + advisory | Done deps need both receipts | No BUILDABLE; non-zero |
+| merged `workspace remove` | Warn | Both receipts | Block |
+| unmerged remove | Existing abandon | Allow without receipts | Allow |
+
+No hidden bypass flag. Manual continuation: `flow auto stop`.
+
+## Main state-root resolution
+
+Bash must match Python `_db.default_db_path` intent:
+
+1. Explicit `FLOW_PROJECT_ROOT` is project root.
+2. Resolve Git worktree top + first/main worktree.
+3. Linked worktree subpath → equivalent main-worktree subpath.
+4. Submodule / `--separate-git-dir` ambiguity → current root + local receipts
+   warning; never place `.flow` inside Git internals.
+5. Receipts readable without Python.
+
+## CLI surface
+
+```text
+flow attest semantic --stage <stage> --revision <rev> --owner <manifest>
+flow attest semantic --card <id> --base <rev> --revision <rev> --owner <manifest>
+flow attest live-verify <id> --revision <rev> --owner <manifest>
+flow attest status [<stage|card>]
+flow attest recover <C-NNN> --mark-failed
+flow auto
+flow auto stop
+```
+
+Exit codes:
+
+- `0` — valid / pass / current accepted
+- `1` — missing / stale / red policy result
+- `2` — invalid usage / schema
+- Timeout / cap / signal → non-zero; never pass
+
+## Process supervisor (attestation only)
+
+Argv-safe: fixed cwd = logical checkout root, process group ownership,
+streaming stdout/stderr independent + combined caps, TERM → grace → KILL → wait.
+Capability probe: if reliable process-group supervisor unavailable, live
+verification and auto activation fail closed (never unbounded fallback).
+
+Usage/event logs for attestation record only subcommand, subject ID, result
+class, duration bucket — never argv after `--`, raw output, or secrets.
+
+## Locks
+
+Order: shared auto-policy mutex → subject locks sorted by `(subject_id, kind)`
+→ existing runner/workspace mutation lock.
+
+Hard consumers hold locks from validation through irreversible side effects
+(graph/harness/removal).
+
+## Backward compatibility
+
+- Manual/teach/work without auto state: warnings only; pre-v0.28 exit codes.
+- Planning `next` never hard-enforced in v0.28.
+- Bash + Git floor; Python/SQLite optional and never required to parse receipts.
+- Harness `risk_lane` remains separate advisory taxonomy (no silent sync).
+
+## Rollback
+
+`flow auto stop`, then revert enforcement. Receipt files under `.flow/` are
+run-state; remove for audit loss only — does not corrupt cards/DB.