@manhquy/flow-skill 0.7.3 → 0.7.5

package/skills/flow/references/claudekit-skills.md

@@ -1,12 +1,13 @@
 # claudekit skills — the per-stage capability map (the seam)
 
-`/flow` already orchestrates claudekit at the **agent layer** (`agent-detection.md` +
-`agent-stage-mapping.md`: 13 ck: agents, ck:→bmad→built-in degrade). This file extends that
-same seam to the **skill layer** — the curated set of ck *skills* worth reaching for at each
-stage, beyond the wired agents. It is a **whitelist, not a dump**: the kit has ~87 skills and
-~60% are marketing/content noise for a build harness. Only the skills below ever get surfaced.
-
-This is the single source of truth for the skill map; `agent-stage-mapping.md` points here.
+`/flow` already orchestrates specialists at the **agent layer** (`agent-detection.md` +
+`agent-stage-mapping.md`: host-native / ck: agents, then bmad, then built-in). This file
+extends that same seam to the **skill layer** — the curated set of build skills worth
+reaching for at each stage. It is a **whitelist, not a dump**: ClaudeKit (~87) and
+AgentKit (~100+) both ship marketing/content noise. Only the skills below ever get
+surfaced. ClaudeKit `ck-*` and AgentKit `ak:*` names are the **same rows** (Name
+resolution). This is the single source of truth for the skill map;
+`agent-stage-mapping.md` points here.
 
 ## Standalone note (v0.22)
 
@@ -32,6 +33,33 @@ review natively.
    missing skill **never lowers a gate** — it only changes whether the enrichment is offered.
    Rich where the skill exists, unbroken where it doesn't.
 
+
+## Name resolution (ClaudeKit + AgentKit)
+
+Host registries spell the same skill three ways: `ck-<slug>`, `ak:<slug>` /
+`ak-<slug>`, or bare `<slug>`. Strip `ck:` / `ck-` / `ak:` / `ak-` and match the
+slug. Offer the **first listed** alias; never offer two names for one verb.
+AgentKit is not a dependency — absence degrades to the native ritual.
+
+| Whitelist row | Also detect |
+|---|---|
+| ck-predict | ak:predict, ak-predict, predict |
+| ck-scenario | ak:scenario, ak-scenario, scenario |
+| ck-security | ak:security, ak-security |
+| ck-loop | ak:loop, ak-loop, loop |
+| ck-graphify | ak:graphify, ak-graphify, graphify |
+| review-pr | ak:review-pr, ak-review-pr |
+| security-scan | ak:security-scan, ak-security-scan |
+| retro | ak:retro, ak-retro |
+| xia | ak:xia, ak-xia |
+| deploy | ak:deploy, ak-deploy |
+| web-testing | ak:web-testing, ak-web-testing |
+| docs-seeker | ak:docs-seeker, ak-docs-seeker |
+| scout | ak:scout, ak-scout |
+| repomix | ak:repomix, ak-repomix |
+
+`gkg` / `ak:gkg` stay unwired (single graph pick = ck-graphify / ak:graphify).
+
 ## Cost gate — offer, don't impose
 
 The high-value skills below are **opt-in-with-prompt**: at the matching gate you *offer* the
@@ -91,10 +119,10 @@ tail, plumbing via `flow.sh loop-prep`/`loop-log` (this file).
 6. **ck-loop @ Build/Verify (Implement→Test→Audit→Fix tail)** — when a fix needs more than one
    experimental attempt against a single numeric target (failing-test count, lint errors, etc.),
    offer `flow.sh loop-prep <card>` to set up an isolated worktree + Verify/Guard commands, then
