@manhquy/flow-skill 0.3.1 → 0.4.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.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,
+SUPERSEDED GAP matrix, R-IMPROVE-HARNESS ritual, brownfield Evidence ledger + material-authority
+stop (see root `CHANGELOG.md` `## 0.27.0`). Publishes to dist-tag **`latest`**.
+
+### Changed
+- Bundled skill tree re-synced from monorepo `skills/flow/` (48 test suites green at ship).
+- Install: **`npx @manhquy/flow-skill@latest`**.
+
 ## [0.3.1] — 2026-08-11 — help USAGE shows @latest
 
 ### Fixed

package/README.md

@@ -10,7 +10,7 @@ One-command installer that copies the [flow](https://github.com/manhquydev/flow-
 ## Install
 
 ```
-# Newest GA — current: v0.3.1, ships skill v0.26.0
+# Newest GA — current: v0.4.0, ships skill v0.27.0
 npx @manhquy/flow-skill@latest
 ```
 
@@ -24,8 +24,8 @@ An interactive prompt asks which agents to install to. Pick one or more, confirm
 > 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.3.0`).
-> Skill product version lives in `skills/flow/SKILL.md` (`metadata.version`, e.g. `0.26.0`).
+> **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`).
 
 ## Non-interactive
@@ -104,7 +104,7 @@ rm -rf <project>/.claude/skills/flow
 `--json` streams one JSON object per line:
 
 ```jsonl
-{"event":"plan","version":"0.3.0","skillVersion":"0.26.0","dryRun":false,"scope":"global","targets":["claude","codex"]}
+{"event":"plan","version":"0.4.0","skillVersion":"0.27.0","dryRun":false,"scope":"global","targets":["claude","codex"]}
 {"event":"install:start","target":"claude","dests":["~/.claude/skills/flow"]}
 {"event":"install:done","target":"claude","dests":["~/.claude/skills/flow"],"result":"success","error":null,"warnings":[]}
 {"event":"summary","success":true,"total":2,"attempted":2,"installed":2,"failed":0,"skipped":0,"aborted":false}

package/README_VN.md

@@ -10,7 +10,7 @@ Trình cài đặt một-lệnh sao chép skill [flow](https://github.com/manhqu
 ## Cài đặt
 
 ```
-# Newest GA — hiện tại: v0.3.1, ships skill v0.26.0
+# Newest GA — hiện tại: v0.4.0, ships skill v0.27.0
 npx @manhquy/flow-skill@latest
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manhquy/flow-skill",
-  "version": "0.3.1",
+  "version": "0.4.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,8 +8,8 @@ keywords: [flow, buildflow, gate, build, ship, scope, prd, contract, card, deplo
 license: MIT
 metadata:
   author: flow-skill
-  version: "0.26.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)."
+  version: "0.27.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)."
 ---
 
 # /flow — buildflow gated build harness
