@brainervirus/workit-cursor 0.11.0 → 1.0.0

package/hooks/hooks-cursor.json

@@ -5,6 +5,35 @@
       {
         "command": "npx -y --prefer-online --package=@brainervirus/workit-cursor@latest workit-cursor-session-start"
       }
+    ],
+    "preToolUse": [
+      {
+        "command": "npx -y --prefer-online --package=@brainervirus/workit-cursor@latest workit-cursor-hook",
+        "matcher": "Write|Edit|Delete|Shell|Remove|ApplyPatch|Apply_Patch|Patch|Rename|Mkdir|Mv|Cp|Touch",
+        "failClosed": true
+      }
+    ],
+    "beforeShellExecution": [
+      {
+        "command": "npx -y --prefer-online --package=@brainervirus/workit-cursor@latest workit-cursor-hook",
+        "failClosed": true
+      }
+    ],
+    "subagentStart": [
+      {
+        "command": "npx -y --prefer-online --package=@brainervirus/workit-cursor@latest workit-cursor-hook",
+        "failClosed": true
+      }
+    ],
+    "subagentStop": [
+      {
+        "command": "npx -y --prefer-online --package=@brainervirus/workit-cursor@latest workit-cursor-hook"
+      }
+    ],
+    "preCompact": [
+      {
+        "command": "npx -y --prefer-online --package=@brainervirus/workit-cursor@latest workit-cursor-hook"
+      }
     ]
   }
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@brainervirus/workit-cursor",
-  "version": "0.11.0",
+  "version": "1.0.0",
   "private": false,
-  "description": "Workit Cursor plugin: MCP server, hooks, rules, marketplace manifest (thin over @brainervirus/workit-core)",
+  "description": "Workit Cursor plugin: shared MCP transport and native adaptive hooks",
   "keywords": [
     "agent",
     "cursor",
@@ -18,6 +18,7 @@
     "url": "https://github.com/BrainerVirus/workit.git"
   },
   "bin": {
+    "workit-cursor-hook": "./dist/workit-hook.js",
     "workit-cursor-mcp": "./dist/mcp-server.js",
     "workit-cursor-session-start": "./dist/cursor-session-start.js"
   },
@@ -26,9 +27,9 @@
     "assets/",
     "mcp.json",
     ".cursor-plugin/",
-    "rules/",
+    "rules/workit-contract.mdc",
     "skills/",
-    "vendor/superpowers/skills/",
+    "commands/",
     "hooks/hooks-cursor.json"
   ],
   "type": "module",
@@ -39,11 +40,10 @@
     "build": "bun scripts/build.ts"
   },
   "dependencies": {
-    "@brainervirus/workit-core": "^0.11.0",
-    "@modelcontextprotocol/sdk": "^1.12.0",
-    "zod": "^3.24.0"
+    "@brainervirus/workit-core": "^1.0.0",
+    "@brainervirus/workit-mcp": "^1.0.0"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   }
 }

package/rules/workit-contract.mdc

@@ -0,0 +1,28 @@
+---
+description: Workit adaptive task contract and truthful Cursor capability limits
+alwaysApply: true
+---
+
+Workit is ambient: inspect the current task state before changing it and use
+the eight shared `workit_*` operations for task, policy, evidence, finding,
+decision, worker, writer, and continuity state.
+
+Cursor's native hooks are evidence only where their documented input and
+blocking behavior support it. AskQuestion answers are policy-only
+(`agent_guided`); `sessionStart` and `preCompact` cannot block; `subagentStop`
+does not expose a stable subagent identity; arbitrary shell writes and Tab
+edits are unavailable. Never claim stronger assurance, and never invent a
+delegation token, receipt, or cross-process caller channel.
+
+Preserve one active task, exact workspace/session bindings, reviewer and
+investigator read-only scope, Cursor's unavailable implementer delegation, and
+the no-worktree rule. Lead implementation stays inline only when policy permits.
+
+When starting a native Cursor subagent during an active Workit task, begin the
+task payload with exactly one bounded role marker: `[workit-role: implementer]`,
+`[workit-role: reviewer]`, or `[workit-role: investigator]`. Cursor's native
+`subagent_type` values describe execution kinds, not Workit authority roles;
+missing, repeated, or invalid markers are denied while a task is active.
+Cursor cannot safely attest MCP writer identity or release a child writer at
+`subagentStop`, so an implementer marker is denied; use reviewer/investigator
+delegation for read-only work only.