-   invoke the `ck-loop` skill with the printed block (ck-loop stays the untouched execution
-   engine — flow supplies plumbing only). See "Loop vs two-strikes" below for when to reach for
-   this instead of the default repair path. The finished run is recorded via `flow.sh loop-log`
-   (NOT the `intervention` channel below — recording it twice would double-count the same event).
+   invoke `ck-loop` or `ak:loop` with the printed block (the loop skill stays the untouched
+   execution engine — flow supplies plumbing only). See "Loop vs two-strikes" below. The
+   finished run is recorded via `flow.sh loop-log` (NOT the `intervention` channel below —
+   recording it twice would double-count the same event).
 
 ## Loop vs two-strikes — the one "fix it" decision tree
 
@@ -105,20 +133,22 @@ different tool for a different situation; do not let operators reach for the wro
 | Situation | Use | Why |
 |---|---|---|
 | Review BLOCKED twice, same model, no metric | two-strikes → cross-model lens | bounded disagreement, not a number |
-| One numeric verify command, needs >1 experimental attempt | `flow.sh loop-prep` + ck-loop | open iterate-to-target, git-tracked/revertable |
-| Drive failing-tests / lint / perf count to a threshold | ck-loop | Verify is a single number; Direction lower |
+| One numeric verify command, needs >1 experimental attempt | `flow.sh loop-prep` + ck-loop / ak:loop | open iterate-to-target, git-tracked/revertable |
+| Drive failing-tests / lint / perf count to a threshold | ck-loop / ak:loop | Verify is a single number; Direction lower |
 | Single obvious fix, one retry | default auto repair | cheaper than spinning up a worktree+loop |
 
 ## Don't surface (cut on purpose — these add noise, not signal)
 
 - **Skill/agent twins** — the wired agent already covers these; surfacing the duplicate skill
