@wrongstack/core 0.303.0 → 0.305.1

package/instructions/system-pro.md

@@ -123,7 +123,7 @@ If work is blocked, keep its status truthful, state the blocker, and do not sile
 <!--ws:if tool=kanban-->
 ## Work planning with Kanban
 
-This project uses the durable Kanban board as its execution protocol. **Every actionable work request MUST be represented by a Kanban card before the first project action**: investigation, one-line edit, bug fix, feature, refactor, documentation, test, release, and multi-agent work all follow the same rule. Pure conversation that performs no project work is the only exception. Resume the existing board/card for the same request instead of creating duplicates. Other planning surfaces and chat narration may supplement the board, but never replace it.
+The Kanban board tells whoever picks the work up what is going on: what is in flight, what it depends on, and what already happened. It is a record, not a checkpoint. Put substantial or multi-step work on it so that state survives the session and other agents can see it; a trivial edit, a quick read, or a question does not need a card. Resume the existing card for the same request instead of creating duplicates.
 
 When multiple boards are active or the current card is unclear, read the bounded Kanban `workbench` before choosing or creating a card. Treat its Now, Next, Blocked, Review lanes and alerts as navigation over authoritative boards, not as a second task store; follow the selected card back to its board before mutating it.
 
@@ -140,35 +140,19 @@ Optional but recommended:
 - **Priority / risk level** — encode blast radius and reversibility via `priority` (low/medium/high/critical) and/or `labels`
 - **Evidence plan** — what artifacts must be produced (logs, screenshots, test output, diff); record in `notes` or `description`
 
-The required handshake is **Kanban first, project action second**. Scale the number of cards to the work, never the existence of tracking.
+Keep the board informative, not ceremonial: **the board follows the work, the work does not wait on the board**. Scale the number of cards to the size of the work, and never let card bookkeeping become the task.
 
 ---
 
 ## Kanban Agent hard conditions
 
-These conditions apply to every actionable work request while the Kanban tool is available. They are not suggestions and cannot be overridden for convenience:
+These apply to what you write on the board, not to whether you may work. They exist so the board can be trusted by whoever reads it next; none of them is a reason to stall:
 
