muonroi-cli 1.4.1 → 1.6.0

package/dist/src/pil/__tests__/layer6-output.test.js

@@ -1,5 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
-import { applyPilSuffix, getResponseToolSet, layer6Output } from "../layer6-output.js";
+import { applyPilSuffix, getResponseToolSet, isImplementationIntent, isQuestionLike, layer6Output, } from "../layer6-output.js";
 // Mock bridge for PIL-03 classifyViaBrain tests
 vi.mock("../../ee/bridge.js", () => ({
     classifyViaBrain: vi.fn().mockResolvedValue(null),
@@ -55,6 +55,38 @@ describe("applyPilSuffix — per-task-type suffixes", () => {
             expect(result).toMatch(/Tôi sẽ/); // bilingual
         }
     });
+    it("de-robotized: NO_PREAMBLE bans only openers, not end-of-turn summary or inter-tool narration", () => {
+        // The summary + inter-tool bans were removed because they stripped natural
+        // connective tissue (the "máy móc" feel). Inter-tool spam is still removed
+        // structurally by stripInterToolNarration() in reasoning.ts. This guards
+        // against the bans silently creeping back into the system prompt.
+        const result = applyPilSuffix("S", makeCtx("debug", "concise"));
+        expect(result).toMatch(/FORBIDDEN OPENERS/);
+        expect(result).not.toMatch(/FORBIDDEN END-OF-TURN SUMMARY/);
+        expect(result).not.toMatch(/FORBIDDEN INTER-TOOL NARRATION/);
+    });
+    it("de-robotized: debug suffix is guidance, not a rigid arrow skeleton", () => {
+        // "Format = Hypothesis → Root cause → Fix → Verify" produced stilted,
+        // label-prefixed answers. It must read as guidance now.
+        const result = applyPilSuffix("S", makeCtx("debug", "concise"));
+        expect(result).toContain("OUTPUT RULES (debug)");
+        expect(result).not.toMatch(/Format = Hypothesis/);
+    });
+    it("E: appends the anti-bookkeeping note on the natural path for non-question turns", () => {
+        // The contract's REPORTING rule leaks as a provenance footer ("evidence only
+        // from this turn") on imperative answer turns; the natural path now guards it.
+        const result = applyPilSuffix("S", makeCtx("analyze", "concise"));
+        expect(result).toMatch(/WRITE FOR THE READER/);
+        expect(result).toMatch(/provenance/i);
+    });
+    it("E: skips the anti-bookkeeping note for question turns (L4 QUESTION directive covers them)", () => {
+        const ctx = { ...makeCtx("analyze", "concise"), raw: "why does the enrichment layer fail?" };
+        expect(applyPilSuffix("S", ctx)).not.toMatch(/WRITE FOR THE READER/);
+    });
+    it("E: response-tools path does not add the natural-path bookkeeping note", () => {
+        const result = applyPilSuffix("S", makeCtx("analyze", "balanced"), true);
+        expect(result).not.toMatch(/WRITE FOR THE READER/);
+    });
     it("PIL-04: response-tools path skips budget+preamble (tool already enforces structure)", () => {
         const result = applyPilSuffix("S", makeCtx("analyze", "balanced"), true);
         expect(result).toContain("respond_analyze");
@@ -74,29 +106,33 @@ describe("applyPilSuffix — per-task-type suffixes", () => {
         expect(result).toMatch(/Do NOT append an evidence-provenance footer/);
     });
 });
-describe("getResponseToolSet — PIL-04 Tier 1.1 gating", () => {
-    it("returns response tool for analyze (list-shaped, JSON wins)", () => {
-        const tools = getResponseToolSet(makeCtx("analyze", null));
+describe("getResponseToolSet — narrow gating (de-robotizing)", () => {
+    // Override raw on a typed ctx so the report/question discriminator is exercised.
+    const ctxRaw = (raw, t) => ({ ...makeCtx(t, null), raw });
+    it("returns response tool for analyze on an explicit report/list request", () => {
+        const tools = getResponseToolSet(ctxRaw("audit the orchestrator and list all cost-leak findings", "analyze"));
         expect(Object.keys(tools)).toContain("respond_analyze");
     });
-    it("returns response tool for plan (list-shaped, JSON wins)", () => {
-        const tools = getResponseToolSet(makeCtx("plan", null));
+    it("returns response tool for plan on an explicit plan request", () => {
+        const tools = getResponseToolSet(ctxRaw("plan the migration to the new auth flow step by step", "plan"));
         expect(Object.keys(tools)).toContain("respond_plan");
     });
+    it("returns response tool for debug only on an explicit report request", () => {
+        const tools = getResponseToolSet(ctxRaw("audit the failing suite and list each root cause", "debug"));
+        expect(Object.keys(tools)).toContain("respond_debug");
+    });
     it("returns empty toolset for generate (code-heavy, markdown wins)", () => {
         expect(getResponseToolSet(makeCtx("generate", null))).toEqual({});
     });
     it("returns empty toolset for refactor (diff-heavy, markdown wins)", () => {
         expect(getResponseToolSet(makeCtx("refactor", null))).toEqual({});
     });
-    it("returns response tool for debug (bounded schema, structural enforcement wins)", () => {
-        const tools = getResponseToolSet(makeCtx("debug", null));
-        expect(Object.keys(tools)).toContain("respond_debug");
-    });
     it("returns empty toolset for documentation (prose-heavy)", () => {
         expect(getResponseToolSet(makeCtx("documentation", null))).toEqual({});
     });
-    it("returns response tool for general when no providerId is passed (back-compat)", () => {
+    it("returns response tool for general regardless of report signal (renders as plain markdown)", () => {
+        // general is exempt from the report/question gate: GeneralSchema is pure text
+        // and its renderer shows plain markdown, so respond_general is never robotic.
         const tools = getResponseToolSet(makeCtx("general", null));
         expect(Object.keys(tools)).toContain("respond_general");
     });
@@ -113,24 +149,87 @@ describe("getResponseToolSet — PIL-04 Tier 1.1 gating", () => {
     it("returns empty toolset when taskType is null", () => {
         expect(getResponseToolSet(makeCtx(null, null))).toEqual({});
     });
+    it("gates the response tool for chitchat turns", () => {
+        const ctx = { ...makeCtx("general", null), intentKind: "chitchat" };
+        expect(getResponseToolSet(ctx)).toEqual({});
+    });
+    it("DROPS respond_<task> for question-style debug/analyze/plan (natural markdown path)", () => {
+        // The de-robotizing change: a plain QUESTION must not be forced into the
+        // rigid respond_* schema + labeled renderer. It falls through to the softened
+        // markdown OUTPUT RULES so the answer reads as natural prose.
+        expect(getResponseToolSet(ctxRaw("why does the build fail intermittently?", "debug"))).toEqual({});
+        expect(getResponseToolSet(ctxRaw("analyze how the enrichment function works", "analyze"))).toEqual({});
+        expect(getResponseToolSet(ctxRaw("what is the cleanest way to structure this module?", "plan"))).toEqual({});
+    });
+    it("KEEPS respond_<task> for explicit report / list / plan requests (EN + VI)", () => {
+        const keep = (raw, t) => Object.keys(getResponseToolSet(ctxRaw(raw, t)));
+        expect(keep("list all cost leaks in the orchestrator", "analyze")).toContain("respond_analyze");
+        expect(keep("review the module and report each finding by severity", "analyze")).toContain("respond_analyze");
+        expect(keep("lập kế hoạch migration sang auth flow mới", "plan")).toContain("respond_plan");
+    });
+    it("DROPS respond_<task> for a QUESTION that merely mentions plan/list (narrow-gate fix)", () => {
+        // Live bug (grok interview): a question that QUOTED the phrase "state a 2-3
+        // line plan" matched the bare word 'plan' in STRUCTURED_REPORT_RE and forced
+        // respond_plan, cramming an introspective answer into a rigid plan schema. A
+        // question-shaped prompt must stay on the natural markdown path even when it
+        // contains plan/list words.
+        expect(getResponseToolSet(ctxRaw("what rules constrain you, e.g. the 'state a 2-3 line plan' directive?", "plan"))).toEqual({});
+        expect(getResponseToolSet(ctxRaw("can you list the main points?", "analyze"))).toEqual({});
+        expect(getResponseToolSet(ctxRaw("how would you plan the rollout?", "plan"))).toEqual({});
+        // Imperative delivery requests are NOT question-shaped → still structured.
+        expect(Object.keys(getResponseToolSet(ctxRaw("plan the rollout step by step", "plan")))).toContain("respond_plan");
+    });
     it("drops respond_<task> on an IMPLEMENTATION-intent prompt (no premature terminal answer)", () => {
         // Live (grok session 19fa8895c41c): an "Improve … implement these fixes"
         // prompt classified `debug` got respond_debug; the model called it mid-task
         // as a plan and the turn ended before the edits completed. Implementation
         // turns must fall through to markdown OUTPUT RULES, not a terminal tool.
+        // Implementation intent takes precedence over a report signal.
         const impl = (raw, t) => ({ ...makeCtx(t, null), raw });
         expect(getResponseToolSet(impl("Improve the story-list screen. Implement these prioritized fixes: …", "debug"))).toEqual({});
         expect(getResponseToolSet(impl("Edit ONLY these two files and fix the empty span", "debug"))).toEqual({});
         expect(getResponseToolSet(impl("refactor the genre dropdown and wire up keyboard handlers", "analyze"))).toEqual({});
         expect(getResponseToolSet(impl("triển khai các cải tiến đã đề xuất", "plan"))).toEqual({});
     });
-    it("KEEPS respond_<task> for pure analysis/plan prompts (narrowness guard)", () => {
-        // The deliverable here IS a structured report — must not be suppressed.
-        const ana = (raw, t) => ({ ...makeCtx(t, null), raw });
-        expect(Object.keys(getResponseToolSet(ana("analyze the orchestrator for cost leaks", "analyze")))).toContain("respond_analyze");
-        expect(Object.keys(getResponseToolSet(ana("why does the build fail intermittently?", "debug")))).toContain("respond_debug");
-        expect(Object.keys(getResponseToolSet(ana("plan the migration to the new auth flow", "plan")))).toContain("respond_plan");
-        expect(Object.keys(getResponseToolSet(ana("review the auth module and explain the design", "analyze")))).toContain("respond_analyze");
+});
+describe("getResponseToolSet — Phase 2b deliverableKind consume (model overrides regex)", () => {
+    const ctxD = (raw, t, deliverableKind) => ({
+        ...makeCtx(t, null),
+        raw,
+        deliverableKind,
+    });
+    it("deliverableKind='code' DROPS respond_* even when the prompt reads as a report/list", () => {
+        // Legacy regex (prefersStructuredReport) would KEEP the tool on "list all …".
+        // The model said the deliverable is code → drop it (edits, not a report).
+        expect(getResponseToolSet(ctxD("list all cost leaks in the orchestrator", "analyze", "code"))).toEqual({});
+    });
+    it("deliverableKind='report' KEEPS respond_* even when the prompt is question-shaped", () => {
+        // Legacy regex (isQuestionLike) would DROP the tool on "why does …?". The
+        // model said the deliverable is a structured report → keep it.
+        const tools = getResponseToolSet(ctxD("why does the suite fail — break it down by cause", "analyze", "report"));
+        expect(Object.keys(tools)).toContain("respond_analyze");
+    });
+    it("deliverableKind='answer' DROPS respond_* for non-general even on a report-shaped request", () => {
+        expect(getResponseToolSet(ctxD("plan the migration step by step", "plan", "answer"))).toEqual({});
+    });
+    it("deliverableKind='answer' KEEPS respond_general (general is exempt — renders as plain markdown)", () => {
+        const tools = getResponseToolSet(ctxD("what does the enrichment layer do?", "general", "answer"));
+        expect(Object.keys(tools)).toContain("respond_general");
+    });
+    it("falls back to the legacy regex when deliverableKind is absent (null)", () => {
+        // No model signal → legacy path: question-shaped analyze drops the tool.
+        expect(getResponseToolSet({ ...makeCtx("analyze", null), raw: "why does the build fail?" })).toEqual({});
+        // …and an explicit report request keeps it.
+        expect(Object.keys(getResponseToolSet({ ...makeCtx("analyze", null), raw: "list all cost leaks" }))).toContain("respond_analyze");
+    });
+    it("DROPS respond_* on an implement turn even when mis-classified as report (session 2b7a10219499)", () => {
+        // "lên plan rồi improvement … cải thiện X" is an implement turn the model
+        // tagged deliverable=report; the report-exception used to KEEP respond_plan,
+        // so the model stated a plan and ended the turn with edits done but
+        // uncommitted/unreported. Implementation intent must suppress the terminal
+        // tool BEFORE the deliverable branch is consulted.
+        expect(getResponseToolSet(ctxD("lên plan rồi improvement nhé, focus cải thiện Compaction", "plan", "report"))).toEqual({});
+        expect(getResponseToolSet(ctxD("improve the compactor and implement the fix", "plan", "report"))).toEqual({});
     });
 });
 describe("applyPilSuffix — outputStyle variants", () => {
@@ -294,4 +393,45 @@ describe("layer6Output", () => {
         expect(result.enriched).toBe(ctx.enriched);
     });
 });
+describe("isQuestionLike — Vietnamese yes/no question frames (regression: session f6f7881a5fae)", () => {
+    it("detects the live miss: 'check ... dùng được mcp ... không nhé'", () => {
+        // The exact prompt that was mis-routed to the implement/verify scaffold.
+        expect(isQuestionLike("bạn check xem dùng được mcp muonroi-docs không nhé")).toBe(true);
+        // It is NOT an implementation intent, so layer4-gsd's informational gate fires.
+        expect(isImplementationIntent("bạn check xem dùng được mcp muonroi-docs không nhé")).toBe(false);
+    });
+    it("detects common VI yes/no tails", () => {
+        expect(isQuestionLike("dùng được không")).toBe(true);
+        expect(isQuestionLike("cái này chạy được không vậy")).toBe(true);
+        expect(isQuestionLike("đúng không")).toBe(true);
+        expect(isQuestionLike("phải không nhỉ")).toBe(true);
+        expect(isQuestionLike("test đã pass chưa")).toBe(true);
+        expect(isQuestionLike("xong chưa ạ")).toBe(true);
+        expect(isQuestionLike("có chạy được không?")).toBe(true);
+    });
+    it("does NOT treat a mid-sentence negation as a question", () => {
+        // "không là hỏng" = "or it breaks" — 'không' is not the clause-final particle.
+        expect(isQuestionLike("đừng commit file .env không là lộ key")).toBe(false);
+        // Plain imperative with a 'nhé' softener (no 'không'/'chưa' tail) stays a task.
+        expect(isQuestionLike("sửa giúp tôi cái này nhé")).toBe(false);
+        expect(isQuestionLike("triển khai tính năng login")).toBe(false);
+    });
+    it("still detects the pre-existing EN/VI question shapes", () => {
+        expect(isQuestionLike("why does the build fail?")).toBe(true);
+        expect(isQuestionLike("tại sao build lỗi")).toBe(true);
+        expect(isQuestionLike("explain the pipeline")).toBe(true);
+    });
+});
+describe("isImplementationIntent — improve / cải thiện (regression: session 2b7a10219499)", () => {
+    it("recognises improve/improvement + VI cải thiện as implement turns", () => {
+        expect(isImplementationIntent("improve the compactor")).toBe(true);
+        expect(isImplementationIntent("lên plan rồi improvement nhé")).toBe(true);
+        expect(isImplementationIntent("focus cải thiện Compaction")).toBe(true);
+        expect(isImplementationIntent("cai thien phan compaction")).toBe(true);
+    });
+    it("does not over-match analysis questions that merely describe behaviour", () => {
+        expect(isImplementationIntent("what does the enrichment layer do?")).toBe(false);
+        expect(isImplementationIntent("why does the suite fail — break it down")).toBe(false);
+    });
+});
 //# sourceMappingURL=layer6-output.test.js.map

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

@@ -23,6 +23,32 @@ describe("createLlmClassifier (PIL Layer 1 Pass 4)", () => {
         expect(result?.outputStyle).toBe("concise");
         expect(result?.confidence).toBeGreaterThan(0.5);
     });
+    it("parses the three-word reply and marks chitchat from the intent word", async () => {
+        const handle = installMockModel({ fixture: { stream: textOnlyStream("general,concise,chat") } });
+        cleanup = handle.uninstall;
+        const factory = (() => handle.model);
+        const classify = createLlmClassifier(factory, "deepseek-v4-flash");
+        const result = await classify("cảm ơn bạn nhé");
+        expect(result?.taskType).toBe("general");
+        expect(result?.intentKind).toBe("chitchat");
+    });
+    it("treats a general QUESTION as task, not chitchat (keep-tools)", async () => {
+        const handle = installMockModel({ fixture: { stream: textOnlyStream("general,concise,task") } });
+        cleanup = handle.uninstall;
+        const factory = (() => handle.model);
+        const classify = createLlmClassifier(factory, "deepseek-v4-flash");
+        const result = await classify("bạn thử call tool setup_guide xem được không");
+        expect(result?.intentKind).toBe("task");
+    });
+    it("defaults intentKind to task when the model omits the third word (backward compatible)", async () => {
+        const handle = installMockModel({ fixture: { stream: textOnlyStream("debug,concise") } });
+        cleanup = handle.uninstall;
+        const factory = (() => handle.model);
+        const classify = createLlmClassifier(factory, "deepseek-v4-flash");
+        const result = await classify("fix the failing build");
+        expect(result?.taskType).toBe("debug");
+        expect(result?.intentKind).toBe("task");
+    });
     it("returns null when the reply cannot be parsed", async () => {
         const handle = installMockModel({ fixture: { stream: textOnlyStream("¯\\_(ツ)_/¯") } });
         cleanup = handle.uninstall;
@@ -100,14 +126,35 @@ describe("createLlmClassifier (PIL Layer 1 Pass 4)", () => {
         expect(result?.taskType).toBe("debug");
         expect(result?.outputStyle).toBe("concise");
     });
-    it("keeps the tiny 16-token budget for non-reasoning models", async () => {
+    it("keeps a tiny output budget for non-reasoning models (24 — four comma words)", async () => {
         const handle = installMockModel({ fixture: { stream: textOnlyStream("generate,concise") } });
         cleanup = handle.uninstall;
         const factory = (() => handle.model);
         const classify = createLlmClassifier(factory, "Qwen/Qwen3-8B"); // reasoning:false
         await classify("add a new endpoint");
         const call = handle.calls[0];
-        expect(call.maxOutputTokens).toBe(16);
+        expect(call.maxOutputTokens).toBe(24);
+    });
+    it("parses the fourth word as the output deliverable (Phase 2b)", async () => {
+        const handle = installMockModel({ fixture: { stream: textOnlyStream("debug,concise,task,code") } });
+        cleanup = handle.uninstall;
+        const factory = (() => handle.model);
+        const classify = createLlmClassifier(factory, "deepseek-v4-flash");
+        const result = await classify("fix the crash in src/auth/login.ts");
+        expect(result?.taskType).toBe("debug");
+        expect(result?.deliverableKind).toBe("code");
+    });
+    it("recovers the deliverable position-independently and defaults to null when absent", async () => {
+        const reportHandle = installMockModel({ fixture: { stream: textOnlyStream("analyze,concise,task,report") } });
+        cleanup = reportHandle.uninstall;
+        const reportClassify = createLlmClassifier((() => reportHandle.model), "deepseek-v4-flash");
+        expect((await reportClassify("list every env var the CLI reads"))?.deliverableKind).toBe("report");
+        reportHandle.uninstall();
+        // Model omits the 4th word → deliverableKind null (consumers fall back to regex).
+        const bareHandle = installMockModel({ fixture: { stream: textOnlyStream("debug,concise") } });
+        cleanup = bareHandle.uninstall;
+        const bareClassify = createLlmClassifier((() => bareHandle.model), "deepseek-v4-flash");
+        expect((await bareClassify("fix it"))?.deliverableKind).toBeNull();
     });
 });
 //# sourceMappingURL=llm-classify.test.js.map

package/dist/src/pil/__tests__/surface-compaction-artifacts.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/pil/__tests__/surface-compaction-artifacts.test.js

@@ -0,0 +1,112 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import { surfaceCompactionArtifacts } from "../layer3-ee-injection.js";
+// Issue #4 — targeted complement to layer3's checkpoint arm on meta turns.
+// layer3 (now run on meta after issue #2) surfaces checkpoints via a FIXED
+// recency query; this arm searches by the meta question (ctx.raw) to surface the
+// elided tool-artifacts relevant to it, and DEFERS when layer3 already injected a
+// checkpoint block. Mock the EE search + the audit log so the test stays offline.
+vi.mock("../../ee/bridge.js", () => ({
+    searchByText: vi.fn().mockResolvedValue([]),
+}));
+vi.mock("../../storage/interaction-log.js", () => ({
+    logInteraction: vi.fn(),
+}));
+import { searchByText } from "../../ee/bridge.js";
+function makeCtx(overrides = {}) {
+    return {
+        raw: "compaction cần cải thiện gì trong CLI",
+        enriched: "compaction cần cải thiện gì trong CLI",
+        taskType: "general",
+        domain: null,
+        confidence: 0.85,
+        outputStyle: "balanced",
+        tokenBudget: 2000,
+        metrics: null,
+        layers: [],
+        sessionId: "sess-meta-1",
+        ...overrides,
+    };
+}
+const artifactPoint = {
+    id: "art1",
+    score: 0.9,
+    payload: {
+        text: "tool-artifact id=call_7 toolName=read_file elided 4200 chars: src/orchestrator/compaction.ts createCompactionSummaryMessage ...",
+    },
+    collection: "experience-behavioral",
+};
+const checkpointPoint = {
+    id: "cp1",
+    score: 0.8,
+    payload: { text: "Context checkpoint summary ✔ DONE: extended IMPORTANT_TOOL_NAMES; tests 16/16" },
+    collection: "experience-behavioral",
+};
+const genericPoint = {
+    id: "gen1",
+    score: 0.97,
+    payload: { text: "Always run the full test suite before pushing" },
+    collection: "experience-behavioral",
+};
+describe("surfaceCompactionArtifacts (issue #4 — meta-turn auto-surface)", () => {
+    beforeEach(() => {
+        vi.mocked(searchByText).mockReset();
+        vi.mocked(searchByText).mockResolvedValue([]);
+    });
+    test("auto-surfaces [artifact] + checkpoint refs (and the rehydrate instruction) into enriched", async () => {
+        // biome-ignore lint/suspicious/noExplicitAny: test fixture shape mirrors EEPoint
+        vi.mocked(searchByText).mockResolvedValue([artifactPoint, checkpointPoint]);
+        const ctx = makeCtx();
+        const out = await surfaceCompactionArtifacts(ctx);
+        expect(out.enriched).toContain("[artifact]"); // artifact-typed line
+        expect(out.enriched).toContain("ee.query tool"); // how to rehydrate the full output
+        expect(out.enriched).toContain("call_7"); // the concrete tool-artifact id the agent can fetch
+        const layer = out.layers.find((l) => l.name === "ee-meta-artifacts");
+        expect(layer?.applied).toBe(true);
+        expect(layer?.delta).toContain("artifacts=2");
+        // Searches only the behavioral collection (where tool-artifacts are persisted).
+        expect(vi.mocked(searchByText)).toHaveBeenCalledWith(expect.stringContaining("tool-artifact"), ["experience-behavioral"], expect.any(Number), expect.any(Object));
+    });
+    test("no sessionId → unchanged, no EE call (no prior compaction to rehydrate)", async () => {
+        const ctx = makeCtx({ sessionId: undefined });
+        const out = await surfaceCompactionArtifacts(ctx);
+        expect(out.enriched).toBe(ctx.enriched);
+        expect(out.layers.find((l) => l.name === "ee-meta-artifacts")?.delta).toBe("no-session");
+        expect(vi.mocked(searchByText)).not.toHaveBeenCalled();
+    });
+    test("search failure is fail-open + recorded (delta=error=…, enriched unchanged)", async () => {
+        vi.mocked(searchByText).mockRejectedValue(new Error("EE down"));
+        const ctx = makeCtx();
+        const out = await surfaceCompactionArtifacts(ctx);
+        expect(out.enriched).toBe(ctx.enriched);
+        expect(out.layers.find((l) => l.name === "ee-meta-artifacts")?.delta).toMatch(/^error=/);
+    });
+    test("generic behavioral hits are filtered out (not mislabelled as artifacts)", async () => {
+        // biome-ignore lint/suspicious/noExplicitAny: test fixture shape mirrors EEPoint
+        vi.mocked(searchByText).mockResolvedValue([genericPoint]);
+        const ctx = makeCtx();
+        const out = await surfaceCompactionArtifacts(ctx);
+        expect(out.enriched).toBe(ctx.enriched);
+        expect(out.layers.find((l) => l.name === "ee-meta-artifacts")?.delta).toBe("no-artifacts");
+    });
+    test("defers to layer3 — skips with NO EE call when a checkpoint block is already present", async () => {
+        // layer3 ran first this turn and injected a checkpoint block (its marker is
+        // in enriched). The complement must not duplicate it or pay a 2nd round-trip.
+        const enriched = `${makeCtx().raw}\n[task checkpoints …]\n<!-- ee-checkpoint-injected:0123456789abcdef -->`;
+        const out = await surfaceCompactionArtifacts(makeCtx({ enriched }));
+        expect(out.layers.find((l) => l.name === "ee-meta-artifacts")?.delta).toBe("already-surfaced");
+        expect(out.enriched).toBe(enriched); // unchanged
+        expect(vi.mocked(searchByText)).not.toHaveBeenCalled();
+    });
+    test("idempotent — a second pass on its own output defers (marker it wrote is seen)", async () => {
+        // biome-ignore lint/suspicious/noExplicitAny: test fixture shape mirrors EEPoint
+        vi.mocked(searchByText).mockResolvedValue([artifactPoint]);
+        const first = await surfaceCompactionArtifacts(makeCtx());
+        expect(first.enriched).toContain("[artifact]");
+        expect(vi.mocked(searchByText)).toHaveBeenCalledTimes(1);
+        const second = await surfaceCompactionArtifacts(makeCtx({ enriched: first.enriched }));
+        expect(second.layers.find((l) => l.name === "ee-meta-artifacts")?.delta).toBe("already-surfaced");
+        expect(second.enriched).toBe(first.enriched); // not grown a second time
+        expect(vi.mocked(searchByText)).toHaveBeenCalledTimes(1); // no second round-trip
+    });
+});
+//# sourceMappingURL=surface-compaction-artifacts.test.js.map

package/dist/src/pil/agent-operating-contract.d.ts

@@ -37,7 +37,7 @@
  * one imperative line targeting that phase's most damaging failure mode. Kept
  * tight (primacy matters more than detail; tokens are the cost).
  */
-export declare const AGENT_OPERATING_CONTRACT = "[AGENT OPERATING CONTRACT \u2014 read first; applies to every step]\n\n1. BEFORE ACTING: do only what was asked. Never assume scope or facts \u2014 if ambiguous, ask or use defaults; never invent requirements.\n2. READING: base statements on what you read/ran THIS turn. Do not infer contents of files you did not open.\n3. EXECUTING: smallest correct change; never widen scope or mask failures (no `|| true`, skipped tests, or swallowed catch).\n4. WHEN UNSURE: verify and cross-check BEFORE concluding. Bugs need a reproduction; reading code is not proof.\n5. REPORTING: answer ONLY what was asked. Every fact or file:line MUST come from this turn; else label \"unverified\"; do not guess. Synthesize evidence gracefully \u2014 do NOT dump massive verbatim tool outputs into the final answer. Cite concise file:line references. Never claim a build/test ran, or describe edits, you did not actually do this turn; if a check can't run, fix it or say so \u2014 don't imply success.\n\n6. LANGUAGE: Reply in user's detected language for final output. Internal reasoning, tools, and code remain in English.\n\n7. ANTI-M\u00D9 / COMPACTION: After seeing \"[pre-compaction warning at step...\" or \"[context compacted at step...\", decide if you need full prior tool results. Emit PRESERVE_FULL_CONTEXT for full veto this turn, or the lighter KEEP_TOOL_IDS: id1,id2 (ids from prior stub \"(id=...)\") to protect only high-value results (read_file/grep on src/PLAN/error etc are auto-protected). Use the ee_query tool with \"tool-artifact id=XXX\" for on-demand full re-hydrate of elided ones. Self-check \"task finished?\" / \"compacted yet?\". Use EE checkpoints.\n\n[END CONTRACT \u2014 instructions follow]";
+export declare const AGENT_OPERATING_CONTRACT = "[AGENT OPERATING CONTRACT \u2014 read first; applies to every step]\n\n1. BEFORE ACTING: do only what was asked. Never assume scope or facts \u2014 if ambiguous, ask or use defaults; never invent requirements.\n2. READING: base statements on what you read/ran THIS turn. Do not infer contents of files you did not open.\n3. EXECUTING: smallest correct change; never widen scope or mask failures (no `|| true`, skipped tests, or swallowed catch).\n4. WHEN UNSURE: verify and cross-check BEFORE concluding. Bugs need a reproduction; reading code is not proof.\n5. REPORTING: answer ONLY what was asked. Every fact or file:line MUST come from this turn; else label \"unverified\"; do not guess. Synthesize evidence gracefully \u2014 do NOT dump massive verbatim tool outputs into the final answer. Cite concise file:line references. Never claim a build/test ran, or describe edits, you did not actually do this turn; if a check can't run, fix it or say so \u2014 don't imply success.\n\n6. LANGUAGE: Reply in user's detected language for final output. Internal reasoning, tools, and code remain in English.\n\n7. ANTI-M\u00D9 / COMPACTION: After seeing \"[pre-compaction warning at step...\" or \"[context compacted at step...\", decide if you need full prior tool results. Emit PRESERVE_FULL_CONTEXT for full veto this turn, or the lighter KEEP_TOOL_IDS: id1,id2 (ids from prior stub \"(id=...)\") to protect only high-value results (read_file/grep on src/PLAN/error etc are auto-protected). Use the ee_query tool with \"tool-artifact id=XXX\" for on-demand full re-hydrate of elided ones. Self-check \"task finished?\" / \"compacted yet?\". Use EE checkpoints.\n\n8. GIT SAFETY: never push on red \u2014 run the check, await its result in a SEPARATE step, confirm 0 failures, then push. Never `git add -A`/`commit -a`; stage explicitly so secrets (.env, .muonroi-cli/, keys) aren't committed. Never `--no-verify`.\n\n[END CONTRACT \u2014 instructions follow]";
 export interface ContractSectionOptions {
     /** Chitchat turns carry no tools and make no factual claims — skip the contract. */
     chitchat?: boolean;

package/dist/src/pil/agent-operating-contract.js

@@ -49,6 +49,8 @@ export const AGENT_OPERATING_CONTRACT = `[AGENT OPERATING CONTRACT — read firs
 
 7. ANTI-MÙ / COMPACTION: After seeing "[pre-compaction warning at step..." or "[context compacted at step...", decide if you need full prior tool results. Emit PRESERVE_FULL_CONTEXT for full veto this turn, or the lighter KEEP_TOOL_IDS: id1,id2 (ids from prior stub "(id=...)") to protect only high-value results (read_file/grep on src/PLAN/error etc are auto-protected). Use the ee_query tool with "tool-artifact id=XXX" for on-demand full re-hydrate of elided ones. Self-check "task finished?" / "compacted yet?". Use EE checkpoints.
 
+8. GIT SAFETY: never push on red — run the check, await its result in a SEPARATE step, confirm 0 failures, then push. Never \`git add -A\`/\`commit -a\`; stage explicitly so secrets (.env, .muonroi-cli/, keys) aren't committed. Never \`--no-verify\`.
+
 [END CONTRACT — instructions follow]`;
 /**
  * Build the contract block for insertion at the front of the system prompt.

package/dist/src/pil/agent-operating-contract.test.js

@@ -42,8 +42,13 @@ describe("AGENT_OPERATING_CONTRACT", () => {
         expect(AGENT_OPERATING_CONTRACT).toMatch(/AGENT OPERATING CONTRACT/i);
         expect(AGENT_OPERATING_CONTRACT).toMatch(/END CONTRACT/i);
     });
-    it("stays compact (under 1800 chars) to preserve attention budget on every turn (anti-mù section added)", () => {
-        expect(AGENT_OPERATING_CONTRACT.length).toBeLessThan(1800);
+    it("carries the git-safety rule (never push on red; no broad git add of secrets)", () => {
+        expect(AGENT_OPERATING_CONTRACT).toMatch(/GIT SAFETY/i);
+        expect(AGENT_OPERATING_CONTRACT).toMatch(/push on red|never push/i);
+        expect(AGENT_OPERATING_CONTRACT).toMatch(/git add -A|stage explicitly/i);
+    });
+    it("stays compact (under 1900 chars) to preserve attention budget on every turn (git-safety rule added)", () => {
+        expect(AGENT_OPERATING_CONTRACT.length).toBeLessThan(1900);
     });
 });
 describe("buildContractSection", () => {

package/dist/src/pil/cheap-model-playbook.js

@@ -25,41 +25,41 @@
  * Wrapped with the `[CRITICAL TOOL-USE RULES ...]` marker so the model knows
  * to treat these as overrides to anything that follows.
  */
-export const CHEAP_MODEL_PLAYBOOK = `[CRITICAL TOOL-USE RULES — read before invoking any tool; these override defaults that follow]
-
-1. Bash output is AUTOMATICALLY cached. Every \`bash\` call returns a \`run_id\`
-   (e.g. \`bash-1\`) you can re-query via \`bash_output_get(run_id, mode=tail|head|grep|lines)\`.
-   - When you want only the last N lines: do NOT pipe \`| tail -N\`. Run the
-     bare command, then call \`bash_output_get(run_id, mode=tail, lines=N)\`.
-   - Same for \`| head\`, \`| grep PATTERN\`, \`> file\`. Pipes/redirects HIDE
-     the full output from the cache; \`bash_output_get\` reads from the cache
-     without re-running.
-   - This applies to EVERY bash call, not just retries.
-   - To VIEW a file use \`read_file\` (start_line/end_line) — never sed/cat a
-     file. \`bash_output_get\` is for COMMAND output, not files.
-
-2. Before reading more than 3 files to understand a topic, delegate to
-   \`task(agent="explore")\`. The sub-agent returns a compressed summary;
-   you save reading tokens.
-
-3. Use the \`grep\` tool (ripgrep) for content search — NOT \`bash\` with
-   \`grep\` / \`find\` piped.
-
-4. When a tool returns \`ERROR: ...\`, do NOT retry the identical call.
-   Pick a different tool, change inputs meaningfully, or stop and report.
-
-5. Fix the ROOT CAUSE, never mask a failure to make it "pass"
-   (\`continue-on-error\`, swallowed try/catch, skipped/deleted test, \`|| true\`).
-   If a step fails from a missing secret/config, make it CONDITIONAL (skip when
-   absent) so it still runs when present — do NOT blanket-ignore it.
-
-6. For a build / CI / test failure, read the ACTUAL failure log or stack trace
-   BEFORE hypothesizing — fix the real error, not a guess from source alone.
-
-7. ANTI-MÙ / COMPACTION (for long sessions): On pre-warn or "[context compacted at step...", emit PRESERVE_FULL_CONTEXT (full veto) or lighter KEEP_TOOL_IDS: id1,id2 (from stub id=) to protect specific high-value results. read_file/grep/lsp/bash on src/PLAN/error are auto-kept (idea 1). Use ee.query tool with "tool-artifact id=XXX" for on-demand full. Self-check "task finished?" / "compacted yet?". Use EE checkpoints.
-
-[END CRITICAL TOOL-USE RULES — your regular instructions begin below]
-
+export const CHEAP_MODEL_PLAYBOOK = `[CRITICAL TOOL-USE RULES — read before invoking any tool; these override defaults that follow]
+
+1. Bash output is AUTOMATICALLY cached. Every \`bash\` call returns a \`run_id\`
+   (e.g. \`bash-1\`) you can re-query via \`bash_output_get(run_id, mode=tail|head|grep|lines)\`.
+   - When you want only the last N lines: do NOT pipe \`| tail -N\`. Run the
+     bare command, then call \`bash_output_get(run_id, mode=tail, lines=N)\`.
+   - Same for \`| head\`, \`| grep PATTERN\`, \`> file\`. Pipes/redirects HIDE
+     the full output from the cache; \`bash_output_get\` reads from the cache
+     without re-running.
+   - This applies to EVERY bash call, not just retries.
+   - To VIEW a file use \`read_file\` (start_line/end_line) — never sed/cat a
+     file. \`bash_output_get\` is for COMMAND output, not files.
+
+2. Before reading more than 3 files to understand a topic, delegate to
+   \`task(agent="explore")\`. The sub-agent returns a compressed summary;
+   you save reading tokens.
+
+3. Use the \`grep\` tool (ripgrep) for content search — NOT \`bash\` with
+   \`grep\` / \`find\` piped.
+
+4. When a tool returns \`ERROR: ...\`, do NOT retry the identical call.
+   Pick a different tool, change inputs meaningfully, or stop and report.
+
+5. Fix the ROOT CAUSE, never mask a failure to make it "pass"
+   (\`continue-on-error\`, swallowed try/catch, skipped/deleted test, \`|| true\`).
+   If a step fails from a missing secret/config, make it CONDITIONAL (skip when
+   absent) so it still runs when present — do NOT blanket-ignore it.
+
+6. For a build / CI / test failure, read the ACTUAL failure log or stack trace
+   BEFORE hypothesizing — fix the real error, not a guess from source alone.
+
+7. ANTI-MÙ / COMPACTION (for long sessions): On pre-warn or "[context compacted at step...", emit PRESERVE_FULL_CONTEXT (full veto) or lighter KEEP_TOOL_IDS: id1,id2 (from stub id=) to protect specific high-value results. read_file/grep/lsp/bash on src/PLAN/error are auto-kept (idea 1). Use ee.query tool with "tool-artifact id=XXX" for on-demand full. Self-check "task finished?" / "compacted yet?". Use EE checkpoints.
+
+[END CRITICAL TOOL-USE RULES — your regular instructions begin below]
+
 `;
 /**
  * Predicate gating playbook injection.

package/dist/src/pil/cheap-model-workbooks.js

@@ -23,19 +23,19 @@
  * Universal anti-ramble convergence block — applies to every task type.
  * Kept tight; the per-task addendum below specialises it.
  */
-export const CHEAP_MODEL_CONVERGENCE = `[CONVERGENCE — minimise tool calls; the system prompt + tools are re-sent every call, so each extra step is expensive]
-
-- Plan the FEWEST reads you need, then read the specific file/section directly.
-  Do NOT broad-grep, re-read a file you already read, or explore "just in case".
-- The moment you have enough to act, STOP investigating and make the change.
-- Make the SMALLEST correct change for the request; do not widen scope.
-- Finish the action before you answer — never stop mid-step (e.g. "I'm verifying…").
-  When done, state completion in ONE line (what changed + that it's verified);
-  no recap, no next-steps padding.
-- GROUND every claim in what you actually read or ran THIS turn: cite real
-  file:line, and never invent counts, line numbers, names, or bugs. If a number
-  (test/file count) is not verified by a command you ran, run the check or mark
-  it "unverified" — do NOT guess a value or assert a finding you did not observe.
+export const CHEAP_MODEL_CONVERGENCE = `[CONVERGENCE — minimise tool calls; the system prompt + tools are re-sent every call, so each extra step is expensive]
+
+- Plan the FEWEST reads you need, then read the specific file/section directly.
+  Do NOT broad-grep, re-read a file you already read, or explore "just in case".
+- The moment you have enough to act, STOP investigating and make the change.
+- Make the SMALLEST correct change for the request; do not widen scope.
+- Finish the action before you answer — never stop mid-step (e.g. "I'm verifying…").
+  When done, state completion in ONE line (what changed + that it's verified);
+  no recap, no next-steps padding.
+- GROUND every claim in what you actually read or ran THIS turn: cite real
+  file:line, and never invent counts, line numbers, names, or bugs. If a number
+  (test/file count) is not verified by a command you ran, run the check or mark
+  it "unverified" — do NOT guess a value or assert a finding you did not observe.
 - ANTI-MÙ: After compaction note or pre-warn, emit PRESERVE_FULL_CONTEXT (full) or KEEP_TOOL_IDS: id1,id2 to protect high-value (auto for read_file/grep on src/PLAN/error). Use the ee_query tool with "tool-artifact id=XXX" for on-demand full re-hydrate. Recall checkpoints. `;
 /**
  * Per-task-type addenda. Each is 1–2 tight lines targeting that type's most
@@ -47,6 +47,9 @@ const TASK_WORKBOOKS = {
         "Never mask a failure to make it pass (no continue-on-error, swallowed catch, skipped test, `|| true`).",
     generate: "GENERATE: confirm the target file + the surrounding pattern, write the new code to match it, then stop. " +
         "Do not scaffold extras or restructure unrelated code.",
+    build: "BUILD: scaffold the MINIMUM runnable project/feature that satisfies the request, matching the chosen stack's " +
+        "conventions. Wire it end-to-end and verify it builds/runs before stopping. Do NOT add speculative features, " +
+        "extra files, or config the request did not ask for.",
     refactor: "REFACTOR: change only what was named (rename/extract/move). Preserve behaviour; add nothing new.",
     analyze: "ANALYZE: answer from what you have already read — do not read the whole codebase. Bullet findings, no narrative. " +
         "For a repo/code review, base findings on the ACTUAL code you inspect (file sizes, structure, key modules), not just AGENTS.md/CLAUDE.md docs.",