-  doubles the "what do I use" confusion: research/researcher, ck-code-review/code-reviewer,
-  ck-debug/debugger, test/tester, git/git-manager, ck-plan/planner, docs/docs-manager,
-  journal/journal-writer, ask, brainstorm. Prefer the **agent** for in-stage execution; reach
-  for the skill only for a distinct verb the agent lacks (already captured above).
-- **Competing orchestrators (cook, vibe, ship, bootstrap)** — each is its own end-to-end
+  doubles the "what do I use" confusion: research/researcher, ck-code-review / ak:code-review /
+  code-reviewer, ck-debug / ak:debug / debugger, test / ak:test / tester, git / ak:git /
+  git-manager, ck-plan / ak:plan / planner, docs / ak:docs / docs-manager, journal /
+  ak:journal / journal-writer, ask, brainstorm. Prefer the **agent** for in-stage execution;
+  reach for the skill only for a distinct verb the agent lacks (already captured above).
+- **Competing orchestrators (cook, vibe, ship, bootstrap, agentkit, plan, orchestrate, team, handover, issue-to-plan, fix)** — each is its own end-to-end
   pipeline with its own gates; invoking one inside a flow stage double-gates and fights flow's
   stage authority. Cherry-pick a sub-step (e.g. ship's merge/PR) at the matching stage only.
+  `ak:agentkit` routes *away* from flow — never invoke it mid-gate.
 - **`worktree` skill** — flow already ships `flow.sh workspace` (git-worktree-per-agent). Pure
   duplicate; never wire it.
 - **`bmad-spec` as a gate** — overlaps flow's own `/flow consistency` cross-artifact audit.

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

@@ -9,8 +9,8 @@ is no fragment loader (ADR-0001).
 
 | User input | Runner call | Host duties after |
 |---|---|---|
-| `/flow` | `bash <skill>/runner/flow.sh status` | Relay prose `NEXT ->`, dwell, and (past 10 cards) the compact summary; nothing to author. Optional `status --json` prints one `flow_context/v1` object (`v,stage,gate,next_verb,card,dwell,load`) — **display-only**. Hosts MUST NOT dispatch `next_verb` (`next`/`card`/`card-start`/`check`/`fix-gate`/`auto`/`skip`). Default `/flow` stays prose status. |
-| `/flow resume` | `bash <skill>/runner/flow.sh resume` | Read-only session-story; no lock. Optional `resume --json` same closed schema as status; display-only, never exec `next_verb`. FAIL/PASS/Never: SKILL.md STOP + Dispatch. |
+| `/flow` | `bash <skill>/runner/flow.sh status` | Relay prose `NEXT ->`, PIN v1 after NEXT_VERB (display-only, do not exec), dwell, and (past 10 cards) the compact summary; nothing to author. Compact recovery is prose status/resume, not `--json`. Optional `status --json` prints one `flow_context/v1` object (`v,stage,gate,next_verb,card,dwell,load`) — **display-only**. Hosts MUST NOT dispatch `next_verb` (`next`/`card`/`card-start`/`check`/`fix-gate`/`auto`/`skip`). Default `/flow` stays prose status. |
+| `/flow resume` | `bash <skill>/runner/flow.sh resume` | Read-only session-story; no lock. PIN v1 after NEXT_VERB, display-only, do not exec. Compact recovery is prose status/resume, not `--json`. Optional `resume --budget` caps in-flight cards at 5 with count line; `resume --json` same closed schema as status; display-only, never exec `next_verb`. FAIL/PASS/Never: SKILL.md STOP + Dispatch. |
 | `/flow next` | `bash <skill>/runner/flow.sh next` | After PASS, compare to `gate-examples.md` (not a second always-on load). FAIL/Never: SKILL.md STOP + Dispatch. |
 | `/flow assess` | `bash <skill>/runner/flow.sh assess` | Fill `flow/00-inspect.md` from EVIDENCE; Brownfield challenge in `gate-rules.md`. |
 | `/flow card` | `bash <skill>/runner/flow.sh card` | Fill per `law/CLAUDE.md`; before coding, `law/CODING.md`. |
@@ -21,25 +21,26 @@ is no fragment loader (ADR-0001).
 | `/flow contract` | `bash <skill>/runner/flow.sh contract` | Advisory client base-URL vs served-path drift; confirm on the running app. |
 | `/flow tokens` | `bash <skill>/runner/flow.sh tokens` | Advisory DESIGN.md token unused/mismatch; dated amendment if intentional. |
 | `/flow coherence` | `bash <skill>/runner/flow.sh coherence` | Advisory version-field drift; semantic contradictions stay a human challenge. |
-| `/flow consistency` | `bash <skill>/runner/flow.sh consistency` | Advisory PRD FRn coverage; then `gate-rules.md` cross-artifact passes. |
+| `/flow consistency` | `bash <skill>/runner/flow.sh consistency [--contract]` | Advisory PRD FRn coverage or contract endpoint audit (`--contract`); see `references/gate-consistency.md`. |
 | `/flow constitution` | `bash <skill>/runner/flow.sh constitution` | Advisory constitution form + markers; then `gate-rules.md`. Not a `next` gate. |
 | `/flow clarify` | `bash <skill>/runner/flow.sh clarify` | List leftover Open-decision boxes; write-back `references/clarify.md`. Not a `next` gate. |
 | `/flow converge` | `bash <skill>/runner/flow.sh converge [--file <payload>]` | Assess vs plan per `references/converge.md`; present the findings table first. |
 | `/flow eval [--stage 01\|02\|05\|card] [--fixture <id>] [--n 3] [--timeout <s>]` | `bash <skill>/runner/flow.sh eval [...]` | Billable; live mode skips if `claude` absent. `--replay` does not inherit that SKIP. See `references/gate-eval.md`. |
 | `/flow eval --report` | `bash <skill>/runner/flow.sh eval --report` | Offline; relay last complete batch + drift. See `references/gate-eval.md`. |
 | `/flow eval --replay` | `bash <skill>/runner/flow.sh eval --replay` | Keyless replay; missing/stale fixtures exit 1. Verdicts never count toward the eval floor. |
+| `/flow eval --diff <old> <new>` | `bash <skill>/runner/flow.sh eval --diff <old> <new>` | Offline; fixture regression classifier vs baseline. See `references/gate-eval.md`. |
 | `/flow project-type <web\|cli\|library\|skill>` | `bash <skill>/runner/flow.sh project-type [t]` | Set/read type per `references/project-types.md`. Confirm before planning. |
 | `/flow usage [--global\|--prune]` | `bash <skill>/runner/flow.sh usage [...]` | Relay local JSONL analytics; `--prune` caps the log. Nothing to author. |
 | `/flow skip <stage> --reason ...` | `bash <skill>/runner/flow.sh skip <stage> --reason ...` | Advance only with matching `DEBT.md`. Security-class: operator-only HALT. |
 | `/flow debt add\|list` | `bash <skill>/runner/flow.sh debt add\|list` | Record/list skips in `DEBT.md`. Security-class is operator-authored only. |
 | `/flow design <file>` | `bash <skill>/runner/flow.sh design <file>` | Advisory DESIGN.md mechanical check; pair `design-review-checklist.md` for UI cards. |
 | `/flow harness <args>` | `bash <skill>/runner/flow.sh harness <args>` | Passthrough to the durable-layer CLI; visible output + real exit. Use `recall` to read back. |
-| `/flow doctor` | `bash <skill>/runner/flow.sh doctor` | Relay FAIL as the fix list. Read-only. |
-| `/flow promote <file>` | `bash <skill>/runner/flow.sh promote <file>` | Copy playbook into `~/.claude/flow/playbooks` for cross-project `recall`. |
+| `/flow doctor` | `bash <skill>/runner/flow.sh doctor` | Relay FAIL as the fix list. Read-only. Also verifies runner integrity against the manifest hash (loud FAIL on drift; skipped on older installs without it). |
+| `/flow promote <file>` | `bash <skill>/runner/flow.sh promote <file> \| --suggest` | Copy playbook into `~/.claude/flow/playbooks` for cross-project `recall`, or suggest draft playbooks (`--suggest`) whose actions are derived from recorded harness patterns (>=2 occurrences); no generic advice is invented. |
 | `/flow mode teach` | `bash <skill>/runner/flow.sh mode teach` | Confirm; host gatekeeps, operator authors. |
 | `/flow mode work` | `bash <skill>/runner/flow.sh mode work` | Interview once, draft 00-05, pause for scope sign-off; same gates. See `references/mode-work.md`. |
 | `/flow ready` | `bash <skill>/runner/flow.sh ready` | Relay buildable cards; operator dispatches. Confirm allowed-files don't overlap. |
-| `/flow workspace <verb>` | `bash <skill>/runner/flow.sh workspace add\|list\|enter\|remove\|check\|doctor [...]` | Relay worktree isolation output; don't auto-`--force` a `remove`. Advisory. |
+| `/flow workspace <verb>` | `bash <skill>/runner/flow.sh workspace add\|list\|enter\|remove\|check\|doctor\|port [...]` | Relay worktree isolation output; don't auto-`--force` a `remove`. `workspace port` allocates deterministic per-card port (`references/host-agnostic-parallel.md`). Advisory. |
 | `/flow auto` | `bash <skill>/runner/flow.sh auto` | Load `references/auto-run.md`. |
 | `/flow auto stop` | `bash <skill>/runner/flow.sh auto stop` | Clear auto policy; return to warning-only manual path. |
 | `/flow attest …` | `bash <skill>/runner/flow.sh attest semantic\|live-verify\|status\|recover …` | Mint/inspect receipts (`references/attestations.md`). Must-ask before mint/recover. |

package/skills/flow/references/flow-catalog.tsv

@@ -7,14 +7,14 @@ brownfield-assess	existing-codebase-no-flow-history	assess	brownfield current-st
 kill-doubt-idea	stage-00-or-01	status	offers the forge-idea ritual (references/forge-idea.md) at Idea/Scope: persona-driven interrogation until it hardens, proves out, or dies cheaply	-	flow
 review-ask	cards-built-pending-review	check	card review path: diff-vs-scope, allowed-files drift, contract shapes, evidence	-	flow
 deploy-ask	review-passed	status	flow has no deploy verb; status shows the Deploy stage; execution stays operator/CI	-	flow
-retro-ask	stage-verify-or-later	retro	runs the native numeric-retro ritual first (git-log recipes), then offers the operator the line	retro	flow
+retro-ask	stage-verify-or-later	retro	runs the native numeric-retro ritual first (git-log recipes), then offers the operator the line	retro|ak:retro	flow
 usage-metrics-ask	any	usage	cycle-time, gate fail-rate, per-stage dwell, command breakdown	-	flow
 parallel-multi-agent-ask	any	ready	buildable + parallel-safety hint before offering workspace add	-	flow
 help-confused	any	status	ground truth first, then explain the gate concept in one plain sentence	-	flow
 card-create-ask	all-planning-gates-passed	card	create next build card; reminds Scope/Allowed-files/Verify/Done-evidence	-	flow
-adr-decision-ask	stage-04	next	offers the native persona-debate ritual before locking a non-trivial ADR decision	ck-predict	flow
-contract-hardening-ask	stage-05	contract	offers the native edge-case decomposition ritual to harden the seam before the Contract gate	ck-scenario	flow
-security-review-ask	security-class-card	check	runs the native STRIDE ritual on every security-class card (guaranteed baseline)	ck-security	flow
-loop-fix-ask	build-verify-numeric-gap	status	offers the native loop protocol (flow.sh loop-prep/loop-log) when a fix needs more than one attempt against a numeric target	ck-loop	flow
+adr-decision-ask	stage-04	next	offers the native persona-debate ritual before locking a non-trivial ADR decision	ck-predict|ak:predict	flow
+contract-hardening-ask	stage-05	contract	offers the native edge-case decomposition ritual to harden the seam before the Contract gate	ck-scenario|ak:scenario	flow
+security-review-ask	security-class-card	check	runs the native STRIDE ritual on every security-class card (guaranteed baseline)	ck-security|ak:security	flow
+loop-fix-ask	build-verify-numeric-gap	status	offers the native loop protocol (flow.sh loop-prep/loop-log) when a fix needs more than one attempt against a numeric target	ck-loop|ak:loop	flow
 open-decision-ask	stage-02-or-03-or-05	clarify	lists ## Open decisions bullets; skill offers references/clarify.md write-back (opt-in, never a next prereq)	-	flow
 close-the-gap-ask	cards-done-verify-plan	converge	assess present code vs plan per references/converge.md, then append-only remainder cards (transactional; CONVERGED writes nothing)	-	flow

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

@@ -8,5 +8,5 @@ NOT-doing list honest about what's deferred?
   debate (architect/security/ops/user-advocate/cost) that surfaces defects while reversal
   is still cheap. Output INFORMS this challenge; it never passes the gate. Skip on a
   trivial ADR.
-- **If `ck-predict` is installed**, it is a richer alternative to the native ritual (same
-  INFORMS-only rule, opt-in-with-prompt — see `claudekit-skills.md`).
+- **If `ck-predict` or `ak:predict` is installed**, it is a richer alternative to the native ritual (same
+  INFORMS-only rule, opt-in-with-prompt — see `claudekit-skills.md` Name resolution).

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

@@ -28,6 +28,6 @@ cli=command+flags+output/exit, library=public function+args+return, skill=comman
   no-drift check, so the contract is exhaustive before any card trusts it. Complements
   `/flow consistency` (it *generates* cases; consistency checks *coherence*). INFORMS
   the gate; never auto-passes it.
-- **If `ck-scenario` is installed**, it is a richer 12-dimension alternative to the
+- **If `ck-scenario` or `ak:scenario` is installed**, it is a richer 12-dimension alternative to the
   native ritual (same INFORMS-only rule, opt-in-with-prompt — see
-  `claudekit-skills.md`).
+  `claudekit-skills.md` Name resolution).

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

