@wrongstack/core 0.302.2 → 0.305.0

package/skills/wrongstack-kanban/SKILL.md

@@ -1,132 +1,134 @@
 ---
 name: wrongstack-kanban
-description: >-
-  Monitor and manage a WrongStack project's IPC-backed Kanban through the
-  dedicated tool actions. Enforces deterministic task lifecycle, prevents
-  fake-progress, and ensures every card carries verifiable evidence before
-  completion. Use this skill whenever working with Kanban boards, tasks,
-  dispatch, verification, or the kanban tool.
-triggers:
-  - user says "kanban", "board", "task dispatch", "kanban queue"
-  - working with the kanban tool or kanban_queue
-  - managing project work through boards
+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 tracked work. Chat
-messages, session logs, and agent self-reports are **not** completion evidence.
-Only persisted board mutations with verifiable evidence count.
+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.
 
-## 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.
-
-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.
+**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.
 
-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.
+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.
 
-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.
+## Proportional hierarchy
 
-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.
-
-## 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 |
+| 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