specrails-core 6.6.5 → 6.7.0

package/dist/agent-runtime/session/drivers/executor/driver.js

@@ -19,6 +19,8 @@ export function executorDescriptor(id, displayName) {
             autonomousContinuation: false,
             steer: false,
             toolFiltering: false,
+            // No turn-level stop that keeps a session: abort the invocation, then run the input next.
+            interrupt: 'emulated',
             usage: Object.freeze({ costUsd: 'per-turn', tokens: 'per-turn' }),
         }),
     });

package/dist/agent-runtime/session/host/protocol.d.ts

@@ -1,6 +1,18 @@
 import { type ValidateFunction } from 'ajv/dist/2020.js';
 /** Protocol versions this host speaks (docs/agent-sessions/protocol.md). */
 export declare const SESSION_PROTOCOL_VERSIONS: readonly number[];
+/** `session.send` deliveries this host accepts (mirrored into integration-contract.json). */
+export declare const SESSION_DELIVERIES: readonly ["queue", "steer", "interrupt"];
+/**
+ * Capabilities `initialize` advertises (mirrored into integration-contract.json).
+ * `delegation`: session.delegate / session.waitSubagents and subagentRuntime.mode 'delegated'.
+ * `flowSessions`: session.send delivery 'interrupt' and per-driver capabilities.interrupt.
+ */
+export declare const SESSION_HOST_CAPABILITIES: Readonly<{
+    readonly sessions: 1;
+    readonly delegation: 1;
+    readonly flowSessions: 1;
+}>;
 /** Longest accepted request line. */
 export declare const MAX_FRAME_BYTES: number;
 type Schema = Record<string, unknown>;

package/dist/agent-runtime/session/host/protocol.js

@@ -1,6 +1,14 @@
 import { Ajv2020 } from 'ajv/dist/2020.js';
 /** Protocol versions this host speaks (docs/agent-sessions/protocol.md). */
 export const SESSION_PROTOCOL_VERSIONS = Object.freeze([1]);
+/** `session.send` deliveries this host accepts (mirrored into integration-contract.json). */
+export const SESSION_DELIVERIES = Object.freeze(['queue', 'steer', 'interrupt']);
+/**
+ * Capabilities `initialize` advertises (mirrored into integration-contract.json).
+ * `delegation`: session.delegate / session.waitSubagents and subagentRuntime.mode 'delegated'.
+ * `flowSessions`: session.send delivery 'interrupt' and per-driver capabilities.interrupt.
+ */
+export const SESSION_HOST_CAPABILITIES = Object.freeze({ sessions: 1, delegation: 1, flowSessions: 1 });
 /** Longest accepted request line. */
 export const MAX_FRAME_BYTES = 2 * 1024 * 1024;
 const id = { type: 'string', minLength: 1, maxLength: 200 };
