@manhquy/flow-skill 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 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
+standard-command recipes, `@latest`-only help EXAMPLES, dual-version accuracy.
+
 ## [0.4.0] — 2026-08-11 — ships skill v0.27.0 (harness authority continuity)
 
 Skill-content release. Ships skill product **v0.27.0**: flow-owned durable authority,

package/README.md

@@ -1,148 +1,167 @@
 # @manhquy/flow-skill
 
-One-command installer that copies the [flow](https://github.com/manhquydev/flow-skill) skill into your coding agent(s).
+Install the **flow** skill into coding agents with one command.
 
-- Pure Node — works on macOS, Linux, and Windows (cmd, PowerShell 5.1/7, Git Bash) with the same code path.
-- Interactive multi-select or non-interactive CI mode.
-- Preserves any user-added files in the destination outside the 6 subdirs the skill owns.
-- Ships with [npm provenance](https://docs.npmjs.com/generating-provenance-statements) via GitHub Actions trusted publishing **starting with rc.2** — rc.1 was a manual bootstrap because npm Trusted Publisher cannot bind to a package that does not yet exist.
+| | |
+|---|---|
+| **Package** | [`@manhquy/flow-skill`](https://www.npmjs.com/package/@manhquy/flow-skill) (installer CLI) |
+| **Current GA** | **0.5.0** — ships skill product **v0.28.0** |
+| **Platforms** | macOS · Linux · Windows (same Node path) |
+| **Requirement** | Node.js **≥ 22.14** |
+| **Source** | [github.com/manhquydev/flow-skill](https://github.com/manhquydev/flow-skill) |
 
-## Install
+flow is a gated build harness (`/flow`): idea → honest gates → real done-evidence. This package only **installs** that skill into agent skill homes.
 
-```
-# Newest GA — current: v0.4.0, ships skill v0.27.0
+---
+
+## Standard install
+
+```bash
+# Recommended — always pin the dist-tag so npx does not reuse a stale cache entry
 npx @manhquy/flow-skill@latest
 ```
 
-An interactive prompt asks which agents to install to. Pick one or more, confirm, done.
+| Step | Detail |
+|------|--------|
+| 1 | Fetches **`latest`** from the npm registry |
+| 2 | Interactive multi-select of detected agents (Claude is always offered) |
+| 3 | Copies `skills/flow` into each selected destination |
+| 4 | Prints what to type after reload (`/flow`, `$flow`, …) |
 
-> **Always use `@latest`.** npx caches by bare name, so a plain `npx @manhquy/flow-skill` can
-> re-run a stale cached copy; `@latest` forces npx to fetch the newest GA release. See
-> [SECURITY.md](./SECURITY.md).
->
-> **`npm i` alone is not enough.** `npm install @manhquy/flow-skill` only adds the installer
-> package to `node_modules`. You must **run** it (`npx @manhquy/flow-skill@latest` or
-> `npx flow-skill` after install) to copy the skill into agent homes.
->
-> **Two version axes:** package `version` in this folder is the **installer** (e.g. `0.4.0`).
-> Skill product version lives in `skills/flow/SKILL.md` (`metadata.version`, e.g. `0.27.0`).
-> `--help` and the JSONL `plan` event expose both (`version` + `skillVersion`).
+**After install:** restart or reload the agent, then invoke flow (see [After install](#after-install)).
 
-## Non-interactive
+### Confirm versions
 
+```bash
+npx @manhquy/flow-skill@latest --help
+# expect: flow-skill v0.5.x (ships skill v0.27.x)
 ```
-# Default selection (Claude + anything detected)
+
+### Common commands
+
+```bash
+# Non-interactive (Claude + detected agents)
 npx @manhquy/flow-skill@latest --yes
 
-# Explicit targets
+# One or more targets
+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           # comma form OK
+npx @manhquy/flow-skill@latest --yes -t claude,codex
 
-# Force all five targets even if not detected
+# Every supported target
 npx @manhquy/flow-skill@latest --yes --all
 
-# Project scope (Claude only — see below)
+# Claude skill inside a project repo (commit-friendly)
 npx @manhquy/flow-skill@latest --yes --project --dir .
 
-# CI-friendly JSONL output
+# Plan only (no disk writes) + JSONL for CI
 npx @manhquy/flow-skill@latest --yes --all --dry-run --json
 ```
 
-## Targets
+### Options
 
-| Name | Label | Destination | Detection marker |
-|---|---|---|---|
-| `claude` | Claude Code | `~/.claude/skills/flow` | any presence of `~/.claude` (Claude is always pre-checked) |
-| `codex` | Codex CLI | `~/.codex/skills/flow` | `~/.codex/skills` |
-| `agents` | Agents home — also the universal [Agent-Skills](https://agentskills.io) home other spec-compliant tools read | `~/.agents/skills/flow` | `~/.agents/skills` |
-| `antigravity` | Antigravity (CLI + IDE) | `~/.gemini/antigravity-cli/skills/flow` **and** `~/.gemini/config/skills/flow` | `~/.gemini/antigravity-cli` **or** `~/.gemini/config/skills` |
-| `cursor` | Cursor | `~/.cursor/skills/flow` | `~/.cursor/skills` (never the bare `~/.cursor` config dir every Cursor user has) |
+| Flag | Meaning |
+|------|---------|
+| `-y`, `--yes` | Skip prompts; install default selection (detected + Claude) |
+| `-t`, `--target <name>` | Target (repeatable or comma-separated) |
+| `--all` | All targets, even if not detected |
+| `--project` | Project scope — Claude only → `<dir>/.claude/skills/flow` |
+| `--dir <path>` | Project directory (implies `--project`; default: cwd) |
+| `--json` | JSONL events (`plan`, `install:*`, `summary`) |
+| `--dry-run` | Print plan; do not write |
+| `-h`, `--help` | Help |
 
-`--project` scope writes to `<dir>/.claude/skills/flow` and supports only the `claude` target. Combining `--project` with a non-Claude target exits with code `2`.
+### Targets
 
-## After install
+| Name | Destination | Detection |
+|------|-------------|-----------|
+| `claude` | `~/.claude/skills/flow` | `~/.claude` (always offered) |
+| `codex` | `~/.codex/skills/flow` | `~/.codex/skills` |
+| `agents` | `~/.agents/skills/flow` | `~/.agents/skills` |
+| `antigravity` | `~/.gemini/antigravity-cli/skills/flow` **and** `~/.gemini/config/skills/flow` | either path |
+| `cursor` | `~/.cursor/skills/flow` | `~/.cursor/skills` |
 
-A freshly-installed skill isn't discovered by an agent until it reloads — the installer's final
-line tells you exactly what to do for whichever targets you installed:
+`--project` supports **only** `claude`. Other targets with `--project` exit `2`.
 
-- 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 (`~/.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
-  the `flow` skill.
-- Diagnostics: run `/flow doctor` from your agent.
+### Rules
 
-## Uninstall
+| Do | Don’t |
+|----|--------|
+| `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.5.0` if needed | Pin npm `@0.28.0` (skill version ≠ package version) |
+| Prefer `@latest` | `@rc` (retired / behind) |
 
-Delete the target directories:
+**Two version axes:** `package.json` version = installer; `SKILL.md` metadata = skill product. Both appear in `--help` and in the `plan` JSONL event (`version` + `skillVersion`).
 
+---
+
+## After install
+
+| Agent | Next step |
+|-------|-----------|
+| Claude Code | Type `/flow` |
+| Codex CLI | Restart Codex once → `$flow` |
+| Antigravity | Restart IDE / `agy` → `/flow` |
+| Agents home | Reload the tool if it does not auto-pick new skills |
+| Cursor | Reload Cursor; confirm `flow` in the agent skills panel |
+| Any | `/flow doctor` (or run `runner/flow.sh doctor`) |
+
+### Verify on disk (Claude global)
+
+```bash
+grep -E '^\s*version:' ~/.claude/skills/flow/SKILL.md | head -1
+bash ~/.claude/skills/flow/runner/flow.sh doctor
 ```
-# Global installs
+
+---
+
+## Uninstall
+
+```bash
 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
 rm -rf ~/.gemini/config/skills/flow
-
-# Project scope (only Claude)
+# project scope:
 rm -rf <project>/.claude/skills/flow
 ```
 
+---
+
 ## Troubleshooting
 
-- **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.26.0`**: that is the **skill product** version, not the npm package version. Install the installer by its own version (`@latest` / `@0.2.x`) — skill content version is printed by `--help` as `ships skill v…`.
-- **Installed package but agent has no `/flow`**: `npm i` does not run the installer. Run `npx @manhquy/flow-skill@latest` (or `npx flow-skill` if already installed) and restart the agent.
-- **Node too old** (`requires Node.js >=22.14.0`): upgrade with your preferred version manager (`nvm install 22`, `fnm install 22`, or Node's official installer). Node 20 reached end-of-life April 2026; npm OIDC Trusted Publishing needs npm >=11.5.1 which bundles with Node 22.14+.
+| Symptom | Fix |
+|---------|-----|
+| 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.28.0` | 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 |
 
-## JSONL contract
+---
 
-`--json` streams one JSON object per line:
+## JSONL (`--json`)
 
 ```jsonl
-{"event":"plan","version":"0.4.0","skillVersion":"0.27.0","dryRun":false,"scope":"global","targets":["claude","codex"]}
+{"event":"plan","version":"0.5.0","skillVersion":"0.28.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":2,"attempted":2,"installed":2,"failed":0,"skipped":0,"aborted":false}
+{"event":"summary","success":true,"total":1,"attempted":1,"installed":1,"failed":0,"skipped":0,"aborted":false}
 ```
 
-`--json --dry-run` emits only the `plan` event. `--json` implies non-interactive; do not combine with a TTY prompt session.
-
-### Event contract
-
-| Event | Required fields | Notes |
-|---|---|---|
-| `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`. |
-| `error` | `message` (string), `exitCode` (int) | Emitted only when the process crashes before completing a normal flow (e.g. missing bundled skill). Then exits with `exitCode`. |
-
-Exit codes: `0` success · `1` at least one target failed · `2` invalid usage (bad target name, `--project` with a non-Claude target, missing bundled skill) · `130` `SIGINT` (Ctrl+C).
+Exit codes: `0` success · `1` target failure · `2` bad usage · `130` SIGINT.
 
-The contract is additive within `0.1.x`. New optional fields may appear; existing fields will not be renamed or removed.
-
-## Requirements
-
-- Node.js **>= 22.14.0** — Node 20 reached end-of-life in April 2026, and the publish workflow requires npm >=11.5.1 (bundled with Node 22.14+) for OIDC Trusted Publisher support
-
-## Provenance
-
-Every version published from the CI workflow carries an [npm provenance](https://docs.npmjs.com/generating-provenance-statements) attestation (SLSA Build Level 2). Verify with:
-
-```
-npm view @manhquy/flow-skill@<version> dist.attestations.provenance
-```
+Contract is additive: new optional fields may appear; existing fields are stable.
 
-> **RC-window exception**: `v0.1.0-rc.1` was published manually from a developer machine to bootstrap npm's Trusted Publisher registration (Trusted Publisher cannot bind to a package that does not exist yet). npm does not generate provenance for publishes outside supported CI. All subsequent versions (`v0.1.0-rc.2` onward) publish through the workflow and are attested.
+---
 
-## Security
+## Provenance & security
 
-See [SECURITY.md](./SECURITY.md) for the threat model, what the installer will and will not do, and how to report issues.
+Published builds from CI include [npm provenance](https://docs.npmjs.com/generating-provenance-statements). Threat model and reporting: [SECURITY.md](./SECURITY.md).
 
 ## License
 

package/README_VN.md

@@ -1,127 +1,167 @@
 # @manhquy/flow-skill
 
-Trình cài đặt một-lệnh sao chép skill [flow](https://github.com/manhquydev/flow-skill) vào (các) coding agent của bạn.
+Cài skill **flow** vào coding agent bằng một lệnh.
 
-- Pure Node — chạy trên macOS, Linux, Windows (cmd, PowerShell 5.1/7, Git Bash) với cùng một code path.
-- Multi-select tương tác hoặc chế độ CI không tương tác.
-- Bảo toàn file người dùng đã thêm ngoài 6 subdir mà skill sở hữu.
-- Ship kèm [npm provenance](https://docs.npmjs.com/generating-provenance-statements) qua GitHub Actions trusted publishing (từ rc.2+).
+| | |
+|---|---|
+| **Package** | [`@manhquy/flow-skill`](https://www.npmjs.com/package/@manhquy/flow-skill) (installer CLI) |
+| **GA hiện tại** | **0.4.1** — ships skill product **v0.27.0** |
+| **Nền tảng** | macOS · Linux · Windows (cùng code path Node) |
+| **Yêu cầu** | Node.js **≥ 22.14** |
+| **Source** | [github.com/manhquydev/flow-skill](https://github.com/manhquydev/flow-skill) |
 
-## Cài đặt
+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.
 
-```
-# Newest GA — hiện tại: v0.4.0, ships skill v0.27.0
+---
+
+## Lệnh chuẩn
+
+```bash
+# Khuyến nghị — luôn gắn @latest để npx không dùng cache cũ
 npx @manhquy/flow-skill@latest
 ```
 
-Prompt tương tác hỏi cài vào agent nào. Chọn một hoặc nhiều, xác nhận, xong.
+| Bước | Chi tiết |
+|------|----------|
+| 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`, …) |
 
-> **Luôn dùng `@latest`.** npx cache theo bare name nên `npx @manhquy/flow-skill` có thể chạy
-> bản cache cũ; `@latest` ép lấy GA mới nhất. Kênh `rc` đã retire — không dùng `@rc`.
->
-> **`npm i` alone chưa đủ** — phải **chạy** CLI. Hai trục version: package npm vs skill product
-> (`ships skill v…` / `skillVersion` trong JSONL). Xem [SECURITY.md](./SECURITY.md).
+**Sau cài:** restart hoặc reload agent (xem [Sau khi cài](#sau-khi-cài)).
 
-## Non-interactive
+### Xác nhận version
 
+```bash
+npx @manhquy/flow-skill@latest --help
+# expect: flow-skill v0.4.x (ships skill v0.27.x)
 ```
-# Chọn mặc định (Claude + những agent detect được)
+
+### Lệnh hay dùng
+
+```bash
+# 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           # Dạng comma OK
+npx @manhquy/flow-skill@latest --yes -t claude,codex
 
-# Ép cài cả 5 target dù không detect
+# Mọi target được hỗ trợ
 npx @manhquy/flow-skill@latest --yes --all
 
-# Project scope (chỉ Claude — xem bên dưới)
+# Skill Claude trong repo (dễ commit)
 npx @manhquy/flow-skill@latest --yes --project --dir .
 
-# JSONL cho CI
+# Chỉ xem kế hoạch, không ghi đĩa + JSONL (CI)
 npx @manhquy/flow-skill@latest --yes --all --dry-run --json
 ```
 
-## Targets
+### Tùy chọn
 
-| Tên | Nhãn | Đích | Marker phát hiện |
-|---|---|---|---|
-| `claude` | Claude Code | `~/.claude/skills/flow` | bất kỳ presence của `~/.claude` (Claude luôn pre-check) |
-| `codex` | Codex CLI | `~/.codex/skills/flow` | `~/.codex/skills` |
-| `agents` | Agents home — cũng là thư mục [Agent-Skills](https://agentskills.io) chung mà các tool tuân chuẩn khác đọc | `~/.agents/skills/flow` | `~/.agents/skills` |
-| `antigravity` | Antigravity (CLI + IDE) | `~/.gemini/antigravity-cli/skills/flow` **và** `~/.gemini/config/skills/flow` | `~/.gemini/antigravity-cli` **hoặc** `~/.gemini/config/skills` |
-| `cursor` | Cursor | `~/.cursor/skills/flow` | `~/.cursor/skills` (không bao giờ dùng thư mục config `~/.cursor` trần — ai dùng Cursor cũng có) |
+| Flag | Ý nghĩa |
+|------|---------|
+| `-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`; mặc định: cwd) |
+| `--json` | JSONL events (`plan`, `install:*`, `summary`) |
+| `--dry-run` | In plan; không ghi đĩa |
+| `-h`, `--help` | Help |
 
-Scope `--project` ghi vào `<dir>/.claude/skills/flow` và chỉ hỗ trợ target `claude`. Kết hợp `--project` với target khác → exit code `2`.
+### Targets
 
-## Sau khi cài
+| Tên | Đích | Detection |
+|-----|------|-----------|
+| `claude` | `~/.claude/skills/flow` | `~/.claude` (luôn được đề xuất) |
+| `codex` | `~/.codex/skills/flow` | `~/.codex/skills` |
+| `agents` | `~/.agents/skills/flow` | `~/.agents/skills` |
+| `antigravity` | `~/.gemini/antigravity-cli/skills/flow` **và** `~/.gemini/config/skills/flow` | một trong hai path |
+| `cursor` | `~/.cursor/skills/flow` | `~/.cursor/skills` |
 
-Skill vừa cài xong sẽ không được agent nhận ra cho tới khi agent reload — dòng cuối cùng của
-installer nói rõ việc cần làm cho đúng target đã cài:
+`--project` **chỉ** hỗ trợ `claude`. Kết hợp target khác → exit `2`.
 
-- Claude Code: gõ `/flow`.
-- Codex CLI: gõ `$flow` (restart Codex 1 lần để load skill mới).
-- Antigravity: restart/reload IDE (hoặc restart `agy`) để load skill mới, rồi gõ `/flow`.
-- Agents home: restart/reload tool nếu nó không tự nhận skill mới.
-- Cursor: **đã xác nhận cài đúng chỗ, chưa xác nhận runner chạy độc lập** — Cursor không có
-  CLI headless để tự động kiểm (khác `agy -p` của Antigravity hay `codex exec` của Codex);
-  restart/reload Cursor sau khi cài rồi kiểm tra panel Agent xem có skill `flow` không.
-- Chẩn đoán: chạy `/flow doctor` từ agent.
+### Quy tắc
+
+| Nên | Không |
+|-----|--------|
+| `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.json` = installer CLI; `SKILL.md` metadata = skill product. Cả hai hiện trong `--help` và event JSONL `plan` (`version` + `skillVersion`).
+
+---
+
+## Sau khi cài
 
-## Gỡ cài đặt
+| Agent | Bước tiếp |
+|-------|-----------|
+| Claude Code | Gõ `/flow` |
+| 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`) |
 
-Xóa dir target:
+### Kiểm tra trên đĩa (Claude global)
 
+```bash
+grep -E '^\s*version:' ~/.claude/skills/flow/SKILL.md | head -1
+bash ~/.claude/skills/flow/runner/flow.sh doctor
 ```
-# Global installs
+
+---
+
+## Gỡ cài
+
+```bash
 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
 rm -rf ~/.gemini/config/skills/flow
-
-# Project scope (chỉ Claude)
+# project scope:
 rm -rf <project>/.claude/skills/flow
 ```
 
-## JSONL contract
-
-`--json` stream một JSON object mỗi dòng. Xem [README.md § JSONL contract](./README.md#jsonl-contract) cho bảng đầy đủ event/field/exit code. Tóm tắt:
+---
 
-- `plan` — event đầu tiên; chứa `version`, `dryRun`, `scope`, `targets`.
-- `install:start` / `install:done` — một cặp mỗi target; `install:done.result` = `success` hoặc `failed`.
-- `summary` — event cuối cùng; `success`, `total`, `attempted`, `installed`, `failed`, `skipped`, `aborted`.
-- Exit codes: `0` OK · `1` ≥1 target fail · `2` sai flag/target · `130` Ctrl+C.
+## Xử lý sự cố
 
-Hợp đồng additive trong `0.1.x` — field mới có thể thêm, field cũ không rename/xóa.
+| Hiện tượng | Cách xử lý |
+|------------|------------|
+| 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 |
 
-## Troubleshooting
+---
 
-- **`EBUSY`/`EPERM` giữa install trên Windows**: một agent đang giữ handle vào file trong destination. Đóng agent + re-run. Installer đã retry 100/300/900 ms trước khi báo error.
-- **Advisory lock cũ**: run trước crash. Run mới tự phát hiện PID dead → reclaim. Trường hợp hiếm (PID được recycle bởi process khác đang chạy): xóa `<parent-of-dest>/.flow-skill.installing.lock`.
-- **`No matching version found` với `@0.24.0`**: đó là version **skill product**, không phải version npm package. Cài installer theo version của nó (bare / `@0.1.x` / `@rc`) — version skill in ra ở `--help` (`ships skill v…`).
-- **Node quá cũ** (`requires Node.js >=22.14.0`): update bằng `nvm install 22`, `fnm install 22`, hoặc installer chính thức của Node. Node 20 hết vòng đời từ 4/2026; npm OIDC Trusted Publishing cần npm >=11.5.1 (bundle theo Node 22.14+).
+## JSONL (`--json`)
 
-## Yêu cầu
-
-- Node.js **>= 22.14.0** — Node 20 hết vòng đời từ 4/2026, và publish workflow cần npm >=11.5.1 (bundle theo Node 22.14+) cho OIDC Trusted Publisher
-
-## Provenance
+```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}
+```
 
-Mỗi phiên bản publish có [npm provenance](https://docs.npmjs.com/generating-provenance-statements) attestation. Verify:
+Exit codes: `0` success · `1` target failure · `2` bad usage · `130` SIGINT.
 
-```
-npm view @manhquy/flow-skill@<version> dist.attestations.provenance
-```
+Contract additive: field mới có thể xuất hiện; field hiện có không đổi tên/xóa.
 
-> **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
+## Provenance & 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.
+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).
 
 ## License
 

package/package.json

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

@@ -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.0"
   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.