package/skills/workit-babysit/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: workit-babysit
+description: Use when a PR needs driving to merge-ready, CI is red, or the user says babysit
+---
+
+# Babysit a PR to merge-ready
+
+Babysit starts automatically on PR creation unless declined (`--no-babysit`).
+One babysitter per PR; never mutate PR topology (no rebase strategy changes,
+no force-push).
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Declare mode: drive (fix + merge), watch (report only), or threads-only.
+2. Work the merge frontier in order: conflicts → review threads → CI.
+3. Classify CI before retry: flake (rerun once) vs stale base (verify with
+   `git merge-base --is-ancestor` before updating) vs real failure (fix).
+4. Triage bot findings skeptically: reproduce or quote code before acting;
+   invalid bots get a reasoned dismissal, never silent ignore.
+5. Batch fixes into one push wave; re-verify green after every push.
+6. Merge only when green and approved, honoring `pr` settings (squash +
+   delete branch). Stop at the human's line: never merge on explicit hold.
+
+## Completion
+
+PR merged per settings, or a status brief (frontier state, next action) when
+blocked on the human. Record evidence for fixes, findings for blockers.

package/skills/workit-behavioral-tdd/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: workit-behavioral-tdd
+description: Use when policy identifies behavior, side effects, permissions, or data handling that may change and a regression boundary is needed
+---
+
+# Behavioral TDD
+
+Test the observable behavior at a stable boundary, not the implementation shape.
+Use this method when assessment selects the `testing` dimension.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Inspect the task requirement, current candidate, intended behavior, and real
+   verification entry point with shared `task`, `policy`, and `evidence` operations.
+2. State one behavior and its observable result. Choose the narrowest stable
+   boundary a caller or user depends on; avoid private helpers and incidental
+   representations.
+3. Write one vertical RED slice that fails for the missing behavior, run it, and
+   preserve the actual failure as evidence. Implement the smallest change, then
+   run the same slice GREEN and record its result. Close enforces the order: a
+   testing requirement with GREEN but no preceding RED evidence stays unsatisfied.
+4. Add only another slice for a distinct behavior or risk. Reconcile stale
+   evidence if the candidate changes.
+
+## Reject noisy tests
+
+- A dependency/version-pin assertion is not behavioral evidence.
+- A test that mirrors branches, private calls, or exact implementation structure
+  is coupled to internals; replace it with the public effect.
+- Duplicate assertions and tests that add no distinct failure signal are noise;
+  delete them.
+- Do not claim a passing test satisfies a different requirement.
+- Banned: tautologies (asserts what the code says, not what it must do),
+  ghost loops (assert inside a possibly-empty loop), smoke-only renders,
+  type-only or CSS-class coupling. If the test still passes when every
+  imported function returns undefined, rewrite the assertion or delete it.
+
+Use shared `evidence` operations for RED/GREEN results. Do not add a second
+lifecycle, approval chain, or test workflow outside the current task state.
+
+## Common mistakes
+
+| Mistake | Correction |
+| --- | --- |
+| "The pin changed, so assert the new string" | Exercise the affected consumer behavior. |
+| "The code is obvious" | A small vertical slice still proves the contract. |
+| Keeping a passing test after the boundary moved | Mark it stale and retest the current candidate. |

package/skills/workit-blast-radius/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: workit-blast-radius
+description: Use when a small-looking change could break something else, before close or merge
+---
+
+# Blast radius beyond the diff
+
+A small diff is not a small risk. Prove the one fact it is safe because of,
+with runnable proof — not assertion.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. List what the change touches: callers, shared state, contracts, config,
+   migrations. Grep every caller of each touched function.
+2. For each: state the one fact it is safe because of (type boundary,
+   existing test, unreachable path) plus how to run the proof.
+3. Run the proofs. Unproven claims stay labeled UNPROVEN in findings —
+   never silently treated as safe.
+4. Fix at the shared root (one guard where all callers route through),
+   not per caller.
+
+## Completion
+
+Blast-radius note in evidence or review: each risk with fact + proof
+command, or an UNPROVEN finding for what could not be proven.

