@straiffi/archon 1.8.14 → 1.8.16

package/dist/server/workers/specSession.js

@@ -5,6 +5,7 @@ import { createSpecMessage, listSpecMessages } from '../lib/specMessages.js';
 import { beginSpecSessionThinkingRun, bindSpecSessionThinkingMessage } from '../lib/thinkingState.js';
 import { createSpecSnapshot, deriveSpecSessionTitle, getDefaultSpecSessionTitle, getSpecSession, getSpecSnapshot, resolveSpecModeValue, updateSpecSessionMode, updateSpecSessionRunConfig, updateSpecSessionStatus, updateSpecSessionTitle, updateSpecSessionUsageSnapshot, } from '../lib/specs.js';
 import { normalizeClaudeModelId, normalizeModelId } from '../lib/models.js';
+import { HttpError } from '../lib/httpError.js';
 import { appendPlanModeQuestionPromptRules, PLAN_MODE_RUNTIME_PROMPT_RULES } from '../lib/planModeQuestions.js';
 import { getProjectMemoryPromptBlock } from '../lib/projectMemoryPrompt.js';
 import { buildPlanningSubagentGuidancePromptBlock } from '../lib/promptSkills.js';
@@ -15,12 +16,13 @@ import { getProjectById } from '../lib/projects.js';
 import { addExecutionRunLink, transitionExecutionRun } from '../lib/executionRuns.js';
 import { TurnStartError } from '../lib/turnExecutionErrors.js';
 import { buildLinkedResearchContext, prepareLinkedPlanningResearch } from './plan.js';
-import { extractGrillQuestionFromOutput, extractSpecArtifactFromOutput, projectPlannerOwnedLikelyFiles, resolveCarriedForwardArtifacts, resolveCarriedForwardStructuredFields, stripMermaidBlocks } from '../lib/specArtifact.js';
+import { extractGrillQuestionFromOutput, extractSpecArtifactFromOutput, projectPlannerOwnedLikelyFiles, resolveCarriedForwardArtifacts, resolveCarriedForwardStructuredFields, stripFileRelationGraphBlocks, stripMermaidBlocks } from '../lib/specArtifact.js';
 import { createAskQuestionMetadata, extractAskQuestionFromOutput, formatAskQuestionMessage } from '../lib/planQuestions.js';
 import { collectSpecResourceUrls } from '../lib/specResources.js';
+import { resolveImportedSpecBundleName } from '../lib/specBundleGroups.js';
 import { resolveSessionTargetForExecution } from '../lib/sessionTargets.js';