@@ -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/**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 …`.
+- `harness/` — **flow-owned** durable layer (`flow.sh harness ...`): intake/story/**complete**/trace/decision/backlog. Live authority = this Python CLI + `flow.sh` + gate-rules (not external `harness-cli`). Historical gap: `harness/GAP-MATRIX-0.1.17.md` (SUPERSEDED). Never `story update --status implemented` — use `story complete --proof-source …`. Improve skill/harness guidance: ritual **R-IMPROVE-HARNESS** in `references/native-rituals.md` (explicit-only; fresh-agent rerun before keep).
 - `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/_templates/00-inspect.md

@@ -12,6 +12,7 @@ then check the gate. `/flow assess` seeds the auto-scan and validates this gate.
 - [ ] I listed the top risks / tech-debt / known issues
 - [ ] I noted the test + quality baseline (what is covered vs not)
 - [ ] A human reviewed this assessment (brownfield assessment is operator-gated)
+- [ ] Every material claim in this assessment is tagged in the Evidence ledger (no Unknown/Decision-required silently treated as product law)
 - [ ] No FILL placeholders remain in this file
 
 ## Detected (auto-scan)
@@ -38,5 +39,22 @@ is most likely to hide. [FILL: note which ranked surfaces you inspected + what y
 ## Test + quality baseline
 [FILL: what is tested vs not; how to run the suite; coverage if known]
 
+## Evidence ledger (claims)
+
+Tag every material claim from Functionality / Risks / Verdict. Do **not** write product
+policy as fact unless **Authoritative**. Tags:
+
+| Tag | Meaning |
+|-----|---------|
+| **Authoritative** | Instruction, accepted decision, product contract, documented procedure |
+| **Observed** | Code/config/tests show current behavior |
+| **Derived** | Direct operational consequence of observed implementation |
+| **Decision required** | Normative/product choice with no authority yet |
+| **Unknown** | Repo does not establish the answer |
+
+| Claim | Tag | Source (path or "none") |
+|-------|-----|-------------------------|
+| [FILL: one material claim] | Observed \| Authoritative \| Derived \| Decision required \| Unknown | path:line or none |
+
 ## Verdict
 [FILL: is the codebase healthy enough to build on? what must be fixed first?]

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

@@ -1,42 +1,61 @@
-# Gap matrix: flow durable layer vs repository-harness CLI 0.1.17
+# SUPERSEDED (2026-08) — historical comparison only
 
-**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.
+> **Live policy:** durable layer is **flow-owned**. **No further schema sync** from
+> repository-harness / `harness-cli`. Last published protocol-v1 archive:
+> **`harness-cli-v0.1.22`** (EOL; no features). Do not treat 0.1.14/0.1.17 as live trust pins.
+>
+> **Live authority:** `flow_harness.py` + `flow.sh` + `gate-rules.md` (see `harness/README.md`).
 
-Supersedes: brainstorm 260703 Thread1 (“nothing to upgrade”).
+---
+
+# Gap matrix (archive): flow durable layer vs repository-harness CLI 0.1.17
+
+**Historical authority note:** compared against `harness-cli-v0.1.17` during v0.24 trust-align.
+Pins below are **archive labels**, not install targets.
+
+| Archive label | Tag | Historical use |
+|---------------|-----|----------------|
+| Protocol floor (archive) | `harness-cli-v0.1.14` | protocol v1 discovery floor at trust-align time |
+| Trust-align snapshot | `harness-cli-v0.1.17` | US-101 spirit inspiration |
+| Do not use | `harness-cli-v0.1.16` | tag without published assets |
+| Last published archive | `harness-cli-v0.1.22` | EOL max (repository-harness ADR 0027) |
+
+Flow does not claim US-101 parity or an isomorphic control plane.
+
+**Supersession:** upstream work-graph / protocol-v1 is not a sync target (recorded 2026-07-26 graph band + 2026-08 EOL).
 
 ## Schema
 
-| Ver | Flow | Harness 0.1.17 | Notes |
-|-----|------|----------------|-------|
-| 001–004 | present (shared) | present | Hash-identical at last measure (2026-07-18) |
-| 005 | present | present | File hash may differ on comments only — do not overclaim DDL fork |
-| 006–008 | **absent** (reserved gap) | changesets / deps / hierarchy | Not adopted this plan |
-| 009–012 | **usage/accessed** (flow-only) | improvement identity / links / closure | **Semantic collision** — same numbers, different DDL |
-| 013 | absent | changeset content sha | Not adopted — stays reserved/absent |
-| 014+ | **graph-executor** (flow-owned band) | absent | Flow-owned since the 2026-07-26 supersession (plan `260726-1718-harness-graph-executor-langgraph-port`) |
-
-## Commands / invariants
-
-| Surface | Flow status | Harness 0.1.17 | Trust note |
-|---------|-------------|----------------|------------|
-| `story update --status implemented` | rejected (trust-align) | rejected (US-101) | Use `story complete` |
-| `story complete` | flow-native flags + honest `proof_source` | `story complete` + live verify | Flow may complete via `card_markdown_gate` **without** setting `last_verified_result=pass` |
-| `story verify` | optional shell verify_command | required for shell-proven complete | shell=True = operator-authored only |
-| `query sql` | **not exposed** | read-only connection | Do not add mutating SQL |
-| Rust forward | refused on flow-lineage DB | n/a | `FLOW_HARNESS_BACKEND=rust` → exit 2 when usage mirror / schema≥9 |
-| Changesets / work-graph | **flow-owned graph executor** (schema band 014+) | 006–013 | **Superseded 2026-07-26** (was: out of scope, FOMO red line) — flow builds its own work-graph; upstream 006–013 will NOT be adopted. Decision record: plan `260726-1718-harness-graph-executor-langgraph-port` |
-| `query contract --json` | not on Python CLI | protocol v1 discovery | Optional external binary smoke only |
-
-## Pins (consumer)
+| Ver | Flow | Harness 0.1.17 (archive) | Notes |
+|-----|------|--------------------------|-------|
+| 001–004 | present (shared ancestry) | present | Frozen; no further sync |
+| 005 | present | present | tool registry ancestry |
+| 006–008 | **absent** (reserved gap) | changesets / deps / hierarchy | Not adopted |
+| 009–012 | **usage/accessed** (flow-owned) | different upstream meaning | Semantic collision avoided |
+| 013 | absent | changeset content sha | Reserved/absent |
+| 014+ | **graph-executor** (flow-owned) | absent | Flow-owned since 2026-07-26 |
+
+## Commands / invariants (still live in flow Python)
+
+| Surface | Flow status | Trust note |
+|---------|-------------|------------|
+| `story update --status implemented` | rejected | Use `story complete` |
+| `story complete` | flow-native `proof_source` | Never forge `last_verified_result=pass` from markdown alone |
+| Rust forward | refused on flow-lineage DB | exit 2 when usage mirror / schema≥9 |
+| Changesets 006–013 | not adopted | graph band 014+ is flow-owned |
+
+## Historical pins (do not install as product dependency)
 
 ```
