agent-bober 0.12.0 → 0.17.0

package/dist/orchestrator/deploy/spawn.js

@@ -0,0 +1,62 @@
+/**
+ * Deployer spawn-site integration surface (Sprint 20).
+ *
+ * Sprint 24 (/bober-incident CLI command) will call spawnDeployer() to:
+ *   1. Merge observability MCP tools (same pattern as the diagnoser — Sprint 16).
+ *   2. Load the bober-deployer agent definition.
+ *   3. Register the risky-action checkpoint callback (the gate that calls executeAction).
+ *
+ * This module exports the spawn helper and the RiskyActionCheckpointCallback type
+ * so Sprint 24 can wire without importing from internal deploy/ modules directly.
+ *
+ * Pattern:
+ * - mergeObsTools: from src/orchestrator/observability/merge.ts (Sprint 16)
+ * - loadAgentDefinition: from src/orchestrator/agent-loader.ts (Sprint 15 pattern)
+ *
+ * The deployer's tool list at spawn time:
+ *   [Read, Bash, Grep, Glob, ...namespacedObsTools]
+ *
+ * The risky-action callback:
+ *   Called once per ProposedAction that classifyCommand() classifies as risky.
+ *   Receives the action description, classification reasoning, and inverse.
+ *   Returns the checkpoint outcome (approved, rejected, or operator-edited).
+ *
+ * Sprint 24 integration point:
+ * ```typescript
+ * import { spawnDeployer } from "../orchestrator/deploy/spawn.js";
+ * const { agentDef, obsTools, stopObs } = await spawnDeployer(config, projectRoot);
+ * try {
+ *   // pass agentDef + obsTools to the agentic loop
+ * } finally {
+ *   await stopObs();
+ * }
+ * ```
+ */
+import { mergeObsTools, stopAll } from "../observability/index.js";
+import { loadAgentDefinition } from "../agent-loader.js";
+// ── spawnDeployer ──────────────────────────────────────────────────────────────
+/**
+ * Prepare the deployer subagent's spawn context.
+ *
+ * Mirrors the diagnoser spawn pattern (Sprint 15/16):
+ *   1. Load the agent definition from agents/bober-deployer.md.
+ *   2. Merge observability MCP tools via Promise.allSettled (partial failure safe).
+ *   3. Return the spawn context for Sprint 24 to pass into the agentic loop.
+ *
+ * The caller MUST call stopObs() in a finally block to release observability MCP processes.
+ *
+ * @param config      - Pipeline config (controls allowAutopilotRiskyActions + mechanism resolution).
+ * @param projectRoot - Absolute path to the project root.
+ */
+export async function spawnDeployer(config, projectRoot) {
+    // Load agent definition in parallel with obs tool merge.
+    const [agentDef, obsResult] = await Promise.all([
+        loadAgentDefinition("bober-deployer", projectRoot),
+        mergeObsTools(config
+            ?.observability?.providers ?? []),
+    ]);
+    const { tools: obsTools, servers: obsServers } = obsResult;
+    const stopObs = () => stopAll(obsServers);
+    return { agentDef, obsTools, stopObs };
+}
+//# sourceMappingURL=spawn.js.map

package/dist/orchestrator/deploy/spawn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.js","sourceRoot":"","sources":["../../../src/orchestrator/deploy/spawn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAgBzD,kFAAkF;AAElF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAqC,EACrC,WAAmB;IAEnB,yDAAyD;IACzD,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC9C,mBAAmB,CAAC,gBAAgB,EAAE,WAAW,CAAC;QAClD,aAAa,CACV,MAA8F;YAC7F,EAAE,aAAa,EAAE,SAAS,IAAI,EAAE,CACnC;KACF,CAAC,CAAC;IAEH,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,SAAS,CAAC;IAE3D,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,UAAiC,CAAC,CAAC;IAEjE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AACzC,CAAC"}

