@crouton-kit/crouter 0.3.43 → 0.3.45

package/dist/core/substrate/schema.d.ts

@@ -58,6 +58,21 @@ export interface SubstrateSchema {
      *  than the node subject. Absent ⇒ no frontmatter trigger. Frontmatter key
      *  `read-when`. */
     readWhen?: GatePredicate;
+    /** Opt-in: this doc is invocable as a pi slash command (`/<name>`, `/` in a
+     *  nested name rendered as `:`). Default `false` — most docs are consulted,
+     *  not invoked. Frontmatter key `slash`. */
+    slash: boolean;
+    /** The gap this doc exists to close — the observed agent failure that
+     *  prompted it (CTO ruling 2026-07-03, `taste/document-substrate` §"Rationale
+     *  is a frontmatter field, never delivered"). MAINTAINER-FACING ONLY: excluded
+     *  from every delivered surface by construction — it is frontmatter, never
+     *  body, so it never reaches a boot render, on-read injection, or `memory
+     *  read` content output; only the raw file at `path` (or `memory read
+     *  --frontmatter`) shows it. It is NOT read-routing (`whenAndWhyToRead` owns
+     *  that) and NOT a content summary (`shortForm` owns that) — it answers
+     *  "what observed failure made this doc exist," never "why obey it." Absent
+     *  when the doc carries none. Frontmatter key `rationale`. */
+    rationale?: string;
 }
 /** A fully-resolved substrate document: the parsed schema PLUS the resolver's
  *  path-derived identity and body. This single object flows through the whole

package/dist/core/substrate/schema.js

@@ -94,6 +94,8 @@ export function parseSubstrateFrontmatter(fm) {
         gate: parseGate(fm.gate),
         appliesTo: parseAppliesTo(fm['applies-to']),
         readWhen: parseGate(fm['read-when']),
+        slash: fm.slash === true,
+        rationale: parseRationale(fm['rationale']),
     };
 }
 /** Parse a resolved MemoryDoc into a fully-typed SubstrateDoc (schema + the
@@ -121,6 +123,13 @@ export function previewLine(doc) {
 function strField(v) {
     return typeof v === 'string' ? v : '';
 }
+/** Resolve an optional `rationale` field: a non-empty string is carried as-is
+ *  (multi-line YAML block scalars parse to a plain string, so no special
+ *  handling is needed); anything else (absent, blank, non-string) yields
+ *  `undefined` — the doc simply carries no rationale. */
+function parseRationale(v) {
+    return typeof v === 'string' && v.trim() !== '' ? v : undefined;
+}
 /** Resolve a visibility field to a ladder rung, falling back to the neutral
  *  floor when absent/invalid. */
 function parseRung(v, fallback) {

package/dist/pi-extensions/canvas-structured-output.d.ts

@@ -0,0 +1,9 @@
+type PiEvents = 'before_agent_start' | 'agent_start';
+interface PiLike {
+    on: (event: PiEvents, handler: (event: any, ctx: any) => void | Promise<void>) => void;
+    registerTool: (definition: Record<string, unknown>) => void;
+    getActiveTools?: () => string[];
+    setActiveTools?: (tools: string[]) => void;
+}
+export declare function registerCanvasStructuredOutput(pi: PiLike): void;
+export default registerCanvasStructuredOutput;

package/dist/pi-extensions/canvas-structured-output.js

@@ -0,0 +1,150 @@
+// canvas-structured-output.ts — dynamic `submit` tool for schema-shaped node results.
+//
+// Loaded into every canvas node. Inert unless nodes/<id>/output-schema.json exists.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { getNode } from '../core/canvas/index.js';
+import { pushFinal, pushUpdate } from '../core/feed/feed.js';
+import { outputResultPath, readOutputRequest, removeOutputSchema, } from '../core/runtime/structured-output.js';
+function reportBody(resultPath, json) {
+    return `Structured output submitted.\n\nResult path: ${resultPath}\n\n\`\`\`json\n${json}\n\`\`\`\n`;
+}
+function activateTool(pi) {
+    try {
+        const current = pi.getActiveTools?.() ?? [];
+        if (!current.includes('submit'))
+            pi.setActiveTools?.([...current, 'submit']);
+    }
+    catch {
+        /* best-effort; registration refresh normally activates new extension tools */
+    }
+}
+function retireTool(pi) {
+    try {
+        const current = pi.getActiveTools?.() ?? [];
+        pi.setActiveTools?.(current.filter((name) => name !== 'submit'));
+    }
+    catch {
+        /* best-effort; the execute handler is inert when no schema file exists */
+    }
+}
+function toolDescription(request) {
+    if (request.mode === 'terminal') {
+        return 'Submit your final structured result. Calling this ends your run: the result is recorded and a final report is pushed automatically — do NOT call `crtr push final` yourself.';
+    }
+    return 'Submit the requested one-off structured result. Calling this records the result, pushes an update report automatically, frees you from the structured-output gate, and lets you continue working.';
+}
+export function registerCanvasStructuredOutput(pi) {
+    const nodeId = process.env['CRTR_NODE_ID'];
+    if (nodeId === undefined || nodeId.trim() === '')
+        return;
+    let registeredKey = null;
+    let active = false;
+    const ensureSubmitTool = (activate) => {
+        const request = readOutputRequest(nodeId);
+        if (request === null) {
+            if (active) {
+                active = false;
+                retireTool(pi);
+            }
+            return;
+        }
+        const key = JSON.stringify(request);
+        if (registeredKey !== key) {
+            pi.registerTool({
+                name: 'submit',
+                label: 'Submit',
+                description: toolDescription(request),
+                promptSnippet: request.mode === 'terminal'
+                    ? 'Submit the final structured result and end this node'
+                    : 'Submit the requested one-off structured result',
+                promptGuidelines: request.mode === 'terminal'
+                    ? [
+                        'Use submit as your final action when the required structured result is ready.',
+                        'After calling submit, do not call crtr push final yourself and do not emit another assistant response.',
+                    ]
+                    : [
+                        'Use submit to answer the pending one-off structured-output request before stopping or going dormant.',
+                        'After one-off submit succeeds, continue with any remaining work normally.',
+                    ],
+                parameters: request.schema,
+                async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+                    const current = readOutputRequest(nodeId);
+                    if (current === null) {
+                        return {
+                            content: [{ type: 'text', text: 'No structured output is currently requested.' }],
+                            details: { submitted: false, reason: 'no_request' },
+                        };
+                    }
+                    if (JSON.stringify(current) !== key) {
+                        registeredKey = null;
+                        ensureSubmitTool(true);
+                        return {
+                            content: [{ type: 'text', text: 'The structured-output request changed while you were working. Call submit again using the current schema.' }],
+                            details: { submitted: false, reason: 'schema_replaced' },
+                        };
+                    }
+                    const resultPath = outputResultPath(nodeId);
+                    const json = JSON.stringify(params, null, 2);
+                    mkdirSync(dirname(resultPath), { recursive: true });
+                    writeFileSync(resultPath, `${json}\n`, 'utf8');
+                    const body = reportBody(resultPath, json);
+                    if (current.mode === 'terminal') {
+                        try {
+                            await pushFinal(nodeId, body);
+                        }
+                        catch (err) {
+                            const status = getNode(nodeId)?.status;
+                            const alreadyFinalized = status === 'done' || status === 'dead' || status === 'canceled' ||
+                                (err instanceof Error && err.message.startsWith("illegal lifecycle transition: 'finalize' from status='"));
+                            if (!alreadyFinalized)
+                                throw err;
+                        }
+                        removeOutputSchema(nodeId);
+                        active = false;
+                        retireTool(pi);
+                        try {
+                            ctx?.shutdown?.();
+                        }
+                        catch { /* ignore */ }
+                        return {
+                            content: [{ type: 'text', text: `Structured output submitted and finalized: ${resultPath}` }],
+                            details: { submitted: true, mode: current.mode, resultPath, result: params },
+                            terminate: true,
+                        };
+                    }
+                    await pushUpdate(nodeId, body);
+                    removeOutputSchema(nodeId);
+                    active = false;
+                    retireTool(pi);
+                    return {
+                        content: [{ type: 'text', text: `Structured output submitted: ${resultPath}` }],
+                        details: { submitted: true, mode: current.mode, resultPath, result: params },
+                    };
+                },
+            });
+            registeredKey = key;
+        }
+        if (activate && !active) {
+            active = true;
+            activateTool(pi);
+        }
+    };
+    try {
+        ensureSubmitTool(false);
+    }
+    catch { /* malformed files are enforced by the stop-guard */ }
+    pi.on('before_agent_start', () => {
+        try {
+            ensureSubmitTool(true);
+        }
+        catch { /* keep the node alive; stop-guard will reprompt */ }
+    });
+    pi.on('agent_start', () => {
+        try {
+            ensureSubmitTool(true);
+        }
+        catch { /* keep the node alive; stop-guard will reprompt */ }
+    });
+}
+export default registerCanvasStructuredOutput;

package/dist/prompts/review.js

@@ -1,3 +1,17 @@
+/**
+ * Builds the guidance delivered to spec/plan reviewer agents.
+ *
+ * Why this exists (CTO, 2026-07-03): reviewer agents without calibration
+ * drift to rubber-stamping or nitpicking, so the decision tables force a
+ * real verdict — but the deeper point is that this reviews AGENT-written
+ * work, not generic review. Agents have a specific failure profile: a check
+ * earns a place here only when it targets a mistake agents actually make
+ * (unrequested features, placeholder sections, noise comments), and a check
+ * for something agents reliably get right (e.g. arithmetic/logic
+ * correctness) is pure noise. Maintain the checklists empirically: add a
+ * check when we observe agents failing at something, cut one that never
+ * catches anything.
+ */
 const SUBMIT_INSTRUCTIONS = `## Delivering your review
 
 When your review is complete, deliver your verdict as instructed by

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.43",
+  "version": "0.3.45",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",