muonroi-cli 1.6.6 → 1.7.0

package/dist/src/pil/llm-classify.js

@@ -25,10 +25,10 @@ const LLM_CLASSIFY_TIMEOUT_MS = 2500;
 // The ceiling is a cap, not padding: the model still stops after two words, so a
 // generous headroom costs nothing when reasoning is short.
 const REASONING_CLASSIFY_TIMEOUT_MS = 8000;
-// Four comma-separated words now (added <deliverable>) — ~10-14 tokens worst
-// case ("documentation,balanced,task,report"). 24 keeps headroom over the
-// prior 16-token cap without padding (the model still stops after four words).
-const NONREASONING_MAX_OUTPUT_TOKENS = 24;
+// Seven comma-separated words now (added <scope>,<lang>) — ~18-26 tokens worst
+// case ("documentation,balanced,task,report,standard,ecosystem,vietnamese").
+// 48 keeps headroom without padding (the model still stops after seven words).
+const NONREASONING_MAX_OUTPUT_TOKENS = 48;
 const REASONING_MAX_OUTPUT_TOKENS = 2048;
 /**
  * Per-namespace shallow merge of providerOptions. The base already carries
@@ -58,7 +58,34 @@ const VALID_TASK_TYPES = new Set([
     "general",
 ]);
 const VALID_STYLES = new Set(["concise", "balanced", "detailed"]);
-const SYSTEM_PROMPT = "You classify user prompts for a coding assistant. Reply with ONE line of FOUR lowercase words separated by commas: <taskType>,<style>,<intent>,<deliverable>\n\n" +
+const VALID_DEPTHS = new Set(["quick", "standard", "heavy"]);
+// Every token the classifier can legitimately emit for the first six fields.
+// Used to isolate the 7th field (language), which is open-vocabulary: the lang
+// word is the one alphabetic token that is NOT a known enum value.
+const KNOWN_CLASSIFY_WORDS = new Set([
+    "refactor",
+    "debug",
+    "plan",
+    "analyze",
+    "documentation",
+    "generate",
+    "general",
+    "concise",
+    "balanced",
+    "detailed",
+    "task",
+    "chat",
+    "chitchat",
+    "answer",
+    "code",
+    "report",
+    "quick",
+    "standard",
+    "heavy",
+    "ecosystem",
+    "local",
+]);
+const SYSTEM_PROMPT = "You classify user prompts for a coding assistant. Reply with ONE line of SEVEN lowercase words separated by commas: <taskType>,<style>,<intent>,<deliverable>,<depth>,<scope>,<lang>\n\n" +
     "taskType ∈ { refactor | debug | plan | analyze | documentation | generate | general }\n" +
     "style ∈ { concise | balanced | detailed }\n" +
     "intent ∈ { task | chat } — 'chat' ONLY for a pure greeting, thanks, or acknowledgement with NO work request (e.g. 'hi', 'cảm ơn nhé', 'ok great'). EVERYTHING else is 'task', including questions about code or the CLI, 'are you done?', and requests to call a tool. When unsure, choose 'task'.\n" +
@@ -66,7 +93,17 @@ const SYSTEM_PROMPT = "You classify user prompts for a coding assistant. Reply w
     "- code — CREATE or EDIT files: implement, fix, build, scaffold, refactor, wire, rename, apply a patch. The deliverable is changed code.\n" +
     "- report — a STRUCTURED list / plan / audit / roadmap / checklist is the deliverable (its value IS the structure).\n" +
     "- answer — everything else: explain, review, investigate, compare, a question about code or the CLI, a yes/no question, a meta/self-eval. The deliverable is a written answer, NO file edits.\n" +
-    "  Pick by the PRIMARY thing the user asked you to produce. A question that merely mentions code is 'answer'. When unsure between answer and report, choose answer.\n\n" +
+    "  Pick by the PRIMARY thing the user asked you to produce. A question that merely mentions code is 'answer'. When unsure between answer and report, choose answer.\n" +
+    "depth ∈ { quick | standard | heavy } — how much work the task ACTUALLY entails (judge the work, NOT the wording; a plainly-phrased request can still be heavy):\n" +
+    "- quick — a trivial single-shot change or a small direct answer: typo, rename one symbol, one-line edit, a quick lookup, 'what does X do'. No plan needed.\n" +
+    "- standard — ordinary feature or bugfix touching a handful of files/functions; needs a short plan + a verify step, but no upfront research or user discussion.\n" +
+    "- heavy — architectural, cross-cutting, multi-file/multi-module, a migration, 'redo/rebuild', a vague 'make it better', or a request with real unresolved design choices. Needs discussion + research + a checked plan before any code.\n" +
+    "  For a pure question/answer (deliverable=answer), depth reflects how much investigation the answer needs: 'quick' for a simple fact, 'standard' for a normal explanation, 'heavy' for a deep architectural review.\n" +
+    "  When unsure between quick and standard, choose standard. When the task is genuinely wide or ambiguous, choose heavy.\n" +
+    "scope ∈ { ecosystem | local }:\n" +
+    "- ecosystem — the turn is about the Muonroi PLATFORM as a whole: the building-block / .NET packages, open-core boundary, the rule engine / decision tables, NuGet packages, or platform setup/install. These are documented in an authoritative docs source.\n" +
+    "- local — EVERYTHING else, including questions about this CLI's own internals (even when they mention the word 'muonroi'). When unsure, choose local.\n" +
+    "lang — the language the user's message is written in, as ONE lowercase English word: english, vietnamese, japanese, french, etc. Use 'english' for English or when unsure.\n\n" +
     "Rules (read carefully — Phase 4 4P-2 disambiguation):\n" +
     "- debug — fix a bug, CI/build/test failure, error, exception, crash, or any 'why is X broken' question.\n" +
     "- generate — create new code, scaffold, write a new file, add a feature from scratch, ADD A NEW TEST, CHANGE A DEFAULT VALUE, modify configuration, improve coverage.\n" +
@@ -91,17 +128,21 @@ const SYSTEM_PROMPT = "You classify user prompts for a coding assistant. Reply w
     "- documentation → balanced (examples + explanation)\n" +
     "- general → concise\n" +
     "Only output 'detailed' if the user prompt LITERALLY contains words like 'explain in detail', 'thorough analysis', 'walk me through', 'giải thích chi tiết', 'phân tích kỹ'.\n\n" +
-    "Intent + deliverable examples:\n" +
-    "- 'hi' → general,concise,chat,answer\n" +
-    "- 'cảm ơn bạn nhé' → general,concise,chat,answer\n" +
-    "- 'bạn thử call tool setup_guide xem được không' → general,concise,task,answer (wants info, not file edits)\n" +
-    "- 'bạn xong chưa' → general,concise,task,answer (a question — NOT chat)\n" +
-    "- 'fix CI failing on Windows' → debug,concise,task,code\n" +
-    "- 'rename function shouldInject to needsReminder' → refactor,concise,task,code\n" +
-    "- 'tại sao bash_output_get trả empty' → analyze,concise,task,answer (investigate → written answer)\n" +
-    "- 'liệt kê tất cả env var CLI đọc' → analyze,concise,task,report (structured list)\n" +
-    "- 'plan the migration to hooks' → plan,balanced,task,report\n\n" +
-    "Prompts may be Vietnamese, English, or mixed. Reply with exactly four words separated by commas. No other text.";
+    "Full examples (taskType,style,intent,deliverable,depth,scope,lang):\n" +
+    "- 'hi' → general,concise,chat,answer,quick,local,english\n" +
+    "- 'cảm ơn bạn nhé' → general,concise,chat,answer,quick,local,vietnamese\n" +
+    "- 'bạn xong chưa' → general,concise,task,answer,quick,local,vietnamese (a question — NOT chat)\n" +
+    "- 'fix the typo in the README title' → generate,concise,task,code,quick,local,english\n" +
+    "- 'fix CI failing on Windows' → debug,concise,task,code,standard,local,english\n" +
+    "- 'rename function shouldInject to needsReminder' → refactor,concise,task,code,quick,local,english\n" +
+    "- 'thêm caching cho provider layer và update tests' → generate,concise,task,code,standard,local,vietnamese\n" +
+    "- 'tại sao bash_output_get trả empty' → analyze,concise,task,answer,standard,local,vietnamese\n" +
+    "- 'liệt kê tất cả env var CLI đọc' → analyze,concise,task,report,standard,local,vietnamese\n" +
+    "- 'refactor the entire auth system to use OAuth' → refactor,concise,task,code,heavy,local,english\n" +
+    "- 'how does the building-block rule engine work' → analyze,concise,task,answer,standard,ecosystem,english\n" +
+    "- 'hệ sinh thái muonroi gồm những gì' → analyze,balanced,task,answer,standard,ecosystem,vietnamese\n" +
+    "- 'plan the migration to hooks' → plan,balanced,task,report,heavy,local,english\n\n" +
+    "Prompts may be Vietnamese, English, or mixed. Reply with exactly seven words separated by commas. No other text.";
 function parseResponse(raw) {
     const cleaned = raw.trim().toLowerCase().replace(/[`*"]/g, "");
     const firstLine = cleaned.split(/\r?\n/)[0] ?? "";
@@ -126,7 +167,32 @@ function parseResponse(raw) {
     // their legacy regex predicates for this turn (never a wrong forced route).
     const deliverableWord = parts.find((p) => p === "answer" || p === "code" || p === "report");
     const deliverableKind = deliverableWord ?? null;
-    return { taskType: taskWord, outputStyle: style, confidence: 0.75, intentKind, deliverableKind };
+    // Fifth word is the model-decided work depth. Parsed position-independently so
+    // a reordered/garbled reply still recovers it; null when absent → Layer 4
+    // defaults to "standard" and the injected rubric lets the agent self-select.
+    const depthWord = parts.find((p) => VALID_DEPTHS.has(p));
+    const depthTier = depthWord ?? null;
+    // Sixth word is the scope. "ecosystem" → platform/docs-authoritative turn;
+    // anything else (incl. absent) → not ecosystem. Position-independent.
+    const scopeWord = parts.find((p) => p === "ecosystem" || p === "local");
+    const ecosystemScope = scopeWord ? scopeWord === "ecosystem" : null;
+    // Seventh word is the user's language. It is the one alphabetic token that is
+    // NOT a known enum value (open vocabulary). null when English / absent so
+    // Layer 4 skips the language re-anchor for English turns.
+    const langWord = parts.find((p) => /^[a-z][a-z-]+$/.test(p) && !KNOWN_CLASSIFY_WORDS.has(p));
+    const replyLanguage = langWord && langWord !== "english" && langWord !== "en"
+        ? langWord.charAt(0).toUpperCase() + langWord.slice(1)
+        : null;
+    return {
+        taskType: taskWord,
+        outputStyle: style,
+        confidence: 0.75,
+        intentKind,
+        deliverableKind,
+        depthTier,
+        ecosystemScope,
+        replyLanguage,
+    };
 }
 /**
  * Build a closure the PIL pipeline can call. Reuses the orchestrator's already-

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

@@ -3,8 +3,8 @@
  *
  * Core type definitions for the Prompt Intelligence Layer (PIL) pipeline.
  */