@@ -20,7 +28,7 @@ const mcpServer = {
 };
 const limits = {
     type: 'object', additionalProperties: false,
-    properties: Object.fromEntries(['idleMs', 'stallMs', 'backgroundMaxMs', 'turnInactivityMs', 'maxSettleHandoffs', 'settleDebounceMs'].map((key) => [key, { type: 'integer', minimum: 0 }])),
+    properties: Object.fromEntries(['idleMs', 'stallMs', 'backgroundMaxMs', 'turnInactivityMs', 'toolInactivityMs', 'maxSettleHandoffs', 'settleDebounceMs'].map((key) => [key, { type: 'integer', minimum: 0 }])),
 };
 const policy = {
     type: 'object', additionalProperties: false, required: ['subagents'],
@@ -58,7 +66,7 @@ export const METHOD_SCHEMAS = Object.freeze({
         },
         oneOf: [{ required: ['resume'] }, { required: ['driver', 'model', 'cwd', 'policy'] }],
     },
-    'session.send': { type: 'object', additionalProperties: false, required: ['sessionId', 'input'], properties: { sessionId: id, input: { type: 'object', additionalProperties: false, required: ['inputId', 'text', 'delivery'], properties: { inputId: id, text, attachments: { type: 'array', maxItems: 32, items: attachment }, delivery: { enum: ['queue', 'steer'] } } } } },
+    'session.send': { type: 'object', additionalProperties: false, required: ['sessionId', 'input'], properties: { sessionId: id, input: { type: 'object', additionalProperties: false, required: ['inputId', 'text', 'delivery'], properties: { inputId: id, text, attachments: { type: 'array', maxItems: 32, items: attachment }, delivery: { enum: [...SESSION_DELIVERIES] } } } } },
     'session.interrupt': { type: 'object', additionalProperties: false, required: ['sessionId'], properties: { sessionId: id } },
     'session.stopSubagents': { type: 'object', additionalProperties: false, required: ['sessionId'], properties: { sessionId: id, subagentIds: { type: 'array', maxItems: 500, items: id } } },
     'session.delegate': { type: 'object', additionalProperties: false, required: ['sessionId', 'description', 'prompt'], properties: { sessionId: id, description: { type: 'string', minLength: 1, maxLength: 200 }, prompt: { type: 'string', minLength: 1, maxLength: 64 * 1024 }, agentType: { type: 'string', minLength: 1, maxLength: 100 }, contextTurns: { type: 'integer', minimum: 0, maximum: 10 } } },

package/dist/agent-runtime/session/host/server.js

@@ -1,6 +1,7 @@
 import { StringDecoder } from 'node:string_decoder';
 import { SessionError, isSessionError } from '../domain/errors.js';
-import { MAX_FRAME_BYTES, RPC_APPLICATION_ERROR, RPC_INVALID_PARAMS, RPC_INVALID_REQUEST, RPC_METHOD_NOT_FOUND, RPC_PARSE_ERROR, SESSION_PROTOCOL_VERSIONS, validatorFor, } from './protocol.js';
+import { redactSessionSnapshot } from '../domain/redaction.js';
+import { MAX_FRAME_BYTES, RPC_APPLICATION_ERROR, RPC_INVALID_PARAMS, RPC_INVALID_REQUEST, RPC_METHOD_NOT_FOUND, RPC_PARSE_ERROR, SESSION_HOST_CAPABILITIES, SESSION_PROTOCOL_VERSIONS, validatorFor, } from './protocol.js';
 /**
  * JSON-RPC 2.0 server over NDJSON stdio (session protocol v1).
  * One handler per method (closed table); each validates its params with a
@@ -27,7 +28,8 @@ export class SessionHost {
         const service = runtime.service;
         this.handlers = Object.freeze({
             'initialize': async (params) => this.initialize(params),
-            'session.open': async (params) => service.open(params),
+            // Live snapshots come from the in-memory session: redact them like the journal does.
+            'session.open': async (params) => { const opened = await service.open(params); return { ...opened, snapshot: redactSessionSnapshot(opened.snapshot) }; },
             'session.send': async (params) => service.send(String(params.sessionId), params.input),
             'session.interrupt': async (params) => service.interrupt(String(params.sessionId)),
             'session.delegate': async (params) => service.delegate(String(params.sessionId), {
@@ -40,7 +42,7 @@ export class SessionHost {
             'session.stopSubagents': async (params) => service.stopSubagents(String(params.sessionId), params.subagentIds),
             'session.update': async (params) => { const { sessionId, ...changes } = params; return service.update(String(sessionId), changes); },
             'session.close': async (params) => { await service.close(String(params.sessionId), String(params.reason)); return {}; },
-            'session.snapshot': async (params) => service.snapshot(String(params.sessionId)),
+            'session.snapshot': async (params) => redactSessionSnapshot(service.snapshot(String(params.sessionId))),
             'session.events': async (params) => service.events(String(params.sessionId), Number(params.afterSeq), params.limit === undefined ? undefined : Number(params.limit)),
             'session.list': async (params) => ({ sessions: service.list(params.state ?? 'open') }),
             'host.ping': async () => ({ ...service.stats(), uptimeMs: Math.round(process.uptime() * 1000) }),
@@ -159,8 +161,7 @@ export class SessionHost {
             protocolVersion: Math.max(...requested),
             scope: this.runtime.scope,
             runtime: this.runtime.identity,
-            // `delegation`: session.delegate / session.waitSubagents and subagentRuntime.mode 'delegated'.
-            capabilities: { sessions: 1, delegation: 1 },
+            capabilities: { ...SESSION_HOST_CAPABILITIES },
             drivers: this.runtime.service.drivers(),
         };
     }

package/dist/agent-runtime/session/index.d.ts

@@ -7,7 +7,7 @@ import type { Clock, DriverCatalog, Ids } from './ports.js';
 export { SessionError, isSessionError, type SessionErrorCode } from './domain/errors.js';
 export { SESSION_EVENT_TYPES, type SessionEvent, type SessionEventBody, type SessionEventEnvelope, type SessionEventType, type ToolActivity } from './domain/events.js';
 export type { SessionSnapshot, SubagentNode, TurnRecord, InputRecord, OpenTurn } from './domain/snapshot.js';
-export type { DriverCapabilities, DriverDescriptor, SessionLimits, SessionPolicy, Usage, McpServerSpec, Attachment } from './domain/types.js';
+export type { DriverCapabilities, DriverDescriptor, InputDelivery, SessionLimits, SessionPolicy, Usage, McpServerSpec, Attachment } from './domain/types.js';
 export type { SessionPolicyInput } from './domain/policy.js';
 export { DEFAULT_LIMITS } from './domain/policy.js';
 export { SessionService, type OpenParams, type SendParams } from './application/session-service.js';

package/dist/agent-runtime/session/journal/sqlite-journal.js

@@ -4,6 +4,7 @@ import { DatabaseSync } from 'node:sqlite';
 import { sessionsRoot } from '../../../shared/specrails-home.js';
 import { PersistenceError, privateSqlitePath } from '../../engine/storage/private-path.js';
 import { SessionError } from '../domain/errors.js';
+import { redactSessionEvent, redactSessionSnapshot } from '../domain/redaction.js';
 import { emptySnapshot, foldEvents } from '../domain/snapshot.js';
 import { JOURNAL_MIGRATIONS, JOURNAL_SCHEMA_VERSION } from './schema.js';
 export const JOURNAL_LEASE_MS = 60_000;
@@ -82,8 +83,11 @@ export class SqliteSessionJournal {
             const current = this.loadSnapshot(sessionId);
             if (!current)
                 throw new SessionError('session_not_found', `Unknown session ${sessionId}`);
-            const envelopes = events.map((event, index) => ({ sessionId, seq: current.lastSeq + index + 1, event }));
-            const next = foldEvents(current, envelopes);
+            // Fold the events as produced (input fingerprints must match the live
+            // session), then persist and return only redacted copies: what is
+            // stored, published and replayed is the same redacted stream.
+            const next = redactSessionSnapshot(foldEvents(current, events.map((event, index) => ({ sessionId, seq: current.lastSeq + index + 1, event }))));
+            const envelopes = events.map((event, index) => ({ sessionId, seq: current.lastSeq + index + 1, event: redactSessionEvent(event) }));
             const insert = this.db.prepare('INSERT INTO events(session_id,seq,type,at,payload_json) VALUES (?,?,?,?,?)');
             for (const envelope of envelopes)
                 insert.run(sessionId, envelope.seq, envelope.event.type, envelope.event.at, JSON.stringify(envelope.event));

package/dist/agent-runtime/session/ports.d.ts

@@ -7,7 +7,7 @@
  */
 import type { SessionEvent, SessionEventEnvelope, ToolActivity } from './domain/events.js';
 import type { SessionSnapshot } from './domain/snapshot.js';
-import type { Attachment, DriverDescriptor, OutputChannel, SessionPolicy, SubagentKind, SubagentPhase } from './domain/types.js';
+import type { Attachment, DriverDescriptor, InputDelivery, OutputChannel, SessionPolicy, SubagentKind, SubagentPhase } from './domain/types.js';
 import type { ReportedUsage, UsageBaseline } from './domain/usage.js';
 export interface DriverOpenSpec {
     sessionId: string;
@@ -25,7 +25,11 @@ export interface DriverInput {
     inputId: string;
     text: string;
     attachments?: Attachment[];
-    delivery: 'queue' | 'steer';
+    /**
+     * Drivers receive `interrupt` only when they declare a native queue and a
+     * native interrupt: they stop the running turn and put this input first.
+     */
+    delivery: InputDelivery;
     /** Set by the application for policy-driven turns (e.g. collecting settled sub-agents). */
     origin?: 'user' | 'system';
 }

package/dist/agent-runtime/session/testing/driver-conformance.js

@@ -8,12 +8,12 @@ function assert(condition, message) {
     if (!condition)
         throw new Error(`Driver conformance: ${message}`);
 }
-async function oneTurn(harness) {
+async function oneTurn(harness, delivery = 'queue') {
     const factory = harness.factory();
     const journal = new MemoryJournal();
     const service = new SessionService({ journal, drivers: catalogOf(factory), clock: new FakeClock(), ids: new SequentialIds() });
     const { sessionId } = await service.open({ driver: factory.descriptor.id, model: harness.model, cwd: process.cwd(), policy: { subagents: harness.subagents } });
-    await service.send(sessionId, { inputId: 'conformance-1', text: 'Reply briefly.', delivery: 'queue' });
+    await service.send(sessionId, { inputId: 'conformance-1', text: 'Reply briefly.', delivery });
     await harness.settle(factory);
     const events = () => journal.events(sessionId).map((envelope) => envelope.event);
     return { factory, journal, service, sessionId, events };
@@ -67,6 +67,20 @@ export const DRIVER_CONFORMANCE = Object.freeze([
             assert(snapshot.openTurn === null && snapshot.phase === 'idle', 'the session is idle after a turn without sub-agents');
         },
     },
+    {
+        name: 'declares its interrupt mechanism and treats an interrupt on an idle session as a queued input',
+        async run(harness) {
+            const caps = harness.factory().descriptor.capabilities;
+            assert(caps.interrupt === 'native' || caps.interrupt === 'emulated', 'capabilities.interrupt is native or emulated');
+            const { events, service, sessionId } = await oneTurn(harness, 'interrupt');
+            const list = events();
+            const accepted = list.find((event) => event.type === 'input.accepted');
+            assert(accepted?.delivery === 'interrupt', 'the journal keeps the requested delivery');
+            const statuses = list.filter((event) => event.type === 'turn.completed').map((event) => event.status);
+            assert(statuses.length === 1 && statuses[0] === 'completed', 'nothing is interrupted on an idle session');
+            assert(service.snapshot(sessionId).inputs['conformance-1']?.state === 'completed', 'the input completes with its turn');
+        },
+    },
     {
         name: 'reports usage according to its declared semantics',
         async run(harness) {

package/dist/agent-runtime/session/testing/memory-journal.js

@@ -1,3 +1,4 @@
+import { redactSessionEvent, redactSessionSnapshot } from '../domain/redaction.js';
 import { emptySnapshot, foldEvents } from '../domain/snapshot.js';
 /**
  * In-memory SessionJournal with the same contract as the SQLite adapter:
@@ -23,8 +24,9 @@ export class MemoryJournal {
             this.failNextAppend = null;
             throw error;
         }
-        const envelopes = events.map((event, index) => ({ sessionId, seq: entry.snapshot.lastSeq + index + 1, event: structuredClone(event) }));
-        const snapshot = foldEvents(entry.snapshot, envelopes);
+        const snapshot = redactSessionSnapshot(foldEvents(entry.snapshot, events.map((event, index) => ({ sessionId, seq: entry.snapshot.lastSeq + index + 1, event }))));
+        // Same redaction boundary as the SQLite adapter (domain/redaction.ts).
+        const envelopes = events.map((event, index) => ({ sessionId, seq: entry.snapshot.lastSeq + index + 1, event: structuredClone(redactSessionEvent(event)) }));
         entry.events.push(...envelopes);
         entry.snapshot = snapshot;
         if (options?.baseline)

package/dist/installer/cli.js

@@ -25,7 +25,8 @@ function usageText() {
         '  install-framework   Materialize the versioned framework (offline)',
         '  swap-current        Point framework/current at a version (offline)',
         '  assemble            Link the framework into a project workspace (offline)',
-        '  pipeline            Inspect and verify durable implementation phases',
+        '  pipeline            Inspect and verify durable implementation phases (pipeline trace: requirement ↔ test traceability)',
+        '  rules               Inventory project gates and written rules (rules inventory → .specrails/rules.json)',
         '  runtime             Run, inspect and resume programmatic agents',
         '  help                Show this help message',
         '  version             Print the installed version',
@@ -57,6 +58,8 @@ async function dispatch(subcommand, flags, positionals) {
             return runPipelineCommand(flags, positionals);
         case 'runtime':
             return (await import('../agent-runtime/cli.js')).runRuntimeCommand(flags, positionals);
+        case 'rules':
+            return (await import('../agent-runtime/project-rules.js')).runRulesCommand(flags, positionals);
         case 'install-framework':
             await runInstallFramework(flags);
             return 0;
@@ -79,6 +82,12 @@ async function dispatch(subcommand, flags, positionals) {
     }
 }
 export async function main(argv = process.argv.slice(2)) {
+    // `pipeline trace` keeps its own argv (repeatable, comma-separated lists) and
+    // judges execution with the runtime's full test-reachability check.
+    if (argv[0] === 'pipeline' && argv[1] === 'trace') {
+        const [{ runSpecTraceCli }, { commandReachesTest }] = await Promise.all([import('../pipeline/spec-trace.js'), import('../agent-runtime/compact/test-reachability.js')]);
+        return runSpecTraceCli(argv.slice(2), { reaches: commandReachesTest });
+    }
     const { subcommand, flags, positionals } = parseArgs(argv);
     // `--version` is global only before a command: `swap-current --version <v>`
     // names a framework version.

package/dist/installer/commands/init.js

@@ -6,7 +6,7 @@ import { recordSuccessfulInstall } from '../util/registry.js';
 import { fileURLToPath } from 'node:url';
 import { InstallerError } from '../util/errors.js';
 import { runCommand } from '../util/exec.js';
-import { info, ok, step } from '../util/logger.js';
+import { info, ok, step, warn } from '../util/logger.js';
 import { isDir, isSymlink, listDir, pathExists, readTextFile, removePath, writeFileLf, } from '../util/fs.js';
 import { loadInstallConfig, resolveConfigPath, } from '../phases/install-config.js';
 import { checkPrerequisites } from '../phases/prereqs.js';
@@ -188,8 +188,8 @@ export async function runInit(flags) {
             assertNoCoreDowngrade(readTextFile(installedMarker).trim(), version);
         const previousSelections = snapshotWorkspaceProviderSelections(artifactRoot);
         const surfaces = [
-            ...['.claude', '.codex', '.gemini', '.kimi-code', 'AGENTS.md', 'GEMINI.md', '.gitignore'].map((name) => path.join(artifactRoot, name)),
-            ...['specrails-version', 'specrails-manifest.json', 'setup-templates', 'runtime'].map((name) => path.join(artifactRoot, '.specrails', name)),
+            ...['.claude', '.codex', '.gemini', '.kimi-code', 'AGENTS.md', 'GEMINI.md', 'CLAUDE.md', '.gitignore'].map((name) => path.join(artifactRoot, name)),
+            ...['specrails-version', 'specrails-manifest.json', 'setup-templates', 'runtime', 'rules.json'].map((name) => path.join(artifactRoot, '.specrails', name)),
             path.join(fwDir, 'current'),
             // Contents deliberately NOT snapshotted: `installFramework` rebuilds a
             // version tree whenever its content stamp does not match and stages
@@ -227,6 +227,17 @@ export async function runInit(flags) {
             }
             // openspec STAYS in the repo (codeRoot) — unchanged behaviour.
             await installOpenSpecProject(codeRoot, prereqs.provider, artifactRoot);
+            // Project rules inventory (gates + parsed rule statements). Offline here:
+            // init never spends on a provider; classifications from an earlier
+            // `specrails-core rules inventory` are kept for unchanged rules.
+            try {
+                const { runRulesInventory } = await import('../../agent-runtime/project-rules.js');
+                const { inventory } = await runRulesInventory({ root: codeRoot, artifactRoot, classify: false });
+                ok(`Project rules inventory: ${inventory.gates.length} gate(s), ${inventory.rules.length} rule(s) in .specrails/rules.json`);
+            }
+            catch (err) {
+                warn(`Project rules inventory skipped: ${err.message}`);
+            }
             if (artifactRoot !== codeRoot)
                 recordSuccessfulInstall(repoRoot, { home: process.env.SPECRAILS_REGISTRY_HOME, providers: [prereqs.provider], coreVersion: version });
             step('Installation complete');

package/dist/installer/phases/scaffold.js

@@ -202,8 +202,15 @@ export function scaffoldInstallation(input) {
         if (skills.placed > 0)
             info(`Placed ${skills.placed} skill(s) into ${input.providerDir}/skills/`);
     }
-    // --- Codex provider settings + AGENTS.md initial content ---
-    if (input.provider === 'codex') {
+    // --- Provider settings + managed instruction block ---
+    if (input.provider === 'claude') {
+        const written = applyClaudeSettings(input);
+        copiedFiles += written;
+        if (written > 0) {
+            info(`Claude provider: wrote ${written} setting file(s) (CLAUDE.md)`);
+        }
+    }
+    else if (input.provider === 'codex') {
         const written = applyCodexSettings(input);
         copiedFiles += written;
         if (written > 0) {
@@ -544,7 +551,10 @@ function seedProjectLayer(input) {
     // Project-named instruction file (codex AGENTS.md / gemini GEMINI.md). Reuse
     // the same sentinel-upsert helpers via the settings appliers, scoped so they
     // ONLY emit the instruction file (the settings file is already linked above).
-    if (input.provider === 'codex') {
+    if (input.provider === 'claude') {
+        seedInstructionFile(path.join(input.workspace, 'CLAUDE.md'), renderInitialClaudeMd(input.codeRoot));
+    }
+    else if (input.provider === 'codex') {
         seedInstructionFile(path.join(input.workspace, 'AGENTS.md'), renderInitialAgentsMd(input.codeRoot));
     }
     else if (input.provider === 'gemini') {
@@ -991,6 +1001,39 @@ function renderInitialKimiAgentsMd(repoRoot) {
         '',
     ].join('\n');
 }
+/**
+ * Claude Code provider settings: the sentinel-protected Specrails block in the
+ * root `CLAUDE.md` (the instruction file Claude Code loads on startup), upserted
+ * exactly like codex `AGENTS.md` and gemini `GEMINI.md` so user content outside
+ * the block survives. Returns files written.
+ */
+function applyClaudeSettings(input) {
+    const claudeMdPath = path.join(input.artifactRoot, 'CLAUDE.md');
+    const content = renderInitialClaudeMd(input.codeRoot);
+    if (!pathExists(claudeMdPath)) {
+        writeFileLf(claudeMdPath, content);
+        return 1;
+    }
+    const existing = readTextFile(claudeMdPath);
+    const next = upsertAgentsMdManagedBlock(existing, extractManagedBlock(content));
+    if (next === existing)
+        return 0;
+    writeFileLf(claudeMdPath, next);
+    return 1;
+}
+function renderInitialClaudeMd(repoRoot) {
+    return renderInitialAgentsMd(repoRoot).replace(AGENTS_MD_END, [
+        '## Project rules',
+        '',
+        '- `.specrails/rules.json` (refreshed by `specrails-core rules inventory`)',
+        '  lists the gates this repository already enforces and how each written',
+        '  rule is checked. Run the gates that cover your change; rules marked',
+        '  `humanOnly` are for the human reviewer, never claim them verified.',
+        '- Read provider rules from `.claude/rules/` when present.',
+        '',
+        AGENTS_MD_END,
+    ].join('\n'));
+}
 function renderInitialGeminiMd(repoRoot) {
     return renderInitialAgentsMd(repoRoot).replace(AGENTS_MD_END, 'Read provider rules from `.gemini/`.\n\n' + AGENTS_MD_END);
 }
@@ -1010,6 +1053,14 @@ function placePipelineRuntime(input) {
         return 0;
     const dest = path.join(input.artifactRoot, '.specrails', 'runtime');
     copyFile(source, path.join(dest, 'pipeline-state.mjs'));
+    // Requirement ↔ test traceability, self-contained like pipeline-state: `node .specrails/runtime/trace.mjs --check`.
+    const trace = path.join(input.scriptDir, 'dist', 'pipeline', 'spec-trace.js');
+    const traced = pathExists(trace) ? 2 : 0;
+    if (traced) {
+        copyFile(trace, path.join(dest, 'spec-trace.mjs'));
+        writeFileLf(path.join(dest, 'trace.mjs'), "import { runSpecTraceCli } from './spec-trace.mjs'\n" +
+            "process.exitCode = await runSpecTraceCli(process.argv.slice(2))\n");
+    }
     writeFileLf(path.join(dest, 'pipeline.mjs'), "import { runPipelineCli } from './pipeline-state.mjs'\n" +
         "process.exitCode = await runPipelineCli(process.argv.slice(2))\n");
     const runtime = path.join(input.scriptDir, 'dist', 'agent-runtime', 'cli.js');
@@ -1026,9 +1077,9 @@ function placePipelineRuntime(input) {
                 agents: Object.fromEntries(['architect', 'developer', 'reviewer'].map(role => [role, { provider, maxTurns: 100 }])), verification: [],
             }, null, 2) + '\n');
         }
-        return 3;
+        return 3 + traced;
     }
-    return 2;
+    return 2 + traced;
 }
 function pruneLegacyArtifacts(input) {
     const legacyPaths = [

package/dist/pipeline/pipeline-state.d.ts

@@ -147,10 +147,19 @@ export interface AcceptanceCheck {
     scope: string;
     limitations: string;
 }
+/** Where in the change one finding applies (contract 5.9). `finding` indexes `findings`; `path` is repository-relative. */
+export interface FindingLocation {
+    finding: number;
+    path: string;
+    line?: number;
+    endLine?: number;
+}
 export interface AcceptanceReport {
     criteria: AcceptanceCriterion[];
     checks: AcceptanceCheck[];
     findings: string[];
+    /** Optional anchors for findings (contract 5.9); absent when the reviewer named none. */
+    findingLocations?: FindingLocation[];
 }
 export interface AcceptanceReceipt extends AcceptanceReport {
     scopeHash: string;
@@ -276,6 +285,12 @@ declare function inspectReceipt(state: PipelineState, env?: NodeJS.ProcessEnv):
 export declare function frozenAcceptanceCriteria(contextInput: unknown): Array<Pick<AcceptanceCriterion, 'specId' | 'criterionIndex' | 'requirement'>>;
 /** Validates a report against the frozen scope without recording it; throws the same errors `recordAcceptance` would. */
 export declare function validateAcceptanceReport(contextInput: unknown, input: unknown): AcceptanceReport;
+/**
+ * Keeps only well-formed anchors for the findings that exist. A malformed
+ * anchor is dropped, never fatal: a location is advisory and must not fail an
+ * otherwise valid review.
+ */
+export declare function sanitizeFindingLocations(value: unknown, findingCount: number): FindingLocation[];
 declare function inspectAcceptance(state: PipelineState): {
     valid: boolean;
     status: PipelineCompletion['validation'];

package/dist/pipeline/pipeline-state.js

@@ -296,7 +296,7 @@ export function bindImplementationExclusions(contextInput, exclusions) {
             continue; // A scoped child receives the parent union, filtered to its frozen repositories.
         repositoryExclusions[id] = [...new Set(paths)].sort();
         for (const item of repositoryExclusions[id]) {
-            if (!/^(?:[a-zA-Z0-9][a-zA-Z0-9._-]*\/)*openspec\/(?:changes|specs)\/[a-z0-9][a-z0-9./-]*$/.test(item))
+            if (!/^(?:[a-zA-Z0-9][a-zA-Z0-9._-]*\/)*openspec\/(?:(?:changes|specs)\/[a-z0-9][a-z0-9./-]*|capability-map\.json)$/.test(item))
                 fail('Implementation artifact exclusion is outside declared OpenSpec artifacts');
             safeChild(repository.path, item);
         }
@@ -485,7 +485,8 @@ export function initializePipeline(contextInput, change) {
             schemaVersion: 1, runId: context.runId, change, context, scopeHash: digest(canonical(context)), revision: 0,
             createdAt: now, updatedAt: now,
             phases: Object.fromEntries(PHASES.map((phase) => [phase, { status: 'pending' }])),
-            artifactExclusions: ['openspec/changes/' + change],
+            // The capability map is Core metadata the archive step rewrites (graph/capability-map.ts), never part of the reviewed candidate.
+            artifactExclusions: ['openspec/changes/' + change, 'openspec/capability-map.json'],
         };
         atomicJson(path.join(pipelineStateDirectory(context), 'context.json'), context);
         saveState(state);
@@ -615,6 +616,36 @@ export function frozenAcceptanceCriteria(contextInput) {
 export function validateAcceptanceReport(contextInput, input) {
     return acceptanceReport(validatePipelineContext(contextInput), input);
 }
+const MAX_FINDING_LOCATIONS = 50;
+/**
+ * Keeps only well-formed anchors for the findings that exist. A malformed
+ * anchor is dropped, never fatal: a location is advisory and must not fail an
+ * otherwise valid review.
+ */
+export function sanitizeFindingLocations(value, findingCount) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const raw of value) {
+        if (out.length >= MAX_FINDING_LOCATIONS)
+            break;
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            continue;
+        const row = raw;
+        const finding = row.finding;
+        if (typeof finding !== 'number' || !Number.isInteger(finding) || finding < 0 || finding >= findingCount || seen.has(finding))
+            continue;
+        const filePath = typeof row.path === 'string' ? row.path.trim().replace(/\\/g, '/').replace(/^\.\//, '') : '';
+        if (!filePath || filePath.length > 500 || filePath.startsWith('/') || /^[A-Za-z]:/.test(filePath) || filePath.includes('\0') || filePath.split('/').includes('..'))
+            continue;
+        const line = typeof row.line === 'number' && Number.isInteger(row.line) && row.line >= 1 && row.line <= 10_000_000 ? row.line : undefined;
+        const endLine = line !== undefined && typeof row.endLine === 'number' && Number.isInteger(row.endLine) && row.endLine > line && row.endLine <= 10_000_000 ? row.endLine : undefined;
+        seen.add(finding);
+        out.push({ finding, path: filePath, ...(line !== undefined ? { line } : {}), ...(endLine !== undefined ? { endLine } : {}) });
+    }
+    return out;
+}
 function nonempty(value) { return typeof value === 'string' && value.trim().length > 0; }
 function evidence(value) { return Array.isArray(value) && value.length > 0 && value.every(nonempty); }
 function acceptanceReport(context, input) {
@@ -655,7 +686,9 @@ function acceptanceReport(context, input) {
             fail('Check needs status, evidence, measurement scope and limitations');
         return { name: check.name, status: check.status, required: check.required, evidence: check.evidence, scope: check.scope, limitations: check.limitations };
     });
-    return { criteria, checks, findings: report.findings };
+    const findings = report.findings;
+    const findingLocations = sanitizeFindingLocations(report.findingLocations, findings.length);
+    return { criteria, checks, findings, ...(findingLocations.length ? { findingLocations } : {}) };
 }
 function inspectAcceptance(state) {
     const receipt = state.acceptance;

package/dist/pipeline/spec-trace.d.ts

@@ -0,0 +1,134 @@
+export declare const SPEC_TRACE_SCHEMA_VERSION = 1;
+export declare const SPEC_TRACE_FILE = "spec-trace.json";
+/** A file that IS a test across ecosystems: `x.test.ts`, `x.spec.js`, `test_x.py`, `x_test.go`, `x_spec.rb`, `XTest.java`, `test_x.sh`, `x.bats`. */
+export declare const TEST_FILE: RegExp;
+/** `capability/slug`: lowercase, accents removed (NFKD), every run of non-alphanumerics a single dash, no leading or trailing dash. */
+export declare function requirementSlug(name: string): string;
+export declare function requirementId(capability: string, name: string): string;
+export interface SpecRequirement {
+    id: string;
+    capability: string;
+    name: string;
+    file: string;
+    line: number;
+}
+export interface TraceTest {
+    repositoryId: string;
+    file: string;
+    line: number;
+}
+export interface TraceTag extends TraceTest {
+    tag: string;
+    form: 'title' | 'comment';
+}
+export interface TraceRepository {
+    id: string;
+    root: string;
+}
+export interface TraceCommand {
+    repositoryId: string;
+    command: string;
+    args: string[];
+    cwd?: string;
+    exitCode: number | null;
+}
+export type ReachesTest = (root: string, command: {
+    command: string;
+    args: string[];
+    cwd?: string;
+}, file: string) => boolean;
+export interface SpecTraceInput {
+    /** The checkout that holds `openspec/` (the run's artifact root). */
+    specsRoot: string;
+    /** Changes whose ADDED/MODIFIED/RENAMED requirements are "touched" (and checked by `--check`). */
+    changes?: string[];
+    repositories: TraceRepository[];
+    /** Explicit test files (the verification plan's or the developer's), repository-relative; added to discovery. */
+    testFiles?: Array<{
+        repositoryId: string;
+        file: string;
+    }>;
+    /** Restrict discovery to these repository-relative globs (`src/**\/*.test.ts`); default: every test-shaped file. */
+    testGlobs?: string[];
+    /** Verification evidence: the receipt Core recorded. */
+    receipt?: {
+        id?: string;
+        commands: TraceCommand[];
+    } | null;
+    /** No receipt, but the caller already ran the tests successfully (a CI step after `npm test`). */
+    testsPassed?: boolean;
+    /** Whether a command executes a test file; Core injects its full reachability check. Default: literal argument inspection. */
+    reaches?: ReachesTest;
+    now?: () => Date;
+}
+export type UndemonstratedReason = 'no-test' | 'not-executed' | 'failed';
+export interface SpecTraceReport {
+    schemaVersion: typeof SPEC_TRACE_SCHEMA_VERSION;
+    generatedAt: string;
+    changes: string[];
+    /** `receipt`: executed means reached by a passing receipt command; `tests-passed`: tagged files count as executed; `none`: nothing counts as executed. */
+    evidence: 'receipt' | 'tests-passed' | 'none';
+    receiptId: string | null;
+    requirements: number;
+    demonstrated: Array<{
+        id: string;
+        name: string;
+        tests: TraceTest[];
+    }>;
+    undemonstrated: Array<{
+        id: string;
+        name: string;
+        reason: UndemonstratedReason;
+        tests: TraceTest[];
+    }>;
+    /** Tags that match no requirement (a typo, a renamed or removed requirement). Advisory. */
+    untagged: TraceTag[];
+    /** Requirements the changes add, modify or rename. */
+    touched: string[];
+    /** Touched requirements that are not demonstrated: what `--check` fails on. */
+    touchedUndemonstrated: string[];
+    scannedFiles: number;
+}
+/** Requirements of the canonical specs, in capability then file order. */
+export declare function readSpecRequirements(specsRoot: string): SpecRequirement[];
+export interface ChangeDelta {
+    added: SpecRequirement[];
+    modified: SpecRequirement[];
+    removed: string[];
+    renamed: Array<{
+        from: string;
+        to: SpecRequirement;
+    }>;
+}
+/** The change's directory: active, or its most recent archive (`archive/YYYY-MM-DD-<change>`). */
+export declare function changeDirectory(specsRoot: string, change: string): string | undefined;
+/** ADDED / MODIFIED / REMOVED / RENAMED requirements of a change's delta specs. */
+export declare function readChangeDelta(specsRoot: string, change: string): ChangeDelta;
+/** Active (unarchived) changes, for a CI check that names none. */
+export declare function activeChanges(specsRoot: string): string[];
+/** Tags in a test file's text with their 1-based lines. */
+export declare function scanTags(text: string): Array<{
+    tag: string;
+    line: number;
+    form: 'title' | 'comment';
+}>;
+/** Literal reachability: a command naming test-shaped paths reaches only those; any other command is assumed to discover every test. */
+export declare const literalReaches: ReachesTest;
+/** The traceability report for the specs and tests under the input roots. Never throws for unreadable files; they are skipped. */
+export declare function traceSpecs(input: SpecTraceInput): SpecTraceReport;
+/** Requirement ids a change adds, modifies or renames: the ones its developer tags and `--check` enforces. */
+export declare function touchedRequirements(specsRoot: string, change: string): string[];
+/** One-line summary shown to hosts and reviewers: `Requirements demonstrated X/Y`. */
+export declare function traceSummary(report: Pick<SpecTraceReport, 'demonstrated' | 'requirements'>): string;
+export declare function renderTraceReport(report: SpecTraceReport): string;
+/**
+ * `pipeline trace [--root <dir>] [--context <context.json>] [--change <name>[,…]] [--tests <glob>[,…]] [--tests-passed] [--check] [--json] [--out <file>]`.
+ * Normal mode is fail-open: it reports and exits 0 even when it cannot read
+ * something. `--check` exits 1 when a requirement touched by the change is
+ * not demonstrated (or the scan itself fails).
+ */
+export declare function runSpecTraceCli(argv: string[], options?: {
+    reaches?: ReachesTest;
+    stdout?: (text: string) => void;
+    stderr?: (text: string) => void;
+}): Promise<number>;