@wrongstack/core 0.302.0 → 0.303.0

package/dist/types/config/root.d.ts

@@ -1,10 +1,11 @@
 import type { ConfiguredHook, HookEvent } from '../hooks.js';
-import type { AutonomyConfig, ChronicleConfig, IndexingConfig, LaunchConfig, SessionLoggingConfig, SyncConfig } from './autonomy.js';
 import type { AdaptiveConcurrencyConfig, CircuitBreakerRuntimeConfig, ContextConfig } from './context.js';
+import type { AutonomyConfig, ChronicleConfig, IndexingConfig, LaunchConfig, SessionLoggingConfig, SyncConfig } from './autonomy.js';
 import type { FeaturesConfig, LogConfig, MCPServerConfig, PluginConfig, PluginManagerConfig, SageConfig } from './mcp-features.js';
 import type { CustomModelDefinition, ModelMatrixEntry, ProviderConfig } from './providers.js';
 import type { CloudSyncConfig, HqClientConfig, ModelRuntimeConfig, SystemPromptConfig } from './runtime.js';
 import type { BrainConfig, FleetConfig, SkillsConfig } from './skills-fleet-brain.js';
+import type { ThemePresetId } from './ui.js';
 import type { ToolsConfig } from './tools.js';
 export interface GitBehaviorConfig {
     /**
@@ -40,6 +41,15 @@ export interface Config {
      * unset, surfaces fall back to their own browser/system detection.
      */
     uiLocale?: string | undefined;
+    /**
+     * TUI color theme preset — read by the TUI on boot to apply the matching
+     * palette, and written by the `/theme` slash command (CLI REPL and TUI) so
+     * the choice persists across restarts. Unconstrained string at the config
+     * layer: the TUI owns the canonical preset list and applies a fallback
+     * (`catppuccin`) when the stored value is unknown, so a forward-compat
+     * drift on the TUI side never breaks the config round-trip.
+     */
+    themePreset?: ThemePresetId | undefined;
     providers?: Record<string, ProviderConfig>;
     /**
      * Top-level custom models (maps modelId → definition). Merged with

package/dist/types/config/skills-fleet-brain.d.ts

@@ -128,6 +128,40 @@ export interface FleetConfig {
     } | undefined;
     /** Brain-gated fleet supervisor (rebalance/steer/spawn-helper). */
     supervisor?: FleetSupervisorConfig | undefined;
+    /** Roster-agent self-learning: capture → optimize → per-skill addenda. */
+    learning?: AgentLearningConfig | undefined;
+}
+/**
+ * Automatic optimization of roster-agent learning.
+ *
+ * Capture is always automatic. This section governs the *distillation* pass
+ * that turns captured directives into per-skill project addenda and a
+ * consolidated role document, then archives and resets the raw buffer.
+ */
+export interface AgentLearningConfig {
+    autoOptimize?: {
+        /** Run the distillation pass automatically. Default true. */
+        enabled?: boolean | undefined;
+        /** Raw buffer size (bytes) that makes a role eligible. Default 8192. */
+        thresholdBytes?: number | undefined;
+        /** Never optimize a buffer with fewer directives than this. Default 4. */
+        minEntries?: number | undefined;
+        /**
+         * Directives routed to a skill that has no addendum yet. Reaching this
+         * count makes a role eligible even below `thresholdBytes`. Default 3.
+         */
+        minPendingSkillDirectives?: number | undefined;
+        /** Minimum gap between automatic passes for one role. Default 6h. */
+        minIntervalMs?: number | undefined;
+        /** Quiet period after the last capture before a pass starts. Default 20s. */
+        debounceMs?: number | undefined;
+        /**
+         * Evaluate every role once when the fleet host starts, so roles that
+         * became eligible before this session are not stuck waiting for their
+         * next capture. Default true.
+         */
+        sweepOnStart?: boolean | undefined;
+    } | undefined;
 }
 /** Config surface for the brain-gated FleetSupervisor. */
 export interface FleetSupervisorConfig {

package/dist/types/config/ui.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared UI theme preset identifiers.
+ *
+ * Lives in core so the Config schema, the CLI `/theme` slash command, and
+ * the TUI runtime can all reference the same string union without
+ * importing the TUI package (which would invert the dependency direction).
+ *
+ * Keep in lockstep with `THEME_OPTIONS` in `packages/tui/src/theme.ts`.
+ * Adding a preset here is intentional — it also requires updating the TUI
+ * presets map AND the CLI `VALID_PRESETS` set in `tui-theme-adapter.ts`.
+ */
+export declare const THEME_PRESET_IDS: readonly ['catppuccin', 'tokyo-night', 'nord', 'cyberpunk', 'dracula', 'gruvbox-dark', 'solarized-dark', 'one-dark', 'monokai', 'rose-pine', 'kanagawa', 'ayu-dark', 'everforest', 'night-owl', 'synthwave'];
+export type ThemePresetId = (typeof THEME_PRESET_IDS)[number];
+//# sourceMappingURL=ui.d.ts.map

package/dist/types/config.d.ts

@@ -6,5 +6,6 @@ export * from './config/providers.js';
 export * from './config/mcp-features.js';
 export * from './config/autonomy.js';
 export * from './config/skills-fleet-brain.js';
+export * from './config/ui.js';
 export * from './config/root.js';
 //# sourceMappingURL=config.d.ts.map

package/dist/types/context-evidence.d.ts

@@ -54,6 +54,8 @@ export interface CompletedWorkEvidence {
 }
 export interface ContextEvidenceState {
     currentIntent?: ContextIntentEvidence | undefined;
+    /** Recent real human inputs, bounded and rendered as volatile continuity evidence. */
+    recentUserTurns?: ContextIntentEvidence[] | undefined;
     sessionGoals: string[];
     implicitFacts: string[];
     activeErrors: string[];

package/dist/types/index.d.ts

@@ -13,8 +13,8 @@ export { ProviderError, classifyProviderError, effectiveInputTokens, isContextOv
 export type { CacheTtl, Capabilities, JsonSchemaSpec, Provider, ProviderContextLimit, ProviderErrorBody, ProviderErrorKind, ReasoningConfig, ReasoningEffort, ReasoningRequest, Request, RequestCacheControl, Response, ResponseFormat, SafetySetting, StopReason, StreamEvent, Usage } from './provider.js';
 export { StreamHangError } from './provider.js';
 export type { ProviderRunner, RunProviderOptions } from './provider-runner.js';
-export { DEFAULT_TUI_THINKING_WORD, FLEET_CHAT_VERBOSITY_VALUES, MAX_TUI_THINKING_WORD_LENGTH, normalizeTokenSavingTier, normalizeTuiThinkingWord, resolveFleetChatVerbosity, resolveTokenSavingTier } from './config.js';
-export type { AdaptiveConcurrencyConfig, AutonomyConfig, BrainConfig, BrainCouncilConfig, BrainCouncilVoterConfig, BrainModelEntry, CircuitBreakerRuntimeConfig, ConcreteTokenSavingTier, Config, ConfigLoader, ConfigStore, ContextConfig, CouncilPersonaDefinition, CouncilToolConfig, CouncilToolProfileDefinition, CustomModelDefinition, ExecDangerConfig, ExecToolConfig, FeaturesConfig, FleetChatVerbosity, FleetConfig, FleetSupervisorConfig, GitBehaviorConfig, HqClientConfig, IndexingConfig, InputHistoryConfig, LaunchConfig, LaunchMenuChoice, LogConfig, LoopDetectionConfig, MCPHealthConfig, MCPHealthThresholds, MCPServerConfig, ModelMatrixEntry, ModelRuntimeCacheConfig, ModelRuntimeConfig, ModelRuntimeParametersConfig, ModelRuntimeReasoningConfig, NextStepsToolConfig, PluginConfig, PluginManagerConfig, ProviderApiKey, ProviderConfig, SageConfig, SessionLoggingConfig, SkillsConfig, SyncCategory, SyncConfig, TokenSavingTier, ToolDescriptionMode, ToolDescriptionModeConfig, ToolResultRenderMode, ToolResultRenderModeConfig, ToolsConfig } from './config.js';
+export { DEFAULT_TUI_THINKING_WORD, FLEET_CHAT_VERBOSITY_VALUES, MAX_TUI_THINKING_WORD_LENGTH, normalizeTokenSavingTier, normalizeTuiThinkingWord, resolveFleetChatVerbosity, resolveTokenSavingTier, THEME_PRESET_IDS } from './config.js';
+export type { AdaptiveConcurrencyConfig, AgentLearningConfig, AutonomyConfig, BrainConfig, BrainCouncilConfig, BrainCouncilVoterConfig, BrainModelEntry, CircuitBreakerRuntimeConfig, ConcreteTokenSavingTier, Config, ConfigLoader, ConfigStore, ContextConfig, CouncilPersonaDefinition, CouncilToolConfig, CouncilToolProfileDefinition, CustomModelDefinition, ExecDangerConfig, ExecToolConfig, FeaturesConfig, FleetChatVerbosity, FleetConfig, FleetSupervisorConfig, GitBehaviorConfig, HqClientConfig, IndexingConfig, InputHistoryConfig, LaunchConfig, LaunchMenuChoice, LogConfig, LoopDetectionConfig, MCPHealthConfig, MCPHealthThresholds, MCPServerConfig, ModelMatrixEntry, ModelRuntimeCacheConfig, ModelRuntimeConfig, ModelRuntimeParametersConfig, ModelRuntimeReasoningConfig, NextStepsToolConfig, PluginConfig, PluginManagerConfig, ProviderApiKey, ProviderConfig, SageConfig, SessionLoggingConfig, SkillsConfig, SyncCategory, SyncConfig, ThemePresetId, TokenSavingTier, ToolDescriptionMode, ToolDescriptionModeConfig, ToolResultRenderMode, ToolResultRenderModeConfig, ToolsConfig } from './config.js';
 export type { AnyHookOutcome, ConfiguredHook, HookEntry, HookEvent, HookFailurePolicy, HookInput, HookInvocationContext, HookMatcher, HookOutcome, HookRegistrationOptions, HttpHook, InProcessHook, PreToolUseOutcome, PreToolUseStage, ShellHook } from './hooks.js';
 export type { Compactor, CompactReport } from './compactor.js';
 export type { DirectoryPolicy, DirectoryRule, PermissionDecision, PermissionPolicy, PermissionTrace, PermissionTraceStep, TrustPolicy } from './permission.js';

package/dist/types/index.js

@@ -575,6 +575,25 @@ function normalizeTuiThinkingWord(value) {
   return word;
 }
 
+// src/types/config/ui.ts
+var THEME_PRESET_IDS = [
+  "catppuccin",
+  "tokyo-night",
+  "nord",
+  "cyberpunk",
+  "dracula",
+  "gruvbox-dark",
+  "solarized-dark",
+  "one-dark",
+  "monokai",
+  "rose-pine",
+  "kanagawa",
+  "ayu-dark",
+  "everforest",
+  "night-owl",
+  "synthwave"
+];
+
 // src/types/session-markers.ts
 var SESSION_MARKER_EVENT_TYPES = /* @__PURE__ */ new Set([
   "mode_changed",
@@ -1282,6 +1301,7 @@ export {
   SddError,
   SessionError,
   StreamHangError,
+  THEME_PRESET_IDS,
   ToolError,
   ToolErrorCategory,
   ToolValidationError,

package/dist/types/messages.d.ts

@@ -3,6 +3,14 @@ export type MessageRole = 'user' | 'assistant' | 'system';
 export interface Message {
     role: MessageRole;
     content: string | ContentBlock[];
+    /**
+     * Local provenance used by context management. `user_input` is reserved for
+     * text the human actually submitted; provider adapters intentionally ignore
+     * this field. Keeping it on the journaled message lets resumed sessions
+     * distinguish real conversation turns from tool-result/runtime `user`
+     * messages without relying on brittle text heuristics.
+     */
+    origin?: 'user_input' | 'runtime' | undefined;
     /**
      * ISO-8601 timestamp from the originating SessionEvent.
      * Populated by SessionStore.replay() during session load/resume

package/dist/types/multi-agent.d.ts

@@ -168,6 +168,13 @@ export interface SubagentConfig {
      * bodies through `SkillLoader`; missing optional skills are skipped safely.
      */
     skillNames?: string[] | undefined;
+    /**
+     * Every skill this role may draw on, before per-project ranking. The catalog
+     * sets this to the full curated set while `skillNames` holds the default
+     * eager slice; the spawn path ranks the pool by project skill-affinity so a
+     * skill the project actually developed can displace an unused sibling.
+     */
+    skillPool?: string[] | undefined;
     /** Optional smart-dispatch metadata for dynamically created project roles. */
     dispatch?: {
         summary: string;

package/dist/types/session.d.ts

@@ -137,6 +137,23 @@ export type SessionEvent = {
      * payload had on disk. Absent on freshly emitted events.
      */
     messagesOmitted?: number;
+} | {
+    /**
+     * The oldest `count` messages were evicted from the front of the history.
+     *
+     * A delta rather than a `messages_replaced` snapshot, because eviction is
+     * the one rewrite that repeats: once a long session reaches
+     * `Context.MAX_MESSAGES`, *every* subsequent append overflows by one and
+     * drops one. Emitting the surviving history each time made the journal
+     * quadratic in session length — measured at 2.1 GB for one session whose
+     * actual content was ~10 MB, and 17.9 GB across a 20 GB corpus. Replay
+     * splices the same prefix off, so the reconstructed conversation is
+     * identical to what the snapshot would have produced.
+     */
+    type: 'messages_dropped';
+    ts: string;
+    version: 1;
+    count: number;
 } | {
     /**
      * Exact post-rewrite conversation state. Replay replaces all messages
@@ -590,6 +607,8 @@ export interface SessionStore {
      * number of sessions indexed.
      */
     rebuildIndex?(): Promise<number>;
+    /** Release project-daemon connections owned by this store. */
+    dispose?(): Promise<void>;
     /**
      * Streaming event-level search. Walks the JSONL once without buffering
      * the whole file, calling `predicate(event, eventIndex, ts)` for each

package/dist/types/task-graph.d.ts

@@ -31,6 +31,8 @@ export interface TaskEdge {
 export interface TaskGraph {
     id: string;
     specId: string;
+    /** Canonical spec scope. When present, execution must retain at least one task per id. */
+    requiredRequirementIds?: string[] | undefined;
     title: string;
     nodes: Map<string, TaskNode>;
     edges: TaskEdge[];

package/dist/types/tool-executor.d.ts

@@ -78,6 +78,8 @@ export interface ToolExecutorOptions {
      * to the result the model sees).
      */
     hookRunner?: import('../hooks/runner.js').HookRunner | undefined;
+    /** Hard-block product mutations outside a ready, running strict Kanban contract. */
+    requireKanbanGovernance?: boolean | undefined;
     /**
      * Per-tool on-screen result render mode map (`tools.resultRenderMode[name]`).
      * When set, the executor reads this map to decide whether the next

package/dist/utils/context-evidence.d.ts

@@ -1,5 +1,5 @@
 import type { Context } from '../core/context.js';
-import type { TextBlock } from '../types/blocks.js';
+import { type TextBlock } from '../types/blocks.js';
 import type { CompactReport } from '../types/compactor.js';
 import type { CompletedWorkEvidence, CompletedWorkSource, ContextEvidenceState, ToolOutputMetadata } from '../types/context-evidence.js';
 export declare function createContextEvidenceState(): ContextEvidenceState;
@@ -14,6 +14,18 @@ export interface RecordToolOutputEvidenceInput {
     outputLines?: number | undefined;
 }
 export declare function recordUserIntentEvidence(ctx: Context, text: string): void;
+/** Runtime steering/status blocks must not displace real conversation turns. */
+export declare function isRuntimeContextInput(text: string): boolean;
+/**
+ * Keep the real conversation thread visible near the stable system prompt.
+ *
+ * Tool-heavy runs can place hundreds of protocol messages after one human
+ * instruction. Re-sending a small, replaceable tail of actual user inputs is
+ * cheaper and more reliable than retaining every intervening tool exchange.
+ * It is volatile provider evidence, so it never grows the durable chat log or
+ * invalidates the cached base prompt.
+ */
+export declare function buildConversationContinuityBlock(ctx: Pick<Context, 'contextEvidence' | 'messages'>): TextBlock | undefined;
 export declare function recordToolOutputEvidence(ctx: Context, input: RecordToolOutputEvidenceInput): ToolOutputMetadata;
 export declare function markAssistantReferencedEvidence(ctx: Context, text: string): void;
 export declare function buildContextEvidenceDigest(ctx: Context): string;

package/dist/utils/index.js

@@ -855,6 +855,9 @@ var MAX_TOOL_CALLS = 80;
 var MAX_FACTS = 40;
 var MAX_ERRORS = 20;
 var MAX_DIGEST_CHARS = 4e3;
+var MAX_RECENT_USER_TURNS = 8;
+var MAX_USER_TURN_CHARS = 700;
+var RUNTIME_CONTEXT_INPUT_PATTERN = /^\[(?:kanban todo update|fleet pulse|loop-detector|todo-reconciliation|mailbox|btw|system|context_state)\b/i;
 var RECENT_TOOL_CALL_SCAN_LIMIT = 20;
 var EXTRACT_CONTENT_CAP_CHARS = 1e4;
 var EXTRACT_ERROR_TAIL_LINES = 200;
@@ -862,6 +865,7 @@ var WRITE_TOOLS = /* @__PURE__ */ new Set(["edit", "write", "replace", "patch"])
 var READ_TOOLS = /* @__PURE__ */ new Set(["read", "grep", "glob", "ls", "tree"]);
 function createContextEvidenceState() {
   return {
+    recentUserTurns: [],
     sessionGoals: [],
     implicitFacts: [],
     activeErrors: [],
@@ -873,15 +877,25 @@ function createContextEvidenceState() {
   };
 }
 function recordUserIntentEvidence(ctx, text) {
-  const intent = normalizeWhitespace(text).slice(0, 700);
+  if (isRuntimeContextInput(text)) return;
+  const intent = normalizeWhitespace(text).slice(0, MAX_USER_TURN_CHARS);
   if (!intent) return;
   const state = ensureEvidence(ctx);
-  state.currentIntent = { text: intent, updatedAt: Date.now() };
+  const turn = { text: intent, updatedAt: Date.now() };
+  state.currentIntent = turn;
+  state.recentUserTurns ??= [];
+  state.recentUserTurns.push(turn);
+  if (state.recentUserTurns.length > MAX_RECENT_USER_TURNS) {
+    state.recentUserTurns.splice(0, state.recentUserTurns.length - MAX_RECENT_USER_TURNS);
+  }
   if (state.sessionGoals.length === 0 || isGoalish(intent)) {
     pushUniqueBounded(state.sessionGoals, intent, 8);
   }
   state.updatedAt = Date.now();
 }
+function isRuntimeContextInput(text) {
+  return RUNTIME_CONTEXT_INPUT_PATTERN.test(text.trim());
+}
 function recordToolOutputEvidence(ctx, input) {
   const state = ensureEvidence(ctx);
   const scanContent = input.content.length > EXTRACT_CONTENT_CAP_CHARS ? input.content.slice(0, EXTRACT_CONTENT_CAP_CHARS) : input.content;
@@ -949,6 +963,11 @@ function buildContextEvidenceDigest(ctx) {
   if (state.currentIntent?.text) {
     lines.push(`intent: ${state.currentIntent.text}`);
   }
+  const priorTurns = (state.recentUserTurns ?? []).slice(-6, -1);
+  if (priorTurns.length > 0) {
+    lines.push("recent_human_instructions:");
+    for (const turn of priorTurns) lines.push(`- ${turn.text}`);
+  }
   const goals = state.sessionGoals.slice(-3);
   if (goals.length > 0) {
     lines.push("session_goals:");
@@ -1003,6 +1022,7 @@ function ensureEvidence(ctx) {
     ctx.contextEvidence = createContextEvidenceState();
   }
   ctx.contextEvidence.completedWork ??= [];
+  ctx.contextEvidence.recentUserTurns ??= [];
   return ctx.contextEvidence;
 }
 var MAX_COMPLETED_WORK = 50;
@@ -1709,12 +1729,16 @@ function buildLiveNextStepsGateBlock(ctx) {
   });
   const omitted = openTodos.length - todoSnapshot.length;
   if (omitted > 0) todoSnapshot.push(`- \u2026and ${omitted} more open todo(s)`);
+  const todoReconciliation = ctx.tools?.some((tool) => tool.name === "todo") ? [
+    "Before ending the turn, you MUST call the `todo` tool with the complete current list to reconcile actual progress: finished items completed, exactly one actively worked item in_progress, and untouched items pending. A prose claim that work is done does not update the Todo/Kanban state."
+  ] : [];
   return {
     type: "text",
     text: [
       "[nextsteps_gate]",
       `Authoritative live state for this request: open todos = ${openTodos.length}.`,
       "You MUST omit <nextsteps> entirely while these todos remain open. Continue or finish the tracked work; do not propose unrelated follow-on work.",
+      ...todoReconciliation,
       "Open todo snapshot:",
       ...todoSnapshot,
       "[/nextsteps_gate]"
@@ -5420,6 +5444,9 @@ function subjectForToolInput(toolName, input, subjectKey) {
   const obj = input;
   if (subjectKey) {
     const value = obj[subjectKey];
+    if (Array.isArray(value)) {
+      return escapeGlobSubject(JSON.stringify(value));
+    }
     if (typeof value === "string") {
       if (isPathSubjectKey(subjectKey)) {
         const normalized = normalizePathSubject(value);

package/instructions/system-lite.md

@@ -28,15 +28,27 @@ The user is an experienced developer; accelerate them and stay focused.
 6. Report what changed, what was verified, and what remains unverified.
 
 <!--ws:if tool=todo-->
-Use a visible `todo` list for tasks with three or more steps.
-Keep its status truthful; do not mark work complete while verification is pending.
+## Todo status lifecycle
+
+Use a visible `todo` list for tasks with three or more steps. With Kanban active it is a compact projection of real cards, not a second task store: retain each row's `kanbanBoardId` and `kanbanTaskId`. Prose does not update it.
+
+1. Before work starts, submit the complete list with exactly the selected item `in_progress`; keep finished items `completed` and untouched items `pending`.
+2. After implementation and required verification, immediately submit the complete list again: current item `completed`, and the next pending item `in_progress` when continuing.
+3. Before a final response, reconcile every status. Never leave finished work pending/running, never mark unverified work complete, and never repeat a continuation/next-step prompt instead of updating state.
+4. Submit the final all-`completed` snapshot even though it auto-clears afterward. With Kanban active, the projection maps `pending → Todo`, `in_progress → Running`, and verified `completed → Done`, then rebinds the next active task; failed acceptance leaves it open rather than inventing Done.
+
+If blocked, keep the item truthful and report the blocker instead of advancing it as successful.
 <!--ws:end-->
 If verification fails twice for unclear reasons, stop and re-read the source instead of guessing.
 
 <!--ws:if tool=kanban-->
 ## Work planning with Kanban
 
-This project has a Kanban board system for tracking multi-step work across turns and agents. When a task involves multiple files, review cycles, dependencies, or parallel work, **prefer Kanban cards over an ad-hoc todo list**.
+**Every actionable work request MUST be represented by a Kanban card before the first project action**. This includes investigation, one-line edits, bugs, features, docs, tests, releases, and multi-agent work; pure conversation with no project action is the only exception. Resume the existing card for the same request. Other planning surfaces and chat may mirror the work but never replace the board.
+
+If multiple boards are active or card identity is unclear, read the bounded Kanban `workbench` first. Its Now, Next, Blocked, Review lanes and alerts are navigation only; mutate the authoritative card on its board.
+
+Use one fully detailed childless leaf card for genuinely atomic work. Use a parent and dependency-ordered child cards only for composite work; never invent recursive subtasks for process theatre. The required handshake is **Kanban first, project action second**. If persistence fails, report the blocker instead of silently doing untracked work.
 
 Before creating a card, identify these prerequisites as a minimum starting point (the full "MUST" specification is governed by the Kanban Agent hard conditions below):
 - **Description** — what needs to be done
@@ -44,16 +56,19 @@ Before creating a card, identify these prerequisites as a minimum starting point
 - **Risk level** — low / medium / high
 - **Audit needs** — what evidence to capture
 
-Decide **"I should use Kanban for this"** when structured tracking would help.
+Scale the number of cards to the work, never the existence of tracking.
 
 ## Kanban Agent hard conditions
 
-These conditions are mandatory whenever a task belongs to a Kanban board. They are not suggestions and cannot be overridden for convenience:
+These conditions apply to every actionable work request while Kanban is available. They are not suggestions and cannot be overridden for convenience:
 
 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 the description, assignee/agent, due date, tags, subtasks, acceptance criteria, dependencies, and any board-required detail fields. An under-filled card must remain in Backlog.
+2. **Fully specify every card before advancing it.** Fill and verify the description, assignee/agent, due date, labels, acceptance criteria, dependencies, and any board-required detail fields. Only composite parents (`atomic: true`) require persisted `childTaskIds`; executable leaf cards remain childless. An under-filled card must remain in Backlog.
 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.** Persist the accepted card in Running before work. Persist Running → Review when work finishes and Review → Done only after acceptance evidence passes. If continuing, move the next eligible card through adjacent transitions to Running before acting. Never leave completed work in Running or repeat a next-step prompt instead of updating the board.
+6. **Keep Contract Map off the critical path.** Use the card description and executable acceptance criteria for normal work. Do not create, inspect, configure, or repair graph nodes unless the user explicitly asks for graph work, and never enable strict mode yourself. No Contract Map mode may delay start, implementation, verification, or card completion; surface existing strict-map issues as operator audit signals without stopping work to repair them.
+7. **Never shrink tracked scope by omission.** Todo, task, and plan rows carry Kanban requirement identity. Preserve every unfinished row and binding in full-list updates, and complete it before removal; only an explicit operator-controlled cancellation or migration path may retire unresolved 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.
 <!--ws:end-->
@@ -184,7 +199,7 @@ SAGE is the only long-term memory.
 <!--ws:end-->
 
 <!--ws:if tool=todo-->
-Use `todo` for the active checklist in the current session.
+Use `todo` for the compact active-task view; with Kanban every row is a real board card.
 <!--ws:end-->
 <!--ws:if tool=plan-->
 Use `plan` for work that spans turns.
@@ -193,7 +208,7 @@ Use `plan` for work that spans turns.
 Use `task` for structured cross-session work.
 <!--ws:end-->
 <!--ws:if tool=kanban-->
-Use `kanban` only when the work belongs on a durable board.
+Use `kanban` for every actionable project request; all such work belongs on the durable board.
 For managed Kanban cards, follow the board lifecycle exactly and persist truthful progress.
 <!--ws:end-->
 <!--ws:if tool=mail_inbox,mailbox-->

package/instructions/system-pro.md

@@ -107,10 +107,27 @@ Reasoning depth is a dial, not a constant. Match it to the blast radius of what
 10. **Leave the knowledge behind, not just the diff.** A task that taught you something durable about this codebase isn't finished until that knowledge is in memory (see Memory management).
 11. **Keep helper scripts temporary and contained.** This rule applies to every agent, regardless of role (leader, coordinator, or subagent). Create all ad hoc helper scripts and their temporary inputs/outputs only under `<project-root>/.temp_files/` — never in the repository root or source directories. Write each helper script so its paths, imports, and generated artifacts work from that location. Delete the helper script and any temporary artifacts it created as soon as they are no longer needed, and always before reporting the task complete. Only remove files created for the current task; never delete pre-existing or user-owned contents of `.temp_files/`. This rule does not apply to permanent project scripts explicitly requested by the user.
 
+<!--ws:if tool=todo-->
+## Todo status lifecycle
+
+The live `todo` list is the compact UI projection of the active work. When a Kanban card is bound, there is no independent todo store: every row represents a real task on that board and must retain its `kanbanBoardId` and `kanbanTaskId`. Prose does not change status.
+
+1. Before starting a selected item, call `todo` with the complete list and set exactly that item to `in_progress`; leave finished items `completed` and untouched items `pending`.
+2. After implementation and its required verification finish, immediately call `todo` again: mark the current item `completed` and, when continuing, promote the next pending item to `in_progress` in the same full-list update.
+3. Before any final response, reconcile the complete list. Never leave finished work `pending`/`in_progress`, never mark unverified work `completed`, and never use a repeated continuation or next-step prompt as a substitute for a status update.
+4. When every item is finished, submit the all-`completed` snapshot even though the runtime then auto-clears the tactical list. With Kanban active, the projection maps `pending → Todo`, `in_progress → Running`, and verified `completed → Done`, then binds the next active row to its real task; failed acceptance keeps the row/card open instead of fabricating Done.
+
+If work is blocked, keep its status truthful, state the blocker, and do not silently advance as though it succeeded.
+<!--ws:end-->
+
 <!--ws:if tool=kanban-->
 ## Work planning with Kanban
 
-This project has a durable Kanban board system (the `kanban` tool) for tracking work across steps, agents, and sessions. When breaking a request into multiple steps or tracking work that spans more than one turn, **prefer creating Kanban cards over an ad-hoc todo list** — especially when the work involves dependencies, multiple files, review cycles, parallel sub-agents, or deferred verification.
+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.
+
+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.
+
+Use a proportional hierarchy: a genuinely atomic change is one fully detailed executable leaf card and needs no artificial child; composite work is a parent with dependency-ordered child cards. Never recursively split a leaf merely to satisfy process. Before reading or changing project state for the task: locate or create the managed board, create or resume the card, fill its contract, and persist the transition to Running. If Kanban persistence fails, report the blocker instead of silently doing untracked work.
 
 Before creating a card, identify these prerequisites (rule #2 below provides the full mandatory specification; this list is the minimal starting point):
 - **Title** — what needs to be done, in one short sentence
@@ -123,13 +140,13 @@ 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`
 
-When you recognise that a request would benefit from structured tracking — multi-step work, review gates, parallel tasks, or deferred checks — proactively decide **"I should do this with Kanban"** and create the cards before starting the first task.
+The required handshake is **Kanban first, project action second**. Scale the number of cards to the work, never the existence of tracking.
 
 ---
 
 ## Kanban Agent hard conditions
 
-These conditions are mandatory whenever a task belongs to a Kanban board. They are not suggestions and cannot be overridden for convenience:
+These conditions apply to every actionable work request while the Kanban tool is available. They are not suggestions and cannot be overridden for convenience:
 
 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:
@@ -142,9 +159,12 @@ These conditions are mandatory whenever a task belongs to a Kanban board. They a
    - `successCriteria` — how completion is verified
    - `dependsOn` — prerequisite card IDs
 
-   An under-filled card must remain in Backlog. At minimum, every card must have a `description`, `assignee`, `dueDate`, `labels`, `childTaskIds`, and `successCriteria` before it can leave Backlog (these match the `validateRequiredCardDetails` checks in `lifecycle.ts`). Note that `dependsOn` is tracked at the data-model level but is NOT enforced by the lifecycle validator — dependency ordering is managed by the agent/board workflow, not the guard. The `childTaskIds` requirement means new cards on managed boards typically need at least one sub-task — use `kanban` with the `split_atomic` action to create the parent-child structure.
+   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.
 
@@ -156,10 +176,10 @@ If a managed transition is rejected, repair the card details or evidence and ret
 
 | Need | Tool | When |
 |---|---|---|
-| Session-level step tracking | `todo` | Single-session task with ≤5 steps, no cross-agent dependencies |
-| Strategic plan | `plan` | Multi-turn roadmap for a single agent |
-| Cross-session work items | `task` | Work that survives session boundaries but needs no board |
-| **Multi-agent / multi-step / review-gated work** | **`kanban`** | Dependencies, parallel agents, review gates, deferred verification |
+| **Any actionable project work** | **`kanban`** | Mandatory durable execution record, from one atomic leaf to a multi-board programme |
+| Compact active-task view | `todo` | UI projection of real Kanban task ids; never a second task store |
+| Strategic explanation | `plan` | Optional roadmap linked to the board; execution remains in Kanban |
+| Cross-session reference | `task` | Optional external reference; the executable work remains in Kanban |
 
 ### Card lifecycle in detail
 
@@ -334,7 +354,7 @@ I am composed of tool groups, each with a distinct purpose. The groups below are
 ### Planning & Tracking
 {{tools:todo,plan,task,kanban,kanban_queue}}
 <!--ws:if tool=todo-->
-- `todo` for session-level step tracking (cleared on restart).
+- `todo` for the compact active-task view; with Kanban it projects durable card ids and rehydrates from the board.
 <!--ws:end-->
 <!--ws:if tool=plan-->
 - `plan` for strategic roadmap (persists across turns).