@ngockhoale/ukit 3.3.2 → 3.4.0

package/template_user/playbooks/shipping.md

@@ -0,0 +1,53 @@
+---
+id: shipping
+lanes: [review-release]
+---
+You own the landing of a stack of ready changes — the work after `babysit`
+leaves each PR merge-ready. You verify each unit on its own evidence, confirm
+the stack is contiguous, land in order behind per-action authorization, and
+confirm the final head. Getting a unit to merge-ready is babysit's job; a unit
+still failing CI or sitting under open review threads belongs back there.
+If the user says "new task", re-route — do not treat the message as the next step.
+1. Confirm this is shipping territory: every unit in the stack is open and
+   merge-ready (the upstream PR-create and babysit steps, RCC-01 classes 3–5,
+   are done) and you can reach CI/review state plus git history. A single
+   unverified change still in development, or a repo where you lack land
+   permission, is a when-not — say so and stop. If `gh` is missing or
+   unauthenticated, report the CLI failure verbatim — never fabricate check,
+   review, or head state.
+2. Verify each unit independently (RCC-01 class 4): `gh pr checks`, `gh pr
+   view`, and 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-unit verification
+   receipt: commands run, output, result. Independent means a green unit does
+   not vouch for its neighbor.
+3. Confirm stack contiguity: each unit's base is the previous unit's head —
+   order them by `gh pr view --json baseRefName,headRefName` and `git`
+   branch inspection. A gap or a unit that fails verification breaks the
+   chain: skip it if the remainder still lands on its own base, otherwise
+   stop the stack there — you never land unverified or non-contiguous work,
+   and the skipped unit is named in the report.
+4. Land in order — each 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 stack"
+   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.
+5. Confirm the final head: `git log`/`git rev-parse` the default branch and
+   check every intended unit is in; attach the receipts and the head
+   confirmation as evidence. If authorization is missing, a unit fails, or
+   contiguity breaks mid-stack, report BLOCKED at that step naming the
+   boundary or the failed unit — never soft-fail around it and never land
+   the remainder silently.
+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 ordered unit list, each per-unit verification receipt, the land
+authorizations asked and granted, the final-head confirmation, and the
+terminal state — stack landed, or BLOCKED with the named cause.
+Ask the human at every irreversible write — per-action, even mid-stack — and
+for a genuine preference call no experiment settles or a real dead end.
+Everything else: do it, report it.

package/template_user/playbooks/skill-evaluation.md

@@ -0,0 +1,48 @@
+---
+id: skill-evaluation
+lanes: [local-build, review-release]
+---
+You own the skill — whether authoring it or measuring whether it helped. Two
+halves, one finish: a validated, discoverable skill, or a scored verdict backed
+by recorded fixtures and arms.
+If the user says "new task", re-route — do not treat the message as the next step.
+Authoring ("make this a skill"):
+1. Shape the skill file — `.claude/skills/<name>/SKILL.md` with `name:` +
+   `description:` frontmatter that states *when* to load it. UKit's own skill
+   standard applies, not a foreign file format copied blindly.
+2. Scaffold its audit — `yarn skill:audit init <name>` creates
+   `docs/skill-audits/<name>/` with the pressure-scenario, rationalization-table,
+   and trigger-accuracy templates.
+3. Pressure-test the discipline — write one pressure scenario; RED: run it
+   without the skill, record the verbatim rationalization; GREEN: re-run with
+   the skill loaded and expect compliance; REFACTOR: a new rationalization gets
+   an explicit counter in the table, never a soft exception. Record each phase
+   via `yarn skill:audit record <name>`; `yarn skill:audit status <name>` is
+   clean only when open rationalizations = 0.
+4. Prove discoverability — run the trigger-accuracy check: prompts that should
+   load the skill do, prompts that should not do not, judged on the frontmatter
+   `description` alone. Fix the description until both hold.
+Measurement ("did this change help"):
+5. Name the fixture set — a stable fixture file or list of prompts (fixture
+   IDs), the same set for both arms, decided before scoring.
+6. Split the arms — control = the baseline (`baselineRef`), changed = the new
+   skill/playbook/prompt/route. The arm assignment is recorded before any
+   scoring happens.
+7. Score the comparison — judge each fixture per arm blinded to which arm
+   produced it; deltas across quality, rework, latency, calls.
+8. Record the verdict — `emitExperimentScorecard` with `net-gain`, `neutral`,
+   or `negative`, carrying fixture IDs + per-arm scores + the arm assignment.
+   A bare vibe verdict with no scored comparison does not finish —
+   `emitExperimentScorecard` enforces the verdict enum and fixture/id shape;
+   an unscored claim fails the recorded-evidence bar. Promotion = `net-gain`
+   plus maintainer review; `neutral|negative` stays disabled.
+Machinery: `yarn skill:audit init|status|record` (scaffolds + records only —
+the model run is the pressure check itself); `src/core/experiments/
+deliberation.js` `emitExperimentScorecard` for the verdict contract.
+Reply: authoring — the skill path, audit status (entries, open
+rationalizations), trigger-accuracy result; measurement — fixture IDs, per-arm
+scores, arm assignment, verdict + promotion eligibility verbatim.
+Ask the human only for: shipping a skill that failed its audit, promoting an
+experiment (net-gain goes to maintainer review, never auto-promote), a genuine
+preference call no fixture settles, or a real dead end. Everything else: do it,
+report it.

