specrails-core 6.0.1 → 6.2.0

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

@@ -0,0 +1,40 @@
+import { pipelineStateDirectory } from '../../../pipeline/pipeline-state.js';
+import { contentDigest } from '../canonical-json.js';
+import { EngineError } from '../contracts.js';
+/** Bind one journal to one declared implementation instance without changing backlog semantics. */
+export function deriveImplementationBinding(parent, execution, change) {
+    const { frame, state } = execution;
+    const standalone = frame.scope.id === 'root' && !frame.nodePath.includes('/') && state.$item === null;
+    let specs = parent.specs, repositories = parent.repositories;
+    if (state.$item !== null) {
+        const item = state.$item.value;
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            throw new EngineError('implementation_item_scope', 'Implementation map items must identify a frozen ticket or repository');
+        if (typeof item.path === 'string') {
+            const repository = parent.repositories.find(value => value.id === item.id && value.path === item.path);
+            if (!repository)
+                throw new EngineError('implementation_item_scope', 'Repository item is outside the frozen execution scope');
+            repositories = [repository];
+            specs = parent.specs.filter(spec => !spec.repositoryIds?.length || spec.repositoryIds.includes(repository.id)).map(spec => ({ ...spec, repositoryIds: [repository.id] }));
+        }
+        else {
+            const spec = parent.specs.find(value => String(value.id) === String(item.id));
+            if (!spec || typeof item.title !== 'string')
+                throw new EngineError('implementation_item_scope', 'Ticket item is outside the frozen execution scope');
+            specs = [spec];
+            if (spec.repositoryIds?.length)
+                repositories = parent.repositories.filter(repository => spec.repositoryIds.includes(repository.id));
+        }
+        if (!specs.length || !repositories.length)
+            throw new EngineError('implementation_item_scope', 'Implementation item has no frozen obligations or repositories');
+    }
+    const digest = contentDigest({ parentRunId: parent.runId, scopeId: frame.scope.id, nodePath: frame.nodePath }).slice(0, 24);
+    const artifact = repositories.find(repository => repository.id === parent.artifactRepositoryId) ?? repositories[0];
+    const context = standalone ? structuredClone(parent) : { ...structuredClone(parent),
+        runId: parent.runId.slice(0, 80) + '-impl-' + digest,
+        artifactRoot: artifact.id === parent.artifactRepositoryId ? parent.artifactRoot : artifact.path,
+        artifactRepositoryId: artifact.id, repositories: structuredClone(repositories), specs: structuredClone(specs),
+    };
+    return { context, change: standalone ? change : change.slice(0, 38).replace(/-+$/, '') + '-' + digest,
+        parentRunId: parent.runId, scopeId: frame.scope.id, nodePath: frame.nodePath, directory: pipelineStateDirectory(context) };
+}

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

@@ -0,0 +1,25 @@
+import type { CoreNodeId, CoreStateType } from '../../graph/state.js';
+import type { ImplementationBinding } from './implementation-binding.js';
+export interface ImplementationJournalSnapshot {
+    schemaVersion: 1;
+    bindingHash: string;
+    files: Array<{
+        area: 'journal' | 'change' | 'main-spec';
+        path: string;
+        hash: string;
+        bytes: number;
+    }>;
+    digest: string;
+}
+/** Immutable bytes precede the SQLite terminal which publishes this exact manifest. */
+export declare function captureImplementationJournal(binding: ImplementationBinding): ImplementationJournalSnapshot;
+/** Restore only checkpoint-owned objects, preserving the source and current repository files. */
+export declare function forkImplementationJournal(snapshot: ImplementationJournalSnapshot, source: ImplementationBinding, target: ImplementationBinding, reserveChange?: () => void): void;
+/** Public checkpoint projection; the caller updates the actual child namespace at its cut node. */
+export declare function projectImplementationFork(target: ImplementationBinding): {
+    next: CoreNodeId;
+    update: Partial<CoreStateType> & {
+        $next: CoreNodeId;
+        $nodeResult: null;
+    };
+};

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

