specrails-core 6.1.0 → 6.2.0

package/dist/agent-runtime/engine/pieces/artifact-contract.js

@@ -0,0 +1,70 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { artifactPath } from '../../openspec.js';
+import { contentDigest } from '../canonical-json.js';
+import { EngineError } from '../contracts.js';
+import { idSchema, paramsSchema, text } from './shared.js';
+/** A reusable artifact invariant, with no agent roles, phase order or successor policy. */
+export function artifactContractPiece(bindings) {
+    return {
+        descriptor: { kind: 'artifact-contract', paramsSchema: paramsSchema({
+                change: { type: 'string', minLength: 1, maxLength: 128 }, contractId: idSchema, action: { enum: ['freeze', 'check'] },
+                requireCompletedTasks: { type: 'boolean' },
+            }, ['change', 'contractId', 'action']), outcomes: ['pass', 'fail', 'failed'], effect: 'read', requiresAI: false },
+        async execute(params, context) {
+            const deps = bindings(), change = text(params.change);
+            if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(change) || change.length > 64)
+                throw new EngineError('invalid_arguments', 'Invalid change identifier');
+            const store = deps.artifactContracts?.(context);
+            if (!store)
+                throw new EngineError('artifact_contract_unavailable', 'Scoped artifact contracts are not bound');
+            const directory = 'openspec/changes/' + change;
+            const files = {};
+            let bytes = 0;
+            const read = (relative) => {
+                const source = readFileSync(artifactPath(deps.context.artifactRoot, directory + '/' + relative), 'utf8');
+                bytes += Buffer.byteLength(source);
+                if (bytes > 2 * 1024 * 1024 || Object.keys(files).length >= 200)
+                    throw new EngineError('output_limit', 'Artifact contract exceeds its read limit');
+                return source;
+            };
+            try {
+                for (const name of ['proposal.md', 'design.md', 'tasks.md'])
+                    files[name] = read(name);
+                const walk = (relative) => {
+                    for (const entry of readdirSync(artifactPath(deps.context.artifactRoot, directory + '/' + relative), { withFileTypes: true })) {
+                        const child = relative + '/' + entry.name;
+                        if (entry.isSymbolicLink())
+                            throw new EngineError('artifact_scope_mismatch', 'Artifact contracts reject symlinks');
+                        if (entry.isDirectory())
+                            walk(child);
+                        else if (entry.isFile() && entry.name.endsWith('.md'))
+                            files[child] = read(child);
+                    }
+                };
+                walk('specs');
+            }
+            catch (error) {
+                if (error instanceof EngineError)
+                    throw error;
+                return { outcome: 'fail', output: { reason: 'required_artifacts_missing' } };
+            }
+            if (!Object.keys(files).some(name => name.startsWith('specs/')) || Object.values(files).some(source => !source.trim()))
+                return { outcome: 'fail', output: { reason: 'empty_artifacts' } };
+            const tasks = [...files['tasks.md'].matchAll(/^\s*[-*]\s+\[([ xX])\]\s+(.+)$/gm)];
+            if (!tasks.length)
+                return { outcome: 'fail', output: { reason: 'tasks_missing' } };
+            // Completion may change checkboxes, never the approved task descriptions.
+            files['tasks.md'] = files['tasks.md'].replace(/^(\s*[-*]\s+\[)[ xX](\]\s+)/gm, '$1 $2');
+            const fingerprint = contentDigest(files), key = text(params.contractId);
+            if (params.action === 'freeze')
+                store.set(key, { fingerprint });
+            else {
+                const frozen = store.get(key);
+                if (!frozen || frozen.fingerprint !== fingerprint)
+                    return { outcome: 'fail', output: { reason: frozen ? 'artifacts_changed' : 'contract_missing' } };
+            }
+            const incomplete = tasks.filter(task => task[1] === ' ').length;
+            return { outcome: params.requireCompletedTasks && incomplete ? 'fail' : 'pass', output: { fingerprint, tasks: tasks.length, incomplete } };
+        },
+    };
+}

package/dist/agent-runtime/engine/pieces/control.js