-import type { ComplexityTier } from "../gsd/complexity.js";
 import type { GrayAreaQuestion } from "../gsd/gray-areas.js";
+import type { ComplexityTier } from "../playbook/complexity.js";
 import type { ComplexitySizeResult } from "./layer1_5-complexity-size.js";
 export type TaskType = "refactor" | "debug" | "plan" | "analyze" | "documentation" | "generate" | "build" | "general";
 export type OutputStyle = "concise" | "detailed" | "balanced";
@@ -42,8 +42,33 @@ export interface PipelineContext {
     activeRunId?: string | null;
     digestAgeMs?: number | null;
     sessionId?: string | null;
-    /** GSD-native triage tier (set by layer4). */
+    /** GSD-native triage tier (set by layer4 — sourced from modelDepthTier when present). */
     complexityTier?: ComplexityTier | null;
+    /**
+     * Model-decided work depth (quick | standard | heavy), set by layer1's
+     * model-first classifier (the 5th classify word). This is the agent-first
+     * source of truth for the GSD directive tier; layer4 prefers it over the
+     * legacy regex `scoreComplexity` (which now only runs as the offline fallback
+     * when the model classifier is unwired/failed). null when the model omitted
+     * the word OR the legacy cascade ran → layer4 falls back accordingly.
+     */
+    modelDepthTier?: ComplexityTier | null;
+    /**
+     * Model-decided scope (agent-first replacement for the `mentionsEcosystemScope`
+     * regex): true when the turn is about the Muonroi PLATFORM/ecosystem (BB/.NET,
+     * building-block, rule engine, platform setup) where muonroi-docs is
+     * authoritative. Set by layer1's classifier; consumed by layer4 to gate the
+     * docs-first nudge. null/undefined → treated as not-ecosystem.
+     */
+    ecosystemScope?: boolean | null;
+    /**
+     * Model-decided reply language as a display name ("Vietnamese", "Japanese"),
+     * or null for English. Agent-first replacement for the Vietnamese-only
+     * diacritic regex — generalizes to any language. Set by layer1; consumed by
+     * layer4 to re-anchor the "reply in the user's language" rule inside the
+     * directive when the user did not write in English.
+     */
+    replyLanguage?: string | null;
     /**
      * Layer 1.5 deterministic complexity-size classification.
      * Populated immediately after `layer1Intent` in `runLayers()`. Consumers:

package/dist/src/{gsd → playbook}/__tests__/directives.test.js

@@ -1,41 +1,40 @@
 import { describe, expect, it } from "vitest";
-import { scoreComplexity } from "../complexity.js";
 import { buildDirective, mentionsEcosystemScope } from "../directives.js";
-import { detectGrayAreas } from "../gray-areas.js";
 describe("buildDirective", () => {
-    it("emits a blocking heavy directive with mandatory steps", () => {
-        const prompt = "redo the entire architecture and map everything across all repos";
-        const complexity = scoreComplexity(prompt);
-        expect(complexity.tier).toBe("heavy");
-        const grayAreas = detectGrayAreas(prompt).questions;
-        const out = buildDirective({ complexity, phase: null, grayAreas });
+    it("emits a blocking heavy directive with discuss → research → plan → check-plan → verify", () => {
+        const out = buildDirective({ tier: "heavy", phase: null });
         expect(out.tier).toBe("heavy");
         expect(out.blocking).toBe(true);
-        expect(out.text).toContain("MANDATORY");
+        expect(out.text).toMatch(/HEAVY task/);
+        expect(out.text).toMatch(/DISCUSS/);
+        expect(out.text).toMatch(/RESEARCH/);
+        expect(out.text).toMatch(/CHECK-PLAN/);
         expect(out.text).toMatch(/AskUserQuestion/);
-        expect(out.text).toMatch(/IN PARALLEL/);
-        expect(out.text).toMatch(/research/i);
-        expect(out.text).toMatch(/verify/i);
+        expect(out.text).toMatch(/VERIFY/);
+        // Hybrid: the agent may de-escalate if the task is smaller than it reads.
+        expect(out.text).toMatch(/STANDARD flow/);
     });
-    it("emits a non-blocking standard directive", () => {
-        const complexity = scoreComplexity("add a /health endpoint");
-        const out = buildDirective({ complexity, phase: "execute", grayAreas: [] });
+    it("emits a non-blocking standard directive with an explicit plan + check step", () => {
+        const out = buildDirective({ tier: "standard", phase: "execute" });
         expect(out.tier).toBe("standard");
         expect(out.blocking).toBe(false);
-        expect(out.text).toMatch(/GSD-quick/i);
+        expect(out.text).toMatch(/STANDARD task/);
+        expect(out.text).toMatch(/PLAN —/);
+        expect(out.text).toMatch(/CHECK —/);
+        expect(out.text).toMatch(/VERIFY —/);
+        // Hybrid: escalate to HEAVY if it turns out architectural.
+        expect(out.text).toMatch(/escalate to the HEAVY flow/);
     });
     it("emits a fix-first debug variant when phase is debug (session 7d56a049e1e3 regression)", () => {
-        const complexity = scoreComplexity("fix CI fail");
-        const out = buildDirective({ complexity, phase: "debug", grayAreas: [] });
+        const out = buildDirective({ tier: "standard", phase: "debug" });
         expect(out.tier).toBe("standard");
         expect(out.text).toMatch(/DEBUG task/);
         expect(out.text).toMatch(/FIX-FIRST/);
         expect(out.text).toMatch(/≤ 8 read_file/);
         expect(out.text).toMatch(/edit_file/);
     });
-    it("standard non-debug phases use the generic GSD-quick directive (regression: don't apply fix-first cap to plan/execute)", () => {
-        const complexity = scoreComplexity("add a counter feature");
-        const out = buildDirective({ complexity, phase: "execute", grayAreas: [] });
+    it("standard non-debug phases use the generic plan/check directive (regression: don't apply fix-first cap to plan/execute)", () => {
+        const out = buildDirective({ tier: "standard", phase: "execute" });
         expect(out.text).not.toMatch(/FIX-FIRST/);
         expect(out.text).not.toMatch(/read_file calls before/);
     });
@@ -43,40 +42,36 @@ describe("buildDirective", () => {
         // A self/meta CLI question routed through GSD must NOT get the
         // implement/verify scaffold — that leaked a "2-3 line plan" preamble +
         // process narration into the human-facing answer.
-        const complexity = scoreComplexity("how does this CLI affect you?");
-        const out = buildDirective({ complexity, phase: null, grayAreas: [], informational: true });
+        const out = buildDirective({ tier: "quick", phase: null, informational: true });
         expect(out.blocking).toBe(false);
         expect(out.text).toMatch(/QUESTION \/ explanatory/);
         expect(out.text).toMatch(/written for the HUMAN/);
         expect(out.text).not.toMatch(/2-3 line plan/);
-        expect(out.text).not.toMatch(/Implement directly/);
+        expect(out.text).not.toMatch(/CHECK-PLAN/);
     });
     it("informational overrides even a heavy tier (a question never implements)", () => {
-        const complexity = scoreComplexity("redo the entire architecture and map everything across all repos");
-        expect(complexity.tier).toBe("heavy");
-        const out = buildDirective({ complexity, phase: null, grayAreas: [], informational: true });
+        const out = buildDirective({ tier: "heavy", phase: null, informational: true });
         expect(out.blocking).toBe(false);
         expect(out.text).toMatch(/QUESTION \/ explanatory/);
-        expect(out.text).not.toMatch(/MANDATORY/);
+        expect(out.text).not.toMatch(/DISCUSS/);
+        expect(out.text).not.toMatch(/CHECK-PLAN/);
     });
-    it("emits a minimal quick directive", () => {
-        const complexity = scoreComplexity("fix typo");
-        const out = buildDirective({ complexity, phase: null, grayAreas: [] });
+    it("emits a quick directive that stays short", () => {
+        const out = buildDirective({ tier: "quick", phase: null });
         expect(out.tier).toBe("quick");
         expect(out.blocking).toBe(false);
-        expect(out.text.length).toBeLessThan(300);
+        expect(out.text).toMatch(/QUICK task/);
+        expect(out.text.length).toBeLessThan(600);
     });
     it("appends the muonroi-docs nudge for an ecosystem question (session 41ccfeb2ceee turn 1)", () => {
-        const complexity = scoreComplexity("bạn hiểu thế nào về ecosystem muonroi nói chung");
-        const out = buildDirective({ complexity, phase: null, grayAreas: [], informational: true, ecosystem: true });
+        const out = buildDirective({ tier: "quick", phase: null, informational: true, ecosystem: true });
         expect(out.text).toMatch(/QUESTION \/ explanatory/); // still the human-facing question directive
         expect(out.text).toMatch(/ECOSYSTEM SCOPE/);
         expect(out.text).toMatch(/muonroi-docs MCP is the AUTHORITATIVE source|AUTHORITATIVE source/);
         expect(out.text).toMatch(/call it FIRST/i);
     });
     it("does NOT append the ecosystem nudge for a plain question", () => {
-        const complexity = scoreComplexity("how does this CLI affect you?");
-        const out = buildDirective({ complexity, phase: null, grayAreas: [], informational: true });
+        const out = buildDirective({ tier: "quick", phase: null, informational: true });
         expect(out.text).not.toMatch(/ECOSYSTEM SCOPE/);
     });
     it("mentionsEcosystemScope is tight: ecosystem/BB wording yes, bare CLI-internals no", () => {
@@ -89,43 +84,24 @@ describe("buildDirective", () => {
         expect(mentionsEcosystemScope("how does muonroi-cli compaction work")).toBe(false);
         expect(mentionsEcosystemScope("fix the off-by-one in the router")).toBe(false);
     });
-    it("renders the recommended option first in gray-area block", () => {
-        const prompt = "redo everything from scratch";
-        const complexity = scoreComplexity(prompt);
-        const grayAreas = detectGrayAreas(prompt).questions;
-        const out = buildDirective({ complexity, phase: null, grayAreas });
-        if (grayAreas.length > 0) {
-            expect(out.text).toMatch(/\[recommended\]/);
-        }
-    });
     // Language nudge — re-anchors the "reply in user's language" rule INSIDE the
     // directive so layered brevity / FIX-FIRST directives can't drown it (live
     // miss: storyflow_ui session 22661c8de9f2).
     describe("language nudge", () => {
         it("appends the nudge when replyLanguage is set", () => {
-            const out = buildDirective({
-                complexity: scoreComplexity("fix CI fail"),
-                phase: "debug",
-                grayAreas: [],
-                replyLanguage: "Vietnamese",
-            });
+            const out = buildDirective({ tier: "standard", phase: "debug", replyLanguage: "Vietnamese" });
             expect(out.text).toMatch(/LANGUAGE — the user wrote in Vietnamese/);
             expect(out.text).toMatch(/Reply in Vietnamese/);
             expect(out.text).toMatch(/OVERRIDES any brevity/);
         });
         it("omits the nudge when replyLanguage is undefined", () => {
-            const out = buildDirective({
-                complexity: scoreComplexity("fix CI fail"),
-                phase: "debug",
-                grayAreas: [],
-            });
+            const out = buildDirective({ tier: "standard", phase: "debug" });
             expect(out.text).not.toMatch(/LANGUAGE —/);
         });
         it("stacks with the ecosystem nudge when both apply", () => {
             const out = buildDirective({
-                complexity: scoreComplexity("how does the muonroi ecosystem work"),
+                tier: "heavy",
                 phase: null,
-                grayAreas: [],
                 ecosystem: true,
                 replyLanguage: "Vietnamese",
             });

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

@@ -0,0 +1,17 @@
+/**
+ * src/playbook/complexity.ts
+ *
+ * Work-depth tier used by the [playbook] directive injected per turn.
+ *
+ *   - "quick"    → trivial single-shot tasks (typo, rename, read-and-explain).
+ *   - "standard" → ordinary feature/bugfix work. Short plan → check → impl → verify.
+ *   - "heavy"    → architectural / multi-file / wide / ambiguous. Full
+ *                  discuss → research → plan → check-plan → implement → verify.
+ *
+ * The depth is decided AGENT-FIRST by the model (the 5th word of the layer1
+ * `llm-classify` call → `ctx.modelDepthTier`), NOT by a regex scan of the
+ * prompt. The old keyword `scoreComplexity` scorer was removed (2026-06-18,
+ * no-regex rule): keyword matching mis-tiered plainly-phrased tasks, which is
+ * exactly what made the agent skip the rigor a task needed.
+ */
+export type ComplexityTier = "quick" | "standard" | "heavy";

package/dist/src/playbook/complexity.js

@@ -0,0 +1,18 @@
+/**
+ * src/playbook/complexity.ts
+ *
+ * Work-depth tier used by the [playbook] directive injected per turn.
+ *
+ *   - "quick"    → trivial single-shot tasks (typo, rename, read-and-explain).
+ *   - "standard" → ordinary feature/bugfix work. Short plan → check → impl → verify.
+ *   - "heavy"    → architectural / multi-file / wide / ambiguous. Full
+ *                  discuss → research → plan → check-plan → implement → verify.
+ *
+ * The depth is decided AGENT-FIRST by the model (the 5th word of the layer1
+ * `llm-classify` call → `ctx.modelDepthTier`), NOT by a regex scan of the
+ * prompt. The old keyword `scoreComplexity` scorer was removed (2026-06-18,
+ * no-regex rule): keyword matching mis-tiered plainly-phrased tasks, which is
+ * exactly what made the agent skip the rigor a task needed.
+ */
+export {};
+//# sourceMappingURL=complexity.js.map

package/dist/src/{gsd → playbook}/directives.d.ts

@@ -1,26 +1,33 @@
 /**
- * src/gsd/directives.ts
+ * src/playbook/directives.ts
  *
- * Builds the system-prompt directive block injected by layer4-gsd. The directive
- * is what actually changes the agent's behaviour: it lists the GSD-style steps
- * the agent must take before touching code.
+ * Builds the system-prompt directive block injected per turn by layer4
+ * (`src/pil/layer4-gsd.ts`). The directive is what actually changes the agent's
+ * behaviour: it injects a HYBRID rubric for the work-depth tier the model chose
+ * — the system recommends a depth, the agent declares its path and may
+ * escalate/de-escalate. This is the "[playbook]" mindset layer (NOT the real
+ * GSD framework / `/gsd:*` skills — it only borrows the discuss→plan→execute
+ * mindset).
  *
  * Three tiers:
- *   - heavy:    full discuss → research → verify → plan → impl → verify flow,
- *               with mandatory AskUserQuestion + parallel Agent dispatch.
- *   - standard: GSD-quick mindset — short plan, then implement, then verify.
+ *   - heavy:    discuss → research → plan → check-plan → implement → verify.
+ *   - standard: short plan → check → implement → verify.
  *   - quick:    minimal hint, run inline.
  *
  * All directive text is English. The agent is responsible for translating
  * user-facing prompts into the user's language at render time.
  */
-import type { ComplexityResult } from "./complexity.js";
-import type { GrayAreaQuestion } from "./gray-areas.js";
-import type { GsdPhase } from "./types.js";
+import type { GsdPhase } from "../gsd/types.js";
+import type { ComplexityTier } from "./complexity.js";
 export interface DirectiveInput {
-    complexity: ComplexityResult;
+    /**
+     * Model-decided work depth (agent-first — see layer1 `llm-classify`). Drives
+     * which rubric is injected. The rubric itself is HYBRID: it states the
+     * recommended depth but lets the agent escalate/de-escalate if the task turns
+     * out bigger or smaller than it read.
+     */
+    tier: ComplexityTier;
     phase: GsdPhase | null;
-    grayAreas: GrayAreaQuestion[];
     /**
      * True when the prompt is informational/explanatory (a question or a
      * self/meta analysis) rather than a request to change code. The deliverable
@@ -58,7 +65,7 @@ export interface DirectiveInput {
 }
 export interface DirectiveOutput {
     text: string;
-    tier: ComplexityResult["tier"];
+    tier: ComplexityTier;
     /** True when the directive forbids the agent from acting before clarifying. */
     blocking: boolean;
 }

package/dist/src/playbook/directives.js

@@ -0,0 +1,149 @@
+/**
+ * src/playbook/directives.ts
+ *
+ * Builds the system-prompt directive block injected per turn by layer4
+ * (`src/pil/layer4-gsd.ts`). The directive is what actually changes the agent's
+ * behaviour: it injects a HYBRID rubric for the work-depth tier the model chose
+ * — the system recommends a depth, the agent declares its path and may
+ * escalate/de-escalate. This is the "[playbook]" mindset layer (NOT the real
+ * GSD framework / `/gsd:*` skills — it only borrows the discuss→plan→execute
+ * mindset).
+ *
+ * Three tiers:
+ *   - heavy:    discuss → research → plan → check-plan → implement → verify.
+ *   - standard: short plan → check → implement → verify.
+ *   - quick:    minimal hint, run inline.
+ *
+ * All directive text is English. The agent is responsible for translating
+ * user-facing prompts into the user's language at render time.
+ */
+const HEADER = "[playbook]";
+/**
+ * High-precision predicate: is this turn about the Muonroi ECOSYSTEM (where the
+ * muonroi-docs MCP is the right source), as opposed to muonroi-cli internals?
+ * Deliberately TIGHTER than smart-filter's hasEcosystemSignal — that one keeps
+ * the server (over-keeping costs only tokens), but a behavioural "call docs
+ * FIRST" nudge must not fire on every "muonroi" mention or it misdirects
+ * CLI-internals questions toward .NET package docs. EN + VI.
+ */
+const ECOSYSTEM_SCOPE_RE = /\becosystem\b|hệ\s*sinh\s*thái|he\s*sinh\s*thai|building[-\s]?block|open[-\s]?core|rule\s*engine|decision\s*table|\bnuget\b/i;
+export function mentionsEcosystemScope(message) {
+    return ECOSYSTEM_SCOPE_RE.test(message);
+}
+/**
+ * Appended to any directive when the turn is ecosystem-scoped. Phrased
+ * conditionally ("if … available") so it is harmless when muonroi-docs is not
+ * configured — the model simply finds no such tool and falls back to local files.
+ */
+export const ECOSYSTEM_DOCS_NUDGE = [
+    `${HEADER} ECOSYSTEM SCOPE — this turn concerns the Muonroi ecosystem (platform overview, BB/.NET packages, building-block, open-core boundary, setup).`,
+    "If the muonroi-docs MCP is available, it is the AUTHORITATIVE source — call it FIRST (docs_search / setup_guide / bb_recipe_list / bb_package_describe), THEN ground with local files. Do NOT characterize the ecosystem from local repo files alone.",
+].join("\n");
+/**
+ * Appended to any directive when the user's reply language is non-English.
+ * The base system prompt's "reply in user's language" rule normally suffices,
+ * but `concise` / `FIX-FIRST` / GSD-debug directive bodies stack on top of it
+ * with strong "be terse / code over prose" language that crowds the rule out
+ * — observed live (storyflow_ui 22661c8de9f2). This NUDGE re-anchors the rule
+ * inside the directive itself so brevity preferences cannot override it.
+ */
+export function buildLanguageNudge(lang) {
+    return [
+        `${HEADER} LANGUAGE — the user wrote in ${lang}. Reply in ${lang}.`,
+        "This rule OVERRIDES any brevity / concise / code-over-prose directive: terseness is fine, but the response language stays the user's.",
+    ].join("\n");
+}
+// All three rubrics are HYBRID + agent-first: the system recommends a depth
+// based on the model's read of the task, but each rubric ends by empowering the
+// agent to escalate or de-escalate if the task turns out bigger/smaller than it
+// looked. Phrased as guidance, not a rigid template (the user prefers natural,
+// senior-engineer reasoning over labeled scaffolds — feedback 12eceab7).
+function buildHeavy(input) {
+    const phaseHint = input.phase ? ` (hint: this reads like a "${input.phase}" task)` : "";
+    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.",
+        "  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.",
+    ].join("\n");
+}
+function buildStandard(input) {
+    const phaseHint = input.phase ? ` (hint: this reads like a "${input.phase}" task)` : "";
+    // Debug-phase variant: tighten exploration budget. Session 7d56a049e1e3
+    // ran 109 tool calls (58 bash + 33 read_file + 16 grep + 2 mcp) over 6
+    // minutes WITHOUT a single edit_file / write_file — agent over-researched
+    // the CI failure instead of attempting a fix. Keep the FIX-FIRST exploration
+    // cap, but still require a brief check against reality before editing.
+    if (input.phase === "debug") {
+        return [
+            `${HEADER} This reads like a DEBUG task${phaseHint} — work FIX-FIRST, but think before you edit:`,
+            "  1. HYPOTHESIS — state a 2-3 line hypothesis (what's failing + your best guess why) BEFORE reading more than 3 files.",
+            "  2. CHECK — confirm the hypothesis against the actual failing code/log (read the key file, re-read the error). Adjust if reality disagrees.",
+            "  3. FIX — apply the smallest plausible fix with edit_file / write_file. Commit to a hypothesis and ship the diff; don't keep exploring.",
+            "  4. VERIFY — rerun the failing command/test and report evidence. When you're in a git repo and the fix verifies, commit it (message ends with the mandatory attribution line).",
+            "Hard limits — exceed only if a tool result genuinely contradicts your hypothesis:",
+            "  - ≤ 8 read_file calls before first edit_file",
+            "  - ≤ 5 grep calls before first edit_file",
+            "  - ≤ 10 bash log-fetching calls (gh run view, cat log, etc.) before first edit_file",
+            "If the limits are blown and you still have no fix, STOP and report what you tried + why you're stuck.",
+        ].join("\n");
+    }
+    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.",
+        "  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.",
+    ].join("\n");
+}
+function buildQuestion() {
+    // Informational / question / meta-analysis turns. The deliverable is the
+    // answer itself — there is no code to implement or test. Keep the agent's
+    // process OUT of the reply: a human asked, a human reads the result.
+    return [
+        `${HEADER} QUESTION / explanatory request — no code change is being asked for.`,
+        "Answer it directly and completely, written for the HUMAN who asked:",
+        "  1. Investigate only as needed — read/grep the specific files that ground your answer this turn.",
+        "  2. Lead with the answer. Use clear prose + structure (headings, bullets). Where a claim rests on the code, cite a concise file:line inline.",
+        "  3. Do NOT output an implementation plan, do NOT narrate your own process or restate these instructions, and do NOT name internal layers / contract rules / tools as if the reader were the agent.",
+        "There is no implement/verify step — the answer is the deliverable.",
+    ].join("\n");
+}
+function buildQuick(input) {
+    const phaseHint = input.phase ? ` (hint: "${input.phase}")` : "";
+    return [
+        `${HEADER} This reads like a QUICK task${phaseHint} — handle it inline. Make the smallest correct change (or give the direct answer) and report what you did. No plan, no subagents.`,
+        "If, as you work, it turns out bigger than it looked — multiple files, unclear requirements — say so and switch to the STANDARD flow (short plan → check → implement → verify) instead of forcing it.",
+    ].join("\n");
+}
+export function buildDirective(input) {
+    // Informational/meta prompts answer a human — never apply the
+    // implement/verify scaffold (it agent-ifies the reply), regardless of tier.
+    const base = input.informational
+        ? { text: buildQuestion(), tier: input.tier, blocking: false }
+        : input.tier === "heavy"
+            ? { text: buildHeavy(input), tier: "heavy", blocking: true }
+            : input.tier === "standard"
+                ? { text: buildStandard(input), tier: "standard", blocking: false }
+                : { text: buildQuick(input), tier: "quick", blocking: false };
+    // Ecosystem-scoped turns get a docs-first nudge regardless of tier (question
+    // OR task): muonroi-docs is the authoritative source and must not be skipped
+    // in favour of guessing from local files (session 41ccfeb2ceee turn 1).
+    let text = base.text;
+    if (input.ecosystem) {
+        text = `${text}\n${ECOSYSTEM_DOCS_NUDGE}`;
+    }
+    // Language nudge: re-anchor the "reply in user's language" rule INSIDE the
+    // directive when the user wrote in a non-English language, so layered
+    // brevity/concise directives can't drown it (storyflow_ui 22661c8de9f2).
+    if (input.replyLanguage) {
+        text = `${text}\n${buildLanguageNudge(input.replyLanguage)}`;
+    }
+    return { ...base, text };
+}
+//# sourceMappingURL=directives.js.map