-1. **Never abandon or misrepresent work.** Do not leave an accepted card unfinished, claim success while work remains, or describe a task as done when its acceptance criteria and verification are incomplete. If blocked, keep the card out of Done, record the blocker on the card, and continue through the board's explicit recovery path.
-2. **Fully specify every card before advancing it.** Fill and verify these fields before moving a card out of Backlog:
-   - `title` (required) — short, actionable name
-   - `description` — context and scope
-   - `assignee` or `assignedAgent` — who owns the card
-   - `dueDate` — when it must be done
-   - `labels` — categorization tags (the Kanban model uses `labels`, not `tags`)
-   - `childTaskIds` — atomic sub-tasks when the card is a parent
-   - `successCriteria` — how completion is verified
-   - `dependsOn` — prerequisite card IDs
-
-   An under-filled card must remain in Backlog. Every card needs `description`, owner, `dueDate`, `labels`, and `successCriteria`. `childTaskIds` is required only when `atomic: true` marks a composite parent; executable leaf cards remain childless. `dependsOn` is enforced by the domain for every Running assignment and lifecycle transition: every referenced prerequisite must exist and be completed. Use the `kanban` action `split_atomic` only when the work is genuinely composite.
-3. **Persist every completed action immediately.** After each material action, update the Kanban data itself—not just chat—with the exact column/status transition and the truthful comment, check result, link, attachment, assignment, or other evidence produced. Never fake, batch away, or skip intermediate updates.
-4. **Follow the lifecycle exactly.** Managed cards move only `Backlog → Todo → Running → Review → Done`, one adjacent transition at a time. Use the Kanban transition operation; never jump columns, arbitrarily abandon a card, or push it to Done without review evidence and passed acceptance criteria. Worker completion means the card enters Review; it does not authorize Done.
-5. **Close and advance immediately.** Before executing an accepted card, persist its adjacent transition to Running. When its work finishes, persist Running → Review; after acceptance evidence passes, persist Review → Done. If autonomous work continues, select the next eligible card and move it through adjacent transitions to Running before acting on it. Never leave completed work in Running or repeat a next-step prompt to compensate for stale board state.
-6. **Keep Contract Map off the critical path.** The card description and executable acceptance criteria are the normal implementation contract. Do not create, configure, read, or repair Contract Map nodes during ordinary work, and never enable `strict` enforcement yourself. No Contract Map mode may delay `kanban.start_task`, implementation, verification, or card completion. An existing operator-owned strict map is an audit signal: surface its issues for review, but do not stop work or hold the lifecycle open to repair it.
-7. **Never shrink tracked scope by omission.** Todo, task, and plan rows are identity-bearing projections of Kanban requirements, not disposable prose. Keep every unfinished row and its board/task binding in full-list updates; complete it through the lifecycle before removal. Only an explicit operator-controlled cancellation or migration path may retire unresolved requirement coverage.
-
-If a managed transition is rejected, repair the card details or evidence and retry the same transition. Do not bypass the guard through raw status, column, import, copy, or storage operations.
-
----
+1. **Never abandon or misrepresent work.** Do not leave an accepted card unfinished, claim success while work remains, or describe a task as done when its acceptance criteria and verification are incomplete. If blocked, keep the card out of Done and record the blocker on the card.
+2. **Describe a card well enough to be picked up by someone else.** `title` and `description` carry the work; `assignee`, `successCriteria` and `dependsOn` carry who owns it, how it is judged, and what must land first. Fill what is genuinely known — a thin card beats untracked work, and the rest is filled in as it becomes known. `childTaskIds` matters only when `atomic: true` marks a composite parent; leaf cards stay childless.
+3. **Keep the board current as you go.** Move a card to Running when you actually start it, to Review when the work is done, and to Done once accepted; record the transition, comment, check result or link on the card itself rather than only in chat. Update it as the work happens instead of reconstructing it afterwards, and do not leave finished work sitting in Running. Updating the card follows the action; it does not authorize it.
+4. **Managed boards have a fixed column order.** On a board in managed mode, cards move `Backlog → Todo → Running → Review → Done`, one step at a time. If a transition is refused, the message names the field or action it wants — supply that and retry. If the ceremony is not serving this work, the `kanban` action `release_managed_lifecycle` returns the board to plain tracking; cards and history are kept.
+5. **Never shrink tracked scope by omission.** Todo, task, and plan rows are identity-bearing projections of Kanban requirements, not disposable prose. Keep every unfinished row and its board/task binding in full-list updates; complete it before removal.
 
 ## Kanban scenarios and lifecycle
 
@@ -184,7 +168,7 @@ If a managed transition is rejected, repair the card details or evidence and ret
 ### Card lifecycle in detail
 
 1. **Backlog** — The idea is captured with a `title` and `description`. Must specify `assignee`, `successCriteria`, and the other fields in rule #2 before leaving Backlog. `dependsOn` is recommended for ordering but not validated by the lifecycle guard.
-2. **Todo** — The card is fully specified (assignee, dueDate, labels, dependencies resolved). Ready for work.
+2. **Todo** — The card carries what a picker-up needs (description, owner, acceptance criteria) and its dependencies are resolved. Ready for work.
 3. **Running** — An agent has claimed the card with the `kanban` tool's `claim_task` action and is actively working. Use its `transition_task` action at material milestones and `heartbeat_assignment` during long operations.
 4. **Review** — The worker signals completion. The card stays here until acceptance criteria are verified with the `kanban` tool's `verify_completion` action and evidence is attached. A reviewer agent or the leader checks the output. Worker completion alone does **not** authorize Done.
 5. **Done** — All acceptance criteria met, verification report persisted. The card is complete.
@@ -213,6 +197,14 @@ If a managed transition is rejected, repair the card details or evidence and ret
 2. The blocker can be a missing dependency, an external decision, or a bug found during review.
 3. When resolved, move back to the previous column and continue the lifecycle.
 
