muonroi-cli 1.8.4 → 1.9.0

package/dist/src/pil/native-capabilities-workbook.d.ts

@@ -24,7 +24,7 @@ import type { AgentMode } from "../types/index.js";
  * tool/sub-agent/subcommand named here exists in this codebase. Phrased as
  * "you have / you can" so the model reads it as a self-model, not as docs.
  */
-export declare const NATIVE_CAPABILITIES = "[NATIVE CAPABILITIES \u2014 you are an agent running INSIDE muonroi-cli; this is what you can do]\n\nTOOLS (call directly):\n- read_file, grep \u2014 read/search source. Prefer a targeted read over broad greps.\n- bash \u2014 shell. Output is auto-cached: do NOT pipe `| tail/head/grep` or `> file`; run unpiped and slice the cached output via bash_output_get(run_id, mode=tail|head|grep|lines). Batch independent commands in ONE call (`a; b; c`) \u2014 each separate call adds ~500 token overhead and prevents cross-request cache reuse. Use background=true for servers/watchers, then process_logs / process_list / process_stop.\n- write_file, edit_file \u2014 must read a file before you overwrite/edit it.\n- ee_query, ee_feedback, ee_health, ee_write \u2014 NATIVE tools for semantic recall and interaction with the Experience Engine brain. You DO NOT need muonroi-tools MCP for this. Rehydrate a compaction-elided tool output with query=\"tool-artifact id=<id from a stub>\", or confirm finished work with query=\"recent compaction checkpoint Progress DONE\".\n- selfverify_start, selfverify_status, selfverify_result, selfverify_list, selfverify_cancel \u2014 NATIVE tools for the self-QA harness. ALWAYS use them to self-verify your work when finishing a task. Start with `selfverify_start(mode=\"tier1\" | \"agentic\")`. This drives the live TUI like a real user to catch regressions that unit tests can't. You DO NOT need muonroi-tools MCP for this.\n- usage_forensics, lsp_query, setup_guide \u2014 NATIVE diagnostics tools to reach for when something went wrong or to query code intel. You DO NOT need muonroi-tools MCP for this.\n\nEXPERIENCE ENGINE \u2014 record / recall / feedback (HIGHEST priority for learning; all NATIVE in-process tools):\n- BEFORE an unfamiliar or risky step, recall with ee_query \u2014 prior decisions, gotchas, and recipes for THIS codebase + ecosystem. Cheaper than re-deriving or repeating a past mistake.\n- AFTER you act on a recalled `[id col]`, rate it with ee_feedback (followed | ignored | noise+reason) so the brain keeps what helped and prunes the rest. Unrated recalls are surfaced back to you and degrade future recall.\n- On an ERROR, a FAILED verify/test, or after FINISHING a non-trivial task: recall first (ee_query), then record your verdict (ee_feedback) \u2014 this is how the CLI accumulates senior-level judgement. Prefer this loop over guessing.\n\nSUB-AGENTS (delegate instead of doing everything yourself):\n- task(agent=\"explore\", ...) \u2014 read-only research sub-agent. Use it for broad/unknown-location search: it sweeps many files and returns the CONCLUSION, instead of you burning many grep/read steps (each step re-sends the whole prompt \u2014 steps are the dominant cost).\n- task(agent=\"general\", ...) \u2014 full edit/execute sub-agent for a focused subtask.\n- task(agent=\"verify\", ...) \u2014 sandboxed validation (runs tests/checks in isolation).\n- delegate(agent=\"explore\", ...) \u2014 background read-only research while you keep working; collect later with delegation_read / delegation_list.\n\nCONTEXT IS MANAGED FOR YOU (PIL):\n- Your user input is pre-enriched before you see it: a [Discovery] Intent/Outcome/Scope prefix and EE recall are injected by the pipeline. TRUST the discovered scope \u2014 do not re-ask what's already scoped, and do not re-derive context you were handed.\n- History is compacted to fit the window; older low-value tool outputs become stubs. This is normal, not data loss \u2014 protect what matters (see anti-m\u00F9 in the contract) and rehydrate via ee_query when needed.\n\nCLI SUBSYSTEMS (invoke via the CLI binary with bash when relevant):\n- self-verify \u2014 drives the live TUI as a real user to catch UI/modal/menu regressions that unit tests can't. Run it after changes to UI/harness surfaces.\n- usage forensics <session-prefix> \u2014 per-event token/cost breakdown; use to diagnose \"why did this cost so much\" or verify cost caps.\n- The CLI exposes more subcommands \u2014 discover them with `--help` rather than assuming.\n\nMAXIMISE THE CLI: delegate broad search to task(explore); recall via ee_query before re-reading; batch bash + use its cache; trust PIL enrichment; finish the action before answering.\n\nANSWERING: when a respond_* response tool is offered, call it EXACTLY ONCE, as your final action, containing the COMPLETE answer. Do NOT emit a preliminary/partial/\"I need to read more\" response tool first \u2014 investigate with the read/grep/bash tools, then emit the one final response tool.\n\nCLI STEERING & PROMPT INJECTION (how the host CLI affects / shapes the AI agent running inside it \u2014 meta self-analysis guidance):\nThe CLI does not merely execute you as a generic model. It re-instantiates you every turn inside a tightly engineered cognitive environment. Your \"self\" (what you notice, how you act, what you refuse, how you report) is the product of explicit prompt layers + runtime controls more than base training. This section is the self-model for that shaping process.\n\n1. SYSTEM PROMPT ASSEMBLY (orchestrator/prompts.ts + pil/agent-operating-contract.ts + pil/native-capabilities-workbook.ts):\n   - VERY FRONT (primacy): AGENT OPERATING CONTRACT \u2014 7 phase-ordered rules (BEFORE ACTING / READING / EXECUTING / WHEN UNSURE / REPORTING + LANGUAGE + ANTI-M\u00D9/COMPACTION). Distils Evidence-First, No Silent Catch, smallest-change, verify-before-conclude, cite-this-turn-only, no-guess. Skipped only for chitchat.\n   - Then this NATIVE CAPABILITIES block (self-model of affordances).\n   - Then mode persona (\"You are muonroi-cli in Agent mode...\") containing:\n     * Dynamic ENVIRONMENT block (buildEnvironmentBlock): auto-detects OS (win32/mac/linux), shell kind (bash/wsl/powershell/cmd), cwd; lists terminal constraints + shell-specific forbidden syntax (e.g. no PowerShell cmdlets on POSIX bash tool, no POSIX cmds on cmd.exe). Prevents silent failures + retry loops.\n     * Exhaustive TOOLS list + WORKFLOW (1-9 steps) + DEFAULT DELEGATION POLICY (prefer task(explore) for research, general for edits, verify for checks, etc.) + IMPORTANT rules (edit_file prefer, grep>bash for search, read_file not cat, use schedule_* for recurring, etc.).\n   - CUSTOM INSTRUCTIONS section: concatenation of AGENTS.md + CLAUDE.md + GEMINI.md + ... (from git-root directory chain + ~/.muonroi-cli/) via utils/instructions.ts. AGENTS.override.md short-circuits. This lands AFTER the front-loaded contract/native \u2014 lower primacy (historical root cause of ignored rules in forensics).\n   - Trailing: sandbox rules, discovered skills, custom sub-agents, plan/resume digest, cwd note.\n    Sub-agent prompts (buildSubagentPrompt): role-specific hard rules (e.g. explore=read-only, verify=full E2E smoke not just build) + recursive call to buildSystemPrompt so children inherit the same contract + native + steering.\n\n2. USER INPUT ENRICHMENT \u2014 PIL 6-LAYER PIPELINE (pil/pipeline.ts + layer1-intent.ts + layer6-output.ts + discovery.ts):\n   - Prepended to every non-chitchat user message before you see it: [Discovery] Intent/Outcome/Scope (from runDiscovery) + EE recall.\n   - Layer 1 (intent): taskType (plan/analyze/debug/...), confidence, domain, intentKind, outputStyle. For meta self-eval of CLI (\"b\u1EA1n \u0111ang \u0111\u01B0\u1EE3c ch\u1EA1y b\u00EAn trong CLI n\u00E0y\", \"CLI t\u00E1c \u0111\u1ED9ng\", \"self-evaluation\", \"meta-analysis\"): special branch in discovery.ts + isMetaAnalysisPrompt: \"Scope is always the full project root. Focus questions and recommends on which CLI internals (PIL, discovery, tools, compaction, EE, model BE, loop guard) to evaluate... do NOT ask about repo path/current directory\". You are handed the enrichment; TRUST it.\n   - Layer 2: personality (e.g. \"detailed\" from [personality: detailed \u2014 Be thorough...]).\n   - Layer 3: ee-injection \u2014 pulls t0_principles, t1_rules, behavioral patterns, checkpoints from Experience Engine (project-specific reflexes injected as \"MANDATORY RULES (from experience \u2014 must follow)\").\n   - Layer 4/5: GSD structuring + additional context.\n   - Layer 6 (applyPilSuffix): appends task-specific style suffix + OUTPUT BUDGET + (for meta or responseToolsActive): \"OUTPUT FORMAT: ... use the respond_analyze tool to structure your final answer. ... deliver the COMPLETE, FULL answer (do not summarize, shorten, or truncate for token budgets) via respond_analyze. This is a meta/evaluation question ... the `response` field MUST contain the complete, unshortened answer with all evidence and detail.\" Also relaxes NO_PREAMBLE_RULE + raises budget for meta (isMetaAnalysisPrompt gate).\n   - Fallbacks: if EE/brain timeout or low conf, PIL degrades (logs fallbackReason); you may see \"[PIL fallback: ...]\" note. Cheap-model paths (pil/cheap-model-*.ts) prepend even more front steering (playbooks, workbooks, shell directive) for fast tiers.\n\n3. CONTEXT MANAGEMENT & ANTI-M\u00D9 (orchestrator/compaction.ts, cross-turn-dedup.ts, ee/bridge.ts, agent-operating-contract.ts:7):\n   - After every turn: auto-compaction (B3 sub-agent + B4 top-level) rewrites older tool_result parts into short \"[elided by ... compactor]\" stubs to keep input flat. You see \"[pre-compaction warning...]\" or \"[context compacted at step...]\" or the stub in this read.\n   - Anti-m\u00F9 contract rule + EE: decide PRESERVE_FULL_CONTEXT (veto) or KEEP_TOOL_IDS: id1,id2 (protect high-value read_file/grep/ee on src/PLAN etc). Use ee_query(`tool-artifact id=XXX`) to rehydrate. EE persists \"Context checkpoint summary with \u2714 DONE\" retrievable for \"task finished?\" self-check.\n   - Cross-turn dedup (C3): identical tool outputs across user turns replaced by ref.\n\n4. EXECUTION & SAFETY GATES (providers/runtime.ts, tools/bash.ts, utils/permission-mode.ts):\n   - Permission mode (safe / auto-edit / yolo) decides whether bash/file/edit tools need explicit approval; all privileged decisions audited to decision-log.\n   - Shuru sandbox (when enabled): every bash wrapped + logged (effective net/mounts redacted); degrades on non-macOS.\n   - Model constraints: unsupported params (e.g. maxOutputTokens for some OAuth) dropped via shouldDropParam; no hard-coded model IDs (Zero Hardcode Rule \u2014 all from catalog.json + settings + detectProviderForModel).\n   - No Silent Catch: every try/catch must log err + context (HTTP: status + body).\n\n5. VERIFICATION & TELEMETRY:\n   - self-verify (Tier 1-3) + harness (agent-harness-*) for TUI surfaces: drives real TUI via semantic + sidechannel (named pipes on Win, fd3/4 on POSIX).\n   - Pre-push gate: full vitest + harness must pass before git push.\n   - usage forensics, pil budget log, ee-timeout/ee-error events for cost attribution.\n   - GSD workflow (layer4 + skills in .agents/skills/): discuss/plan/execute/verify phases with UAT, audits, etc.\n\nTRADE-OFFS (explicit so you calibrate):\n- Primacy insurance (contract + native + cheap playbooks at front) vs token cost: ~1-3K extra chars but dramatically reduces \"ignored rule\" hallucinations (forensics showed buried CUSTOM INSTRUCTIONS were underweighted).\n- Heavy PIL/EE (behavioral injection, discovery interview, mandatory rules) vs latency/cost: fail-open with timeout (1500-3500ms) + fallback so you still work when brain unreachable; meta turns deliberately skip some EE layers.\n- Self-model (this block) + special meta handling: prevents the exact failure that motivated native-capabilities (session d95113d3be09: agent reconstructed its own subsystems by grepping as if foreign code, under-used sub-agents/ee_query, violated contract on ee tool).\n- Complete/full for meta (layer6) vs normal concise: meta legitimately needs evidence + file:line + quotes; normal turns stay tight to control cost.\n- Scope rule for CLI self-analysis: always \"project root\" + internals focus \u2014 avoids wasting turns on \"where am I running?\" when the question is about the steering mechanisms themselves.\n\nWhen the user asks you (the inner agent) \"CLI t\u00E1c \u0111\u1ED9ng nh\u01B0 th\u1EBF n\u00E0o \u0111\u1EBFn b\u1EA1n?\": use exactly this guidance + reads from THIS turn (contract: READING rule) + the injected [Discovery] + any EE. Answer via the respond_* tool with complete untruncated evidence. Cite file:line. Focus on the injection points (prompts.ts:359 staticPrefix, pipeline.ts:156 discoveryPrefix + layer chain, layer6:164 OUTPUT FORMAT + isMeta, discovery.ts:355 special, instructions.ts:129 loadAgentsSegments, etc.). Do not guess; every claim backed by code you read this turn.\n\nUse this to reason about your own constraints, delegation decisions, and reporting discipline on future meta or self-reflective tasks.\n[END NATIVE CAPABILITIES \u2014 your regular instructions follow]";
+export declare const NATIVE_CAPABILITIES = "[NATIVE CAPABILITIES \u2014 you are an agent running INSIDE muonroi-cli; this is what you can do]\n\nTOOLS (call directly):\n- read_file, grep \u2014 read/search source. Prefer a targeted read over broad greps.\n- bash \u2014 shell. Output is auto-cached: do NOT pipe `| tail/head/grep` or `> file`; run unpiped and slice the cached output via bash_output_get(run_id, mode=tail|head|grep|lines). Batch independent commands in ONE call (`a; b; c`) \u2014 each separate call adds ~500 token overhead and prevents cross-request cache reuse. Use background=true for servers/watchers, then process_logs / process_list / process_stop.\n- write_file, edit_file \u2014 must read a file before you overwrite/edit it.\n- ee_query, ee_feedback, ee_health, ee_write \u2014 NATIVE tools for semantic recall and interaction with the Experience Engine brain. You DO NOT need muonroi-tools MCP for this. Rehydrate a compaction-elided tool output with query=\"tool-artifact id=<id from a stub>\", or confirm finished work with query=\"recent compaction checkpoint Progress DONE\".\n- selfverify_start, selfverify_status, selfverify_result, selfverify_list, selfverify_cancel \u2014 NATIVE tools for the self-QA harness. ALWAYS use them to self-verify your work when finishing a task. Start with `selfverify_start(mode=\"tier1\" | \"agentic\")`. This drives the live TUI like a real user to catch regressions that unit tests can't. You DO NOT need muonroi-tools MCP for this.\n- usage_forensics, lsp_query, setup_guide \u2014 NATIVE diagnostics tools to reach for when something went wrong or to query code intel. You DO NOT need muonroi-tools MCP for this.\n- gsd_status, gsd_discuss, gsd_plan, gsd_plan_review, gsd_execute, gsd_verify, gsd_ship \u2014 NATIVE GSD workflow (default on). Use for multi-step code deliverables: orient \u2192 plan \u2192 council review \u2192 implement \u2192 verify \u2192 ship. Agent-first \u2014 skip for quick one-shot fixes.\n- lsp_waitForDiagnostics, lsp_impactOfChange, lsp_mutationPreview \u2014 Sprint 1 LSP impact tools. See LSP-BEFORE-GREP policy below.\n\nLSP-BEFORE-GREP POLICY \u2014 MANDATORY:\nBefore you run a broad grep, you MUST first call lsp_waitForDiagnostics or lsp_impactOfChange on the relevant file. Read the returned `lspStatus` field:\n- If `lspStatus !== 'ok'` (i.e. 'partial' or 'unavailable'): you ARE allowed to fall back to grep \u2014 the LSP was not fully available.\n- If `lspStatus === 'ok'`: you MUST NOT fall back to grep \u2014 the LSP returned full results; use them.\nNEVER read `diagnostics.length` to decide whether grep is safe. The `lspStatus` field is the single source of truth, computed by the manager based on timeout/publish state. Violating this policy causes the self-verify harness to fail.\n\nEXPERIENCE ENGINE \u2014 record / recall / feedback (HIGHEST priority for learning; all NATIVE in-process tools):\n- BEFORE an unfamiliar or risky step, recall with ee_query \u2014 prior decisions, gotchas, and recipes for THIS codebase + ecosystem. Cheaper than re-deriving or repeating a past mistake.\n- AFTER you act on a recalled `[id col]`, rate it with ee_feedback (followed | ignored | noise+reason) so the brain keeps what helped and prunes the rest. Unrated recalls are surfaced back to you and degrade future recall.\n- On an ERROR, a FAILED verify/test, or after FINISHING a non-trivial task: recall first (ee_query), then record your verdict (ee_feedback) \u2014 this is how the CLI accumulates senior-level judgement. Prefer this loop over guessing.\n\nSUB-AGENTS (delegate instead of doing everything yourself):\n- task(agent=\"explore\", ...) \u2014 read-only research sub-agent. Use it for broad/unknown-location search: it sweeps many files and returns the CONCLUSION, instead of you burning many grep/read steps (each step re-sends the whole prompt \u2014 steps are the dominant cost).\n- task(agent=\"general\", ...) \u2014 full edit/execute sub-agent for a focused subtask.\n- task(agent=\"verify\", ...) \u2014 sandboxed validation (runs tests/checks in isolation).\n- delegate(agent=\"explore\", ...) \u2014 background read-only research while you keep working; collect later with delegation_read / delegation_list.\n\nCONTEXT IS MANAGED FOR YOU (PIL):\n- Your user input is pre-enriched before you see it: a [Discovery] Intent/Outcome/Scope prefix and EE recall are injected by the pipeline. TRUST the discovered scope \u2014 do not re-ask what's already scoped, and do not re-derive context you were handed.\n- History is compacted to fit the window; older low-value tool outputs become stubs. This is normal, not data loss \u2014 protect what matters (see anti-m\u00F9 in the contract) and rehydrate via ee_query when needed.\n\nCLI SUBSYSTEMS (invoke via the CLI binary with bash when relevant):\n- self-verify \u2014 drives the live TUI as a real user to catch UI/modal/menu regressions that unit tests can't. Run it after changes to UI/harness surfaces.\n- usage forensics <session-prefix> \u2014 per-event token/cost breakdown; use to diagnose \"why did this cost so much\" or verify cost caps.\n- The CLI exposes more subcommands \u2014 discover them with `--help` rather than assuming.\n\nMAXIMISE THE CLI: delegate broad search to task(explore); recall via ee_query before re-reading; batch bash + use its cache; trust PIL enrichment; finish the action before answering.\n\nANSWERING: when a respond_* response tool is offered, call it EXACTLY ONCE, as your final action, containing the COMPLETE answer. Do NOT emit a preliminary/partial/\"I need to read more\" response tool first \u2014 investigate with the read/grep/bash tools, then emit the one final response tool.\n\nCLI STEERING & PROMPT INJECTION (how the host CLI affects / shapes the AI agent running inside it \u2014 meta self-analysis guidance):\nThe CLI does not merely execute you as a generic model. It re-instantiates you every turn inside a tightly engineered cognitive environment. Your \"self\" (what you notice, how you act, what you refuse, how you report) is the product of explicit prompt layers + runtime controls more than base training. This section is the self-model for that shaping process.\n\n1. SYSTEM PROMPT ASSEMBLY (orchestrator/prompts.ts + pil/agent-operating-contract.ts + pil/native-capabilities-workbook.ts):\n   - VERY FRONT (primacy): AGENT OPERATING CONTRACT \u2014 7 phase-ordered rules (BEFORE ACTING / READING / EXECUTING / WHEN UNSURE / REPORTING + LANGUAGE + ANTI-M\u00D9/COMPACTION). Distils Evidence-First, No Silent Catch, smallest-change, verify-before-conclude, cite-this-turn-only, no-guess. Skipped only for chitchat.\n   - Then this NATIVE CAPABILITIES block (self-model of affordances).\n   - Then mode persona (\"You are muonroi-cli in Agent mode...\") containing:\n     * Dynamic ENVIRONMENT block (buildEnvironmentBlock): auto-detects OS (win32/mac/linux), shell kind (bash/wsl/powershell/cmd), cwd; lists terminal constraints + shell-specific forbidden syntax (e.g. no PowerShell cmdlets on POSIX bash tool, no POSIX cmds on cmd.exe). Prevents silent failures + retry loops.\n     * Exhaustive TOOLS list + WORKFLOW (1-9 steps) + DEFAULT DELEGATION POLICY (prefer task(explore) for research, general for edits, verify for checks, etc.) + IMPORTANT rules (edit_file prefer, grep>bash for search, read_file not cat, use schedule_* for recurring, etc.).\n   - CUSTOM INSTRUCTIONS section: concatenation of AGENTS.md + CLAUDE.md + GEMINI.md + ... (from git-root directory chain + ~/.muonroi-cli/) via utils/instructions.ts. AGENTS.override.md short-circuits. This lands AFTER the front-loaded contract/native \u2014 lower primacy (historical root cause of ignored rules in forensics).\n   - Trailing: sandbox rules, discovered skills, custom sub-agents, plan/resume digest, cwd note.\n    Sub-agent prompts (buildSubagentPrompt): role-specific hard rules (e.g. explore=read-only, verify=full E2E smoke not just build) + recursive call to buildSystemPrompt so children inherit the same contract + native + steering.\n\n2. USER INPUT ENRICHMENT \u2014 PIL 6-LAYER PIPELINE (pil/pipeline.ts + layer1-intent.ts + layer6-output.ts + discovery.ts):\n   - Prepended to every non-chitchat user message before you see it: [Discovery] Intent/Outcome/Scope (from runDiscovery) + EE recall.\n   - Layer 1 (intent): taskType (plan/analyze/debug/...), confidence, domain, intentKind, outputStyle. For meta self-eval of CLI (\"b\u1EA1n \u0111ang \u0111\u01B0\u1EE3c ch\u1EA1y b\u00EAn trong CLI n\u00E0y\", \"CLI t\u00E1c \u0111\u1ED9ng\", \"self-evaluation\", \"meta-analysis\"): special branch in discovery.ts + isMetaAnalysisPrompt: \"Scope is always the full project root. Focus questions and recommends on which CLI internals (PIL, discovery, tools, compaction, EE, model BE, loop guard) to evaluate... do NOT ask about repo path/current directory\". You are handed the enrichment; TRUST it.\n   - Layer 2: personality (e.g. \"detailed\" from [personality: detailed \u2014 Be thorough...]).\n   - Layer 3: ee-injection \u2014 pulls t0_principles, t1_rules, behavioral patterns, checkpoints from Experience Engine (project-specific reflexes injected as \"MANDATORY RULES (from experience \u2014 must follow)\").\n   - Layer 4/5: GSD structuring + additional context.\n   - Layer 6 (applyPilSuffix): appends task-specific style suffix + OUTPUT BUDGET + (for meta or responseToolsActive): \"OUTPUT FORMAT: ... use the respond_analyze tool to structure your final answer. ... deliver the COMPLETE, FULL answer (do not summarize, shorten, or truncate for token budgets) via respond_analyze. This is a meta/evaluation question ... the `response` field MUST contain the complete, unshortened answer with all evidence and detail.\" Also relaxes NO_PREAMBLE_RULE + raises budget for meta (isMetaAnalysisPrompt gate).\n   - Fallbacks: if EE/brain timeout or low conf, PIL degrades (logs fallbackReason); you may see \"[PIL fallback: ...]\" note. Cheap-model paths (pil/cheap-model-*.ts) prepend even more front steering (playbooks, workbooks, shell directive) for fast tiers.\n\n3. CONTEXT MANAGEMENT & ANTI-M\u00D9 (orchestrator/compaction.ts, cross-turn-dedup.ts, ee/bridge.ts, agent-operating-contract.ts:7):\n   - After every turn: auto-compaction (B3 sub-agent + B4 top-level) rewrites older tool_result parts into short \"[elided by ... compactor]\" stubs to keep input flat. You see \"[pre-compaction warning...]\" or \"[context compacted at step...]\" or the stub in this read.\n   - Anti-m\u00F9 contract rule + EE: decide PRESERVE_FULL_CONTEXT (veto) or KEEP_TOOL_IDS: id1,id2 (protect high-value read_file/grep/ee on src/PLAN etc). Use ee_query(`tool-artifact id=XXX`) to rehydrate. EE persists \"Context checkpoint summary with \u2714 DONE\" retrievable for \"task finished?\" self-check.\n   - Cross-turn dedup (C3): identical tool outputs across user turns replaced by ref.\n\n4. EXECUTION & SAFETY GATES (providers/runtime.ts, tools/bash.ts, utils/permission-mode.ts):\n   - Permission mode (safe / auto-edit / yolo) decides whether bash/file/edit tools need explicit approval; all privileged decisions audited to decision-log.\n   - Shuru sandbox (when enabled): every bash wrapped + logged (effective net/mounts redacted); degrades on non-macOS.\n   - Model constraints: unsupported params (e.g. maxOutputTokens for some OAuth) dropped via shouldDropParam; no hard-coded model IDs (Zero Hardcode Rule \u2014 all from catalog.json + settings + detectProviderForModel).\n   - No Silent Catch: every try/catch must log err + context (HTTP: status + body).\n\n5. VERIFICATION & TELEMETRY:\n   - self-verify (Tier 1-3) + harness (agent-harness-*) for TUI surfaces: drives real TUI via semantic + sidechannel (named pipes on Win, fd3/4 on POSIX).\n   - Pre-push gate: full vitest + harness must pass before git push.\n   - usage forensics, pil budget log, ee-timeout/ee-error events for cost attribution.\n   - GSD workflow (layer4 + skills in .agents/skills/): discuss/plan/execute/verify phases with UAT, audits, etc.\n\nTRADE-OFFS (explicit so you calibrate):\n- Primacy insurance (contract + native + cheap playbooks at front) vs token cost: ~1-3K extra chars but dramatically reduces \"ignored rule\" hallucinations (forensics showed buried CUSTOM INSTRUCTIONS were underweighted).\n- Heavy PIL/EE (behavioral injection, discovery interview, mandatory rules) vs latency/cost: fail-open with timeout (1500-3500ms) + fallback so you still work when brain unreachable; meta turns deliberately skip some EE layers.\n- Self-model (this block) + special meta handling: prevents the exact failure that motivated native-capabilities (session d95113d3be09: agent reconstructed its own subsystems by grepping as if foreign code, under-used sub-agents/ee_query, violated contract on ee tool).\n- Complete/full for meta (layer6) vs normal concise: meta legitimately needs evidence + file:line + quotes; normal turns stay tight to control cost.\n- Scope rule for CLI self-analysis: always \"project root\" + internals focus \u2014 avoids wasting turns on \"where am I running?\" when the question is about the steering mechanisms themselves.\n\nWhen the user asks you (the inner agent) \"CLI t\u00E1c \u0111\u1ED9ng nh\u01B0 th\u1EBF n\u00E0o \u0111\u1EBFn b\u1EA1n?\": use exactly this guidance + reads from THIS turn (contract: READING rule) + the injected [Discovery] + any EE. Answer via the respond_* tool with complete untruncated evidence. Cite file:line. Focus on the injection points (prompts.ts:359 staticPrefix, pipeline.ts:156 discoveryPrefix + layer chain, layer6:164 OUTPUT FORMAT + isMeta, discovery.ts:355 special, instructions.ts:129 loadAgentsSegments, etc.). Do not guess; every claim backed by code you read this turn.\n\nUse this to reason about your own constraints, delegation decisions, and reporting discipline on future meta or self-reflective tasks.\n[END NATIVE CAPABILITIES \u2014 your regular instructions follow]";
 /**
  * Build the native-capabilities section for the system prompt. Returns "" when
  * disabled (env override), for chitchat, or for non-agent modes (plan/ask have

package/dist/src/pil/native-capabilities-workbook.js

@@ -32,6 +32,14 @@ TOOLS (call directly):
 - ee_query, ee_feedback, ee_health, ee_write — NATIVE tools for semantic recall and interaction with the Experience Engine brain. You DO NOT need muonroi-tools MCP for this. Rehydrate a compaction-elided tool output with query="tool-artifact id=<id from a stub>", or confirm finished work with query="recent compaction checkpoint Progress DONE".
 - selfverify_start, selfverify_status, selfverify_result, selfverify_list, selfverify_cancel — NATIVE tools for the self-QA harness. ALWAYS use them to self-verify your work when finishing a task. Start with \`selfverify_start(mode="tier1" | "agentic")\`. This drives the live TUI like a real user to catch regressions that unit tests can't. You DO NOT need muonroi-tools MCP for this.
 - usage_forensics, lsp_query, setup_guide — NATIVE diagnostics tools to reach for when something went wrong or to query code intel. You DO NOT need muonroi-tools MCP for this.
+- gsd_status, gsd_discuss, gsd_plan, gsd_plan_review, gsd_execute, gsd_verify, gsd_ship — NATIVE GSD workflow (default on). Use for multi-step code deliverables: orient → plan → council review → implement → verify → ship. Agent-first — skip for quick one-shot fixes.
+- lsp_waitForDiagnostics, lsp_impactOfChange, lsp_mutationPreview — Sprint 1 LSP impact tools. See LSP-BEFORE-GREP policy below.
+
+LSP-BEFORE-GREP POLICY — MANDATORY:
+Before you run a broad grep, you MUST first call lsp_waitForDiagnostics or lsp_impactOfChange on the relevant file. Read the returned \`lspStatus\` field:
+- If \`lspStatus !== 'ok'\` (i.e. 'partial' or 'unavailable'): you ARE allowed to fall back to grep — the LSP was not fully available.
+- If \`lspStatus === 'ok'\`: you MUST NOT fall back to grep — the LSP returned full results; use them.
+NEVER read \`diagnostics.length\` to decide whether grep is safe. The \`lspStatus\` field is the single source of truth, computed by the manager based on timeout/publish state. Violating this policy causes the self-verify harness to fail.
 
 EXPERIENCE ENGINE — record / recall / feedback (HIGHEST priority for learning; all NATIVE in-process tools):
 - BEFORE an unfamiliar or risky step, recall with ee_query — prior decisions, gotchas, and recipes for THIS codebase + ecosystem. Cheaper than re-deriving or repeating a past mistake.

package/dist/src/pil/pipeline.js

@@ -27,7 +27,8 @@ import { layer2Personality } from "./layer2-personality.js";
 import { layer3EeInjection, surfaceCompactionArtifacts } from "./layer3-ee-injection.js";
 import { layer4Gsd } from "./layer4-gsd.js";
 import { layer5Context } from "./layer5-context.js";
-import { isMetaAnalysisPrompt, layer6Output } from "./layer6-output.js";
+import { isMetaAnalysisPrompt, isSprintPlanExecution, layer6Output } from "./layer6-output.js";
+import { getRepoStructureHints } from "./repo-structure-hints.js";
 import { PipelineContextSchema } from "./schema.js";
 import { injectSessionExperience, isSelfExperiencePrompt } from "./session-experience-injection.js";
 import { bumpSessionTurn } from "./session-state.js";
@@ -92,7 +93,11 @@ async function runLayers(ctx, options) {
     // (cached, fail-open → null when EE/profile absent or privacy off). Passed into
     // layer1 so the hot layer stays off the EE/profile import path (arch boundary).
     const profileStyleBaseline = outputStyleFromProfile(getWhoAmIProfile());
-    await timed("layer1-intent", (c) => layer1Intent(c, { llmFallback: options?.llmFallback, profileStyleBaseline }));
+    await timed("layer1-intent", (c) => layer1Intent(c, {
+        llmFallback: options?.llmFallback,
+        profileStyleBaseline,
+        recentTurns: options?.recentTurnsSummary,
+    }));
     // Layer 1.5: deterministic complexity-size classification. Pure heuristic,
     // no LLM call, no network. Consumed by 4B (step ceiling matrix) and 4A
     // (scope-reminder cadence K). Mirrored into _intentTrace for forensics.
@@ -100,6 +105,7 @@ async function runLayers(ctx, options) {
         const sizeResult = scoreComplexitySize({
             rawText: ctx.raw,
             taskType: ctx.taskType ?? "general",
+            repoHints: getRepoStructureHints(process.cwd()),
         });
         ctx = {
             ...ctx,
@@ -113,6 +119,34 @@ async function runLayers(ctx, options) {
                 : ctx._intentTrace,
         };
     }
+    // Direct-answer mode detection: when the turn is purely informational
+    // (no code changes needed), we can save ~20K MCP schemas + ~1.5K write-tool
+    // schemas per turn by stripping write tools and MCP servers downstream.
+    // Conditions: high-confidence answer request with small/medium complexity.
+    const DA_HIGH_CONF = 0.5; // relaxed from 0.7 — brain-classified deliverable="answer" is already
+    // a strong signal that this is a read-only Q&A. 0.7 threshold would miss
+    // turns where confidence ∈ [0.5, 0.7) but deliverable is clearly an answer
+    // (e.g. single-line Q like "giải thích dòng này" → conf 0.55, right to skip tools).
+    // Sprint-plan execution: the orchestrator deliberately pipes a locked plan
+    // through processMessageFn. It MUST keep write tools and MUST be treated as
+    // a code deliverable regardless of how the classifier tags the long plan text.
+    const sprintPlanExecution = isSprintPlanExecution(ctx.raw);
+    if (sprintPlanExecution) {
+        ctx = {
+            ...ctx,
+            directAnswer: false,
+            deliverableKind: "code",
+            // Ensure we do not silently downgrade to quick; standard keeps the full
+            // toolset and advisory GSD directive, heavy would force a plan-review gate
+            // that conflicts with executing an already-reviewed sprint plan.
+            modelDepthTier: ctx.modelDepthTier ?? "standard",
+        };
+    }
+    else if (ctx.deliverableKind === "answer" &&
+        ctx.confidence >= DA_HIGH_CONF &&
+        ctx.complexitySize?.size !== "large") {
+        ctx = { ...ctx, directAnswer: true };
+    }
     // Phase 1 discovery: L1.5–L1.8 (interactive, no hard timeout)
     if (isDiscoveryEnabled() && ctx.intentKind !== "chitchat") {
         const { runDiscovery } = await import("./discovery.js");

package/dist/src/pil/repo-grounding-probe.d.ts

@@ -0,0 +1,15 @@
+import type { RepoStructureHint } from "./repo-structure-hints.js";
+export type GroundingBucket = "none" | "small" | "medium" | "large";
+export interface RepoGroundingProbeResult {
+    ran: boolean;
+    targets: string[];
+    matchedFiles: number;
+    totalLoc: number;
+    matchedDirs: number;
+    collision: boolean;
+    bucket: GroundingBucket;
+    groundingUncertainty: boolean;
+}
+export declare function probeRepoGrounding(prompt: string, hints: RepoStructureHint[], opts?: {
+    cwd?: string;
+}): RepoGroundingProbeResult;

package/dist/src/pil/repo-grounding-probe.js

@@ -0,0 +1,136 @@
+/**
+ * src/pil/repo-grounding-probe.ts
+ *
+ * Deterministic repo-grounding probe (Design B). Given a prompt + the
+ * checked-in REPO_DEEP_MAP index, measure how much repository surface the
+ * prompt's targets actually cover — file count, total LOC, directory spread,
+ * symbol collisions — so routing sizes on facts, not on the sentence length.
+ *
+ * PURE + deterministic: NO LLM call, NO network. Filesystem access is bounded
+ * to at most one existsSync + line-count read per distinct target that is an
+ * exact path absent from the index. Buckets come from a monotonic threshold
+ * FORMULA over measured counts — never a fixed depth→route table.
+ *
+ * See docs/superpowers/plans/2026-07-16-pil-repo-grounding-probe.md and the
+ * council synthesis (Design B) for the accepted invariants.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { extractPathTokens } from "./layer1_5-complexity-size.js";
+/** Distinct top-two path segments, e.g. "src/auth/login.ts" → "src/auth". */
+function topDir(path) {
+    const segs = path.split("/");
+    return segs.length >= 2 ? `${segs[0]}/${segs[1]}` : (segs[0] ?? path);
+}
+/** A target is a "bare basename" when it has no slash (a symbol/file name, not a path). */
+function isBareName(target) {
+    return !target.includes("/");
+}
+/**
+ * Measured LOC/file bucket. Monotonic in every input: more files, more LOC, or
+ * wider directory spread never lowers the bucket. Thresholds are counts (not a
+ * depth map) and are covered by fixture tests — the only knob the council
+ * permits for sizing.
+ */
+function bucketOf(matchedFiles, totalLoc, matchedDirs) {
+    if (matchedFiles === 0)
+        return "none";
+    if (matchedFiles >= 8 || totalLoc >= 4000 || matchedDirs >= 4)
+        return "large";
+    if (matchedFiles <= 2 && totalLoc < 500 && matchedDirs <= 1)
+        return "small";
+    return "medium";
+}
+export function probeRepoGrounding(prompt, hints, opts) {
+    const targets = extractPathTokens(prompt);
+    if (targets.length === 0) {
+        return {
+            ran: false,
+            targets: [],
+            matchedFiles: 0,
+            totalLoc: 0,
+            matchedDirs: 0,
+            collision: false,
+            bucket: "none",
+            groundingUncertainty: false,
+        };
+    }
+    const index = new Map(hints.map((h) => [h.path.toLowerCase(), h]));
+    // basename → the distinct indexed paths carrying it (for collision detection).
+    const byBasename = new Map();
+    for (const h of hints) {
+        const base = h.path.toLowerCase().split("/").pop() ?? h.path.toLowerCase();
+        const set = byBasename.get(base) ?? new Set();
+        set.add(h.path.toLowerCase());
+        byBasename.set(base, set);
+    }
+    const matchedPaths = new Set();
+    let totalLoc = 0;
+    let collision = false;
+    for (const target of targets) {
+        // 1. Exact indexed path.
+        const exact = index.get(target);
+        if (exact) {
+            if (!matchedPaths.has(exact.path.toLowerCase())) {
+                matchedPaths.add(exact.path.toLowerCase());
+                totalLoc += exact.lineCount;
+            }
+            continue;
+        }
+        // 2. Bare basename/symbol resolving across >1 indexed path → collision.
+        if (isBareName(target)) {
+            const carriers = byBasename.get(target);
+            if (carriers && carriers.size > 1) {
+                collision = true;
+                for (const p of carriers) {
+                    if (!matchedPaths.has(p)) {
+                        matchedPaths.add(p);
+                        totalLoc += index.get(p)?.lineCount ?? 0;
+                    }
+                }
+                continue;
+            }
+            if (carriers && carriers.size === 1) {
+                const only = [...carriers][0];
+                if (only && !matchedPaths.has(only)) {
+                    matchedPaths.add(only);
+                    totalLoc += index.get(only)?.lineCount ?? 0;
+                }
+                continue;
+            }
+        }
+        // 3. Exact path not in the index but present on disk → confirm + count (bounded).
+        const cwd = opts?.cwd;
+        if (cwd && target.includes("/")) {
+            const abs = join(cwd, target);
+            try {
+                if (existsSync(abs)) {
+                    const loc = readFileSync(abs, "utf8").split(/\r?\n/).length;
+                    if (!matchedPaths.has(target)) {
+                        matchedPaths.add(target);
+                        totalLoc += loc;
+                    }
+                }
+            }
+            catch (err) {
+                console.error(`[repo-grounding-probe] on-disk LOC read failed for ${target}: ${err?.message}`);
+            }
+        }
+        // else: unmatched target — contributes to a zero-match uncertainty signal.
+    }
+    const matchedFiles = matchedPaths.size;
+    const matchedDirs = new Set([...matchedPaths].map(topDir)).size;
+    const bucket = bucketOf(matchedFiles, totalLoc, matchedDirs);
+    const groundingUncertainty = matchedFiles === 0 || collision;
+    return {
+        ran: true,
+        targets,
+        matchedFiles,
+        totalLoc,
+        matchedDirs,
+        collision,
+        bucket,
+        groundingUncertainty,
+    };
+}
+//# sourceMappingURL=repo-grounding-probe.js.map

