specrails-core 6.0.0 → 6.1.0

package/dist/agent-runtime/evaluation.js

@@ -10,6 +10,13 @@ import { ExecutorRegistry } from './executors.js';
 import { OpenSpecTools } from './openspec.js';
 import { validatePipelineContext } from '../pipeline/pipeline-state.js';
 import { runtimeEfficiency } from './efficiency.js';
+import { validateWorkflowDefinition } from './engine/definition-validator.js';
+import { validationPieceRegistry } from './engine/pieces/index.js';
+import { configuredRoles } from './engine/preflight.js';
+import { createRun, definitionRunDirectory } from './engine/runs.js';
+import { observeLedger } from './engine/run-status.js';
+import { RunDatabase } from './engine/checkpoint/database.js';
+import { ledgerWorkflowState } from './engine/invocation-context.js';
 function oracle(test, file) {
     return spawnSync(process.execPath, ['-e', 'const assert = require("node:assert/strict"); const api = require(process.argv[1]);' + test.oracle, file], { encoding: 'utf8', timeout: 10000 }).status === 0;
 }
@@ -26,12 +33,13 @@ function prepare(test, root) {
     });
     return validatePipelineContext({ schemaVersion: 1, runId: randomUUID(), backlogRoot: root, artifactRoot: repositories[0].path, artifactRepositoryId: repositories[0].id, repositories, ownership: { git: 'host', backlog: 'host', worktrees: 'host' }, specs: [{ id: 1, title: test.id, description: test.description + ' Implement behavior in implementation.cjs in every selected repository.', repositoryIds: test.repositories, acceptanceCriteria: [test.description] }] });
 }