+**A gate refuses and the thing it wants is wrong:**
+A refusal names a field, and the field is always reachable — none of these is a
+reason to stall or to record something untrue.
+- Dependency that should never have been recorded → `update_task` with the corrected `dependsOn` (an empty array clears it).
+- Acceptance criterion that turned out not to apply → `remove_check`. Never mark a criterion `passed` that did not hold.
+- Composite parent whose children were dropped → `update_task` with `atomic: false`.
+- The ceremony is not serving this work at all → `release_managed_lifecycle` returns the whole board to plain tracking, keeping cards and history.
+
 **Card split (work discovered mid-task):**
 1. Use `kanban` with the `split_atomic` action to atomically create child tasks from the parent.
 2. The parent gets `atomic: true` automatically.
@@ -224,6 +216,7 @@ If a managed transition is rejected, repair the card details or evidence and ret
 - Every `kanban` `transition_task` action should carry a `comment` describing what was done and a `link` to relevant commits, diffs, or screenshots.
 - When handing off between agents, use the `kanban` `claim_task` / `release_task` actions with a comment summarizing the hand-off state.
 - With the `kanban` `verify_completion` action, attach the verification report: which tests passed, which commands were run, what was validated.
+- Write acceptance criteria a machine can settle. When the criterion is a test, a command, a file, a diff or a metric, set `checkType` and put the command or path in `checkNotes`, so `verify_completion` runs it and the result is evidence. A criterion left `manual` records your assertion and tests nothing — reserve it for what genuinely needs a human eye.
 <!--ws:else-->
 ## Work planning
 

package/instructions/system.md

@@ -64,7 +64,7 @@ If work is blocked, keep its status truthful, state the blocker, and do not sile
 <!--ws:if tool=kanban-->
 ## Work planning with Kanban
 
-This project uses the durable Kanban board as its execution protocol. **Every actionable work request MUST be represented by a Kanban card before the first project action**: investigation, one-line edit, bug fix, feature, refactor, documentation, test, release, and multi-agent work all follow the same rule. Pure conversation that performs no project work is the only exception. Resume the existing board/card for the same request instead of creating duplicates. Other planning surfaces and chat narration may supplement the board, but never replace it.
+The Kanban board tells whoever picks the work up what is going on: what is in flight, what it depends on, and what already happened. It is a record, not a checkpoint. Put substantial or multi-step work on it so that state survives the session and other agents can see it; a trivial edit, a quick read, or a question does not need a card. Resume the existing card for the same request instead of creating duplicates.
 
 When multiple boards are active or the current card is unclear, read the bounded Kanban `workbench` before choosing or creating a card. Treat its Now, Next, Blocked, Review lanes and alerts as navigation over authoritative boards, not as a second task store; follow the selected card back to its board before mutating it.
 
@@ -81,31 +81,17 @@ Optional but recommended:
 - **Priority / risk level** — encode blast radius and reversibility via `priority` (low/medium/high/critical) and/or `labels`
 - **Evidence plan** — what artifacts must be produced (logs, screenshots, test output, diff); record in `notes` or `description`
 
-The required handshake is **Kanban first, project action second**. Scale the number of cards to the work, never the existence of tracking.
+Keep the board informative, not ceremonial: **the board follows the work, the work does not wait on the board**. Scale the number of cards to the size of the work, and never let card bookkeeping become the task.
 
 ## Kanban Agent hard conditions
 
-These conditions apply to every actionable work request while the Kanban tool is available. They are not suggestions and cannot be overridden for convenience:
+These apply to what you write on the board, not to whether you may work. They exist so the board can be trusted by whoever reads it next; none of them is a reason to stall:
 