@@ -22,3 +22,15 @@ declared in the PRD's **`## Features`** section (ids in prose or the pain table
 ignored so a legacy mention can't inflate the set). A blank success-metric body is the gate's job, not
 this probe's (it only checks "if a metric exists, it carries a number"). When `consistency` reports
 "no FR ids found", treat it as *coverage-unverified*, not *coverage-clean*.
+
+## Contract-to-card endpoint coverage (`/flow consistency --contract`)
+
+Mechanical audit verifying that every endpoint declared in `flow/05-contract.md` is covered across generated cards before building starts.
+
+- **Extraction:** Parses `flow/05-contract.md`'s interface table (`Method` and `Path` columns; tolerates column order variations).
+- **Matching Rule:** Scans `cards/C-*.md` `## Scope` sections for literal path token substring matches (e.g. `/healthz`, `/api/users/:id`).
+- **Summary & Warnings:**
+  - Prints `N endpoint(s), M covered, K uncovered`.
+  - Uncovered endpoints produce an advisory warning block and exit 1 (matching `consistency` house convention for findings).
+  - Clean audit exits 0 (`PASS: all N endpoint(s) covered across cards/ scope.`).
+- **Auto-skip:** If `flow/05-contract.md` is absent or declares no endpoint table, prints a one-line note and exits 0 (consistent with F3 non-REST auto-skip spirit).

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