@@ -0,0 +1,192 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { initializePipeline, inspectPipeline, pipelineStateDirectory, validatePipelineContext } from '../../../pipeline/pipeline-state.js';
+import { child, write } from '../../graph/artifacts.js';
+import { expandedPlanCommands, forkVerificationPlan, readVerificationPlan } from '../../verification-plan.js';
+import { contentDigest } from '../canonical-json.js';
+import { EngineError } from '../contracts.js';
+const MAX_FILES = 8192, MAX_BYTES = 256 * 1024 * 1024, MAX_MANIFEST = 1024 * 1024;
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+const objects = (binding) => child(binding.directory, 'agent-workflow/implementation-snapshots/objects');
+function fail(message) { throw new EngineError('implementation_snapshot_invalid', message); }
+function validateBinding(binding) {
+    const context = validatePipelineContext(binding.context);
+    if (path.resolve(binding.directory) !== pipelineStateDirectory(context) || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(binding.change))
+        fail('Snapshot journal binding is invalid');
+}
+function durableBlob(directory, digest, bytes) {
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const target = child(directory, digest);
+    if (existsSync(target)) {
+        if (hash(readFileSync(target)) !== digest)
+            fail('Immutable snapshot object changed');
+        return;
+    }
+    const temporary = child(directory, digest + '.' + randomUUID() + '.tmp');
+    const fd = openSync(temporary, 'wx', 0o600);
+    try {
+        writeFileSync(fd, bytes);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        renameSync(temporary, target);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+    // Windows does not support opening directories for fsync; file contents are
+    // already flushed and rename is atomic. Unix also persists the directory entry.
+    if (process.platform !== 'win32') {
+        const dir = openSync(directory, 'r');
+        try {
+            fsyncSync(dir);
+        }
+        finally {
+            closeSync(dir);
+        }
+    }
+}
+/** Immutable bytes precede the SQLite terminal which publishes this exact manifest. */
+export function captureImplementationJournal(binding) {
+    validateBinding(binding);
+    const journal = inspectPipeline(binding.context);
+    const state = JSON.parse(readFileSync(child(binding.directory, 'state.json'), 'utf8'));
+    if (state.change !== binding.change || journal.runId !== binding.context.runId)
+        fail('Snapshot does not belong to the admitted implementation');
+    const entries = [];
+    let total = 0;
+    const add = (root, relative, area) => {
+        const target = child(root, relative);
+        if (!existsSync(target))
+            return;
+        const stat = lstatSync(target);
+        if (stat.isSymbolicLink())
+            fail('Snapshot refuses symlink artifacts');
+        if (stat.isDirectory()) {
+            for (const name of readdirSync(target).sort())
+                add(root, relative + '/' + name, area);
+            return;
+        }
+        if (!stat.isFile() || entries.length >= MAX_FILES || (total += stat.size) > MAX_BYTES)
+            fail('Implementation snapshot exceeds its bounded file budget');
+        const bytes = readFileSync(target), digest = hash(bytes);
+        durableBlob(objects(binding), digest, bytes);
+        entries.push({ area, path: relative, hash: digest, bytes: bytes.length });
+    };
+    for (const relative of ['state.json', 'context.json', 'verification', 'receipts', 'openspec-archive.json', 'openspec-archive-base.json'])
+        add(binding.directory, relative, 'journal');
+    const active = child(binding.context.artifactRoot, 'openspec/changes/' + binding.change);
+    const changeRoot = existsSync(active) ? active : state.archivePath;
+    if (changeRoot && existsSync(changeRoot)) {
+        const safe = child(binding.context.artifactRoot, path.relative(binding.context.artifactRoot, changeRoot));
+        for (const name of readdirSync(safe).sort())
+            add(safe, name, 'change');
+    }
+    const mainSpecs = existsSync(child(binding.directory, 'openspec-archive-base.json'))
+        ? child(binding.directory, 'agent-workflow/openspec-base-specs')
+        : child(binding.context.artifactRoot, 'openspec/specs');
+    if (existsSync(mainSpecs))
+        for (const name of readdirSync(mainSpecs).sort())
+            add(mainSpecs, name, 'main-spec');
+    const payload = { schemaVersion: 1, bindingHash: contentDigest(binding), files: entries };
+    const snapshot = { ...payload, digest: contentDigest(payload) };
+    if (Buffer.byteLength(JSON.stringify(snapshot)) > MAX_MANIFEST)
+        fail('Implementation snapshot manifest exceeds 1 MiB');
+    return snapshot;
+}
+/** Restore only checkpoint-owned objects, preserving the source and current repository files. */
+export function forkImplementationJournal(snapshot, source, target, reserveChange) {
+    validateBinding(source);
+    validateBinding(target);
+    const { digest, ...payload } = snapshot;
+    if (snapshot.schemaVersion !== 1 || snapshot.bindingHash !== contentDigest(source) || digest !== contentDigest(payload)
+        || !Array.isArray(snapshot.files) || snapshot.files.length > MAX_FILES || Buffer.byteLength(JSON.stringify(snapshot)) > MAX_MANIFEST)
+        fail('Implementation snapshot manifest failed its identity check');
+    if (source.directory === target.directory || source.context.runId === target.context.runId || source.change === target.change)
+        fail('A fork requires new journal and change identities');
+    const targetChange = child(target.context.artifactRoot, 'openspec/changes/' + target.change);
+    if (existsSync(child(target.directory, 'state.json')) || existsSync(targetChange))
+        fail('Fork refuses to overwrite an existing implementation');
+    const files = new Map(), seen = new Set();
+    let total = 0;
+    for (const item of snapshot.files) {
+        if (!['journal', 'change', 'main-spec'].includes(item.area) || !/^[a-f0-9]{64}$/.test(item.hash) || !Number.isSafeInteger(item.bytes) || item.bytes < 0 || (total += item.bytes) > MAX_BYTES)
+            fail('Snapshot object metadata is invalid');
+        const key = item.area + '/' + item.path;
+        if (seen.has(key))
+            fail('Snapshot contains duplicate paths');
+        seen.add(key);
+        child(item.area === 'journal' ? target.directory : item.area === 'change' ? targetChange : child(target.directory, 'agent-workflow/openspec-base-specs'), item.path);
+        if (item.area === 'journal' && !/^(?:state\.json|context\.json|openspec-archive(?:-base)?\.json|verification\/.+|receipts\/.+)$/.test(item.path))
+            fail('Snapshot contains an undeclared journal artifact');
+        const bytes = readFileSync(child(objects(source), item.hash));
+        if (bytes.length !== item.bytes || hash(bytes) !== item.hash)
+            fail('Snapshot object is missing or corrupt');
+        files.set(key, bytes);
+    }
+    const stateBytes = files.get('journal/state.json');
+    if (!stateBytes)
+        fail('Snapshot has no implementation journal');
+    const state = JSON.parse(stateBytes.toString('utf8'));
+    if (state.runId !== source.context.runId || state.change !== source.change)
+        fail('Snapshot state belongs to another implementation');
+    const priorBaseline = files.get('journal/openspec-archive-base.json');
+    let sourceChange = source.change;
+    if (priorBaseline) {
+        const baseline = JSON.parse(priorBaseline.toString('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 || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(baseline.sourceChange))
+            fail('Snapshot archive baseline has invalid provenance');
+        sourceChange = baseline.sourceChange;
+    }
+    reserveChange?.();
+    const fresh = initializePipeline(target.context, target.change);
+    for (const [key, bytes] of files) {
+        if (['journal/state.json', 'journal/context.json', 'journal/openspec-archive.json', 'journal/openspec-archive-base.json', 'journal/verification/plan.json'].includes(key))
+            continue;
+        const area = key.slice(0, key.indexOf('/')), relative = key.slice(key.indexOf('/') + 1);
+        const destination = child(area === 'journal' ? target.directory : area === 'change' ? targetChange : child(target.directory, 'agent-workflow/openspec-base-specs'), relative);
+        mkdirSync(path.dirname(destination), { recursive: true, mode: 0o700 });
+        writeFileSync(destination, bytes, { flag: 'wx', mode: 0o600 });
+    }
+    const baseSpecs = child(target.directory, 'agent-workflow/openspec-base-specs');
+    mkdirSync(baseSpecs, { recursive: true, mode: 0o700 });
+    const archiveBytes = files.get('journal/openspec-archive.json');
+    if (archiveBytes) {
+        const archive = JSON.parse(archiveBytes.toString('utf8'));
+        for (const item of archive.writes) {
+            if (!item.path.startsWith('openspec/specs/'))
+                fail('Snapshot archive baseline has an invalid path');
+            const file = child(baseSpecs, item.path.slice('openspec/specs/'.length));
+            if (item.before === null)
+                rmSync(file, { force: true });
+            else
+                write(file, item.before);
+        }
+    }
+    write(child(target.directory, 'openspec-archive-base.json'), JSON.stringify({ schemaVersion: 1, snapshot: snapshot.digest, directory: 'agent-workflow/openspec-base-specs', sourceChange }) + '\n');
+    const planBytes = files.get('journal/verification/plan.json');
+    if (planBytes)
+        forkVerificationPlan(target.context, JSON.parse(planBytes.toString('utf8')), source.context);
+    const prepared = JSON.parse(readFileSync(child(target.directory, 'state.json'), 'utf8'));
+    const restored = { ...fresh, revision: state.revision + 1, updatedAt: new Date().toISOString(),
+        phases: { ...fresh.phases, architect: state.phases.architect, developer: state.phases.developer },
+        artifactExclusions: [...new Set([...state.artifactExclusions, ...fresh.artifactExclusions])],
+        ...(prepared.verificationPlan ? { verificationPlan: prepared.verificationPlan } : {}) };
+    write(child(target.directory, 'state.json'), JSON.stringify(restored) + '\n');
+    write(child(target.directory, 'agent-workflow/implementation-fork.json'), JSON.stringify({ sourceRunId: source.context.runId, sourceChange: source.change, snapshot: snapshot.digest }) + '\n');
+}
+/** Public checkpoint projection; the caller updates the actual child namespace at its cut node. */
+export function projectImplementationFork(target) {
+    validateBinding(target);
+    const inspection = inspectPipeline(target.context), plan = readVerificationPlan(target.context);
+    const next = inspection.phases.architect.status !== 'done' ? 'architect' : inspection.phases.developer.status !== 'done' ? 'developer' : 'verify';
+    return { next, update: { $next: next, $nodeResult: null, verifyResult: null, review: null, archived: null, verifyHistory: [],
+            ...(plan ? { plan: expandedPlanCommands(target.context, plan) } : {}),
+            ...(inspection.phases.architect.status !== 'done' ? { architecture: null } : {}),
+            ...(inspection.phases.developer.status !== 'done' ? { development: null } : {}) } };
+}

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

@@ -0,0 +1,27 @@
+import { CoreState, type CoreNodeId, type CoreStateType, type CoreStateUpdate } from '../../graph/state.js';
+import type { NodeResult, StepRecord, WorkflowNode, WorkflowState, WorkflowStepContext } from '../../workflow-types.js';
+import { type JsonObject, type PieceExecutionContext, type PieceResult } from '../contracts.js';
+import type { PieceDependencies } from './ports.js';
+import { type ImplementationJournalSnapshot } from './implementation-journal.js';
+/** Child graph contract; the compiler supplies the actual durable LangGraph boundaries. */
+export interface ImplementationAdapter {
+    schema: typeof CoreState;
+    nodes: Record<CoreNodeId, WorkflowNode<CoreStateType>>;
+    entry: CoreNodeId;
+    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, 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

@@ -0,0 +1,177 @@
+import path from 'node:path';
+import { existsSync } from 'node:fs';
+import { expandedPlanCommands, readVerificationPlan } from '../../verification-plan.js';
+import { bindImplementationExclusions, initializePipeline, inspectPipeline, pipelineStateDirectory } from '../../../pipeline/pipeline-state.js';
+import { resolveRoleDescriptor, roleIds } from '../../config.js';
+import { journal } from '../../graph/artifacts.js';
+import { coreNodes } from '../../graph/nodes.js';
+import { resolveReviewPolicy } from '../../graph/review-policy.js';
+import { createRoleInvoker } from '../../graph/roles.js';
+import { CORE_NODE_ORDER, CoreState } from '../../graph/state.js';
+import { prepareOpenSpec, roleOpenSpecContext } from '../../openspec.js';
+import { EngineError } from '../contracts.js';
+import { contentDigest } from '../canonical-json.js';
+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, independent = false) {
+    const original = deps.stepContext(context);
+    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;
+    return { ...original, stepId: id, checkpoint: { ...checkpoint,
+            nextStep: checkpoint.nextStep === null ? id : local(checkpoint.nextStep),
+            steps: Object.fromEntries(Object.entries(checkpoint.steps).filter(([key]) => belongs(key)).map(([key, value]) => [local(key), { ...value, id: local(value.id) }])),
+            history: checkpoint.history.filter(entry => belongs(entry.stepId)).map(entry => ({ ...entry, stepId: local(entry.stepId) })),
+            events: checkpoint.events.filter(event => !event.stepId || belongs(event.stepId)).map(event => ({ ...event, ...(event.stepId ? { stepId: local(event.stepId) } : {}) })),
+            ...(checkpoint.pendingApproval ? { pendingApproval: { ...checkpoint.pendingApproval, stepId: local(checkpoint.pendingApproval.stepId) } } : {}),
+            ...(checkpoint.pendingQuestion ? { pendingQuestion: { ...checkpoint.pendingQuestion, stepId: local(checkpoint.pendingQuestion.stepId) } } : {}),
+        }, interrupt: (request) => {
+            const value = context.interrupt({ kind: request.kind, prompt: request.kind === 'question' ? request.question : request.reason,
+                nodePath: context.frame.nodePath, scopeId: context.frame.scope.id, attemptId: context.frame.attemptId });
+            if (!value || typeof value !== 'object' || Array.isArray(value) || (request.kind === 'question' ? typeof value.answer !== 'string' : value.approved !== true))
+                throw new EngineError('invalid_resume', 'Implementation interrupt requires a matching answer or approval');
+            return value;
+        } };
+}
+/** Reuse every legacy node and quality gate; this factory never runs the legacy JSON workflow host. */
+export function createImplementationAdapter(deps, input) {
+    const { change, params } = input;
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(change) || change.length > 64)
+        throw new EngineError('invalid_arguments', 'Implementation requires an admitted OpenSpec change');
+    const config = { ...deps.config,
+        ...(params.approvalBeforeArchive === undefined ? {} : { approvalBeforeArchive: params.approvalBeforeArchive === true }),
+        ...(params.reviewPolicy ? { review: params.reviewPolicy } : {}) };
+    const attempts = params.attempts ?? config.limits?.maxAttempts ?? 3;
+    const bindings = new Map();
+    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) => {
+        const exclusions = deps.implementationExclusions?.(context);
+        if (exclusions)
+            bindImplementationExclusions(binding.context, exclusions);
+    };
+    const consent = (binding) => {
+        const pipeline = journal(binding.context);
+        return contentDigest(json({ candidate: inspectPipeline(binding.context).candidateHash, plan: pipeline.verificationPlan?.hash ?? null,
+            criteria: pipeline.acceptance?.criteria.map(({ evidence: _evidence, ...criterion }) => criterion) ?? null,
+            checks: pipeline.acceptance?.checks.map(({ evidence: _evidence, ...check }) => check) ?? null }));
+    };
+    const adapter = {
+        schema: CoreState, nodes: coreNodes(metadata), entry: 'architect',
+        async initialize(context) {
+            context.signal.throwIfAborted();
+            const binding = deps.bindImplementation(context, change, input.independent);
+            const pipeline = binding.context;
+            const state = initializePipeline(pipeline, binding.change);
+            refresh(binding, context);
+            if (state.phases.archive.status === 'done') {
+                const inspection = inspectPipeline(pipeline);
+                if (!inspection.verification.valid || !inspection.acceptance.valid || (inspection.resumePhase && !['ship', 'ci'].includes(inspection.resumePhase)))
+                    throw new EngineError('incompatible_resume', 'Archived implementation evidence changed; start a new run');
+            }
+            const directory = path.join(pipelineStateDirectory(pipeline), 'agent-workflow');
+            const prepared = prepareOpenSpec(pipeline.artifactRoot, binding.change, directory);
+            const openspec = Object.fromEntries(roleIds(config).filter(role => resolveRoleDescriptor(config, role).openspecSkill).map(role => {
+                const descriptor = resolveRoleDescriptor(config, role), provider = config.providers.find(item => item.id === descriptor.provider);
+                return [role, roleOpenSpecContext(prepared, pipeline.artifactRoot, binding.change, directory, descriptor, provider?.kind === 'cli' ? provider.cli : 'claude')];
+            }));
+            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: 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: [] };
+            }
+            return {};
+        },
+        async runNode(id, state, context) {
+            const prepared = bindings.get(context.frame.scope.id);
+            if (!prepared)
+                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, 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.
+                if (id === 'archive' && step.pending?.kind === 'approval') {
+                    step.interrupt(step.pending);
+                    const inspection = inspectPipeline(binding.context);
+                    if (inspection.verification.valid && inspection.acceptance.valid && inspection.phases.reviewer.status === 'done')
+                        prepared.archiveConsent = consent(binding);
+                    if (step.checkpoint.pendingApproval)
+                        step.checkpoint.pendingApproval.grantedAt = new Date().toISOString();
+                }
+                prepared.resumeChecked = true;
+                for (const completed of CORE_NODE_ORDER) {
+                    const record = step.checkpoint.steps[completed];
+                    if (completed === id || record?.status !== 'succeeded')
+                        continue;
+                    if (!await adapter.validateCompleted(completed, record, step.checkpoint, context)) {
+                        const update = completed === 'architect'
+                            ? { architecture: null, development: null, verifyResult: null, review: null, archived: null, plan: [] }
+                            : completed === 'verify' ? { verifyResult: null, review: null, archived: null }
+                                : completed === 'reviewer' ? { review: null, archived: null } : {};
+                        return { status: 'succeeded', next: completed, update, output: { revalidated: false, resumeFrom: completed } };
+                    }
+                }
+            }
+            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,
+                archiveApproved: () => prepared.archiveConsent !== undefined && prepared.archiveConsent === consent(binding),
+                note: (role, text) => context.progress({ type: 'agent-event', payload: { role, event: { kind: 'text', text } } }),
+                onVerificationOutput: text => context.progress({ type: 'verification-output', payload: { text } }),
+            });
+            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)
+                throw new EngineError('implementation_not_initialized', 'Implementation snapshot requires its initialized scope');
+            refresh(prepared.binding, context);
+            return captureImplementationJournal(prepared.binding);
+        },
+        async summarize(state, context) {
+            const prepared = bindings.get(instanceKey(context));
+            if (!prepared)
+                throw new EngineError('implementation_not_initialized', 'Implementation summary requires its initialized scope');
+            refresh(prepared.binding, context);
+            const inspection = inspectPipeline(prepared.binding.context), pipeline = journal(prepared.binding.context);
+            const archived = inspection.phases.archive.status === 'done' && inspection.completion.implementation === 'complete' && inspection.verification.valid && inspection.acceptance.valid;
+            const outcome = archived ? 'next' : state.review?.approved === false || state.verifyResult?.valid === false ? 'rejected' : 'failed';
+            const receipt = pipeline.verification;
+            const verified = receipt !== undefined && inspection.verification.valid && !receipt.unverifiedRepositories?.length && receipt.commands.length > 0;
+            return { outcome, ...(outcome === 'failed' ? { status: 'failed' } : {}),
+                output: json({ completion: inspection.completion, review: state.review, archived: state.archived }),
+                completion: { ok: archived, verified, reasons: inspection.completion.reasons },
+                ...(receipt ? { receipt: receiptEvidence({ ...receipt, valid: inspection.verification.valid }),
+                    verified: verified ? { receiptId: receipt.id, candidateHash: receipt.candidateHash, atTransition: context.frame.transition, revision: context.frame.transition } : null } : {}) };
+        },
+        async validateCompleted(id, record, checkpoint, context) {
+            const prepared = bindings.get(context.frame.scope.id);
+            if (!prepared)
+                throw new EngineError('implementation_not_initialized', 'Implementation validation requires its initialized scope');
+            const inspection = inspectPipeline(prepared.binding.context);
+            if (id === 'architect')
+                return inspection.phases.architect.status === 'done' && inspection.resumePhase !== 'architect';
+            const retryingArchive = checkpoint.nextStep === 'archive' && checkpoint.steps.archive?.status === 'failed';
+            if (id === 'verify' && !retryingArchive && checkpoint.status !== 'succeeded' && inspection.phases.archive.status !== 'done' && !(checkpoint.pendingApproval?.stepId === 'archive' && !checkpoint.pendingApproval.grantedAt))
+                return false;
+            if (id === 'verify')
+                return record.output?.valid !== false && inspection.verification.valid;
+            if (id === 'reviewer')
+                return inspection.phases.reviewer.status === 'done' && inspection.verification.valid && !['architect', 'developer', 'reviewer'].includes(inspection.resumePhase ?? '');
+            if (id === 'archive')
+                return inspection.phases.archive.status === 'done';
+            return true;
+        },
+    };
+    return adapter;
+}

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

