specrails-core 6.0.1 → 6.1.0

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.d.ts

@@ -0,0 +1,23 @@
+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;
+    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;
+/** 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;
+}): ImplementationAdapter;

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

@@ -0,0 +1,176 @@
+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) {
+    const original = deps.stepContext(context);
+    const prefix = 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) => 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);
+            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: false });
+            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);
+            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),
+                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);
+        },
+        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,22 @@
+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 { 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),
+        ...openSpecPieces(bindings), ...controlPieces(bindings), assignPiece(), ...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[];

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

@@ -0,0 +1,69 @@
+import { archivedOpenSpecChange, archiveOpenSpecChange } from '../../graph/artifacts.js';
+import { OpenSpecCommandError, resolveOpenSpecCli, runOpenSpec } from '../../openspec.js';
+import { EngineError } from '../contracts.js';
+import { boundedText, json, paramsSchema, text } from './shared.js';
+const schema = paramsSchema({ change: { type: 'string', minLength: 1, maxLength: 128 }, allowArchived: { type: 'boolean' }, repositoryId: { type: 'string', minLength: 1, maxLength: 128 } }, ['change']);
+function changeId(value) {
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value) || value.length > 64)
+        throw new EngineError('invalid_arguments', 'Invalid OpenSpec change identifier');
+    return value;
+}
+export function openSpecPieces(bindings) {
+    return [{
+            descriptor: { kind: 'openspec-validate', paramsSchema: schema, outcomes: ['pass', 'fail', 'failed'], effect: 'read', 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));
+                const archived = params.allowArchived === true ? archivedOpenSpecChange(deps.context, change) : undefined;
+                if (archived)
+                    return { outcome: 'pass', output: { change, archived, skipped: true } };
+                let stdout, exited = true;
+                try {
+                    stdout = await runOpenSpec(resolveOpenSpecCli(), deps.context.artifactRoot, ['validate', change, '--strict', '--json'], context.signal);
+                }
+                catch (error) {
+                    if (!(error instanceof OpenSpecCommandError) || error.exitCode === undefined || error.exitCode < 1)
+                        throw error;
+                    stdout = error.stdout;
+                    exited = false;
+                }
+                let report;
+                try {
+                    report = JSON.parse(stdout);
+                }
+                catch {
+                    throw new EngineError('openspec_invalid_output', 'OpenSpec did not return its validation report');
+                }
+                const item = report.items?.find(entry => entry.id === change && entry.type === 'change');
+                if (!item || typeof item.valid !== 'boolean')
+                    throw new EngineError('openspec_invalid_output', 'OpenSpec validation did not report the requested change');
+                return { outcome: exited && item.valid ? 'pass' : 'fail', output: json(report) };
+            },
+        }, {
+            descriptor: { kind: 'openspec-archive', paramsSchema: schema, 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 archived = params.allowArchived === true ? archivedOpenSpecChange(deps.context, change) : undefined;
+                if (archived)
+                    return { outcome: 'next', output: { change, archived, skipped: true } };
+                try {
+                    await archiveOpenSpecChange(deps.context, change, { directory: deps.artifactDirectory(context), beforePublish: () => {
+                            if (initial !== deps.executionSnapshot(context).candidate?.hash)
+                                throw new EngineError('candidate_changed', 'Candidate changed while preparing the OpenSpec archive');
+                        } }, context.signal);
+                }
+                catch (error) {
+                    if (!(error instanceof OpenSpecCommandError) || error.exitCode === undefined || error.exitCode < 1)
+                        throw error;
+                    return { outcome: 'failed', status: 'failed', error: { code: 'openspec_command_failed', message: boundedText(error.message, 4000) },
+                        output: { change, exitCode: error.exitCode, stdout: boundedText(error.stdout) } };
+                }
+                return { outcome: 'next', output: { change, archived: true }, history: [{ id: context.frame.attemptId + ':archive', transition: context.frame.transition, attempt: context.frame.attempt, ordinal: 0, nodePath: context.frame.nodePath, text: boundedText('Archived OpenSpec change ' + change) }] };
+            },
+        }];
+}

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

@@ -0,0 +1,48 @@
+import type { PipelineContext, VerificationEvidencePort } from '../../../pipeline/pipeline-state.js';
+import type { RuntimeConfig } from '../../executor-types.js';
+import type { ExecutorRegistry } from '../../executors.js';
+import type { ProviderInvocation } from '../../efficiency-types.js';
+import type { OpenSpecRoleContext } from '../../openspec.js';
+import type { RoleStatePort } from '../../role-state.js';
+import type { WorkflowStepContext } from '../../workflow-types.js';
+import type { CandidateState, JsonValue, PieceExecutionContext, VerifiedState } from '../contracts.js';
+import type { ProjectMemory } from '../store/sqlite-store.js';
+import type { ImplementationBinding } from './implementation-binding.js';
+/** One physical attempt's durable notes; never a cache shared between providers or runs. */
+export interface PieceStatePort {
+    get(key: string): JsonValue | undefined;
+    set(key: string, value: JsonValue): void;
+}
+export interface PieceDependencies {
+    context: PipelineContext;
+    config: RuntimeConfig;
+    registry: ExecutorRegistry;
+    stepContext(context: PieceExecutionContext): WorkflowStepContext;
+    roleState(context: PieceExecutionContext): RoleStatePort;
+    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;
+    executionSnapshot(context: PieceExecutionContext): {
+        candidate: CandidateState | null;
+        verified: VerifiedState | null;
+    };
+    verification(context: PieceExecutionContext): VerificationEvidencePort;
+    /** 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;
+    /** 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>;
+    policies?: {
+        historyMaxChars?: number;
+        noProgress?: number;
+    };
+}
+/** Evaluated only at execution; catalog listing and validation are effect-free. */
+export type PieceDependencyProvider = () => PieceDependencies;

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

@@ -0,0 +1 @@
+export {};

package/dist/agent-runtime/engine/pieces/project-memory.d.ts

@@ -0,0 +1,3 @@
+import type { PieceExecutionContext } from '../contracts.js';
+/** Project notes are advisory: failure must never replay an already billed provider response. */
+export declare function advisoryMemory<T>(context: PieceExecutionContext, operation: () => Promise<T>): Promise<T | undefined>;

package/dist/agent-runtime/engine/pieces/project-memory.js

@@ -0,0 +1,13 @@
+/** Project notes are advisory: failure must never replay an already billed provider response. */
+export async function advisoryMemory(context, operation) {
+    try {
+        return await operation();
+    }
+    catch {
+        try {
+            context.progress({ type: 'span', payload: { name: 'project-memory', status: 'unavailable', nodePath: context.frame.nodePath } });
+        }
+        catch { /* Diagnostics cannot fail the node. */ }
+        return undefined;
+    }
+}

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

@@ -0,0 +1,5 @@
+import { type Piece } from '../contracts.js';
+import type { PieceDependencyProvider } from './ports.js';
+export declare function verificationSentinel(output: string): 'pass' | 'fail' | undefined;
+/** Free turns share accounting and executor protections, without adding role instructions. */
+export declare function promptPiece(bindings: PieceDependencyProvider): Piece;