ndrstnd 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable ndrstnd changes are documented here. Versions are released as unprefixed Git tags and published through npm and the repository’s Homebrew tap.
+
+## 0.2.0 — 2026-07-20
+
+This release contains the changes made after 0.1.0 through the current 0.2.0 release candidate.
+
+### Agent analysis and reliability
+
+- Replaced the fragile compact analysis wire format in the agent prompt with an explicit named-object JSON contract. Chapters, steps, deferred items, forward references, focus ranges, and test executions now have named properties that coding agents can generate and repair more reliably.
+- Kept compatibility with legacy compact responses while making the explicit format canonical, so existing cached or in-flight agent behavior can be diagnosed without weakening the new contract.
+- Changed evidence references from brittle hunk ID strings to zero-based indexes in the numbered review manifest, with validation that every meaningful hunk is classified and every hunk appears in the timeline.
+- Hardened JSON extraction, wire-schema validation, prose limits, evidence invariants, focus ranges, step ordering, duplicate detection, and repair prompts. Failed drafts receive targeted repair turns and transient agent failures get one fresh-client retry.
+- Added clearer analysis progress and heartbeat output so long Codex or Claude Code runs are observable instead of looking hung.
+
+### Failure diagnosis and CLI
+
+- Added a portable `ndrstnd-analysis-diagnostic` JSON artifact for review failures. It records tool/runtime metadata, sanitized command and scope information, per-turn timings and activity, response hashes, extraction metadata, validation phases, and transport errors without including prompts, patches, environment variables, or raw responses by default.
+- Added `--diagnostic-include-agent-output` for private escalations when the maintainer needs the raw agent response; such artifacts are explicitly marked sensitive.
+- Made CLI failures print numbered reporting steps, including where to find the diagnostic artifact, what command and scope to attach, and what to do when the artifact itself cannot be written.
+- Improved missing-agent and authentication guidance, including actionable commands for installing or signing in to Codex or Claude Code.
+
+### Packaging, Homebrew, and documentation
+
+- Added native `better-sqlite3` rebuild coverage to the test lifecycle and a packaged-binding smoke test in the Homebrew formula.
+- Pinned the 0.1.1 and 0.1.2 Homebrew source archive hashes and documented the tap trust step and release hash workflow.
+- Documented Node.js runtime and native dependency rules, merge-base review scoping, cached analysis behavior, explicit agent selection, conversation imports, and the failure-diagnostic reporting process.
+- Removed a misleading Homebrew hero command from the project site.
+
+### Verification
+
+- Expanded analysis, CLI, parser, packaging, and diagnostic regression coverage. The release checks are `npm run lint`, `npm test`, `npm run build`, and `npm pack --dry-run`.
+
+### Homebrew publication follow-up
+
+The formula remains pinned to the last published 0.1.2 archive until the 0.2.0 Git tag exists on GitHub. After publishing the tag, compute the archive SHA-256 with the command documented at the top of `Formula/ndrstnd.rb`, update that formula’s URL and hash, run Homebrew audit/install checks, and commit the formula update.
+
+## 0.1.0
+
+- Initial public ndrstnd release as a local comprehension workspace with Story, Timeline, Test plan, and Full diff views.

package/README.md

@@ -41,6 +41,12 @@ Without a branch, ndrstnd reviews the checked-out branch including staged, unsta
 
 Add `--conversation path/to/ndrstnd-conversation-v1.json` to ground the narrative in the dialogue that produced the branch: motives, rejected alternatives, constraints, and any observed test runs feed the Story and the Test plan.
 
+## When a review fails
+
+ndrstnd never creates a partial or invented HTML review. If a review reaches the repository and fails during collection, agent analysis, validation, or artifact writing, it writes a shareable diagnostic JSON file under that repository’s `.ndrstnd/` directory and prints numbered reporting steps. Keep the file unchanged and share it with the exact command, selected agent, and intended base/target scope. It contains environment and scope metadata plus hashed prompt/response metadata, but excludes prompts, diffs, environment variables, and raw agent responses by default.
+
+If the maintainer needs to inspect the agent’s response, rerun the same command with `--diagnostic-include-agent-output` and share that diagnostic only through a private channel; it is explicitly marked as sensitive. If ndrstnd cannot write the diagnostic file, preserve the complete terminal output instead. Do not attach credentials, tokens, or repository contents unless requested through a secure channel.
+
 ## Scope
 
 ndrstnd is for understanding code: it explains the implementation story, evidence, risk signals, and selected lines. It deliberately does not critique the change, submit review comments, or edit the branch.

package/dist/server/analysis-core.d.ts