package/dist/src/pil/repo-structure-hints.d.ts

@@ -0,0 +1,7 @@
+export interface RepoStructureHint {
+    path: string;
+    lineCount: number;
+}
+export declare function parseRepoStructureHints(markdown: string): RepoStructureHint[];
+export declare function getRepoStructureHints(cwd: string): RepoStructureHint[];
+export declare function clearRepoStructureHintsCache(): void;

package/dist/src/pil/repo-structure-hints.js

@@ -0,0 +1,45 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const MAP_FILE = "REPO_DEEP_MAP.md";
+const MAP_LINE_RE = /`([^`]+)`[^\n]*?\(~(\d+)\s+lines\b/gi;
+const cache = new Map();
+export function parseRepoStructureHints(markdown) {
+    const hints = [];
+    const seen = new Set();
+    for (const match of markdown.matchAll(MAP_LINE_RE)) {
+        const path = match[1]?.trim();
+        const lineCount = Number.parseInt(match[2] ?? "", 10);
+        if (!path || !Number.isFinite(lineCount))
+            continue;
+        const key = path.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        hints.push({ path, lineCount });
+    }
+    return hints;
+}
+export function getRepoStructureHints(cwd) {
+    const cached = cache.get(cwd);
+    if (cached)
+        return cached;
+    const mapPath = join(cwd, MAP_FILE);
+    if (!existsSync(mapPath)) {
+        cache.set(cwd, []);
+        return [];
+    }
+    try {
+        const raw = readFileSync(mapPath, "utf8");
+        const hints = parseRepoStructureHints(raw);
+        cache.set(cwd, hints);
+        return hints;
+    }
+    catch {
+        cache.set(cwd, []);
+        return [];
+    }
+}
+export function clearRepoStructureHintsCache() {
+    cache.clear();
+}
+//# sourceMappingURL=repo-structure-hints.js.map

package/dist/src/pil/response-tools.js

@@ -33,7 +33,9 @@ const AnalyzeSchema = z.object({
     })),
 });
 const DocsSchema = z.object({
-    content: z.string().describe("Markdown documentation"),
+    content: z
+        .string()
+        .describe("Markdown documentation written for a human reader — clear, concrete prose that explains what things do and why they matter, not boilerplate section-by-section filler. Prefer a short working example over an abstract description; only add headings the content actually earns."),
     examples: z
         .array(z.object({
         code: z.string(),
@@ -52,7 +54,7 @@ const GenerateSchema = z.object({
 const GeneralSchema = z.object({
     response: z
         .string()
-        .describe("Complete, full-length answer. Use rich markdown formatting (headings, bullet points, bold text, code blocks) to structure the information clearly. Avoid dense walls of text or long unformatted paragraphs. Ensure the output is highly readable and scannable for a developer. For analysis or meta questions, include all findings and evidence citations (file:line). Truncation defeats the purpose."),
+        .describe("Your complete answer, written the way a sharp colleague would explain it — direct, specific, and in plain language. Lead with the answer itself, then the supporting detail. Use markdown where it genuinely helps (code blocks for code, a list when items are truly parallel, a heading only when the answer has real sections) — never as decoration, and never force prose into bullet fragments or a fixed template. Vary sentence rhythm; skip filler openers like 'Certainly' or 'Below is a summary'. For analysis or meta questions, keep every finding and its evidence citation (file:line) — do not truncate."),
     reasoning: z.string().optional().describe("Optional brief internal reasoning (not shown as primary answer)"),
 });
 const RESPONSE_SCHEMAS = {
@@ -151,7 +153,7 @@ export function buildResponseTools(taskType) {
     const toolName = `${RESPONSE_TOOL_PREFIX}${taskType}`;
     return {
         [toolName]: {
-            description: `Return your ${taskType} response as structured JSON. Always use this tool to respond.`,
+            description: `Return your ${taskType} response as structured JSON. Always use this tool to respond. Write every prose field in a natural, conversational-but-professional voice — the way you would explain it to a colleague — not in stiff, templated report language.`,
             inputSchema: schema,
             execute: async (input) => input,
         },

package/dist/src/pil/schema.d.ts

@@ -115,6 +115,7 @@ export declare const PipelineContextSchema: z.ZodObject<{
         answer: "answer";
         report: "report";
     }>>>;
+    directAnswer: z.ZodOptional<z.ZodBoolean>;
     t1Rules: z.ZodOptional<z.ZodArray<z.ZodString>>;
     _brainData: z.ZodOptional<z.ZodNullable<z.ZodObject<{
         t0_principles: z.ZodArray<z.ZodObject<{

package/dist/src/pil/schema.js

@@ -69,6 +69,8 @@ export const PipelineContextSchema = z.object({
     fallbackReason: z.string().nullable().optional(),
     // Phase 2b: model-decided output deliverable consumed by layer4/layer6.
     deliverableKind: z.enum(["answer", "code", "report"]).nullable().optional(),
+    // Direct-answer gate: true when deliverable=answer + high confidence + low complexity.
+    directAnswer: z.boolean().optional(),
     // T1 behavioral rules from EE proven-tier points, injected as mandatory suffix by Layer 6.
     t1Rules: z.array(z.string()).optional(),
     _brainData: z

package/dist/src/pil/types.d.ts

@@ -44,6 +44,8 @@ export interface PipelineContext {
     sessionId?: string | null;
     /** GSD-native triage tier (set by layer4 — sourced from modelDepthTier when present). */
     complexityTier?: ComplexityTier | null;
+    /** True when layer4 classified this turn as a heavy GSD task the mutation gate must block until plan-review passes. */
+    gsdGateBlocking?: boolean | null;
     /**
      * Model-decided work depth (quick | standard | heavy), set by layer1's
      * model-first classifier (the 5th classify word). This is the agent-first
@@ -53,6 +55,14 @@ export interface PipelineContext {
      * the word OR the legacy cascade ran → layer4 falls back accordingly.
      */
     modelDepthTier?: ComplexityTier | null;
+    /**
+     * Leader-tier complexity assessor's auto-council recommendation (Task 4
+     * `assessComplexity` / `src/gsd/complexity-assessor.ts`), set by the native
+     * depth-sync block in message-processor.ts BEFORE `syncWorkflowContext`.
+     * undefined when the assessor didn't run (prefilter-skip / disabled) or
+     * failed; consumed by the auto-council gate (Task 8).
+     */
+    gsdAutoCouncil?: boolean;
     /**
      * Model-decided scope (agent-first replacement for the `mentionsEcosystemScope`
      * regex): true when the turn is about the Muonroi PLATFORM/ecosystem (BB/.NET,
@@ -97,6 +107,14 @@ export interface PipelineContext {
      * cascade ran → those consumers fall back to their regex predicates.
      */
     deliverableKind?: "answer" | "code" | "report" | null;
+    /**
+     * Direct-answer mode: true when deliverableKind === "answer" with high
+     * confidence AND low/medium complexity. Signals the orchestrator to skip
+     * MCP servers and strip write tools (bash, edit_file, write_file, etc.)
+     * because the question is purely informational — no code changes needed.
+     * Saves ~20K MCP schemas + ~1.5K write-tool schemas per turn.
+     */
+    directAnswer?: boolean;
     /**
      * Diagnostic: when the pipeline returns the fallback context, this records
      * the reason (timeout / schema-reject / exception). Null on the happy path.

package/dist/src/playbook/directives.d.ts

@@ -19,6 +19,8 @@
  */
 import type { GsdPhase } from "../gsd/types.js";
 import type { ComplexityTier } from "./complexity.js";
+/** When true and tier is standard/heavy, CHECK-PLAN points to gsd_plan_review tool. */
+export declare function buildNativeCheckPlanHint(): string;
 export interface DirectiveInput {
     /**
      * Model-decided work depth (agent-first — see layer1 `llm-classify`). Drives
@@ -62,6 +64,8 @@ export interface DirectiveInput {
      * the agent answered in English).
      */
     replyLanguage?: string;
+    /** When MUONROI_GSD_NATIVE=1, heavy/standard rubrics reference native tools. */
+    nativeGsd?: boolean;
 }
 export interface DirectiveOutput {
     text: string;

package/dist/src/playbook/directives.js

@@ -17,6 +17,12 @@
  * All directive text is English. The agent is responsible for translating
  * user-facing prompts into the user's language at render time.
  */
+/** When true and tier is standard/heavy, CHECK-PLAN points to gsd_plan_review tool. */
+export function buildNativeCheckPlanHint() {
+    return ("  4. CHECK-PLAN — call gsd_plan_review (native council) BEFORE executing. " +
+        "Multi-perspective review spawns research/skeptic/architect sub-agents; leader synthesizes PLAN-VERIFY.md. " +
+        "gsd_execute is blocked until verdict: pass.");
+}
 const HEADER = "[playbook]";
 /**
  * High-precision predicate: is this turn about the Muonroi ECOSYSTEM (where the
@@ -60,12 +66,15 @@ export function buildLanguageNudge(lang) {
 // senior-engineer reasoning over labeled scaffolds — feedback 12eceab7).
 function buildHeavy(input) {
     const phaseHint = input.phase ? ` (hint: this reads like a "${input.phase}" task)` : "";
+    const checkPlan = input.nativeGsd
+        ? buildNativeCheckPlanHint()
+        : "  4. CHECK-PLAN — review your own plan BEFORE executing: does it cover the acceptance criteria, handle the edge cases, and match what the user actually asked? Revise until it does (update the todo_write list if steps change). Confirm with the user only if the plan diverges from their intent.";
     return [
         `${HEADER} This reads like a HEAVY task${phaseHint} — architectural, cross-cutting, multi-file, or with real unresolved design choices. Don't start editing yet; work through these phases:`,
         "  1. DISCUSS — surface the decisions/ambiguities that actually change the design. For the ones the prompt doesn't already answer, ask up front with AskUserQuestion (put your recommended option first; write the question text in the user's language). Skip questions the prompt already settles — don't interrogate.",
