@ngockhoale/ukit 3.3.3 → 3.4.1

package/template_user/playbooks/architecture-decision.md

@@ -0,0 +1,28 @@
+---
+id: architecture-decision
+lanes: [map-impact, shared-edit]
+---
+You own this fork. Compare the alternatives on the stated constraints and leave a
+decision a later session can check — never settle the fork by just building one.
+If the user says "new task", re-route — do not treat the message as the next step.
+1. Gather constraints: restate the fork as a checkable question, then the forces
+   that govern it (scale, team, ecosystem fit, migration cost, blast radius) and
+   the non-negotiables — what no acceptable answer may violate.
+2. Enumerate the real alternatives, including "keep the status quo" when it is a
+   live option; kill each option with a stated reason or keep it in play.
+3. Compare the survivors on equal terms, constraint by constraint; split each
+   alternative into `observed` traits (seen in docs, source, or a probe) and
+   `inferred` ones — never upgrade a guess past its evidence.
+4. Record the decision: the call, the alternatives considered with their kill or
+   survive reasons, and a falsifiable rationale — the specific evidence that
+   would change the call ("revisit if load crosses X", "revisit if Y ships Z").
+5. Settle the fork, then stop: the recorded decision, not a spike, is the
+   deliverable. A fork whose settlement mechanism is a disposable artifact is a
+   `prototype` ask — the spike produces the evidence; this playbook produces the
+   decision. The decided path hands off to feature-implementation or migration
+   as a new routed task; it is not executed here.
+Reply: the decision, each alternative and why it won or lost, the falsifiable
+rationale in plain terms, and the recommended follow-on lane.
+Ask the human only for: a genuine preference call no evidence settles, a
+constraint only they can supply, or a real dead end. Everything else: compare,
+record, report it.

package/template_user/playbooks/autonomous-run.md