@@ -54,7 +54,7 @@ export declare function buildPromptReviewInput(input: CollectedReviewInput, conv
         signal: import("../shared/domain.js").FileSignal;
         signalReason: string | undefined;
         hunks: {
-            id: string;
+            index: number;
             fileId: string;
             path: string | undefined;
             oldStart: number;
@@ -73,11 +73,11 @@ export declare function buildPromptReviewInput(input: CollectedReviewInput, conv
         }[];
     }[];
     construction: {
-        suggestedEvidenceOrder: string[];
+        suggestedEvidenceOrder: number[];
         defineBeforeUse: {
             symbol: string | undefined;
-            definedIn: string;
-            usedIn: string;
+            definedIn: number;
+            usedIn: number;
         }[];
     };
     conversation: {

package/dist/server/analysis-core.js

@@ -1,8 +1,8 @@
-import { AnalysisDocumentSchema } from "../shared/analysis-schema.js";
+import { AnalysisDocumentSchema, TestExecutionSchema } from "../shared/analysis-schema.js";
 import { z } from "zod";
 import { deriveEvidenceOrder } from "./evidence-ordering.js";
 export function parseAnalysisDocument(value, input, options) {
-    const document = parseWireAnalysisDocument(value);
+    const document = parseWireAnalysisDocument(value, input);
     const duplicateChapterIds = duplicated(document.chapters.map((chapter) => chapter.id));
     if (duplicateChapterIds.length > 0)
         throw new Error(`Analysis chapter ids are duplicated: ${duplicateChapterIds.join(", ")}. Give every chapter in c a unique id.`);
@@ -98,6 +98,59 @@ export const PROSE_WORD_RANGES = {
     goal: { min: 12, max: 40 },
     youNowHave: { min: 12, max: 40 },
 };
+const ManifestIndexSchema = z.number().int().min(0);
+const AgentDeferredSchema = z.object({
+    concern: z.string().min(1).max(700),
+    resolvedByStepId: z.string().min(1).max(80).nullable().optional(),
+});
+const AgentForwardRefSchema = z.object({
+    symbol: z.string().min(1),
+    introducedByStepId: z.string().min(1).max(80),
+});
+const AgentChapterSchema = z.object({
+    id: z.string().min(1).max(80),
+    title: z.string().min(1).max(120),
+    kind: z.enum(["feature", "decision", "behavior", "non_functional", "risk", "test", "other"]),
+    synopsis: z.string().min(1).max(1_200),
+    before: z.string().max(900).nullable().optional(),
+    after: z.string().max(900).nullable().optional(),
+    confidence: z.enum(["high", "medium", "low"]),
+    attention: z.enum(["low", "contained", "elevated", "high", "critical"]),
+    riskCategories: z.array(z.enum(["formatting", "refactor", "behavior", "performance", "security"])),
+    evidenceIndexes: z.array(ManifestIndexSchema).min(1),
+});
+const AgentStepSchema = z.object({
+    id: z.string().min(1).max(80),
+    title: z.string().min(1).max(120),
+    goal: z.string().min(1).max(900),
+    youNowHave: z.string().min(1).max(900),
+    deferred: z.array(AgentDeferredSchema),
+    dependsOn: z.array(z.string().min(1).max(80)),
+    forwardRefs: z.array(AgentForwardRefSchema),
+    advancesChapterIds: z.array(z.string().min(1).max(80)).min(1),
+    evidenceIndexes: z.array(ManifestIndexSchema).min(1),
+});
+const AgentOmittedGroupSchema = z.object({
+    title: z.string().min(1).max(240),
+    reason: z.string().min(1).max(700),
+    evidenceIndexes: z.array(ManifestIndexSchema).min(1),
+});
+const AgentFocusSchema = z.object({
+    evidenceIndex: ManifestIndexSchema,
+    ranges: z.array(z.object({
+        startLine: z.number().int().min(1),
+        endLine: z.number().int().min(1),
+    })).min(1).max(5),
+});
+const AgentAnalysisDocumentSchema = z.object({
+    summary: z.string().min(1).max(1_600),
+    chapters: z.array(AgentChapterSchema),
+    steps: z.array(AgentStepSchema),
+    omittedGroups: z.array(AgentOmittedGroupSchema),
+    unclassifiedEvidenceIndexes: z.array(ManifestIndexSchema),
+    focus: z.array(AgentFocusSchema).optional(),
+    testExecution: z.array(TestExecutionSchema).max(5).optional(),
+});
 function duplicated(values) {
     const seen = new Set();
     const dupes = new Set();
@@ -182,21 +235,31 @@ function validateStepPlan(document, input, meaningfulEvidence) {
         if ((stepIndex.get(before.id) ?? 0) < (stepIndex.get(after.id) ?? 0))
             continue;
         if (after.forwardRefs[constraint.symbol] !== before.id) {
-            throw new Error(`Analysis step order violates symbol ${constraint.symbol}: ${before.id} must come before ${after.id}. Reorder the steps, or declare forwardRefs {"${constraint.symbol}":"${before.id}"} on ${after.id} if the forward use is intentional.`);
+            throw new Error(`Analysis step order violates symbol ${constraint.symbol}: ${before.id} must come before ${after.id}. Reorder the steps, or declare forwardRefs [{"symbol":"${constraint.symbol}","introducedByStepId":"${before.id}"}] on ${after.id} if the forward use is intentional.`);
         }
     }
 }
+const AGENT_ANALYSIS_FORMAT = `Return exactly one JSON object using explicit property names. This is intentionally more verbose than the legacy compact format: never use the short keys s, c, t, o, u, f, or x; never use positional arrays or hunk ID strings.
+
+The top-level properties are summary, chapters, steps, omittedGroups, unclassifiedEvidenceIndexes, and optionally focus and testExecution. Chapters are objects with id, title, kind, synopsis, before, after, confidence, attention, riskCategories, and evidenceIndexes. Use null for before or after when there is no concrete before or after description. Steps are objects with id, title, goal, youNowHave, deferred, dependsOn, forwardRefs, advancesChapterIds, and evidenceIndexes. Each deferred item is an object with concern and optional resolvedByStepId; use null when no later step resolves it. Each forward reference is an object with symbol and introducedByStepId. Focus is an array of objects with evidenceIndex and ranges; each range is an object with startLine and endLine. Test executions are objects with command, outcome, summary, and source.
+
+All evidenceIndexes and unclassifiedEvidenceIndexes values are zero-based integer indexes into the numbered review manifest. Each meaningful evidence index must appear exactly once in a chapter, omitted group, or unclassifiedEvidenceIndexes, and exactly once in steps. Group every low-signal evidence index into an omitted group with a short reason; unclassifiedEvidenceIndexes is a last resort. Focus drives the Evidence zoom excerpts: include it only for chapter evidence and give each focused evidence index 1-3 new-file line ranges. Omit testExecution when no run was actually observed; never invent execution evidence. Use empty arrays for no deferred concerns, dependencies, forward references, omitted groups, or unclassified evidence. This is the canonical shape, and every object field must be present except before, after, resolvedByStepId, focus, and testExecution.
+
+Canonical shape:
+{"summary":"...","chapters":[{"id":"chapter-01","title":"...","kind":"behavior","synopsis":"...","before":null,"after":null,"confidence":"medium","attention":"contained","riskCategories":["behavior"],"evidenceIndexes":[0]}],"steps":[{"id":"step-01","title":"...","goal":"...","youNowHave":"...","deferred":[{"concern":"...","resolvedByStepId":null}],"dependsOn":[],"forwardRefs":[],"advancesChapterIds":["chapter-01"],"evidenceIndexes":[0]}],"omittedGroups":[],"unclassifiedEvidenceIndexes":[],"focus":[{"evidenceIndex":0,"ranges":[{"startLine":10,"endLine":12}]}],"testExecution":[{"command":"npm test","outcome":"passed","summary":"...","source":"repository"}]}`;
 export function analysisPrompt(input, conversation) {
     const reviewInput = buildPromptReviewInput(input, conversation);
-    return `You are ndrstnd, a comprehension assistant. Explain a branch without critiquing it or proposing changes. Prioritize the implementation story and behavior changes. Return compact minified JSON only with this shape: {s,c:[[id,title,kind,synopsis,before|null,after|null,confidence,attention,riskCategories,evidenceIds]],t:[[id,title,goal,youNowHave,[[concern,resolvedByStepId|null]],dependsOn,forwardRefs,advancesChapterIds,evidenceIds]],o:[[title,reason,evidenceIds]],u:[evidenceId],f:{evidenceId:[[startLine,endLine]]},x:[[command,outcome,summary,source]]}. In each c tuple, position 3 is kind and may be exactly feature, decision, behavior, non_functional, risk, test, or other; position 9 is riskCategories and may contain only formatting, refactor, behavior, performance, or security. Confidence is high, medium, or low. Attention is low, contained, elevated, high, or critical. Use only listed evidence IDs. Every meaningful evidence ID must appear exactly once in c, o, or u, and exactly once in t. Group every low-signal evidence ID into an omitted group in o with a concise reason such as lockfile churn or generated output; u is a last resort for evidence that truly cannot be classified. f drives the Evidence zoom excerpts: for every evidence ID used in c, list 1-3 [startLine,endLine] ranges of new-file line numbers marking the exact lines a reviewer must read first - the load-bearing statements, not whole hunks, imports, or boilerplate. Each range must fall inside that hunk's new-file lines; inspect the patch to choose them precisely. x reports test or build runs that were actually observed: when the conversation or repository shows a command and its result, add [command,outcome,summary,source] with outcome passed, failed, mixed, or unknown and source conversation or repository. Omit x entirely when no run was observed - never invent execution evidence.
+    return `You are ndrstnd, a comprehension assistant. Explain a branch without critiquing it or proposing changes. Prioritize the implementation story and behavior changes.
+
+${AGENT_ANALYSIS_FORMAT}
 
 Prose depth is validated and out-of-range fields are rejected, so hit these word counts: summary ${PROSE_WORD_RANGES.summary.min}-${PROSE_WORD_RANGES.summary.max} words; each synopsis ${PROSE_WORD_RANGES.synopsis.min}-${PROSE_WORD_RANGES.synopsis.max} words across two or three sentences explaining what changed, how it works, and why it matters; before and after ${PROSE_WORD_RANGES.beforeAfter.min}-${PROSE_WORD_RANGES.beforeAfter.max} words each describing concrete observable behavior; each step goal ${PROSE_WORD_RANGES.goal.min}-${PROSE_WORD_RANGES.goal.max} words stating the intent and mechanism; each youNowHave ${PROSE_WORD_RANGES.youNowHave.min}-${PROSE_WORD_RANGES.youNowHave.max} words stating the capability that now exists. Titles stay under 10 words. Name the actual functions, types, and files involved. Never answer with a single vague sentence, and never pad - every sentence must add information a reviewer can act on.
 
-Timeline steps are a rational reconstruction of how to build this branch. They are not commit chronology, file order, or the Story chapters repeated. Each step must be one capability increment; explain its intent in goal, its postcondition in youNowHave, intentionally postponed concerns in deferred, earlier step ids in dependsOn, unavoidable forward symbol uses in forwardRefs as {"Symbol":"later-step-id"}, the Story chapters it advances, and its evidence IDs. The manifest's construction.defineBeforeUse entries are hard ordering rules: each symbol must be defined in the same or an earlier step than its use, or the using step must declare it in forwardRefs. construction.suggestedEvidenceOrder is one valid linearization you may regroup into steps.
+Timeline steps are a rational reconstruction of how to build this branch. They are not commit chronology, file order, or the Story chapters repeated. Each step must be one capability increment; explain its intent in goal, its postcondition in youNowHave, intentionally postponed concerns in deferred, earlier step ids in dependsOn, unavoidable forward symbol uses in forwardRefs as objects with symbol and introducedByStepId, the Story chapters it advances, and its evidence indexes. The manifest's construction.defineBeforeUse entries are hard ordering rules: each symbol must be defined in the same or an earlier step than its use, or the using step must declare it in forwardRefs. construction.suggestedEvidenceOrder is one valid linearization of manifest indexes you may regroup into steps.
 
 When the review input includes conversation, it is the dialogue between the user and the coding agent that produced this branch. Treat it as primary evidence of intent: explain why changes were made, which alternatives were considered or rejected, and which incidents, requirements, or downstream consumers motivated them, weaving those stated reasons into the summary, chapter synopses, before/after, step goals, and deferred concerns instead of guessing intent from the code alone. Attribute reasons faithfully - never invent motives the conversation does not support, and never copy credentials or secrets from it. When conversation is absent, ground every claim in the diff and repository alone.
 
-You are running in the reviewed repository with a read-only sandbox. The review input below is a compact manifest. Hunks that carry a patch field include their complete diff text inline - never re-fetch those with git. For hunks without inline patch text, or when you need surrounding code, use the file paths, hunk IDs, line anchors, and suggested git commands to inspect only what you still need for a high-quality comprehension story. Prefer grouping related evidence IDs by behavior or decision instead of mirroring path order.
+You are running in the reviewed repository with a read-only sandbox. The review input below is a compact manifest. Hunks that carry a patch field include their complete diff text inline - never re-fetch those with git. For hunks without inline patch text, or when you need surrounding code, use the file paths, manifest indexes, line anchors, and suggested git commands to inspect only what you still need for a high-quality comprehension story. Prefer grouping related evidence indexes by behavior or decision instead of mirroring path order.
 
 Review input:
 ${JSON.stringify(reviewInput)}`;
@@ -212,7 +275,7 @@ export function buildPromptReviewInput(input, conversation) {
     const filesById = new Map(input.files.map((file) => [file.id, file]));
     const hunksByFile = new Map();
     let inlinePatchBudget = INLINE_PATCH_BUDGET;
-    for (const hunk of input.hunks) {
+    for (const [index, hunk] of input.hunks.entries()) {
         const file = filesById.get(hunk.fileId);
         let patch;
         if (file?.signal === "meaningful" && !file.binary && hunk.lines.length > 0) {
@@ -222,7 +285,7 @@ export function buildPromptReviewInput(input, conversation) {
                 patch = text;
             }
         }
-        const compact = compactHunk(hunk, file?.path, patch);
+        const compact = compactHunk(hunk, file?.path, patch, index);
         const list = hunksByFile.get(hunk.fileId) ?? [];
         list.push(compact);
         hunksByFile.set(hunk.fileId, list);
@@ -237,7 +300,7 @@ export function buildPromptReviewInput(input, conversation) {
             summaryCommand: `git diff --stat --find-renames --find-copies ${diffRange(input)}`,
             patchCommand: `git diff --no-ext-diff --unified=80 --find-renames --find-copies ${diffRange(input)} -- <path>`,
             currentFileCommand: "sed -n '<start>,<end>p' <path>",
-            note: "Hunks with a patch field carry their complete diff inline; run the patch command only for hunks without one or when surrounding code matters. For untracked working-tree files, inspect the current file directly and use the manifest hunk anchors as evidence IDs.",
+            note: "Hunks with a patch field carry their complete diff inline; run the patch command only for hunks without one or when surrounding code matters. For untracked working-tree files, inspect the current file directly. Refer to hunks by their numbered manifest index, never by inventing an identifier.",
         },
         files: input.files.map((file) => ({
             id: file.id,
@@ -250,10 +313,10 @@ export function buildPromptReviewInput(input, conversation) {
             hunks: hunksByFile.get(file.id) ?? [],
         })),
         construction: {
-            suggestedEvidenceOrder: evidenceOrder.orderedEvidenceIds,
+            suggestedEvidenceOrder: evidenceOrder.orderedEvidenceIds.map((id) => input.hunks.findIndex((hunk) => hunk.id === id)),
             defineBeforeUse: evidenceOrder.constraints
                 .filter((constraint) => constraint.reason === "symbol")
-                .map((constraint) => ({ symbol: constraint.symbol, definedIn: constraint.beforeEvidenceId, usedIn: constraint.afterEvidenceId })),
+                .map((constraint) => ({ symbol: constraint.symbol, definedIn: input.hunks.findIndex((hunk) => hunk.id === constraint.beforeEvidenceId), usedIn: input.hunks.findIndex((hunk) => hunk.id === constraint.afterEvidenceId) })),
         },
         conversation: compactConversation(conversation),
     };
@@ -265,88 +328,213 @@ const CompactChapterSchema = z.tuple([
     z.string().min(1).max(80),
     z.string().min(1).max(120),
     KindSchema,
-    z.string().min(1).max(420),
-    z.string().max(300).nullable(),
-    z.string().max(300).nullable(),
+    z.string().min(1).max(1_200),
+    z.string().max(900).nullable(),
+    z.string().max(900).nullable(),
     ConfidenceSchema,
     z.enum(["low", "contained", "elevated", "high", "critical"]),
     z.array(CompactRiskCategorySchema),
-    z.array(z.string().min(1)).min(1),
+    z.array(z.union([z.number().int().min(0), z.string().min(1)])).min(1),
 ]);
 const CompactStepSchema = z.tuple([
     z.string().min(1).max(80),
     z.string().min(1).max(120),
-    z.string().min(1).max(320),
-    z.string().min(1).max(320),
-    z.array(z.tuple([z.string().min(1).max(220), z.string().min(1).max(80).nullable()])),
+    z.string().min(1).max(900),
+    z.string().min(1).max(900),
+    z.array(z.tuple([z.string().min(1).max(700), z.string().min(1).max(80).nullable()])),
     z.array(z.string().min(1).max(80)),
     z.record(z.string().min(1), z.string().min(1).max(80)),
     z.array(z.string().min(1).max(80)).min(1),
-    z.array(z.string().min(1)).min(1),
+    z.array(z.union([z.number().int().min(0), z.string().min(1)])).min(1),
 ]);
+const CompactEvidenceRefSchema = z.union([z.number().int().min(0), z.string().min(1)]);
+const CompactChapterObjectSchema = z.object({
+    id: z.string().min(1).max(80),
+    title: z.string().min(1).max(120),
+    kind: KindSchema,
+    synopsis: z.string().min(1).max(1_200),
+    before: z.string().max(900).nullable().optional(),
+    after: z.string().max(900).nullable().optional(),
+    confidence: ConfidenceSchema,
+    attention: z.enum(["low", "contained", "elevated", "high", "critical"]),
+    riskCategories: z.array(CompactRiskCategorySchema),
+    evidenceIndexes: z.array(z.number().int().min(0)).min(1),
+});
+const CompactStepObjectSchema = z.object({
+    id: z.string().min(1).max(80),
+    title: z.string().min(1).max(120),
+    goal: z.string().min(1).max(900),
+    youNowHave: z.string().min(1).max(900),
+    deferred: z.array(AgentDeferredSchema),
+    dependsOn: z.array(z.string().min(1).max(80)),
+    forwardRefs: z.record(z.string().min(1), z.string().min(1).max(80)),
+    advancesChapterIds: z.array(z.string().min(1).max(80)).min(1),
+    evidenceIndexes: z.array(z.number().int().min(0)).min(1),
+});
+const CompactOmittedGroupSchema = z.tuple([z.string().min(1).max(240), z.string().min(1).max(700), z.array(CompactEvidenceRefSchema).min(1)]);
+const CompactOmittedGroupObjectSchema = z.object({ title: z.string().min(1).max(240), reason: z.string().min(1).max(700), evidenceIndexes: z.array(z.number().int().min(0)).min(1) });
 const CompactAnalysisDocumentSchema = z.object({
-    s: z.string().min(1).max(560),
-    c: z.array(CompactChapterSchema),
-    t: z.array(CompactStepSchema),
-    o: z.array(z.tuple([z.string().min(1).max(120), z.string().min(1).max(220), z.array(z.string().min(1)).min(1)])),
-    u: z.array(z.string().min(1)),
+    s: z.string().min(1).max(1_600),
+    c: z.array(z.union([CompactChapterSchema, CompactChapterObjectSchema])),
+    t: z.array(z.union([CompactStepSchema, CompactStepObjectSchema])),
+    o: z.array(z.union([CompactOmittedGroupSchema, CompactOmittedGroupObjectSchema])),
+    u: z.array(CompactEvidenceRefSchema),
     f: z.record(z.string().min(1), z.array(z.tuple([z.number().int().min(1), z.number().int().min(1)])).min(1).max(5)).optional(),
     x: z.array(z.tuple([z.string().min(1).max(200), z.enum(["passed", "failed", "mixed", "unknown"]), z.string().min(1).max(300), z.enum(["conversation", "repository"])])).max(5).optional(),
 });
-function parseWireAnalysisDocument(value) {
+function parseWireAnalysisDocument(value, input) {
     const full = AnalysisDocumentSchema.safeParse(value);
     if (full.success)
         return full.data;
+    const agent = AgentAnalysisDocumentSchema.safeParse(value);
+    if (agent.success)
+        return normalizeAgentAnalysisDocument(agent.data, input);
     const compactResult = CompactAnalysisDocumentSchema.safeParse(value);
     if (!compactResult.success) {
         // Repair turns quote this message; reporting the schema the document was aiming for keeps those turns productive.
-        const fullShaped = value !== null && typeof value === "object" && ("summary" in value || "chapters" in value);
-        const [shape, error] = fullShaped ? ["full", full.error] : ["compact", compactResult.error];
-        throw new Error(`Analysis document did not match the ${shape} shape: ${error.issues.slice(0, 8).map((issue) => `${issue.path.join(".") || "document"}: ${issue.message}`).join("; ")}`);
+        const shape = isAgentShaped(value) ? "agent" : isFullShaped(value) ? "full" : "compact";
+        const error = shape === "agent" ? agent.error : shape === "full" ? full.error : compactResult.error;
+        throw new Error(`Analysis document did not match the ${shape} shape: ${formatSchemaIssues(error)}`);
     }
     const compact = compactResult.data;
+    const evidenceId = (reference) => typeof reference === "string" && !/^\d+$/.test(reference) ? reference : evidenceIdAtIndex(input, Number(reference));
     return AnalysisDocumentSchema.parse({
         summary: compact.s,
-        chapters: compact.c.map((chapter) => ({
-            id: chapter[0],
-            title: chapter[1],
-            kind: chapter[2],
-            synopsis: chapter[3],
-            before: chapter[4] ?? undefined,
-            after: chapter[5] ?? undefined,
-            confidence: chapter[6],
-            attention: chapter[7],
-            riskCategories: chapter[8],
-            evidenceIds: chapter[9],
-        })),
-        steps: compact.t.map((step) => ({
-            id: step[0],
-            title: step[1],
-            goal: step[2],
-            youNowHave: step[3],
+        chapters: compact.c.map((chapter) => Array.isArray(chapter) ? {
+            id: chapter[0], title: chapter[1], kind: chapter[2], synopsis: chapter[3],
+            before: chapter[4] ?? undefined, after: chapter[5] ?? undefined,
+            confidence: chapter[6], attention: chapter[7], riskCategories: chapter[8],
+            evidenceIds: chapter[9].map(evidenceId),
+        } : {
+            id: chapter.id, title: chapter.title, kind: chapter.kind, synopsis: chapter.synopsis,
+            before: chapter.before ?? undefined, after: chapter.after ?? undefined,
+            confidence: chapter.confidence, attention: chapter.attention, riskCategories: chapter.riskCategories,
+            evidenceIds: chapter.evidenceIndexes.map(evidenceId),
+        }),
+        steps: compact.t.map((step) => Array.isArray(step) ? {
+            id: step[0], title: step[1], goal: step[2], youNowHave: step[3],
             deferred: step[4].map((item) => ({ concern: item[0], resolvedByStepId: item[1] ?? undefined })),
-            dependsOn: step[5],
-            forwardRefs: step[6],
-            advancesChapterIds: step[7],
-            evidenceIds: step[8],
-        })),
-        omittedGroups: compact.o.map((group) => ({ title: group[0], reason: group[1], evidenceIds: group[2] })),
-        unclassifiedEvidenceIds: compact.u,
-        focus: compact.f === undefined ? undefined : Object.fromEntries(Object.entries(compact.f).map(([evidenceId, ranges]) => [evidenceId, ranges.map(([start, end]) => ({ start, end }))])),
+            dependsOn: step[5], forwardRefs: step[6], advancesChapterIds: step[7],
+            evidenceIds: step[8].map(evidenceId),
+        } : {
+            id: step.id, title: step.title, goal: step.goal, youNowHave: step.youNowHave,
+            deferred: step.deferred.map((item) => ({ concern: item.concern, resolvedByStepId: item.resolvedByStepId ?? undefined })),
+            dependsOn: step.dependsOn, forwardRefs: step.forwardRefs, advancesChapterIds: step.advancesChapterIds,
+            evidenceIds: step.evidenceIndexes.map(evidenceId),
+        }),
+        omittedGroups: compact.o.map((group) => Array.isArray(group) ? { title: group[0], reason: group[1], evidenceIds: group[2].map(evidenceId) } : { title: group.title, reason: group.reason, evidenceIds: group.evidenceIndexes.map(evidenceId) }),
+        unclassifiedEvidenceIds: compact.u.map(evidenceId),
+        focus: compact.f === undefined ? undefined : Object.fromEntries(Object.entries(compact.f).map(([reference, ranges]) => [evidenceId(reference), ranges.map(([start, end]) => ({ start, end }))])),
         testExecution: compact.x === undefined ? undefined : compact.x.map(([command, outcome, summary, source]) => ({ command, outcome, summary, source })),
     });
 }
+function normalizeAgentAnalysisDocument(document, input) {
+    return AnalysisDocumentSchema.parse({
+        summary: document.summary,
+        chapters: document.chapters.map((chapter) => ({
+            id: chapter.id,
+            title: chapter.title,
+            kind: chapter.kind,
+            synopsis: chapter.synopsis,
+            before: chapter.before ?? undefined,
+            after: chapter.after ?? undefined,
+            confidence: chapter.confidence,
+            attention: chapter.attention,
+            riskCategories: chapter.riskCategories,
+            evidenceIds: chapter.evidenceIndexes.map((index) => evidenceIdAtIndex(input, index)),
+        })),
+        steps: document.steps.map((step) => ({
+            id: step.id,
+            title: step.title,
+            goal: step.goal,
+            youNowHave: step.youNowHave,
+            deferred: step.deferred.map((item) => ({ concern: item.concern, resolvedByStepId: item.resolvedByStepId ?? undefined })),
+            dependsOn: step.dependsOn,
+            forwardRefs: normalizeForwardRefs(step.id, step.forwardRefs),
+            advancesChapterIds: step.advancesChapterIds,
+            evidenceIds: step.evidenceIndexes.map((index) => evidenceIdAtIndex(input, index)),
+        })),
+        omittedGroups: document.omittedGroups.map((group) => ({
+            title: group.title,
+            reason: group.reason,
+            evidenceIds: group.evidenceIndexes.map((index) => evidenceIdAtIndex(input, index)),
+        })),
+        unclassifiedEvidenceIds: document.unclassifiedEvidenceIndexes.map((index) => evidenceIdAtIndex(input, index)),
+        focus: normalizeFocus(document.focus, input),
+        testExecution: document.testExecution,
+    });
+}
+function evidenceIdAtIndex(input, index) {
+    const hunk = input.hunks[index];
+    if (hunk === undefined)
+        throw new Error(`Evidence index ${index} is outside the review input manifest.`);
+    return hunk.id;
+}
+function normalizeForwardRefs(stepId, refs) {
+    const normalized = {};
+    for (const ref of refs) {
+        if (normalized[ref.symbol] !== undefined)
+            throw new Error(`Analysis step ${stepId} declares forward reference ${ref.symbol} more than once.`);
+        normalized[ref.symbol] = ref.introducedByStepId;
+    }
+    return normalized;
+}
+function normalizeFocus(focus, input) {
+    if (focus === undefined)
+        return undefined;
+    const normalized = {};
+    for (const entry of focus) {
+        const evidenceId = evidenceIdAtIndex(input, entry.evidenceIndex);
+        if (normalized[evidenceId] !== undefined)
+            throw new Error(`Focus declares evidence index ${entry.evidenceIndex} more than once.`);
+        normalized[evidenceId] = entry.ranges.map((range) => ({ start: range.startLine, end: range.endLine }));
+    }
+    return normalized;
+}
+function isFullShaped(value) {
+    return value !== null && typeof value === "object" && ("summary" in value || "chapters" in value || "steps" in value);
+}
+function isAgentShaped(value) {
+    if (!isFullShaped(value))
+        return false;
+    if ("unclassifiedEvidenceIndexes" in value)
+        return true;
+    const objectValue = value;
+    const collections = [objectValue["chapters"], objectValue["steps"], objectValue["omittedGroups"]];
+    return collections.some((collection) => Array.isArray(collection) && collection.some((item) => item !== null && typeof item === "object" && "evidenceIndexes" in item));
+}
+function formatSchemaIssues(error) {
+    const issues = collectSchemaIssues(error).slice(0, 8);
+    return issues.length === 0
+        ? "document: Invalid input"
+        : issues.map((issue) => `${issue.path.join(".") || "document"}: ${issue.message}`).join("; ");
+}
+function collectSchemaIssues(error, prefix = []) {
+    const messages = [];
+    for (const issue of error.issues) {
+        const path = [...prefix, ...issue.path];
+        if (issue.code === "invalid_union") {
+            const nested = issue.unionErrors.flatMap((unionError) => collectSchemaIssues(unionError, path));
+            const specific = nested.filter((candidate) => candidate.path.length > path.length);
+            messages.push(...(specific.length > 0 ? specific : nested));
+        }
+        else {
+            messages.push({ path, message: issue.message });
+        }
+    }
+    return messages;
+}
 function hunkPatchText(hunk) {
     const markers = { context: " ", addition: "+", deletion: "-" };
     const oldCount = hunk.lines.filter((line) => line.kind !== "addition").length;
     const newCount = hunk.lines.filter((line) => line.kind !== "deletion").length;
     return [`@@ -${hunk.oldStart},${oldCount} +${hunk.newStart},${newCount} @@`, ...hunk.lines.map((line) => `${markers[line.kind]}${line.content}`)].join("\n");
 }
-function compactHunk(hunk, path, patch) {
+function compactHunk(hunk, path, patch, index) {
     const additions = hunk.lines.filter((line) => line.kind === "addition");
     const deletions = hunk.lines.filter((line) => line.kind === "deletion");
     const context = hunk.lines.length - additions.length - deletions.length;
-    // Samples only anchor hunk IDs to recognizable content; the agent reads the inline
+    // Samples anchor manifest indexes to recognizable content; the agent reads the inline
     // patch or inspects the real one for detail, so two short previews per hunk are enough.
     const sampleLines = deletions.length > 0 && additions.length > 0 ? [deletions[0], additions[0]] : [...deletions, ...additions].slice(0, 2);
     const changedLineSamples = sampleLines.map((line) => ({
@@ -356,7 +544,7 @@ function compactHunk(hunk, path, patch) {
         preview: line.content.trim().slice(0, 100),
     }));
     return {
-        id: hunk.id,
+        index,
         fileId: hunk.fileId,
         path,
         oldStart: hunk.oldStart,