package/skills/workit-challenge/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: workit-challenge
+description: Use when a proposal is ambiguous, consequential, disputed, or may hide assumptions, coupling, failure modes, or a simpler solution
+---
+
+# Challenge a proposal with a grounded grill
+
+Treat the proposal as a hypothesis. Facts are the agent's job; decisions are
+the user's. Use this method when assessment selects the `challenge` or
+`decisions` dimension.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Ground first: inspect the task, policy, candidate, evidence, decisions, and
+   the repo docs that exist. Never ask what code or docs can answer.
+2. Diverge once, bounded: when the approach is unknown, offer 3-5 candidate
+   directions with evidence and tradeoffs in one advisory burst, without
+   critique. Record the burst as artifact evidence when it matters; the user
+   steers or mixes.
+3. Grill one question at a time: each question carries your recommended answer,
+   the facts behind it, and at least one rejected alternative. Resolve
+   dependency order and recompute after every answer — a wall of questions is
+   not an interview.
+4. Funnel every resolution: the moment a consequential choice settles, bind it
+   with a receipt-shaped question (header `Workit decision: <purpose>`, exactly
+   `approved`/`rejected`, the approved description carrying the exact content).
+   If the user already stated the choice in conversation and no receipt can be
+   minted, record it in task progress and reassess so the settled requirement
+   retires — never re-ask to mint a receipt, and never leave it for close to
+   demand.
+5. Durability: write or refresh the spec under `docs/<slug>/` only when the
+   `durable-spec` requirement fires. No glossary, no second lifecycle.
+6. Counter-case: each material recommendation carries one strongest
+   counter-case (hidden assumption, failure mode, coupling, simpler
+   alternative). Stop when a counter-case adds no new constraint.
+
+Stop at an empty frontier or three rounds; the cap is the bound. Say directly
+when the proposal is weak, overcomplicated, or solves the wrong problem.
+
+## Guardrails
+
+- Do not create a universal spec, plan, approval chain, or second lifecycle.
+- Unknowns that affect the dependent action remain unresolved until evidence or a
+  user decision closes them.
+- Use the shared operations for state and provenance; never write task metadata
+  directly.
+- An in-session counter-case is never fresh-context review; claim only what it is.
+
+## Common mistakes
+
+| Mistake | Correction |
+| --- | --- |
+| Asking what the code or docs already answer | Ground first; the user owns choices, not lookups. |
+| Listing every hypothetical objection | One strongest counter-case, then stop. |
+| Asking "what do you think?" without a recommendation | Recommend an option and explain the tradeoff. |
+| Leaving a settled choice for close to confirm | Funnel it when it resolves; progress plus reassessment if no receipt. |

package/skills/workit-debug/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: workit-debug
+description: Use when behavior is failing, surprising, contradictory, or regressed and the root cause is not established
+---
+
+# 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.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## 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 checks.
+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.
+
+Honor task status, scope, revisions, and native authority gates. Do not bypass
+them for an incident, create a second lifecycle, or claim a fix from a green
+command that did not exercise the affected behavior.
+
+## Red-capable gate
+
+Never hypothesize without a loop that goes red on this exact failure. Build
+the loop first, in this order: failing test → CLI command + fixture →
+request replay → trace. Tighten it until fast, sharp, deterministic, and
+agent-runnable. No loop → stop, list what was tried, ask for the
+environment or artifact; never theorize without it.
+
+Minimise: cut one element at a time until every remainder is load-bearing;
+the minimised case becomes the regression test. State hypotheses ranked and
+falsifiable (`If <X> then changing <Y> removes it`), probe one variable at
+a time, tag debug logs for grep cleanup. Write the regression at the seam
+where the real pattern occurs — no correct seam means the finding is the
+architecture, so flag it instead of patching around it.
+
+When the host reports writer capability unavailable, do not mutate or delegate
+mutation. Continue inline only if policy and lead authority permit it;
+otherwise report the capability gap.
+
+## 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. |

package/skills/workit-deslop/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: workit-deslop
+description: Use before opening a PR or after implementation to remove AI slop from code and prose
+---
+
+# Deslop code and prose
+
+Throughput without quality is slop. Clean it with a minimal diff — deslop
+never refactors behavior.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## 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.