-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
+# archive labels only — not live authority
+HARNESS_PROTOCOL_V1_TAG_ARCHIVE = harness-cli-v0.1.14
+HARNESS_CLI_TRUST_ALIGN_SNAPSHOT = harness-cli-v0.1.17
+HARNESS_CLI_LAST_PUBLISHED_ARCHIVE = harness-cli-v0.1.22
+DO_NOT_USE = harness-cli-v0.1.16
 ```
 
 ## Rust refuse-forward
 
-Any DB with `usage_event` or `MAX(schema_version) >= 9` is **flow-lineage**. Python entrypoint must refuse forwarding to external `harness-cli` (exit 2). `graph` verbs are NEVER forwarded regardless of DB state (flow-only surface, band 014+). The former "schema re-home ≥014 (separate epic)" note is superseded 2026-07-26: 014+ is now the flow-owned graph-executor band; 013 remains reserved/absent.
+Any DB with `usage_event` or `MAX(schema_version) >= 9` is **flow-lineage**. Python entrypoint
+must refuse forwarding to external `harness-cli` (exit 2). `graph` verbs are NEVER forwarded.
+**Supersession:** upstream work-graph / protocol-v1 is not a sync target.

package/skills/flow/harness/README.md

@@ -1,20 +1,26 @@
 # flow-harness — durable layer
 
 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` (shared base schema + flow-only usage extensions). State lives at
+auto-scored execution traces, decision records, and the growth-rule backlog. State lives at
 `<project>/.flow/harness.db` and survives across sessions — this is the "external memory"
 that fights context rot.
 
-## Authority pins (repository-harness)
+## Live authority (flow-owned)
 
-| 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 |
+| Layer | Authority |
+|-------|-----------|
+| **Mechanical gates** | `runner/flow.sh` exit codes |
+| **Semantic gates** | `references/gate-rules.md` + `law/` |
+| **Durable memory** | **this Python CLI** (`flow_harness.py`) + `.flow/harness.db` — **flow-owned** |
 