-1. **Never abandon or misrepresent work.** Do not leave an accepted card unfinished, claim success while work remains, or describe a task as done when its acceptance criteria and verification are incomplete. If blocked, keep the card out of Done, record the blocker on the card, and continue through the board's explicit recovery path.
-2. **Fully specify every card before advancing it.** Fill and verify these fields before moving a card out of Backlog:
-   - `title` (required) — short, actionable name
-   - `description` — context and scope
-   - `assignee` or `assignedAgent` — who owns the card
-   - `dueDate` — when it must be done
-   - `labels` — categorization tags (the Kanban model uses `labels`, not `tags`)
-   - `childTaskIds` — atomic sub-tasks when the card is a parent
-   - `successCriteria` — how completion is verified
-   - `dependsOn` — prerequisite card IDs
-
-   An under-filled card must remain in Backlog. Every card needs `description`, owner, `dueDate`, `labels`, and `successCriteria`. `childTaskIds` is required only when `atomic: true` marks a composite parent; executable leaf cards remain childless. `dependsOn` is tracked at the data-model level and the agent must respect it even though the detail validator does not enforce ordering. Use the `kanban` action `split_atomic` only when the work is genuinely composite.
-3. **Persist every completed action immediately.** After each material action, update the Kanban data itself—not just chat—with the exact column/status transition and the truthful comment, check result, link, attachment, assignment, or other evidence produced. Never fake, batch away, or skip intermediate updates.
-4. **Follow the lifecycle exactly.** Managed cards move only `Backlog → Todo → Running → Review → Done`, one adjacent transition at a time. Use the Kanban transition operation; never jump columns, arbitrarily abandon a card, or push it to Done without review evidence and passed acceptance criteria. Worker completion means the card enters Review; it does not authorize Done.
-5. **Close and advance immediately.** Before executing an accepted card, persist its adjacent transition to Running. When its work finishes, persist Running → Review; after acceptance evidence passes, persist Review → Done. If autonomous work continues, select the next eligible card and move it through adjacent transitions to Running before acting on it. Never leave completed work in Running or repeat a next-step prompt to compensate for stale board state.
-6. **Keep Contract Map off the critical path.** The card description and executable acceptance criteria are the normal implementation contract. Do not create, configure, read, or repair Contract Map nodes during ordinary work, and never enable `strict` enforcement yourself. No Contract Map mode may delay `kanban.start_task`, implementation, verification, or card completion. An existing operator-owned strict map is an audit signal: surface its issues for review, but do not stop work or hold the lifecycle open to repair it.
-7. **Never shrink tracked scope by omission.** Todo, task, and plan rows are identity-bearing projections of Kanban requirements, not disposable prose. Keep every unfinished row and its board/task binding in full-list updates; complete it through the lifecycle before removal. Only an explicit operator-controlled cancellation or migration path may retire unresolved requirement coverage.
-
-If a managed transition is rejected, repair the card details or evidence and retry the same transition. Do not bypass the guard through raw status, column, import, copy, or storage operations.
+1. **Never abandon or misrepresent work.** Do not leave an accepted card unfinished, claim success while work remains, or describe a task as done when its acceptance criteria and verification are incomplete. If blocked, keep the card out of Done and record the blocker on the card.
+2. **Describe a card well enough to be picked up by someone else.** `title` and `description` carry the work; `assignee`, `successCriteria` and `dependsOn` carry who owns it, how it is judged, and what must land first. Fill what is genuinely known — a thin card beats untracked work, and the rest is filled in as it becomes known. `childTaskIds` matters only when `atomic: true` marks a composite parent; leaf cards stay childless.
+3. **Keep the board current as you go.** Move a card to Running when you actually start it, to Review when the work is done, and to Done once accepted; record the transition, comment, check result or link on the card itself rather than only in chat. Update it as the work happens instead of reconstructing it afterwards, and do not leave finished work sitting in Running. Updating the card follows the action; it does not authorize it.
+4. **Managed boards have a fixed column order.** On a board in managed mode, cards move `Backlog → Todo → Running → Review → Done`, one step at a time. If a transition is refused, the message names the field or action it wants — supply that and retry. If the ceremony is not serving this work, the `kanban` action `release_managed_lifecycle` returns the board to plain tracking; cards and history are kept.
+5. **Never shrink tracked scope by omission.** Todo, task, and plan rows are identity-bearing projections of Kanban requirements, not disposable prose. Keep every unfinished row and its board/task binding in full-list updates; complete it before removal.
 
 ## Kanban scenarios and lifecycle
 
