specrails-core 6.0.0 → 6.1.0

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

@@ -1,15 +1,18 @@
 import { guardrailEnabled } from '../guardrails.js';
 import { addDeveloperChecks, bindPlan, expandedPlanCommands, initializeVerificationPlan, readVerificationPlan, validateProposedChecks } from '../verification-plan.js';
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { OpenSpecTools } from '../openspec.js';
-import { candidateManifest, fingerprintCandidate, frozenAcceptanceCriteria, recordAcceptance, transitionPipeline, validateAcceptanceReport, verifyPipeline, } from '../../pipeline/pipeline-state.js';
+import { candidateManifest, 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 { archive, child, journal, object, parseArchitecture, proposedVerification, write, writeDesignConfidence } from './artifacts.js';
 import { evaluateReview } from './review-policy.js';
-import { installEnvironment, isEnvironmentFailure } from '../compact/environment.js';
+import { hostPreconditionFailure, installEnvironment, isEnvironmentFailure } from '../compact/environment.js';
 import { unreachedTestFiles, unreachedTestsReason } from '../compact/test-reachability.js';
 import { exitCodeContradiction, exitHonestyReason } from '../compact/exit-code-honesty.js';
 import { boundedReviewManifest, reviewChanges } from '../review-context.js';
+import { describeFailure, divergence, outcomesSinceResume, unchangedFailure } from './convergence.js';
+import { captureOutOfScope, changeBases, changeSet, describeDiscarded, discardOutOfScopeEdits, renderChangeSet } from '../change-scope.js';
 /** Autonomous investigation passes before a low-confidence design asks or proceeds. */
 export const MAX_DEEPEN_PASSES = 1;
 const DEVELOPER_SUMMARY_LIMIT = 32_000;
@@ -63,6 +66,34 @@ export function developerRecord(output, text, result, provider) {
         incomplete,
     };
 }