-Gap inventory: [`GAP-MATRIX-0.1.17.md`](./GAP-MATRIX-0.1.17.md). Flow does **not** claim bit-identical US-101.
+Schema bands **001–005** are frozen shared ancestry with pre-EOL `repository-harness`;
+**009–012** and **014+** are flow-owned forever. **No further upstream schema sync**
+(repository-harness protocol v1 / `harness-cli` is EOL — ADR 0027; last published archive
+`harness-cli-v0.1.22`). Historical gap inventory:
+[`GAP-MATRIX-0.1.17.md`](./GAP-MATRIX-0.1.17.md) (SUPERSEDED comparison only).
+
+**Self-improving this skill:** explicit-only ritual **`R-IMPROVE-HARNESS`** in
+`references/native-rituals.md` (fresh-agent rerun before claiming a keep).
 
 ## Backends
 

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

@@ -1,6 +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
+# HISTORICAL ARCHIVE ONLY — not live product trust.
+# Digests from GitHub Release harness-cli-v0.1.17 (v0.24 trust-align snapshot).
+# Protocol v1 / harness-cli is EOL (repository-harness ADR 0027; last published archive 0.1.22).
+# Do not install as a flow dependency; flow durable layer is flow-owned Python.
+# TAG harness-cli-v0.1.17 (archive)
+# PROTOCOL_FLOOR harness-cli-v0.1.14 (archive)
 # DO_NOT_USE harness-cli-v0.1.16
 5d13f0a024d9d69701534a879581c9433bc0069e04d052e5aacd93b91b3b7a43  harness-cli-linux-x64
 128c42c251fb31b58582342c09c68be6ed3329340fb1d8f179c88590a4539c97  harness-cli-linux-arm64

package/skills/flow/references/command-dispatch.md

@@ -9,7 +9,7 @@ install dir; run from the project root so `flow/` and `cards/` resolve.
 | `/flow` | `bash <skill>/runner/flow.sh status` | Runner now prints its own `NEXT ->` line (same helper as `resume`) plus stage dwell and, past 10 cards, a compact done/in-flight/todo summary. Relay it; nothing to author. |
 | `/flow resume` | `bash <skill>/runner/flow.sh resume` | Read-only, no lock. Relay all four sections verbatim (last session, in-flight + dwell, gate state, NEXT ->). Run this FIRST when entering a project mid-cycle with no prior context this session. Never expand on or guess at raw args it didn't print — it deliberately shows command names only. |
 | `/flow next` | `bash <skill>/runner/flow.sh next` | If FAIL: relay the exact violations + line numbers; offer help, don't author/tick in teach mode. If PASS: run the stage's challenge in `gate-rules.md`; flag hollow content, let operator decide. |
-| `/flow assess` | `bash <skill>/runner/flow.sh assess` | Brownfield only: fill `flow/00-inspect.md` from EVIDENCE (read the code) — functionality/UI/UX vs product, risks, test baseline. Reuse `scout`/`researcher`. Gate is operator-reviewed; then proceed to `/flow next`. |
+| `/flow assess` | `bash <skill>/runner/flow.sh assess` | Brownfield only: fill `flow/00-inspect.md` from EVIDENCE (read the code) — functionality/UI/UX vs product, risks, test baseline, **Evidence ledger** claim tags. After mechanical PASS, apply gate-rules **Brownfield assess** challenge (no Observed→product-law promotion). Reuse `scout`/`researcher`. Gate is operator-reviewed; then proceed to `/flow next`. |
 | `/flow card` | `bash <skill>/runner/flow.sh card` | Confirm the new card id; remind: fill Scope (one thing) / Allowed files / Verify / Done-evidence per `law/CLAUDE.md`. |
 | `/flow card start C-NNN` | `bash <skill>/runner/flow.sh card start C-NNN` | Optional: mark the card in flight (operator-visible in-progress, shown in `/flow status`). Portable `cards/.inflight` registry; does NOT touch the gated `status:` field. Coexists with hand-edit. |
 | `/flow card done C-NNN` | `bash <skill>/runner/flow.sh card done C-NNN` | Optional convenience: CLI-owned flip to `done`, gated by the SAME done-rules as `check` (reverts on fail — never a hollow done). Then still apply the semantic card review (diff-vs-scope, contract shapes, real evidence) as with `check`. |