package/skills/workit-diagram/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: workit-diagram
+description: Use when a spec or plan needs a flow or architecture diagram
+---
+
+# Mermaid when needed, never by default
+
+Tables first, ASCII trees second, mermaid only when a flow or architecture
+needs it. Flowchart, sequence, state, or ER only. No renderer, no network.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Syntax rules (mermaid v11)
+
+- Fence as ` ```mermaid `, no surrounding prose inside the fence.
+- Quote node labels containing punctuation: `A["input (x, y)"]`.
+- One direction per diagram (`TD` or `LR`); keep nodes under twelve.
+- Name actors exactly as the codebase names them (real symbols only).
+
+## Verify
+
+Re-read the fence before commit: balanced quotes/brackets, every node
+reachable, labels match spec terms. If it cannot be verified by reading,
+delete it.
+
+## Completion
+
+One diagram that argues a decision, or nothing. Never a diagram suite.

package/skills/workit-green-run/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: workit-green-run
+description: Use to drive a red CI pipeline back to green, usually inside babysit
+---
+
+# The CI loop
+
+Watch, classify, fix, push once, re-verify. Host-native (`gh` / GitLab);
+never invent CI APIs.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Read the failing checks, not the summary. Quote the failing log lines.
+2. Classify each: flake (rerun once, note it) / stale base (update after
+   merge-base check) / real failure (reproduce locally, then fix).
+3. Fix at root cause with a regression test; push one wave.
+4. Re-verify the same checks green on the new head. A fix without a
+   green re-run is not a fix.
+
+## Completion
+
+Green pipeline on the merge head, or an escalated finding with the exact
+failing logs when the fix needs the human.

package/skills/workit-handoff/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: workit-handoff
+description: Use when work must continue in another session, host, or agent after interruption, transfer, or compaction
+---
+
+# Handoff durable task state
+
+Transfer continuity, not live authority. Use this method when assessment selects
+the `durable-handoff` rule.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Inspect the current task, scope, decisions, policy requirements, candidate,
+   evidence, findings, progress, and worker states with shared `task` and `state`
+   operations.
+2. Export the compact state through `state.export`. Preserve the objective,
+   exclusions, accepted decisions and reasons, evidence references, open gaps,
+   findings, candidate identity, blockers, and next action. Do not include
+   credentials, live writer ownership, or host authority.
+3. Import only through the destination `state.import` operation and its expected
+   workspace revision. The destination starts paused or otherwise unauthorised
+   until it observes its own host/session and reconciles stale evidence and
+   uncertain workers.
+4. Resume or continue through shared `task`, `policy`, `worker`, `writer`, and
+   `evidence` operations. Record what changed instead of copying a transcript.
+
+A handoff does not require a formal spec or plan unless those are separate
+selected requirements. Never grant destination authority from imported prose,
+create a second lifecycle, or edit task metadata directly.
+
+## Common mistakes
+
+| Mistake | Correction |
+| --- | --- |
+| Sending the whole transcript | Export compact decisions, gaps, evidence, and next action. |
+| Restoring the old writer or credentials | Re-observe authority in the destination. |
+| Calling a handoff complete without reconciliation | Recheck stale files and uncertain workers first. |

package/skills/workit-implement/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: workit-implement
+description: Use when scoped implementation, helper delegation, or checkout writer coordination is required by the current task policy
+---
+
+# Implement within authority
+
+Implement only inside the current task scope and writer boundary. Assignment is
+not launch authority, and a timeout is not proof that a worker stopped.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Inspect task state, requirements, decisions, candidate, capabilities, and
+   current workers with shared `task`, `policy`, and `worker` operations.
+2. If a helper is useful, assign one bounded objective with allowed paths,
+   applicable requirements, evidence needed, and a stopping condition. Helpers
+   cannot change scope, record binding decisions, close or pause the task, assign
+   helpers, or resolve blockers for the lead.
+3. Observe the native session and worker state. Acquire checkout writer ownership
+   through `writer` before any product-mutating command; release it explicitly.
+   Cancellation remains uncertain until process exit or explicit recovery.
+4. Reconcile the helper report and evidence through shared operations. If required
+   delegation is unavailable, continue inline only when policy allows it and state
+   the capability limitation.
+
+Do not edit Workit metadata directly, create nested helper trees, widen paths, or
+create a second lifecycle. Read-only investigation and bounded reports do not
+grant product-write ownership.
+
+When the host reports writer capability unavailable, do not mutate or delegate
+mutation. Continue inline only if policy and lead authority permit it;
+otherwise report the capability gap.
+
+## Common mistakes
+
+| Mistake                                        | Correction                                          |
+| ---------------------------------------------- | --------------------------------------------------- |
+| "The helper timed out, so the writer is free"  | Observe exit or perform explicit recovery.          |
+| Letting a helper approve its own exception     | Return the decision to the lead/user.               |
+| Running a build while another writer is active | Treat builds and tests that mutate state as writes. |

package/skills/workit-mockup/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: workit-mockup
+description: Use when a UI decision needs sketching before implementation
+---
+
+# ASCII mockups before UI code
+
+Sketch, don't build. Three genuinely different layout hypotheses maximum,
+ASCII only, no code output.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Fix a legend (`┌─┐ │ └─┘ ░ ≈ [ ] ( )`) and keep sketches 60-80 cols,
+   8-20 rows.
+2. Per hypothesis: regions, component reuse vs new (named against the
+   existing codebase), empty/loading/populated/error states, nav flow.
+3. Ask at most one clarifying question, then recommend. Flag hi-fi
+   escalation when ASCII cannot settle it (density, motion, brand).
+
+## Completion
+
+The sketch plus the decision lands in the spec dir. Throwaway by design.

package/skills/workit-plan/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: workit-plan
+description: Use when dependencies, sequencing, coordination, or resumption make durable next actions useful
+---
+
+# Plan useful coordination
+
+Use a compact plan when assessment selects `artifacts` or `continuity`. A plan
+organizes work; it is not a second lifecycle or a prerequisite for implementation.
+
+## Before method work
+
+If there is no active or paused task, run shared `task.start` then `policy.assess`
+before relying on selected policy rules or other product mutations. Assessment
+selects requirements; do not wait for a rule that can only exist after assess.
+
+## Method
+
+1. Inspect current task state, scope, decisions, requirements, candidate, workers,
+   findings, and blockers through the shared `task` and `policy` operations.
+2. Record only the useful sequence: objective, dependency, bounded task, evidence
+   needed, owner, and next action. Keep the plan against the existing system.
+3. If policy separately requires a durable specification, record that behavior
+   agreement; otherwise do not invent a spec. A plan without a spec is valid.
+4. Update the shared task progress at meaningful boundaries. Reassess when facts,
+   dependencies, or scope change; preserve unresolved blockers and decisions.
+5. On steering (new instructions mid-task): apply `workit-steer` — park state
+   verbatim, classify same-task / new-task / quick-question, handle, re-anchor.
+
+Use shared task/progress and evidence operations. Do not create a universal
+spec-and-plan ceremony, duplicate task state, approval chain, or custom status
+machine. A short paragraph is enough when it captures the required continuity.
+
+## Triage (automatic)
+
+Set assessor signals from size facts, not memory (`triageTier` /
+`triageSignals` in policy-resolver):
+
+- **Large → spec + full plan:** new/changed observable behavior, open
+  ambiguity, cross-package/host contract or auth/data/security surface,
+  irreversible migration, or ≥3 subsystems / ≥2 packages touched.
+- **Medium → compact plan-only** (Sequence/Acceptance, ~30-60 lines): known
+  approach, single subsystem, 2-8 steps. Step count alone never escalates
+  a known single-subsystem run to spec.
+- **Small → neither** (progress + evidence only): single bounded mechanical
+  action, no open choices, reversible. Record `Spec: none (reason)`.
+
+`task.start` + `policy.assess` stay mandatory at all sizes. The lead may
+re-tier with the reason recorded in progress (override, never silent).
+
+## Decomposition
+
+Slice tracer bullets, not layers: each plan task crosses the necessary
+layers to a small demoable behavior with its blocking edges declared.
+Wide refactors use expand–contract (add the new seam, migrate callers,
+delete the old). Per task record Files (create/modify/test, exact paths),
+exact commands with expected output, and one commit. No placeholders —
+an implementer must be able to execute a task with zero extra context.
+
+## Common mistakes
+
+| Mistake | Correction |
+| --- | --- |
+| Writing a full packet for a small dependency | Capture the next bounded action and its evidence. |
+| Treating the plan as authority | Authority remains in task scope, decisions, revisions, and caller provenance. |
+| Copying a transcript into the plan | Preserve decisions, gaps, blockers, and next action only. |