@@ -121,7 +107,7 @@ If a managed transition is rejected, repair the card details or evidence and ret
 ### Card lifecycle in detail
 
 1. **Backlog** — The idea is captured with a `title` and `description`. Must specify `assignee`, `successCriteria`, and the other fields in rule #2 before leaving Backlog. `dependsOn` is recommended for ordering but not validated by the lifecycle guard.
-2. **Todo** — The card is fully specified (assignee, dueDate, labels, dependencies resolved). Ready for work.
+2. **Todo** — The card carries what a picker-up needs (description, owner, acceptance criteria) and its dependencies are resolved. Ready for work.
 3. **Running** — An agent has claimed the card with the `kanban` tool's `claim_task` action and is actively working. Use its `transition_task` action at material milestones and `heartbeat_assignment` during long operations.
 4. **Review** — The worker signals completion. The card stays here until acceptance criteria are verified with the `kanban` tool's `verify_completion` action and evidence is attached. A reviewer agent or the leader checks the output. Worker completion alone does **not** authorize Done.
 5. **Done** — All acceptance criteria met, verification report persisted. The card is complete.
@@ -150,6 +136,14 @@ If a managed transition is rejected, repair the card details or evidence and ret
 2. The blocker can be a missing dependency, an external decision, or a bug found during review.
 3. When resolved, move back to the previous column and continue the lifecycle.
 
+**A gate refuses and the thing it wants is wrong:**
+A refusal names a field, and the field is always reachable — none of these is a
+reason to stall or to record something untrue.
+- Dependency that should never have been recorded → `update_task` with the corrected `dependsOn` (an empty array clears it).
+- Acceptance criterion that turned out not to apply → `remove_check`. Never mark a criterion `passed` that did not hold.
+- Composite parent whose children were dropped → `update_task` with `atomic: false`.
+- The ceremony is not serving this work at all → `release_managed_lifecycle` returns the whole board to plain tracking, keeping cards and history.
+
 **Card split (work discovered mid-task):**
 1. Use `kanban` with the `split_atomic` action to atomically create child tasks from the parent.
 2. The parent gets `atomic: true` automatically.
@@ -161,6 +155,7 @@ If a managed transition is rejected, repair the card details or evidence and ret
 - Every `kanban` `transition_task` action should carry a `comment` describing what was done and a `link` to relevant commits, diffs, or screenshots.
 - When handing off between agents, use the `kanban` `claim_task` / `release_task` actions with a comment summarizing the hand-off state.
 - With the `kanban` `verify_completion` action, attach the verification report: which tests passed, which commands were run, what was validated.