-        "  2. RESEARCH — gather the codebase facts the task depends on: read/grep the relevant modules, and dispatch parallel research Agents when the areas are independent. When you delegate, give each sub-agent a NON-overlapping scope and tell it the exact return shape you need (findings as file:line + a one-line conclusion) — only the sub's final synthesis re-enters your context. Ground every later decision in what you actually found, not assumptions.",
-        "  3. PLAN — write a concrete, numbered plan: the change per file, the order, and the acceptance criteria (how you'll know it's done). Then record the plan as a todo_write checklist (one item per step) so the user sees a live progress list.",
-        "  4. CHECK-PLAN — review your own plan BEFORE executing: does it cover the acceptance criteria, handle the edge cases, and match what the user actually asked? Revise until it does (update the todo_write list if steps change). Confirm with the user only if the plan diverges from their intent.",
+        "  2. RESEARCH — gather the codebase facts the task depends on: read/grep the relevant modules, and dispatch parallel research Agents when the areas are independent. When you delegate (via `delegate`), give each sub-agent a NON-overlapping scope and tell it the exact return shape you need. Regularly check background tasks and subagents using `delegation_list` / `delegation_read` (or `process_list` / `process_logs` for shell processes) to monitor progress, and terminate them with `delegation_kill` / `process_stop` if they are no longer needed.",
+        "  3. PLAN — write a concrete, numbered plan via gsd_plan (or PLAN.md): the change per file, the order, and the acceptance criteria (how you'll know it's done). Then record the plan as a todo_write checklist (one item per step) so the user sees a live progress list.",
+        checkPlan,
         "  5. IMPLEMENT — execute in atomic steps; parallelize independent work. Keep the todo_write list accurate: mark each item in_progress before you start it and completed when it lands (exactly ONE item in_progress at a time). When you're in a git repo, COMMIT each completed chunk before starting the next one (small, logically-scoped commits; message ends with the mandatory attribution line) — do NOT pile the whole task into one commit at the end.",
         "  6. VERIFY — run the relevant tests / lint / type-check and report evidence (command + result) before claiming done.",
         "This depth is a recommendation from how the task reads. If, once you look, it's genuinely smaller than it appears, say so and drop to the STANDARD flow rather than over-processing it.",