@@ -27,10 +27,14 @@ export function controlPieces(bindings) {
     for (const kind of ['approval', 'question', 'gate']) {
         const field = kind === 'question' ? 'text' : 'reason';
         pieces.push({
-            descriptor: { kind, paramsSchema: paramsSchema({ [field]: { ...stringSchema, minLength: 1 } }, [field]), outcomes: ['next'], effect: 'read', requiresAI: false },
+            descriptor: { kind, paramsSchema: paramsSchema({ [field]: { ...stringSchema, minLength: 1 }, bindCandidate: { type: 'boolean' }, enabled: { type: 'boolean' } }, [field]), outcomes: ['next'], effect: 'read', requiresAI: false },
             async execute(params, context) {
-                const response = context.interrupt({ kind, prompt: text(params[field]), nodePath: context.frame.nodePath, scopeId: context.frame.scope.id, attemptId: context.frame.attemptId });
-                return { outcome: 'next', output: { response }, ...(kind === 'question' ? { answers: [answerEntry(context, response)] } : {}) };
+                const memo = bindings().memo(context);
+                const bound = params.bindCandidate ? memo.get('approval-candidate') ?? bindings().executionSnapshot(context).candidate?.hash ?? null : undefined;
+                if (params.bindCandidate && memo.get('approval-candidate') === undefined)
+                    memo.set('approval-candidate', bound);
+                const response = kind === 'approval' && params.enabled === false ? { approved: true } : context.interrupt({ kind, prompt: text(params[field]), nodePath: context.frame.nodePath, scopeId: context.frame.scope.id, attemptId: context.frame.attemptId });
+                return { outcome: 'next', output: { response, ...(params.bindCandidate ? { candidateHash: bound } : {}) }, ...(kind === 'question' ? { answers: [answerEntry(context, response)] } : {}) };
             },
         });
     }

package/dist/agent-runtime/engine/pieces/implementation-binding.d.ts

@@ -1,6 +1,7 @@
 import { type PipelineContext } from '../../../pipeline/pipeline-state.js';
 import { type PieceExecutionContext } from '../contracts.js';
 export interface ImplementationBinding {
+    shared?: true;
     context: PipelineContext;
     change: string;
     parentRunId: string;

package/dist/agent-runtime/engine/pieces/implementation-step.d.ts

@@ -0,0 +1,5 @@
+import { type Piece } from '../contracts.js';
+import type { PieceDependencyProvider } from './ports.js';
+/** Outcomes are facts, not destinations. Only the host definition chooses the next node. */
+export declare const IMPLEMENTATION_STEP_OUTCOMES: readonly ["next", "incomplete", "rejected", "replan", "reverify", "rereview", "failed"];
+export declare function implementationStepPiece(bindings: PieceDependencyProvider): Piece;

package/dist/agent-runtime/engine/pieces/implementation-step.js

@@ -0,0 +1,47 @@
+import { CoreState } from '../../graph/state.js';
+import { EngineError } from '../contracts.js';
+import { createImplementationAdapter } from './implementation.js';
+import { json, paramsSchema } from './shared.js';
+/** Outcomes are facts, not destinations. Only the host definition chooses the next node. */
+export const IMPLEMENTATION_STEP_OUTCOMES = ['next', 'incomplete', 'rejected', 'replan', 'reverify', 'rereview', 'failed'];
+export function implementationStepPiece(bindings) {
+    return {
+        descriptor: { kind: 'implementation-step', paramsSchema: paramsSchema({
+                phase: { enum: ['architect', 'developer', 'fixer', 'verify', 'reviewer', 'archive'] },
+            }, ['phase']), outcomes: [...IMPLEMENTATION_STEP_OUTCOMES], effect: 'write', requiresAI: true },
+        async execute(params, context) {
+            const deps = bindings(), phase = params.phase;
+            const change = deps.change ?? context.state.$vars.changeId;
+            if (typeof change !== 'string')
+                throw new EngineError('invalid_arguments', 'Implementation operation requires a frozen change');
+            const saved = deps.operationState?.(context);
+            const resumed = [...deps.stepContext(context).checkpoint.events].reverse().find(event => event.type === 'workflow_resumed')?.timestamp ?? '';
+            const adapter = createImplementationAdapter(deps, { change, params: {}, independent: true, revalidate: saved?.operationResume !== resumed, archiveConsent: saved?.operationRunId === deps.context.runId && typeof saved.operationConsent === 'string' ? saved.operationConsent : undefined });
+            const initialized = await adapter.initialize(context);
+            const initial = { plan: [], unverifiedRepositories: [], architecture: null, development: null,
+                verifyResult: null, review: null, answers: [], deepenPasses: 0, archived: null, verifyHistory: [] };
+            const state = { ...initial, ...saved?.operationState,
+                ...(saved?.operationRunId === deps.context.runId ? {} : initialized) };
+            const response = await adapter.runNode(phase, state, context);
+            const updated = { ...state };
+            for (const [key, value] of Object.entries(response.update ?? {})) {
+                const channel = CoreState.spec[key];
+                updated[key] = channel.operator ? channel.operator(state[key], value) : value;
+            }
+            const normal = { architect: 'developer', developer: 'verify', fixer: 'verify', verify: 'reviewer', reviewer: 'archive', archive: null }[phase];
+            const next = response.next === undefined ? normal : response.next;
+            const outcome = response.status !== 'succeeded' ? 'failed' : next === normal ? 'next'
+                : next === 'architect' ? 'replan' : next === 'verify' ? 'reverify' : next === 'reviewer' ? 'rereview'
+                    : next === 'developer' ? 'incomplete' : next === 'fixer' ? 'rejected' : 'failed';
+            // The summary reads host verification receipts and acceptance, never an agent's claim.
+            const evidence = await adapter.summarize(updated, context);
+            return { outcome, status: response.status,
+                ...(response.output === undefined ? {} : { output: json({ ...((response.output && typeof response.output === 'object' && !Array.isArray(response.output)) ? response.output : { value: response.output }), phase }) }),
+                ...(response.error ? { error: { code: response.status === 'blocked' ? 'implementation_blocked' : 'implementation_failed', message: response.error } } : {}),
+                childUpdate: { operationState: json(updated), operationRunId: deps.context.runId, operationResume: resumed, operationConsent: adapter.consentSnapshot?.(context) ?? null, journal: json(adapter.snapshot(context)) },
+                ...(evidence.receipt ? { receipt: evidence.receipt, verified: phase === 'archive' && outcome === 'next' ? evidence.verified : null } : {}),
+                ...(phase === 'archive' && outcome === 'next' ? { completion: evidence.completion } : {}),
+            };
+        },
+    };
+}

package/dist/agent-runtime/engine/pieces/implementation.d.ts

@@ -11,13 +11,17 @@ export interface ImplementationAdapter {
     initialize(context: PieceExecutionContext): Promise<CoreStateUpdate>;
     runNode(id: CoreNodeId, state: CoreStateType, context: PieceExecutionContext): Promise<NodeResult<CoreStateType>>;
     snapshot(context: PieceExecutionContext): ImplementationJournalSnapshot;
+    consentSnapshot?(context: PieceExecutionContext): string | undefined;
     summarize(state: CoreStateType, context: PieceExecutionContext): Promise<PieceResult>;
     validateCompleted(id: CoreNodeId, record: StepRecord, checkpoint: WorkflowState, context: PieceExecutionContext): Promise<boolean>;
 }
 /** Scope the legacy convergence/attempt view without changing durable event attribution. */
-export declare function implementationStepContext(deps: PieceDependencies, context: PieceExecutionContext, id: CoreNodeId): WorkflowStepContext;
+export declare function implementationStepContext(deps: PieceDependencies, context: PieceExecutionContext, id: CoreNodeId, independent?: boolean): WorkflowStepContext;
 /** Reuse every legacy node and quality gate; this factory never runs the legacy JSON workflow host. */
 export declare function createImplementationAdapter(deps: PieceDependencies, input: {
     change: string;
     params: JsonObject;
+    independent?: boolean;
+    revalidate?: boolean;
+    archiveConsent?: string;
 }): ImplementationAdapter;

package/dist/agent-runtime/engine/pieces/implementation.js

@@ -15,9 +15,9 @@ import { json } from './shared.js';
 import { receiptEvidence } from './verify.js';
 import { captureImplementationJournal } from './implementation-journal.js';
 /** Scope the legacy convergence/attempt view without changing durable event attribution. */
-export function implementationStepContext(deps, context, id) {
+export function implementationStepContext(deps, context, id, independent = false) {
     const original = deps.stepContext(context);
-    const prefix = context.frame.nodePath.slice(0, -id.length);
+    const prefix = independent ? '' : context.frame.nodePath.slice(0, -id.length);
     const local = (value) => value.startsWith(prefix) ? value.slice(prefix.length) : value;
     const belongs = (value) => CORE_NODE_ORDER.includes(value) || (value.startsWith(prefix) && !value.slice(prefix.length).includes('/'));
     const checkpoint = original.checkpoint;
@@ -46,7 +46,7 @@ export function createImplementationAdapter(deps, input) {
         ...(params.reviewPolicy ? { review: params.reviewPolicy } : {}) };
     const attempts = params.attempts ?? config.limits?.maxAttempts ?? 3;
     const bindings = new Map();
-    const instanceKey = (context) => context.frame.scope.id + '/' + context.frame.visitId;
+    const instanceKey = (context) => input.independent ? context.frame.scope.id : context.frame.scope.id + '/' + context.frame.visitId;
     const metadata = { context: deps.context, config, change, attempts, policy: resolveReviewPolicy(config), openspec: {}, focusedCorrectionEvidence: true,
         invoke: (() => { throw new EngineError('implementation_not_initialized', 'Implementation metadata nodes must run through the durable adapter'); }), note() { } };
     const refresh = (binding, context) => {
@@ -64,7 +64,7 @@ export function createImplementationAdapter(deps, input) {
         schema: CoreState, nodes: coreNodes(metadata), entry: 'architect',
         async initialize(context) {
             context.signal.throwIfAborted();
-            const binding = deps.bindImplementation(context, change);
+            const binding = deps.bindImplementation(context, change, input.independent);
             const pipeline = binding.context;
             const state = initializePipeline(pipeline, binding.change);
             refresh(binding, context);
@@ -81,7 +81,7 @@ export function createImplementationAdapter(deps, input) {
             }));
             for (const role of Object.keys(openspec))
                 await deps.registry.get(resolveRoleDescriptor(config, role).provider).validateOpenSpec?.(openspec[role]);
-            bindings.set(instanceKey(context), { binding, openspec, resumeChecked: false });
+            bindings.set(instanceKey(context), { binding, openspec, resumeChecked: input.independent === true && input.revalidate === false, archiveConsent: input.archiveConsent });
             if (existsSync(path.join(directory, 'implementation-fork.json'))) {
                 const plan = readVerificationPlan(pipeline);
                 return { ...(plan ? { plan: expandedPlanCommands(pipeline, plan) } : {}), verifyResult: null, review: null, archived: null, verifyHistory: [] };
@@ -94,7 +94,7 @@ export function createImplementationAdapter(deps, input) {
                 throw new EngineError('implementation_not_initialized', 'Initialize this implementation scope before executing its child graph');
             const { binding, openspec } = prepared;
             refresh(binding, context);
-            const step = implementationStepContext(deps, context, id);
+            const step = implementationStepContext(deps, context, id, input.independent);
             if (!prepared.resumeChecked && (step.pending || step.checkpoint.events.some(event => event.type === 'workflow_resumed'))) {
                 // Collect archive consent first, then revalidate completed verification
                 // and review exactly as the legacy host does on explicit resume.
@@ -120,7 +120,7 @@ export function createImplementationAdapter(deps, input) {
                     }
                 }
             }
-            const invoke = createRoleInvoker({ context: binding.context, config, registry: deps.registry, openspec, roleState: deps.roleState(context),
+            const invoke = createRoleInvoker({ context: binding.context, config, registry: deps.registry, openspec, roleState: deps.roleState(context), propagateInterruptions: input.independent,
                 onAgentEvent: (role, event) => context.progress({ type: 'agent-event', payload: json({ role, event }) }) });
             const localConfig = { ...config, verification: config.verification.filter(command => binding.context.repositories.some(repository => repository.id === command.repositoryId)) };
             const nodes = coreNodes({ ...metadata, context: binding.context, config: localConfig, change: binding.change, openspec, invoke,
@@ -130,6 +130,7 @@ export function createImplementationAdapter(deps, input) {
             });
             return nodes[id].run(state, step);
         },
+        consentSnapshot(context) { return bindings.get(instanceKey(context))?.archiveConsent; },
         snapshot(context) {
             const prepared = bindings.get(context.frame.scope.id) ?? bindings.get(instanceKey(context));
             if (!prepared)

package/dist/agent-runtime/engine/pieces/index.js

@@ -1,3 +1,4 @@
+import { artifactContractPiece } from './artifact-contract.js';
 import { PieceRegistry } from '../piece-registry.js';
 import { controlPieces, compositionPieces } from './control.js';
 import { deciderPiece } from './decider.js';
@@ -7,6 +8,7 @@ import { promptPiece } from './prompt.js';
 import { roleTurnPiece } from './role-turn.js';
 import { shellPiece } from './shell.js';
 import { verifyPiece } from './verify.js';
+import { implementationStepPiece } from './implementation-step.js';
 import { assignPiece } from './assign.js';
 /** The composition root binds effects once; definitions can only select this reviewed catalog. */
 export function createPieceRegistry(deps) {
@@ -18,5 +20,5 @@ export function validationPieceRegistry() {
 }
 function registry(bindings) {
     return new PieceRegistry([promptPiece(bindings), roleTurnPiece(bindings), deciderPiece(bindings), verifyPiece(bindings), shellPiece(bindings),
-        ...openSpecPieces(bindings), ...controlPieces(bindings), assignPiece(), ...compositionPieces()]);
+        artifactContractPiece(bindings), ...openSpecPieces(bindings), ...controlPieces(bindings), assignPiece(), implementationStepPiece(bindings), ...compositionPieces()]);
 }

package/dist/agent-runtime/engine/pieces/openspec.js

@@ -42,12 +42,18 @@ export function openSpecPieces(bindings) {
                 return { outcome: exited && item.valid ? 'pass' : 'fail', output: json(report) };
             },
         }, {
-            descriptor: { kind: 'openspec-archive', paramsSchema: schema, outcomes: ['next', 'failed'], effect: 'write', requiresAI: false },
+            descriptor: { kind: 'openspec-archive', paramsSchema: { ...schema, properties: { ...schema.properties, requiresVerified: { type: 'boolean' }, reviewedCandidate: { type: 'string' }, approvedCandidate: { type: 'string' } } }, outcomes: ['next', 'failed'], effect: 'write', requiresAI: false },
             async execute(params, context) {
                 const deps = bindings();
                 if (params.repositoryId !== undefined && params.repositoryId !== deps.context.artifactRepositoryId)
                     throw new EngineError('artifact_scope_mismatch', 'OpenSpec repository must match the frozen artifact repository');
-                const change = changeId(text(params.change)), initial = deps.executionSnapshot(context).candidate?.hash;
+                const snapshot = deps.executionSnapshot(context);
+                const verified = snapshot.verified ?? deps.verifiedBeforeWrite?.(context);
+                if (params.requiresVerified && (!snapshot.candidate || !verified || verified.candidateHash !== snapshot.candidate.hash))
+                    return { outcome: 'failed', output: { reason: 'unverified' } };
+                if ([params.reviewedCandidate, params.approvedCandidate].some(hash => hash !== undefined && hash !== snapshot.candidate?.hash))
+                    return { outcome: 'failed', output: { reason: 'candidate_changed' } };
+                const change = changeId(text(params.change)), initial = snapshot.candidate?.hash;
                 const archived = params.allowArchived === true ? archivedOpenSpecChange(deps.context, change) : undefined;
                 if (archived)
                     return { outcome: 'next', output: { change, archived, skipped: true } };

package/dist/agent-runtime/engine/pieces/ports.d.ts

@@ -15,15 +15,18 @@ export interface PieceStatePort {
 }
 export interface PieceDependencies {
     context: PipelineContext;
+    readonly change?: string;
     config: RuntimeConfig;
     registry: ExecutorRegistry;
     stepContext(context: PieceExecutionContext): WorkflowStepContext;
     roleState(context: PieceExecutionContext): RoleStatePort;
+    artifactContracts?(context: PieceExecutionContext): PieceStatePort;
     memo(context: PieceExecutionContext): PieceStatePort;
     /** Narrow project memory is restricted by the declared piece and namespace capability. */
     memory(context: PieceExecutionContext): ProjectMemory;
     /** Provider settlement and the response needed for interrupt replay share one transaction. */
     settleResult(context: PieceExecutionContext, key: string, value: JsonValue, invocation: ProviderInvocation): void;
+    verifiedBeforeWrite?(context: PieceExecutionContext): VerifiedState | null;
     executionSnapshot(context: PieceExecutionContext): {
         candidate: CandidateState | null;
         verified: VerifiedState | null;
@@ -32,13 +35,15 @@ export interface PieceDependencies {
     /** A scoped adapter directory for recoverable OpenSpec write sets, never state.json. */
     artifactDirectory(context: PieceExecutionContext): string;
     /** Registers parent-owned scoped journals for candidate inspection, recovery and fork. */
-    bindImplementation(context: PieceExecutionContext, change: string): ImplementationBinding;
+    bindImplementation(context: PieceExecutionContext, change: string, shared?: boolean): ImplementationBinding;
     /** Current union of declared implementation artifacts and journals, including the parent run. */
     implementationExclusions?(context: PieceExecutionContext): {
         runtimeExclusions: readonly string[];
         repositoryExclusions: Readonly<Record<string, readonly string[]>>;
     };
     openspec?(context: PieceExecutionContext): Record<string, OpenSpecRoleContext>;
+    /** Committed private operation state, inaccessible to workflow variables or fork patches. */
+    operationState?(context: PieceExecutionContext): JsonValue | undefined;
     policies?: {
         historyMaxChars?: number;
         noProgress?: number;

package/dist/agent-runtime/engine/pieces/prompt.js

@@ -5,7 +5,7 @@ import { contentDigest } from '../canonical-json.js';
 import { EngineError } from '../contracts.js';
 import { answerEntry, boundedText, captures, captureSchema, historyEntry, json, paramsSchema, invocationTimers, stringSchema, text } from './shared.js';
 const sessionFailures = new Set(['session_not_found', 'session_expired', 'session_unsupported']);
-const engineSchema = paramsSchema({ provider: { type: 'string', minLength: 1, maxLength: 128 }, model: { type: 'string', minLength: 1, maxLength: 256 }, effort: { type: 'string', minLength: 1, maxLength: 64 }, thinking: { enum: ['on', 'off'] } }, ['provider']);
+const engineSchema = paramsSchema({ provider: { type: 'string', minLength: 1, maxLength: 128 }, model: { type: 'string', minLength: 1, maxLength: 256 }, effort: { type: 'string', minLength: 1, maxLength: 64 }, thinking: { enum: ['on', 'off'] }, maxTurns: { type: 'integer', minimum: 1 } }, ['provider']);
 const promptSchema = {
     ...paramsSchema({ engine: engineSchema, text: { ...stringSchema, minLength: 1 }, nativeCommand: paramsSchema({ id: { type: 'string', pattern: '^[a-z][a-z0-9:_-]{0,63}$' }, args: stringSchema }, ['id']),
         access: { enum: ['read', 'write'] }, sentinel: { enum: ['verification', 'blocked', 'none'] }, captureVars: captureSchema,
@@ -58,7 +58,7 @@ export function promptPiece(bindings) {
                         prompt: native ? '' : text(params.text) + suffix,
                         ...(native ? { nativeCommand: { id: native.id, args: (native.args ?? '') + suffix } } : {}),
                         cwd: deps.context.artifactRoot, allowedRoots: deps.context.repositories.map(repo => repo.path),
-                        model: engine.model, effort: engine.effort, thinking: engine.thinking,
+                        model: engine.model, effort: engine.effort, thinking: engine.thinking, maxTurns: engine.maxTurns,
                         timeoutMs: params.timeoutMs ?? deps.config.limits?.timeoutMs,
                         idleTimeoutMs: params.idleTimeoutMs ?? deps.config.limits?.idleTimeoutMs,
                         signal: context.signal, resumeSessionId: sessionId,

package/dist/agent-runtime/engine/pieces/role-turn.js

@@ -68,6 +68,6 @@ export async function executeRoleTurn(deps, params, context, options = {}) {
             await memory.put(['review', 'notes'], finalKey, { roleId, candidateHash: before?.hash ?? null,
                 text: boundedText(result.text, 4000), lastAttemptId: context.frame.attemptId });
     });
-    return { outcome: 'next', output: { text: boundedText(result.text), ...(result.value ? { structured: json(result.value) } : {}) },
+    return { outcome: 'next', output: { candidateHash: deps.executionSnapshot(context).candidate?.hash ?? null, text: boundedText(result.text), ...(result.value ? { structured: json(result.value) } : {}) },
         history: [historyEntry(context, result.text)], ...(params.sessionContinuity !== 'none' && session ? { session: { sessionId: session.sessionId, identity: session.identity } } : {}) };
 }

package/dist/agent-runtime/engine/pieces/verify.js

@@ -2,7 +2,39 @@ import { contentDigest } from '../canonical-json.js';
 import { advisoryMemory } from './project-memory.js';
 import { executeVerification, validateVerificationRequest } from '../../../pipeline/pipeline-state.js';
 import { withScopeDefault } from '../../change-scope.js';
-import { json, paramsSchema, positiveInteger } from './shared.js';
+import { boundedText, json, paramsSchema, positiveInteger } from './shared.js';
+/** Keep real subprocess diagnostics in committed outputs for subsequent agents.
+ * The full command evidence remains in the receipt; prioritize failed checks
+ * when the output budget is exhausted. */
+function verificationDiagnostics(receipt) {
+    let remaining = 32_000;
+    const outputs = new Map();
+    const priority = receipt.commands.map((command, index) => ({ command, index }))
+        .sort((a, b) => Number(b.command.exitCode !== 0) - Number(a.command.exitCode !== 0));
+    for (const { command, index } of priority) {
+        const output = command.output.slice(-Math.min(8_000, remaining));
+        // slice(-0) would include all the original text.
+        outputs.set(index, remaining > 0 ? output : '');
+        remaining -= remaining > 0 ? output.length : 0;
+    }
+    let budget = 64_000;
+    const commands = [];
+    for (const { index, command } of priority) {
+        const output = outputs.get(index) ?? '';
+        const args = command.args.slice(0, 16).map(arg => boundedText(arg, 128));
+        const diagnostic = { repositoryId: command.repositoryId, command: boundedText(command.command, 512),
+            args, cwd: boundedText(command.cwd, 512),
+            exitCode: command.exitCode, durationMs: command.durationMs, output,
+            truncated: output.length < command.output.length || command.outputTruncated === true
+                || command.command.length > 512 || command.cwd.length > 512 || command.args.length > 16 || command.args.some(arg => arg.length > 128) };
+        const size = JSON.stringify(diagnostic).length;
+        if (size > budget)
+            break;
+        budget -= size;
+        commands.push(diagnostic);
+    }
+    return { commands, ...(commands.length < receipt.commands.length ? { omittedCommands: receipt.commands.length - commands.length } : {}) };
+}
 export const verificationCommandSchema = paramsSchema({
     repositoryId: { type: 'string', minLength: 1, maxLength: 128 }, command: { type: 'string', minLength: 1, maxLength: 4096 },
     args: { type: 'array', maxItems: 1024, items: { type: 'string', maxLength: 32_000 } }, cwd: { type: 'string', maxLength: 4096 },
@@ -19,10 +51,28 @@ export function verificationDeadline(deps, context) {
 export function verifyPiece(bindings) {
     return {
         descriptor: { kind: 'verify', paramsSchema: paramsSchema({ commands: { oneOf: [{ const: 'configured' }, { type: 'array', maxItems: 100, items: verificationCommandSchema }] },
-                unverified: { type: 'boolean' }, maxConcurrency: { type: 'integer', minimum: 1, maximum: 4 } }, ['commands']), outcomes: ['pass', 'fail', 'failed'], effect: 'write', requiresAI: false, storeAccess: 'write' },
+                additionalCommandsFrom: { type: 'string', minLength: 1, maxLength: 128 }, unverified: { type: 'boolean' }, maxConcurrency: { type: 'integer', minimum: 1, maximum: 4 } }, ['commands']), outcomes: ['pass', 'fail', 'failed'], effect: 'write', requiresAI: false, storeAccess: 'write' },
         async execute(params, context) {
             const deps = bindings();
             const commands = (params.commands === 'configured' ? deps.config.verification : params.commands).map(command => withScopeDefault(deps.context, command));
+            const hostRepositories = new Set(commands.map(command => command.repositoryId));
+            if (typeof params.additionalCommandsFrom === 'string') {
+                const source = context.state.$outputs[params.additionalCommandsFrom];
+                const proposals = source?.structured?.verification;
+                if (!Array.isArray(proposals) || proposals.length > 20)
+                    throw new Error('Verification proposals must be a bounded array from a committed agent output');
+                // Host checks always stay mandatory. The same scoped command validation
+                // applies to these actual subprocesses and to configured checks below.
+                for (const proposal of proposals) {
+                    if (!proposal || typeof proposal !== 'object' || Array.isArray(proposal))
+                        throw new Error('Invalid verification proposal');
+                    const raw = proposal;
+                    if (!deps.context.repositories.some(repository => repository.id === raw.repositoryId))
+                        throw new Error('Unknown verification repository');
+                    if (!hostRepositories.has(raw.repositoryId))
+                        commands.push(withScopeDefault(deps.context, raw));
+                }
+            }
             const coversAll = deps.context.repositories.every(repository => commands.some(command => command.repositoryId === repository.id));
             const request = { kind: coversAll || params.unverified === true ? 'full' : 'scoped', commands, ...(params.unverified === true ? { unverified: true } : {}) };
             validateVerificationRequest(deps.context, request);
@@ -45,7 +95,7 @@ export function verifyPiece(bindings) {
             const outcome = infrastructure ? 'failed' : receipt.valid ? 'pass' : 'fail';
             const verified = receipt.valid && receipt.commands.length > 0 && !receipt.unverifiedRepositories?.length;
             return { outcome, ...(infrastructure ? { status: 'failed', error: { code: 'verification_execution_error', message: receipt.reason ?? 'A verification command could not complete' } } : {}),
-                output: { receiptId: receipt.id, valid: receipt.valid, ...(receipt.reason ? { reason: receipt.reason } : {}), commands: receipt.commands.map(command => ({ repositoryId: command.repositoryId, command: command.command, exitCode: command.exitCode })) },
+                output: { receiptId: receipt.id, valid: receipt.valid, ...(receipt.reason ? { reason: receipt.reason } : {}), ...verificationDiagnostics(receipt) },
                 receipt: receiptEvidence(receipt), ...(verified ? { verified: { receiptId: receipt.id, candidateHash: receipt.candidateHash, atTransition: context.frame.transition, revision: context.frame.transition } } : { verified: null }) };
         },
     };

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

@@ -42,6 +42,8 @@ export interface RoleInvokerDeps {
     openspec?: Record<AgentRole, import('../openspec.js').OpenSpecRoleContext>;
     /** Engine hosts isolate sessions/routes by scope and node instead of a role-global file. */
     roleState?: RoleStatePort;
+    /** Durable independent operations must recover uncertain effects explicitly. */
+    propagateInterruptions?: boolean;
     /** `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

@@ -192,6 +192,8 @@ export function createRoleInvoker(deps) {
             }
         }
         catch (error) {
+            if (deps.propagateInterruptions && error instanceof AgentExecutionError && ['aborted', 'timeout', 'idle_timeout', 'lease_lost'].includes(error.code))
+                throw error;
             return { ok: false, error: error instanceof Error ? error.message : String(error), ...(error instanceof AgentExecutionError ? { code: error.code } : {}) };
         }
     };

package/dist/agent-runtime/prompts.js

@@ -152,7 +152,7 @@ function architectSection(verification, definition) {
             '2. Decide the approach, name the exact files/modules to create or change (inside the repository scope when one is declared), and call out risks, edge cases and compatibility concerns. Plan only the change the requested work needs; unrelated clean-ups are out of scope.',
             '3. Break the work into ordered, atomic tasks. Each task names concrete files and includes its own tests. Every task must be completable by an agent that can only edit files and run commands: never add tasks such as "run the test suite", "verify", "test manually in a browser", "commit" or "open a PR". Core runs verification and the host owns delivery.',
             '4. Execute the official OpenSpec fast-forward skill. Query status and instructions in dependency order; author the real delta specs and other artifacts using those templates and project rules. Preserve existing requirements through OpenSpec delta semantics. Do not fabricate complete replacement specs.',
-            '5. Propose verification. For each repository listed below without a configured verification command, name the existing command that proves the change: the project\'s test script, type check, build or lint (for example `npm` with args `["test"]`, or `cargo` with `["test"]`). Only propose commands that exist in the repository today or that a task in this plan adds; omit repositories where nothing automated applies. For a repository with a scope, the command must exercise that scope: omit cwd (it then runs in the scope directory) or name a directory inside it; never a command that runs every workspace of a larger checkout. Core runs them after the developer finishes and feeds failures back.',
+            '5. Propose verification. For each repository listed below without a configured verification command, name the existing command that proves the change: the project\'s test script, type check, build or lint (for example `npm` with args `["test"]`, or `cargo` with `["test"]`). Only propose commands that exist in the repository today or that a task in this plan adds; omit repositories where nothing automated applies. For a repository with a scope, the command must exercise that scope: omit cwd for a single scope (it then runs there), or name a directory inside it; for multiple code workspaces, propose a separate command with an explicit cwd for each selected workspace; never a command that runs every workspace of a larger checkout. Core runs them after the developer finishes and feeds failures back.',
             '6. Score your confidence honestly: `high` when the code evidence is conclusive; `medium` when the design rests on one non-obvious assumption (name it in the design); `low` when several plausible designs exist and you cannot choose without missing information. With `low`, put the single question whose answer decides the design in `question`. Core first lets you investigate further, then either asks the requester that exact question or proceeds on your stated assumptions, depending on the project configuration.',
             '',
         ] : [definition, '']),

package/dist/pipeline/pipeline-state.js

@@ -814,6 +814,8 @@ function validateCommand(context, raw) {
     const cwd = command.cwd === undefined ? directory(repositoryWorkingDirectory(repo)) : directory(path.resolve(repo.path, String(command.cwd)));
     if (!within(repo.path, cwd))
         fail('Verification cwd escapes selected repository');
+    if (!withinRepositoryScope(repo, path.relative(repo.path, cwd).split(path.sep).join('/')))
+        fail('Verification cwd escapes selected code workspace');
     const env = command.env === undefined ? undefined : object(command.env);
     if (env && Object.values(env).some((value) => typeof value !== 'string' || value.includes('\0')))
         fail('Invalid verification environment');

package/integration-contract.json

@@ -116,14 +116,14 @@
     "file": ".specrails/install-config.yaml",
     "version": 1,
     "fields": {
-      "version": "number — schema version, currently 1",
-      "provider": "string — claude | codex | gemini | kimi",
+      "version": "number \u2014 schema version, currently 1",
+      "provider": "string \u2014 claude | codex | gemini | kimi",
       "tier": "Deprecated legacy string, tolerated and ignored; all installs use deterministic placement.",
-      "agents.selected": "string[] — unique lowercase kebab-case agent ids to install (1-64 characters)",
-      "agents.excluded": "string[] — unique lowercase kebab-case agent ids to skip; must not overlap agents.selected",
-      "models.preset": "string — balanced | budget | max; resolved within the selected provider catalog",
-      "models.defaults.model": "string — exact provider model id or configured alias (overrides preset; Kimi: 1-128 characters matching [A-Za-z0-9][A-Za-z0-9._/:-]*; default: k3)",
-      "models.overrides": "Record<safe-agent-id, string> — exact per-agent provider model ids or configured aliases with the same provider-specific validation (highest priority)"
+      "agents.selected": "string[] \u2014 unique lowercase kebab-case agent ids to install (1-64 characters)",
+      "agents.excluded": "string[] \u2014 unique lowercase kebab-case agent ids to skip; must not overlap agents.selected",
+      "models.preset": "string \u2014 balanced | budget | max; resolved within the selected provider catalog",
+      "models.defaults.model": "string \u2014 exact provider model id or configured alias (overrides preset; Kimi: 1-128 characters matching [A-Za-z0-9][A-Za-z0-9._/:-]*; default: k3)",
+      "models.overrides": "Record<safe-agent-id, string> \u2014 exact per-agent provider model ids or configured aliases with the same provider-specific validation (highest priority)"
     }
   },
   "checkpoints": {
@@ -246,7 +246,9 @@
       "signal",
       "cancel"
     ],
-    "cliPresentationOperations": ["help"],
+    "cliPresentationOperations": [
+      "help"
+    ],
     "apiOperation": "runtime api emits {type: runtime-api, apiVersion, coreVersion, runtimeIdentity, workflowVersions, engineVersion, engines, nodeKindsVersion, nodeKinds, capabilities, guardrails}; does not invoke providers",
     "validationTransport": "runtime validate --stdin accepts UTF-8 configuration JSON up to 2 MiB, mutually exclusive with --config",
     "compactStatus": "runtime status --compact omits workflow history, events and outputs, frozen pipeline context and verification command output; retains identities (runId, traceId), phase statuses and visits, pendingApproval, pendingQuestion, usage, completion, acceptance summary and verification metadata",
@@ -296,11 +298,14 @@
     "documentation": "docs/agent-runtime.md",
     "instructionsVersion": "10",
     "workflowVersion": "7",
-    "engines": [1, 2],
+    "engines": [
+      1,
+      2
+    ],
     "engine": {
       "version": 2,
       "definitionSchema": "schemas/workflow-definition.schema.json",
-      "nodeKindsVersion": 5
+      "nodeKindsVersion": 7
     },
     "nodeKinds": [
       "prompt",
@@ -308,6 +313,7 @@
       "decider",
       "verify",
       "shell",
+      "artifact-contract",
       "openspec-validate",
       "openspec-archive",
       "condition",
@@ -316,15 +322,25 @@
       "question",
       "gate",
       "assign",
+      "implementation-step",
       "component",
       "map",
       "implementation",
       "join"
     ],
+    "implementationSteps": {
+      "version": 1,
+      "kind": "implementation-step",
+      "ownership": "Host definitions compose phases and freeze role definitions; Core executes individual operations and evidence gates"
+    },
     "engineStatePath": "<backlogRoot>/.specrails/pipeline/<runId>/agent-workflow/run.sqlite",
     "frozenRequest": "agent-runtime-request.json carries workflow {id, version, source: builtin|definition, definitionHash, engine: 1|2}; resume and status select the engine from workflow.engine and a request without the block is a legacy (engine 1) run",
     "builtins": [
-      { "id": "specrails-implementation", "version": "7", "deprecated": false }
+      {
+        "id": "specrails-implementation",
+        "version": "7",
+        "deprecated": true
+      }
     ],
     "developerTools": "The developer role runs with each CLI's autonomous edit+shell mode (claude --tools default --dangerously-skip-permissions with Agent/Task/Skill disallowed; codex workspace-write; gemini --yolo; kimi print mode). Architect and reviewer stay read-only. Claude roles load project settings only (--setting-sources project,local).",
     "verificationPolicy": "Configured commands are optional. The architect proposes commands for repositories without one; repositories with no automated check are admitted and recorded in the receipt as unverifiedRepositories. Unchecked tasks return to the developer as feedback instead of failing the run.",
@@ -356,12 +372,16 @@
       ],
       "customAgentLoop": "free",
       "nativeCommandUnsupported": "native_command_unsupported"
+    },
+    "workflowAgentSteps": {
+      "version": 1,
+      "ownership": "Host-defined roles, schemas and gates; Core provides scoped artifact contracts and verified candidate guards"
     }
   },
   "execution": {
     "schemaVersion": 1,
     "contextEnv": "SPECRAILS_EXECUTION_CONTEXT",
-    "context": "Absolute JSON file: runId, backlogRoot, backlogPath?, artifactRoot, artifactRepositoryId, repositories[{id,name,path,baseSha?,scope?}], ownership{git,backlog,worktrees:host|core}, specs[{id,title,description,repositoryIds?,acceptanceCriteria?}]. scope (runtime capability repositoryScope) lists the checkout-relative directories a repository is confined to — a package registered inside a larger checkout: commands without cwd run in the first one, model-proposed checks stay inside it, edits outside it are undone after each developer/fixer turn and reviews judge the git change set against the run base.",
+    "context": "Absolute JSON file: runId, backlogRoot, backlogPath?, artifactRoot, artifactRepositoryId, repositories[{id,name,path,baseSha?,scope?}], ownership{git,backlog,worktrees:host|core}, specs[{id,title,description,repositoryIds?,acceptanceCriteria?}]. scope (runtime capability repositoryScope) lists the checkout-relative directories a repository is confined to \u2014 a package registered inside a larger checkout: commands without cwd run in the first one, model-proposed checks stay inside it, edits outside it are undone after each developer/fixer turn and reviews judge the git change set against the run base.",
     "runtime": ".specrails/runtime/pipeline.mjs",
     "operations": [
       "init",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "specrails-core",
-  "version": "6.1.0",
-  "description": "Agent workflow engine for specrails-desktop: provider-independent installer and programmatic agent runtime for Claude Code, Codex, Gemini CLI and Kimi Code",
+  "version": "6.2.0",
+  "description": "Agent workflow engine for specrails-desktop: provider-independent installer and programmatic agent runtime for Claude Code and Codex",
   "type": "module",
   "exports": {
     "./agent-runtime": {

package/schemas/workflow-definition.schema.json

@@ -250,6 +250,8 @@
             "join",
             "component",
             "implementation",
+            "implementation-step",
+            "artifact-contract",
             "end"
           ]
         },