package/skills/flow/references/gate-rules.md

@@ -19,6 +19,20 @@ artifact, never silently block a sound one.
 > the bad shape, not less, and a hedging "unless it matters" clause turns a crisp recipe noisy. Pick
 > the form deliberately; don't reflexively reach for another "do NOT".
 
+## Brownfield assess (flow/00-inspect.md)
+
+Separate from Stage 00 Idea. After `flow.sh assess` mechanical PASS (no `[FILL]`, boxes
+checked), apply this semantic challenge before planning:
+
+- Are material claims in the **Evidence ledger** tagged
+  (Authoritative / Observed / Derived / Decision required / Unknown)?
+- Is any **Observed** or **Derived** claim silently promoted to must-build product law
+  without operator authority?
+- Are **Decision required** / **Unknown** items listed for the operator — not invented into
+  Scope/PRD?
+- If the ledger is empty or only `[FILL]` rows remain while the gate boxes are checked,
+  the assessment is hollow — report mechanically-passed-but-qualitatively-weak.
+
 ## Stage 00 — Idea
 Mechanical: pitch present, one real person named, no FILL.
 **Challenge:** Is the pitch really 3 sentences (who / pain / what)? Is the named person a
@@ -52,6 +66,9 @@ Mechanical: 7 boxes checked, no FILL.
 Mechanical: every feature has Impact (H/M/L) + Grade (A/B/C), no L-above-A in v1, cut list,
 GO/KILL, no FILL.
 **Challenge — watch for GRADE LAUNDERING:**
+- **Material-authority stop:** if materially different externally observable product choices
+  remain open (quota, identity key, tenancy model, response contract, enforcement owner, …),
+  **stop** — list the choice and consequences. Configurable defaults are not authority.
 - Is any expensive feature quietly graded B when it's really C? (realtime, payments from
   scratch, custom auth, autonomous agentic pipeline, heavy concurrency = C). Call C a C.
 - For every C in scope, is it justified as one of: (1) C IS the product -> it goes FIRST;
@@ -66,6 +83,8 @@ GO/KILL, no FILL.
 ## Stage 03 — PRD
 Mechanical: filled from stage 02, numeric success metric, pain&gain table, no FILL.
 **Challenge:**
+- **Material-authority stop:** if the PRD invents policy (who can access what, retention,
+  billing rules) with no prior operator/ADR authority, stop and list Decision-required items.
 - Is the success metric a real NUMBER ("first response < 2h"), not "save time" / "better UX"?
 - The pain&gain table is the spine: does *every pain* cite evidence (a stage-01 quote or
   named observation) AND name the v1 feature that kills it? Does *every v1 feature* kill at
@@ -91,6 +110,8 @@ access/effects column filled, no FILL.
 **The "interface" is the project type's seam** (`/flow project-type`): web=endpoint,
 cli=command+flags+output/exit, library=public function+args+return, skill=command/file.
 **Challenge — this is where producer/consumer drift is born (every type):**