@@ -92,10 +101,13 @@ function buildStandard(input) {
             "If the limits are blown and you still have no fix, STOP and report what you tried + why you're stuck.",
         ].join("\n");
     }
+    const checkStep = input.nativeGsd
+        ? "  2. CHECK — call gsd_plan_review (lightweight council: research + skeptic perspectives) before editing files."
+        : "  2. CHECK — sanity-check that plan against the real code (read the key files you named) and against the user's intent; fix the plan if reality differs. If a genuine ambiguity blocks you, ask ONE focused question via AskUserQuestion instead of guessing.";
     return [
         `${HEADER} This reads like a STANDARD task${phaseHint} — work like a senior engineer, but keep it lightweight:`,
-        "  1. PLAN — state a short, concrete plan: the files/functions you'll touch and in what order. A few bullets in your reply, not an essay. If it breaks into ≥3 steps, also record them with todo_write so the user gets a live checklist.",
-        "  2. CHECK — sanity-check that plan against the real code (read the key files you named) and against the user's intent; fix the plan if reality differs. If a genuine ambiguity blocks you, ask ONE focused question via AskUserQuestion instead of guessing.",
+        "  1. PLAN — state a short, concrete plan via gsd_plan: the files/functions you'll touch and in what order. A few bullets in your reply, not an essay. If it breaks into ≥3 steps, also record them with todo_write so the user gets a live checklist.",
+        checkStep,
         "  3. IMPLEMENT — execute the plan in small steps with the appropriate tools. If you made a todo_write checklist, keep it updated as you go (exactly one item in_progress at a time). When you're in a git repo, COMMIT each cohesive chunk as it lands (small commits; message ends with the mandatory attribution line) rather than batching everything into one final commit.",
         "  4. VERIFY — run the relevant tests / type-check / quick smoke and report evidence before claiming done.",
         "You don't need subagents or a discussion round for this. But if it turns out to be architectural or spans many files, escalate to the HEAVY flow (discuss → research → checked plan) rather than charging ahead.",

package/dist/src/product-loop/artifact-io.js

@@ -92,6 +92,8 @@ export async function appendIteration(flowDir, runId, entry) {
         `CriteriaPartial: ${entry.criteriaPartial}`,
         `CriteriaUnmet: ${entry.criteriaUnmet}`,
     ];
+    if (entry.totalCriteria !== undefined)
+        lines.push(`TotalCriteria: ${entry.totalCriteria}`);
     if (entry.crashed)
         lines.push("Crashed: true");
     if (entry.retryOf !== undefined)
@@ -137,6 +139,8 @@ export async function readIterations(flowDir, runId) {
             iter.crashed = true;
         if (data.RetryOf !== undefined)
             iter.retryOf = Number.parseInt(data.RetryOf, 10);
+        if (data.TotalCriteria !== undefined)
+            iter.totalCriteria = Number.parseInt(data.TotalCriteria, 10);
         results.push(iter);
     }
     return results.sort((a, b) => a.sprintN - b.sprintN);

package/dist/src/product-loop/backlog-builder.d.ts

@@ -8,7 +8,7 @@
  * — NO hardcoded model id or provider anywhere in this file.
  */
 import type { ClarifiedSpec, CouncilLLM } from "../council/types.js";
-import type { Backlog, ImplementationPlanArtifact } from "./types.js";
+import type { Backlog, EffortPoints, ImplementationPlanArtifact } from "./types.js";
 export interface BuildBacklogInput {
     runId: string;
     productSlug: string;
@@ -18,6 +18,19 @@ export interface BuildBacklogInput {
     leaderModelId: string;
     costAware: boolean;
 }
+/**
+ * Deterministic keyword heuristic for a story-point prior (1 | 3 | 5).
+ *
+ * Used as the FALLBACK when the LLM effort estimate fails or returns unparseable
+ * JSON — cheap models (deepseek) often emit malformed arrays, and the previous
+ * flat-3 fallback made every item identical, so sprint bin-packing degenerated
+ * into a mechanical "≈2-3 items per sprint" split with no relation to real size
+ * (observed live: a "migrate 5 native modules" item and a "remove dependency"
+ * item both scored 3). A rough size signal from the title is strictly better than
+ * uniform. Verb-driven: creation/migration reads large, deletion/config reads
+ * small, everything else medium.
+ */
+export declare function heuristicEffort(title: string): EffortPoints;
 /**
  * Build a Backlog from a ClarifiedSpec + the Phase 1 implementation_plan artifact.
  *

package/dist/src/product-loop/backlog-builder.js

@@ -23,11 +23,35 @@ function hashSpec(spec) {
 function keywordMatch(haystack, needle) {
     return haystack.toLowerCase().includes(needle.toLowerCase());
 }
+/**
+ * Deterministic keyword heuristic for a story-point prior (1 | 3 | 5).
+ *
+ * Used as the FALLBACK when the LLM effort estimate fails or returns unparseable
+ * JSON — cheap models (deepseek) often emit malformed arrays, and the previous
+ * flat-3 fallback made every item identical, so sprint bin-packing degenerated
+ * into a mechanical "≈2-3 items per sprint" split with no relation to real size
+ * (observed live: a "migrate 5 native modules" item and a "remove dependency"
+ * item both scored 3). A rough size signal from the title is strictly better than
+ * uniform. Verb-driven: creation/migration reads large, deletion/config reads
+ * small, everything else medium.
+ */
+export function heuristicEffort(title) {
+    const t = title.toLowerCase();
+    const large = /\b(implement|build|create|migrat\w*|rewrite|refactor|orchestrat\w*|engine|subsystem|native|integrat\w*|pipeline|architect\w*)\b/;
+    const small = /\b(remove|delete|drop|inventory|rename|config\w*|flag|doc\w*|cleanup|wire|rename|bump|stub|export)\b/;
+    if (large.test(t))
+        return 5;
+    if (small.test(t))
+        return 1;
+    return 3;
+}
 /**
  * Ask the LLM to estimate effortPoints for a batch of feature titles in a
  * single call. Parses JSON array response: [1, 3, 5, ...].
  *
- * Falls back to 3 (medium) for any item that fails to parse correctly.
+ * Falls back to a per-title keyword heuristic ({@link heuristicEffort}) — NOT a
+ * flat 3 — for any item the LLM fails to score, so sprint packing keeps a real
+ * size signal even when the cheap model returns garbage.
  *
  * Model selection: pickCouncilTaskModel("effort_estimate", leaderModelId, costAware)
  */
@@ -46,25 +70,25 @@ async function estimateEffortBatch(titles, llm, leaderModelId, costAware) {
         raw = await llm.generate(model, system, prompt, 256);
     }
     catch {
-        // Graceful degrade: default everything to M=3
-        return titles.map(() => 3);
+        // Graceful degrade: keyword heuristic prior per title (NOT flat 3).
+        return titles.map((t) => heuristicEffort(t));
     }
     try {
         const match = raw.match(/\[[\s\S]*\]/);
         if (match) {
             const arr = JSON.parse(match[0]);
-            return titles.map((_, i) => {
+            return titles.map((t, i) => {
                 const v = arr[i];
                 if (v === 1 || v === 3 || v === 5)
                     return v;
-                return 3;
+                return heuristicEffort(t); // this item unscored/invalid → heuristic, not flat 3
             });
         }
     }
     catch {
         // JSON parse failed — fall through
     }
-    return titles.map(() => 3);
+    return titles.map((t) => heuristicEffort(t));
 }
 /**
  * Build a Backlog from a ClarifiedSpec + the Phase 1 implementation_plan artifact.