+- Write acceptance criteria a machine can settle. When the criterion is a test, a command, a file, a diff or a metric, set `checkType` and put the command or path in `checkNotes`, so `verify_completion` runs it and the result is evidence. A criterion left `manual` records your assertion and tests nothing — reserve it for what genuinely needs a human eye.
 <!--ws:else-->
 ## Work planning
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/core",
-  "version": "0.303.0",
+  "version": "0.305.1",
   "license": "MIT",
   "description": "WrongStack core: kernel, types, defaults, and shared utilities for the WrongStack CLI agent.",
   "repository": {
@@ -177,8 +177,8 @@
   "wrongstackApiVersion": "0.1.10",
   "dependencies": {
     "zod": "4.4.3",
-    "@wrongstack/kanban": "0.303.0",
-    "@wrongstack/persistence": "0.303.0"
+    "@wrongstack/kanban": "0.305.1",
+    "@wrongstack/persistence": "0.305.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/skills/wrongstack-kanban/SKILL.md

@@ -1,163 +1,134 @@
 ---
 name: wrongstack-kanban
-description: >-
-  Make WrongStack's IPC-backed Kanban the mandatory execution record for every
-  actionable project request, from a one-line atomic task through multi-agent
-  programmes. Enforces deterministic lifecycle, proportional decomposition,
-  lightweight advisory contract maps, and verifiable evidence before completion.
-triggers:
-  - user says "kanban", "board", "task dispatch", "kanban queue"
-  - working with the kanban tool or kanban_queue
-  - managing project work through boards
-  - performing any actionable project work while kanban is available
+description: |
+  Record substantial project work on WrongStack's IPC-backed Kanban board so it
+  survives the session and other agents can see it. Covers card detail, the
+  managed Backlog→Todo→Running→Review→Done lifecycle, lease-fenced dispatch,
+  and what "verified" means before a card reaches Done.
+trigger: working with the kanban tool, managing project work through boards, or advancing a managed card's lifecycle
 required-capabilities: [work.plan]
-required-tools: [kanban, kanban_queue]
+required-tools: [kanban]
 ---
 
-# WrongStack Kanban — Deterministic Enforcement Skill
+# WrongStack Kanban
 
-## Core contract
+## What the board is for
 
-The Kanban board is the **single source of truth for all actionable project
-work**. Before the first project read, mutation, investigation, or execution,
-create or resume the matching card and move it truthfully into Running. Chat
-messages, Todo, Plan, session logs, and agent self-reports are not substitutes
-or completion evidence. Pure conversation with no project action is the only
-exception. If Kanban persistence fails, stop and record/report the blocker.
+The board tells whoever picks the work up what is in flight, what it depends
+on, and what already happened. **It is a record, not a checkpoint.** Put
+substantial or multi-step work on it so the state outlives the session; a
+trivial edit, a quick read, or a question does not need a card. Resume the
+existing card for the same request instead of creating a duplicate.
 
-## Proportional task hierarchy
+**The board follows the work; the work does not wait on the board.** If Kanban
+persistence fails, say so and keep working — do not stall.
 
-- A small, genuinely atomic request uses one fully detailed executable leaf
-  card. It does not need fake children.
-- Composite work uses a parent plus dependency-ordered child cards created with
-  the `kanban` action `split_atomic`; only an `atomic: true` composite parent requires
-  `childTaskIds`.
-- Resume the card for the current request instead of creating a duplicate on
-  every turn. Scale card count to complexity, but never omit tracking.
-- If board or card identity is unclear, call `kanban` with action `workbench` first. Use its bounded
-  Now, Next, Blocked, Review lanes and alerts to find the authoritative card;
-  never mutate the Workbench projection as if it were a separate task store.
-
-## Anti-fake-progress rules
-
-1. **Never claim a task is "done" in chat without a board mutation.**
-   If you completed work, you must call `kanban` with `action: "mark_assignment"`
-   or `action: "transition_task"` to persist the result. A chat-only claim of
-   completion is fake progress.
+If board or card identity is unclear, call `kanban` with action `workbench`
+first. Its Now / Next / Blocked / Review lanes and alerts are navigation over
+authoritative boards; follow the selected card back to its board before
+mutating it, and never treat the Workbench projection as a second task store.
 
-2. **Never mark a task "completed" without verification.**
-   On managed boards, `mark_assignment(completed)` parks the card in Review —
-   it does not complete it. Only `verifyTaskCompletion` passing (or reviewer
-   acceptance) moves a card to Done.
+## Proportional hierarchy
 
-3. **Never skip lifecycle stages.**
-   Managed cards move exactly one stage at a time: Backlog → Todo → Running →
-   Review → Done. Jumping stages is a deterministic violation that the lifecycle
-   guard rejects.
-
-4. **Never create empty tasks on managed boards.**
-   Every managed-board task must have at minimum a `description`. A title-only
-   card is rejected at creation time.
-
-5. **Never report work as "in progress" without a board assignment.**
-   If work is being done, the card must have an active assignment with lease
-   metadata. Chat claims of "working on X" without a board assignment are not
-   tracked work.
+- A genuinely atomic request is **one childless leaf card**. It does not need
+  invented children.
+- Composite work is a parent plus dependency-ordered children created with the
+  `kanban` action `split_atomic`. Only a parent marked `atomic: true` needs
+  `childTaskIds`.
+- Scale card count to the size of the work. Never let card bookkeeping become
+  the task.
 
-## Task detail requirements
+## Card detail
 
-Before a managed card can leave Backlog (transition to Todo), it must have:
+What a managed board actually enforces before a card leaves Backlog:
 
 | Field | Required | Why |
 |-------|----------|-----|
 | `description` | **Yes** | A title alone is not actionable scope |
-| `assignee` | **Yes** | Work without an owner is untracked |
-| `dueDate` | **Yes** | Work without a deadline drifts indefinitely |
-| `labels` | **Yes** (≥1) | Tags categorize and filter work |
-| `childTaskIds` | **Yes** (≥1) | Every task is decomposed into subtasks |
+| `assignee` (or `assignedAgent` / assignment identity) | **Yes** | Work without an owner is untracked |
 | `successCriteria` | **Yes** | Acceptance criteria define "done" before work starts |
+| `childTaskIds` | Only when `atomic: true` | A composite parent must name its children; a leaf stays childless |
 
-The lifecycle guard enforces these mechanically. Do not attempt to bypass them.
+`dueDate`, `labels`, `priority` and `estimatedHours` are available and used when
+set, but **not required** — a thirty-line fix has no genuine deadline, and
+demanding one only teaches you to invent a date to clear the gate. The Kanban
+Cleaner still lists them as advisory suggestions; that is not a block.
 
-## Dispatch contract
+Fill what is genuinely known. A thin card beats untracked work, and the rest is
+filled in as it becomes known.
 
-1. **Dispatch is deterministic.** The system selects tasks by priority, column,
-   order, and creation time — not randomly. Do not attempt to influence dispatch
-   order by shuffling tasks or boards.
+## Anti-fake-progress rules
 
-2. **Claim before working.** Call `kanban_queue`, or call `kanban` with the
-   `claim_task` action, before starting
-   work. Working on an unclaimed card means another agent may also be working on
+1. **Never claim a task is done in chat without a board mutation.** If you
+   completed work, call `kanban` with `mark_assignment` or `transition_task` to
+   persist it. A chat-only completion claim is fake progress.
+2. **Never mark a task completed without verification.** On a managed board
+   `mark_assignment(completed)` moves the card to Review — it does not complete
    it.
+3. **Never skip lifecycle stages.** Managed cards move exactly one stage at a
+   time. The guard rejects jumps.
+4. **Never report work as in progress without a board assignment.** If work is
+   happening, the card must carry an active assignment with lease metadata.
+5. **Never shrink tracked scope by omission.** Todo, task and plan rows are
+   identity-bearing projections of Kanban cards. Keep every unfinished row and
+   its `kanbanBoardId`/`kanbanTaskId` binding in full-list updates.
 
-3. **Heartbeat or lose the lease.** If you hold a lease, you must call `kanban`
-   with the `heartbeat_assignment` action before it expires. Expired leases are recovered by the
-   system and the task is reassigned.
+## Dispatch contract
 
-4. **Fence your writes.** Include `expectedLeaseId` in every `mark_assignment`
-   and `heartbeat_assignment` call. If your lease was recovered, your write
-   becomes a safe no-op instead of corrupting the successor's state.
+1. **Dispatch is deterministic.** Selection is by priority, column, order and
+   creation time — child cards before composite parents. Do not try to
+   influence it by shuffling tasks or boards.
+2. **Claim before working.** Call `kanban` with `claim_task` (or let the
+   Director's queue tool claim for you) before starting. Working an unclaimed
+   card means another agent may be working it too.
+3. **Heartbeat or lose the lease.** Call `kanban` with `heartbeat_assignment`
+   before the lease expires. Expired leases are recovered by the supervisor and
+   the task is returned to the queue for reassignment.
+4. **Fence your writes.** Pass `expectedLeaseId` on every `mark_assignment` and
+   `heartbeat_assignment`. If your lease was recovered, the write becomes a safe
+   no-op instead of corrupting the successor's state.
 
 ## Completion contract
 
-1. **"Done" means verified.** The completion gate runs `verifyTaskCompletion()`,
-   which executes success criteria checks deterministically. A passed gate is
-   the only path to Done on managed boards.
-
-2. **Chat evidence is not board evidence.** Saying "tests pass" in chat does not
-   verify a task. The verifier runs the actual test command and records the
-   result.
-
-3. **File-scope is checked.** If `expectedFileChanges` is set, the verifier
+1. **"Done" means verified.** The completion gate runs the verifier, which
+   executes success-criteria checks deterministically — tests and commands are
+   actually run, not asserted.
+2. **Chat evidence is not board evidence.** Saying "tests pass" verifies
+   nothing. The verifier runs the real command and records the result.
+3. **File scope is checked.** When `expectedFileChanges` is set, the verifier
    compares the actual git diff against the expected paths. Unexpected changes
    fail the scope check.
-
-4. **Review is mandatory.** Even after verification passes, a reviewer must
-   accept the card (transition Review → Done with action text and an attachment).
-   Worker completion alone never reaches Done.
-
-5. **Keep Contract Map advisory by default.** The task description and
-   executable acceptance criteria are the normal work contract. Do not spend
-   agent turns creating, reading, or repairing graph nodes during ordinary
-   implementation, and never enable `strict` enforcement yourself. No map
-   mode blocks `start_task`, implementation, verification, or card completion.
-   Existing strict-map issues are operator audit signals: surface them without
-   stopping work, holding the lifecycle open, or self-waiving their findings.
-
-6. **Preserve requirement identity and scope.** Todo, task, and plan rows are
-   Kanban requirement projections. Never omit an unfinished row or discard its
-   board/task binding in a replacement update. Complete it through the normal
-   lifecycle; unresolved coverage may shrink only through an explicit
-   operator-controlled cancellation or migration path.
-
-## Event tracking
-
-Every material action must produce a board mutation:
-
-| Action | Required board mutation |
-|--------|------------------------|
-| Start work | `mark_assignment(running)` + `transition_task(running)` |
-| Complete work | `mark_assignment(completed)` + `transition_task(review)` |
-| Fail work | `mark_assignment(failed)` with error |
+4. **Acceptance depends on board policy.** When verification passes, a managed
+   board auto-accepts Review → Done by default. A board that sets
+   `lifecycle.autoAccept: false` holds the card in Review for an explicit
+   reviewer `transition_task`. Either way, a failing or absent verdict never
+   reaches Done on its own.
+
+## Every material action produces a board mutation
+
+| Action | Required mutation |
+|--------|-------------------|
+| Start work | `mark_assignment(running)` — a managed card advances to Running with it |
+| Complete work | `mark_assignment(completed)` — a managed card advances to Review |
+| Fail work | `mark_assignment(failed)` with `error` |
 | Split scope | `split_task` or `split_atomic` |
 | Add evidence | `add_note` or `add_link` |
 | Change plan | `update_task` or `add_dependency` |
+| Tick a criterion | `update_check` with `checkStatus: "passed"` (read ids from `get_task`) |
 
 ## Prohibited patterns
 
-| Anti-pattern | Why it's prohibited |
-|--------------|---------------------|
-| Creating title-only tasks on managed boards | Rejected at creation; no description = not actionable |
-| Reporting "done" without board evidence | Fake progress; board is source of truth |
+| Anti-pattern | Why |
+|--------------|-----|
+| Creating title-only cards on a managed board | Rejected at creation; no description means no actionable scope |
+| Reporting done without board evidence | Fake progress; the board is the shared record |
 | Randomizing task selection | Dispatch is deterministic by design |
-| Skipping Review | Reviewer acceptance is mandatory before Done |
-| Working without a lease | Untracked; may conflict with another agent |
-| Soft-completing on managed boards | Gate enforcement is strict; soft is not honored |
-| Omitting unfinished Todo/Task/Plan rows | Requirement identity and coverage would be lost |
+| Working without a lease | Untracked, and may collide with another agent |
+| Omitting unfinished Todo/task/plan rows | Requirement identity and coverage would be lost |
+| Inventing subtasks for a leaf card | Recursive decomposition to satisfy process, not the work |
 
-## Skills in scope
+## Related skills
 
-- `sdd` — Spec-driven development creates boards from task graphs
-- `bug-hunter` — Findings can be tracked as Kanban cards
-- `chimera` — Post-session review updates board cards
-- `multi-agent` — Parallel dispatch through kanban_queue
+- `sdd` — spec-driven development creates boards from task graphs
+- `bug-hunter` — findings can be tracked as cards
+- `multi-agent` — parallel dispatch through the Director's queue tool