+/** 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 {
+        return renderChangeSet(changeSet(context, change));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The turn's record without the files Core undid: they are not part of the change, so they never count as progress. */
+function withoutDiscarded(context, record, discarded) {
+    if (!discarded.length)
+        return record;
+    const undone = new Set(discarded.map(edit => edit.path));
+    const relative = (file) => {
+        let value = file.replace(/\\/g, '/').replace(/^\.\//, '');
+        for (const repository of context.repositories) {
+            const root = repository.path.replace(/\\/g, '/');
+            if (value.startsWith(root + '/')) {
+                value = value.slice(root.length + 1);
+                break;
+            }
+        }
+        return value;
+    };
+    const kept = (files) => files.filter(file => !undone.has(relative(file)));
+    return { ...record, files: kept(record.files), tests: kept(record.tests), discarded: discarded.map(edit => (context.repositories.length > 1 ? edit.repositoryId + ':' : '') + edit.path).slice(0, 200) };
+}
 function architectNode(deps) {
     const { context, config, change, invoke, note } = deps;
     const accept = (output) => {
@@ -77,6 +108,8 @@ function architectNode(deps) {
         effect: 'write', ends: ['developer'],
         async run(state, step) {
             transitionPipeline(context, 'architect', 'running');
+            // The change is measured from here: record each repository's base before any role edits.
+            changeBases(context);
             // A resumed node collects the requester's answer first, so the pass that
             // asked the question is never repeated.
             const answers = [...state.answers];
@@ -164,7 +197,9 @@ async function implementationVisit(deps, state, step, mode) {
     // instructions.
     const fixer = fixing ? config.fixer : undefined;
     const provider = (fixer ?? config.agents.developer).provider;
-    const full = roleInstructions('developer', context, change, { definition: fixing ? config.rolePrompts?.fixer : config.rolePrompts?.developer, ...(fixing ? { stance: 'fixer' } : {}), feedback, verification: state.plan }) + (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.' : '');
+    // 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 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
@@ -173,11 +208,13 @@ 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'}).`);
+    // 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, {
         kind: visits > 1 ? 'correction' : 'initial',
         ...(fixer ? { agentOverride: fixer } : {}), ...(fixing ? { stance: 'fixer' } : {}),
         ...(resumable
-            ? { prompt: correctionInstructions('developer', feedback), resumeSessionId: previous.sessionId, fallbackPrompt: full }
+            ? { prompt: correctionInstructions('developer', feedback, { ...(changes ? { changeSet: changes } : {}), developer: state.development, focusedEvidence: deps.focusedCorrectionEvidence && config.efficiency?.contextMode !== 'full' }), resumeSessionId: previous.sessionId, fallbackPrompt: full }
             : { prompt: full }),
         structured: true, lenient: true, outputSchema: DEVELOPER_OUTPUT_SCHEMA,
     }, (output, text, result) => {
@@ -188,6 +225,19 @@ async function implementationVisit(deps, state, step, mode) {
             throw new Error('Developer verification proposals are disabled by the frozen policy');
         return { ...developerRecord(output, text, result, provider), ...(checks.length ? { verificationChecks: checks } : {}) };
     });
+    const who = fixing ? 'Fixer' : 'Developer';
+    let discarded;
+    try {
+        discarded = discardOutOfScopeEdits(context, guard);
+    }
+    catch (error) {
+        return { status: 'blocked', error: `${who} edited files outside the repository scope and Core could not undo them: ${error instanceof Error ? error.message : String(error)}. Restore those files in the worktree, then resume.` };
+    }
+    const multiple = context.repositories.length > 1;
+    if (discarded.length) {
+        const scopes = context.repositories.filter(repository => repository.scope?.length).map(repository => repository.scope.join(', ')).join('; ');
+        note(mode, `Undid ${plural(discarded.length, 'edit')} outside the repository scope (${scopes}): ${describeDiscarded(discarded, multiple)}. Only changes inside the scope are part of this change.`);
+    }
     // A timeout is a budget, not a defect: the groups already finished are
     // ticked in tasks.md and verified, and write_progress holds the handoff, so
     // the run BLOCKS (resume continues from the next open group, or raise
@@ -195,10 +245,9 @@ async function implementationVisit(deps, state, step, mode) {
     if (!outcome.ok)
         return settle(outcome, 'Finished task groups are ticked and verified; resume to continue from the next open group, or raise limits.timeoutMs.');
     new OpenSpecTools(deps.openspec.developer, step.signal).assertParticipation();
-    const record = outcome.value;
+    const record = withoutDiscarded(context, outcome.value, discarded);
     const effective = addDeveloperChecks(context, record.verificationChecks ?? []);
     bindPlan(context, effective);
-    const who = fixing ? 'Fixer' : 'Developer';
     note(mode, record.structured
         ? `${who} finished: ${plural(record.files.length, 'file')} changed, ${plural(record.tests.length, 'test file')} touched${record.incomplete.length ? `, ${plural(record.incomplete.length, 'task')} left incomplete` : ''}.`
         : `${who} finished without the structured summary; the prose summary is recorded instead.`);
@@ -237,8 +286,55 @@ function fixerNode(deps) {
         },
     };
 }
+/** Where a missing dependency install belongs: the nearest directory with a lockfile or manifest above the failing command, else the repository root. */
+const INSTALL_MARKERS = ['package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock', 'pnpm-lock.yaml', 'bun.lock', 'bun.lockb', 'requirements.txt', 'pyproject.toml', 'go.mod', 'Cargo.toml'];
+function installRoots(context, commands) {
+    const roots = [];
+    for (const command of commands) {
+        const repository = context.repositories.find(repo => repo.id === command.repositoryId);
+        if (!repository)
+            continue;
+        let directory = command.cwd;
+        let chosen = repository.path;
+        for (;;) {
+            const relative = path.relative(repository.path, directory);
+            if (relative.startsWith('..') || path.isAbsolute(relative))
+                break;
+            if (INSTALL_MARKERS.some(name => existsSync(path.join(directory, name)))) {
+                chosen = directory;
+                break;
+            }
+            if (!relative)
+                break;
+            directory = path.dirname(directory);
+        }
+        roots.push(chosen);
+    }
+    // Every repository root stays a candidate: its plan is a no-op when it is already installed.
+    return [...new Set([...roots, ...context.repositories.map(repository => repository.path)])];
+}
+/** A directory as the log should name it: relative to the checkout that contains it. */
+function checkoutRelative(context, directory) {
+    const repository = context.repositories.find(repo => { const relative = path.relative(repo.path, directory); return !relative.startsWith('..') && !path.isAbsolute(relative); });
+    return repository ? path.relative(repository.path, directory).split(path.sep).join('/') || '.' : directory;
+}
+function hostPreconditionMessage(reason, command, args, directory) {
+    return `Verification cannot run in this environment: ${reason} (\`${[command, ...args].join(' ')}\` in ${directory}). This is not a defect in the change, so no correction round was started. Make it available to Specrails (for example in the login shell profile Specrails loads, or with a refreshed registry token), then resume.`;
+}
+/** A failed check the host must unblock (credentials, registry access, a missing variable): no correction round can repair it. */
+function preconditionBlock(context, receipt) {
+    for (const command of receipt.commands) {
+        if (command.exitCode === 0)
+            continue;
+        const reason = hostPreconditionFailure(command.output);
+        if (reason)
+            return hostPreconditionMessage(reason, command.command, command.args, checkoutRelative(context, command.cwd));
+    }
+    return undefined;
+}
 function verifyNode(deps) {
     const { context, note, config } = deps;
+    const roots = context.repositories.map(repository => repository.path);
     return {
         effect: 'write', ends: ['reviewer', 'developer', 'fixer'],
         async run(state, step) {
@@ -257,35 +353,85 @@ function verifyNode(deps) {
                 throw new Error('Verification plan is unavailable');
             const plan = expandedPlanCommands(context, effective);
             const uncovered = uncoveredRepositories(context, plan);
-            let receipt = await verifyPipeline(context, { kind: 'full', planHash: effective.planHash, commands: plan, ...(uncovered.length ? { unverified: true } : {}) }, deps.onVerificationOutput, step.signal, { ...(guardrailEnabled(config.guardrails, 'verify-idle-timeout') ? {} : { idleTimeoutMs: 0 }), onEvidence: async (kind, payload) => { await step.reportEfficiencyActivity?.(kind, payload); }, maxConcurrency: effective.executionPolicy.maxConcurrency, ...(step.remainingBudget().maxDurationMs === undefined ? {} : { deadline: Date.now() + step.remainingBudget().maxDurationMs }) });
+            // A correction round that left the failed candidate exactly as it was
+            // cannot pass the same checks: stop instead of re-running them.
+            const recent = outcomesSinceResume(state.verifyHistory ?? [], step.checkpoint);
+            const last = recent.at(-1);
+            const rejected = last?.passed === true && state.review !== null && !state.review.approved;
+            if (recent.some(entry => !entry.passed) || rejected) {
+                const candidate = fingerprintCandidate(journal(context));
+                const unchanged = unchangedFailure(recent, candidate, effective.planHash);
+                if (unchanged) {
+                    note('fixer', 'The correction round did not change the candidate that failed verification; stopping instead of re-running the same checks.');
+                    return { status: 'blocked', error: `Correction loop stopped: the last correction round left the change exactly as it was when verification failed (${unchanged.summary}). Re-running the same checks cannot pass. If the failure lies outside this change (a pre-existing failure, another package or the environment), fix it there and resume.`, usage: NO_SPEND };
+                }
+                // The reviewer rejected exactly this candidate and the correction round changed nothing: the
+                // fixer disputes the request. Its evidence still holds, so the reviewer decides again without
+                // re-running the same checks; a second rejection of the same change ends the dispute.
+                if (rejected && last.candidateHash === candidate && last.planHash === effective.planHash) {
+                    const reviews = recent.filter(entry => entry.passed && entry.candidateHash === candidate && entry.planHash === effective.planHash).length;
+                    if (reviews >= 2) {
+                        note('fixer', 'The reviewer rejected the same unchanged change twice; stopping instead of another round.');
+                        return { status: 'blocked', error: `Correction loop stopped: the reviewer rejected the same change twice and the correction rounds did not change it (${state.review.issues.slice(0, 3).join('; ').slice(0, 600) || state.review.summary.slice(0, 300)}). Decide whether the review request applies to this change, then resume.`, usage: NO_SPEND };
+                    }
+                    if (inspectPipeline(context).verification.valid && state.verifyResult) {
+                        note('developer', 'The correction round did not change the verified change; reusing its verification evidence and returning to the reviewer.');
+                        transitionPipeline(context, 'developer', 'done');
+                        return { status: 'succeeded', next: 'reviewer', update: { verifyResult: state.verifyResult, verifyHistory: [{ ...last, at: new Date().toISOString() }] }, output: state.verifyResult, usage: NO_SPEND };
+                    }
+                }
+            }
+            const run = () => verifyPipeline(context, { kind: 'full', planHash: effective.planHash, commands: plan, ...(uncovered.length ? { unverified: true } : {}) }, deps.onVerificationOutput, step.signal, { ...(guardrailEnabled(config.guardrails, 'verify-idle-timeout') ? {} : { idleTimeoutMs: 0 }), onEvidence: async (kind, payload) => { await step.reportEfficiencyActivity?.(kind, payload); }, maxConcurrency: effective.executionPolicy.maxConcurrency, ...(step.remainingBudget().maxDurationMs === undefined ? {} : { deadline: Date.now() + step.remainingBudget().maxDurationMs }) });
+            let receipt = await run();
+            const hostBlocked = (reason) => {
+                note('fixer', 'Verification failed on the environment, not on the change; stopping for the host instead of starting a correction round.');
+                return { status: 'blocked', error: reason, usage: NO_SPEND };
+            };
+            let precondition = receipt.valid ? undefined : preconditionBlock(context, receipt);
+            if (precondition)
+                return hostBlocked(precondition);
             // A failure that is really a missing toolchain or dependency (exit 127,
             // "command not found", "Cannot find module"…) is the HOST's to fix, not
             // the model's — for every developer: a fresh worktree has no
-            // node_modules whatever wrote the code. Install once and re-verify; only
-            // a second failure becomes developer feedback.
+            // node_modules whatever wrote the code. Install once where the failing
+            // command runs and re-verify; only a second failure becomes feedback.
             if (!receipt.valid && guardrailEnabled(config.guardrails, 'environment-repair') && receipt.commands.some(command => isEnvironmentFailure(command.exitCode, command.output))) {
-                const installs = installEnvironment(context.repositories.map(repository => repository.path), { failureOutput: receipt.commands.map(command => command.output).join('\n'), lockfileRepair: guardrailEnabled(config.guardrails, 'lockfile-repair'), onEvent: event => note('developer', event.kind === 'text' ? event.text ?? '' : `[environment] ${event.tool ?? ''} ${event.detail ?? ''}`.trim()) });
+                const installs = installEnvironment(installRoots(context, receipt.commands.filter(command => command.exitCode !== 0)), { failureOutput: receipt.commands.map(command => command.output).join('\n'), lockfileRepair: guardrailEnabled(config.guardrails, 'lockfile-repair'), onEvent: event => note('developer', event.kind === 'text' ? event.text ?? '' : `[environment] ${event.tool ?? ''} ${event.detail ?? ''}`.trim()) });
+                const refused = installs.find(outcome => outcome.precondition);
+                if (refused)
+                    return hostBlocked(hostPreconditionMessage(`installing its dependencies failed because ${refused.precondition}`, refused.command, refused.args, checkoutRelative(context, refused.root)));
                 if (installs.some(outcome => outcome.ok)) {
                     note('developer', 'Verification failed on the environment (missing dependencies or tools); the host installed them and is verifying again.');
-                    receipt = await verifyPipeline(context, { kind: 'full', planHash: effective.planHash, commands: plan, ...(uncovered.length ? { unverified: true } : {}) }, deps.onVerificationOutput, step.signal, { ...(guardrailEnabled(config.guardrails, 'verify-idle-timeout') ? {} : { idleTimeoutMs: 0 }), onEvidence: async (kind, payload) => { await step.reportEfficiencyActivity?.(kind, payload); }, maxConcurrency: effective.executionPolicy.maxConcurrency, ...(step.remainingBudget().maxDurationMs === undefined ? {} : { deadline: Date.now() + step.remainingBudget().maxDurationMs }) });
+                    receipt = await run();
+                    precondition = receipt.valid ? undefined : preconditionBlock(context, receipt);
+                    if (precondition)
+                        return hostBlocked(precondition);
                 }
             }
             const evidence = {
                 valid: receipt.valid, ...(receipt.reason ? { reason: receipt.reason } : {}), receiptId: receipt.id, unverifiedRepositories: uncovered,
                 commands: receipt.commands.map(({ evidenceId, repositoryId, command, args, exitCode, output }) => ({ ...(evidenceId ? { evidenceId } : {}), repositoryId, command, args, exitCode, output: output.slice(-2000) })),
             };
-            if (!receipt.valid) {
-                note('fixer', `Verification failed (${receipt.reason ?? 'a command failed'}); handing the exact output to the fixer.`);
-                return { status: 'succeeded', next: 'fixer', update: { verifyResult: evidence }, output: evidence, usage: NO_SPEND };
-            }
+            const outcome = (passed, finding) => ({ at: new Date().toISOString(), candidateHash: receipt.candidateHash, planHash: effective.planHash, passed, ...(passed ? {} : describeFailure(receipt, roots, finding)) });
+            /** Hands a failure to the fixer unless the correction loop has stopped converging. */
+            const toFixer = (record, message, finding) => {
+                const failure = outcome(false, finding);
+                const loop = divergence(recent, failure);
+                if (loop) {
+                    note('fixer', 'The correction loop is not converging; stopping instead of starting another round.');
+                    return { status: 'blocked', error: `Correction loop stopped: ${loop} Inspect the evidence, fix what lies outside the change (or adjust the request), then resume.`, output: record, usage: NO_SPEND };
+                }
+                note('fixer', message);
+                return { status: 'succeeded', next: 'fixer', update: { verifyResult: record, verifyHistory: [failure] }, output: record, usage: NO_SPEND };
+            };
+            if (!receipt.valid)
+                return toFixer(evidence, `Verification failed (${receipt.reason ?? 'a command failed'}); handing the exact output to the fixer.`);
             // Exit 0 with "3 failed" in the output is a broken harness, not a pass.
             if (guardrailEnabled(config.guardrails, 'exit-code-honesty')) {
                 const findings = receipt.commands.flatMap(command => { const found = exitCodeContradiction(command.exitCode, command.output); return found ? [{ ...found, command: [command.command, ...command.args].join(' ') }] : []; });
                 if (findings.length) {
                     const reason = exitHonestyReason(findings);
-                    note('fixer', `Verification exited 0 but reported failures (${findings.map(item => item.sample).join(' | ')}); handing it to the fixer as a failure.`);
-                    const dishonest = { ...evidence, valid: false, reason };
-                    return { status: 'succeeded', next: 'fixer', update: { verifyResult: dishonest }, output: dishonest, usage: NO_SPEND };
+                    return toFixer({ ...evidence, valid: false, reason }, `Verification exited 0 but reported failures (${findings.map(item => item.sample).join(' | ')}); handing it to the fixer as a failure.`, reason);
                 }
             }
             // Every command exited 0 — but did any of them RUN the tests the
@@ -299,14 +445,12 @@ function verifyNode(deps) {
                 const unreached = context.repositories.flatMap(repository => unreachedTestFiles(repository.path, plan.filter(command => command.repositoryId === repository.id).map(({ command, args, cwd }) => ({ command, args, ...(cwd ? { cwd } : {}) })), reported).map(file => context.repositories.length > 1 ? `${repository.id}:${file}` : file));
                 if (unreached.length) {
                     const reason = unreachedTestsReason(unreached);
-                    note('fixer', `Verification incomplete: ${unreached.join(', ')} ${unreached.length === 1 ? 'is' : 'are'} not run by any verification command; handing it to the fixer.`);
-                    const incomplete = { ...evidence, valid: false, reason };
-                    return { status: 'succeeded', next: 'fixer', update: { verifyResult: incomplete }, output: incomplete, usage: NO_SPEND };
+                    return toFixer({ ...evidence, valid: false, reason }, `Verification incomplete: ${unreached.join(', ')} ${unreached.length === 1 ? 'is' : 'are'} not run by any verification command; handing it to the fixer.`, reason);
                 }
             }
             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 }, output: evidence, usage: NO_SPEND };
+            return { status: 'succeeded', next: 'reviewer', update: { verifyResult: evidence, verifyHistory: [outcome(true)] }, output: evidence, usage: NO_SPEND };
         },
     };
 }
@@ -365,9 +509,12 @@ function reviewerNode(deps) {
                 : undefined;
             if (reReview)
                 note('reviewer', `Re-review: ${plural(reReview.changes.length, 'file')} changed since the previous verdict; certifying the previous issues instead of re-reading the candidate.`);
-            const prompt = roleInstructions('reviewer', context, change, { definition: config.rolePrompts?.reviewer, feedback: feedbackFor(state), verification: state.plan, policy, criteria, developer: state.development, ...(reReview ? { reReview } : {}) });
+            // 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 incremental = config.efficiency?.reviewMode !== 'full' && delta.mode === 'incremental' && state.review?.sessionId;
-            const followup = correctionInstructions('reviewer', feedbackFor(state)) + '\nChanges since YOUR previous reviewed candidate:\n' + JSON.stringify(delta.changes)
+            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);
             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 => {

package/dist/agent-runtime/graph/roles.d.ts

@@ -1,3 +1,4 @@
+import { type RoleStatePort } from '../role-state.js';
 import { type InvocationKind } from '../role-routing.js';
 import { type PipelineContext } from '../../pipeline/pipeline-state.js';
 import type { ExecutorRegistry } from '../executors.js';
@@ -17,6 +18,9 @@ export interface InvokeOptions {
     /** Run this invocation on another configured engine (the fixer) with the matching stance; sessions never carry across engines. */
     agentOverride?: RuntimeAgentConfig;
     stance?: 'fixer';
+    /** Per-piece invocation bounds; explicit zero disables only that timer. */
+    timeoutMs?: number;
+    idleTimeoutMs?: number;
 }
 export type InvokeOutcome<T> = {
     ok: true;
@@ -36,6 +40,8 @@ export interface RoleInvokerDeps {
     config: RuntimeConfig;
     registry: ExecutorRegistry;
     openspec?: Record<AgentRole, import('../openspec.js').OpenSpecRoleContext>;
+    /** Engine hosts isolate sessions/routes by scope and node instead of a role-global file. */
+    roleState?: RoleStatePort;
     /** `fixer` labels the developer step's events during a correction round on the fixer stance, so a log reader sees who is acting. */
     onAgentEvent?: (role: AgentEventRole, event: AgentEvent) => void;
 }

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

@@ -1,8 +1,10 @@
+import { resolveRoleDescriptor } from '../config.js';
+import { isBuiltinRole } from '../executor-types.js';
 import { repositoryContextSnapshot, renderRepositoryContext } from '../repository-context.js';
 import { readRoleState, writeRoleState } from '../role-state.js';
 import { fingerprint } from '../durable-store.js';
 import { selectRoleRoute } from '../role-routing.js';
-import { ROLE_SKILLS, OPENSPEC_VERSION, OpenSpecTools, OpenSpecParticipationError, openSpecRepairPrompt } from '../openspec.js';
+import { openSpecSkill, OPENSPEC_VERSION, OpenSpecTools, OpenSpecParticipationError, openSpecRepairPrompt } from '../openspec.js';
 import path from 'node:path';
 import { performance } from 'node:perf_hooks';
 import { frozenAcceptanceCriteria, pipelineStateDirectory } from '../../pipeline/pipeline-state.js';
@@ -48,31 +50,33 @@ export function createRoleInvoker(deps) {
     }
     catch { /* Observer cannot replay agent effects. */ } };
     const execute = async (role, step, prompt, structured, extra) => {
-        const directory = deps.openspec?.[role].stateDirectory ?? path.join(pipelineStateDirectory(context), 'agent-workflow');
-        const saved = readRoleState(directory);
+        const directory = deps.openspec?.[role]?.stateDirectory ?? path.join(pipelineStateDirectory(context), 'agent-workflow');
+        const saved = deps.roleState?.read() ?? readRoleState(directory);
+        const persist = () => deps.roleState ? deps.roleState.write(saved) : writeRoleState(directory, saved);
         const budget = step.remainingBudget();
         if (budget.maxTokens === 0 || budget.maxCostUsd === 0 || step.signal.aborted)
             throw new AgentExecutionError('No budget remains for another role invocation', step.signal.aborted ? 'aborted' : 'budget_exhausted', { inputTokens: 0, outputTokens: 0, costUsd: 0 });
         const kind = extra.kind ?? (extra.resumeSessionId ? 'correction' : 'initial');
-        const route = selectRoleRoute(role, extra.agentOverride ?? config.agents[role], kind, step.checkpoint, extra.agentOverride ? undefined : saved.routes[role]);
+        const descriptor = resolveRoleDescriptor(config, role);
+        const route = selectRoleRoute(role, extra.agentOverride ?? (isBuiltinRole(role) ? config.agents[role] : descriptor), kind, step.checkpoint, extra.agentOverride ? undefined : saved.routes[role]);
         const selected = route.selection;
         const capabilities = await registry.capabilities(selected.provider, selected.model);
-        const identity = fingerprint({ role, selected, transport: capabilities.transport, instructionsVersion: ROLE_INSTRUCTIONS_VERSION, provider: config.providers.find(provider => provider.id === selected.provider) ?? selected.provider, definition: (extra.agentOverride ? config.rolePrompts?.fixer : config.rolePrompts?.[role]) ?? null, openspec: deps.openspec?.[role] ?? null, context });
+        const identity = fingerprint({ role, selected, transport: capabilities.transport, instructionsVersion: ROLE_INSTRUCTIONS_VERSION, provider: config.providers.find(provider => provider.id === selected.provider) ?? selected.provider, definition: (extra.agentOverride ? config.rolePrompts?.fixer : config.rolePrompts?.[role] ?? descriptor.prompt) ?? null, ...(isBuiltinRole(role) ? {} : { policy: descriptor }), openspec: deps.openspec?.[role] ?? null, context });
         const previous = saved.sessions[role];
         const resumeSessionId = capabilities.continuation === 'supported' && previous?.identity === identity && previous.sessionId === extra.resumeSessionId ? extra.resumeSessionId : undefined;
         const snapshot = repositoryContextSnapshot(context);
-        const incremental = Boolean(resumeSessionId && config.efficiency?.contextMode !== 'full');
+        const incremental = Boolean(resumeSessionId && capabilities.resumeRequiresFullContext !== true && config.efficiency?.contextMode !== 'full');
         const packet = renderRepositoryContext(snapshot, incremental ? previous?.context : undefined);
-        const rolePrompt = !resumeSessionId && extra.fallbackPrompt ? extra.fallbackPrompt : prompt;
+        const rolePrompt = (!resumeSessionId || capabilities.resumeRequiresFullContext) && extra.fallbackPrompt ? extra.fallbackPrompt : prompt;
         const obligations = '\nCurrent frozen acceptance obligations (all remain required):\n' + JSON.stringify(frozenAcceptanceCriteria(context));
-        const fullPrompt = rolePrompt + obligations + '\n\n' + packet;
+        const fullPrompt = rolePrompt + (step.operatorSteering ?? '') + obligations + '\n\n' + packet;
         if (extra.agentOverride)
             note(role, `Fixer route: ${selected.provider}/${selected.model ?? 'provider default'} — correction round on the fixer engine`);
         else if (saved.routes[role]?.tier !== route.tier)
             note(role, `Role route: ${selected.provider}/${selected.model ?? 'provider default'} — ${route.reason}`);
         if (!extra.agentOverride) {
             saved.routes[role] = { tier: route.tier, reason: route.reason, attemptId: step.attemptId };
-            writeRoleState(directory, saved);
+            persist();
         }
         const measurement = { provider: selected.provider, ...(selected.model ? { model: selected.model } : {}),
             contextMode: incremental ? 'incremental' : 'full', promptBytes: Buffer.byteLength(fullPrompt), contextBytes: Buffer.byteLength(packet), handoffBytes: Buffer.byteLength(rolePrompt), requestedEffort: selected.effort ?? null,
@@ -85,11 +89,12 @@ export function createRoleInvoker(deps) {
         const onEvent = forward(extra.stance === 'fixer' ? 'fixer' : role, structured);
         try {
             if (deps.openspec?.[role])
-                note(role, `OpenSpec ${OPENSPEC_VERSION}: ${ROLE_SKILLS[role]} (official skill document through scoped tools).`);
+                note(role, `OpenSpec ${OPENSPEC_VERSION}: ${openSpecSkill(deps.openspec[role])} (official skill document through scoped tools).`);
             const result = await registry.execute(selected.provider, {
-                role, prompt: fullPrompt, openspec: deps.openspec?.[role] ? { ...deps.openspec[role], ...(role === 'architect' ? {} : { evidenceScope: { backlogRoot: context.backlogRoot, runId: context.runId } }) } : undefined, cwd: context.artifactRoot, allowedRoots: context.repositories.map(repo => repo.path),
+                role, access: descriptor.access, artifacts: descriptor.artifacts, instructions: 'role', prompt: fullPrompt, openspec: deps.openspec?.[role] ? { ...deps.openspec[role], ...(role === 'architect' ? {} : { evidenceScope: { backlogRoot: context.backlogRoot, runId: context.runId } }) } : undefined, cwd: context.artifactRoot, allowedRoots: context.repositories.map(repo => repo.path),
                 model: selected.model, effort: selected.effort, ...(selected.thinking ? { thinking: selected.thinking } : {}), maxTurns: selected.maxTurns, signal: step.signal,
-                timeoutMs: config.limits?.timeoutMs,
+                timeoutMs: extra.timeoutMs ?? config.limits?.timeoutMs,
+                idleTimeoutMs: extra.idleTimeoutMs ?? config.limits?.idleTimeoutMs,
                 maxTokens: budget.maxTokens, maxCostUsd: budget.maxCostUsd,
                 ...(config.guardrails ? { guardrails: config.guardrails } : {}),
                 ...(extra.stance ? { stance: extra.stance } : {}),
@@ -103,7 +108,7 @@ export function createRoleInvoker(deps) {
                 saved.sessions[role] = { identity, sessionId: result.sessionId, context: snapshot };
             else
                 delete saved.sessions[role];
-            writeRoleState(directory, saved);
+            persist();
             succeeded = true;
             return result;
         }
@@ -119,6 +124,7 @@ export function createRoleInvoker(deps) {
         }
     };
     return async (role, step, options, accept) => {
+        const timers = { timeoutMs: options.timeoutMs, idleTimeoutMs: options.idleTimeoutMs };
         const structured = options.structured === true;
         const workflow = deps.openspec?.[role] ? new OpenSpecTools(deps.openspec[role]) : undefined;
         const cursor = workflow?.participationCursor() ?? 0;
@@ -146,17 +152,17 @@ export function createRoleInvoker(deps) {
                 // A correction pass continues the role's own session: the work it did and
                 // the reasons behind it are already in context.
                 try {
-                    result = await execute(role, step, options.prompt, structured, { kind: options.kind, resumeSessionId: options.resumeSessionId, outputSchema: options.outputSchema, fallbackPrompt: options.fallbackPrompt, agentOverride: options.agentOverride, stance: options.stance });
+                    result = await execute(role, step, options.prompt, structured, { ...timers, kind: options.kind, resumeSessionId: options.resumeSessionId, outputSchema: options.outputSchema, fallbackPrompt: options.fallbackPrompt, agentOverride: options.agentOverride, stance: options.stance });
                 }
                 catch (error) {
                     if (!(error instanceof AgentExecutionError) || !SESSION_FALLBACK_CODES.has(error.code))
                         throw error;
                     note(role, `Previous ${role} session is unavailable; starting a fresh ${role} turn with the same instructions.`);
-                    result = await execute(role, step, options.fallbackPrompt, structured, { kind: 'session-fallback', outputSchema: options.outputSchema, agentOverride: options.agentOverride, stance: options.stance });
+                    result = await execute(role, step, options.fallbackPrompt, structured, { ...timers, kind: 'session-fallback', outputSchema: options.outputSchema, agentOverride: options.agentOverride, stance: options.stance });
                 }
             }
             else {
-                result = await execute(role, step, options.prompt, structured, { kind: options.kind, resumeSessionId: options.resumeSessionId, outputSchema: options.outputSchema, fallbackPrompt: options.fallbackPrompt, agentOverride: options.agentOverride, stance: options.stance });
+                result = await execute(role, step, options.prompt, structured, { ...timers, kind: options.kind, resumeSessionId: options.resumeSessionId, outputSchema: options.outputSchema, fallbackPrompt: options.fallbackPrompt, agentOverride: options.agentOverride, stance: options.stance });
             }
             let problem, omittedWorkflow = false;
             try {
@@ -175,7 +181,7 @@ export function createRoleInvoker(deps) {
             note(role, omittedWorkflow
                 ? `The ${role} omitted its required OpenSpec workflow; requesting one correction in the same role before accepting the result.`
                 : `The ${role} reply was not a valid result (${problem}); asking the same session to resend it.`);
-            const repaired = await execute(role, step, result.sessionId ? repair : (options.fallbackPrompt ?? options.prompt) + '\n' + repair, structured, { kind: 'repair', resumeSessionId: result.sessionId, outputSchema: options.outputSchema,
+            const repaired = await execute(role, step, result.sessionId ? repair : (options.fallbackPrompt ?? options.prompt) + '\n' + repair, structured, { ...timers, kind: 'repair', resumeSessionId: result.sessionId, outputSchema: options.outputSchema,
                 fallbackPrompt: (options.fallbackPrompt ?? options.prompt) + '\nPrevious response (bounded):\n' + result.text.slice(-32_000) + '\n' + repair,
             });
             try {

package/dist/agent-runtime/graph/state.d.ts

@@ -1,4 +1,5 @@
 import type { VerificationCommand } from '../../pipeline/pipeline-state.js';
+import type { VerifyOutcome } from './convergence.js';
 export type DesignConfidence = 'high' | 'medium' | 'low';
 export interface ArchitectureRecord {
     planningDepth?: 'focused' | 'full';
@@ -28,6 +29,8 @@ export interface DeveloperRecord {
     }>;
     /** False when the provider returned prose instead of the structured summary. */
     structured: boolean;
+    /** Edits outside the repository scope that Core undid after this turn (repository-qualified when several repositories are in scope). */
+    discarded?: string[];
 }
 export interface VerificationRecord {
     valid: boolean;
@@ -76,6 +79,8 @@ export declare const CoreState: import("@langchain/langgraph").AnnotationRoot<{
     /** Autonomous investigation passes the architect already spent on a low-confidence design. */
     deepenPasses: import("@langchain/langgraph").BaseChannel<number, number | import("@langchain/langgraph").OverwriteValue<number>, unknown>;
     archived: import("@langchain/langgraph").BaseChannel<ArchiveRecord | null, ArchiveRecord | import("@langchain/langgraph").OverwriteValue<ArchiveRecord | null> | null, unknown>;
+    /** Recent verify outcomes (bounded), so the host can tell a converging correction loop from a circular one. */
+    verifyHistory: import("@langchain/langgraph").BaseChannel<VerifyOutcome[], VerifyOutcome[] | import("@langchain/langgraph").OverwriteValue<VerifyOutcome[]>, unknown>;
 }>;
 export type CoreStateType = typeof CoreState.State;
 export type CoreStateUpdate = typeof CoreState.Update;

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

@@ -18,6 +18,8 @@ export const CoreState = Annotation.Root({
     /** Autonomous investigation passes the architect already spent on a low-confidence design. */
     deepenPasses: Annotation({ ...replace(), default: () => 0 }),
     archived: Annotation({ ...replace(), default: () => null }),
+    /** Recent verify outcomes (bounded), so the host can tell a converging correction loop from a circular one. */
+    verifyHistory: Annotation({ reducer: (previous, next) => [...previous, ...next].slice(-50), default: () => [] }),
 });
 /** Graph order. `fixer` is the correction node: verify (failed, tasks ticked) and reviewer (rejected) route there; it hands back to verify. */
 export const CORE_NODE_ORDER = ['architect', 'developer', 'fixer', 'verify', 'reviewer', 'archive'];

package/dist/agent-runtime/kimi-acp.js

@@ -1,22 +1,22 @@
 import { toolEvent } from './tool-event.js';
 import { normalizeKimiCliModel } from './kimi-model.js';
-import { AgentExecutionError, unknownUsage, validateAgentRequest } from './executor-types.js';
+import { AgentExecutionError, unknownUsage, normalizeAgentRequest } from './executor-types.js';
 import { runCliProcess } from './cli-process.js';
 import { parseStructuredText } from './openai-executor.js';
 import { WorkspaceTools } from './workspace-tools.js';
 function record(value) { return value && typeof value === 'object' && !Array.isArray(value) ? value : {}; }
 /** Native ACP v1 keeps Kimi 0.27 read-only roles usable without a platform skill or a model call during capability negotiation. */
 export async function executeKimiReadonlyAcp(request, options = {}) {
-    validateAgentRequest(request);
-    if (request.role === 'developer' && !options.openspecBridge)
+    request = normalizeAgentRequest(request);
+    if (request.access === 'write' && !options.openspecBridge)
         throw new AgentExecutionError('Read-only ACP transport cannot execute developer roles', 'invalid_request');
     if (request.maxCostUsd !== undefined)
         throw new AgentExecutionError('Kimi cannot enforce a strict USD cap', 'cost_limit_unsupported');
     if (request.maxTokens !== undefined)
         throw new AgentExecutionError('Kimi 0.27 ACP does not report authoritative token usage. Remove the token cap or choose another provider for this role.', 'usage_unavailable');
-    const readOnly = request.role !== 'developer';
+    const readOnly = request.access === 'read';
     const mode = readOnly ? 'plan' : 'auto';
-    const tools = new WorkspaceTools(request.cwd, request.allowedRoots, request.role);
+    const tools = new WorkspaceTools(request.cwd, request.allowedRoots, request.access);
     let transport, nextId = 0, sessionId, text = '', completed = false, turns = 0, permissionDenied = false;
     const calls = new Map();
     const send = (method, params, success) => {
@@ -157,7 +157,7 @@ export async function executeKimiReadonlyAcp(request, options = {}) {
         call.success(record(message.result));
     };
     const result = await (options.runProcess ?? runCliProcess)({ command: 'kimi', args: ['acp'] }, {
-        cwd: tools.cwd, signal: request.signal, timeoutMs: request.timeoutMs ?? 15 * 60_000, env: options.env, onLine: onMessage,
+        cwd: tools.cwd, signal: request.signal, timeoutMs: request.timeoutMs ?? 15 * 60_000, idleTimeoutMs: request.idleTimeoutMs, env: options.env, onLine: onMessage,
         duplex: control => {
             transport = control;
             send('initialize', { protocolVersion: 1, clientInfo: { name: 'specrails-core', version: '1' }, clientCapabilities: { fs: { readTextFile: readOnly, writeTextFile: readOnly }, terminal: readOnly } }, initialized => {

package/dist/agent-runtime/openai-executor.js

@@ -1,7 +1,7 @@
 import { readVerificationEvidence } from '../pipeline/pipeline-state.js';
 import { assertEffortSupported, unknownCapabilities } from './capabilities.js';
 import { OpenSpecTools, OPENSPEC_TOOL_DEFINITION, openSpecPrompt } from './openspec.js';
-import { AgentExecutionError, unknownUsage, validateAgentRequest } from './executor-types.js';
+import { AgentExecutionError, unknownUsage, normalizeAgentRequest, isBuiltinRole } from './executor-types.js';
 import { WorkspaceTools } from './workspace-tools.js';
 import { ChatClient, record } from './compact/chat-client.js';
 import { DEFAULT_CONTEXT_WINDOW_TOKENS, runToolLoop } from './compact/guarded-loop.js';
@@ -40,13 +40,15 @@ export class OpenAICompatibleExecutor {
             throw new AgentExecutionError('A strict USD cap requires an executor with a native spending limit; OpenAI-compatible endpoints do not provide one. Use a token cap or an executor with native cost enforcement.', 'cost_limit_unsupported');
     }
     async execute(request) {
-        validateAgentRequest(request);
+        request = normalizeAgentRequest(request);
+        if (request.nativeCommand)
+            throw new AgentExecutionError('OpenAI-compatible providers do not support native commands', 'native_command_unsupported');
         assertEffortSupported(request, this.capabilities());
         this.validateLimits(request);
         if (!request.model?.trim())
             throw new AgentExecutionError('OpenAI-compatible execution requires a model', 'invalid_model');
         const controller = new AbortController();
-        const toolset = new WorkspaceTools(request.cwd, request.allowedRoots, request.role);
+        const toolset = new WorkspaceTools(request.cwd, request.allowedRoots, request.access);
         const openspec = request.openspec ? new OpenSpecTools(request.openspec, controller.signal) : undefined;
         const evidenceScope = request.openspec?.evidenceScope && request.role !== 'architect' ? request.openspec.evidenceScope : undefined;
         const definitions = [...toolset.definitions(), ...(openspec ? [OPENSPEC_TOOL_DEFINITION] : []), ...(evidenceScope ? [{ type: 'function', function: { name: 'read_verification_evidence', description: 'Read host verification evidence and source files with opaque IDs and bounded cursors. List to discover IDs.', parameters: { type: 'object', additionalProperties: false, properties: { id: { type: 'string' }, section: { type: 'string', enum: ['summary', 'stdout', 'stderr', 'source'] }, sourceId: { type: 'string' }, cursor: { type: 'string' }, limit: { type: 'integer', minimum: 1, maximum: 100 } } } } }] : [])];
@@ -56,11 +58,13 @@ export class OpenAICompatibleExecutor {
         // The compact pipelines are several bounded model calls per role (the
         // architect alone is ~8); a role budget sized for one agentic call would
         // cut them off. Scale the DEFAULT only — an explicit timeout is respected.
-        const compact = resolveAgentLoop(this.provider) === 'compact' && request.openspec !== undefined;
+        const compact = isBuiltinRole(request.role) && request.instructions === 'role' && resolveAgentLoop(this.provider) === 'compact' && request.openspec !== undefined;
         const timeoutMs = request.timeoutMs ?? this.options.defaultTimeoutMs ?? (compact ? 45 * 60_000 : 15 * 60_000);
-        const idleTimeoutMs = this.options.idleTimeoutMs ?? IDLE_TIMEOUT_MS;
-        if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1)
-            throw new AgentExecutionError('timeoutMs must be a positive integer', 'invalid_limit');
+        const idleTimeoutMs = request.idleTimeoutMs ?? this.options.idleTimeoutMs ?? IDLE_TIMEOUT_MS;
+        for (const value of [timeoutMs, idleTimeoutMs]) {
+            if (!Number.isSafeInteger(value) || value < 0 || value > 2_147_483_647)
+                throw new AgentExecutionError('Timeouts must be nonnegative timer integers', 'invalid_limit');
+        }
         const env = this.options.env ?? process.env;
         const key = this.provider.apiKeyEnv ? env[this.provider.apiKeyEnv] : undefined;
         if (this.provider.apiKeyEnv && !key)
@@ -81,10 +85,11 @@ export class OpenAICompatibleExecutor {
         // group role while it is still producing (observed: groups 1–2 verified
         // green, group 3 cut mid-patch, whole run failed). A genuine hang is the
         // idle watchdog's job: no tool call, reply or usage for IDLE_TIMEOUT_MS.
-        let timer = setTimeout(() => controller.abort(new Error('Agent timeout')), timeoutMs);
-        const resetDeadline = () => { clearTimeout(timer); timer = setTimeout(() => controller.abort(new Error('Agent timeout')), timeoutMs); };
+        let timer;
+        const resetDeadline = () => { clearTimeout(timer); timer = timeoutMs > 0 ? setTimeout(() => controller.abort(new Error('Agent timeout')), timeoutMs) : undefined; };
+        resetDeadline();
         let lastActivity = Date.now();
-        const idle = compact ? setInterval(() => { if (Date.now() - lastActivity > idleTimeoutMs)
+        const idle = (compact || request.idleTimeoutMs !== undefined) && idleTimeoutMs > 0 ? setInterval(() => { if (Date.now() - lastActivity > idleTimeoutMs)
             controller.abort(new Error('Agent idle timeout')); }, Math.min(15_000, Math.max(50, Math.floor(idleTimeoutMs / 4)))) : undefined;
         idle?.unref?.();
         const onEvent = request.onEvent || idle ? (event) => { lastActivity = Date.now(); request.onEvent?.(event); } : undefined;
@@ -95,13 +100,13 @@ export class OpenAICompatibleExecutor {
         try {
             // Compact pipelines need the official workflow to drive; a plain role task
             // without an OpenSpec binding runs the guarded loop instead.
-            if (resolveAgentLoop(this.provider) === 'compact' && openspec) {
+            if (compact && openspec) {
                 compactMode = true;
                 const compact = { client, request, inputs: extractPromptInputs(request.prompt), toolset, openspec, contextWindowTokens, ...(maxOutputTokens === undefined ? {} : { maxOutputTokens }), resetDeadline, signal: controller.signal, onEvent, guardrails: request.guardrails, stance: request.stance };
                 return request.role === 'architect' ? await runCompactArchitect(compact) : request.role === 'developer' ? await runCompactDeveloper(compact) : await runCompactReviewer(compact);
             }
             const messages = [
-                { role: 'system', content: `You execute one ${request.role} task. Use only the provided workspace tools. Allowed roots: ${JSON.stringify(toolset.roots)}. Working directory: ${toolset.cwd}. Return the complete requested final result. Do not coordinate another workflow. Execute only the assigned role and its supplied OpenSpec workflow.` },
+                ...(request.instructions === 'none' ? [] : [{ role: 'system', content: `You execute one ${request.role} task. Use only the provided workspace tools. Allowed roots: ${JSON.stringify(toolset.roots)}. Working directory: ${toolset.cwd}. Return the complete requested final result. Do not coordinate another workflow. Execute only the assigned role and its supplied OpenSpec workflow.` }]),
                 { role: 'user', content: (request.openspec ? openSpecPrompt(request.openspec) : '') + request.prompt },
             ];
             const { text } = await runToolLoop({