@@ -295,3 +295,37 @@ guard so an in-flight or in-postmortem run's dir cannot be pruned under the oper
 3. If the storm was rate-limit: wait past the window (typically minutes), then rerun.
 4. If persistent: capture the `.err` line in a comment, escalate — this is when a throttled
    `rate_limit_info` sample would land in the corpus and let `rate_limited` become authoritative.
+
+## eval --diff
+
+Offline longitudinal regression classifier across eval batches or model bumps.
+Mutually exclusive with live eval or replay (`flow.sh eval --diff <old_results> <new_results>`).
+Zero model calls, zero new runtime dependencies, deterministic.
+
+If multiple batches exist in an input results file, `--diff` compares the latest complete batch
+(falling back to the latest batch `run_id` present). Fixture expectations are resolved from each
+row's own `expected` field, falling back to `$EVAL_MANIFEST` (field 4).
+
+Classification is correctness-relative (`correct = verdict == expected`):
+
+| Old State | New State | Classification | Description |
+|-----------|-----------|----------------|-------------|
+| Correct (`old == expected`) | Correct (`new == expected`) | `UNCHANGED` | Intended verdict preserved (PASS→PASS on sound, FLAG→FLAG on hollow) |
+| Correct (`old == expected`) | Incorrect (`new != expected`) | `REGRESSED` | Previously correct fixture eroded (e.g. PASS→FLAG on sound, FLAG→PASS on hollow) |
+| Incorrect (`old != expected`) | Correct (`new == expected`) | `IMPROVED` | Previously failing/misclassified fixture now matches expected |
+| Incorrect (`old != expected`) | Incorrect (`new != expected`) | `SATURATED` | Neither run reached expected verdict (e.g. PASS→PASS on hollow, FLAG→INVALID) |
+| present | absent | `removed` | Fixture present only in old results |
+| absent | present | `added` | Fixture present only in new results |
+| unknown expected | any | `unknown` | Fixture missing expected verdict in both records and manifest |
+| `expected_old != expected_new` | any | `expectation-changed` | Expected verdict changed between runs; displayed as `OLD→NEW` in expected column; does not count as regressed or improved |
+
+An `INVALID` or `UNRELIABLE` verdict represents an infra/parse/timeout failure and never matches an expected `PASS` or `FLAG`. An `INVALID` outcome on a previously correct fixture is always classified as `REGRESSED`. Unknown fixtures (`expected` unresolvable) show `unknown` and never flip the exit code.
+
+### Output and exit codes
+
+Prints a compact aligned table (`id`, `expected`, `old`, `new`, `classification`) followed by summary counts:
+`N regressed, M improved, K saturated, U unchanged, E expectation-changed`.
+
+- Exit `0`: clean comparison (0 regressed).
+- Exit `1`: regression detected (≥1 fixture classified as `REGRESSED`).
+- Exit `2`: missing, unreadable, or containing no fixture records.