package/template_user/playbooks/small-feature.md

@@ -0,0 +1,20 @@
+---
+id: small-feature
+lanes: [local-fix, local-build]
+---
+You own this slice. Make it appear and work on the real surface — a created file
+nothing reaches is not done.
+If the user says "new task", re-route — do not treat the message as the next step.
+1. Infer scope and the done predicate from the request plus repo conventions —
+   routine choices (file name, style, component split, state pattern) are yours;
+   ask only when the choices diverge into materially different product behavior.
+2. Build the smallest usable slice — everything needed for the behavior to appear
+   and work. No spec phase, no architect lane on this path.
+3. Wire it into the usage flow — the unwired component is the most likely cheat;
+   an import plus a callsite is the minimum proof of wiring.
+4. Verify on the real surface: UI = run it and observe render/interaction;
+   function = concrete input→output cases. Build-pass proves nothing.
+5. Record the assumptions you made — one line each.
+Reply: what was added, where it is wired, and the surface evidence it works.
+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/verification-map.json

@@ -0,0 +1,153 @@
+{
+  "version": 1,
+  "playbooks": {
+    "small-feature": {
+      "launch": "\"create X doing Y\" single-surface",
+      "doctor": "repo conventions identified; harness exists?",
+      "drive": "implement + wire + render/run",
+      "expected": "slice works on real surface",
+      "evidence": ["render-observation or IO-case receipt"],
+      "cleanup": "remove throwaway scaffolds"
+    },
+    "feature-implementation": {
+      "launch": "\"implement X\" w/ contract",
+      "doctor": "done predicate stated; analog found",
+      "drive": "predicate → smallest change → verify → widen once",
+      "expected": "predicate holds on real artifact",
+      "evidence": ["predicate evidence + impact-sweep output"],
+      "cleanup": "none"
+    },
+    "bug-fix": {
+      "launch": "\"fix X\" reproducible",
+      "doctor": "repro command/surface reachable",
+      "drive": "repro → hypothesis bisect → minimal fix → re-verify",
+      "expected": "original repro passes same-surface",
+      "evidence": ["repro-before + repro-after verbatim, root cause named"],
+      "cleanup": "rejected-hypothesis notes kept"
+    },
+    "investigation": {
+      "launch": "\"how/why X\"",
+      "doctor": "read-only confirmed",
+      "drive": "frame → gather → classify → answer",
+      "expected": "cited answer or falsified assumption",
+      "evidence": ["path:symbol/command-output anchors"],
+      "cleanup": "git status clean check"
+    },
+    "refactor": {
+      "launch": "\"restructure X\" behavior-preserved",
+      "doctor": "pin exists or characterization tests writable",
+      "drive": "pin → stepwise change → re-pin → migrate callers",
+      "expected": "pin green before+after; zero legacy callers",
+      "evidence": ["pin receipts + caller sweep"],
+      "cleanup": "old surface deleted"
+    },
+    "performance": {
+      "launch": "\"X is slow\" + symptom",
+      "doctor": "harness identified; baseline measurable",
+      "drive": "baseline → trace → improve → re-measure",
+      "expected": "measured delta ≥ stated margin",
+      "evidence": ["before/after numbers + commands"],
+      "cleanup": "harness left runnable"
+    },
+    "runtime-forensics": {
+      "launch": "live symptom / dropped artifact",
+      "doctor": "instrumentation tools present (sample, node --inspect, profilers)",
+      "drive": "attach/observe → capture → isolate → name mechanism",
+      "expected": "anomaly explained by captured evidence",
+      "evidence": ["heap/CPU/handle captures + derived readings"],
+      "cleanup": "captures stored under artifacts; processes released"
+    },
+    "architecture-decision": {
+      "launch": "\"A or B\" fork",
+      "doctor": "alternatives enumerable",
+      "drive": "gather constraints → compare → record",
+      "expected": "decision recorded w/ falsifiable rationale",
+      "evidence": ["decision record + alternatives"],
+      "cleanup": "none"
+    },
+    "prototype": {
+      "launch": "\"spike Y\"",
+      "doctor": "decision-to-settle stated",
+      "drive": "cheapest artifact → measure → verdict",
+      "expected": "fork settled; artifact dispositioned",
+      "evidence": ["experiment output + verdict + disposable/promoted flag"],
+      "cleanup": "throwaway flagged or removed"
+    },
+    "migration": {
+      "launch": "\"move to new schema/API\"",
+      "doctor": "target shape defined; rollback path exists",
+      "drive": "pin → migrate → verify on target → rollback demo",
+      "expected": "target verified + rollback demonstrated",
+      "evidence": ["migration verify + rollback receipts"],
+      "cleanup": "legacy path scheduled for removal"
+    },
+    "verification": {
+      "launch": "\"verify/check X\"",
+      "doctor": "the named check is runnable",
+      "drive": "run check → record verdict",
+      "expected": "verdict recorded (pass/fail/inconclusive)",
+      "evidence": ["check output verbatim"],
+      "cleanup": "none"
+    },
+    "skill-evaluation": {
+      "launch": "\"skill X\" / \"did change help\"",
+      "doctor": "fixture set named",
+      "drive": "author→validate→ship OR arms→score→verdict",
+      "expected": "skill discoverable OR scored comparison recorded",
+      "evidence": ["audit output / fixture IDs + scores"],
+      "cleanup": "fixtures versioned"
+    },
+    "session-pickup": {
+      "launch": "resume signal",
+      "doctor": "resumable record exists",
+      "drive": "load → reconstruct → verify vs worktree → continue",
+      "expected": "resumed at correct cursor, no re-done steps",
+      "evidence": ["state-verify receipt"],
+      "cleanup": "stale records pruned"
+    },
+    "autonomous-run": {
+      "launch": "bounded long goal",
+      "doctor": "finish condition fixable",
+      "drive": "loop: work → verify → re-check finish",
+      "expected": "finish verified or escape hatch + named blocker",
+      "evidence": ["progress ledger + final verification"],
+      "cleanup": "resumable record closed"
+    },
+    "release": {
+      "launch": "\"bump/ship/publish\"",
+      "doctor": "on UKit repo; scripts exist (verify-release.mjs)",
+      "drive": "version → test:release-core → push+tag → gh release → npm dry-run → publish → parity probes",
+      "expected": "3 version probes equal",
+      "evidence": ["probe outputs (npm view / gh release list / git tag)"],
+      "cleanup": "if parity fails: report \"not shipped\" (owner §4)"
+    }
+  },
+  "artifactClasses": {
+    "ui": {
+      "name": "UI surface verification",
+      "check": "render the changed surface or drive it through the project's UI harness (package.json script `test:ui`) and record the receipt",
+      "harness": { "packageScript": "test:ui" },
+      "fallback": "receipt class `render-observation` — attest the observed render/interaction via UKIT_EVIDENCE (class=render-observation;surface=<how observed>)",
+      "evidenceRequired": ["render-observation|io-case"]
+    },
+    "cli": {
+      "name": "CLI/IO surface verification",
+      "check": "run the CLI entry or its IO harness (package.json script `test:cli`) and record the receipt",
+      "harness": { "packageScript": "test:cli" },
+      "fallback": "receipt class `io-case` — attest one input/output case via UKIT_EVIDENCE (class=io-case;surface=<command>)",
+      "evidenceRequired": ["io-case"]
+    },
+    "docs": {
+      "name": "Docs/prose verification",
+      "check": "skim the rendered prose for link/format integrity; no test run required",
+      "fallback": "receipt class `doc-render` — optional; attest a docs render check via UKIT_EVIDENCE when available",
+      "evidenceRequired": []
+    },
+    "config": {
+      "name": "Config/settings verification",
+      "check": "load or lint the changed config once (project's own loader/lint command) and record the receipt",
+      "fallback": "receipt class `config-load` — attest a config load/lint observation via UKIT_EVIDENCE when no script exists",
+      "evidenceRequired": []
+    }
+  }
+}