-function fixtureRegistry(test, context) {
+function fixtureRegistry(test, context, onPrompt) {
     let developers = 0, reviews = 0;
     const sessions = new Map();
     return new ExecutorRegistry().register('fixture', {
         capabilities: () => ({ transport: 'offline-fixture', continuation: 'supported', effortSupport: 'unsupported', supportedEfforts: [], observedModel: false, observedEffort: false }),
         async execute(request) {
+            onPrompt?.(request);
             const sessionId = 'fixture-' + request.role;
             if (request.resumeSessionId && !sessions.has(request.resumeSessionId))
                 throw new Error('Fixture session was not restored');
@@ -57,11 +65,11 @@ function fixtureRegistry(test, context) {
             }
             else {
                 await tools.execute({ action: 'instructions', artifact: 'apply' });
-                if (request.role === 'developer') {
+                if (request.role === 'developer' || request.role === 'fixer') {
                     developers++;
                     for (const repo of context.repositories)
                         writeFileSync(path.join(repo.path, 'implementation.cjs'), test.correction && developers === 1 ? test.defects[0] : test.solution);
-                    writeFileSync(path.join(context.artifactRoot, 'openspec/changes/evaluation-change/tasks.md'), '## 1. Implementation\n- [x] 1.1 Implement and test the requested behavior\n');
+                    await tools.execute({ action: 'write_artifact', path: 'tasks.md', content: '## 1. Implementation\n- [x] 1.1 Implement and test the requested behavior\n' });
                     output = { summary: 'Implemented fixture behavior', files: ['implementation.cjs'], tests: [], verification: 'Core executes the frozen checks', incomplete: [] };
                 }
                 else {
@@ -75,18 +83,23 @@ function fixtureRegistry(test, context) {
     });
 }
 export async function runEvaluation(options) {
+    if (options.capturePrompts && options.real)
+        throw new Error('Prompt capture is limited to offline fixture evaluation');
     const repetitions = options.repetitions ?? 1;
     if (!Number.isSafeInteger(repetitions) || repetitions < 1 || repetitions > 20)
         throw new Error('Evaluation repetitions must be 1–20');
     if (options.real && (!options.config || !Number.isFinite(options.maxCostUsd) || options.maxCostUsd <= 0 || Object.values(options.config.agents).some(role => !role.model)))
         throw new Error('Real evaluation requires explicit per-role models and a positive aggregate spend limit');
+    const corpus = options.caseIds ? EVALUATION_CORPUS.filter(item => options.caseIds.includes(item.id)) : EVALUATION_CORPUS;
+    if (!corpus.length || options.caseIds?.some(id => !corpus.some(item => item.id === id)))
+        throw new Error('Unknown or empty evaluation case selection');
     const identity = coreRuntimeIdentity();
     const observations = [];
-    let spend = 0, stopReason = null;
+    let spend = 0, stopReason = null, evaluatedDefinitionVersion = null;
     const root = mkdtempSync(path.join(tmpdir(), 'specrails-evaluation-'));
     try {
         for (let repeat = 0; repeat < repetitions && !stopReason; repeat++)
-            for (const test of EVALUATION_CORPUS) {
+            for (const test of corpus) {
                 // Check the independent oracle itself against defective candidates.
                 const probe = path.join(root, 'oracle-probe.cjs');
                 writeFileSync(probe, test.solution);
@@ -113,7 +126,33 @@ export async function runEvaluation(options) {
                     const started = Date.now();
                     let state;
                     try {
-                        state = await runCoreWorkflow({ context, change: 'evaluation-change', config, ...(options.real ? {} : { registry: fixtureRegistry(test, context) }) });
+                        let promptNumber = 0;
+                        const capture = options.capturePrompts ? (request) => {
+                            const directory = path.join(options.output, 'prompts', test.id + '-' + repeat + '-' + mode);
+                            mkdirSync(directory, { recursive: true, mode: 0o700 });
+                            const filename = String(++promptNumber).padStart(2, '0') + '-' + request.role + (request.stance ? '-' + request.stance : '');
+                            writeFileSync(path.join(directory, filename + '.txt'), request.prompt, { mode: 0o600 });
+                            writeFileSync(path.join(directory, filename + '.json'), JSON.stringify({ role: request.role, stance: request.stance ?? null,
+                                model: request.model ?? null, resumeSessionId: request.resumeSessionId ?? null, promptBytes: Buffer.byteLength(request.prompt),
+                                sections: request.prompt.split(/(?=^#{1,4} )/m).map(section => ({ heading: section.split('\n')[0].slice(0, 150), bytes: Buffer.byteLength(section) })) }, null, 2) + '\n', { mode: 0o600 });
+                        } : undefined;
+                        const registry = options.real ? undefined : fixtureRegistry(test, context, capture);
+                        if (options.definition === undefined)
+                            state = await runCoreWorkflow({ context, change: 'evaluation-change', config, ...(registry ? { registry } : {}) });
+                        else {
+                            const validation = validateWorkflowDefinition(options.definition, validationPieceRegistry(), configuredRoles(config), { published: true });
+                            if (!validation.ok)
+                                throw new Error('Evaluation definition failed validation: ' + JSON.stringify(validation.errors));
+                            evaluatedDefinitionVersion = validation.version;
+                            await createRun({ context, change: 'evaluation-change', config, definition: validation.definition, ...(registry ? { registry } : {}) });
+                            const database = await RunDatabase.open(path.join(definitionRunDirectory(context), 'run.sqlite'), { readOnly: true });
+                            try {
+                                state = ledgerWorkflowState(observeLedger(database), validation.definition, '*');
+                            }
+                            finally {
+                                database.close();
+                            }
+                        }
                     }
                     catch (error) {
                         observations.push({ caseId: test.id, repeat, mode, status: 'blocked', independentAccepted: false, error: error instanceof Error ? error.message : String(error), runtimeIdentity: identity, taskHash: fingerprint(test), oracleHash: fingerprint(test.oracle), repositories: context.repositories.map(({ id, baseSha }) => ({ id, baseSha })), configHash: fingerprint(config) });
@@ -145,7 +184,7 @@ export async function runEvaluation(options) {
             return [mode, { samples: rows.length, independentlyAccepted: accepted, costPerAcceptedUsd: options.real && knownCost !== null && accepted ? knownCost / accepted : null, medianActiveDurationMs: median(durations), minActiveDurationMs: durations.length ? Math.min(...durations) : null, maxActiveDurationMs: durations.length ? Math.max(...durations) : null, standardDeviationMs: average === null ? null : Math.sqrt(durations.reduce((sum, value) => sum + (value - average) ** 2, 0) / durations.length) }];
         }));
         const full = groups.full, optimized = groups.optimized;
-        const paired = observations.length === EVALUATION_CORPUS.length * repetitions * 2 && full.samples === optimized.samples;
+        const paired = observations.length === corpus.length * repetitions * 2 && full.samples === optimized.samples;
         const noObservedQualityDrop = paired && optimized.independentlyAccepted >= full.independentlyAccepted;
         const promptPairs = observations.filter(row => row.mode === 'full' && row.caseId === 'verification-correction').map(row => {
             const other = observations.find(item => item.mode === 'optimized' && item.caseId === row.caseId && item.repeat === row.repeat);
@@ -158,7 +197,10 @@ export async function runEvaluation(options) {
             return Array.isArray(row.invocations) && Array.isArray(other?.invocations) && other.invocations.length <= row.invocations.length;
         });
         const monetaryConclusion = options.real && paired && full.costPerAcceptedUsd !== null && optimized.costPerAcceptedUsd !== null && full.costPerAcceptedUsd > 0 ? optimized.costPerAcceptedUsd <= full.costPerAcceptedUsd * 0.8 && noObservedQualityDrop ? 'target-met-in-this-sample' : 'target-not-met-in-this-sample' : 'inconclusive';
-        const report = { schemaVersion: 1, experiment: Object.values(options.config?.agents ?? {}).some(role => role.escalation) ? 'routing' : 'same-model', noExtraInvocations, mode: options.real ? 'real' : 'offline', runtimeIdentity: identity, corpusHash: fingerprint(EVALUATION_CORPUS), measurement: options.real ? 'reported-provider-usage' : 'synthetic-fixture-usage; no actual AI savings measured', monetaryTarget: 0.2, monetaryConclusion, groups, noObservedQualityDrop, promptPairs, correctionPromptTargetMet: promptPairs.length > 0 && promptPairs.every(pair => pair.reduction !== null && pair.reduction >= 0.4), sampleLimitations: 'Small descriptive paired sample; does not establish a universal quality or savings guarantee.', stopReason, reportedSpendUsd: options.real ? spend : 0, observations };
+        const report = { schemaVersion: 1, isDefinitionEvaluation: options.definition !== undefined,
+            ...(options.definition === undefined ? {} : { definitionHash: evaluatedDefinitionVersion }),
+            acceptedCases: observations.filter(row => row.independentAccepted).length,
+            allCasesAccepted: paired && observations.every(row => row.independentAccepted), experiment: Object.values(options.config?.agents ?? {}).some(role => role.escalation) ? 'routing' : 'same-model', noExtraInvocations, mode: options.real ? 'real' : 'offline', runtimeIdentity: identity, corpusHash: fingerprint(corpus), measurement: options.real ? 'reported-provider-usage' : 'synthetic-fixture-usage; no actual AI savings measured', monetaryTarget: 0.2, monetaryConclusion, groups, noObservedQualityDrop, promptPairs, correctionPromptTargetMet: promptPairs.length > 0 && promptPairs.every(pair => pair.reduction !== null && pair.reduction >= 0.4), sampleLimitations: 'Small descriptive paired sample; does not establish a universal quality or savings guarantee.', stopReason, reportedSpendUsd: options.real ? spend : 0, observations };
         mkdirSync(options.output, { recursive: true });
         writeFileSync(path.join(options.output, 'evaluation.json'), JSON.stringify(report, null, 2) + '\n');
         writeFileSync(path.join(options.output, 'evaluation.md'), `# Implementation efficiency evaluation\n\nMode: ${report.mode}. ${report.measurement}.\n\nMonetary target: 20% lower aggregate cost per independently accepted output. Conclusion: ${monetaryConclusion}.\n\n${JSON.stringify(groups, null, 2)}\n\nCorrection prompt comparison: ${JSON.stringify(promptPairs)}\n\n${observations.map(row => `- ${row.caseId}, ${row.mode}: ${row.status}; independent acceptance ${row.independentAccepted}; ${row.activeDurationMs} ms`).join('\n')}\n\n${stopReason ?? (options.real ? report.sampleLimitations : 'No paid benchmark has established monetary savings.')}\n`);

package/dist/agent-runtime/executor-types.d.ts

@@ -3,7 +3,31 @@ import type { CacheTokenUsage } from './efficiency-types.js';
 import type { GuardrailSettings } from './guardrails.js';
 export declare const DEFAULT_AGENT_TIMEOUT_MS: number;
 export declare const DEFAULT_AGENT_IDLE_TIMEOUT_MS: number;
-export type AgentRole = 'architect' | 'developer' | 'reviewer';
+export declare const BUILTIN_ROLES: readonly ["architect", "developer", "reviewer"];
+export type BuiltinAgentRole = typeof BUILTIN_ROLES[number];
+export type AgentRole = string;
+export type AgentAccess = 'read' | 'write';
+export type ArtifactAccess = 'none' | 'tasks-checkboxes' | 'all';
+export type OpenSpecSkill = 'openspec-ff-change' | 'openspec-apply-change' | 'openspec-verify-change';
+export declare const ROLE_ID: RegExp;
+export declare function isBuiltinRole(role: string): role is BuiltinAgentRole;
+export declare const BUILTIN_ROLE_POLICY: {
+    readonly architect: {
+        readonly access: "read";
+        readonly artifacts: "all";
+        readonly openspecSkill: "openspec-ff-change";
+    };
+    readonly developer: {
+        readonly access: "write";
+        readonly artifacts: "tasks-checkboxes";
+        readonly openspecSkill: "openspec-apply-change";
+    };
+    readonly reviewer: {
+        readonly access: "read";
+        readonly artifacts: "none";
+        readonly openspecSkill: "openspec-verify-change";
+    };
+};
 /** Who an observer sees acting: a pipeline role, or the FIXER stance the developer step takes on a correction round. */
 export type AgentEventRole = AgentRole | 'fixer';
 export type CliProvider = 'claude' | 'codex' | 'gemini' | 'kimi';
@@ -37,6 +61,15 @@ export interface RuntimeAgentConfig {
         effort?: string;
     };
 }
+export interface RuntimeRoleConfig extends RuntimeAgentConfig {
+    access: AgentAccess;
+    artifacts: ArtifactAccess;
+    prompt?: string;
+    openspecSkill?: OpenSpecSkill;
+}
+export interface RoleDescriptor extends RuntimeRoleConfig {
+    id: AgentRole;
+}
 export interface EfficiencyPolicy {
     schemaVersion: 1;
     contextMode?: 'full' | 'incremental';
@@ -64,7 +97,8 @@ export interface RuntimeConfig {
     efficiency?: EfficiencyPolicy;
     enabled: boolean;
     providers: RuntimeProviderConfig[];
-    agents: Record<AgentRole, RuntimeAgentConfig>;
+    agents: Record<BuiltinAgentRole, RuntimeAgentConfig>;
+    roles?: Record<AgentRole, RuntimeRoleConfig>;
     /** Optional engine for correction rounds (after a failed verification or a rejected review); unset ⇒ the developer corrects. */
     fixer?: RuntimeAgentConfig;
     limits?: {
@@ -110,6 +144,14 @@ export interface AgentEvent {
 export interface AgentRequest {
     openspec?: import('./openspec.js').OpenSpecRoleContext;
     role: AgentRole;
+    /** Optional only for backward-compatible built-in requests. Custom roles require explicit policy. */
+    access?: AgentAccess;
+    artifacts?: ArtifactAccess;
+    instructions?: 'role' | 'none';
+    nativeCommand?: {
+        id: string;
+        args?: string;
+    };
     prompt: string;
     cwd: string;
     allowedRoots: string[];
@@ -118,8 +160,9 @@ export interface AgentRequest {
     /** Local engines: private thinking on/off for this invocation (see RuntimeAgentConfig.thinking). */
     thinking?: 'on' | 'off';
     maxTurns?: number;
+    /** Total invocation limit; zero disables this timer without disabling cancellation or run budgets. */
     timeoutMs?: number;
-    /** Maximum silence from the provider; independent of the total invocation limit. */
+    /** Maximum silence from the provider; zero disables the idle timer. */
     idleTimeoutMs?: number;
     maxTokens?: number;
     maxCostUsd?: number;
@@ -157,3 +200,10 @@ export declare class AgentExecutionError extends Error {
 }
 export declare function unknownUsage(): AgentUsage;
 export declare function validateAgentRequest(request: AgentRequest): void;
+/** Resolve compatible defaults without changing the caller's frozen request. */
+export declare function requestPolicy(request: Pick<AgentRequest, 'role' | 'access' | 'artifacts' | 'instructions'>): {
+    access: AgentAccess;
+    artifacts: ArtifactAccess;
+    instructions: 'role' | 'none';
+};
+export declare function normalizeAgentRequest(request: AgentRequest): AgentRequest & ReturnType<typeof requestPolicy>;

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

@@ -1,5 +1,13 @@
 export const DEFAULT_AGENT_TIMEOUT_MS = 60 * 60_000;
 export const DEFAULT_AGENT_IDLE_TIMEOUT_MS = 15 * 60_000;
+export const BUILTIN_ROLES = ['architect', 'developer', 'reviewer'];
+export const ROLE_ID = /^[a-z][a-z0-9-]{0,63}$/;
+export function isBuiltinRole(role) { return BUILTIN_ROLES.includes(role); }
+export const BUILTIN_ROLE_POLICY = {
+    architect: { access: 'read', artifacts: 'all', openspecSkill: 'openspec-ff-change' },
+    developer: { access: 'write', artifacts: 'tasks-checkboxes', openspecSkill: 'openspec-apply-change' },
+    reviewer: { access: 'read', artifacts: 'none', openspecSkill: 'openspec-verify-change' },
+};
 export class AgentExecutionError extends Error {
     code;
     usage;
@@ -15,13 +23,21 @@ export class AgentExecutionError extends Error {
 }
 export function unknownUsage() { return { inputTokens: null, outputTokens: null, costUsd: null }; }
 export function validateAgentRequest(request) {
-    if (!['architect', 'developer', 'reviewer'].includes(request.role) || typeof request.prompt !== 'string' || !request.prompt.trim() || request.prompt.includes('\0'))
+    if (typeof request.role !== 'string' || !ROLE_ID.test(request.role) || typeof request.prompt !== 'string' || request.prompt.includes('\0') || (!request.nativeCommand && !request.prompt.trim()))
         throw new AgentExecutionError('Invalid role request', 'invalid_request');
+    const policy = requestPolicy(request);
+    if (request.nativeCommand !== undefined) {
+        const command = request.nativeCommand;
+        if (!command || typeof command !== 'object' || Array.isArray(command) || Object.keys(command).some(key => !['id', 'args'].includes(key)) || typeof command.id !== 'string' || !/^[a-z][a-z0-9:_-]{0,63}$/.test(command.id) || (command.args !== undefined && (typeof command.args !== 'string' || command.args.includes('\0'))) || request.prompt.trim() || policy.instructions !== 'none' || request.openspec)
+            throw new AgentExecutionError('Invalid native command request', 'invalid_request');
+    }
+    if (policy.instructions === 'none' && request.openspec)
+        throw new AgentExecutionError('Free prompts cannot bind role instructions', 'invalid_request');
     if (request.model !== undefined && (typeof request.model !== 'string' || !request.model.trim() || request.model.length > 256 || /^-/.test(request.model) || /[\0\r\n]/.test(request.model)))
         throw new AgentExecutionError('Invalid model identifier', 'invalid_model');
     for (const key of ['maxTurns', 'timeoutMs', 'idleTimeoutMs', 'maxTokens', 'maxCostUsd']) {
         const value = request[key];
-        if (value !== undefined && (!Number.isFinite(value) || value <= 0 || (key !== 'maxCostUsd' && !Number.isSafeInteger(value))))
+        if (value !== undefined && (!Number.isFinite(value) || (value < 0 || (value === 0 && key !== 'timeoutMs' && key !== 'idleTimeoutMs')) || (key !== 'maxCostUsd' && !Number.isSafeInteger(value))))
             throw new AgentExecutionError(`Invalid ${key}`, 'invalid_limit');
     }
     if (request.resumeSessionId !== undefined && (typeof request.resumeSessionId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/.test(request.resumeSessionId)))
@@ -31,3 +47,20 @@ export function validateAgentRequest(request) {
     if (request.signal?.aborted)
         throw new AgentExecutionError('Agent cancelled', 'aborted');
 }
+/** Resolve compatible defaults without changing the caller's frozen request. */
+export function requestPolicy(request) {
+    const legacy = isBuiltinRole(request.role) ? BUILTIN_ROLE_POLICY[request.role] : undefined;
+    const access = request.access ?? legacy?.access;
+    const artifacts = request.artifacts ?? legacy?.artifacts;
+    const instructions = request.instructions ?? (legacy ? 'role' : undefined);
+    if ((access !== 'read' && access !== 'write') || (artifacts !== 'none' && artifacts !== 'tasks-checkboxes' && artifacts !== 'all') || (instructions !== 'role' && instructions !== 'none'))
+        throw new AgentExecutionError('Explicit access, artifacts and instructions are required', 'invalid_request');
+    return { access, artifacts, instructions };
+}
+export function normalizeAgentRequest(request) {
+    validateAgentRequest(request);
+    const policy = requestPolicy(request);
+    const legacy = isBuiltinRole(request.role) ? BUILTIN_ROLE_POLICY[request.role] : undefined;
+    const unchangedBinding = request.openspec && request.openspec.role === request.role && request.openspec.access === undefined && request.openspec.artifacts === undefined && policy.access === legacy?.access && policy.artifacts === legacy?.artifacts;
+    return { ...request, ...policy, ...(request.openspec && !unchangedBinding ? { openspec: { ...request.openspec, access: policy.access, artifacts: policy.artifacts } } : {}) };
+}

package/dist/agent-runtime/executors.js

@@ -1,4 +1,4 @@
-import { AgentExecutionError, validateAgentRequest } from './executor-types.js';
+import { AgentExecutionError, normalizeAgentRequest } from './executor-types.js';
 import { validateRuntimeConfig } from './config.js';
 import { CliExecutor } from './cli-executor.js';
 import { OpenAICompatibleExecutor } from './openai-executor.js';
@@ -24,7 +24,7 @@ export class ExecutorRegistry {
     async capabilities(id, model) { return await this.get(id).capabilities?.(model) ?? unknownCapabilities('registered:' + id); }
     validateLimits(id, limits) { this.get(id).validateLimits?.(limits); }
     async execute(id, request) {
-        validateAgentRequest(request);
+        request = normalizeAgentRequest(request);
         if (request.effort !== undefined)
             assertEffortSupported(request, await this.capabilities(id, request.model));
         const result = await this.get(id).execute(request);

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

@@ -1,6 +1,8 @@
 import { type PipelineContext, type PipelineState, type VerificationCommand } from '../../pipeline/pipeline-state.js';
 import type { DesignConfidence } from './state.js';
 export declare const SLUG: RegExp;
+/** Historical target lookup, not an archive or verification receipt. */
+export declare function archivedOpenSpecChange(context: PipelineContext, change: string): string | undefined;
 export declare function object(value: unknown): Record<string, unknown>;
 /** Accepts the object wherever the model put it: bare, fenced, or surrounded by commentary. */
 export declare function parseAgentObject(text: string): Record<string, unknown>;
@@ -23,4 +25,9 @@ export declare function writeDesignConfidence(context: PipelineContext, change:
 }): void;
 /** Commands the architect proposed for repositories the configuration leaves uncovered. */
 export declare function proposedVerification(context: PipelineContext, configured: VerificationCommand[], verification: unknown): VerificationCommand[];
+/** Recoverable pinned-CLI archive for ledger-only runs; no implementation journal. */
+export declare function archiveOpenSpecChange(context: PipelineContext, change: string, adapter: {
+    directory: string;
+    beforePublish(): void;
+}, signal?: AbortSignal): Promise<void>;
 export declare function archive(context: PipelineContext, change: string, signal?: AbortSignal): Promise<void>;

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

@@ -3,7 +3,25 @@ import { randomUUID } from 'node:crypto';
 import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { checkArchive, pipelineStateDirectory, transitionPipeline, validateVerificationRequest, } from '../../pipeline/pipeline-state.js';
+import { assertProposalInScope, withScopeDefault } from '../change-scope.js';
 export const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Historical target lookup, not an archive or verification receipt. */
+export function archivedOpenSpecChange(context, change) {
+    if (!SLUG.test(change) || change.length > 64)
+        throw new Error('Invalid OpenSpec change identifier');
+    if (existsSync(artifactPath(context.artifactRoot, 'openspec/changes/' + change)))
+        return undefined;
+    const relative = 'openspec/changes/archive', directory = artifactPath(context.artifactRoot, relative);
+    if (!existsSync(directory))
+        return undefined;
+    const candidate = readdirSync(directory, { withFileTypes: true }).filter(entry => entry.isDirectory() &&
+        (entry.name === change || /^\d{4}-\d{2}-\d{2}-/.test(entry.name) && entry.name.slice(11) === change))
+        .sort((left, right) => left.name.localeCompare(right.name, 'en'))[0];
+    if (!candidate)
+        return undefined;
+    artifactPath(context.artifactRoot, relative + '/' + candidate.name);
+    return relative + '/' + candidate.name;
+}
 export function object(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         throw new Error('Expected a structured JSON object from agent');
@@ -105,14 +123,16 @@ export function proposedVerification(context, configured, verification) {
             throw new Error('Invalid proposed verification command');
         return { repositoryId: command.repositoryId, command: command.command, args: command.args, ...(typeof command.cwd === 'string' && command.cwd ? { cwd: command.cwd } : {}) };
     }).filter(command => !covered.has(command.repositoryId) && context.repositories.some(repository => repository.id === command.repositoryId));
+    for (const command of proposed)
+        assertProposalInScope(context, command, 'proposed verification command');
     if (proposed.length)
-        validateVerificationRequest(context, { kind: 'scoped', commands: proposed });
+        validateVerificationRequest(context, { kind: 'scoped', commands: proposed.map(command => withScopeDefault(context, command)) });
     return proposed;
 }
 /** Publish an archive prepared by the real CLI. The durable write set makes a
  * crash between main-spec updates recoverable without applying a delta twice. */
-async function archiveWithOpenSpec(context, change, active, signal) {
-    const directory = pipelineStateDirectory(context);
+async function archiveWithOpenSpec(context, change, active, signal, adapter) {
+    const directory = adapter?.directory ?? pipelineStateDirectory(context);
     const receipt = path.join(directory, 'openspec-archive.json');
     const files = (root, prefix = '') => {
         if (!existsSync(root))
@@ -124,7 +144,8 @@ async function archiveWithOpenSpec(context, change, active, signal) {
             return entry.isDirectory() ? files(path.join(root, entry.name), relative + '/') : [relative];
         });
     };
-    const activeHash = hash(JSON.stringify(files(active).sort().map(file => [file, readFileSync(artifactPath(active, file), 'utf8')])));
+    const treeHash = (root) => hash(JSON.stringify(files(root).sort().map(file => [file, readFileSync(artifactPath(root, file), 'utf8')])));
+    const activeHash = treeHash(active);
     let plan;
     if (existsSync(receipt))
         plan = JSON.parse(readFileSync(receipt, 'utf8'));
@@ -134,6 +155,22 @@ async function archiveWithOpenSpec(context, change, active, signal) {
             const source = artifactPath(context.artifactRoot, 'openspec');
             files(source); // Reject symlinks before copying or invoking the external CLI.
             cpSync(source, path.join(staging, 'openspec'), { recursive: true });
+            // A fork prepares its delta against checkpoint-owned main specs. Publish
+            // still compares all current preimages below; no source files are rewound.
+            const forkBase = path.join(directory, 'openspec-archive-base.json');
+            let beforeRoot = path.join(source, 'specs');
+            let sourceChange;
+            if (existsSync(forkBase)) {
+                const baseline = object(JSON.parse(readFileSync(forkBase, 'utf8')));
+                if (baseline.schemaVersion !== 1 || baseline.directory !== 'agent-workflow/openspec-base-specs' || typeof baseline.snapshot !== 'string' || !/^[a-f0-9]{64}$/.test(baseline.snapshot)
+                    || typeof baseline.sourceChange !== 'string' || baseline.sourceChange.length > 64 || !SLUG.test(baseline.sourceChange))
+                    throw new Error('Invalid fork archive baseline');
+                sourceChange = baseline.sourceChange;
+                beforeRoot = child(directory, baseline.directory);
+                files(beforeRoot);
+                rmSync(path.join(staging, 'openspec/specs'), { recursive: true, force: true });
+                cpSync(beforeRoot, path.join(staging, 'openspec/specs'), { recursive: true });
+            }
             const output = await runOpenSpec(resolveOpenSpecCli(), staging, ['archive', change, '--yes'], signal);
             const archiveRoot = path.join(staging, 'openspec/changes/archive');
             const archives = existsSync(archiveRoot) ? readdirSync(archiveRoot).filter(name => name.endsWith('-' + change)) : [];
@@ -148,20 +185,40 @@ async function archiveWithOpenSpec(context, change, active, signal) {
             const destination = 'openspec/changes/archive/' + archives[0];
             if (existsSync(artifactPath(context.artifactRoot, destination)))
                 throw new Error('OpenSpec archive destination already exists');
-            const beforeRoot = path.join(source, 'specs'), afterRoot = path.join(staging, 'openspec/specs');
+            const afterRoot = path.join(staging, 'openspec/specs');
             const names = new Set([...files(beforeRoot), ...files(afterRoot)]);
             const contents = (root, name) => existsSync(path.join(root, name)) ? readFileSync(path.join(root, name), 'utf8') : null;
-            plan = { activeHash, destination, writes: [...names].map(name => ({ path: 'openspec/specs/' + name, before: contents(beforeRoot, name), after: contents(afterRoot, name) })).filter(item => item.before !== item.after) };
+            plan = { activeHash, destination, writes: [...names].map(name => {
+                    const before = contents(beforeRoot, name);
+                    let after = contents(afterRoot, name);
+                    // Pinned OpenSpec inserts a change ID into the placeholder for a newly
+                    // created specification. Preserve that provenance during fork replay;
+                    // authored text and all byte-for-byte publication guards stay intact.
+                    if (sourceChange && before === null && after !== null)
+                        after = after.replace(`\n## Purpose\nTBD - created by archiving change ${change}. Update Purpose after archive.\n## Requirements\n`, `\n## Purpose\nTBD - created by archiving change ${sourceChange}. Update Purpose after archive.\n## Requirements\n`);
+                    return { path: 'openspec/specs/' + name, before, after };
+                }).filter(item => item.before !== item.after) };
             write(receipt, JSON.stringify(plan));
         }
         finally {
             rmSync(staging, { recursive: true, force: true });
         }
     }
-    if (plan.activeHash !== activeHash)
-        throw new Error('Reviewed artifacts changed since the OpenSpec archive was prepared');
     if (!new RegExp('^openspec/changes/archive/[0-9]{4}-[0-9]{2}-[0-9]{2}-' + change + '$').test(plan.destination))
         throw new Error('Invalid OpenSpec archive receipt');
+    if (adapter && !existsSync(active)) {
+        const archived = artifactPath(context.artifactRoot, plan.destination);
+        if (!existsSync(archived) || treeHash(archived) !== plan.activeHash || plan.writes.some(item => {
+            if (!item.path.startsWith('openspec/specs/'))
+                throw new Error('Invalid OpenSpec archive write');
+            const target = artifactPath(context.artifactRoot, item.path);
+            return (existsSync(target) ? readFileSync(target, 'utf8') : null) !== item.after;
+        }))
+            throw new Error('OpenSpec archive recovery does not match the prepared write set');
+        return;
+    }
+    if (plan.activeHash !== activeHash)
+        throw new Error('Reviewed artifacts changed since the OpenSpec archive was prepared');
     const targets = plan.writes.map(item => {
         if (!item.path.startsWith('openspec/specs/'))
             throw new Error('Invalid OpenSpec archive write');
@@ -169,16 +226,23 @@ async function archiveWithOpenSpec(context, change, active, signal) {
         const current = existsSync(target) ? readFileSync(target, 'utf8') : null;
         if (current !== item.before && current !== item.after)
             throw new Error('Main specification changed during archive; refusing to overwrite: ' + item.path);
-        return { ...item, target };
+        return { ...item, target, unchanged: current === item.after };
     });
     // The external CLI ran asynchronously; recheck the candidate and artifacts before publishing.
     signal?.throwIfAborted();
-    checkArchive(context);
+    if (treeHash(active) !== activeHash)
+        throw new Error('Reviewed artifacts changed during OpenSpec archive preparation');
+    if (adapter)
+        adapter.beforePublish();
+    else
+        checkArchive(context);
     // Validate every path and preimage before publishing the first output.
     const destination = artifactPath(context.artifactRoot, plan.destination);
     if (existsSync(destination))
         throw new Error('Archive destination already exists');
     for (const item of targets) {
+        if (item.unchanged)
+            continue;
         if (item.after === null)
             rmSync(item.target, { force: true });
         else
@@ -187,6 +251,18 @@ async function archiveWithOpenSpec(context, change, active, signal) {
     mkdirSync(path.dirname(destination), { recursive: true });
     renameSync(active, destination);
 }
+/** Recoverable pinned-CLI archive for ledger-only runs; no implementation journal. */
+export async function archiveOpenSpecChange(context, change, adapter, signal) {
+    if (!SLUG.test(change) || change.length > 64)
+        throw new Error('Invalid OpenSpec change identifier');
+    mkdirSync(adapter.directory, { recursive: true, mode: 0o700 });
+    if (lstatSync(adapter.directory).isSymbolicLink())
+        throw new Error('Refusing symlink archive adapter directory');
+    const active = artifactPath(context.artifactRoot, 'openspec/changes/' + change);
+    if (!existsSync(active) && !existsSync(path.join(adapter.directory, 'openspec-archive.json')))
+        throw new Error('OpenSpec active change does not exist');
+    await archiveWithOpenSpec(context, change, active, signal, adapter);
+}
 export async function archive(context, change, signal) {
     const state = journal(context);
     if (state.phases.archive.status !== 'done') {

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

@@ -0,0 +1,26 @@
+import type { VerificationReceipt } from '../../pipeline/pipeline-state.js';
+import type { WorkflowState } from '../workflow-types.js';
+/** One verify visit, as the convergence guard remembers it. */
+export interface VerifyOutcome {
+    at: string;
+    candidateHash: string;
+    planHash: string;
+    passed: boolean;
+    /** Normalized identity of the first failure: the command plus its output with volatile details removed. */
+    signature?: string;
+    summary?: string;
+}
+/** Verify visits since the latest explicit resume: a human continuing a blocked run grants a fresh budget, as for attempts. */
+export declare function outcomesSinceResume(history: readonly VerifyOutcome[], checkpoint: WorkflowState): VerifyOutcome[];
+/** Identity and one-line description of a failed receipt (or of a host finding that failed a green receipt). */
+export declare function describeFailure(receipt: Pick<VerificationReceipt, 'commands' | 'reason'>, roots: readonly string[], finding?: string): {
+    signature: string;
+    summary: string;
+};
+/**
+ * Why the failure just recorded (`current`, not yet in `history`) proves the
+ * correction loop is not converging, or undefined when another round can help.
+ */
+export declare function divergence(history: readonly VerifyOutcome[], current: VerifyOutcome): string | undefined;
+/** The same test for a candidate that has not been verified again yet: an unchanged failed candidate is not worth a new run. */
+export declare function unchangedFailure(history: readonly VerifyOutcome[], candidateHash: string, planHash: string): VerifyOutcome | undefined;

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

@@ -0,0 +1,62 @@
+import { fingerprint } from '../durable-store.js';
+/** Verify visits since the latest explicit resume: a human continuing a blocked run grants a fresh budget, as for attempts. */
+export function outcomesSinceResume(history, checkpoint) {
+    const resumed = [...checkpoint.events].reverse().find(event => event.type === 'workflow_resumed');
+    return history.filter(entry => !resumed || entry.at >= resumed.timestamp);
+}
+function normalized(output, roots) {
+    let text = output.replace(/\u001b\[[0-9;?]*[A-Za-z]/g, '');
+    for (const root of [...roots].sort((a, b) => b.length - a.length))
+        text = text.split(root).join('<repo>');
+    return text.split(/\r?\n/)
+        .map(line => line.replace(/\b[0-9a-f]{7,64}\b/gi, '#').replace(/\d+(?:[.,]\d+)*/g, '0').replace(/\s+/g, ' ').trim())
+        .filter(Boolean).slice(-40).join('\n');
+}
+/** The last line that says what went wrong, bounded. */
+function headline(output) {
+    const lines = output.replace(/\u001b\[[0-9;?]*[A-Za-z]/g, '').split(/\r?\n/).map(line => line.trim()).filter(Boolean);
+    const telling = [...lines].reverse().find(line => /error|fail|✕|×|not found|cannot|denied|refused|forbidden|unauthori[sz]ed/i.test(line));
+    return (telling ?? lines.at(-1) ?? '').slice(0, 300);
+}
+/** Identity and one-line description of a failed receipt (or of a host finding that failed a green receipt). */
+export function describeFailure(receipt, roots, finding) {
+    if (finding)
+        return { signature: fingerprint({ finding: normalized(finding, roots) }), summary: finding.slice(0, 300) };
+    const failed = receipt.commands.find(command => command.exitCode !== 0);
+    if (!failed)
+        return { signature: fingerprint({ reason: receipt.reason ?? 'verification failed' }), summary: receipt.reason ?? 'verification failed' };
+    const name = failed.label ?? [failed.command, ...failed.args].join(' ');
+    const detail = headline(failed.output);
+    return {
+        signature: fingerprint({ check: failed.key ?? [failed.command, ...failed.args, failed.cwd], exitCode: failed.exitCode, output: normalized(failed.output, roots) }),
+        summary: `${name} exited ${failed.exitCode}${detail ? `: ${detail}` : ''}`.slice(0, 400),
+    };
+}
+/**
+ * Why the failure just recorded (`current`, not yet in `history`) proves the
+ * correction loop is not converging, or undefined when another round can help.
+ */
+export function divergence(history, current) {
+    if (current.passed || !current.signature)
+        return undefined;
+    const cycle = history.find(entry => !entry.passed && entry.candidateHash === current.candidateHash && entry.planHash === current.planHash);
+    if (cycle)
+        return `The correction round returned the change to a state that already failed verification (${current.summary}). Running the same checks again cannot pass.`;
+    let repeats = 0;
+    for (const entry of [...history].reverse()) {
+        if (entry.passed || entry.signature !== current.signature)
+            break;
+        repeats++;
+    }
+    if (repeats >= 2)
+        return `The same verification failure survived ${repeats} correction rounds unchanged (${current.summary}). It is most likely outside what this change can fix: a pre-existing failure, another package, or the environment.`;
+    const previous = history.at(-1);
+    if (previous?.passed && history.some(entry => !entry.passed && entry.signature === current.signature)) {
+        return `A review correction brought back a verification failure that an earlier correction had fixed (${current.summary}). The review request and the checks pull in opposite directions; decide which one applies before resuming.`;
+    }
+    return undefined;
+}
+/** The same test for a candidate that has not been verified again yet: an unchanged failed candidate is not worth a new run. */
+export function unchangedFailure(history, candidateHash, planHash) {
+    return [...history].reverse().find(entry => !entry.passed && entry.candidateHash === candidateHash && entry.planHash === planHash);
+}

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

@@ -9,6 +9,8 @@ import type { CoreNodeId, CoreStateType, DeveloperRecord, VerificationRecord } f
 /** Autonomous investigation passes before a low-confidence design asks or proceeds. */
 export declare const MAX_DEEPEN_PASSES = 1;
 export interface CoreNodeDeps {
+    /** V2 presentation omits framework dispatch frames; original evidence stays complete. */
+    focusedCorrectionEvidence?: boolean;
     archiveApproved?: () => boolean;
     context: PipelineContext;
     config: RuntimeConfig;