package/dist/orchestrator/deploy/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Type definitions for the deploy module (Sprint 20).
+ *
+ * ProposedAction — the action the deployer agent proposes for execution.
+ * ExecutorSeam   — the injection seam that enables unit testing without real execa.
+ * DeployResult   — the summary returned to the orchestrator after a deployer session.
+ */
+import { z } from "zod";
+export declare const ProposedActionSchema: z.ZodObject<{
+    /** Unique action id within this incident session. */
+    id: z.ZodString;
+    /** Human-readable description of what the action does. */
+    description: z.ZodString;
+    /**
+     * Agent-declared blast-radius classification. This is a HINT — the executor
+     * re-classifies by command content via classifyCommand(). If the executor's
+     * classification is risky the action is treated as risky regardless of this field.
+     */
+    classification: z.ZodEnum<["safe", "risky"]>;
+    /** One-sentence justification explaining why the classification was chosen. */
+    reasoning: z.ZodString;
+    /** Optional shell command to execute. If absent, execution is a no-op (metadata-only record). */
+    command: z.ZodOptional<z.ZodString>;
+    /**
+     * REQUIRED inverse declaration — how to undo this action.
+     * Sprint 21 rollback awareness reads this field from every ChangeEntry; it must
+     * be present BEFORE execution starts (not added retroactively).
+     */
+    inverse: z.ZodObject<{
+        description: z.ZodString;
+        command: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        command?: string | undefined;
+    }, {
+        description: string;
+        command?: string | undefined;
+    }>;
+    /** Optional shell command to verify preconditions BEFORE execution. */
+    preconditionCheck: z.ZodOptional<z.ZodString>;
+    /** Optional shell command to verify postconditions AFTER execution. */
+    postconditionCheck: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    id: string;
+    classification: "safe" | "risky";
+    inverse: {
+        description: string;
+        command?: string | undefined;
+    };
+    reasoning: string;
+    command?: string | undefined;
+    preconditionCheck?: string | undefined;
+    postconditionCheck?: string | undefined;
+}, {
+    description: string;
+    id: string;
+    classification: "safe" | "risky";
+    inverse: {
+        description: string;
+        command?: string | undefined;
+    };
+    reasoning: string;
+    command?: string | undefined;
+    preconditionCheck?: string | undefined;
+    postconditionCheck?: string | undefined;
+}>;
+export type ProposedAction = z.infer<typeof ProposedActionSchema>;
+/**
+ * Injection seam for command execution.
+ *
+ * Tests pass a fake executor that captures calls without side effects.
+ * Production code uses defaultExecutor (execa wrapper in executor.ts).
+ *
+ * Every Bash command the deployer runs MUST go through this seam —
+ * classifyCommand() runs on the command string BEFORE the seam is called.
+ */
+export interface ExecutorSeam {
+    run(command: string): Promise<{
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    }>;
+}
+export interface DeployResult {
+    incidentId: string;
+    executed: Array<{
+        actionId: string;
+        status: "executed" | "failed";
+        durationMs: number;
+        error?: string;
+    }>;
+    aborted: Array<{
+        actionId: string;
+        reason: "checkpoint_rejected" | "precondition_failed" | "missing_inverse" | "postcondition_failed";
+    }>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/orchestrator/deploy/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/deploy/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,oBAAoB;IAC/B,qDAAqD;;IAErD,0DAA0D;;IAE1D;;;;OAIG;;IAEH,+EAA+E;;IAE/E,iGAAiG;;IAEjG;;;;OAIG;;;;;;;;;;;IAKH,uEAAuE;;IAEvE,uEAAuE;;;;;;;;;;;;;;;;;;;;;;;;;;EAEvE,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAIlE;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrF;AAID,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,KAAK,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,UAAU,GAAG,QAAQ,CAAC;QAC9B,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC,CAAC;IACH,OAAO,EAAE,KAAK,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,qBAAqB,GAAG,qBAAqB,GAAG,iBAAiB,GAAG,sBAAsB,CAAC;KACpG,CAAC,CAAC;CACJ"}

package/dist/orchestrator/deploy/types.js

@@ -0,0 +1,39 @@
+/**
+ * Type definitions for the deploy module (Sprint 20).
+ *
+ * ProposedAction — the action the deployer agent proposes for execution.
+ * ExecutorSeam   — the injection seam that enables unit testing without real execa.
+ * DeployResult   — the summary returned to the orchestrator after a deployer session.
+ */
+import { z } from "zod";
+// ── ProposedAction ─────────────────────────────────────────────────────────────
+export const ProposedActionSchema = z.object({
+    /** Unique action id within this incident session. */
+    id: z.string().min(1),
+    /** Human-readable description of what the action does. */
+    description: z.string().min(1),
+    /**
+     * Agent-declared blast-radius classification. This is a HINT — the executor
+     * re-classifies by command content via classifyCommand(). If the executor's
+     * classification is risky the action is treated as risky regardless of this field.
+     */
+    classification: z.enum(["safe", "risky"]),
+    /** One-sentence justification explaining why the classification was chosen. */
+    reasoning: z.string().min(1),
+    /** Optional shell command to execute. If absent, execution is a no-op (metadata-only record). */
+    command: z.string().optional(),
+    /**
+     * REQUIRED inverse declaration — how to undo this action.
+     * Sprint 21 rollback awareness reads this field from every ChangeEntry; it must
+     * be present BEFORE execution starts (not added retroactively).
+     */
+    inverse: z.object({
+        description: z.string().min(1),
+        command: z.string().optional(),
+    }),
+    /** Optional shell command to verify preconditions BEFORE execution. */
+    preconditionCheck: z.string().optional(),
+    /** Optional shell command to verify postconditions AFTER execution. */
+    postconditionCheck: z.string().optional(),
+});
+//# sourceMappingURL=types.js.map

package/dist/orchestrator/deploy/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/orchestrator/deploy/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,kFAAkF;AAElF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,qDAAqD;IACrD,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,0DAA0D;IAC1D,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B;;;;OAIG;IACH,cAAc,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,+EAA+E;IAC/E,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,iGAAiG;IACjG,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B;;;;OAIG;IACH,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC;QAChB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QAC9B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAC/B,CAAC;IACF,uEAAuE;IACvE,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACxC,uEAAuE;IACvE,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC1C,CAAC,CAAC"}

package/dist/orchestrator/documenter-agent.d.ts

@@ -0,0 +1,57 @@
+import type { BoberConfig } from "../config/schema.js";
+import type { SprintContract } from "../contracts/sprint-contract.js";
+import type { EvaluationRunResult } from "../evaluators/registry.js";
+import type { GeneratorResult } from "./generator-agent.js";
+/** One existing doc the documenter updated because the sprint made it stale. */
+export interface RelatedDocUpdate {
+    path: string;
+    reason: string;
+}
+/**
+ * The structured result emitted by the bober-documenter subagent.
+ */
+export interface DocumentationResult {
+    contractId: string;
+    /** Path to the per-sprint record the documenter wrote. */
+    sprintDocPath: string;
+    /** Existing docs the documenter updated. */
+    relatedDocsUpdated: RelatedDocUpdate[];
+    /** The docs-only commit the documenter made, if any. */
+    docsCommit?: string;
+    /** Code/doc issues the documenter noticed but did NOT fix (it must not touch code). */
+    concerns: string[];
+    summary: string;
+}
+/**
+ * Run the bober-documenter subagent to write per-sprint documentation.
+ *
+ * Runs AFTER the evaluator returns passed=true and the sprint is committed.
+ * The documenter writes a focused record of what the sprint built to
+ * `docs/sprints/<contractId>.md`, finds & updates related existing docs that
+ * the change made stale, and commits ONLY the doc files. It must NOT modify
+ * application code or tests — the sprint already passed evaluation.
+ *
+ * Documentation is advisory: a documenter failure never downgrades the
+ * already-passed sprint (see the caller in pipeline.ts).
+ *
+ * The documenter reuses the "generator" role's write-tool surface (bash,
+ * read/write/edit files, glob, grep) — mirroring how runCodeReviewer reuses
+ * the "evaluator" role rather than introducing a distinct AgentRole.
+ *
+ * @param contract        The sprint contract that just passed.
+ * @param evaluation      The evaluation result (passed=true).
+ * @param generatorResult The generator's result — the authoritative list of
+ *                        what changed in this sprint.
+ * @param projectRoot     Absolute path to the project root.
+ * @param config          The resolved bober configuration.
+ * @returns A DocumentationResult with the docs written and updated.
+ */
+export declare function runDocumenter(contract: SprintContract, evaluation: EvaluationRunResult, generatorResult: GeneratorResult | undefined, projectRoot: string, config: BoberConfig): Promise<DocumentationResult>;
+/**
+ * Parse the documenter's response into a DocumentationResult.
+ * Mirrors the resilient JSON-parsing pattern from code-reviewer-agent.ts.
+ *
+ * Exported for direct unit testing.
+ */
+export declare function parseDocumentationResult(text: string, contractId: string, defaultSprintDocPath: string): DocumentationResult;
+//# sourceMappingURL=documenter-agent.d.ts.map

package/dist/orchestrator/documenter-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documenter-agent.d.ts","sourceRoot":"","sources":["../../src/orchestrator/documenter-agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAU5D,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,aAAa,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,kBAAkB,EAAE,gBAAgB,EAAE,CAAC;IACvC,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uFAAuF;IACvF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAID;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,cAAc,EACxB,UAAU,EAAE,mBAAmB,EAC/B,eAAe,EAAE,eAAe,GAAG,SAAS,EAC5C,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,mBAAmB,CAAC,CAkH9B;AAID;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,oBAAoB,EAAE,MAAM,GAC3B,mBAAmB,CAyDrB"}

package/dist/orchestrator/documenter-agent.js

@@ -0,0 +1,195 @@
+import { createClient } from "../providers/factory.js";
+import { logger } from "../utils/logger.js";
+import { resolveModel } from "./model-resolver.js";
+import { assembleSystemPrompt } from "./agent-loader.js";
+import { resolveRoleTools, getGraphState, getGraphDeps } from "./tools/index.js";
+import { runAgenticLoop } from "./agentic-loop.js";
+// ── Main ───────────────────────────────────────────────────────────
+/**
+ * Run the bober-documenter subagent to write per-sprint documentation.
+ *
+ * Runs AFTER the evaluator returns passed=true and the sprint is committed.
+ * The documenter writes a focused record of what the sprint built to
+ * `docs/sprints/<contractId>.md`, finds & updates related existing docs that
+ * the change made stale, and commits ONLY the doc files. It must NOT modify
+ * application code or tests — the sprint already passed evaluation.
+ *
+ * Documentation is advisory: a documenter failure never downgrades the
+ * already-passed sprint (see the caller in pipeline.ts).
+ *
+ * The documenter reuses the "generator" role's write-tool surface (bash,
+ * read/write/edit files, glob, grep) — mirroring how runCodeReviewer reuses
+ * the "evaluator" role rather than introducing a distinct AgentRole.
+ *
+ * @param contract        The sprint contract that just passed.
+ * @param evaluation      The evaluation result (passed=true).
+ * @param generatorResult The generator's result — the authoritative list of
+ *                        what changed in this sprint.
+ * @param projectRoot     Absolute path to the project root.
+ * @param config          The resolved bober configuration.
+ * @returns A DocumentationResult with the docs written and updated.
+ */
+export async function runDocumenter(contract, evaluation, generatorResult, projectRoot, config) {
+    const contractId = contract.contractId;
+    logger.sprint(contractId, `Documenting: ${contract.title}`);
+    const documenterModel = config.documenter?.model ?? config.generator.model;
+    const model = resolveModel(documenterModel);
+    const maxTurns = config.documenter?.maxTurns ?? 20;
+    // Documenter needs WRITE access — reuse the "generator" role tool set
+    // (bash, read/write/edit, glob, grep; UNION with graph_* when gated).
+    const graphState = getGraphState(config);
+    const graphDeps = graphState.engineHealth === "ready" ? getGraphDeps() : undefined;
+    const toolSet = resolveRoleTools("generator", projectRoot, graphState, graphDeps ?? undefined);
+    const systemPrompt = await assembleSystemPrompt("generator", "bober-documenter", projectRoot, graphState);
+    const client = createClient(config.documenter?.provider ?? config.generator.provider ?? null, config.documenter?.endpoint ?? config.generator.endpoint ?? null, config.documenter?.providerConfig ?? config.generator.providerConfig, documenterModel, "Documenter");
+    const contractJson = JSON.stringify(contract, null, 2);
+    const evalSummary = JSON.stringify({
+        passed: evaluation.passed,
+        score: evaluation.score,
+        summary: evaluation.summary,
+    }, null, 2);
+    const filesChanged = generatorResult?.filesChanged && generatorResult.filesChanged.length > 0
+        ? generatorResult.filesChanged.map((f) => `- ${f}`).join("\n")
+        : "(no file list reported — derive the change set from git)";
+    const sprintDocPath = `docs/sprints/${contractId}.md`;
+    const userMessage = `# Sprint Contract
+
+${contractJson}
+
+# Evaluation Result (Already Passed)
+
+${evalSummary}
+
+# Files Changed This Sprint (from the generator report)
+
+${filesChanged}
+
+# Project Root
+
+${projectRoot}
+
+# Context
+
+- Contract ID: ${contractId}
+- Spec ID: ${contract.specId}
+- The implementation is ALREADY complete, evaluated, and committed.
+- Your job is documentation ONLY. Do NOT modify application code, tests, configs, or build files.
+
+# Your Task
+
+1. Inspect what actually shipped: run \`git show --stat HEAD\` and \`git diff HEAD~1 HEAD\` on the changed files. Read the source of the key new/changed symbols — do not document from filenames alone.
+2. Write a focused per-sprint record to ${sprintDocPath} (create docs/sprints/ if needed): what the sprint added, the public surface (symbols/endpoints/CLI commands/config keys with file:line), how it fits, and maintainer notes.
+3. Find & update related existing docs the change made stale: grep README.md, docs/**, CLAUDE.md, AGENTS.md, ADRs, and module docs for the names of changed symbols/commands/config keys. Update only what is genuinely inaccurate or now-missing. Match each doc's existing voice and formatting.
+4. Commit ONLY the documentation files (verify with \`git status\` that no source/test files are staged):
+   \`git add <doc files> && git commit -m "bober(${contractId}): docs for <short title>"\`
+
+If you believe code is wrong, do NOT fix it — record it in "concerns".
+
+Output ONLY a JSON object (no markdown fences):
+{
+  "contractId": "${contractId}",
+  "sprintDocPath": "${sprintDocPath}",
+  "relatedDocsUpdated": [
+    {"path": "<path>", "reason": "<why it was stale / what you changed>"}
+  ],
+  "docsCommit": "<hash> - <message>",
+  "concerns": [],
+  "summary": "<2-3 sentence summary>"
+}`;
+    logger.info(`Calling documenter model (${documenterModel} → ${model})...`);
+    const result = await runAgenticLoop({
+        client,
+        model,
+        systemPrompt,
+        userMessage,
+        tools: toolSet.schemas,
+        toolHandlers: toolSet.handlers,
+        maxTurns,
+        maxTokens: 16384,
+        onToolUse: (name, input) => {
+            const inp = input;
+            const inputStr = JSON.stringify(inp).slice(0, 120);
+            logger.debug(`  [documenter] ${name}(${inputStr})`);
+        },
+    });
+    logger.debug(`Documenter completed in ${result.turnsUsed} turns (${result.toolsCalled.length} tool calls)`);
+    const docResult = parseDocumentationResult(result.finalText, contractId, sprintDocPath);
+    logger.info(`Documentation complete: ${docResult.sprintDocPath} (+${docResult.relatedDocsUpdated.length} related docs updated, ${docResult.concerns.length} concerns)`);
+    return docResult;
+}
+// ── JSON parser ────────────────────────────────────────────────────
+/**
+ * Parse the documenter's response into a DocumentationResult.
+ * Mirrors the resilient JSON-parsing pattern from code-reviewer-agent.ts.
+ *
+ * Exported for direct unit testing.
+ */
+export function parseDocumentationResult(text, contractId, defaultSprintDocPath) {
+    let parsed;
+    // Try direct parse
+    try {
+        parsed = JSON.parse(text.trim());
+    }
+    catch {
+        // Try extracting from markdown fences
+        const fenceMatch = /```(?:json)?\s*\n?([\s\S]*?)\n?\s*```/.exec(text);
+        if (fenceMatch) {
+            try {
+                parsed = JSON.parse(fenceMatch[1].trim());
+            }
+            catch {
+                // Fall through
+            }
+        }
+        // Try finding { ... }
+        if (!parsed) {
+            const braceStart = text.indexOf("{");
+            const braceEnd = text.lastIndexOf("}");
+            if (braceStart !== -1 && braceEnd > braceStart) {
+                try {
+                    parsed = JSON.parse(text.slice(braceStart, braceEnd + 1));
+                }
+                catch {
+                    // Fall through to default
+                }
+            }
+        }
+    }
+    if (parsed && typeof parsed === "object" && parsed !== null) {
+        const obj = parsed;
+        return {
+            contractId: typeof obj.contractId === "string" ? obj.contractId : contractId,
+            sprintDocPath: typeof obj.sprintDocPath === "string"
+                ? obj.sprintDocPath
+                : defaultSprintDocPath,
+            relatedDocsUpdated: parseRelatedDocs(obj.relatedDocsUpdated),
+            ...(typeof obj.docsCommit === "string" ? { docsCommit: obj.docsCommit } : {}),
+            concerns: parseStringArray(obj.concerns),
+            summary: typeof obj.summary === "string" ? obj.summary : "No summary provided.",
+        };
+    }
+    // Fallback — documenter ran but response wasn't parseable.
+    return {
+        contractId,
+        sprintDocPath: defaultSprintDocPath,
+        relatedDocsUpdated: [],
+        concerns: [],
+        summary: "Documenter response could not be parsed.",
+    };
+}
+function parseRelatedDocs(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .filter((item) => typeof item === "object" && item !== null)
+        .map((item) => ({
+        path: typeof item.path === "string" ? item.path : "unknown",
+        reason: typeof item.reason === "string" ? item.reason : "",
+    }));
+}
+function parseStringArray(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((item) => typeof item === "string");
+}
+//# sourceMappingURL=documenter-agent.js.map

package/dist/orchestrator/documenter-agent.js.map

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

package/dist/orchestrator/environment.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Detected host environment, surfaced to agents so they (a) target the right
+ * OS/shell and (b) only invoke tooling that is actually installed — instead of
+ * guessing (e.g. DeepSeek hallucinating a `bash` tool or GNU-only flags on macOS).
+ */
+export interface HostEnvironment {
+    /** Raw node platform string (darwin | linux | win32 | ...). */
+    platform: string;
+    /** Friendly OS name (macOS | Linux | Windows | <platform>). */
+    osName: string;
+    /** OS kernel release. */
+    osRelease: string;
+    /** CPU architecture (arm64 | x64 | ...). */
+    arch: string;
+    /** Login shell from $SHELL, if known. */
+    shell: string | undefined;
+    /** Node.js version (process.version). */
+    nodeVersion: string;
+    /** Detected project package manager (npm | pnpm | yarn | bun | undefined). */
+    packageManager: string | undefined;
+    /** Names of common dev CLIs found on PATH. */
+    installedTools: string[];
+}
+/**
+ * Detect the host environment. Tool/OS detection is process-stable, so the
+ * result is cached after the first call (package-manager detection re-runs only
+ * when the cache is cold). Pass a projectRoot for package-manager detection.
+ */
+export declare function detectEnvironment(projectRoot: string): Promise<HostEnvironment>;
+/** Reset the cache (tests). */
+export declare function resetEnvironmentCache(): void;
+/**
+ * Render the environment + the role's exact harness tools as a markdown block
+ * for injection into an agent's system prompt.
+ *
+ * @param env         Detected host environment.
+ * @param toolNames   The exact harness tool names available to this role (e.g.
+ *                    ["read_file","glob","grep"]). Used to stop models inventing
+ *                    tools (e.g. a non-existent "bash" for read-only roles).
+ * @param projectRoot Absolute path to the project root. Surfaced so models stop
+ *                    guessing it — non-Claude models otherwise invent an absolute
+ *                    path with the wrong home dir, which the path sandbox rejects.
+ */
+export declare function formatEnvironmentContext(env: HostEnvironment, toolNames: string[], projectRoot?: string): string;
+//# sourceMappingURL=environment.d.ts.map

package/dist/orchestrator/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/orchestrator/environment.ts"],"names":[],"mappings":"AAOA;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,8CAA8C;IAC9C,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAiFD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,eAAe,CAAC,CAa1B;AAED,+BAA+B;AAC/B,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,eAAe,EACpB,SAAS,EAAE,MAAM,EAAE,EACnB,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAgDR"}