specrails-core 6.6.4 → 6.7.0

package/dist/agent-runtime/graph/nodes.js

@@ -3,11 +3,19 @@ import { verificationFailureSummary } from '../verification-diagnostics.js';
 import { addDeveloperChecks, bindPlan, expandedPlanCommands, initializeVerificationPlan, readVerificationPlan, validateProposedChecks } from '../verification-plan.js';
 import path from 'node:path';
 import { OpenSpecTools } from '../openspec.js';
-import { candidateManifest, describeModifiedFiles, fingerprintCandidate, frozenAcceptanceCriteria, inspectPipeline, recordAcceptance, transitionPipeline, validateAcceptanceReport, verifyPipeline, } from '../../pipeline/pipeline-state.js';
-import { ARCHITECT_OUTPUT_SCHEMA, DEVELOPER_OUTPUT_SCHEMA, REVIEW_OUTPUT_SCHEMA, correctionInstructions, deepenInstructions, roleInstructions } from '../prompts.js';
+import { candidateManifest, describeModifiedFiles, fingerprintCandidate, frozenAcceptanceCriteria, inspectPipeline, recordAcceptance, sanitizeFindingLocations, transitionPipeline, validateAcceptanceReport, verifyPipeline, } from '../../pipeline/pipeline-state.js';
+import { ARCHITECT_OUTPUT_SCHEMA, DEVELOPER_OUTPUT_SCHEMA, REVIEW_OUTPUT_SCHEMA, baselinePlanInstructions, baselineStageInstructions, correctionInstructions, deepenInstructions, roleInstructions } from '../prompts.js';
 import { archive, child, journal, object, parseArchitecture, proposedVerification, write, writeDesignConfidence } from './artifacts.js';
 import { evaluateReview } from './review-policy.js';
+import { riskFinding, settleReviewBrief } from './review-brief.js';
+import { writeReviewBriefRecord } from './review-brief-record.js';
+import { recordSpecTrace, specTraceFinding } from './spec-trace-record.js';
+import { touchedRequirements } from '../../pipeline/spec-trace.js';
+import { CAPABILITY_MAP_PATH, recordArchivedChange } from './capability-map.js';
+import { BASELINE_BLOCKER, detectBaseline, nonTestEdits, readBaselineRecord, testEdits, validateBaselinePlan, writeBaselineRecord } from './baseline.js';
+import { DEFAULT_CLARIFICATION_POLICY, blockingClarifications, clarificationQuestion, designAssumptions, parseClarifications, validateDesignSections, writeClarificationsRecord } from './clarifications.js';
 import { describeDrift } from '../compact/environment.js';
+import { projectRulesContext } from '../project-rules.js';
 import { adoptedOutputNote, environmentFailure, hostPreconditionMessage, nondeterministicOutputBlocker, preconditionBlock, repairEnvironment, selfMutationOnly } from '../verification-repair.js';
 import { unreachedTestFiles, unreachedTestsReason } from '../compact/test-reachability.js';
 import { exitCodeContradiction, exitHonestyReason } from '../compact/exit-code-honesty.js';
@@ -67,6 +75,20 @@ export function developerRecord(output, text, result, provider) {
         incomplete,
     };
 }