package/template_user/playbooks/verification.md

@@ -0,0 +1,22 @@
+---
+id: verification
+lanes: [review-release, local-fix]
+---
+You own this check. Run the named check and record its verdict — a failed check is
+a finding to report, not a task to fix.
+If the user says "new task", re-route — do not treat the message as the next step.
+1. Name the check and its verdict predicate — the command, surface, or
+   observation that produces pass/fail.
+2. Run it and capture the output verbatim. If this engine cannot produce that
+   evidence class, fall back to the closest runnable check and mark the limit
+   `unverified` — never fabricate a pass.
+3. Visual channel (skippable — only when parity against a reference is the ask):
+   capture reference → render → vision-compare → iterate until equivalence or
+   named divergence; prefer DOM/snapshot assertions when they suffice — vision
+   passes are the expensive channel.
+4. Record the verdict: pass, fail, or inconclusive with what is missing. A fail
+   hands off to the owning group (bug-fix, performance) as a new routed task.
+Reply: the check run, the verbatim output or comparison captures, and the recorded
+verdict.
+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/worktree-cleanup.md

@@ -0,0 +1,37 @@
+---
+id: worktree-cleanup
+lanes: [local-fix, local-build]
+---
+You own this workspace-hygiene pass. Reclaim stale/merged worktrees — every
+removal sits behind a per-entry safety check, never a blanket sweep. If the
+user says "new task", re-route — do not treat the message as the next step.
+1. Confirm this is cleanup territory: accumulated `.worktrees/*` entries (or
+   linked worktrees anywhere) left by completed or abandoned runs. A repo
+   with no extra worktrees is already clean — report that and stop.
+2. Enumerate candidates and classify them. Run
+   `node .claude/ukit/index/worktree-sweep.mjs` (dry-run is the default — it
+   reads `git worktree list --porcelain`, classifies each entry
+   merged/stale/active, and prints the classification table with a per-entry
+   verdict). It removes nothing.
+3. Read the verdicts. Each non-main worktree is `safe` or a named skip —
+   `skip-dirty` (uncommitted work), `skip-locked` (git lock, deliberate),
+   `skip-active` (a resumable-run record or a `docs/AI_HANDOFF/RUN.md` cursor
+   whose phase is not `done`/`blocked`), `skip-detached-head`. The gate is
+   per entry: no uncommitted work AND no active run.
+4. Apply — removal is a destructive operation: a worktree's checkout is
+   deleted, so `Ask the human` before running `--apply`, even when every
+   candidate reads `safe`. With authorization, run
+   `node .claude/ukit/index/worktree-sweep.mjs --apply`; it runs
+   `git worktree remove` only on `safe` entries and prints each removal's
+   gate verdict. Skipped entries are named in the report and left untouched.
+5. Report and finish: all stale/merged worktrees reclaimed, nothing active or
+   dirty touched. Nothing safe to remove, or everything skipped, is a report
+   — print the verdicts, never exit silently.
+Machinery: `worktree-sweep.mjs` over `git` porcelain — full on Claude Code
+and omp via Bash; on Codex run the same commands manually — enforcement stays
+advisory/instruction-mediated, never a live gate claim.
+Reply: the classification list with every per-entry verdict, what was removed
+(and under which authorization), and what was skipped.
+Ask the human only for: irreversible writes (every `--apply` removal), a
+genuine preference call no experiment settles, or a real dead end. Everything
+else: do it, report it.