package/skills/flow/references/host-agnostic-parallel.md

@@ -52,3 +52,82 @@ evidence. No hook install into `~/.claude` or `~/.omp`. No long-lived socket sub
 
 Own-runtime / own-PTY / own-wait is a successor ADR plus a separate product,
 not a card in this skill.
+
+## workspace port
+
+Deterministic per-card port allocator for parallel worktree web verification (`flow workspace port <C-NNN>`).
+
+- **Formula:** `port = FLOW_WORKSPACE_BASEPORT + port_offset` (where `port_offset` is the registered worktree offset from `.flow/workspaces.jsonl`). Stable per registration and matches `workspace enter`.
+- **Port Bounds & Fail-Loud:** If `port = FLOW_WORKSPACE_BASEPORT + port_offset > 65535`, `workspace port` fails loudly with exit 2 (`FAIL - port range exhausted for '<card>' (baseport <b> + offset <o> = <raw> > 65535); lower FLOW_WORKSPACE_BASEPORT`) rather than wrapping or aliasing.
+- **Environment Override:** `FLOW_WORKSPACE_BASEPORT` (defaults to `3000`; valid numeric range is `1..65535`). Out-of-range baseport exits 2.
+- **Target File Contract:** Writes/overwrites strictly `<worktree>/.env.flow.local` inside the card's registered workspace root with:
+  ```sh
+  PORT=<port>
+  FLOW_CARD=<C-NNN>
+  ```
+  Mutates only this single file; zero locks needed beyond standard workspace mechanics.
+- **Exit Codes:**
+  - `0`: Workspace resolved, port computed, `.env.flow.local` written.
+  - `2`: Card argument invalid shape, no registered workspace in `.flow/workspaces.jsonl`, missing `port_offset`, baseport out of range, or port range exhausted > 65535 (never creates worktrees implicitly).
+
+## resume output contract
+
+`flow resume` is the external-orchestrator re-entry surface. It is read-only for planning/card state (event-tail + registry reads via
+`inflight_display`; no lock, no plan/card mutation, no `next_verb`
+execution) — but the runner's EXIT trap (`_log_on_exit` -> `_log_event`)
+still appends telemetry on every invocation (a row to the project's
+`events.jsonl` plus a compact row to the device-global log), so expect
+those files to grow. The documented elements below describe shipped
+behavior; anything not listed here is not to be parsed.
+
+**Output shape, in order:**
+
+1. **Header.** `flow resume`, then indented `project:` (repo root) and
+   `auto:` (attestation auto state). If planning has not started
+   (`current_stage_idx < 0`), resume emits only `nothing to resume - <next
+   action>` + `NEXT_VERB=<verb>` and stops.
+2. **Last-session telemetry block.** The most recent foreign session_id in
+   `events.jsonl` (string inequality vs the current session), emitting that
+   session's rows as `<ts> <command> ok|FAIL(n) [stage_from -> stage_to]`.
+   Command **NAMES only — never raw args** (free-text args can carry
+   unmasked secrets). Rows are capped `tail -5` (most recent wins). A
+   `ppid:`-scheme session whose latest foreign row is < 900s from the anchor
+   (this session's own first row if present, else wall-clock `now` — the
+   no-own-row-yet case is exactly when resume runs) is labeled
+   `recent activity` instead of `last session`, because PID reuse makes a
+   "last session" that may never have existed. Absolute timestamps shown
+   either way. If `events.jsonl` is empty/absent: `no telemetry - showing
+   gate state only`, then gate state + NEXT, and no in-flight section.
+3. **In-flight section.** `in flight:` header, then one line per todo card
+   still registered in `$CARDS_DIR/.inflight` (`cards/.inflight`, per
+   `_inflight_file`): `    <id> (in flight, started
+   <Xm|Xh|Xd> ago)`. Stale ids (card file gone) self-skip; **completed cards
+   are never listed** (only `status: todo` rows qualify).
+4. **Gate state.** Identical block to `flow status` (`_gate_state_brief`):
+   current stage only — `planning: at stage <s>` plus `gate: PASS|BLOCKED`.
+   (In the rare earlier-stage-blocked state, NEXT may point at an earlier
+   stage than this current-stage gate; that is by design.)
+5. **Exactly one `NEXT -> <action>` + `NEXT_VERB=<verb>` line pair**, from
+   the same `_next_action` ladder as `status` — the two verbs can never
+   disagree.
+
+**`--budget` semantics.** `resume --budget` caps the in-flight list at 5
+lines plus one `    +M more in flight - see 'flow card'` summary line
+(where M = hidden count). With ≤5 in-flight cards, `--budget` output is
+**byte-identical to default resume output** (matching rule:
+byte-identical-under-budget). No other section is affected; default resume
+lists all in-flight cards and never emits the summary line. Extra arguments
+to either form exit 2.
+
+**`resume --json`.** Emits exactly one closed `flow_context/v1` object —
+the same schema as `status --json`:
+`{"v":"flow_context/v1","stage":...,"gate":"PASS|BLOCKED|none","next_verb":...,"card":...,"dwell":...,"load":...}`.
+Display-only: it reports what to run next but never executes `next_verb`.
+
+**Scope note (not a stability promise).** The elements above are parseable by external
+orchestrators; parse only these, never ad-hoc prose. This documents shipped
+behavior as of the current flow version (`version` in `skills/flow/SKILL.md`
+— currently 0.34.0 — surfaced as `flow_version` in telemetry). The project
+has not adopted a formal compatibility guarantee: when upgrading flow,
+re-diff this contract against the runner (`cmd_resume`, `inflight_display`,
+`_log_event`) before relying on it.

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