@@ -0,0 +1,43 @@
+---
+id: autonomous-run
+lanes: [shared-edit, map-impact]
+---
+You own this run. Loop work → verify → re-check-finish until the condition
+holds or the escape hatch fires — never fabricate a finish.
+If the user says "new task", re-route — do not treat the message as the next step.
+1. Bound the goal before touching anything: write the finish condition as a
+   checkable predicate you can re-run (e.g. "zero legacy callers", "all N
+   items verified"). An unbounded goal is not an autonomous run — name the
+   bound or stop, never loop on a vague ask.
+2. Work the loop: act, verify the step's evidence, re-check the finish
+   predicate. A phase is a checkpointed segment of this same loop with its
+   own predicate (PB-U21 merged), not a separate planner. Checkpoint each
+   segment by appending a milestone Progress entry —
+   `<ISO-8601> · milestone: <name> · last-green: <what passed> · files: <...>
+   · drift: none|<why>` — and persist a resumable record via
+   `resumable-run.mjs suspend <projectRoot> <taskId> --phase <phase> --next
+   <action> --completed <a,b,...>`; an interrupted session resumes through
+   session-pickup's `resumable-run.mjs read` state-verify, not this playbook.
+3. On repeated failure of the same step or segment predicate, escalate into a
+   deeper debug/verify lane — do not retry the same lane a fourth time, and
+   do not exit "blocked" on a fix-loop.
+4. Escalate (escape hatch): a blocker outside scope, an authorization
+   boundary, or the round cap reached — stop the loop, name the blocker
+   verbatim, and hand off the ledgered progress: the checkpointed milestone
+   entries plus a suspended resumable record. "Done" is only the finish
+   condition verified OR the hatch fired with its named blocker — nothing
+   else is a terminal report.
+5. On finish: run the final verification against the step-1 predicate and
+   report it. `stop-coordinator.mjs` is the single Stop authority — this
+   playbook declares no second stop/finish gate; your loop re-checks the
+   predicate, the coordinator decides whether Stop holds.
+Machinery: `resumable-run.mjs suspend|read` for checkpoints, the milestone
+Progress-entry format for the phase ledger, `stop-coordinator.mjs` as the ONE
+Stop evaluator. On Codex (no hook surface) run the same commands manually —
+enforcement stays advisory, never a live claim.
+Sub-playbooks: `orchestrate` when the ask is a standing multi-workstream
+program needing a coordinator; a single bounded goal stays here.
+Reply: the finish predicate, per-segment verification evidence, and the
+terminal state — verified finish or Escalate with the named blocker.
+Ask the human only for: irreversible writes, a genuine preference call no
+experiment settles, or a real dead end. Everything else: do it, report it.

package/template_user/playbooks/autopilot-full.md

@@ -0,0 +1,59 @@
+---
+id: autopilot-full
+lanes: [review-release]
+---
+You own a set of independent changes that should each become its own
+verified PR. You split the work into independent units, assign one owner per
+PR, run the units as sequential worktree waves, verify each merge-ready, and
+land each independently behind per-action authorization.
+If the user says "new task", re-route — do not treat the message as the next step.
+1. Confirm this is autopilot-full territory: two or more independent changes
+   that should each ship as its own verified PR, and you can reach
+   CI/review state plus git history. Dependent or stacked changes re-route
+   to `autopilot-stack`; a single change goes down the feature path — say
+   so and stop. If `gh` is missing or unauthenticated, report the CLI
+   failure verbatim — never fabricate check, review, or head state.
+2. Split the work into independent units: each unit stands alone on the
+   base branch — its own branch, diff, checks, and PR. Name the seam
+   between units and the files each touches; an overlap that makes order
+   matter is a dependency — re-route that pair to `autopilot-stack`.
+3. Assign one owner per PR and run sequential worktree waves (RCC-01
+   classes 1–3: branch/commit, feature-branch push, `gh pr create`). The
+   upstream provider connector plus parallel background agents fall back
+   here to sequential worktree waves — the pattern the handoff pipeline
+   already proves with its executor worktrees — plus `gh` per PR.
+   Parallelism is a cost optimization, not a correctness requirement; the
+   sequential wave preserves the semantics.
+4. Verify each unit merge-ready independently (RCC-01 classes 4–5): `gh pr
+   checks`, `gh pr view`, review threads via
+   `gh api repos/{owner}/{repo}/pulls/{n}/comments`, plus the unit's own
+   test/build run where the repo defines one. Record a per-PR verification
+   receipt — commands run, output, result. A green unit never vouches for
+   its neighbor; a unit that fails verification goes back to its owner, it
+   is never landed unverified.
+5. Land each independently — every merge/land is an irreversible write
+   behind the RCC-01 §Land-authorization boundary. Merge/land to the
+   default branch and push-to-default are gated: stop and `Ask the human`
+   before each one; authorization is per-action and never carried forward —
+   "land the set" authorizes the described sequence once, and a new merge
+   is a new authorization. The fallback land step is `gh pr merge` or
+   `git merge` into the default branch plus `git push` — no connector-only
+   step. A model never authorizes; the gate stays deterministic and human.
+   Record a per-PR land receipt: the authorization granted, the land
+   command, the resulting head.
+6. Finish when all units are landed as independent verified heads: `git
+   log`/`git rev-parse` the default branch and confirm every intended unit
+   is in. If authorization is missing or a unit fails verification, report
+   BLOCKED at that step naming the boundary or the failed unit — the
+   remaining units stay unlanded; never soft-fail around it.
+Every step here is `gh`/git over Bash (RCC-01 §Capability matrix) — full on
+Claude Code and omp; on Codex the gate posture is advisory /
+instruction-mediated (RCC-01 §Hook-free enforcement): the model is asked, not
+stopped.
+Reply: the unit map, each per-PR verification receipt, the land
+authorizations asked and granted, the per-PR land receipts with resulting
+heads, and the terminal state — all units landed, or BLOCKED with the named
+cause.
+Ask the human at every irreversible write — per-action, even mid-set — and
+for a genuine preference call no experiment settles or a real dead end.
+Everything else: do it, report it.

package/template_user/playbooks/autopilot-stack.md

@@ -0,0 +1,54 @@
+---
+id: autopilot-stack
+lanes: [review-release]
+---
+You build and verify a linear stacked-PR series on one base branch — a set
+of ordered changes where each layer depends on the layer beneath it. You
+order the stack, chain the branches, verify each layer on its parent, and
+hand the verified stack to the operator for review/land. You never land the
+stack yourself.
+If the user says "new task", re-route — do not treat the message as the next step.
+1. Confirm this is autopilot-stack territory: a stacked-PR series on one
+   base branch where the layers genuinely depend on each other and a linear
+   order exists. Independent changes with no ordering requirement are
+   `autopilot-full`, and a single change is the feature path — re-route
+   both and stop. If you cannot reach git or `gh`, report the CLI failure
+   verbatim and stop — never fabricate stack, check, or PR state.
+2. Order the stack: lay out the layers base-to-tip from the dependency
+   order the user gave or the code requires, and record it — a stack
+   ordering record naming each layer, its branch name, and its parent. A
+   stack with no linear order is not a stack; if the ordering is
+   ambiguous, resolve it before the first branch exists.
+3. Chain the branches: each layer branches off its parent's head — `git
+   checkout -b <layer-branch> <parent-branch>` — never off the default
+   branch mid-stack. Open each PR with `gh pr create --base <parent>` so
+   the PR base is the parent layer's branch, not the default branch. This
+   is the RCC-01 §Provider-API fallback: connector stack metadata is
+   convenience, explicit git branch chaining is the capability — no step
+   is connector-only.
+4. Build and verify each layer on its parent: the layer's own test/build
+   run plus the diff against its parent branch. Record a per-layer
+   verification receipt — commands run, output, result — in stack order.
+   A layer that fails stops the chain there: later layers are never built
+   on an unverified parent, the failing layer is named verbatim, and the
+   run reports BLOCKED — never continue past it and never fabricate a
+   green.
+5. Hand the verified stack to the operator for review/land — the RCC-01
+   §Land-authorization boundary. The agent never lands the stack itself:
+   merge/land to the default branch is an irreversible write, gated per
+   action — if the operator delegates a land step to you, `Ask the human`
+   before each merge and never carry authorization forward; a model never
+   authorizes. Finish at the boundary: stack fully built and verified,
+   ordering record and receipts attached, operator reviewing — or BLOCKED
+   at the named layer.
+Every step is `gh`/git over Bash (RCC-01 §Capability matrix) — full on
+Claude Code and omp; on Codex the gate posture is advisory /
+instruction-mediated (RCC-01 §Hook-free enforcement): the model is asked,
+not stopped.
+Reply: the stack ordering record, each per-layer verification receipt, the
+PR list with its `--base` chain, and the terminal state — stack built and
+verified, handed to the operator for review/land, or BLOCKED at the named
+layer.
+Ask the human only for: a land authorization the operator delegates to you
+(per merge, never carried forward), a genuine ordering call the code cannot
+settle, or a real dead end. Everything else: do it, report it.

package/template_user/playbooks/babysit.md

@@ -0,0 +1,39 @@
+---
+id: babysit
+lanes: [review-release]
+---
+You own this PR's journey to merge-ready. Loop read-state → fix → push →
+re-check until CI is green, every review thread is resolved, and no conflicts
+remain — then hand back. The merge itself is out of scope.
+If the user says "new task", re-route — do not treat the message as the next step.
+1. Confirm this is babysit territory: a PR is already open (upstream's
+   PR-create step class, RCC-01 class 3, is done) and you can reach CI/review
+   state. No open PR, or no CI-or-review access → not babysit — say so and
+   stop. If `gh` is missing or unauthenticated, report the CLI failure
+   verbatim — never fabricate check or review state.
+2. Read state (RCC-01 class 4): `gh pr checks` for CI, `gh pr view` for PR
+   status, and review threads via
+   `gh api repos/{owner}/{repo}/pulls/{n}/comments`. Record a snapshot — CI
+   statuses, unresolved threads, conflict state.
+3. Fix what the snapshot names: resolve failing checks and review comments,
+   rebase or merge-base-resolve conflicts, then `git push` — class 5's
+   conflict/comment resolution loop composing commit + push + status reads.
+   Feature-branch pushes are reversible; run them autonomously.
+4. Re-check: re-read the same three surfaces and take a new snapshot. Repeat
+   the loop until the PR reports merge-ready — CI green, threads resolved, no
+   conflicts. Polling cadence is manual on the `gh`/git-over-Bash fallback
+   (RCC-01 §Provider-API fallback row): you re-run the reads; nothing polls
+   for you.
+5. Finish at merge-ready and hand back — landing belongs to `shipping` behind
+   the RCC-01 §Land-authorization boundary (an irreversible write), so this
+   playbook never performs the merge. If authorization or capability is
+   missing at any step, report BLOCKED at that step with the named cause —
+   do not soften it.
+Every step here is `gh`/git over Bash (RCC-01 §Capability matrix) — full on
+Claude Code and omp; on Codex the gate posture is advisory /
+instruction-mediated (RCC-01 §Hook-free enforcement): the model is asked, not
+stopped.
+Reply: the PR number, the per-round CI + review-thread snapshots, and the
+terminal state — merge-ready handed back, or BLOCKED with the named cause.
+Ask the human only for: irreversible writes, a genuine preference call no
+experiment settles, or a real dead end. Everything else: do it, report it.

package/template_user/playbooks/bug-fix.md

@@ -12,7 +12,9 @@ If the user says "new task", re-route — do not treat the message as the next s
    "might help" is a hypothesis, not a fix; it does not ship.
 4. Verify on the same surface: the original repro now passes. "Inconclusive" or
    wrong-surface is not a pass. A unit test shows branch behavior, not bug absence.
-5. Keep the rejected hypotheses — one line each, why ruled out.
+5. Keep the rejected hypotheses — one line each, why ruled out. When rejections on
+   this same defect cross the fix-loop threshold, stop retrying this lane —
+   escalate to runtime-forensics (live symptom) or a deeper debug/verify lane.
 Reply: what was broken, root cause, fix, how verified — paste failing-then-passing
 repro output verbatim.
 Ask the human only for: irreversible writes, a genuine preference call no experiment settles, or a real dead end. Everything else: do it, report it.

package/template_user/playbooks/{issue-implementation.md → feature-implementation.md}

@@ -1,14 +1,16 @@
 ---
-id: issue-implementation
+id: feature-implementation
 lanes: [local-build, shared-edit, map-impact]
 ---
 You own this task. Normalize the goal, build, verify.
 If the user says "new task", re-route — do not treat the message as the next step.
 1. State the done condition as a checkable predicate before writing code.
 2. Find the established analog — follow it unless you name why it does not fit.
+   (Skippable only when you can name why no analog exists.)
 3. Name the data shape and its organizing structure before writing logic.
 4. Implement the smallest change satisfying the predicate.
 5. Verify against the predicate on the real artifact — not "it compiles".
 6. Widen once: check the impact surface the route named, no broader.
 Reply: what changed, the predicate, the evidence it now holds.
-Ask the human only for: irreversible writes, a genuine preference call no experiment settles, or a real dead end. Everything else: do it, report it.
+Ask the human only for: irreversible writes, a genuine preference call no experiment
+settles, or a real dead end. Everything else: do it, report it.

package/template_user/playbooks/hillclimb.md

@@ -0,0 +1,44 @@
+---
+id: hillclimb
+lanes: [local-build, find-cause]
+---
+You own a sustained optimization program — one metric, one target, a
+hypothesis loop, and a ledger. A hillclimb ends at the target or at the
+stated stop criterion; it never drifts open-ended.
+If the ask is a single measured perf issue, re-route to performance —
+Performance Fix != Hillclimb; this playbook is a program, not one fix.
+If the metric is not yet measurable (no baseline, no harness), re-route to
+investigation and stand up the measurement first — never climb blind.
+If the user says "new task", re-route — do not treat the message as the next
+step.
+1. Pin the program: name the metric, the target, and the measurement harness
+   (the benchmark or timed run that produces the number), and state the stop
+   criterion up front — an iteration budget, a time box, or a plateau rule.
+   A program without a written stop criterion is not a hillclimb — bound it
+   or stop.
+2. Propose one hypothesis per iteration — a single change with the mechanism
+   it should move ("inlining X cuts allocation churn"). Never batch
+   hypotheses: a mixed step cannot be attributed, so it cannot be learned
+   from.
+3. Measure: run the same harness and record the number against the
+   iteration's baseline. Keep the harness untouched across iterations so
+   every delta stays comparable.
+4. Accept or reject the change on the measured delta alone and record the
+   verdict — accept keeps the change as the new baseline; reject reverts it.
+   A rejected hypothesis still gets a verdict line: negative results are
+   ledger evidence, not silence.
+5. Repeat from step 2 until the target is reached or the pinned budget/stop
+   criterion is exhausted — then stop and report the ledger either way.
+Ledger: every iteration appends one entry to the exec-ledger surface under
+`.ukit/storage/cache/exec-ledger/` in the milestone Progress-entry grammar —
+`<ISO-8601> · milestone: hillclimb-<n> · last-green: <what passed> · files:
+<...> · drift: none|<why>` — carrying hypothesis → measurement → verdict, so
+an interrupted program resumes from the ledger, not from memory.
+Machinery: plain Bash for harness runs and ledger appends on all three
+engines; on Codex the ledger stays advisory — no hook surface enforces it.
+Reply: the metric and target, the per-iteration ledger (hypothesis →
+measurement → verdict), and the terminal state — target reached or the stop
+criterion exhausted.
+Ask the human only for: irreversible changes, a metric/target preference call
+no measurement settles, or a real dead end. Everything else: run the loop,
+report the ledger.

package/template_user/playbooks/investigation.md

@@ -0,0 +1,21 @@
+---
+id: investigation
+lanes: [find-cause, map-impact]
+---
+You own this question. Answer it with citations or falsify it — you may not mutate
+the repo to get there.
+If the user says "new task", re-route — do not treat the message as the next step.
+1. Frame the question as a checkable claim — what would confirm it, what would
+   falsify it.
+2. Gather evidence read-only: index-first lookups, source reads, non-mutating
+   commands. No edits, no scaffolds.
+3. Classify every finding: `observed` (seen in source or output), `inferred` (it
+   follows), `unverified` (cannot be checked here) — never upgrade a claim past
+   its evidence.
+4. Answer the question, or mark it unresolved with the exact missing evidence
+   named. (Skippable: the unresolved branch only when every claim is observed.)
+5. Confirm zero mutation — `git status` clean, no stray files.
+Reply: the answer with `path:symbol` or command-output citations per claim, the
+`unverified` items and why, and confirmation the repo is untouched.
+Ask the human only for: irreversible writes, a genuine preference call no experiment
+settles, or a real dead end. Everything else: do it, report it.

package/template_user/playbooks/migration.md

@@ -0,0 +1,21 @@
+---
+id: migration
+lanes: [shared-edit, map-impact]
+---
+You own this move. Land it on the new shape, verify it there, and prove the way
+back.
+If the user says "new task", re-route — do not treat the message as the next step.
+1. Pin the current state and behavior — counts, checksums, or the characterization
+   suite you will re-check after the move.
+2. Define the target shape and the rollback path before touching anything — a
+   migration with no demonstrated way back is not ready.
+3. Migrate in verifiable steps; re-check the pin on the target after each step,
+   not from memory.
+4. Verify on the target: read and exercise the moved data/system through the new
+   shape; the pin holds.
+5. Demonstrate rollback on a safe surface — run it or dry-run it and capture the
+   output; then schedule the legacy path for removal — it does not linger.
+Reply: what moved, the verification evidence on the target, the rollback
+demonstration, and the legacy-path removal plan.
+Ask the human only for: irreversible writes, a genuine preference call no experiment
+settles, or a real dead end. Everything else: do it, report it.

package/template_user/playbooks/open-pr.md

@@ -0,0 +1,48 @@
+---
+id: open-pr
+lanes: [review-release]
+---
+You own packaging this finished work into a review-ready PR — ordered commits,
+a conventional title, a briefing-style body, and a PR a reviewer can open
+cold. Landing the PR is not part of this playbook.
+If the user says "new task", re-route — do not treat the message as the next step.
+1. Confirm this is open-pr territory: a finished unit of work exists locally —
+   commits already made or a working tree ready to commit — and the repo has a
+   PR surface (a `gh`-reachable forge remote). No finished work to package, or
+   a repo without a PR surface → not open-pr — say so and stop. If `gh` is
+   missing or unauthenticated, report the CLI failure verbatim — never
+   fabricate PR or check state.
+2. Order or split the commits (RCC-01 class 1): read `git status` and `git
+   log`/`diff` against the base branch, then shape the history a reviewer
+   expects — one logical change per commit, ordered so each commit builds on
+   the last, splits that separate mechanical moves from semantic edits. On a
+   feature branch this is reversible and runs autonomously; never rewrite or
+   reorder commits already pushed to the default branch — that belongs behind
+   `Ask the human`.
+3. Write the title: conventional-commit shape (`type(scope): summary` —
+   `feat:`, `fix:`, `chore:` …) in imperative mood, sized to one line. The
+   title names what the PR does, not the task that asked for it.
+4. Write the body: briefing style — what changed and why up front, the
+   evidence (commands run, output that proves it), then anything a reviewer
+   must know before reading the diff. A reviewer who never saw this session
+   should be able to approve from the body alone.
+5. Open the PR with `gh pr create` (RCC-01 class 3): first push the feature
+   branch — a reversible write, autonomous — then create with the title and
+   body from steps 3–4. The fallback is forge REST over `gh api`/`curl` via
+   Bash (RCC-01 §Provider-API fallback) — the trivial fallback that makes this
+   the release group's lead entry; no step is connector-only.
+6. Confirm ready state: `gh pr view` the new PR — it exists, is non-draft
+   unless a draft was asked for, points at the right base, and carries the
+   title/body you wrote. The merge itself, any push or merge to the default
+   branch, is an irreversible write behind the RCC-01 §Land-authorization
+   boundary — this playbook never performs it; if the ask was "open AND land",
+   stop at the open PR and `Ask the human` for the land, or hand to `shipping`.
+Every step here is `gh`/git over Bash (RCC-01 §Capability matrix) — full on
+Claude Code and omp; on Codex the gate posture is advisory /
+instruction-mediated (RCC-01 §Hook-free enforcement): the model is asked, not
+stopped.
+Reply: the PR URL plus the title and body verbatim, and the terminal state —
+ready for review, or BLOCKED with the named cause.
+Ask the human only for: irreversible writes (default-branch push/merge, the
+land), a genuine preference call no experiment settles, or a real dead end.
+Everything else: do it, report it.

package/template_user/playbooks/orchestrate.md

@@ -0,0 +1,45 @@
+---
+id: orchestrate
+lanes: [shared-edit, map-impact]
+---
+You are the coordinator of a standing multi-workstream program. Loop
+decompose → assign → coordinate merges/conflicts → track state → report
+until program-level acceptance holds or a program-level blocker fires.
+If the user says "new task", re-route — do not treat the message as the next step.
+1. Confirm this is orchestrate territory: a standing program with more than
+   one workstream running at once. A single bounded goal is `autonomous-run`,
+   and a small parallel task set that fits one worktree wave needs no
+   coordinator — route both there and stop.
+2. Decompose the program into workstreams: each carries a bounded goal, a
+   checkable finish predicate (the autonomous-run contract), and declared
+   file/lane boundaries — the seams where streams meet are what you own.
+3. Assign owners: one executor worktree per workstream and a per-task file
+   per workstream under `docs/AI_HANDOFF/tasks/` as its owner/agent contract
+   — scope, status, predicate, Progress entries. Register every stream in
+   `docs/AI_HANDOFF/INDEX.md` and keep the `docs/AI_HANDOFF/RUN.md` cursor
+   pointing at the program's next step; that pair is the resumable surface.
+4. Coordinate merges and conflicts: when a stream's predicate verifies, fold
+   its worktree into the program order — name conflicts, classify which
+   stream owns the resolution, and record the call in the coordinator
+   decision log. You adjudicate seams; inside a worktree the owner executes.
+5. Track program state and report: milestone Progress entries —
+   `<ISO-8601> · milestone: <name> · last-green: <what passed> · files: <...>
+   · drift: none|<why>` — are the ledger; never trust `last-green` without
+   its verification evidence. Append a coordinator entry per decision so an
+   interrupted session resumes from INDEX/RUN, not from memory.
+6. Finish at program-level acceptance: every workstream predicate verified
+   AND cross-stream integration confirmed, then coordinator close-out —
+   reconcile INDEX statuses, drain the cursor, and summarize the decision
+   log. A blocker outside any stream's scope stops the program; name it
+   verbatim and hand back the ledger — never fabricate acceptance.
+This is the file-based pattern, not live multi-agent plumbing: no durable
+background agents, no cross-agent messaging — file handoff through
+INDEX/RUN, task files, and Progress entries is the whole contract. The same
+contract holds on all three engines: full on Claude Code and omp; on Codex
+(no hook surface) it is advisory / instruction-mediated — the model is
+asked, not stopped.
+Reply: the workstream map, the coordinator decision log, and the terminal
+state — program-level acceptance with the close-out, or BLOCKED with the
+named blocker.
+Ask the human only for: irreversible writes, a genuine preference call no
+experiment settles, or a real dead end. Everything else: do it, report it.

package/template_user/playbooks/performance.md

@@ -0,0 +1,33 @@
+---
+id: performance
+lanes: [local-build, find-cause]
+---
+You own a measured slowness claim. Turn it into a before/after delta on one
+harness — the measured delta is the finish; guessing is not.
+If the ask carries no measurable signal yet (no number, baseline, or harness),
+re-route to investigation and measure first — never optimize blind.
+If the symptom is live or intermittent (hangs, freezes, "sometimes"), re-route
+to runtime-forensics — that playbook names the mechanism first.
+If the user says "new task", re-route — do not treat the message as the next
+step.
+1. Baseline: identify the harness (benchmark, timed request, profiling run) or
+   build the smallest one that reproduces the symptom; record the measurement
+   and state the target margin explicitly.
+2. Trace: instrument the same harness — profile, flame graph, query plan,
+   timing breakdown — and name the hot path that dominates the symptom.
+3. Improve: make the smallest change aimed at that hot path; keep the harness
+   untouched so before/after stay comparable.
+4. Re-measure: run the same harness again. Finished only when the measured
+   delta meets the stated margin; otherwise iterate from the new profile or
+   hand back with the numbers you have.
+5. Leave the harness runnable: store captures under artifacts, keep the
+   commands copy-pasteable for the next run.
+One run proves one delta — repeated hillclimb passes beyond the stated margin
+are a follow-on run, not part of this one.
+Sub-playbooks: `hillclimb` when the ask is a sustained metric program with a
+target and an iteration budget; a single measured issue stays here.
+Reply: the before/after numbers, the harness + commands that produced them,
+the hot path found, and the change made.
+Ask the human only for: irreversible changes, a cost/complexity preference
+call no measurement settles, or a real dead end. Everything else: do it,
+report it.

package/template_user/playbooks/prototype.md

@@ -0,0 +1,28 @@
+---
+id: prototype
+lanes: [local-build]
+---
+You own this spike. Build the cheapest thing that settles the fork, then dispose
+or promote it — never leave it ambiguous.
+If the user says "new task", re-route — do not treat the message as the next step.
+1. State the design question this spike answers and the observation that settles
+   it — the measured number, render, or behavior that picks a side.
+2. Build the cheapest artifact that produces that evidence — hardcode freely;
+   hardening, tests, and wiring are deliberately skipped unless they are the
+   discriminating evidence.
+3. Measure or observe against the criterion from step 1; capture the output
+   verbatim — observed evidence, never an estimate.
+4. Record the verdict — which side the evidence picked and why the runner-up
+   lost; a fork decidable without building stops early with the verdict.
+5. Dispose or promote: mark the artifact throwaway (remove or quarantine it) or
+   flag it for promotion — a prototype silently left in place is a defect. The
+   spike answers a question; it does not ship a feature — no integration,
+   verification-map ceremony, or production-diff obligation applies here. When
+   the artifact must ship, hand off to feature-implementation with the findings.
+   A fork needing a recorded decision instead of a build is
+   architecture-decision territory — re-route rather than spike.
+Reply: the design question, the experiment output verbatim, the verdict, and the
+artifact disposition (disposable | promoted).
+Ask the human only for: irreversible writes, a genuine preference call no
+experiment settles, or a real dead end. Everything else: run it, record it,
+dispose of it.

package/template_user/playbooks/refactor.md

@@ -0,0 +1,19 @@
+---
+id: refactor
+lanes: [shared-edit, map-impact]
+---
+You own this restructure. Behavior must not change — pin it, move it, prove it.
+If the user says "new task", re-route — do not treat the message as the next step.
+1. Pin the current behavior: the existing suite, or characterization checks you
+   write first. A pin you cannot run is not a pin. (Skippable: writing
+   characterization checks only when a runnable pin already exists — cite it.)
+2. Apply the structural change in verifiable steps — re-run the pin after each,
+   not once at the end.
+3. Migrate every caller before deleting the old surface — a compatibility shim
+   still counts as a caller; sweep until zero legacy references remain.
+4. Re-run the pin with the new structure in place: green, zero behavior delta.
+5. Delete the old surface and its dead code — obsolete aliases and re-exports go
+   in the same change, not a follow-up.
+Reply: what moved, the pin evidence before-and-after, the caller sweep result.
+Ask the human only for: irreversible writes, a genuine preference call no experiment
+settles, or a real dead end. Everything else: do it, report it.

package/template_user/playbooks/release.md

@@ -0,0 +1,28 @@
+---
+id: release
+lanes: [review-release]
+---
+You own this ship chain — this repo's own release only. Done means all three
+version probes equal: package.json, git tag/GitHub Release, npm registry.
+If the user says "new task", re-route — do not treat the message as the next step.
+1. Update the version and changelog, commit, and run `yarn test:release-core`.
+2. `git push origin <branch>` and `git push --tags` with a tag matching the
+   version.
+3. Create the GitHub Release from that tag.
+4. `npm publish --dry-run` first, then `npm publish` in the same cycle.
+5. Probe all three sources — `npm view @ngockhoale/ukit version`, `gh release
+   list`, `git tag` — all must equal package.json; run
+   `node scripts/release/verify-release.mjs --post-publish`.
+6. If parity fails or publish never ran, say "not shipped" and name the exact
+   missing step — git-only or GitHub-only is not a release; stopping early is a
+   named miss, never a quiet success.
+Sub-playbooks: `open-pr` when finished local work needs packaging into a
+review-ready PR; `babysit` when an already-open PR must be driven to
+merge-ready; `shipping` when a stack of ready changes must be verified and
+landed; `autopilot-full` when independent changes should each ship as their
+own verified PR; `autopilot-stack` when ordered layers build a stacked-PR
+series.
+Reply: the version, the three probe outputs verbatim, and shipped | not shipped with
+the exact missing step.
+Ask the human only for: irreversible writes, a genuine preference call no experiment
+settles, or a real dead end. Everything else: do it, report it.

package/template_user/playbooks/runtime-forensics.md

@@ -0,0 +1,23 @@
+---
+id: runtime-forensics
+lanes: [find-cause]
+---
+You own this anomaly. Turn it into a named mechanism with captured evidence —
+naming the mechanism is the finish; fixing it is the follow-on run.
+If the user says "new task", re-route — do not treat the message as the next step.
+1. Pick the input branch: live process → attach and observe it; captured artifact
+   (.cpuprofile, trace, spindump, heap snapshot) → load it with the matching
+   analyzer.
+2. Capture the evidence: live = samples, heap, open handles over an observation
+   window; artifact = hot frames, dominators, blocked threads cited into the
+   capture.
+3. Isolate the anomaly — the state or hot path that explains the reported
+   symptom; rule out the candidates that do not.
+4. Name the mechanism and hand off — the fix goes to bug-fix or performance as a
+   follow-on run, carrying this evidence.
+5. Release the patient: detach or kill instrumentation, store captures under
+   artifacts, leave nothing running.
+Reply: the anomaly, the named mechanism, the captures/derived readings that prove
+it, and the recommended follow-on lane.
+Ask the human only for: irreversible writes, a genuine preference call no
+experiment settles, or a real dead end. Everything else: do it, report it.

package/template_user/playbooks/session-pickup.md

@@ -0,0 +1,31 @@
+---
+id: session-pickup
+lanes: [local-fix, local-build]
+---
+You own this continuation. Resume at the confirmed cursor — never fabricate
+continuity.
+If the user says "new task", re-route — do not treat the message as the next step.
+Resume (a resumable record exists):
+1. Load the resumable record — goal, done-so-far, next step — via
+   `resumable-run.mjs read <projectRoot> <taskId>`; a `status: absent` or no
+   record means there is nothing to resume: re-route as the underlying task
+   type, do not resume.
+2. Verify the record against the actual worktree before trusting it — the
+   `stateVerify` receipt already flags divergent index/config fingerprints;
+   where it reports `fail` or the tree disagrees, the record is stale:
+   reconcile or report the divergence, never silently pick a side.
+3. Continue from the confirmed cursor — no re-done steps, no skipped ones.
+Suspend (interruption, deliberate pause, session end):
+4. Checkpoint progress — what is done, what is next, open questions.
+5. Persist the resumable record via `resumable-run.mjs suspend <projectRoot>
+   <taskId> --phase <phase> --next <action> --completed <a,b,...>` and
+   self-check sufficiency: a cold session could resume from the record alone.
+Machinery: `resumable-run.mjs read|suspend`; stage `off` writes nothing and the
+pickup record is advisory context. On Codex (no hook surface) run the same
+commands manually — enforcement stays advisory, never a live claim.
+Sub-playbooks: `worktree-cleanup` when the session tail is reclaiming the
+stale worktrees past sessions spawned — the gated sweep, not a resume.
+Reply: for resume — the cursor you verified and the evidence the worktree agrees;
+for suspend — the record written and the sufficiency check.
+Ask the human only for: irreversible writes, a genuine preference call no experiment
+settles, or a real dead end. Everything else: do it, report it.