@@ -0,0 +1,7 @@
+import { PieceRegistry } from '../piece-registry.js';
+import type { PieceDependencies } from './ports.js';
+export type { PieceDependencies, PieceStatePort } from './ports.js';
+/** The composition root binds effects once; definitions can only select this reviewed catalog. */
+export declare function createPieceRegistry(deps: PieceDependencies): PieceRegistry;
+/** Exactly the production descriptors and validators, without creating a host or an executor. */
+export declare function validationPieceRegistry(): PieceRegistry;

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

@@ -0,0 +1,24 @@
+import { artifactContractPiece } from './artifact-contract.js';
+import { PieceRegistry } from '../piece-registry.js';
+import { controlPieces, compositionPieces } from './control.js';
+import { deciderPiece } from './decider.js';
+import { openSpecPieces } from './openspec.js';
+import { EngineError } from '../contracts.js';
+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) {
+    return registry(() => deps);
+}
+/** Exactly the production descriptors and validators, without creating a host or an executor. */
+export function validationPieceRegistry() {
+    return registry(() => { throw new EngineError('read_only', 'Catalog registry cannot execute workflow effects'); });
+}
+function registry(bindings) {
+    return new PieceRegistry([promptPiece(bindings), roleTurnPiece(bindings), deciderPiece(bindings), verifyPiece(bindings), shellPiece(bindings),
+        artifactContractPiece(bindings), ...openSpecPieces(bindings), ...controlPieces(bindings), assignPiece(), implementationStepPiece(bindings), ...compositionPieces()]);
+}

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

@@ -0,0 +1,3 @@
+import { type Piece } from '../contracts.js';
+import type { PieceDependencyProvider } from './ports.js';
+export declare function openSpecPieces(bindings: PieceDependencyProvider): Piece[];