-import { captureSpecSnapshotRepositoryEvidenceFromAcquisition } from '../lib/specSnapshotEvidence.js';
-import { obtainExactCompletedScan, projectSpecRepositoryImpact, reconcileSpecLikelyFiles, selectSpecRepositoryImpactSeeds, serializeSpecRepositoryImpactForPrompt } from '../lib/specRepositoryImpact.js';
+import { unavailableSpecSnapshotRepositoryEvidence } from '../lib/specSnapshotEvidenceSerialization.js';
+import { SPEC_GRAPH_DISABLED_REASON } from '../lib/specGraphFeature.js';
 import { registerBundleSpecWork, registerRepoRootSpecWork } from '../lib/specWorkspaceActivity.js';
 import { IMPLEMENTATION_BODY_DEDUPLICATION_RULES, IMPLEMENTATION_DETAIL_RULES, IMPLEMENTATION_READY_DESCRIPTION_REQUIREMENTS, IMPLEMENTATION_READY_DESCRIPTION_SECTION_TEMPLATE, } from '../lib/ticketDescriptionContract.js';
 const raceAgainstSpecCancellation = async (promise, cancellationState) => {
@@ -68,6 +70,7 @@ const getTranscriptContentFallback = (runs) => {
         || runs?.find(run => run.thinking_log?.trim())?.thinking_log?.trim()
         || '';
 };
+const stripSpecFileGraph = (value) => stripFileRelationGraphBlocks(value).trim();
 const resolveSpecWorkerKey = (specSessionId) => `spec-session:${specSessionId}`;
 /**
  * Render the prior snapshot's structured fields as a compact text block the
@@ -108,9 +111,15 @@ const formatPreviousSpecStateBlock = (snapshot) => {
             lines.push(`- ${dep.blocker_key} -> ${dep.dependent_key}`);
         }
     }
+    if ((snapshot.bundle_groups ?? []).length > 0) {
+        lines.push('Bundle groups:');
+        for (const group of snapshot.bundle_groups ?? []) {
+            lines.push(`- ${group.key} (${group.name}): ${group.ticket_keys.join(', ')}`);
+        }
+    }
     return lines.join('\n');
 };
-const buildStandardModeTail = ({ existingMermaid, existingMockup, existingFileRelationGraph, }) => {
+const buildStandardModeTail = ({ existingMermaid, existingMockup, bundleGroupingInstruction, }) => {
     return [
         [
             'Turn handling:',
@@ -124,25 +133,12 @@ const buildStandardModeTail = ({ existingMermaid, existingMockup, existingFileRe
             '   (carry-forward status, prior-turn JSON bugs, re-emission rationale, or notes about what the',
             '   artifact "still contains"). The reader never needs to know that information was carried forward.',
             '',
-            '2. Diagrams. Emit TWO mermaid diagrams as separate fenced blocks — they serve different purposes and',
-            '   the UI renders them in different panels (Visualization vs Likely Files), so do not merge them into',
-            '   one block. Both are normally expected on a plan update that touches code; skip one only when its',
-            '   subject matter is genuinely absent.',
-            '   a. A `mermaid` block — the ARCHITECTURE/data-flow diagram (components, request lifecycle, module',
-            '      boundaries, data flow). Use `flowchart TD` for hierarchical/architectural layouts, `flowchart LR`',
-            '      for timelines or sequential flows. Nodes here are abstract roles ("API server", "DB", "client"),',
-            '      NOT individual source files. Skip only for trivial single-step plans with no architecture to depict.',
-            '   b. An `archon-file-graph` block — the FILE-RELATION diagram: literal edges between the entries in',
-            '      `likely_files` (A imports B, A calls B, A extends B, etc.). Use `flowchart LR` and reference the',
-            '      SAME file paths used in `likely_files` so the reader can cross-reference. Emit this block whenever',
-            '      `likely_files` contains 3 or more files that import, call, or otherwise depend on each other;',
-            '      omit it only when the files are genuinely independent (a flat list with no cross-file edges).',
-            '      Do NOT duplicate the architecture diagram here — if a node is "the API server" it belongs in (a),',
-            '      if it is "src/server/api.ts" it belongs in (b).',
-            '   The fence language tag determines where the diagram renders: a plain `mermaid` block renders in the',
-            '   Visualization slot, an `archon-file-graph` block renders under Likely Files. Putting file-relation',
-            '   content in a plain `mermaid` block lands it in the wrong slot.',
-            '   Mermaid syntax rules apply to BOTH diagrams (a single bad label fails the whole diagram):',
+            '2. When the plan has architecture or data flow to show, emit one `mermaid` block for the',
+            '   ARCHITECTURE/data-flow diagram (components, request lifecycle, module boundaries, data flow). Use',
+            '   `flowchart TD` for hierarchical/architectural layouts or `flowchart LR` for timelines and sequential',
+            '   flows. Nodes here are abstract roles ("API server", "DB", "client"), NOT individual source files.',
+            '   Skip it for trivial plans with no architecture to depict.',
+            '   Mermaid syntax rules apply to this diagram:',
             '   - Quote EVERY node label that contains anything other than letters, digits, spaces, or hyphens, using',
             '     the bracket-quoted form `ID["label text"]`. File paths, function signatures, and any text with `.`,',
             '     `/`, `(`, `)`, `[`, `]`, `"`, `&`, `<`, `>`, or `|` MUST be quoted.',
@@ -153,8 +149,6 @@ const buildStandardModeTail = ({ existingMermaid, existingMockup, existingFileRe
             '   Example:',
             '     Good:  MA["MobileApp.tsx"] --> API["mobileApi.ts"]',
             '     Bad:   MA[MobileApp.tsx] --> API[mobileApi.ts]   %% tolerated, but any `)` or `]` in a bare label is a hard parse failure',
-            '   The `archon-file-graph` block is for human review only and is never forwarded to the build agent or',
-            '   included in any ticket description.',
             '',
             '3. When (and only when) the plan involves a UI surface, optionally include a low-fidelity UI mockup as a',
             '   self-contained, generic, unstyled HTML wireframe inside a fenced `archon-mockup` block. Use plain',
@@ -165,7 +159,7 @@ const buildStandardModeTail = ({ existingMermaid, existingMockup, existingFileRe
             '',
             '4. A machine-readable artifact block with the spec structured data, using exactly these markers:',
             '   <archon-spec-artifact>',
-            '   {"summary":"short plan summary","likely_files":[{"path":"src/foo.ts","reason":"Add bar helper","is_new":false},{"path":"src/newHelper.ts","reason":"Provide the new shared helper","is_new":true}],"tickets":[{"key":"add-foo-bar","title":"Add bar helper to foo module","description":"## Problem Statement\\nThe foo module is missing the `bar` helper, blocking downstream consumers from validating inputs consistently.\\n\\n## Acceptance Criteria\\n- [ ] A `bar(input)` function is exported from `src/foo.ts`.\\n- [ ] Invalid inputs throw a typed error with a clear message.\\n- [ ] All existing callers of foo continue to work unchanged.\\n\\n## Implementation Approach\\n1. Add `bar` to `src/foo.ts` following the existing `baz` helper signature pattern.\\n2. Reuse the project existing validation utilities instead of inlining checks.\\n3. Export `bar` from the module barrel file.\\n\\n## Edge Cases and Error Handling\\n- Empty string inputs should throw the same typed error as other invalid inputs.\\n- Preserve current behavior for `undefined`/`null` (do not coerce).\\n\\n## Constraints and Things to Avoid\\n- Do not introduce a new dependency.\\n- Do not change the public signature of existing exports."},{"key":"use-bar-in-consumer","title":"Call bar from consumer module","description":"## Problem Statement\\nThe consumer module duplicates input validation that `bar` now provides.\\n\\n## Acceptance Criteria\\n- [ ] Consumer calls `bar` instead of its own inline validation.\\n- [ ] Existing consumer tests still pass.\\n\\n## Implementation Approach\\n1. Replace the inline check in consumer with a call to `bar`.\\n2. Remove the now-unused validation helper from consumer.\\n\\n## Edge Cases and Error Handling\\n- Consumer must handle the typed errors thrown by `bar`.\\n\\n## Constraints and Things to Avoid\\n- Do not change the consumer public API."}],"dependencies":[{"blocker_key":"add-foo-bar","dependent_key":"use-bar-in-consumer"}]}',
+            '   {"summary":"short plan summary","likely_files":[{"path":"src/foo.ts","reason":"Add bar helper","is_new":false},{"path":"src/newHelper.ts","reason":"Provide the new shared helper","is_new":true}],"tickets":[{"key":"add-foo-bar","title":"Add bar helper to foo module","description":"## Problem Statement\\nThe foo module is missing the `bar` helper, blocking downstream consumers from validating inputs consistently.\\n\\n## Acceptance Criteria\\n- [ ] A `bar(input)` function is exported from `src/foo.ts`.\\n- [ ] Invalid inputs throw a typed error with a clear message.\\n- [ ] All existing callers of foo continue to work unchanged.\\n\\n## Implementation Approach\\n1. Add `bar` to `src/foo.ts` following the existing `baz` helper signature pattern.\\n2. Reuse the project existing validation utilities instead of inlining checks.\\n3. Export `bar` from the module barrel file.\\n\\n## Edge Cases and Error Handling\\n- Empty string inputs should throw the same typed error as other invalid inputs.\\n- Preserve current behavior for `undefined`/`null` (do not coerce).\\n\\n## Constraints and Things to Avoid\\n- Do not introduce a new dependency.\\n- Do not change the public signature of existing exports."},{"key":"use-bar-in-consumer","title":"Call bar from consumer module","description":"## Problem Statement\\nThe consumer module duplicates input validation that `bar` now provides.\\n\\n## Acceptance Criteria\\n- [ ] Consumer calls `bar` instead of its own inline validation.\\n- [ ] Existing consumer tests still pass.\\n\\n## Implementation Approach\\n1. Replace the inline check in consumer with a call to `bar`.\\n2. Remove the now-unused validation helper from consumer.\\n\\n## Edge Cases and Error Handling\\n- Consumer must handle the typed errors thrown by `bar`.\\n\\n## Constraints and Things to Avoid\\n- Do not change the consumer public API."}],"dependencies":[{"blocker_key":"add-foo-bar","dependent_key":"use-bar-in-consumer"}],"bundle_groups":[{"key":"core-change","name":"foo-validation","ticket_keys":["add-foo-bar","use-bar-in-consumer"]}]}',
             '   </archon-spec-artifact>',
             '',
             'The artifact represents the complete current state of the spec. On follow-up turns, re-emit every field',
@@ -207,8 +201,10 @@ const buildStandardModeTail = ({ existingMermaid, existingMockup, existingFileRe
             '    work). Omit the field or emit `[]` for tickets that need neither (e.g. pure backend work). The system',
             '    appends the tagged blocks as text; never embed the diagram or mockup source in the description yourself.',
             '- `dependencies` — array of objects with `blocker_key` (the ticket key that must be done first) and `dependent_key` (the ticket key that depends on the blocker). Only include direct blockers, not transitive dependencies. Every key must reference one of the generated ticket keys.',
+            '- `bundle_groups` (required for a new spec) — ordered array of {"key":"stable-kebab-key","name":"short-branch-safe-name","ticket_keys":["ticket-key"]}. Every ticket must appear exactly once, groups and effective names must be unique, groups cannot be empty, and dependencies cannot cross groups.',
+            bundleGroupingInstruction,
             '',
-            'For the optional array fields (assumptions, open_questions, likely_files, dependencies):',
+            'For the optional array fields (assumptions, open_questions, likely_files, dependencies, bundle_groups):',
             '- OMIT a field to leave it unchanged from the prior snapshot — it is carried forward automatically.',
             '- Emit an array to set the field to that exact value this turn. Emit `[]` ONLY to intentionally clear it.',
             '- When the plan changes a field, re-emit it with the updated contents. Do not silently drop entries that',
@@ -218,8 +214,6 @@ const buildStandardModeTail = ({ existingMermaid, existingMockup, existingFileRe
             'automatically from the fenced code block above.',
             'Do NOT include the UI mockup in the artifact JSON — the `archon-mockup` block is extracted',
             'automatically from its fenced code block above when present.',
-            'Do NOT include the file-relation graph in the artifact JSON — the `archon-file-graph` block is extracted',
-            'automatically from its fenced code block above when present, and is for human review only.',
             'A per-ticket `relevant_visualizations` tag array IS allowed — it references the blocks by key and does',
             'not duplicate their content.',
             '',
@@ -234,19 +228,19 @@ const buildStandardModeTail = ({ existingMermaid, existingMockup, existingFileRe
             '- If no dependencies are needed, return an empty dependencies array.',
             '- If the artifact block is missing or malformed, no specification snapshot will be saved.',
         ].join('\n'),
-        (existingMermaid || existingMockup || existingFileRelationGraph)
+        (existingMermaid || existingMockup)
             ? [
-                'A `mermaid` diagram, `archon-mockup` UI wireframe, and/or `archon-file-graph` file-relation diagram',
+                'A `mermaid` diagram and/or `archon-mockup` UI wireframe',
                 'has already been established for this spec in a prior turn and is preserved automatically across',
                 'turns. Do NOT regenerate any of these fenced blocks unless this turn materially changes the',
-                'architecture, UI, or file relationships it depicts — re-emitting unchanged content wastes tokens.',
-                'Omit the `mermaid`, `archon-mockup`, and/or `archon-file-graph` blocks on this turn when they would',
+                'architecture or UI it depicts — re-emitting unchanged content wastes tokens.',
+                'Omit the `mermaid` and/or `archon-mockup` blocks on this turn when they would',
                 'be unchanged; they will be carried forward from the previous snapshot automatically.',
             ].join('\n')
             : '',
     ].filter(Boolean).join('\n\n');
 };
-const buildGrillModeTail = () => {
+const buildGrillModeTail = (bundleGroupingInstruction) => {
     return [
         [
             'GRILL MODE: You are pressure-testing this spec before it is written. Do NOT emit the full plan or the',
@@ -294,11 +288,11 @@ const buildGrillModeTail = () => {
         [
             'Standard spec artifact emission rules (use ONLY on the turn you finalize the plan):',
             '',
-            buildStandardModeTail({ existingMermaid: false, existingMockup: false, existingFileRelationGraph: false }),
+            buildStandardModeTail({ existingMermaid: false, existingMockup: false, bundleGroupingInstruction }),
         ].join('\n'),
     ].join('\n\n');
 };
-const buildSpecPrompt = ({ projectName, projectPath, instruction, hasAttachments, projectMemory, memoryEnabled, previousSnapshot, linkedResearchContext, repositoryImpactContext, mode, }) => {
+const buildSpecPrompt = ({ projectName, projectPath, instruction, hasAttachments, projectMemory, memoryEnabled, previousSnapshot, linkedResearchContext, mode, targetKind, targetBundleName, externalKey, }) => {
     const trimmedInstruction = instruction.trim();
     const attachmentPrompt = hasAttachments
         ? 'One or more user-attached images are included with this turn. Inspect them for requirements, visual constraints, and implementation context.'
@@ -313,7 +307,11 @@ const buildSpecPrompt = ({ projectName, projectPath, instruction, hasAttachments
             : '';
     const existingMermaid = Boolean(previousSnapshot?.mermaid);
     const existingMockup = Boolean(previousSnapshot?.mockup);
-    const existingFileRelationGraph = Boolean(previousSnapshot?.file_relation_graph);
+    const bundleGroupingInstruction = targetKind === 'bundle'
+        ? `This spec targets the existing bundle "${targetBundleName ?? 'captured bundle'}". Emit exactly one group containing every ticket; multi-bundle output is invalid and the captured bundle will be used.`
+        : externalKey
+            ? `This is an imported spec. Group tickets independently as justified, but bundle names are ignored and persisted deterministically as ${resolveImportedSpecBundleName(externalKey, 0)}, ${resolveImportedSpecBundleName(externalKey, 1)}, and onward in group order.`
+            : 'Choose one or more independently buildable PR-oriented groups with short branch-safe names. If the user requests an exact count, use it only when that exact number of non-empty independent groups is justified; otherwise ask the user to reconsider and do not emit an artifact.';
     const previousSpecBaseline = previousSnapshot
         ? [
             'This spec already exists from prior turns. Treat the spec as accumulating: the artifact you emit this',
@@ -338,15 +336,14 @@ const buildSpecPrompt = ({ projectName, projectPath, instruction, hasAttachments
         `Project: ${projectName}\nWorking directory: ${projectPath}`,
         projectMemory,
         linkedResearchContext,
-        repositoryImpactContext,
         previousSpecBaseline,
         attachmentPrompt,
         attachmentResponseInstruction,
         userRequest,
     ];
     const modeTail = mode === 'grill'
-        ? buildGrillModeTail()
-        : buildStandardModeTail({ existingMermaid, existingMockup, existingFileRelationGraph });
+        ? buildGrillModeTail(bundleGroupingInstruction)
+        : buildStandardModeTail({ existingMermaid, existingMockup, bundleGroupingInstruction });
     const prompt = [
         ...sharedBlocks,
         modeTail,
@@ -545,15 +542,6 @@ export const startSpecSessionTurn = ({ specSessionId, instruction, attachments =
                     ? { kind: 'bundle', bundle_id: runnableTarget.target.target_bundle_id }
                     : { kind: 'repo_root', bundle_id: null };
                 const requestedMode = turnMode ?? resolveSpecModeValue(latestSession.mode);
-                let consultedScan = {
-                    state: 'fallback',
-                    reason: 'acquisition_failed',
-                    message: 'Repository graph evidence was not acquired for this turn mode.',
-                };
-                let repositoryImpactContext = '';
-                const scanAcquisition = requestedMode === 'standard'
-                    ? obtainExactCompletedScan(latestProject, targetDescriptor)
-                    : Promise.resolve(consultedScan);
                 const promptContext = latestSession.title === getDefaultSpecSessionTitle()
                     ? null
                     : latestSession.title;
@@ -565,39 +553,20 @@ export const startSpecSessionTurn = ({ specSessionId, instruction, attachments =
                     currentInstruction: trimmedInstruction,
                     invocation: { parentType: 'spec', parentId: specSessionId, agentRunId: mainRunId },
                 });
-                const preResponseContext = await raceAgainstSpecCancellation(Promise.all([
-                    trimmedInstruction
-                        ? prepareLinkedPlanningResearch(trimmedInstruction, {
-                            projectId: latestProject.id,
-                            cwd,
-                            tool: resolvedTool,
-                            model: resolvedModel,
-                            variant: resolvedVariant,
-                            skills: resolvedSkills,
-                            executionContext,
-                            cancellationState: specCancellation,
-                            agentRunParent: { parentType: 'spec', parentId: specSessionId, io },
-                        })
-                        : Promise.resolve([]),
-                    scanAcquisition,
-                ]), specCancellation);
-                const [linkedResearch, acquiredScan] = preResponseContext.cancelled
-                    ? [[], consultedScan]
-                    : preResponseContext.value;
-                consultedScan = acquiredScan;
-                if (consultedScan.state === 'ready') {
-                    const promptSeeds = selectSpecRepositoryImpactSeeds({
-                        plannerLikelyFiles: projectPlannerOwnedLikelyFiles(previousSnapshot?.likely_files ?? []),
-                        instruction: trimmedInstruction,
-                    });
-                    if (promptSeeds.length > 0) {
-                        repositoryImpactContext = serializeSpecRepositoryImpactForPrompt(projectSpecRepositoryImpact({
-                            projectId: latestProject.id,
-                            scanId: consultedScan.scan.id,
-                            seeds: promptSeeds,
-                        }));
-                    }
-                }
+                const preResponseContext = await raceAgainstSpecCancellation(trimmedInstruction
+                    ? prepareLinkedPlanningResearch(trimmedInstruction, {
+                        projectId: latestProject.id,
+                        cwd,
+                        tool: resolvedTool,
+                        model: resolvedModel,
+                        variant: resolvedVariant,
+                        skills: resolvedSkills,
+                        executionContext,
+                        cancellationState: specCancellation,
+                        agentRunParent: { parentType: 'spec', parentId: specSessionId, io },
+                    })
+                    : Promise.resolve([]), specCancellation);
+                const linkedResearch = preResponseContext.cancelled ? [] : preResponseContext.value;
                 // Honor an interrupt that arrived during the pre-response window. There
                 // is no child to kill and no partial response to save; transition straight
                 // to 'stopped' (worker-owned, mirroring how Chat finalizes after a stop).
@@ -636,8 +605,10 @@ export const startSpecSessionTurn = ({ specSessionId, instruction, attachments =
                     memoryEnabled: Boolean(latestProject.memory_enabled),
                     previousSnapshot,
                     linkedResearchContext,
-                    repositoryImpactContext,
                     mode: requestedMode,
+                    targetKind: runnableTarget.target.target_kind,
+                    targetBundleName: latestSession.target_branch_snapshot,
+                    externalKey: latestSession.external_source?.external_key ?? null,
                 });
                 const specRunResult = await runSpecAgent({
                     specSessionId,
@@ -658,9 +629,9 @@ export const startSpecSessionTurn = ({ specSessionId, instruction, attachments =
                 });
                 if (specRunResult.completionStatus === 'stopped') {
                     const interruptedSession = getSpecSession(specSessionId);
-                    const interruptedResponse = interruptedSession?.streaming_response?.trim()
-                        || specRunResult.finalResponse?.trim()
-                        || getTranscriptContentFallback(specRunResult.transcriptRuns)
+                    const interruptedResponse = stripSpecFileGraph(interruptedSession?.streaming_response ?? '')
+                        || stripSpecFileGraph(specRunResult.finalResponse ?? '')
+                        || stripSpecFileGraph(getTranscriptContentFallback(specRunResult.transcriptRuns))
                         || '';
                     if (resolvedTool === 'opencode' && interruptedSession?.title === getDefaultSpecSessionTitle()) {
                         updateSpecSessionTitle(specSessionId, deriveSpecSessionTitle(trimmedInstruction));
@@ -725,9 +696,9 @@ export const startSpecSessionTurn = ({ specSessionId, instruction, attachments =
                         throw new Error(`Invalid Grill question envelope: ${grillResult.error}`);
                     }
                     if (grillResult.grillQuestion) {
-                        const cleanedGrillText = grillResult.cleanedOutput.trim()
+                        const cleanedGrillText = stripSpecFileGraph(grillResult.cleanedOutput)
                             || grillResult.grillQuestion.question
-                            || streamedAssistantMessage.trim();
+                            || stripSpecFileGraph(streamedAssistantMessage);
                         const grillMessageId = createSpecMessage({
                             specSessionId,
                             role: 'assistant',
@@ -775,7 +746,7 @@ export const startSpecSessionTurn = ({ specSessionId, instruction, attachments =
                     throw new Error(`Invalid question envelope: ${askQuestionResult.error}`);
                 }
                 if (askQuestionResult.questionSet) {
-                    const questionMessage = askQuestionResult.cleanedOutput.trim() || formatAskQuestionMessage(askQuestionResult.questionSet);
+                    const questionMessage = stripSpecFileGraph(askQuestionResult.cleanedOutput) || formatAskQuestionMessage(askQuestionResult.questionSet);
                     const messageId = createSpecMessage({
                         specSessionId,
                         role: 'assistant',
@@ -820,29 +791,23 @@ export const startSpecSessionTurn = ({ specSessionId, instruction, attachments =
                 if (latestProject.memory_enabled && parsedResponse.suggestions && parsedResponse.suggestions.length > 0) {
                     persistSpecSessionProjectMemorySuggestions(latestProject.id, specSessionId, parsedResponse.suggestions);
                 }
-                const cleanedPlanText = stripMermaidBlocks(parsedResponse.cleanedOutput).trim()
-                    || stripMermaidBlocks(streamedAssistantMessage).trim();
+                const cleanPlannerResponse = (value) => stripSpecFileGraph(stripMermaidBlocks(value));
+                const cleanedPlanText = cleanPlannerResponse(parsedResponse.cleanedOutput)
+                    || cleanPlannerResponse(streamedAssistantMessage);
                 let assistantMessage = cleanedPlanText
-                    || getTranscriptContentFallback(specRunResult.transcriptRuns)
+                    || stripSpecFileGraph(getTranscriptContentFallback(specRunResult.transcriptRuns))
                     || (attachments.length > 0 ? ATTACHMENT_ONLY_EMPTY_RESPONSE_FALLBACK : '');
+                let artifactValidationError = artifactResult.error;
                 // Create snapshot from artifact if present. Presence is populated
                 // alongside artifact by the extractor, so the two are non-null together.
                 if (artifactResult.artifact && artifactResult.presence) {
-                    if (sessionMode === 'grill') {
-                        const acquisition = await raceAgainstSpecCancellation(obtainExactCompletedScan(latestProject, targetDescriptor), specCancellation);
-                        if (acquisition.cancelled) {
-                            throw new Error('Spec repository evidence acquisition was cancelled');
-                        }
-                        consultedScan = acquisition.value;
-                    }
                     // A block re-emitted this turn overrides the previous snapshot's value;
                     // an omitted block is carried forward so established artifacts don't
                     // disappear when a follow-up turn omits the diagram/mockup.
-                    const { mermaid: mermaidBlock, mockup: mockupBlock, fileRelationGraph: fileRelationGraphBlock } = resolveCarriedForwardArtifacts({
+                    const { mermaid: mermaidBlock, mockup: mockupBlock } = resolveCarriedForwardArtifacts({
                         rawResponse,
                         previousMermaid: previousSnapshot?.mermaid ?? null,
                         previousMockup: previousSnapshot?.mockup ?? null,
-                        previousFileRelationGraph: previousSnapshot?.file_relation_graph ?? null,
                     });
                     // Optional structured array fields use the same carry-forward contract:
                     // a field the LLM emitted this turn (including an explicit empty array)
@@ -857,75 +822,66 @@ export const startSpecSessionTurn = ({ specSessionId, instruction, attachments =
                                 openQuestions: previousSnapshot.open_questions,
                                 likelyFiles: previousSnapshot.likely_files,
                                 dependencies: previousSnapshot.dependencies,
+                                bundleGroups: previousSnapshot.bundle_groups ?? [],
                             }
                             : null,
                     });
                     const resourceUrls = collectSpecResourceUrls(listSpecMessages(specSessionId, latestProject.id)
                         .filter(message => message.role === 'user')
                         .map(message => message.content));
-                    const plannerSeedPaths = selectSpecRepositoryImpactSeeds({
-                        plannerLikelyFiles: carriedFields.likelyFiles,
-                        instruction: trimmedInstruction,
-                    });
-                    const postResponseProjection = consultedScan.state === 'ready' && plannerSeedPaths.length > 0
-                        ? projectSpecRepositoryImpact({
-                            projectId: latestProject.id,
-                            scanId: consultedScan.scan.id,
-                            seeds: plannerSeedPaths,
-                        })
-                        : {
-                            state: 'fallback',
-                            reason: 'unknown_seeds',
-                            message: 'No existing planner-authored likely files were available as repository graph seeds.',
-                        };
-                    const repositoryEvidence = await captureSpecSnapshotRepositoryEvidenceFromAcquisition({
-                        project: latestProject,
-                        target: targetDescriptor,
-                        seedPaths: plannerSeedPaths,
-                        acquisition: consultedScan,
-                    });
-                    const likelyFiles = repositoryEvidence.capture_state === 'complete'
-                        ? reconcileSpecLikelyFiles({ plannerLikelyFiles: carriedFields.likelyFiles, projection: postResponseProjection })
-                        : projectPlannerOwnedLikelyFiles(carriedFields.likelyFiles);
-                    const snapshotId = createSpecSnapshot({
-                        specSessionId,
-                        summary: artifactResult.artifact.summary,
-                        assumptions: carriedFields.assumptions,
-                        openQuestions: carriedFields.openQuestions,
-                        likelyFiles,
-                        tickets: artifactResult.artifact.tickets,
-                        dependencies: carriedFields.dependencies,
-                        resourceUrls,
-                        mermaid: mermaidBlock,
-                        mockup: mockupBlock,
-                        fileRelationGraph: fileRelationGraphBlock,
-                        planText: cleanedPlanText,
-                        repositoryEvidence,
-                    });
-                    addExecutionRunLink({
-                        projectId: executionContext.projectId,
-                        runId: executionContext.runId,
-                        link: {
-                            entityType: 'spec_snapshot',
-                            entityId: snapshotId,
-                            relationship: 'result',
-                            expectedParent: { entityType: 'spec_session', entityId: specSessionId },
-                        },
-                    });
+                    const repositoryEvidence = unavailableSpecSnapshotRepositoryEvidence(SPEC_GRAPH_DISABLED_REASON, targetDescriptor);
+                    const likelyFiles = projectPlannerOwnedLikelyFiles(carriedFields.likelyFiles);
+                    let snapshotId = null;
+                    try {
+                        snapshotId = createSpecSnapshot({
+                            specSessionId,
+                            summary: artifactResult.artifact.summary,
+                            assumptions: carriedFields.assumptions,
+                            openQuestions: carriedFields.openQuestions,
+                            likelyFiles,
+                            tickets: artifactResult.artifact.tickets,
+                            dependencies: carriedFields.dependencies,
+                            bundleGroups: carriedFields.bundleGroups,
+                            resourceUrls,
+                            mermaid: mermaidBlock,
+                            mockup: mockupBlock,
+                            fileRelationGraph: null,
+                            planText: cleanedPlanText,
+                            repositoryEvidence,
+                        });
+                    }
+                    catch (error) {
+                        if (!(error instanceof HttpError) || error.status !== 422) {
+                            throw error;
+                        }
+                        artifactValidationError = error.message;
+                    }
+                    if (snapshotId) {
+                        addExecutionRunLink({
+                            projectId: executionContext.projectId,
+                            runId: executionContext.runId,
+                            link: {
+                                entityType: 'spec_snapshot',
+                                entityId: snapshotId,
+                                relationship: 'result',
+                                expectedParent: { entityType: 'spec_session', entityId: specSessionId },
+                            },
+                        });
+                    }
                     // Auto-finalize: when an artifact is emitted during grill mode, the
                     // agent has signaled that it has no remaining questions. Flip the
                     // session mode back to 'standard' so subsequent turns run the standard
                     // prompt. This runs inside the same queued job that wrote the snapshot,
                     // so it cannot race with a concurrent user-initiated mode change.
-                    if (sessionMode === 'grill') {
+                    if (snapshotId && sessionMode === 'grill') {
                         updateSpecSessionMode(specSessionId, 'standard');
                     }
                 }
                 // Append artifact error note to the visible message if extraction failed.
                 // Suppress the "no block found" note — it is normal for Q&A turns where the
                 // agent intentionally omitted the artifact because the specification did not change.
-                if (artifactResult.error && assistantMessage && artifactResult.error !== 'No spec artifact block found in planner response') {
-                    assistantMessage += `\n\n[Note: ${artifactResult.error}. No specification snapshot was saved. You can try refining the spec or asking the planner to regenerate the artifact.]`;
+                if (artifactValidationError && assistantMessage && artifactValidationError !== 'No spec artifact block found in planner response') {
+                    assistantMessage += `\n\n[Note: ${artifactValidationError}. No specification snapshot was saved. You can try refining the spec or asking the planner to regenerate the artifact.]`;
                 }
                 if (assistantMessage) {
                     const messageId = createSpecMessage({