+/** The passed baseline of this change, for the developer and reviewer prompts. */
+function baselinePromptContext(context, change) {
+    const record = readBaselineRecord(context);
+    return record?.change === change && record.status === 'passed' ? { ...(record.receiptId ? { receiptId: record.receiptId } : {}), tests: record.tests, uncovered: record.detection.uncovered } : undefined;
+}
+/** Requirement ids the change's delta specs add, modify or rename; none when they cannot be read. */
+function touchedRequirementIds(context, change) {
+    try {
+        return touchedRequirements(context.artifactRoot, change);
+    }
+    catch {
+        return [];
+    }
+}
 /** The change so far as prompt lines; a checkout git cannot measure yields no section instead of failing the role. */
 function measuredChange(context, change) {
     try {
@@ -97,12 +119,20 @@ function withoutDiscarded(context, record, discarded) {
 }
 function architectNode(deps) {
     const { context, config, change, invoke, note } = deps;
+    const policy = config.architect?.clarifications ?? DEFAULT_CLARIFICATION_POLICY;
+    const lowConfidencePauses = (config.architect?.onLowConfidence ?? 'ask') === 'ask';
     const accept = (output) => {
-        const architecture = parseArchitecture(object(output));
+        const raw = object(output);
+        const architecture = { ...parseArchitecture(raw), clarifications: parseClarifications(raw.clarifications) };
         if (config.efficiency?.planning === 'full' || context.repositories.length > 1 || /\b(?:migration|security|authentication|authorization|public contract|public api|migraci[oó]n|seguridad)\b/i.test(context.specs.map(spec => spec.title + ' ' + spec.description).join('\n')))
             architecture.planningDepth = 'full';
         // Malformed proposals are repaired inside the same session, like any other structural defect.
         proposedVerification(context, config.verification, architecture.verification);
+        // A reply that will pause has no finished design yet; one that proceeds
+        // must carry Non-Goals (and Assumptions for its clarifications), repaired in-session.
+        const pauses = blockingClarifications(architecture.clarifications, policy).length > 0 || (architecture.confidence === 'low' && lowConfidencePauses);
+        if (!pauses)
+            validateDesignSections(context, change, { clarifications: architecture.clarifications, policy });
         return architecture;
     };
     return {
@@ -121,25 +151,40 @@ function architectNode(deps) {
                 fresh.push(reply.answer);
                 note('architect', 'Continuing the architecture with the answer to the blocking question.');
             }
-            const prompt = roleInstructions('architect', context, change, { definition: config.rolePrompts?.architect, verification: config.verification, answers, planning: config.efficiency?.planning });
+            const projectRules = projectRulesContext(context);
+            const prompt = roleInstructions('architect', context, change, { definition: config.rolePrompts?.architect, verification: config.verification, answers, planning: config.efficiency?.planning, clarifications: policy, ...(projectRules ? { projectRules } : {}) });
             const first = await invoke('architect', step, { prompt, structured: true, outputSchema: ARCHITECT_OUTPUT_SCHEMA }, accept);
             if (!first.ok)
                 return settle(first, 'Resume to run the architect again, or raise limits.timeoutMs.');
             let architecture = first.value;
+            let sessionId = first.result.sessionId;
             let passes = state.deepenPasses;
             if (architecture.confidence === 'low' && passes < MAX_DEEPEN_PASSES) {
                 passes += 1;
                 note('architect', `Design confidence is low${architecture.question ? ` (${architecture.question})` : ''}; asking the architect to investigate the code further before deciding.`);
                 const second = await invoke('architect', step, { kind: 'deepen', prompt: deepenInstructions(architecture.question), fallbackPrompt: prompt + '\nPrevious response (bounded):\n' + first.text.slice(-32_000) + '\n' + deepenInstructions(architecture.question), structured: true, outputSchema: ARCHITECT_OUTPUT_SCHEMA, resumeSessionId: first.result.sessionId }, accept);
-                if (second.ok)
+                if (second.ok) {
                     architecture = second.value;
+                    sessionId = second.result.sessionId ?? sessionId;
+                }
                 else
                     note('architect', `The investigation pass could not be used (${second.error}); keeping the first design.`);
             }
+            const blocking = blockingClarifications(architecture.clarifications, policy);
+            if (blocking.length) {
+                // High-impact questions without a safe default come before any plan:
+                // the run pauses on them and the answers return as authoritative input.
+                const lowQuestion = architecture.confidence === 'low' && lowConfidencePauses ? architecture.question : undefined;
+                writeDesignConfidence(context, change, architecture);
+                writeClarificationsRecord(context, { change, policy, status: 'awaiting-answers', clarifications: architecture.clarifications, blocking, answers });
+                transitionPipeline(context, 'architect', 'blocked', 'High-impact clarifications need answers');
+                note('architect', `The architect raised ${plural(blocking.length, 'high-impact question')} without a safe default; pausing for answers before planning.`);
+                step.interrupt({ kind: 'question', question: clarificationQuestion(blocking, lowQuestion) });
+            }
             let assumed = false;
             if (architecture.confidence === 'low') {
                 const question = architecture.question ?? 'The architect could not choose between several plausible designs; inspect proposal.md and state the intended behavior.';
-                if ((config.architect?.onLowConfidence ?? 'ask') === 'ask') {
+                if (lowConfidencePauses) {
                     // The draft artifacts are written first so the requester can read the
                     // proposal while answering; the resumed pass replaces them.
                     writeDesignConfidence(context, change, architecture);
@@ -152,11 +197,34 @@ function architectNode(deps) {
             }
             const workflow = new OpenSpecTools(deps.openspec.architect, step.signal);
             workflow.assertParticipation();
-            const applied = await workflow.assertReady();
-            const specs = Object.keys((await workflow.status()).artifactPaths).length ? (applied.contextFiles.specs ?? []) : [];
-            const names = (Array.isArray(specs) ? specs : [specs]).map(file => path.basename(path.dirname(file)));
+            let applied = await workflow.assertReady();
             const proposed = proposedVerification(context, config.verification, architecture.verification);
             writeDesignConfidence(context, change, architecture, { assumed });
+            writeClarificationsRecord(context, { change, policy, status: 'proceeded', clarifications: architecture.clarifications, blocking: [], answers, assumptions: designAssumptions(context, change) });
+            if (architecture.clarifications.length)
+                note('architect', `Proceeding on ${plural(architecture.clarifications.length, 'clarification')} recorded under Assumptions in design.md.`);
+            if (config.baselineOnTouch) {
+                // Baseline on touch: code the blast radius reaches that no capability
+                // covers gets characterization tests and an as-built spec first.
+                const detection = detectBaseline(context, change);
+                if (!detection.uncovered.length)
+                    writeBaselineRecord(context, { change, status: 'not-needed', detection, tests: [] });
+                else {
+                    note('architect', `The blast radius reaches ${plural(detection.uncovered.length, 'file')} no capability covers (${detection.uncovered.slice(0, 8).join(', ')}); asking the architect for a Baseline task group.`);
+                    const instructions = baselinePlanInstructions(detection.uncovered);
+                    const planned = await invoke('architect', step, { kind: 'baseline', prompt: instructions, fallbackPrompt: prompt + '\n' + instructions, structured: true, outputSchema: ARCHITECT_OUTPUT_SCHEMA, ...(sessionId ? { resumeSessionId: sessionId } : {}) }, output => {
+                        object(output);
+                        validateBaselinePlan(context, change);
+                        return true;
+                    });
+                    if (!planned.ok)
+                        return settle(planned, 'Resume to run the architect again, or raise limits.timeoutMs.');
+                    applied = await workflow.assertReady();
+                    writeBaselineRecord(context, { change, status: 'planned', detection, tests: [] });
+                }
+            }
+            const specs = Object.keys((await workflow.status()).artifactPaths).length ? (applied.contextFiles.specs ?? []) : [];
+            const names = (Array.isArray(specs) ? specs : [specs]).map(file => path.basename(path.dirname(file)));
             const effective = initializeVerificationPlan(context, config.verification, proposed, config.efficiency?.verification?.maxConcurrency);
             bindPlan(context, effective);
             const plan = expandedPlanCommands(context, effective);
@@ -170,11 +238,12 @@ function architectNode(deps) {
                 planningDepth: architecture.planningDepth, referencePatterns: architecture.referencePatterns, riskFlags: architecture.riskFlags,
                 ...(architecture.planningReason ? { planningReason: architecture.planningReason } : {}),
                 ...(architecture.question ? { question: architecture.question } : {}), ...(assumed ? { assumed: true } : {}),
+                ...(architecture.clarifications.length ? { clarifications: architecture.clarifications } : {}),
             };
             return {
                 status: 'succeeded', next: 'developer',
                 update: { plan, unverifiedRepositories: uncovered, architecture: record, answers: fresh, deepenPasses: passes },
-                output: { change, verification: plan, unverifiedRepositories: uncovered, confidence: architecture.confidence, assumed, deepenPasses: passes },
+                output: { change, verification: plan, unverifiedRepositories: uncovered, confidence: architecture.confidence, assumed, deepenPasses: passes, clarifications: architecture.clarifications },
             };
         },
     };
@@ -200,7 +269,9 @@ async function implementationVisit(deps, state, step, mode) {
     const provider = (fixer ?? config.agents.developer).provider;
     // What the run has changed so far, from git: a correction stays inside it.
     const changes = state.development ? measuredChange(context, change) : undefined;
-    const full = roleInstructions('developer', context, change, { definition: fixing ? config.rolePrompts?.fixer : config.rolePrompts?.developer, ...(fixing ? { stance: 'fixer' } : {}), feedback, verification: state.plan, developer: state.development, ...(changes ? { changeSet: changes } : {}) }) + (config.efficiency?.acceptDeveloperChecks !== false ? '\nYou may propose verificationChecks in your JSON summary. These are additive required checks, never replacements for the baseline. Use kind command with structured command/args, or kind harness with entrypoint and 1–8 relative source files (64 KiB each, 256 KiB total). Core persists harnesses outside delivery, appends the absolute entrypoint to argv and supplies SPECRAILS_CHECK_REPO_ROOT. Stable keys revise your own checks; omission retains them. Do not claim a check passed until Core has executed it.' : '');
+    const requirementTags = touchedRequirementIds(context, change);
+    const developerPrompt = () => roleInstructions('developer', context, change, { ...(baselinePromptContext(context, change) ? { baseline: baselinePromptContext(context, change) } : {}), definition: fixing ? config.rolePrompts?.fixer : config.rolePrompts?.developer, ...(fixing ? { stance: 'fixer' } : {}), feedback, verification: state.plan, developer: state.development, ...(changes ? { changeSet: changes } : {}), ...(requirementTags.length ? { requirementTags } : {}) }) + (config.efficiency?.acceptDeveloperChecks !== false ? '\nYou may propose verificationChecks in your JSON summary. These are additive required checks, never replacements for the baseline. Use kind command with structured command/args, or kind harness with entrypoint and 1–8 relative source files (64 KiB each, 256 KiB total). Core persists harnesses outside delivery, appends the absolute entrypoint to argv and supplies SPECRAILS_CHECK_REPO_ROOT. Stable keys revise your own checks; omission retains them. Do not claim a check passed until Core has executed it.' : '');
+    let full = developerPrompt();
     const previous = state.development;
     // A CLI developer with a live session takes corrections and continuations
     // as a short follow-up in that session; a configured fixer engine always
@@ -209,6 +280,14 @@ async function implementationVisit(deps, state, step, mode) {
     const resumable = !fixer && previous?.sessionId !== undefined && previous.provider === provider && visits > 1;
     if (fixer)
         note('fixer', `Correction round on the fixer engine (${fixer.provider}/${fixer.model ?? 'provider default'}).`);
+    // Baseline on touch: characterization comes first and must pass on the unchanged code.
+    const baseline = !fixing && config.baselineOnTouch ? readBaselineRecord(context) : null;
+    if (baseline && baseline.change === change && baseline.status !== 'passed' && baseline.status !== 'not-needed') {
+        const stopped = await baselineStage(deps, step, baseline, full, provider);
+        if (stopped)
+            return stopped;
+        full = developerPrompt();
+    }
     // Out-of-scope state before the turn: afterwards the host undoes exactly what the turn did outside the scope.
     const guard = captureOutOfScope(context, change);
     const outcome = await invoke('developer', step, {
@@ -262,6 +341,54 @@ async function implementationVisit(deps, state, step, mode) {
         output: { summary: record.summary, provider, ...(record.sessionId ? { sessionId: record.sessionId } : {}), files: record.files, tests: record.tests, incomplete: record.incomplete, structured: record.structured },
     };
 }
+/**
+ * The baseline stage of a developer visit: the developer writes only the
+ * characterization tests and the as-built spec, Core checks that no non-test
+ * file changed and runs the verification plan on the unchanged code. A failure
+ * stops the run with an explicit host blocker; a pass is recorded with its
+ * receipt and the visit continues with the change tasks.
+ */
+async function baselineStage(deps, step, record, full, provider) {
+    const { context, change, invoke, note } = deps;
+    const uncovered = record.detection.uncovered;
+    const stop = (status, reason, extra = {}) => {
+        writeBaselineRecord(context, { ...record, ...extra, status, reason });
+        note('developer', reason);
+        return { status: 'blocked', error: `${reason} (${BASELINE_BLOCKER})`, usage: NO_SPEND };
+    };
+    note('developer', `Baseline stage: characterization tests for ${uncovered.slice(0, 8).join(', ')} before the change touches them.`);
+    const guard = captureOutOfScope(context, change);
+    const outcome = await invoke('developer', step, { kind: 'baseline', prompt: full + '\n' + baselineStageInstructions(uncovered), structured: true, lenient: true, outputSchema: DEVELOPER_OUTPUT_SCHEMA }, (output, text, result) => developerRecord(output, text, result, provider));
+    try {
+        discardOutOfScopeEdits(context, guard);
+    }
+    catch (error) {
+        return { status: 'blocked', error: `Developer edited files outside the repository scope during the baseline stage and Core could not undo them: ${error instanceof Error ? error.message : String(error)}. Restore those files, then resume.` };
+    }
+    if (!outcome.ok)
+        return settle(outcome, 'Resume to run the baseline stage again, or raise limits.timeoutMs.');
+    const changed = changeSet(context, change).flatMap(set => set.files.map(file => ({ repositoryId: set.repositoryId, path: file.path })));
+    const edited = nonTestEdits(changed.map(file => file.path));
+    if (edited.length)
+        return stop('violated', `The baseline stage changed non-test files (${edited.slice(0, 10).join(', ')}); the module must stay untouched until its characterization tests pass on the base code. Restore those files, then resume`);
+    const tests = testEdits([...new Set([...outcome.value.tests, ...changed.map(file => file.path)])]);
+    const effective = readVerificationPlan(context);
+    const plan = effective ? expandedPlanCommands(context, effective) : [];
+    if (!effective || !plan.length)
+        return stop('failed', 'No verification command can run the characterization tests on the base code; configure one for the repository, then resume', { tests });
+    const unreached = context.repositories.flatMap(repository => unreachedTestFiles(repository.path, plan.filter(command => command.repositoryId === repository.id).map(({ command, args, cwd }) => ({ command, args, ...(cwd ? { cwd } : {}) })), tests));
+    if (unreached.length)
+        return stop('failed', `No verification command runs the characterization tests ${unreached.join(', ')}; wire them into the repository's test command, then resume`, { tests });
+    const uncoveredRepositories = context.repositories.filter(repository => !plan.some(command => command.repositoryId === repository.id)).map(repository => repository.id);
+    const receipt = await verifyPipeline(context, { kind: 'full', planHash: effective.planHash, commands: plan, ...(uncoveredRepositories.length ? { unverified: true } : {}) }, deps.onVerificationOutput, step.signal);
+    if (!receipt.valid) {
+        const failing = receipt.commands.filter(command => command.exitCode !== 0).map(command => [command.command, ...command.args].join(' '));
+        return stop('failed', `Characterization tests fail on the base code (receipt ${receipt.id}${failing.length ? ': ' + failing.join('; ') : ''}): they do not describe the current behaviour of ${uncovered.slice(0, 8).join(', ')}. Make the characterization tests describe what the code does today (never change the module to match them), then resume`, { tests, receiptId: receipt.id });
+    }
+    writeBaselineRecord(context, { ...record, status: 'passed', tests, receiptId: receipt.id, reason: undefined });
+    note('developer', `Baseline passed on the base code (receipt ${receipt.id}, ${plural(tests.length, 'characterization test file')}); continuing with the change.`);
+    return undefined;
+}
 function developerNode(deps) {
     return {
         effect: 'write', ends: ['verify'],
@@ -436,7 +563,12 @@ function verifyNode(deps) {
             }
             transitionPipeline(context, 'developer', 'done');
             note('developer', plan.length ? `Verification passed: ${plural(plan.length, 'command')} exited 0.` : 'No verification commands available; relying on task completion and review.');
-            return { status: 'succeeded', next: 'reviewer', update: { verifyResult: evidence, verifyHistory: [outcome(true)] }, output: evidence, usage: NO_SPEND };
+            // Advisory requirement ↔ test trace, bound to this receipt; it never changes the outcome.
+            const trace = recordSpecTrace(context, deps.change, receipt, state.development?.tests ?? []);
+            if (trace)
+                note('developer', `${trace.summary}${trace.touchedUndemonstrated.length ? `; not demonstrated for this change: ${trace.touchedUndemonstrated.map(item => item.id).join(', ')}` : ''} (advisory).`);
+            const verified = trace ? { ...evidence, specTrace: trace } : evidence;
+            return { status: 'succeeded', next: 'reviewer', update: { verifyResult: verified, verifyHistory: [outcome(true)] }, output: verified, usage: NO_SPEND };
         },
     };
 }
@@ -475,7 +607,11 @@ export function buildAcceptanceReport(criteria, verification, raw) {
     // Reviewer inspections are evidence, never gates: only Core's own subprocess receipts are required checks.
     for (const item of Array.isArray(input.checks) ? input.checks : [])
         checks.push({ ...object(item), required: false });
-    return { criteria: certified, checks, findings: (Array.isArray(input.findings) ? input.findings : []) };
+    const findings = (Array.isArray(input.findings) ? input.findings : []);
+    // The advisory spec trace is evidence for the merger, never a check: it cannot change the acceptance status.
+    // Anchors index the reviewer's own findings; appended host findings come after them, so the indexes stay valid.
+    const findingLocations = sanitizeFindingLocations(input.findingLocations, findings.length);
+    return { criteria: certified, checks, findings: verification?.specTrace ? [...findings, specTraceFinding(verification.specTrace)] : findings, ...(findingLocations.length ? { findingLocations } : {}) };
 }
 function reviewerNode(deps) {
     const { context, change, invoke, note, policy, config } = deps;
@@ -497,13 +633,19 @@ function reviewerNode(deps) {
                 note('reviewer', `Re-review: ${plural(reReview.changes.length, 'file')} changed since the previous verdict; certifying the previous issues instead of re-reading the candidate.`);
             // The reviewer judges the change itself, measured from git — not the whole checkout.
             const changes = measuredChange(context, change);
-            const prompt = roleInstructions('reviewer', context, change, { definition: config.rolePrompts?.reviewer, feedback: feedbackFor(state), verification: state.plan, policy, criteria, developer: state.development, ...(changes ? { changeSet: changes } : {}), ...(reReview ? { reReview } : {}) });
+            const baselineContext = baselinePromptContext(context, change);
+            const projectRules = projectRulesContext(context);
+            const prompt = roleInstructions('reviewer', context, change, { ...(baselineContext ? { baseline: baselineContext } : {}), ...(projectRules ? { projectRules } : {}), definition: config.rolePrompts?.reviewer, feedback: feedbackFor(state), verification: state.plan, policy, criteria, developer: state.development, ...(changes ? { changeSet: changes } : {}), ...(reReview ? { reReview } : {}) });
             const incremental = config.efficiency?.reviewMode !== 'full' && delta.mode === 'incremental' && state.review?.sessionId;
             const followup = correctionInstructions('reviewer', feedbackFor(state), { focusedEvidence: deps.focusedCorrectionEvidence && config.efficiency?.contextMode !== 'full' }) + '\nChanges since YOUR previous reviewed candidate:\n' + JSON.stringify(delta.changes)
                 + (changes ? '\nThe complete change under review (from git, against the run\'s base) — review these files only:\n' + changes.join('\n') : '')
                 + '\nRecertify EVERY current acceptance criterion; previous met results are not current evidence:\n' + JSON.stringify(criteria)
                 + '\nCurrent developer handoff:\n' + JSON.stringify(state.development);
+            // The first reply may spend the single repair turn on a malformed brief;
+            // a repaired reply keeps its verdict and only loses the brief.
+            let replies = 0;
             const outcome = await invoke('reviewer', step, { kind: state.review ? 'correction' : 'initial', prompt: incremental ? followup : prompt, ...(incremental ? { resumeSessionId: state.review.sessionId, fallbackPrompt: prompt } : {}), structured: true, outputSchema: REVIEW_OUTPUT_SCHEMA }, output => {
+                const repairable = replies++ === 0;
                 const raw = object(output);
                 const review = evaluateReview(raw, policy);
                 const report = buildAcceptanceReport(criteria, state.verifyResult, raw.acceptance);
@@ -513,23 +655,30 @@ function reviewerNode(deps) {
                 catch (error) {
                     throw new Error('Invalid acceptance report: ' + (error instanceof Error ? error.message : String(error)));
                 }
-                return { ...review, report };
+                const brief = settleReviewBrief(raw.brief, { repairable });
+                // Risks beyond the brief's cap stay visible as supplementary findings.
+                if (brief.overflow.length)
+                    report.findings = [...report.findings, ...brief.overflow.map(riskFinding)];
+                return { ...review, report, brief };
             });
             if (!outcome.ok)
                 return failed(outcome.error);
             const workflow = new OpenSpecTools(deps.openspec.reviewer, step.signal);
             workflow.assertParticipation();
             await workflow.assertReady();
-            const { record, approved, report } = outcome.value;
-            const reviewedRecord = { ...record, manifest, ...(outcome.result.sessionId ? { sessionId: outcome.result.sessionId } : {}) };
+            const { record, approved, report, brief } = outcome.value;
+            if (brief.diagnostic)
+                note('reviewer', brief.diagnostic);
+            const reviewedRecord = { ...record, ...(brief.brief ? { brief: brief.brief } : {}), ...(brief.diagnostic ? { briefDiagnostic: brief.diagnostic } : {}), manifest, ...(outcome.result.sessionId ? { sessionId: outcome.result.sessionId } : {}) };
             // Acceptance evidence is bound to the exact candidate before the reviewer verdict is recorded.
             recordAcceptance(context, report);
+            writeReviewBriefRecord(context, { change, approved, score: record.score, ...(brief.brief ? { brief: brief.brief } : {}), ...(brief.diagnostic ? { diagnostic: brief.diagnostic } : {}) });
             if (!approved) {
                 transitionPipeline(context, 'reviewer', 'blocked', 'Review requests corrections');
                 note('reviewer', `Review requested corrections (score ${record.score}, ${plural(record.issues.length, 'issue')}); handing them to the fixer.`);
                 return { status: 'succeeded', next: 'fixer', update: { review: reviewedRecord }, output: reviewedRecord };
             }
-            write(child(context.artifactRoot, 'openspec/changes/' + change + '/confidence-score.json'), JSON.stringify({ change, overall: record.score, aspects: record.aspects, summary: record.summary }, null, 2) + '\n');
+            write(child(context.artifactRoot, 'openspec/changes/' + change + '/confidence-score.json'), JSON.stringify({ change, overall: record.score, aspects: record.aspects, summary: record.summary, ...(brief.brief ? { brief: brief.brief } : {}) }, null, 2) + '\n');
             transitionPipeline(context, 'reviewer', 'done');
             note('reviewer', `Review approved with score ${record.score}: ${record.summary}`);
             const reviewed = { ...reviewedRecord, candidateHash: fingerprintCandidate(journal(context)) };
@@ -548,7 +697,17 @@ function archiveNode(deps) {
                 step.reportUsage(NO_SPEND);
                 step.interrupt({ kind: 'approval', reason: 'Approve archive after inspecting the verified implementation' });
             }
-            await archive(context, change, step.signal);
+            await archive(context, change, step.signal, { beforeDone: archived => {
+                    // Only journals that exclude the map from the candidate may rewrite it (older runs keep their reviewed hash).
+                    if (!journal(context).artifactExclusions.includes(CAPABILITY_MAP_PATH))
+                        return;
+                    try {
+                        recordArchivedChange(context, change, archived);
+                    }
+                    catch (error) {
+                        deps.note('architect', `The capability map could not be updated (${error instanceof Error ? error.message : String(error)}); baseline detection will not see this change.`);
+                    }
+                } });
             const record = { archivePath: journal(context).archivePath, deliveryOwner: context.ownership.git };
             return { status: 'succeeded', next: null, update: { archived: record }, output: record, usage: NO_SPEND };
         },

package/dist/agent-runtime/graph/review-brief-record.d.ts

@@ -0,0 +1,25 @@
+import { type PipelineContext } from '../../pipeline/pipeline-state.js';
+import { REVIEW_BRIEF_SCHEMA_VERSION, type ReviewBrief } from './review-brief.js';
+/** Host-readable record of the latest reviewer verdict's brief, rewritten at every verdict. */
+export interface ReviewBriefRecord {
+    schemaVersion: typeof REVIEW_BRIEF_SCHEMA_VERSION;
+    change: string;
+    approved: boolean;
+    score: number;
+    recordedAt: string;
+    /** Null when the reviewer sent no brief or it was dropped. */
+    brief: ReviewBrief | null;
+    /** Present when a malformed brief was dropped after the repair turn. */
+    diagnostic?: string;
+}
+export declare const REVIEW_BRIEF_FILE = "review-brief.json";
+export declare function reviewBriefPath(context: Pick<PipelineContext, 'backlogRoot' | 'runId'>): string;
+export declare function writeReviewBriefRecord(context: PipelineContext, verdict: {
+    change: string;
+    approved: boolean;
+    score: number;
+    brief?: ReviewBrief;
+    diagnostic?: string;
+}): void;
+/** The latest recorded brief for a run, or null when no reviewer verdict was recorded (or the file is unreadable). */
+export declare function readReviewBriefRecord(context: Pick<PipelineContext, 'backlogRoot' | 'runId'>): ReviewBriefRecord | null;

package/dist/agent-runtime/graph/review-brief-record.js

@@ -0,0 +1,26 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pipelineStateDirectory } from '../../pipeline/pipeline-state.js';
+import { write } from './artifacts.js';
+import { REVIEW_BRIEF_SCHEMA_VERSION } from './review-brief.js';
+export const REVIEW_BRIEF_FILE = 'review-brief.json';
+export function reviewBriefPath(context) {
+    return path.join(pipelineStateDirectory(context), REVIEW_BRIEF_FILE);
+}
+export function writeReviewBriefRecord(context, verdict) {
+    const record = { schemaVersion: REVIEW_BRIEF_SCHEMA_VERSION, change: verdict.change, approved: verdict.approved, score: verdict.score, recordedAt: new Date().toISOString(), brief: verdict.brief ?? null, ...(verdict.diagnostic ? { diagnostic: verdict.diagnostic } : {}) };
+    write(reviewBriefPath(context), JSON.stringify(record, null, 2) + '\n');
+}
+/** The latest recorded brief for a run, or null when no reviewer verdict was recorded (or the file is unreadable). */
+export function readReviewBriefRecord(context) {
+    try {
+        const file = reviewBriefPath(context);
+        if (!existsSync(file))
+            return null;
+        const value = JSON.parse(readFileSync(file, 'utf8'));
+        return value && typeof value === 'object' && value.schemaVersion === REVIEW_BRIEF_SCHEMA_VERSION ? value : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/agent-runtime/graph/review-brief.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The reviewer's risk brief: an optional, advisory companion to the verdict that
+ * tells a human what changed, what the change leans on, what no test exercises
+ * and where to look first. It never feeds the approval gate (review-policy.ts).
+ */
+export declare const REVIEW_BRIEF_SCHEMA_VERSION = 1;
+/** At most this many risks reach the brief; the rest become acceptance findings. */
+export declare const REVIEW_BRIEF_RISK_LIMIT = 5;
+export declare const REVIEW_RISK_SEVERITIES: readonly ['high', 'medium', 'low'];
+export declare const REVIEW_RISK_AREAS: readonly ['data', 'security', 'api', 'ux', 'performance', 'ops', 'other'];
+export declare const REVIEW_INVARIANT_STATUSES: readonly ['kept', 'changed', 'at-risk'];
+export interface ReviewBehaviourChange {
+    what: string;
+    where: string;
+    userVisible: boolean;
+}
+export interface ReviewInvariant {
+    invariant: string;
+    evidence: string;
+    status: typeof REVIEW_INVARIANT_STATUSES[number];
+}
+export interface ReviewUntested {
+    path: string;
+    why: string;
+}
+export interface ReviewRisk {
+    severity: typeof REVIEW_RISK_SEVERITIES[number];
+    area: typeof REVIEW_RISK_AREAS[number];
+    whatToLookAt: string;
+    ref: string;
+}
+/** A spec claim of a touched capability that the code contradicts (reviewer check 9); may be empty. */
+export interface ReviewDivergence {
+    capability: string;
+    requirement: string;
+    observed: string;
+}
+export interface ReviewBrief {
+    behaviourChanges?: ReviewBehaviourChange[];
+    invariantsTouched?: ReviewInvariant[];
+    untested?: ReviewUntested[];
+    risks?: ReviewRisk[];
+    humanChecks?: string[];
+    divergences?: ReviewDivergence[];
+}
+/** The optional `brief` property of REVIEW_OUTPUT_SCHEMA. Every list is optional and may be empty. */
+export declare const REVIEW_BRIEF_SCHEMA: Record<string, unknown>;
+/**
+ * Validates and normalizes a reviewer brief. Absent (`undefined`/`null`) means
+ * no brief; an empty object is a valid, empty brief. Risks are ordered by
+ * severity (stable within a severity) and capped at REVIEW_BRIEF_RISK_LIMIT;
+ * the rest are returned as `overflow`. Throws `Invalid review brief: …` when
+ * malformed, which the role invoker treats as repairable.
+ */
+export declare function parseReviewBrief(value: unknown): {
+    brief?: ReviewBrief;
+    overflow: ReviewRisk[];
+};
+/** One acceptance finding line for a risk that did not fit in the brief. */
+export declare function riskFinding(risk: ReviewRisk): string;
+export interface SettledReviewBrief {
+    brief?: ReviewBrief;
+    overflow: ReviewRisk[];
+    diagnostic?: string;
+}
+/**
+ * Applies the repair policy: on the first reply a malformed brief throws so the
+ * role invoker spends its single repair turn; on the repaired reply it is
+ * dropped with a diagnostic instead of failing the review.
+ */
+export declare function settleReviewBrief(value: unknown, options: {
+    repairable: boolean;
+}): SettledReviewBrief;

package/dist/agent-runtime/graph/review-brief.js

@@ -0,0 +1,127 @@
+/**
+ * The reviewer's risk brief: an optional, advisory companion to the verdict that
+ * tells a human what changed, what the change leans on, what no test exercises
+ * and where to look first. It never feeds the approval gate (review-policy.ts).
+ */
+export const REVIEW_BRIEF_SCHEMA_VERSION = 1;
+/** At most this many risks reach the brief; the rest become acceptance findings. */
+export const REVIEW_BRIEF_RISK_LIMIT = 5;
+const LIST_LIMIT = 20;
+const TEXT_LIMIT = 2000;
+export const REVIEW_RISK_SEVERITIES = ['high', 'medium', 'low'];
+export const REVIEW_RISK_AREAS = ['data', 'security', 'api', 'ux', 'performance', 'ops', 'other'];
+export const REVIEW_INVARIANT_STATUSES = ['kept', 'changed', 'at-risk'];
+const text = { type: 'string', minLength: 1 };
+const items = (properties) => ({ type: 'array', items: { type: 'object', additionalProperties: false, required: Object.keys(properties), properties } });
+/** The optional `brief` property of REVIEW_OUTPUT_SCHEMA. Every list is optional and may be empty. */
+export const REVIEW_BRIEF_SCHEMA = {
+    type: 'object', additionalProperties: false,
+    description: 'Optional risk brief for the human who merges the change. Advisory only: it never changes the verdict.',
+    properties: {
+        behaviourChanges: items({ what: text, where: { ...text, description: 'file:line' }, userVisible: { type: 'boolean' } }),
+        invariantsTouched: items({ invariant: text, evidence: { ...text, description: 'file:line or file:start-end' }, status: { type: 'string', enum: [...REVIEW_INVARIANT_STATUSES] } }),
+        untested: items({ path: text, why: text }),
+        risks: items({ severity: { type: 'string', enum: [...REVIEW_RISK_SEVERITIES] }, area: { type: 'string', enum: [...REVIEW_RISK_AREAS] }, whatToLookAt: text, ref: { ...text, description: 'file:line' } }),
+        humanChecks: { type: 'array', items: text },
+        divergences: items({ capability: text, requirement: text, observed: text }),
+    },
+};
+class BriefError extends Error {
+    constructor(detail) { super('Invalid review brief: ' + detail); }
+}
+function field(value, where) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new BriefError(`${where} must be a non-empty string`);
+    return value.trim().slice(0, TEXT_LIMIT);
+}
+function member(value, allowed, where) {
+    if (typeof value !== 'string' || !allowed.includes(value))
+        throw new BriefError(`${where} must be one of ${allowed.join(', ')}`);
+    return value;
+}
+function list(value, name, parse) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!Array.isArray(value))
+        throw new BriefError(`${name} must be an array`);
+    return value.map((item, index) => {
+        const where = `${name}[${index}]`;
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            throw new BriefError(`${where} must be an object`);
+        return parse(item, where);
+    });
+}
+const SEVERITY_RANK = { high: 0, medium: 1, low: 2 };
+/**
+ * Validates and normalizes a reviewer brief. Absent (`undefined`/`null`) means
+ * no brief; an empty object is a valid, empty brief. Risks are ordered by
+ * severity (stable within a severity) and capped at REVIEW_BRIEF_RISK_LIMIT;
+ * the rest are returned as `overflow`. Throws `Invalid review brief: …` when
+ * malformed, which the role invoker treats as repairable.
+ */
+export function parseReviewBrief(value) {
+    if (value === undefined || value === null)
+        return { overflow: [] };
+    if (typeof value !== 'object' || Array.isArray(value))
+        throw new BriefError('brief must be an object');
+    const raw = value;
+    const brief = {};
+    const behaviourChanges = list(raw.behaviourChanges, 'behaviourChanges', (item, where) => {
+        if (typeof item.userVisible !== 'boolean')
+            throw new BriefError(`${where}.userVisible must be a boolean`);
+        return { what: field(item.what, where + '.what'), where: field(item.where, where + '.where'), userVisible: item.userVisible };
+    });
+    const invariantsTouched = list(raw.invariantsTouched, 'invariantsTouched', (item, where) => ({
+        invariant: field(item.invariant, where + '.invariant'), evidence: field(item.evidence, where + '.evidence'), status: member(item.status, REVIEW_INVARIANT_STATUSES, where + '.status'),
+    }));
+    const untested = list(raw.untested, 'untested', (item, where) => ({ path: field(item.path, where + '.path'), why: field(item.why, where + '.why') }));
+    const risks = list(raw.risks, 'risks', (item, where) => ({
+        severity: member(item.severity, REVIEW_RISK_SEVERITIES, where + '.severity'), area: member(item.area, REVIEW_RISK_AREAS, where + '.area'),
+        whatToLookAt: field(item.whatToLookAt, where + '.whatToLookAt'), ref: field(item.ref, where + '.ref'),
+    }));
+    let humanChecks;
+    if (raw.humanChecks !== undefined && raw.humanChecks !== null) {
+        if (!Array.isArray(raw.humanChecks))
+            throw new BriefError('humanChecks must be an array');
+        humanChecks = raw.humanChecks.map((item, index) => field(item, `humanChecks[${index}]`));
+    }
+    const divergences = list(raw.divergences, 'divergences', (item, where) => ({
+        capability: field(item.capability, where + '.capability'), requirement: field(item.requirement, where + '.requirement'), observed: field(item.observed, where + '.observed'),
+    }));
+    let overflow = [];
+    if (behaviourChanges)
+        brief.behaviourChanges = behaviourChanges.slice(0, LIST_LIMIT);
+    if (invariantsTouched)
+        brief.invariantsTouched = invariantsTouched.slice(0, LIST_LIMIT);
+    if (untested)
+        brief.untested = untested.slice(0, LIST_LIMIT);
+    if (risks) {
+        const ordered = risks.map((risk, index) => ({ risk, index })).sort((a, b) => SEVERITY_RANK[a.risk.severity] - SEVERITY_RANK[b.risk.severity] || a.index - b.index).map(entry => entry.risk);
+        brief.risks = ordered.slice(0, REVIEW_BRIEF_RISK_LIMIT);
+        overflow = ordered.slice(REVIEW_BRIEF_RISK_LIMIT);
+    }
+    if (humanChecks)
+        brief.humanChecks = humanChecks.slice(0, LIST_LIMIT);
+    if (divergences)
+        brief.divergences = divergences.slice(0, LIST_LIMIT);
+    return { brief, overflow };
+}
+/** One acceptance finding line for a risk that did not fit in the brief. */
+export function riskFinding(risk) {
+    return `Additional ${risk.severity} ${risk.area} risk (beyond the brief's top ${REVIEW_BRIEF_RISK_LIMIT}): ${risk.whatToLookAt} (${risk.ref})`;
+}
+/**
+ * Applies the repair policy: on the first reply a malformed brief throws so the
+ * role invoker spends its single repair turn; on the repaired reply it is
+ * dropped with a diagnostic instead of failing the review.
+ */
+export function settleReviewBrief(value, options) {
+    try {
+        return parseReviewBrief(value);
+    }
+    catch (error) {
+        if (options.repairable)
+            throw error;
+        return { overflow: [], diagnostic: `Review brief dropped after the repair turn: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}

package/dist/agent-runtime/graph/roles.js

@@ -10,6 +10,7 @@ import { performance } from 'node:perf_hooks';
 import { frozenAcceptanceCriteria, pipelineStateDirectory } from '../../pipeline/pipeline-state.js';
 import { AgentExecutionError, unknownUsage } from '../executor-types.js';
 import { ROLE_INSTRUCTIONS_VERSION, repairInstructions } from '../prompts.js';
+import { asksBeforePlanning } from './clarifications.js';
 import { parseAgentObject } from './artifacts.js';
 /** Executor failures that mean "this session cannot be continued", not "the role failed". */
 const SESSION_FALLBACK_CODES = new Set(['session_not_found', 'session_expired', 'session_unsupported']);
@@ -138,9 +139,10 @@ export function createRoleInvoker(deps) {
                     parseError = error;
                 }
             }
-            // A genuine architect question can precede artifact creation. Completed
-            // role results must prove this invocation used the workflow, not an old visit.
-            if (!(role === 'architect' && output?.confidence === 'low'))
+            // A genuine architect question (low confidence, or a high-impact
+            // clarification without a safe default) can precede artifact creation.
+            // Completed role results must prove this invocation used the workflow, not an old visit.
+            if (!(role === 'architect' && (output?.confidence === 'low' || asksBeforePlanning(output?.clarifications))))
                 workflow?.assertParticipation(cursor);
             if (structured && !output && !options.lenient)
                 throw new Error('Invalid structured role response: ' + (parseError instanceof Error ? parseError.message : 'missing object'));