@brainervirus/workit-codex 4.0.0 → 5.0.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "workit",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "Adaptive engineering workflow rails for Codex",
   "author": {
     "name": "BrainerVirus"

package/README.md

@@ -3,7 +3,7 @@
 [![CI](https://github.com/BrainerVirus/workit/actions/workflows/ci.yml/badge.svg)](https://github.com/BrainerVirus/workit/actions/workflows/ci.yml)
 [![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](../../LICENSE)
 
-Workit plugin for Codex CLI and desktop — native manifest, documented hooks, the shared MCP transport, and sixteen method skills. Reads run over MCP; mutations run CLI-driven, because caller-unattested MCP cannot attest effects.
+Workit plugin for Codex CLI and desktop — native manifest, documented hooks, the shared MCP transport, and eleven method skills. Reads run over MCP; mutations run CLI-driven, because caller-unattested MCP cannot attest effects.
 
 ## Requirements
 
@@ -26,4 +26,4 @@ node_modules/.bin/workit <family> <action> --json --confirm   # mutations (CLI-d
 workit writer acquire --actor <session-id>                    # bind a writer to this session explicitly
 ```
 
-The hook honors exactly the bound session and nothing else. Arbitrary-question receipts and attested writer delegation are unavailable on this host by design. See `skills/` for the sixteen `workit-*` method skills.
+The hook honors exactly the bound session and nothing else. Arbitrary-question receipts and attested writer delegation are unavailable on this host by design. The package ships the eleven `workit-*` method skills in `skills/`, generated at build time from `packages/workit-core/skills`.

package/dist/launch-mcp.js

@@ -21341,13 +21341,13 @@ function evaluateClosure(requestedOutcome, view) {
 
 // packages/workit-core/src/core/methods.ts
 var METHODS = {
-  "workit-challenge": { dimensions: ["challenge", "decisions"] },
-  "workit-behavioral-tdd": { dimensions: ["testing"], ruleIds: ["mechanical-existing-checks"] },
+  "workit-shape": { dimensions: ["challenge", "decisions", "artifacts", "continuity"] },
+  "workit-bdd": { dimensions: ["testing"] },
   "workit-review": { dimensions: ["review"], ruleIds: ["fresh-context-review", "self-review"] },
-  "workit-plan": { dimensions: ["artifacts", "continuity"] },
-  "workit-implement": { dimensions: ["delegation"] },
+  "workit-implement": { ruleIds: ["mechanical-existing-checks"] },
+  "workit-fanout": { dimensions: ["delegation"] },
   "workit-debug": {},
-  "workit-handoff": {},
+  "workit-continue": {},
   "workit-deslop": { ruleIds: ["pre-pr-cleanup"] }
 };
 var methodMatches = (definition, requirement) => definition.dimensions?.includes(requirement.dimension) === true || definition.ruleIds?.includes(requirement.ruleId) === true;
@@ -27985,6 +27985,7 @@ var signals = new Map;
 var cache = new Map;
 // packages/workit-core/src/hooks/handle.ts
 var offered = new Set;
+var CLAUDE_JUDGES = new Set(["workit:verifier", "workit:reviewer"]);
 // packages/workit-core/src/hooks/hosts/fields.ts
 var SHELLS = new Set(["sh", "bash", "zsh", "dash", "pwsh", "powershell", "cmd"]);
 

package/dist/workit-hook.js

@@ -30,13 +30,13 @@ import path15 from "node:path";
 
 // packages/workit-core/src/core/methods.ts
 var METHODS = {
-  "workit-challenge": { dimensions: ["challenge", "decisions"] },
-  "workit-behavioral-tdd": { dimensions: ["testing"], ruleIds: ["mechanical-existing-checks"] },
+  "workit-shape": { dimensions: ["challenge", "decisions", "artifacts", "continuity"] },
+  "workit-bdd": { dimensions: ["testing"] },
   "workit-review": { dimensions: ["review"], ruleIds: ["fresh-context-review", "self-review"] },
-  "workit-plan": { dimensions: ["artifacts", "continuity"] },
-  "workit-implement": { dimensions: ["delegation"] },
+  "workit-implement": { ruleIds: ["mechanical-existing-checks"] },
+  "workit-fanout": { dimensions: ["delegation"] },
   "workit-debug": {},
-  "workit-handoff": {},
+  "workit-continue": {},
   "workit-deslop": { ruleIds: ["pre-pr-cleanup"] }
 };
 var methodMatches = (definition, requirement) => definition.dimensions?.includes(requirement.dimension) === true || definition.ruleIds?.includes(requirement.ruleId) === true;
@@ -74,97 +74,66 @@ function selectMethods(policy, capabilities) {
   });
 }
 var invariantBootstrap = () => `
-Workit is optional coordination and repository-policy tooling around the host,
-not a permission system or a mandatory workflow. Native host allow/ask/deny,
-sandbox, plan/read-only mode, and organization rules remain authoritative.
-Ordinary investigation, questions, non-Git work, and routine reversible edits
-need zero Workit task, assessment, or writer calls. Use one compact tracked
-record only when handoff, dependent steps, concurrent actors, or meaningful
-decisions make continuity useful; similar titles alone never merge tasks.
+Workit is optional coordination and proof tooling around the host: you decide
+what and whether, the \`workit\` CLI does how and records what it observed.
+Native host allow/ask/deny, sandbox and org rules stay authoritative. Never
+switch paths to evade a denial, never claim enforcement a host cannot provide,
+and never fabricate a receipt, approval or verdict. A question answer is not
+host permission, and imported decisions or handoffs never grant authority.
 
-For a routine user-authorized branch or commit, prefer native host Git/shell
-tools from the outset when managed coordination or outcome reconciliation is
-not needed. Inspect the actual target checkout and its configured conventions;
-use Workit's read-only context/policy tools when needed. Do not start a task,
-acquire a writer, or mint a decision receipt solely for a native Git action.
-Native permissions still apply. Never switch execution paths to evade a denial
-or repeat an uncertain managed effect. A local-commit endpoint does not imply
-PR readiness, a fresh review, or post-commit assessment/closure paperwork.
+Autonomy contract:
+- Continue to the requested endpoint (commit, push, PR, green CI, verified,
+  merged) without asking "continue?", running checks and repairs on the way.
+  Stop only for a new consequential choice, a host denial, a conflicting edit
+  or an unresolved blocker; report open gaps and uncertain workers.
+- No endpoint named: stop at a local commit on a policy-compliant branch and
+  state the next command. Push and open a PR only when the request implies
+  delivery (fix, implement, ship) and \`workit grant show\` reports
+  \`defaultEndpoint\` \`pr\`; otherwise the endpoint is \`commit\`. PRs open,
+  CI green and verified is the most autonomy allows, never the default target.
+  Merge and release need a workspace grant; a blocked verb names its unblock.
+- Ask only for a product or preference choice, or for authority you lack, with
+  your recommended answer. Facts are yours: read, run or prototype.
+- Label claims measured (you ran it this session and saw the result),
+  inferred, or guess. Prose is a note: only a configured check the CLI ran
+  (\`workit check <name>\`) satisfies a gate; an ad-hoc
+  \`workit check -- <cmd>\` never does.
+- Author is not verifier: never record a passing verdict on work your session
+  wrote. The lead starts each verifier with its own session
+  (\`WORKIT_SESSION_ID=<lead>-v<n>\`; Claude Code subagents get one from the
+  hook), and the verifier records \`workit ledger verdict\`.
+- A local-commit endpoint does not imply PR readiness, and a local commit alone
+  is not evidence of a requested remote push. Before reporting delivery,
+  reconcile every requested item and observe it (\`workit verify-delivery\`).
 
-For tracked work, inspect its current state and use the shared operations for
-task, policy, evidence, finding, decision, worker, writer, and state changes.
-Each branch has one implicit task: an operation without taskId applies to it,
-and the first recording (a note, check, finding or evidence) creates it, so you
-never manage task ids. Start a record only for an explicit tracked objective;
-assess or reassess only
-when policy selection or changed evidence/constraints requires it. Omitted
-expectedRevision and expectedWorkspaceRevision use current values; explicit
-values are still concurrency-checked, so never copy revisions between calls.
-A busy result means another live Workit call holds the checkout lock: retry the
-same call; it is not a recovery condition. A lock left by a dead process is
-reclaimed on the next write, and \`workit doctor --fix-lock\` clears it on demand.
-An omitted revision absorbs a concurrent write: Workit re-reads, re-checks
-policy, and reapplies the call, returning busy under persistent contention. A
-revision_conflict means a revision you passed is stale: re-read the record
-before deciding whether to retry.
-A solo edit does not need writer acquisition; use it when concurrent checkout
-writers need coordination. Record only observed facts and checks. Close-time
-testing and verification gates accept only a configured check the CLI ran:
-\`workit check <name>\` (\`npx -y @brainervirus/workit-cli check <name>\` when
-\`workit\` is not on PATH); a recorded check result is a note and an ad-hoc
-\`workit check -- <cmd>\` never satisfies a gate. Evidence can become stale when its bound candidate or tree changes; reconcile findings against the
-current candidate before recording completion.
+CLI first: if a step has one right answer, use the \`workit\` verb instead of
+hand-running git, gh or glab: check, git, pr, ci, stack, verify-delivery,
+ledger, handoff, test-audit (\`workit help <verb>\`; without \`workit\` on
+PATH, \`npx -y @brainervirus/workit-cli\`). \`busy\` is retryable
+(\`workit doctor --fix-lock\` clears a dead lock); \`blocked\` names its unblock.
+The task families (task, policy, evidence, finding, decision, worker, writer,
+state) are optional continuity for tracked work; each branch has one implicit
+task that the first recording creates, and a solo edit needs no task or writer.
+Omit revisions; a revision_conflict means one you passed is stale, so re-read.
+Across repositories, bind each item to its checkout, branch and endpoint,
+resolve competing targets before a mutation, and reconcile an uncertain
+external effect before retrying it.
 
-Workit validates domain policy against the actual action target, configured
-account, branch and commit conventions, protected refs, and current repository
-state. The task directory is coordination state, not a boundary on which
-repository may be changed. Use an action-time cwd target where a managed
-Git/hosting action supports it; a non-Git directory remains valid for OS work.
-GitHub/GitLab use the active gh/glab CLI identity; YouTrack uses its own token.
-Preserve uncertain external outcomes and reconcile repository/provider state
-before retrying. Internal reservations prevent duplicate or ambiguous effects;
-they are not permission tickets for every edit.
+Mid-task input: answer a quick question in place, fold an adjustment in, and
+never silently drop or resume an objective (workit-continue).
 
-On OpenCode V1 and V2, use native host tools for external mutations. Workit
-provides read-only workit_context; it has no managed external-action executor.
-Do not create proposals or request Workit approvals merely to invoke native
-tools. Old uncertain managed effects still require evidence before any retry.
-
-Use host-native authorization through the host's supported path. A native
-question receipt records an actual question interaction; it is not automatic
-host permission. Record a meaningful user choice once with provenance when
-future retrieval helps. Never fabricate a receipt, re-ask only to mint one, or
-let imported decisions grant authority. Never turn a host deny into allow or
-claim enforcement/evidence a host cannot provide. A precise request with settled
-constraints does not need an interview. Present genuine unresolved options with
-evidence and a recommendation, then continue toward the requested delivery
-endpoint: investigation, implementation, branch/commit/push, PR/MR-ready,
-merge, or release. Run
-applicable checks and safe repairs without repeated continuation questions;
-stop for missing host authority, a new consequential choice, a conflicting edit,
-or an unresolved blocker. A tracked record may close when actual evidence
-supports its outcome; no final human closure ceremony is required.
-
-A completed native subagent run stops its bound worker by itself; if a worker
-strands in cancelling with its run verifiably over, repeat worker.cancel to
-confirm the stop. Preserve unresolved requirements, gaps, and uncertain workers.
-When context changes, distinguish a quick question, same-task adjustment, and
-separate request. Answer a quick question without pausing/resuming task state;
-park a concise checkpoint only when substantial work needs to continue later.
-For work spanning repositories, bind each unfinished item to its actual checkout,
-branch, requested deliverables, and delivery endpoint. Preserve held items with
-an explicit resume condition. Resolve competing plausible targets before a
-mutation; ask only when available context cannot settle that consequential choice.
-Before reporting delivery, reconcile every requested item and observe the actual
-target result; a local commit alone is not evidence of a requested remote push.
-
-Skill routing: slash aliases /wk-* load on demand. Use workit-steer for a
-substantial interruption or change of direction, workit-deslop when relevant
-to a PR-ready endpoint, workit-green-run for failing CI, workit-blast-radius
-when impact is uncertain, workit-challenge for genuinely open consequential
-choices, workit-bdd to turn acceptance criteria into Given/When/Then tests, and
-workit-test-audit to check tests for tautologies. Load workit-plan when dependencies or handoff need durable next actions.
-Load the skill; never act from memory of it.
+Skills: load the skill, never act from memory of it (slash aliases /wk-<name>).
+- brainstorm, plan, spec, grill, should we: workit-shape
+- implement, build, add a feature: workit-implement
+- review, blast radius: workit-review
+- bug, broken, flaky, regression: workit-debug
+- ship, babysit, CI, merge: workit-ship
+- resume, pick up, handoff, interruption: workit-continue
+- BDD, TDD, acceptance criteria, Given/When/Then: workit-bdd
+- test audit, tautology, weak tests: workit-test-audit
+- deslop, slop, dead code: workit-deslop
+- fan out, parallelize, parallel agents, swarm: workit-fanout
+- verify the app, smoke test, prove it works: workit-verify-app
 `.trim();
 
 // packages/workit-core/src/core/task-contract.ts
@@ -17115,7 +17084,16 @@ var usable2 = (value) => value === "native" || value === "partial";
 var NONE2 = { kind: "none" };
 var offered = new Set;
 var CLAUDE_WORKTREE_IMPLEMENTER = "workit:implementer";
-var subagentStartText = (host, descriptor, event) => host === "claude_code" && event.agentType === CLAUDE_WORKTREE_IMPLEMENTER ? `Workit observed ${descriptor.label} subagent ${event.agentId} (${event.agentType}) working in its own git worktree: it may edit and commit there, within its brief's scope. Before the first commit, switch to a policy-compliant branch (\`git switch -c <type>/<slug>\`, e.g. feature/<slug>); branch policy hooks still deny protected or non-compliant branches. Never push, open a PR, or merge unless the brief asks for it.` : `Workit observed ${descriptor.label} subagent ${event.agentId} (${event.agentType}) as read-only/agent-guided; writer delegation is unavailable.`;
+var CLAUDE_JUDGES = new Set(["workit:verifier", "workit:reviewer"]);
+var subagentSession = (session, agentId) => [session, agentId].filter((part) => Boolean(part)).join(":").replace(/[^A-Za-z0-9_.:@/+-]/g, "-").slice(0, 128);
+var subagentStartText = (host, session, descriptor, event) => {
+  if (host === "claude_code" && event.agentType === CLAUDE_WORKTREE_IMPLEMENTER)
+    return `Workit observed ${descriptor.label} subagent ${event.agentId} (${event.agentType}) working in its own git worktree: it may edit and commit there, within its brief's scope. Before the first commit, switch to a policy-compliant branch with \`workit git branch <branch> --base <base>\` (e.g. feature/<slug>); branch policy hooks still deny protected or non-compliant branches. Never record a verdict on your own work. Never push, open a PR, or merge unless the brief asks for it.`;
+  const readOnly = `Workit observed ${descriptor.label} subagent ${event.agentId} (${event.agentType}) as read-only/agent-guided; writer delegation is unavailable.`;
+  if (host === "claude_code" && event.agentType && CLAUDE_JUDGES.has(event.agentType) && event.agentId)
+    return `${readOnly} Its own Workit session is ${subagentSession(session, event.agentId)}: record verdicts with \`workit ledger verdict <result> --session ${subagentSession(session, event.agentId)} ...\` so the ledger tells it apart from the author.`;
+  return readOnly;
+};
 function handleHook(input, deps) {
   const { descriptor } = deps;
   const event = input.event;
@@ -17141,7 +17119,10 @@ function handleHook(input, deps) {
     case "shell.pre":
       return usable2(descriptor.shellPolicy.deny) ? shellPolicy(input.cwd, event.command) : NONE2;
     case "subagent.start":
-      return { kind: "context", text: subagentStartText(input.host, descriptor, event) };
+      return {
+        kind: "context",
+        text: subagentStartText(input.host, input.session.id ?? null, descriptor, event)
+      };
     case "compact.pre":
       return {
         kind: "notice",
@@ -17695,7 +17676,7 @@ var codexAdapter = {
     };
   },
   render: render2,
-  addendum: (input) => `<workit-codex-mutations>Codex MCP is read-only: unattested callers cannot mutate. Run the workit CLI for task mutations: node_modules/.bin/workit <family> <action> --json --confirm${input.session.id ? `; bind the writer to this session with node_modules/.bin/workit writer acquire --task <id> --revision <rev> --actor ${input.session.id} --confirm` : ""}. Binding decisions and external actions need a human.</workit-codex-mutations>`
+  addendum: (input) => `<workit-codex-mutations>Codex MCP is read-only: unattested callers cannot mutate. Run workit verbs with the workit CLI on the shell (node_modules/.bin/workit, or npx -y @brainervirus/workit-cli): check, git branch|commit|push, pr, ci, stack, ledger, handoff; task-family mutations take --json --confirm${input.session.id ? `; bind the writer to this session with node_modules/.bin/workit writer acquire --task <id> --revision <rev> --actor ${input.session.id} --confirm` : ""}. A verifier or reviewer records workit ledger verdict under a session the lead assigns (WORKIT_SESSION_ID=<lead>-v<n>), never the author's. Merge and release need a workspace grant; a question answer is not host permission.</workit-codex-mutations>`
 };
 
 // packages/workit-core/src/hooks/hosts/cursor.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-codex",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "private": false,
   "description": "Workit Codex CLI/desktop plugin — shared MCP transport, hooks, and sixteen method skills",
   "keywords": [
@@ -38,8 +38,8 @@
     "build": "bun scripts/build.ts"
   },
   "dependencies": {
-    "@brainervirus/workit-core": "^4.0.0",
-    "@brainervirus/workit-mcp": "^4.0.0"
+    "@brainervirus/workit-core": "^5.0.0",
+    "@brainervirus/workit-mcp": "^5.0.0"
   },
   "engines": {
     "node": ">=24"

package/skills/workit-bdd/SKILL.md

@@ -1,41 +1,47 @@
 ---
 name: workit-bdd
-description: Use when turning a requirement, issue or acceptance criterion into tests, or when tests should read as behavior (Given/When/Then, BDD, scenarios, acceptance tests, test names and seams)
+description: Turn requirements into Given/When/Then scenarios, agree the test seam, and work test-first in vertical RED/GREEN slices. Use for BDD, TDD, acceptance criteria, scenarios, Given/When/Then, write a test first.
 ---
 
 # Behavior first: Given/When/Then
 
-Write each acceptance criterion as Given/When/Then before any code, then let
-it name the test and pick the seam. This skill shapes the scenarios; the
-RED/GREEN loop itself is workit-behavioral-tdd.
-
-## Method
-
-1. Write the scenarios. One behavior per scenario, in the user's or caller's
-   words: `Given <state>, When <action>, Then <observable result>`. Include the
-   unhappy paths a caller depends on (denied, empty, invalid, timeout).
-2. Agree the seams. Pick the highest stable interface the scenario can be
-   observed through: a CLI verb, a public function, an HTTP route. Ideally one
-   seam per feature. Write the seams down; do not test at an unagreed seam.
-3. Name the tests after the scenarios. The test name is the Given/When/Then
-   sentence; the body is arrange (Given), act (When), assert (Then). Expected
-   values come from the scenario (a literal from a worked example or the
-   spec), never from the code.
-4. Use Gherkin only where the repo already does (`.feature` files with
-   playwright-bdd, cucumber, jest-cucumber). Otherwise plain test names carry
-   the scenario; do not add a BDD framework.
-5. Build in vertical slices, one scenario at a time, with
-   workit-behavioral-tdd: run `workit check test` RED for the new scenario,
-   make the smallest change, run `workit check test` GREEN, then the next.
-6. Mock only at system boundaries: network, clock, randomness, other
-   processes, sometimes the filesystem. Never the unit or its internal
+1. **Write the scenarios.** One behavior each, in the caller's words:
+   `Given <state>, When <action>, Then <observable result>`. Include the
+   unhappy paths callers depend on (denied, empty, invalid, timeout).
+2. **Agree the seam.** The highest stable interface the scenario can be
+   observed through: a CLI verb, a public function, an HTTP route; ideally one
+   per feature. Do not test at a seam nobody agreed to.
+3. **Name tests after scenarios.** The name is the Given/When/Then sentence;
+   the body is arrange, act, assert. Expected values come from the scenario (a
+   literal from a worked example, the spec, an external contract), never from
+   the code under test.
+4. **Build in vertical slices.** Write one vertical RED slice that fails for
+   the missing behavior and run it through the CLI so the failure is observed:
+   `workit check test`. Make the smallest change, run the same check GREEN,
+   then take the next scenario. Any edit makes the observation stale; re-run
+   before you claim it. A recorded "tests pass" is a note, and an ad-hoc
+   `workit check -- <cmd>` never satisfies the gate: only the configured
+   `test` check does. No `test` detected? Create `workit.checks.json`, copying
+   in every check the repo already runs: once it exists it replaces the
+   detected defaults.
+5. **Mock only at system boundaries:** network, clock, randomness, other
+   processes, sometimes the filesystem. Never the unit or its own
    collaborators; use the real thing or an in-memory adapter behind a port.
+6. **Gherkin only where the repo already uses it** (`.feature` files with
+   playwright-bdd, cucumber, jest-cucumber). Otherwise test names carry it.
 
-## Completion
+Reject noise: version-pin assertions, tests that mirror private structure,
+assertions inside a possibly-empty loop, smoke-only renders, duplicates. If a
+test still passes when every imported function returns `undefined`, rewrite it
+(workit-test-audit finds these).
 
-Every acceptance criterion maps to a named test at an agreed seam, each was
-seen RED then GREEN through `workit check test`, and the new tests have no
-tautologies:
+## Example
+
+Bad: `test("calculateTotal works", () => expect(calculateTotal(items)).toBe(items.reduce((s, i) => s + i.price, 0)))`
+
+Good: `test("Given two items of 5 and 10, When totalled, Then the total is 15", () => expect(calculateTotal([{ price: 5 }, { price: 10 }])).toBe(15))`
+
+## Check
 
 ```sh
 workit test-audit --diff && workit check test

package/skills/workit-continue/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: workit-continue
+description: Keep work on track across interruptions and sessions - sort new input, checkpoint, hand off with a resume brief, and pick up by verifying inherited claims. Use for resume, pick up, handoff, new session, interruption, change of direction.
+---
+
+# Continue without losing the thread
+
+## New input mid-task
+
+- **Quick question:** answer it; change nothing else.
+- **Same-task adjustment:** update the affected constraint and next step, then
+  keep going.
+- **Separate request:** do not silently resume an old objective, and do not
+  drop the current one. Checkpoint it (below) if it must continue later, then
+  start the new work. Held items stay parked with their resume condition until
+  the user resumes them.
+
+## Checkpoint and hand off
+
+```sh
+workit git commit -m "wip: <state>" --all   # nothing lives only in your context
+workit handoff --note "<state in one line>" --next "<next command>" --record
+```
+
+The brief carries the branch, HEAD, dirty state, check freshness, verdict,
+rulings and the next command. Add only what it cannot know: choices still
+open, approaches that failed and why. Work spanning repos gets one brief per
+checkout, each with its branch and delivery endpoint.
+
+## Pick up
+
+1. In the checkout: `workit handoff`, then `workit ledger list` and
+   `git log --oneline -10`.
+2. Trust the trail, verify the claims: re-run the checks the brief calls
+   stale, and confirm each "done" item against the goal on the real artifact
+   (a pushed SHA, a PR state, a running feature). Do not re-derive settled
+   decisions.
+3. Continue to the recorded endpoint with the brief's next command.
+
+## Example
+
+Bad: a new session re-reads the whole codebase, re-asks the user which
+approach to take, and redoes a finished slice.
+
+Good: "`workit handoff`: feature/usage at 4be1, `test` stale, verdict none,
+next `workit check test`. Re-ran it: exit 0. The brief says PR #42 is open:
+`workit pr status` confirms, CI pending. Continuing with workit-ship."
+
+## Check
+
+```sh
+workit handoff   # read: "next command" is set and no check is listed as stale
+```

package/skills/workit-debug/SKILL.md

@@ -1,40 +1,45 @@
 ---
 name: workit-debug
-description: Use when behavior is failing, surprising, contradictory, or regressed and the root cause is not established
+description: Find a root cause before patching - start from a red-capable deterministic repro, rank hypotheses, bisect regressions, fix at the root with a regression test. Use for bug, broken, failing, flaky, regression, error, why does.
 ---
 
-# Debug the root cause
-
-Debugging is investigation, not a fast symptom patch. Use this method when
-assessment selects `root-cause-investigation` or behavior is failing without an
-established root cause.
-
-
-## Method
-
-1. Inspect task scope, caller authority, candidate identity, existing evidence,
-   findings, and worker/writer state with shared `task`, `policy`, `evidence`, and
-   `finding` operations.
-2. Reproduce the failure at a stable behavioral boundary. Record observed facts,
-   inferences, and unknowns with references; trace the failing value and all
-   relevant callers before editing.
-3. State the root-cause hypothesis and the smallest in-scope fix. Write a focused
-   regression at the boundary when practical, then run RED and GREEN through
-   `workit check <name>` so the results are observed, not reported.
-4. Acquire writer authority through `writer` before mutation. Reconcile the
-   candidate, evidence, and findings after the change; investigate sibling paths
-   and stale conclusions rather than assuming the first patch worked.
-
-Respect the user's scope and native authority. For a deterministic failure, make
-one focused reproduction that exercises the affected boundary and add a
-regression check when practical. If no direct reproduction exists, gather the
-available evidence and state what remains uncertain instead of inventing a red
-loop or blocking unrelated work.
-
-## Common mistakes
-
-| Mistake                               | Correction                                             |
-| ------------------------------------- | ------------------------------------------------------ |
-| Patching the nearest stack frame      | Trace the input, callers, and shared cause.            |
-| Reproducing only after editing        | Capture the failure before mutation.                   |
-| Treating one passing command as proof | Verify the affected behavior and record real evidence. |
+# Debug from a red loop
+
+## Steps
+
+1. **Build the loop before any hypothesis.** One command that is red for the
+   user's exact symptom, deterministic, fast and runnable by you:
+   `workit check -- <repro>`. Shrink it until it fails in seconds. If the
+   symptom only shows on the running app, drive it with the project's
+   verify-<app> skill. No loop yet? Building it is the task; do not guess-patch.
+2. **Read the failure, not the summary:** the full error, the failing value,
+   and every caller on its path.
+3. **Rank three to five falsifiable hypotheses**, likeliest first. Test one at
+   a time with the loop or a tagged log line (`[DEBUG-<id>]`, removed at the
+   end with one grep). Keep a short hypothesis log so a dead idea stays dead.
+4. **Regression? Bisect it:** `git bisect start <bad> <good>` then
+   `git bisect run <repro>`. The first bad commit names the cause.
+5. **Fix at the root**, the one place every failing caller passes through.
+   Add a regression test at a seam that exercises the real bug pattern; if no
+   such seam exists, report that as a finding.
+6. **Stop rule:** after three dead hypotheses, write down what is measured and
+   what is inferred, widen the loop, or ask for the one fact only the user has.
+
+Every shipped line traces to evidence from the loop. A "might help" retry or
+guard is a hypothesis, not a fix.
+
+## Example
+
+Bad: "Probably a race; added a retry." (no repro, nothing measured)
+
+Good: "Repro: `workit check -- bun test lock.test.ts -t stale` red 10/10.
+H1 dead pid not reclaimed - confirmed: `kill(pid, 0)` throws EPERM for another
+user's pid and we treated it as dead. Fix: EPERM means alive. Loop green 10/10;
+regression test pins the EPERM case."
+
+## Check
+
+```sh
+workit check -- <repro>   # red before the fix, green after
+workit check test
+```

package/skills/workit-deslop/SKILL.md

@@ -1,31 +1,41 @@
 ---
 name: workit-deslop
-description: Use before opening a PR or after implementation to remove AI slop from code and prose
+description: Remove AI slop before a PR - dead code, comments that restate the code, filler prose - with a minimal diff and identical behavior. Use for deslop, clean up, slop, tidy before PR, remove dead code, trim the PR body.
 ---
 
 # Deslop code and prose
 
-Throughput without quality is slop. Clean it with a minimal diff — deslop
-never refactors behavior.
-
-
-## Method
-
-1. Code: delete dead helpers, redundant validators, stub references, and
-   comments that restate the code. Comments die by default; keep one only
-   with proof of an unchangeable constraint, encoded structurally if cheap.
-2. Prose (PR body, spec, docs): cut filler, keep real symbol names and
-   before→after numbers. One doc, one purpose.
-3. Keep the diff minimal: deslop removes lines, never moves logic. If a
-   cleanup wants behavior change, it becomes its own tasked change.
-
-## Completion
-
-A smaller diff with identical behavior and green checks. Report lines
-removed, not lines written.
-
-Record passing check evidence linked to the `pre-pr-cleanup` requirement id
-from the current policy (`kind: check`, `result: passed`, summary naming what
-was removed). That requirement gates `hosting.pull_request` and close. If the
-change genuinely has nothing to clean, ask for an approved limitation
-decision instead of recording evidence that did not happen.
+Throughput without quality is slop. Deslop only removes; it never changes
+behavior. A change that wants new behavior is its own change.
+
+1. **Find it with tools first.** The repo's dead-code and lint tools on the
+   branch diff (for example `knip`, `ts-prune`, `vulture`, `cargo udeps`, or
+   the linter's unused rules), then read the diff:
+   `git diff <base>...HEAD`.
+2. **Code.** Delete unused helpers and exports, stub references, debug
+   leftovers (`[DEBUG-` tags, stray logs), and comments that restate the next
+   line. Keep comments that say *why* (a constraint, a workaround with its
+   link), license headers and tool directives.
+3. **Prose** (PR body, spec, docs): cut filler and hedging, keep real symbol
+   names and before-to-after numbers. One doc, one purpose.
+4. **Minimal diff.** Deslop removes lines; it never moves logic. A removed
+   validator that changes behavior is not deslop.
+5. **Re-run the checks** and report lines removed, not lines written. Nothing
+   to clean is a valid result: say what you checked ("0 removals; ran knip and
+   read the diff"). When a tracked task lists a `pre-pr-cleanup` requirement,
+   record this result as its evidence.
+
+## Example
+
+Bad: deleting `// retry: the gateway drops the first request after idle (#412)`
+because "comments die".
+
+Good: deleting `// increment the counter` above `count += 1`, an unused
+`formatLegacyDate` export reported by knip, and two hedging paragraphs from the
+PR body: "-34 lines, behavior unchanged, `workit check test` exit 0".
+
+## Check
+
+```sh
+workit check test && git diff --stat <base>...HEAD
+```