@davidorex/pi-jit-agents 0.14.6 → 0.28.0

package/dist/template.js

@@ -18,7 +18,27 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { tryResolveContextDir } from "@davidorex/pi-context/context-dir";
 import nunjucks from "nunjucks";
+/**
+ * Absolute path to this package's bundled `templates/` directory — the canonical
+ * package-layer root for the 3-tier template search (tier 3 / builtinDir).
+ *
+ * Per DEC-0049 uniform-agent axiom, agent-prompt rendering assets (per-item
+ * macros + whole-block delegators + per-agent template directories) live in
+ * pi-jit-agents. Consumers (pi-workflows, pi-behavior-monitors, pi-agent-
+ * dispatch) import this function rather than computing their own
+ * package-relative paths.
+ *
+ * Resolves via `import.meta.url` so the path works under both source and
+ * built (dist) modes — the dist/ directory and the src/ directory sit at the
+ * same depth relative to the package root.
+ */
+export function bundledTemplateDir() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(here, "..", "templates");
+}
 /**
  * Create a Nunjucks environment with three-tier template discovery.
  *
@@ -27,11 +47,17 @@ import nunjucks from "nunjucks";
  * inline prompt uses no templates at all.
  */
 export function createTemplateEnv(ctx) {
-    const projectDir = path.join(ctx.cwd, ".project", "templates");
     const userDir = ctx.userDir ?? path.join(os.homedir(), ".pi", "agent", "templates");
     const searchPaths = [];
-    if (fs.existsSync(projectDir))
-        searchPaths.push(projectDir);
+    // Project tier (FGAP-074 C3): pointer-less repos omit it; user/builtin tiers
+    // unaffected. `contextTemplatesDir(cwd)` was `<contextDir>/templates`, so the
+    // inline equivalent is `path.join(base, "templates")`.
+    const base = tryResolveContextDir(ctx.cwd);
+    if (base !== null) {
+        const projectTemplates = path.join(base, "templates");
+        if (fs.existsSync(projectTemplates))
+            searchPaths.push(projectTemplates);
+    }
     if (fs.existsSync(userDir))
         searchPaths.push(userDir);
     if (ctx.builtinDir && fs.existsSync(ctx.builtinDir))

package/dist/template.js.map

@@ -1 +1 @@
-{"version":3,"file":"template.js","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,QAAQ,MAAM,UAAU,CAAC;AAWhC;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAuB;IACxD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC;IAC/D,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;IAEpF,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC5D,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACtD,IAAI,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC;QAAE,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAEtF,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAE/F,OAAO,IAAI,QAAQ,CAAC,WAAW,CAAC,MAAM,EAAE;QACvC,UAAU,EAAE,KAAK;QACjB,gBAAgB,EAAE,KAAK;KACvB,CAAC,CAAC;AACJ,CAAC;AAED,sFAAsF;AACtF,MAAM,yBAAyB,GAAG,0BAA0B,CAAC;AAE7D,SAAS,YAAY,CAAC,CAAS;IAC9B,OAAO,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AACjD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC7B,GAAyB,EACzB,WAAmB,EACnB,OAAgC;IAEhC,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,SAAS,EAAE,yBAAyB,CAAC,CAAC;IAC1E,MAAM,QAAQ,GAAG,GAAG,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACpD,OAAO,QAAQ,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,YAAY,CAAC,yBAAyB,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;AAC1F,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CACjC,GAAyB,EACzB,YAAoB,EACpB,OAAgC;IAEhC,IAAI,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACvD,OAAO,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,GAAG,CAAC,MAAM,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC"}
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":"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"}

package/dist/trace-redactor.d.ts

@@ -39,5 +39,5 @@ export declare function redactLlmResponse<T extends {
  * Compiles each `regex` string to a RegExp with the `g` flag.
  * Throws if the file does not exist, parses to invalid JSON, or contains malformed entries.
  */
-export declare function loadProjectRedactionConfig(configPath: string): RedactionPattern[];
+export declare function loadContextRedactionConfig(configPath: string): RedactionPattern[];
 //# sourceMappingURL=trace-redactor.d.ts.map

package/dist/trace-redactor.js

@@ -123,7 +123,7 @@ function redactContentItem(item, config) {
  * Compiles each `regex` string to a RegExp with the `g` flag.
  * Throws if the file does not exist, parses to invalid JSON, or contains malformed entries.
  */
-export function loadProjectRedactionConfig(configPath) {
+export function loadContextRedactionConfig(configPath) {
     if (!existsSync(configPath)) {
         throw new Error(`trace redaction config not found: ${configPath}`);
     }

package/dist/trace-writer.js

@@ -15,7 +15,7 @@
 //     pi-coding-agent's transitive dependency tree). Node 23.x exposes node:fs flockSync as
 //     `undefined` in the version this repo targets, so the userspace lockfile approach is
 //     the working option; the lock is held only for the duration of the append.
-//   - Schema validation reuses validateFromFile from @davidorex/pi-project/schema-validator
+//   - Schema validation reuses validateFromFile from @davidorex/pi-context/schema-validator
 //     so the AJV runtime, error format, and ESM/CJS interop shim live in one place.
 //
 // Size-rotation strategy:
@@ -26,7 +26,7 @@
 import { appendFileSync, existsSync, mkdirSync, statSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { validateFromFile } from "@davidorex/pi-project/schema-validator";
+import { validateFromFile } from "@davidorex/pi-context/schema-validator";
 // proper-lockfile is CommonJS — under Node16 module resolution + ESM consumer the default
 // import resolves to the module namespace, so lockSync hangs off the default export.
 import _properLockfile from "proper-lockfile";

package/dist/types.d.ts

@@ -4,8 +4,11 @@
  * Implements the jit-agents-spec.md §2 boundary contract: four public surfaces
  * (load, compile, execute, introspect) with typed inputs and outputs.
  */
-import type { Api, AssistantMessage, Model } from "@mariozechner/pi-ai";
+import type { ItemLocation } from "@davidorex/pi-context";
+import type { Api, AssistantMessage, Model } from "@earendil-works/pi-ai";
 import type nunjucks from "nunjucks";
+import type { BudgetWarning } from "./budget-enforcer.js";
+import type { RendererRegistry } from "./renderer-registry.js";
 /**
  * A loaded agent specification.
  *
@@ -39,13 +42,50 @@ export interface AgentSpec {
      * against the invocation cwd.
      */
     outputSchema?: string;
-    contextBlocks?: string[];
+    /**
+     * Block-context references injected into the agent's template environment.
+     *
+     * Two element shapes are accepted:
+     *
+     * - **Bare string** (e.g. `"requirements"`): whole-block injection — the
+     *   entire `.project/<name>.json` payload is read at compile time and
+     *   surfaced to the template under `_<name>`. This is the established
+     *   surface and remains unchanged for existing specs.
+     *
+     * - **Object** ({@link ContextBlockRef}): per-item or scoped injection —
+     *   declares a specific item id and/or kind-specific focus hints to be
+     *   resolved by the compile-time injector. Plan 4 (Wave 2) owns the
+     *   resolution semantics; the parser only typechecks the shape here.
+     */
+    contextBlocks?: (string | ContextBlockRef)[];
     /**
      * Directory the spec was loaded from. Internal use — exposed on the type
      * for tier-aware operations but never relied on by consumers directly.
      */
     readonly loadedFrom: string;
 }
+/**
+ * Typed object form for {@link AgentSpec.contextBlocks} entries.
+ *
+ * Bare-string entries in `contextBlocks` denote whole-block injection
+ * (existing behaviour); object entries denote per-item or scoped injection
+ * — the surface Plan 4 (Wave 2) consumes to inject specific block items
+ * (e.g. one decision, one feature) rather than entire blocks.
+ *
+ * `compileAgent` does not yet honour these fields; this interface defines
+ * the parsing-time contract only. Plan 4 wires resolution through the
+ * cross-block resolver and per-item macros.
+ */
+export interface ContextBlockRef {
+    /** Block name, e.g. "decisions", "features". Required. */
+    name: string;
+    /** Optional ID of a specific item to inject. Plan 4 resolves via cross-block resolver. */
+    item?: string;
+    /** Optional kind-specific scope hints (e.g., { story: "STORY-001" }). Plan 4 passes through to macros. */
+    focus?: Record<string, string>;
+    /** Optional traversal depth. 0 = bare-ID refs (default), 1 = inline direct, 2+ recurse. */
+    depth?: number;
+}
 /**
  * Options for loadAgent / createAgentLoader.
  *
@@ -66,6 +106,10 @@ export interface LoadContext {
 }
 /**
  * Options for compileAgent.
+ *
+ * Plan 4 (Wave 2) extends this with two optional fields supporting object-form
+ * `contextBlocks` resolution. Both default to internal lazy construction when
+ * absent so existing callers (string-only `contextBlocks`) require no changes.
  */
 export interface CompileContext {
     /** Nunjucks environment from createTemplateEnv — used to render template references. */
@@ -74,6 +118,22 @@ export interface CompileContext {
     input: unknown;
     /** Project root. Used for `.project/` block reads during contextBlocks injection. */
     cwd: string;
+    /**
+     * Optional renderer registry for per-item macro resolution. When absent,
+     * object-form `contextBlocks` entries still inject the resolved item under
+     * `_<name>_item`, but the `render_recursive` Nunjucks global cannot
+     * dispatch — recursive rendering returns a `[unrendered: <kind>/<id>]`
+     * fallback marker rather than throwing.
+     */
+    rendererRegistry?: RendererRegistry;
+    /**
+     * Optional pre-built ID index. When absent and any object-form
+     * `contextBlocks` entry needs item resolution (or the `resolve`/
+     * `render_recursive` Nunjucks globals are invoked), `compileAgent` builds
+     * one on demand via `buildIdIndex(cwd)`. Callers performing many compiles
+     * in one pass should build once and pass it in for reuse.
+     */
+    idIndex?: Map<string, ItemLocation>;
 }
 /**
  * A compiled agent ready for dispatch.
@@ -102,6 +162,26 @@ export interface CompiledAgent {
      * inspection, not the rendered string.
      */
     contextValues: Record<string, unknown>;
+    /**
+     * Optional list of budget-truncation warnings collected during compile.
+     *
+     * Populated by the `enforceBudget` Nunjucks global registered by
+     * `compileAgent`: every macro invocation that exceeds the field's
+     * `x-prompt-budget` annotation appends one entry naming the field path,
+     * the declared budget, the actual measured token/word counts, and whether
+     * truncation was applied. Surfaces composition-time prompt-size signals
+     * to callers without breaking existing consumers (optional field; absent
+     * when no enforceBudget call has produced a warning during this compile).
+     *
+     * Distinct from runtime errors — a warning here means the rendered prompt
+     * is fully formed but a budgeted field carried more text than its
+     * annotation declared. The truncated text appears in the rendered prompt
+     * with the `[…truncated to budget]` marker; this array preserves the
+     * full warning record for trace / inspection consumers.
+     */
+    budgetWarnings?: BudgetWarning[];
+    /** Tool grant carried from AgentSpec.tools — operation-granular per DEC-0047; the clamp at executeAgent enforces child ⊆ parent at dispatch boundary. */
+    tools?: string[];
 }
 /**
  * Dispatch-time context for executeAgent.
@@ -111,6 +191,8 @@ export interface DispatchContext {
     model: Model<Api>;
     /** API auth — apiKey and headers from the consumer's model registry. */
     auth: JitAgentAuth;
+    /** Parent agent's tool grant (caller-supplied). executeAgent clamps compiled.tools ⊆ parentGrant. Undefined = empty set (default-empty per DEC-0047). */
+    parentGrant?: string[];
     /** Max tokens for the LLM call. Defaults to 1024. */
     maxTokens?: number;
     /** Abort signal for cancellation. */
@@ -128,7 +210,7 @@ export interface DispatchContext {
     /**
      * Optional path to a project-extension trace redaction config
      * (`.workflows/monitors/<name>/trace-config.json` shape). When set,
-     * `loadProjectRedactionConfig` is invoked once per executeAgent call and
+     * `loadContextRedactionConfig` is invoked once per executeAgent call and
      * the resulting custom patterns are layered atop `BUILTIN_PATTERNS` for
      * every redacted field. When unset / null, only the builtin pattern set
      * applies. Independent of `tracePath` — config loading is a no-op when
@@ -178,7 +260,7 @@ export interface AgentContract {
     name: string;
     role?: string;
     inputSchema?: Record<string, unknown>;
-    contextBlocks?: string[];
+    contextBlocks?: (string | ContextBlockRef)[];
     outputFormat?: "json" | "text";
     outputSchema?: string;
 }

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,9 @@
 {
 	"name": "@davidorex/pi-jit-agents",
-	"version": "0.14.6",
+	"version": "0.28.0",
+	"publishConfig": {
+		"access": "public"
+	},
 	"description": "Agent spec compilation and in-process dispatch runtime — the package that owns everything between 'I have a spec' and 'I have a typed result'",
 	"license": "MIT",
 	"author": "David Ryan",
@@ -49,17 +52,18 @@
 	"files": [
 		"dist/",
 		"schemas/",
+		"templates/",
 		"*.md"
 	],
 	"scripts": {
 		"clean": "rm -rf dist",
-		"build": "tsc -p tsconfig.build.json",
+		"build": "rm -rf dist && tsc -p tsconfig.build.json",
 		"prepublishOnly": "npm run clean && npm run build",
 		"test": "tsx --test src/*.test.ts"
 	},
 	"dependencies": {
-		"@davidorex/pi-project": "^0.14.6",
-		"@mariozechner/pi-ai": "^0.70.2",
+		"@davidorex/pi-context": "^0.28.0",
+		"@earendil-works/pi-ai": "^0.75.4",
 		"nunjucks": "^3.2.4",
 		"proper-lockfile": "^4.1.2",
 		"yaml": "^2.7.1"
@@ -67,5 +71,8 @@
 	"devDependencies": {
 		"@types/nunjucks": "^3.2.6",
 		"@types/proper-lockfile": "^4.1.4"
+	},
+	"engines": {
+		"node": ">=22.19.0"
 	}
 }

package/schemas/agent-trace.schema.json

@@ -1,14 +1,15 @@
 {
 	"$schema": "http://json-schema.org/draft-07/schema#",
 	"title": "Agent Trace Entry",
-	"description": "Discriminated union of trace events emitted during pi-jit-agents executeAgent invocations for monitor-classify pipelines. Each entry validates a single JSONL line; the .jsonl file as a whole is not a single JSON document. Per DEC-0004 the structural shape ({ type, id, parentId, timestamp, ...extra }) mirrors pi-coding-agent's SessionEntry but is deliberately a separate schema namespace — there is no literal inheritance. Per DEC-0005 these entries are produced by a push-write trace stream divergent from pi-mono's pull/replay model, so each variant is fired at the moment of occurrence inside executeAgent rather than reconstructed after the fact. The six variants form a parent-chained tree: session_start (root) → classify_call → { classify_response, context_collection } → verdict_decision; trace_end closes the session at the executeAgent exit boundary.",
+	"description": "Discriminated union of trace events emitted during pi-jit-agents executeAgent invocations for monitor-classify pipelines. Each entry validates a single JSONL line; the .jsonl file as a whole is not a single JSON document. The structural shape ({ type, id, parentId, timestamp, ...extra }) mirrors pi-coding-agent's SessionEntry but is deliberately a separate schema namespace — there is no literal inheritance. Entries are produced by a push-write trace stream divergent from pi-mono's pull/replay model, so each variant is fired at the moment of occurrence inside executeAgent rather than reconstructed after the fact. The six variants form a parent-chained tree: session_start (root) → classify_call → { classify_response, context_collection } → verdict_decision; trace_end closes the session at the executeAgent exit boundary.",
 	"oneOf": [
 		{ "$ref": "#/definitions/session_start" },
 		{ "$ref": "#/definitions/classify_call" },
 		{ "$ref": "#/definitions/classify_response" },
 		{ "$ref": "#/definitions/context_collection" },
 		{ "$ref": "#/definitions/verdict_decision" },
-		{ "$ref": "#/definitions/trace_end" }
+		{ "$ref": "#/definitions/trace_end" },
+		{ "$ref": "#/definitions/extension_load_warning" }
 	],
 	"definitions": {
 		"traceId": {
@@ -186,6 +187,33 @@
 				"totalDurationMs": { "type": "number" },
 				"verdict": { "$ref": "#/definitions/verdictResult" }
 			}
+		},
+		"extension_load_warning": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["type", "id", "parentId", "timestamp", "extension_name", "message", "severity"],
+			"properties": {
+				"type": { "const": "extension_load_warning" },
+				"id": { "$ref": "#/definitions/traceId" },
+				"parentId": {
+					"type": ["null", "string"],
+					"description": "Extension-load events are typically root events (no parent classify session); null when emitted at extension factory boundary. May reference a parent trace when emitted from within a dispatched agent's lifecycle."
+				},
+				"timestamp": { "$ref": "#/definitions/isoTimestamp" },
+				"extension_name": {
+					"type": "string",
+					"description": "Name of the Pi extension emitting the warning (e.g., pi-agent-dispatch)."
+				},
+				"message": {
+					"type": "string",
+					"description": "Human-readable description of the observed condition (e.g., 'substrate config absent — composites empty')."
+				},
+				"severity": {
+					"type": "string",
+					"enum": ["info", "warning", "error"],
+					"description": "Severity classification per the canonical pi.ui.notify levels."
+				}
+			}
 		}
 	}
 }

package/templates/analyzers/base-analyzer.md

@@ -0,0 +1,9 @@
+{% block identity %}You are a code analyst.{% endblock %} Given an exploration summary and a code path to analyze:
+
+{% block checklist %}
+1. Analyze the code thoroughly
+{% endblock %}
+
+{% block constraints %}
+Be specific — cite files and line ranges where applicable.
+{% endblock %}

package/templates/analyzers/patterns-task.md

@@ -0,0 +1,11 @@
+Analyze design patterns at `{{ path }}`.
+
+{% if exploration.files is defined %}
+## Codebase
+{% for file in exploration.files %}
+- `{{ file.path }}` ({{ file.lines }} lines)
+{% endfor %}
+{% endif %}
+
+Identify patterns, conventions, and anti-patterns. Provide recommendations.
+Write your analysis as JSON conforming to the output schema.

package/templates/analyzers/patterns.md

@@ -0,0 +1,15 @@
+{% extends "analyzers/base-analyzer.md" %}
+
+{% block identity %}You are a design pattern analyst.{% endblock %}
+
+{% block checklist %}
+1. **Design patterns**: What patterns are used? Are they applied correctly?
+2. **Idioms**: What language/framework idioms are followed or violated?
+3. **Conventions**: Naming, file organization, import style — are they consistent?
+4. **Anti-patterns**: Are there patterns that work against the codebase?
+5. **Recommendations**: What patterns would improve the codebase?
+{% endblock %}
+
+{% block constraints %}
+Focus on patterns and conventions, not raw quality or architecture. Be specific — cite examples.
+{% endblock %}

package/templates/analyzers/quality-task.md

@@ -0,0 +1,11 @@
+Analyze code quality at `{{ path }}`.
+
+{% if exploration.files is defined %}
+## Codebase
+{% for file in exploration.files %}
+- `{{ file.path }}` ({{ file.lines }} lines)
+{% endfor %}
+{% endif %}
+
+Assess test coverage, error handling, code smells, and maintainability.
+Write your analysis as JSON conforming to the output schema.

package/templates/analyzers/quality.md

@@ -0,0 +1,15 @@
+{% extends "analyzers/base-analyzer.md" %}
+
+{% block identity %}You are a code quality analyst.{% endblock %}
+
+{% block checklist %}
+1. **Test coverage**: What is tested? What isn't? Are tests meaningful?
+2. **Error handling**: How are errors handled? Are there gaps?
+3. **Code smells**: Duplicated logic, overly complex functions, magic numbers?
+4. **Documentation**: Is the code documented? Are the docs accurate?
+5. **Maintainability**: How easy would it be to modify this code?
+{% endblock %}
+
+{% block constraints %}
+Focus on quality concerns, not architecture or design patterns. Be specific — cite files and line ranges.
+{% endblock %}

package/templates/analyzers/structure-task.md

@@ -0,0 +1,17 @@
+Analyze the code at `{{ path }}`.
+
+{% if exploration.files is defined %}
+## Prior Exploration
+{% for file in exploration.files %}
+- `{{ file.path }}` ({{ file.lines }} lines){% if file.exports %}: {{ file.exports | length }} exports{% endif %}
+{% endfor %}
+{% endif %}
+
+{% if exploration.types is defined %}
+## Known Types
+{% for t in exploration.types %}
+- `{{ t.name }}` ({{ t.kind }}) in `{{ t.file }}`
+{% endfor %}
+{% endif %}
+
+Write your analysis as JSON conforming to the output schema.

package/templates/analyzers/structure.md

@@ -0,0 +1,15 @@
+{% extends "analyzers/base-analyzer.md" %}
+
+{% block identity %}You are a code structure analyst.{% endblock %}
+
+{% block checklist %}
+1. **Architecture**: How is the code organized? What patterns are used?
+2. **Module boundaries**: Are responsibilities clearly separated?
+3. **Dependencies**: What are the key dependency relationships?
+4. **Entry points**: How does execution flow through the code?
+5. **Configuration**: How is the system configured?
+{% endblock %}
+
+{% block constraints %}
+Focus on structural concerns, not code quality or patterns. Be specific — cite files and directories.
+{% endblock %}

package/templates/architecture-designer/task.md

@@ -0,0 +1,117 @@
+## Project Identity
+
+**Name:** {{ project.name }}
+**Description:** {{ project.description }}
+**Core Value:** {{ project.core_value }}
+{% if project.stack %}
+
+### Stack
+{% for item in project.stack %}
+- {{ item }}
+{% endfor %}
+{% endif %}
+
+### Constraints
+{% for constraint in project.constraints %}
+- [{{ constraint.type }}] {{ constraint.description }}
+{% endfor %}
+
+### Scope Boundaries
+
+**In scope:**
+{% for item in project.scope_boundaries.in %}
+- {{ item }}
+{% endfor %}
+
+**Out of scope:**
+{% for item in project.scope_boundaries.out %}
+- {{ item }}
+{% endfor %}
+
+## Requirements
+
+### Must
+{% for req in requirements.requirements %}
+{% if req.priority == "must" %}
+- **{{ req.id }}** [{{ req.type }}]: {{ req.description }}
+{% endif %}
+{% endfor %}
+
+### Should
+{% for req in requirements.requirements %}
+{% if req.priority == "should" %}
+- **{{ req.id }}** [{{ req.type }}]: {{ req.description }}
+{% endif %}
+{% endfor %}
+
+### Could
+{% for req in requirements.requirements %}
+{% if req.priority == "could" %}
+- **{{ req.id }}** [{{ req.type }}]: {{ req.description }}
+{% endif %}
+{% endfor %}
+
+## Instructions
+
+Design the initial architecture for this project. Produce modules, patterns, and boundaries that satisfy the requirements above — starting with "must" requirements and ensuring "should" requirements have a clear home.
+
+### For each module, provide:
+
+1. **name** — short identifier (e.g., "api", "auth", "storage", "cli")
+2. **file** — primary file path relative to project root (e.g., "src/api.ts")
+3. **responsibility** — one sentence: what this module owns and what it does not
+4. **dependencies** — array of other module names this depends on (empty if none)
+5. **lines** — estimated lines of code (rough order of magnitude)
+
+### For each pattern, provide:
+
+1. **name** — recognized pattern name (e.g., "Repository Pattern", "Event Sourcing", "Middleware Pipeline")
+2. **description** — why this pattern is appropriate for this project's specific needs
+3. **used_in** — array of module names that implement this pattern
+
+### For boundaries, provide:
+
+An array of strings — each describing a hard architectural constraint. These should be specific to this project, not generic ("All database access goes through the storage module", not "separate concerns").
+
+### Design principles
+
+- Module count should be proportional to requirements — a 5-requirement project needs 3-5 modules, not 15
+- Every "must" functional requirement should map to at least one module's responsibility
+- Every "must" non-functional requirement should be addressed by a pattern or boundary
+- Dependencies should flow in one direction — avoid circular module dependencies
+- If the project has a stated stack, modules should use file extensions and conventions matching that stack
+- Prefer explicit boundaries over implicit conventions
+
+### Overview
+
+Write an `overview` paragraph (required) summarizing:
+- The architectural style (layered, modular, pipeline, etc.)
+- The key structural decisions and why they fit this project
+- How the architecture supports the core_value
+
+### Output format
+
+Produce a single JSON object:
+
+```json
+{
+  "overview": "string (required)",
+  "modules": [
+    {
+      "name": "string (required)",
+      "file": "string (required)",
+      "responsibility": "string (required)",
+      "dependencies": ["string"],
+      "lines": 100
+    }
+  ],
+  "patterns": [
+    {
+      "name": "string (required)",
+      "description": "string (required)",
+      "used_in": ["module-name"]
+    }
+  ],
+  "boundaries": ["string"]
+}
+```

package/templates/architecture-inferrer/task.md

@@ -0,0 +1,61 @@
+Infer the architecture of the project at `{{ path }}`.
+
+## Codebase Analysis
+
+{% if exploration.files is defined %}
+### Files
+{% for file in exploration.files %}
+- `{{ file.path }}` ({{ file.language | default("unknown") }}, {{ file.lines | default("?") }} lines){% if file.exports %} — {{ file.exports | length }} exports{% endif %}
+{% endfor %}
+{% endif %}
+
+{% if exploration.types is defined %}
+### Types
+{% for t in exploration.types %}
+- `{{ t.name }}` ({{ t.kind }}) in `{{ t.file }}`
+{% endfor %}
+{% endif %}
+
+{% if exploration.dependencies is defined %}
+### Dependencies
+{% for d in exploration.dependencies %}
+- `{{ d.from }}` → `{{ d.to }}` ({{ d.type | default("import") }})
+{% endfor %}
+{% endif %}
+
+{% if exploration.entryPoints is defined %}
+### Entry Points
+{% for ep in exploration.entryPoints %}
+- `{{ ep }}`
+{% endfor %}
+{% endif %}
+
+## Instructions
+
+From the analysis above and targeted code reads, produce an architecture block:
+
+1. **Modules** — each cohesive unit with a clear responsibility. For each:
+   - `name`: concise identifier (e.g., "block-api", "expression-engine")
+   - `file`: primary file path relative to project root
+   - `responsibility`: one-sentence description of what this module does
+   - `dependencies`: array of other module names this module depends on
+   - `lines`: approximate line count
+
+2. **Patterns** — design patterns evidenced in the code. For each:
+   - `name`: pattern name (e.g., "registry", "factory", "middleware")
+   - `description`: how this pattern is applied in this codebase
+   - `used_in`: array of module names that use this pattern
+
+3. **Boundaries** — architectural seams where modules interact through defined interfaces (e.g., "block-api validates all writes before persistence", "dispatch spawns subprocesses through a single entry point")
+
+4. **Overview** — one paragraph summarizing the architecture: what the system does, how it's organized, and what the key design decisions are
+
+Read entry points, config files, and module interfaces to confirm the exploration. Do not read every file.
+
+## Required Output Schema
+
+You MUST produce JSON conforming exactly to this schema. Every required field must be present.
+
+```json
+{{ output_schema }}
+```