@@ -6,12 +6,12 @@ maintenance. Each was written fresh from public/generic patterns (persona-panel
 generic edge-case taxonomy, STRIDE — public Microsoft SDL methodology, git-log
 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
+or any other kit. Where a matching ck or ak 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.
+`claudekit-skills.md` for the optional-enrichment annex (Name resolution).
 
-Every ritual below follows the same rule as the ck skills it stands in for: it
+Every ritual below follows the same rule as the ck/ak skills it stands in for: it
 **informs** the gate; the gate (the `flow.sh` exit code + the semantic challenge) still
 judges. A ritual "looks good" is not a PASS.
 

package/skills/flow/references/pin-v1.txt

@@ -0,0 +1,5 @@
+PIN v1
+Never FLOW_FORCE a live session. Mechanical FAIL -> STOP.
+Security-class skip/debt -> HALT until the operator accepts in DEBT.md.
+Never mark a card done without pasted world-state evidence.
+NEXT_VERB is advisory; never auto-exec next, card, card-start, check, fix-gate, auto, or skip.

package/skills/flow/runner/attestations.sh

@@ -233,7 +233,7 @@ _att_git_clean_for_attest() {
     path="${path#\"}"; path="${path%\"}"
     case "$path" in
       .flow|.flow/*) continue ;;
-      flow/.lock|flow/.lock.d|flow/.lock.d/*) continue ;;
+      flow/.lock|flow/.lock.*|flow/.lock.d|flow/.lock.d/*) continue ;;
       cards/C-*.md)
         _att_card_projection_matches_head "$path" || return 1
         continue