specrails-core 6.1.0 → 6.2.0

package/README.md

@@ -6,8 +6,8 @@
 
 The agent workflow engine behind [Specrails Desktop](https://github.com/fjpulidop/specrails-desktop). Core does two things:
 
-1. **Installs** the specrails workflow into a project for Claude Code, Codex CLI, Gemini CLI or Kimi Code: three roles (architect, developer, reviewer), the `implement` and `retry` entry points (`implement` runs one ticket or several tickets as one aggregate run) and the official OpenSpec skills.
-2. **Runs** implementations through the [programmatic agent runtime](docs/agent-runtime.md): a LangGraph workflow (architect → developer → verify → reviewer → archive) with per-role providers, deterministic verification, durable recovery and OpenAI-compatible local models.
+1. **Installs** the specrails workflow into a project for Claude Code or Codex CLI: three roles (architect, developer, reviewer), the `implement` and `retry` entry points (`implement` runs one ticket or several tickets as one aggregate run) and the official OpenSpec skills.
+2. **Executes** Desktop-owned workflow definitions through the [programmatic agent runtime](docs/agent-runtime.md): independent agent and implementation operations, per-role providers, deterministic verification, durable recovery and OpenAI-compatible local models. Desktop owns workflow composition and editable loop agents; Core retains the old builtin for saved runs.
 
 Desktop bundles a pinned Core package and owns everything around it: worktrees, commits, pull requests, backlog and the user interface. Core never ships code on its own; it prepares a reviewed candidate for the host.
 
@@ -31,7 +31,7 @@ bin/specrails-core.mjs     npm bin shim → dist/installer/cli.js
 src/installer/             CLI, framework lifecycle, provider rendering
 src/pipeline/              pipeline journal, gates and verification receipts
 src/agent-runtime/         programmatic runtime: graph, executors, compact loop, recovery
-templates/                 role definitions, workflow commands, provider settings, Kimi runner
+templates/                 role definitions, workflow commands, provider settings
 schemas/                   runtime configuration schema and fixtures
 integration-contract.json  Desktop ⇄ Core contract
 ```

package/dist/agent-runtime/change-scope.js

@@ -45,6 +45,8 @@ export function withScopeDefault(context, command) {
     if (command.cwd !== undefined)
         return command;
     const scope = context.repositories.find(repo => repo.id === command.repositoryId)?.scope;
+    if (scope && scope.length > 1)
+        throw new Error('Verification must name an explicit cwd for each selected code workspace');
     return scope?.length ? { ...command, cwd: scope[0] } : command;
 }
 /** Model-proposed checks stay inside the repository scope: they prove the change, not the whole checkout. */

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

@@ -32,7 +32,8 @@ export function buildCliInvocation(provider, request, options = {}) {
     }
     const readOnly = requestPolicy(request).access === 'read';
     // Pin the product alias; explicit IDs remain reproducible across releases.
-    const modelId = provider === 'claude' && request.model === 'opus' ? 'claude-opus-5-5' : request.model;
+    const claudeModelIds = { opus: 'claude-opus-5-5', sonnet: 'claude-sonnet-5-5' };
+    const modelId = provider === 'claude' && request.model ? claudeModelIds[request.model] ?? request.model : request.model;
     const model = modelId ? ['--model', modelId] : [];
     const extraRoots = request.allowedRoots.filter(root => root !== request.cwd);
     const resume = request.resumeSessionId;

package/dist/agent-runtime/cli.js

@@ -158,7 +158,7 @@ export async function runRuntimeCommand(flags, positionals, emit = value => proc
         emit({ type: 'runtime-api', apiVersion: RUNTIME_API_VERSION, coreVersion: CORE_PACKAGE_VERSION, runtimeIdentity: coreRuntimeIdentity(), workflowVersions: [CORE_WORKFLOW_VERSION],
             engineVersion: 2, engines: RUNTIME_ENGINES, nodeKindsVersion: NODE_KINDS_VERSION, nodeKinds: validationPieceRegistry().kinds(),
             capabilities: { openRoles: 1, scopedRecovery: 1, efficientRoleExecution: 1, reproducibleVerification: 1, implementationEfficiencyMetrics: 1, compactAgentLoop: 1, configurableGuardrails: 1, compactOutputBudget: 1, roleThinkingControl: 1, repositoryScope: 1,
-                engineV2: 1, workflowDefinitions: 1, fanOut: 1, fork: 1, forkIdempotency: 1, steeringInbox: 1 }, guardrails: GUARDRAIL_CATALOG });
+                engineV2: 1, workflowAgentSteps: 1, implementationSteps: 1, workflowDefinitions: 1, fanOut: 1, fork: 1, forkIdempotency: 1, steeringInbox: 1 }, guardrails: GUARDRAIL_CATALOG });
         return 0;
     }
     if (command === 'validate') {

package/dist/agent-runtime/engine/checkpoint/ledger.js

@@ -198,7 +198,7 @@ export class RunLedger {
         else if (result.verified) {
             const receipt = result.receipt, verified = result.verified;
             const evidence = receipt?.evidence && typeof receipt.evidence === 'object' && !Array.isArray(receipt.evidence) ? receipt.evidence : undefined;
-            if (!['verify', 'implementation'].includes(String(visit.kind)) || !receipt?.valid || receipt.scope !== 'full' || !candidate ||
+            if (!['verify', 'implementation', 'implementation-step'].includes(String(visit.kind)) || !receipt?.valid || receipt.scope !== 'full' || !candidate ||
                 !Array.isArray(evidence?.commands) || evidence.commands.length === 0 ||
                 (evidence.unverifiedRepositories !== undefined && (!Array.isArray(evidence.unverifiedRepositories) || evidence.unverifiedRepositories.length !== 0)) ||
                 verified.receiptId !== receipt.id || verified.candidateHash !== candidate.hash || verified.revision !== candidate.revision || verified.atTransition !== frame.transition) {
@@ -460,7 +460,7 @@ export class RunLedger {
     }
     sessionOwner(frame, ownerNodePath, key) {
         const owner = ownerNodePath.replace(/\/$/, '');
-        if (!key.startsWith('session:') || (owner !== '' && owner !== frame.nodePath && !frame.nodePath.startsWith(owner + '/'))) {
+        if ((!key.startsWith('session:') && !key.startsWith('contract:artifacts:') && key !== 'binding:implementation') || (owner !== '' && owner !== frame.nodePath && !frame.nodePath.startsWith(owner + '/'))) {
             throw new EngineError('piece_state_scope', 'Shared sessions require an ancestor node owner in this execution scope');
         }
         return owner;

package/dist/agent-runtime/engine/cli.js

@@ -68,7 +68,7 @@ export async function runDefinitionCommand(flags, positionals, emit) {
     if (command === 'workflows') {
         if (!positionals[1] || positionals[1] === 'list') {
             emit({ type: 'runtime-workflows', nodeKindsVersion: NODE_KINDS_VERSION, nodeKinds: validationPieceRegistry().catalog(), definitionSchema: workflowDefinitionSchema,
-                builtins: [{ id: 'specrails-implementation', version: CORE_WORKFLOW_VERSION, deprecated: false }] });
+                builtins: [{ id: 'specrails-implementation', version: CORE_WORKFLOW_VERSION, deprecated: true }] });
             return 0;
         }
         if (positionals[1] !== 'validate' || flags.stdin !== true)

package/dist/agent-runtime/engine/compiler.js

@@ -35,19 +35,21 @@ export function compileWorkflowDefinition(definition, registry, execution, optio
             const outcomes = node.kind === 'component' ? componentBody?.outputs ?? ['next', 'failed'] : registry.outcomes(node.kind, node.params);
             const branchName = '_core_map_' + id;
             const mapPredecessor = node.kind === 'join' ? Object.entries(body.nodes).find(([, value]) => value.kind === 'map' && value.ends.next === id)?.[0] : undefined;
-            const retry = { maxAttempts: node.retry?.maxAttempts ?? (piece.descriptor.requiresAI ? 2 : 1), retrySafe: effect === 'read', initialIntervalMs: node.retry?.backoffMs ?? 5000 };
+            const requiresAI = piece.descriptor.requiresAI && !(node.kind === 'implementation-step' && ['verify', 'archive'].includes(String(node.params.phase)));
+            const retry = { maxAttempts: node.retry?.maxAttempts ?? (requiresAI ? 2 : 1), retrySafe: effect === 'read', initialIntervalMs: node.retry?.backoffMs ?? 5000 };
             graph.addNode(id, async (state, config) => {
                 const info = config.executionInfo;
                 if (!info?.threadId)
                     throw new EngineError('execution_identity_missing', 'Durable definitions require public task identity and a checkpoint thread');
                 const nodePath = state.$scope.nodePathPrefix ? state.$scope.nodePathPrefix + '/' + id : id;
-                const frame = await execution.enter({ nodePath, kind: node.kind, effect, requiresAI: piece.descriptor.requiresAI,
-                    acceptsSteering: piece.descriptor.requiresAI && ['prompt', 'role-turn'].includes(node.kind) && node.params.appendSteering !== false, scope: state.$scope,
+                const frame = await execution.enter({ nodePath, kind: node.kind, effect, requiresAI,
+                    acceptsSteering: requiresAI && (['prompt', 'role-turn'].includes(node.kind) || node.kind === 'implementation-step' && !['verify', 'archive'].includes(String(node.params.phase))) && node.params.appendSteering !== false, scope: state.$scope,
                     task: { checkpointThreadId: info.threadId, checkpointId: info.checkpointId, taskCheckpointNs: info.checkpointNs, taskId: info.taskId }, retry });
                 let result;
+                let childEvidence;
                 let mapPlan;
                 try {
-                    const interpolated = interpolateParams(node.params, state.$vars);
+                    const interpolated = interpolateParams(node.params, state.$vars, state);
                     const params = node.kind === 'end' && root ? { ...interpolated, requiresVerified: interpolated.requiresVerified === true || frozen.delivery?.requiresVerified === true } : interpolated;
                     if (node.kind === 'map') {
                         const items = mapItems(params.over, state, options.collections);
@@ -82,11 +84,10 @@ export function compileWorkflowDefinition(definition, registry, execution, optio
                         const exit = completed.$exit;
                         if (!exit)
                             throw new EngineError('component_exit_missing', `Component ${nodePath} did not produce an exit`);
+                        childEvidence = { $candidate: completed.$candidate, $verified: completed.$verified };
                         result = { outcome: exit.outcome, status: exit.status, output: { outputs: completed.$outputs, completion: { ...exit.completion } },
-                            candidate: completed.$candidate ?? undefined, verified: completed.$verified, usage: completed.$usage, completion: exit.completion,
+                            usage: completed.$usage, completion: exit.completion,
                             ...(exit.error ? { error: exit.error } : {}) };
-                        if (!result.candidate)
-                            delete result.candidate;
                     }
                     else
                         result = await execution.execute(frame, effect, signal => piece.execute(params, {
@@ -129,7 +130,7 @@ export function compileWorkflowDefinition(definition, registry, execution, optio
                     result.completion = { ...result.completion, ok: false, reasons: [...new Set([...result.completion.reasons, 'unverified'])] };
                 }
                 const marker = execution.terminal(frame, result);
-                const patch = resultPatch(id, frame, marker.result, marker);
+                const patch = { ...resultPatch(id, frame, marker.result, marker), ...childEvidence };
                 if (mapPlan)
                     patch.$maps = { [id]: mapPlan };
                 if (node.kind === 'join' && mapPredecessor && state.$maps[mapPredecessor])

package/dist/agent-runtime/engine/definition-schema.d.ts

@@ -192,7 +192,7 @@ export declare const workflowDefinitionSchema: {
             readonly required: readonly ["kind", "params", "ends"];
             readonly properties: {
                 readonly kind: {
-                    readonly enum: readonly ["prompt", "role-turn", "decider", "condition", "assign", "verify", "shell", "openspec-validate", "openspec-archive", "approval", "question", "gate", "map", "join", "component", "implementation", "end"];
+                    readonly enum: readonly ["prompt", "role-turn", "decider", "condition", "assign", "verify", "shell", "openspec-validate", "openspec-archive", "approval", "question", "gate", "map", "join", "component", "implementation", "implementation-step", "artifact-contract", "end"];
                 };
                 readonly params: {
                     readonly type: "object";

package/dist/agent-runtime/engine/definition-schema.js

@@ -251,6 +251,8 @@ export const workflowDefinitionSchema = {
                         "join",
                         "component",
                         "implementation",
+                        "implementation-step",
+                        "artifact-contract",
                         "end"
                     ]
                 },

package/dist/agent-runtime/engine/definition-types.d.ts

@@ -1,5 +1,5 @@
 import type { EngineEffect, JsonObject, WorkflowBudget } from './contracts.js';
-export declare const PIECE_KINDS: readonly ["prompt", "role-turn", "decider", "condition", "assign", "verify", "shell", "openspec-validate", "openspec-archive", "approval", "question", "gate", "map", "join", "component", "implementation", "end"];
+export declare const PIECE_KINDS: readonly ["prompt", "role-turn", "decider", "condition", "assign", "verify", "shell", "artifact-contract", "openspec-validate", "openspec-archive", "approval", "question", "gate", "map", "join", "component", "implementation", "implementation-step", "end"];
 export type PieceKind = typeof PIECE_KINDS[number];
 export interface DefinitionNode {
     kind: PieceKind;

package/dist/agent-runtime/engine/definition-types.js

@@ -1,3 +1,3 @@
 export const PIECE_KINDS = ['prompt', 'role-turn', 'decider', 'condition', 'assign', 'verify', 'shell',
-    'openspec-validate', 'openspec-archive', 'approval', 'question', 'gate', 'map', 'join',
-    'component', 'implementation', 'end'];
+    'artifact-contract', 'openspec-validate', 'openspec-archive', 'approval', 'question', 'gate', 'map', 'join',
+    'component', 'implementation', 'implementation-step', 'end'];

package/dist/agent-runtime/engine/definition-validator.js

@@ -34,6 +34,7 @@ export function validateWorkflowDefinition(input, registry, roles = {}, options
             if (!Object.hasOwn(roles, role))
                 add('role_not_found', '/roles', `Role ${role} is not configured`);
         let implementations = 0;
+        let operationCount = 0;
         let writes = false;
         const successfulEnds = [];
         const bodies = definition.components ?? {};
@@ -133,6 +134,9 @@ export function validateWorkflowDefinition(input, registry, roles = {}, options
                 }
                 if (node.kind === 'implementation')
                     implementations += 1;
+                if (node.kind === 'implementation-step') {
+                    operationCount += 1;
+                }
                 if (node.kind === 'end' && node.params.outcome === 'success')
                     successfulEnds.push({ path, verified: node.params.requiresVerified === true });
                 if (node.kind === 'end' && node.params.exit !== undefined) {
@@ -173,8 +177,8 @@ export function validateWorkflowDefinition(input, registry, roles = {}, options
         inspectReferences(definition, [], '');
         for (const [name, body] of Object.entries(bodies))
             inspectReferences(body, [name], '/components/' + name);
-        if ((definition.journal === 'ledger-only' && implementations !== 0) || (definition.journal === 'implementation' && (implementations !== 1 || definition.change === 'none')))
-            add('journal_mismatch', '/journal', 'Implementation journals require exactly one implementation piece and an existing or new change');
+        if ((definition.journal === 'ledger-only' && (implementations !== 0 || operationCount > 0)) || (definition.journal === 'implementation' && ((implementations !== 1 && operationCount === 0) || (implementations > 0 && operationCount > 0) || definition.change === 'none')))
+            add('journal_mismatch', '/journal', 'Implementation journals require independent implementation steps or one legacy implementation wrapper, and an existing or new change');
         if (writes && definition.delivery?.requiresVerified !== false && definition.delivery?.requiresVerified !== true)
             for (const end of successfulEnds)
                 if (!end.verified)

package/dist/agent-runtime/engine/expressions.d.ts

@@ -7,5 +7,5 @@ export declare function boundedPattern(pattern: string): RegExp;
 /** Recursive descent over a closed grammar; no eval or executable expression callbacks. */
 export declare function parseExpression(source: string): Expression;
 export declare function validateInterpolations(value: JsonValue): void;
-export declare function interpolateParams(params: JsonObject, vars: Record<string, JsonValue>): JsonObject;
+export declare function interpolateParams(params: JsonObject, vars: Record<string, JsonValue>, state?: CoreDefinitionState): JsonObject;
 export {};

package/dist/agent-runtime/engine/expressions.js

@@ -140,21 +140,34 @@ export function parseExpression(source) {
 export function validateInterpolations(value) {
     if (typeof value === 'string') {
         const tokens = value.replaceAll('{{{{', '').match(/\{\{[^}]*\}\}/g) ?? [];
-        for (const token of tokens)
+        for (const token of tokens) {
+            if (token.startsWith('{{outputs.') && (!/^\{\{outputs\.[A-Za-z][A-Za-z0-9_.-]*\}\}$/.test(token) || token.slice(10, -2).split('.').some(part => forbiddenKeys.has(part))))
+                throw new EngineError('invalid_interpolation', 'Invalid workflow output reference');
             if (token.startsWith('{{run.') && !/^\{\{run\.[A-Za-z][A-Za-z0-9_-]*\}\}$/.test(token))
                 throw new EngineError('invalid_interpolation', `Invalid runtime variable ${token}`);
+        }
     }
     else if (Array.isArray(value))
         value.forEach(validateInterpolations);
     else if (value && typeof value === 'object')
         Object.values(value).forEach(validateInterpolations);
 }
-export function interpolateParams(params, vars) {
+export function interpolateParams(params, vars, state) {
     function resolve(value) {
         if (typeof value === 'string')
-            return value.replace(/\{\{\{\{|\{\{run\.([A-Za-z][A-Za-z0-9_-]*)\}\}/g, (token, name) => {
+            return value.replace(/\{\{\{\{|\{\{run\.([A-Za-z][A-Za-z0-9_-]*)\}\}|\{\{outputs\.([A-Za-z][A-Za-z0-9_.-]*)\}\}|\{\{history\.text\}\}/g, (token, name, output) => {
                 if (token === '{{{{')
                     return '{{';
+                if (token === '{{history.text}}')
+                    return (state?.$history ?? []).map(entry => `[${entry.nodePath}] ${entry.text}`).join('\n').slice(-32_000);
+                if (output) {
+                    if (output.split('.').some(part => forbiddenKeys.has(part)))
+                        throw new EngineError('invalid_interpolation', 'Prototype output paths are forbidden');
+                    const resolved = state ? lookup(state, '$outputs.' + output) : undefined;
+                    if (resolved === undefined)
+                        throw new EngineError('output_missing', `Workflow output ${output} is missing`);
+                    return typeof resolved === 'string' ? resolved : JSON.stringify(resolved);
+                }
                 if (!name || !Object.hasOwn(vars, name))
                     throw new EngineError('run_var_missing', `Runtime variable ${name ?? ''} is missing`);
                 const replacement = vars[name];

package/dist/agent-runtime/engine/fork.js

@@ -1,8 +1,9 @@
-import { existsSync, renameSync, rmSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, renameSync, rmSync } from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { pipelineStateDirectory, validatePipelineContext } from '../../pipeline/pipeline-state.js';
 import { createExecutorRegistry } from '../executors.js';
+import { artifactPath } from '../openspec.js';
 import { coreRuntimeIdentity } from '../core-host.js';
 import { sameRuntimeIdentity } from '../runtime-identity.js';
 import { canonicalJson, contentDigest } from './canonical-json.js';
@@ -33,6 +34,38 @@ function rebind(source, parent, change) {
     const context = validatePipelineContext({ ...source.context, runId: standalone ? parent.runId : parent.runId.slice(0, 80) + '-impl-' + digest });
     return { ...source, context, parentRunId: parent.runId, change: standalone ? change : change.slice(0, 38).replace(/-+$/, '') + '-' + digest, directory: pipelineStateDirectory(context) };
 }
+function copyActiveChange(context, source, target, allocation) {
+    const from = artifactPath(context.artifactRoot, 'openspec/changes/' + source);
+    if (!existsSync(from))
+        return; // A cut before planning has no authored artifacts yet.
+    const to = artifactPath(context.artifactRoot, 'openspec/changes/' + target);
+    if (existsSync(to))
+        throw new EngineError('run_exists', 'Fork refuses to replace an existing change');
+    allocation.reserve(to);
+    let bytes = 0, files = 0;
+    const copy = (relative) => {
+        const directory = relative ? artifactPath(from, relative) : from;
+        mkdirSync(relative ? artifactPath(to, relative) : to, { recursive: true, mode: 0o700 });
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const child = relative ? relative + '/' + entry.name : entry.name;
+            if (entry.isSymbolicLink())
+                throw new EngineError('artifact_scope_mismatch', 'Fork rejects symlinked change artifacts');
+            if (entry.isDirectory())
+                copy(child);
+            else if (entry.isFile()) {
+                const content = readFileSync(artifactPath(from, child));
+                bytes += content.length;
+                files++;
+                if (bytes > 2 * 1024 * 1024 || files > 200)
+                    throw new EngineError('output_limit', 'Fork artifacts exceed their copy limit');
+                writeFileSync(artifactPath(to, child), content, { flag: 'wx', mode: 0o600 });
+            }
+            else
+                throw new EngineError('artifact_scope_mismatch', 'Fork requires ordinary change artifacts');
+        }
+    };
+    copy('');
+}
 /** A fork publishes an independently leased historical cut; the source is opened read-only. */
 export async function forkRun(directory, options) {
     const state = patchState(options.state);
@@ -93,20 +126,27 @@ export async function forkRun(directory, options) {
         const change = request.change ? request.change.slice(0, 42).replace(/-+$/, '') + '-fork-' + contentDigest(context.runId).slice(0, 12) : undefined;
         const forkRequest = { ...request, context, ...(change ? { change } : {}) };
         const sourceBindings = destination.sqlite.prepare("SELECT * FROM piece_state WHERE key='binding:implementation'").all();
+        const genericChange = !!change && sourceBindings.length === 0 && definition.journal === 'ledger-only';
+        if (genericChange)
+            copyActiveChange(context, request.change, change, allocation);
         const restored = [];
         for (const row of sourceBindings) {
             // A completed implementation is inherited evidence. Rebinding its journal would
             // create a new candidate and repeat verified work even when the workspace is unchanged.
             const completed = destination.sqlite.prepare('SELECT 1 FROM attempts WHERE visit_id=? AND terminal_digest IS NOT NULL').get(row.visit_id);
-            if (completed)
+            const binding = JSON.parse(String(row.value_json));
+            if (completed && !binding.shared)
+                continue;
+            const childScope = binding.shared ? binding.scopeId : binding.scopeId + '/' + String(row.visit_id);
+            const results = destination.sqlite.prepare('SELECT a.output_json FROM attempts a JOIN visits v ON a.visit_id=v.visit_id WHERE a.scope_id=? AND a.output_json IS NOT NULL ORDER BY v.global_transition DESC,a.attempt DESC').all(childScope);
+            const snapshot = results.map(result => JSON.parse(String(result.output_json)).childUpdate?.journal).find(value => value !== undefined);
+            const lastOperation = results.map(result => JSON.parse(String(result.output_json))).find(result => result.childUpdate?.operationState !== undefined);
+            if (binding.shared && lastOperation?.completion?.ok)
                 continue;
-            const binding = JSON.parse(String(row.value_json)), target = rebind(binding, context, change);
+            const target = rebind(binding, context, change);
             const changeDirectory = path.join(target.context.artifactRoot, 'openspec', 'changes', target.change);
             if ((target.directory !== targetRoot && existsSync(target.directory)) || existsSync(changeDirectory))
                 throw new EngineError('run_exists', 'Fork refuses to replace an existing implementation journal or change');
-            const childScope = binding.scopeId + '/' + String(row.visit_id);
-            const results = destination.sqlite.prepare('SELECT a.output_json FROM attempts a JOIN visits v ON a.visit_id=v.visit_id WHERE a.scope_id=? AND a.output_json IS NOT NULL ORDER BY v.global_transition DESC,a.attempt DESC').all(childScope);
-            const snapshot = results.map(result => JSON.parse(String(result.output_json)).childUpdate?.journal).find(value => value !== undefined);
             if (snapshot) {
                 if (target.directory !== targetRoot)
                     allocation.reserve(target.directory);
@@ -120,7 +160,7 @@ export async function forkRun(directory, options) {
         destination.transaction('fork-rebound', () => {
             lease.assert(token);
             destination.put('runs', { ...ledger.run(), request_json: canonicalJson(forkRequest), status: 'running', completion_json: null,
-                ...(Object.keys(state).length || restored.length ? { verified_json: null } : {}) });
+                ...(Object.keys(state).length || restored.length || genericChange ? { verified_json: null } : {}) });
             for (const binding of restored)
                 destination.put('piece_state', { ...binding.row, value_json: canonicalJson(binding.target) });
             destination.put('piece_state', { run_id: context.runId, scope_id: 'root', node_path: '', key: 'lineage:fork', value_json: canonicalJson({
@@ -141,7 +181,7 @@ export async function forkRun(directory, options) {
                 heads.set(namespace, tuple);
         }
         for (const binding of restored) {
-            if (!existsSync(path.join(binding.target.directory, 'state.json')))
+            if (!existsSync(path.join(binding.target.directory, 'state.json')) || binding.source.shared)
                 continue;
             const scope = binding.source.scopeId + '/' + String(binding.row.visit_id);
             const matching = [...heads.values()].filter(tuple => tuple.checkpoint.channel_values.$scope?.id === scope && '$next' in tuple.checkpoint.channel_values);
@@ -154,11 +194,13 @@ export async function forkRun(directory, options) {
                 throw new EngineError('fork_checkpoint_missing', 'Implementation checkpoint has no unambiguous public previous node');
             await runtime.graph.updateState(tuple.config, projection.update, writer);
         }
-        if (Object.keys(state).length) {
+        if (Object.keys(state).length || genericChange) {
             const tuple = await runtime.saver.getTuple(targetConfig);
             if (!tuple)
                 throw new EngineError('fork_checkpoint_missing', 'Target checkpoint is not present in the historical cut');
             const values = tuple.checkpoint.channel_values;
+            if (genericChange)
+                state.$vars = { ...(values.$outer?.$vars ?? values.$vars), ...state.$vars, changeId: change };
             const outer = values.$outer;
             const update = outer ? { $outer: { ...outer,
                     ...(state.$vars ? { $vars: { ...outer.$vars, ...state.$vars } } : {}),

package/dist/agent-runtime/engine/graph-description.d.ts

@@ -8,7 +8,7 @@ export declare function describeDefinition(runId: string, definition: WorkflowDe
     workflowId: string;
     nodes: {
         path: string;
-        kind: "join" | "map" | "verify" | "shell" | "end" | "approval" | "question" | "prompt" | "gate" | "implementation" | "role-turn" | "decider" | "condition" | "assign" | "openspec-validate" | "openspec-archive" | "component";
+        kind: "join" | "map" | "verify" | "shell" | "end" | "approval" | "question" | "prompt" | "gate" | "implementation" | "role-turn" | "decider" | "condition" | "assign" | "openspec-validate" | "openspec-archive" | "component" | "implementation-step" | "artifact-contract";
         label: string;
     }[];
     edges: {
@@ -24,7 +24,7 @@ export declare function describeDefinition(runId: string, definition: WorkflowDe
                 nodes: {
                     component?: string | undefined;
                     id: string;
-                    kind: "join" | "map" | "verify" | "shell" | "end" | "approval" | "question" | "prompt" | "gate" | "implementation" | "role-turn" | "decider" | "condition" | "assign" | "openspec-validate" | "openspec-archive" | "component";
+                    kind: "join" | "map" | "verify" | "shell" | "end" | "approval" | "question" | "prompt" | "gate" | "implementation" | "role-turn" | "decider" | "condition" | "assign" | "openspec-validate" | "openspec-archive" | "component" | "implementation-step" | "artifact-contract";
                     label: string;
                     ends: {
                         [x: string]: string | null;
@@ -36,7 +36,7 @@ export declare function describeDefinition(runId: string, definition: WorkflowDe
         nodes: {
             component?: string | undefined;
             id: string;
-            kind: "join" | "map" | "verify" | "shell" | "end" | "approval" | "question" | "prompt" | "gate" | "implementation" | "role-turn" | "decider" | "condition" | "assign" | "openspec-validate" | "openspec-archive" | "component";
+            kind: "join" | "map" | "verify" | "shell" | "end" | "approval" | "question" | "prompt" | "gate" | "implementation" | "role-turn" | "decider" | "condition" | "assign" | "openspec-validate" | "openspec-archive" | "component" | "implementation-step" | "artifact-contract";
             label: string;
             ends: {
                 [x: string]: string | null;

package/dist/agent-runtime/engine/invocation-context.js

@@ -18,6 +18,8 @@ export function definitionNodeAt(definition, nodePath) {
 }
 export function roleAt(definition, nodePath) {
     const node = definitionNodeAt(definition, nodePath);
+    if (node?.kind === 'implementation-step')
+        return String(node.params.phase);
     if (node?.kind === 'role-turn' || node?.kind === 'decider')
         return String(node.params.roleId);
     return node?.kind === 'prompt' ? 'prompt' : nodePath.split('/').at(-1);

package/dist/agent-runtime/engine/piece-dependencies.d.ts

@@ -18,13 +18,13 @@ export declare class RunPieceDependencies implements PieceDependencies {
     private readonly definition;
     private readonly ledger;
     private readonly directory;
-    private readonly change?;
+    readonly change?: string | undefined;
     private readonly projectMemory?;
     readonly policies: PieceDependencies['policies'];
     constructor(context: PipelineContext, config: RuntimeConfig, registry: ExecutorRegistry, definition: WorkflowDefinition, ledger: RunLedger, directory: string, change?: string | undefined, projectMemory?: SqliteProjectStore | undefined);
     memory(context: PieceExecutionContext): ProjectMemory;
     private implementationBindings;
-    bindImplementation(context: PieceExecutionContext, change: string): ImplementationBinding;
+    bindImplementation(context: PieceExecutionContext, change: string, shared?: boolean): ImplementationBinding;
     private candidateScope;
     private inheritedCandidateScope;
     private candidate;
@@ -38,8 +38,12 @@ export declare class RunPieceDependencies implements PieceDependencies {
         candidate: CandidateState;
         verified: import("./contracts.js").VerifiedState | null;
     };
+    /** Write admission revokes certification; the archive may check its immutable pre-write checkpoint against a real receipt. */
+    verifiedBeforeWrite(context: PieceExecutionContext): import("./contracts.js").VerifiedState | null;
     /** Only the execution owner proposes protected candidate/receipt channels. */
     finalize(frame: AttemptFrame, result: PieceResult, effect: EngineEffect): PieceResult;
+    operationState(context: PieceExecutionContext): JsonValue | undefined;
+    artifactContracts(context: PieceExecutionContext): PieceStatePort;
     memo(context: PieceExecutionContext): PieceStatePort;
     roleState(context: PieceExecutionContext): RoleStatePort;
     stepContext(context: PieceExecutionContext): import("../workflow-types.js").WorkflowStepContext;

package/dist/agent-runtime/engine/piece-dependencies.js

@@ -42,13 +42,20 @@ export class RunPieceDependencies {
             .map(row => JSON.parse(String(row.value_json)))
             .filter(binding => binding.parentRunId === this.context.runId);
     }
-    bindImplementation(context, change) {
-        const binding = deriveImplementationBinding(this.context, context, change);
-        const previous = this.ledger.readPieceState(context.frame, 'binding:implementation');
+    bindImplementation(context, change, shared = false) {
+        const scoped = shared ? { ...context, frame: { ...context.frame, nodePath: context.frame.scope.nodePathPrefix } } : context;
+        const binding = deriveImplementationBinding(this.context, scoped, change);
+        if (shared)
+            binding.shared = true;
+        const previous = shared ? this.ledger.readScopedPieceState(context.frame, binding.nodePath, 'binding:implementation') : this.ledger.readPieceState(context.frame, 'binding:implementation');
         if (previous !== undefined && contentDigest(previous) !== contentDigest(binding))
             throw new EngineError('scope_mismatch', 'Implementation binding changed within a frozen run');
-        if (previous === undefined)
-            this.ledger.writePieceState(context.frame, 'binding:implementation', json(binding));
+        if (previous === undefined) {
+            if (shared)
+                this.ledger.writeScopedPieceState(context.frame, binding.nodePath, 'binding:implementation', json(binding));
+            else
+                this.ledger.writePieceState(context.frame, 'binding:implementation', json(binding));
+        }
         return binding;
     }
     candidateScope() {
@@ -58,6 +65,8 @@ export class RunPieceDependencies {
             ? readCandidateScope(this.context)
             : inherited ? this.inheritedCandidateScope(inherited)
                 : { context: this.context, scopeHash: contentDigest(this.context), artifactExclusions: this.change ? ['openspec/changes/' + this.change] : [] };
+        if (inherited && this.change)
+            base.artifactExclusions = [...new Set([...base.artifactExclusions, 'openspec/changes/' + this.change])];
         const bindings = this.implementationBindings(), repositoryExclusions = Object.fromEntries(Object.entries(base.repositoryExclusions ?? {}).map(([id, paths]) => [id, [...paths]]));
         for (const binding of bindings) {
             const exclusions = existsSync(path.join(binding.directory, 'state.json')) ? readCandidateScope(binding.context).artifactExclusions : ['openspec/changes/' + binding.change];
@@ -103,6 +112,17 @@ export class RunPieceDependencies {
         const candidate = snapshot.candidate?.hash === hash ? snapshot.candidate : this.candidate(context.frame.transition, Number(this.ledger.run().candidate_revision) + 1);
         return { candidate, verified: snapshot.verified?.candidateHash === hash ? snapshot.verified : null };
     }
+    /** Write admission revokes certification; the archive may check its immutable pre-write checkpoint against a real receipt. */
+    verifiedBeforeWrite(context) {
+        const verified = context.state.$verified;
+        if (!verified || verified.candidateHash !== this.fingerprint())
+            return null;
+        const receipt = this.ledger.db.get('receipts', { receipt_id: verified.receiptId });
+        if (!receipt || receipt.run_id !== this.ledger.runId || receipt.valid !== 1 || receipt.candidate_hash !== verified.candidateHash)
+            return null;
+        const evidence = JSON.parse(String(receipt.receipt_json));
+        return evidence.scope === 'full' ? verified : null;
+    }
     /** Only the execution owner proposes protected candidate/receipt channels. */
     finalize(frame, result, effect) {
         const hash = this.fingerprint(), snapshot = this.ledger.scopeSnapshot(frame.scope.id);
@@ -116,7 +136,7 @@ export class RunPieceDependencies {
         const node = definitionNodeAt(this.definition, frame.nodePath);
         const kind = node?.kind ?? this.ledger.db.get('visits', { visit_id: frame.visitId })?.kind;
         const evidence = receipt?.evidence;
-        const certifies = result.verified !== null && ['verify', 'implementation'].includes(String(kind)) && receipt?.valid && receipt.scope === 'full' && !!evidence?.commands?.length && !evidence.unverifiedRepositories?.length;
+        const certifies = result.verified !== null && ['verify', 'implementation', 'implementation-step'].includes(String(kind)) && receipt?.valid && receipt.scope === 'full' && !!evidence?.commands?.length && !evidence.unverifiedRepositories?.length;
         if (receipt?.valid && receipt.candidateHash !== hash)
             return { ...result, outcome: 'fail',
                 ...(effect === 'write' ? { candidate } : {}), verified: null,
@@ -127,6 +147,16 @@ export class RunPieceDependencies {
                 : effect === 'write' || snapshot.verified?.candidateHash !== hash ? { verified: null } : {}),
         };
     }
+    operationState(context) {
+        return [...this.ledger.scopeSnapshot(context.frame.scope.id).attempts].reverse()
+            .find(attempt => attempt.result?.childUpdate?.operationState !== undefined)?.result?.childUpdate;
+    }
+    artifactContracts(context) {
+        const owner = context.frame.scope.nodePathPrefix;
+        const keyOf = (key) => 'contract:artifacts:' + key;
+        return { get: key => this.ledger.readScopedPieceState(context.frame, owner, keyOf(key)),
+            set: (key, value) => this.ledger.writeScopedPieceState(context.frame, owner, keyOf(key), value) };
+    }
     memo(context) {
         const keyOf = (key) => 'memo:' + context.frame.visitId + ':' + key;
         return { get: key => this.ledger.readPieceState(context.frame, keyOf(key)), set: (key, value) => this.ledger.writePieceState(context.frame, keyOf(key), value) };
@@ -144,7 +174,24 @@ export class RunPieceDependencies {
             write: value => this.ledger.writeScopedPieceState(context.frame, context.frame.scope.nodePathPrefix, 'session:roles', json(value)),
         };
     }
-    stepContext(context) { return invocationStepContext(this.ledger, this.definition, context); }
+    stepContext(context) {
+        const step = invocationStepContext(this.ledger, this.definition, context);
+        if (definitionNodeAt(this.definition, context.frame.nodePath)?.kind !== 'implementation-step')
+            return step;
+        const phase = (path) => {
+            const node = definitionNodeAt(this.definition, path);
+            return node?.kind === 'implementation-step' ? String(node.params.phase) : path;
+        };
+        const checkpoint = step.checkpoint;
+        return { ...step, checkpoint: { ...checkpoint,
+                nextStep: checkpoint.nextStep ? phase(checkpoint.nextStep) : null,
+                steps: Object.fromEntries(Object.entries(checkpoint.steps).map(([key, value]) => [phase(key), { ...value, id: phase(key) }])),
+                history: checkpoint.history.map(value => ({ ...value, stepId: phase(value.stepId) })),
+                events: checkpoint.events.map(value => ({ ...value, ...(value.stepId ? { stepId: phase(value.stepId) } : {}) })),
+                ...(checkpoint.pendingApproval ? { pendingApproval: { ...checkpoint.pendingApproval, stepId: phase(checkpoint.pendingApproval.stepId) } } : {}),
+                ...(checkpoint.pendingQuestion ? { pendingQuestion: { ...checkpoint.pendingQuestion, stepId: phase(checkpoint.pendingQuestion.stepId) } } : {}),
+            } };
+    }
     settleResult(context, key, value, invocation) {
         if (!invocation.invocationId)
             throw new EngineError('invocation_mismatch', 'A response memo requires its durable invocation ID');

package/dist/agent-runtime/engine/piece-registry.d.ts

@@ -4,7 +4,7 @@ import type { DefinitionIssue, RoleCatalog } from './definition-types.js';
  * Version of the published piece catalog and observable piece behavior. Bump
  * when either changes; retained runtime packages preserve earlier semantics.
  */
-export declare const NODE_KINDS_VERSION = 5;
+export declare const NODE_KINDS_VERSION = 7;
 /** Immutable bindings supplied by Core's composition root; user definitions cannot register code. */
 export declare class PieceRegistry {
     private readonly entries;

package/dist/agent-runtime/engine/piece-registry.js

@@ -11,7 +11,7 @@ function freezeData(value) {
  * Version of the published piece catalog and observable piece behavior. Bump
  * when either changes; retained runtime packages preserve earlier semantics.
  */
-export const NODE_KINDS_VERSION = 5;
+export const NODE_KINDS_VERSION = 7;
 /** Immutable bindings supplied by Core's composition root; user definitions cannot register code. */
 export class PieceRegistry {
     entries = new Map();

package/dist/agent-runtime/engine/pieces/artifact-contract.d.ts

@@ -0,0 +1,4 @@
+import { type Piece } from '../contracts.js';
+import type { PieceDependencyProvider } from './ports.js';
+/** A reusable artifact invariant, with no agent roles, phase order or successor policy. */
+export declare function artifactContractPiece(bindings: PieceDependencyProvider): Piece;