+- **Material-authority stop:** access/effects (public/token/admin, writes) that encode product
+  policy without operator authority → stop; do not invent tenancy/auth from convenience.
 - Does every PRD feature map to at least one interface, and vice versa?
 - Does every interface have BOTH input and output shapes, with field/flag names that will not
   drift (the #1 AI-build failure: backend ships `player_email`, UI assumed `email`, both green;

package/skills/flow/references/native-rituals.md

@@ -1,13 +1,15 @@
-# Native gate rituals — standalone baseline (v0.22)
+# Native gate rituals — standalone baseline (v0.22+)
 
-Five clean-room playbooks that make flow self-sufficient without any external skill kit
-installed. Each was written fresh from public/generic patterns (persona-panel review,
+Six clean-room playbooks that make flow self-sufficient without any external skill kit
+installed. Rituals 1–5 cover product gates; **R-IMPROVE-HARNESS** covers skill/harness
+maintenance. Each was written fresh from public/generic patterns (persona-panel review,
 generic edge-case taxonomy, STRIDE — public Microsoft SDL methodology, git-log
-retrospection, iterate-to-numeric-target loops) — none of this text is copied from
-claudekit-engineer (proprietary, All Rights Reserved) or any other kit. Where a matching
-ck skill is installed, it is offered as a **richer alternative**, never a requirement —
-see the seam files (`gate-rules.md`, `adversarial-review.md`, `law/RETRO.md`) for the
-native-first wiring, and `claudekit-skills.md` for the optional-enrichment annex.
+retrospection, iterate-to-numeric-target loops, evidence-backed harness improvement) —
+none of this text is copied from claudekit-engineer (proprietary, All Rights Reserved)
+or any other kit. Where a matching ck skill is installed, it is offered as a **richer
+alternative**, never a requirement — see the seam files (`gate-rules.md`,
+`adversarial-review.md`, `law/RETRO.md`) for the native-first wiring, and
+`claudekit-skills.md` for the optional-enrichment annex.
 
 Every ritual below follows the same rule as the ck skills it stands in for: it
 **informs** the gate; the gate (the `flow.sh` exit code + the semantic challenge) still
@@ -131,3 +133,38 @@ Steps:
 Informs, never judges: this is execution machinery, not a gate — the card's Build/Verify
 gate (`flow.sh check`) still judges the final diff, exactly as it does for any other
 card.
+
+## 6. Improve-flow-harness ritual (R-IMPROVE-HARNESS)
+
+Purpose: improve one bounded future-agent behavior in **this skill** (guidance, templates,
+gate wording, playbooks, diagnostics) without turning every difficult task into permanent
+process. Port of the *spirit* of repository-harness `$improve-harness` — not a binary
+dependency. **Stable id: `R-IMPROVE-HARNESS`.** (Deferred strategist counsel is
+`R-STRATEGIST` — do not conflate.)
+
+When: the operator/maintainer **explicitly** asks to improve the harness/skill after
+observed reusable agent friction. Never auto-fire from `next`/`check`/`auto`. Inspection
+or "report friction" alone does **not** authorize skill edits.
+
+Steps:
+1. **Authority** — confirm explicit improve request; record repo root/revision.
+2. **Baseline** — representative job, concrete failure, evidence, human intervention,
+   known limitations. No observed baseline → stop with an experiment *proposal* only.
+3. **Earliest gap owner** — context | capability | domain | authority | proof | environment.
+4. **One intervention hypothesis** before editing:
+   ```
+   If <smallest change> at <owner>, then a fresh agent will <observable>
+   on <job>, because <mechanism>.
+   Evidence that would weaken this: …
+   ```
+5. Apply **only** that authorized change (prefer skill docs/templates/playbooks over
+   new frameworks). Run focused tests for the changed boundary.
+6. **Fresh rerun** — new agent session, equivalent start state. Record whether the
+   intervention was available, retrieved/invoked, and relevant. If no fresh rerun:
+   decision stays **pending fresh rerun** — **never claim keep**.
+7. **Decision:** keep | revise | remove | pending fresh rerun.
+8. On **keep**, prefer a durable note: `flow.sh harness backlog close …` or
+   `decision add` with `fresh_agent_rerun=yes` + session id.
+
+Informs, never judges: this ritual maintains the skill; it never passes a product gate
+and never auto-runs on the build path.

package/skills-manifest.json

@@ -2,7 +2,7 @@
   "source": "../skills/flow",
   "destRelative": "skills/flow",
   "fileCount": 84,
-  "syncedAt": "2026-08-11T06:05:58.635Z",
+  "syncedAt": "2026-08-11T07:44:16.437Z",
   "fileList": [
     "SKILL.md",
     "_templates/00-idea.md",