specrails-core 6.6.5 → 6.7.0

package/dist/agent-runtime/executor-types.d.ts

@@ -28,6 +28,21 @@ export declare const BUILTIN_ROLE_POLICY: {
         readonly openspecSkill: 'openspec-verify-change';
     };
 };
+/**
+ * Engine-only built-in roles. Core owns their policy and their instructions
+ * (prompts.ts); they take the architect's provider assignment, are not legacy
+ * pipeline phases and cannot be redefined as custom roles.
+ */
+export declare const ENGINE_ROLES: readonly ['deriver'];
+export type EngineRole = typeof ENGINE_ROLES[number];
+export declare function isEngineRole(role: string): role is EngineRole;
+export declare const ENGINE_ROLE_POLICY: {
+    readonly deriver: {
+        readonly access: 'read';
+        readonly artifacts: 'all';
+        readonly openspecSkill: 'openspec-ff-change';
+    };
+};
 /** Who an observer sees acting: a pipeline role, or the FIXER stance the developer step takes on a correction round. */
 export type AgentEventRole = AgentRole | 'fixer';
 export type CliProvider = 'claude' | 'codex' | 'gemini' | 'kimi';
@@ -112,6 +127,8 @@ export interface RuntimeConfig {
     /** Idempotent commands the `verify` piece runs sequentially before each verification plan (same shape as `verification`; `policy` is ignored). */
     setup?: VerificationCommand[];
     approvalBeforeArchive?: boolean;
+    /** Characterize uncovered modules before changing them: a Baseline task group whose tests must pass on the base code (default false). */
+    baselineOnTouch?: boolean;
     /** Review gate thresholds (0–100); unset fields keep Core's defaults. */
     review?: {
         minScore?: number;
@@ -120,6 +137,8 @@ export interface RuntimeConfig {
     /** What to do when the architect still reports low confidence after investigating: ask the requester (default) or proceed on stated assumptions. */
     architect?: {
         onLowConfidence?: 'ask' | 'proceed';
+        /** `ask-on-high` (default): a high-impact clarification without a safe default pauses the run; `always-proceed`: plan on stated assumptions. */
+        clarifications?: 'ask-on-high' | 'always-proceed';
     };
     /** Compact-runtime guardrails switched OFF by the project (`{ id: false }`); unset = every guardrail on. */
     guardrails?: GuardrailSettings;

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

@@ -8,6 +8,16 @@ export const BUILTIN_ROLE_POLICY = {
     developer: { access: 'write', artifacts: 'tasks-checkboxes', openspecSkill: 'openspec-apply-change' },
     reviewer: { access: 'read', artifacts: 'none', openspecSkill: 'openspec-verify-change' },
 };
+/**
+ * Engine-only built-in roles. Core owns their policy and their instructions
+ * (prompts.ts); they take the architect's provider assignment, are not legacy
+ * pipeline phases and cannot be redefined as custom roles.
+ */
+export const ENGINE_ROLES = ['deriver'];
+export function isEngineRole(role) { return ENGINE_ROLES.includes(role); }
+export const ENGINE_ROLE_POLICY = {
+    deriver: { access: 'read', artifacts: 'all', openspecSkill: 'openspec-ff-change' },
+};
 export class AgentExecutionError extends Error {
     code;
     usage;

package/dist/agent-runtime/failure-classification.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Structured failure classification (contract 5.8, capability `failureClassification`).
+ *
+ * A terminal `failed` or `blocked` run reports WHY it stopped in one typed record so a host
+ * can offer a remedy without parsing prose. The classifier is a pure function of signals the
+ * run already produced (status, the failing step, error codes and messages); it never invents
+ * a cause. Anything it cannot tie to a documented signal is `unknown` with `confidence: 'low'`.
+ */
+export declare const FAILURE_KINDS: readonly ['tests_failed', 'provider_limit', 'environment', 'blocked', 'timeout', 'tool_inactivity', 'crash', 'unknown'];
+export type FailureKind = (typeof FAILURE_KINDS)[number];
+export declare const FAILURE_CONFIDENCE: readonly ['high', 'low'];
+export interface FailureClassification {
+    kind: FailureKind;
+    /** The step (engine 1) or node path (engine 2) that stopped the run. */
+    phase?: string;
+    /** Correction rounds the run spent before it stopped (visits of the correction step). */
+    rounds?: number;
+    /** `provider_limit` only: the provider's own wording of when it resets ("3am (Europe/Madrid)"), never reformatted. */
+    resetAt?: string;
+    /** One short plain sentence taken from the run's own error; bounded, redacted upstream. */
+    detail?: string;
+    /** The step a `runtime resume` continues from, when resuming can help. */
+    resumablePhase?: string;
+    confidence: (typeof FAILURE_CONFIDENCE)[number];
+}
+export interface FailureSignals {
+    status: string;
+    /** Run-level error: engine 1 sends a string, engine 2 `{code, message}`. */
+    error?: unknown;
+    /** Engine 1 step records or engine 2 compact step map, keyed by step id / node path. */
+    steps?: Record<string, {
+        status?: unknown;
+        visits?: unknown;
+        error?: unknown;
+        kind?: unknown;
+    } | undefined>;
+    /** Engine 2 `recentFailures`, newest first. */
+    recentFailures?: Array<{
+        nodePath?: unknown;
+        status?: unknown;
+        visit?: unknown;
+        error?: unknown;
+    } | undefined>;
+    nextStep?: unknown;
+}
+export declare function providerLimitReset(message: string): string | undefined;
+/**
+ * Classify a terminal result. Returns `undefined` for any status other than `failed` or
+ * `blocked`: a succeeded, paused or cancelled run has nothing to diagnose.
+ */
+export declare function classifyFailure(signals: FailureSignals): FailureClassification | undefined;

package/dist/agent-runtime/failure-classification.js

@@ -0,0 +1,110 @@
+/**
+ * Structured failure classification (contract 5.8, capability `failureClassification`).
+ *
+ * A terminal `failed` or `blocked` run reports WHY it stopped in one typed record so a host
+ * can offer a remedy without parsing prose. The classifier is a pure function of signals the
+ * run already produced (status, the failing step, error codes and messages); it never invents
+ * a cause. Anything it cannot tie to a documented signal is `unknown` with `confidence: 'low'`.
+ */
+export const FAILURE_KINDS = ['tests_failed', 'provider_limit', 'environment', 'blocked', 'timeout', 'tool_inactivity', 'crash', 'unknown'];
+export const FAILURE_CONFIDENCE = ['high', 'low'];
+const DETAIL_LIMIT = 280;
+const text = (value) => typeof value === 'string' ? value : '';
+function messageOf(error) {
+    if (typeof error === 'string')
+        return { code: '', message: error };
+    if (error && typeof error === 'object') {
+        const record = error;
+        return { code: text(record.code), message: text(record.message) };
+    }
+    return { code: '', message: '' };
+}
+/** The provider's own "resets 3am (Europe/Madrid)" hint, when the message carries one. */
+const RESETS = /\bresets?\s+(?:at\s+|in\s+)?([^\n·(]*?\d[^\n·(]*?)(\s*\([^)]*\))?(?=\s*(?:\(error|[.,;]\s|\n|$))/i;
+export function providerLimitReset(message) {
+    const match = RESETS.exec(message);
+    if (!match)
+        return undefined;
+    const value = `${match[1].trim()}${match[2] ? ` ${match[2].trim()}` : ''}`.trim().replace(/[.,;:]+$/, '');
+    return value && value.length <= 80 ? value : undefined;
+}
+const PROVIDER_LIMIT = /\byou(?:'|’)?ve (?:hit|reached) your (?:session|usage|weekly|daily|monthly|plan)?\s*limit\b|\berror type rate_limit\b|\bHTTP 429\b|\b429 Too Many Requests\b|\brate[ _-]?limit(?:ed|s)? (?:exceeded|reached|hit)\b|\brate_limit_error\b|\binsufficient_quota\b|\busage limit (?:reached|exceeded)\b|\bRESOURCE_EXHAUSTED\b|\bquota (?:exceeded|exhausted)\b/i;
+const ENVIRONMENT_CODES = new Set(['verification_host_precondition', 'verification_nondeterministic_output', 'verification_execution_error']);
+const ENVIRONMENT_TEXT = /Verification cannot run in this environment|Verification output is not deterministic|\(verification_nondeterministic_output\)|setup command .* failed|could not undo them|outside the repository scope/i;
+const IDLE_CODES = new Set(['idle_timeout']);
+const IDLE_TEXT = /\bidle timeout\b|no tool call, reply or usage for|no output for \d/i;
+const TIMEOUT_CODES = new Set(['timeout']);
+const TIMEOUT_TEXT = /total execution limit|active-duration budget exhausted|execution timed out|reached its time budget/i;
+const CRASH_CODES = new Set(['lease_lost', 'storage_corrupt', 'provider_request_error', 'incomplete_response', 'terminal_conflict']);
+const CRASH_TEXT = /execution failed \(exit \d+\)|exited without a successful final result|lost its endpoint|process exited|\bcrashed\b|\bSIGKILL\b|\bSIGSEGV\b/i;
+const TESTS_TEXT = /Correction loop stopped: .*(?:verif|check|test|fail)|verification (?:failed|did not pass)|failing (?:tests|checks)|(?:tests?|checks?) (?:are |is )?failing|(?:tests?|checks?) failed/i;
+const BLOCKED_CODES = new Set(['baseline_characterization_failed', 'budget_exhausted', 'retry_exhausted', 'recover_required', 'recovery_ambiguous']);
+const BLOCKED_TEXT = /correction limit reached|continuation limit reached|reviewer rejected the same change|could not make progress|Run budget is exhausted|\(baseline_characterization_failed\)/i;
+const CORRECTION_STEP = /(?:^|[/.:])(?:fixer|fix|correct)/i;
+function detailOf(message) {
+    const flat = message.replace(/\s+/g, ' ').trim();
+    if (!flat)
+        return undefined;
+    return flat.length > DETAIL_LIMIT ? `${flat.slice(0, DETAIL_LIMIT - 1)}…` : flat;
+}
+function failingPhase(signals) {
+    const recent = (signals.recentFailures ?? []).find(item => item && typeof item.nodePath === 'string' && ['failed', 'blocked', 'interrupted'].includes(text(item.status)));
+    if (recent) {
+        const { code, message } = messageOf(recent.error);
+        return { phase: recent.nodePath, message, code };
+    }
+    const entries = Object.entries(signals.steps ?? {}).filter(([, step]) => step && ['failed', 'blocked', 'interrupted'].includes(text(step.status)));
+    const [id, step] = entries[0] ?? [];
+    if (id && step)
+        return { phase: id, ...(() => { const { code, message } = messageOf(step.error); return { code, message }; })() };
+    return { message: '', code: '' };
+}
+function correctionRounds(steps) {
+    let visits = 0;
+    for (const [id, step] of Object.entries(steps ?? {})) {
+        if (!step || !CORRECTION_STEP.test(id))
+            continue;
+        const count = typeof step.visits === 'number' && Number.isFinite(step.visits) ? step.visits : 0;
+        visits += count;
+    }
+    return visits > 0 ? visits : undefined;
+}
+/**
+ * Classify a terminal result. Returns `undefined` for any status other than `failed` or
+ * `blocked`: a succeeded, paused or cancelled run has nothing to diagnose.
+ */
+export function classifyFailure(signals) {
+    if (signals.status !== 'failed' && signals.status !== 'blocked')
+        return undefined;
+    const top = messageOf(signals.error);
+    const step = failingPhase(signals);
+    // The run-level error names the cause; the failing attempt's own error is the fallback.
+    const code = top.code || step.code;
+    const message = top.message || step.message;
+    const haystack = `${top.message}\n${step.message}`;
+    const phase = step.phase ?? (typeof signals.nextStep === 'string' && signals.nextStep ? signals.nextStep : undefined);
+    const rounds = correctionRounds(signals.steps);
+    const base = { ...(phase ? { phase } : {}), ...(rounds ? { rounds } : {}) };
+    const detail = detailOf(message);
+    const resumable = phase ? { resumablePhase: typeof signals.nextStep === 'string' && signals.nextStep ? signals.nextStep : phase } : {};
+    const done = (kind, extra = {}, resume = false) => ({ kind, ...base, ...(detail ? { detail } : {}), ...(resume ? resumable : {}), ...extra, confidence: kind === 'unknown' ? 'low' : 'high' });
+    if (PROVIDER_LIMIT.test(haystack)) {
+        const resetAt = providerLimitReset(haystack);
+        return done('provider_limit', resetAt ? { resetAt } : {}, true);
+    }
+    if (IDLE_CODES.has(code) || IDLE_TEXT.test(haystack))
+        return done('tool_inactivity', {}, true);
+    if (TIMEOUT_CODES.has(code) || TIMEOUT_TEXT.test(haystack))
+        return done('timeout', {}, true);
+    if (code === 'baseline_characterization_failed' || /\(baseline_characterization_failed\)/.test(haystack))
+        return done('blocked');
+    if (ENVIRONMENT_CODES.has(code) || ENVIRONMENT_TEXT.test(haystack))
+        return done('environment', {}, true);
+    if (BLOCKED_CODES.has(code) || BLOCKED_TEXT.test(haystack))
+        return done('blocked', {}, true);
+    if (TESTS_TEXT.test(haystack) || (code === 'verification_failed'))
+        return done('tests_failed', {}, signals.status === 'blocked');
+    if (CRASH_CODES.has(code) || CRASH_TEXT.test(haystack))
+        return done('crash', {}, true);
+    return done('unknown', {}, false);
+}

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

@@ -30,4 +30,6 @@ export declare function archiveOpenSpecChange(context: PipelineContext, change:
     directory: string;
     beforePublish(): void;
 }, signal?: AbortSignal): Promise<void>;
-export declare function archive(context: PipelineContext, change: string, signal?: AbortSignal): Promise<void>;
+export declare function archive(context: PipelineContext, change: string, signal?: AbortSignal, options?: {
+    beforeDone?: (archived: string) => void;
+}): Promise<void>;

package/dist/agent-runtime/graph/artifacts.js

@@ -263,7 +263,7 @@ export async function archiveOpenSpecChange(context, change, adapter, signal) {
         throw new Error('OpenSpec active change does not exist');
     await archiveWithOpenSpec(context, change, active, signal, adapter);
 }
-export async function archive(context, change, signal) {
+export async function archive(context, change, signal, options = {}) {
     const state = journal(context);
     if (state.phases.archive.status !== 'done') {
         const active = artifactPath(context.artifactRoot, 'openspec/changes/' + change);
@@ -272,6 +272,10 @@ export async function archive(context, change, signal) {
             transitionPipeline(context, 'archive', 'running');
             await archiveWithOpenSpec(context, change, active, signal);
         }
+        // Idempotent post-archive metadata (the capability map); repeated after a crash.
+        const archived = archivedOpenSpecChange(context, change);
+        if (archived && options.beforeDone)
+            options.beforeDone(artifactPath(context.artifactRoot, archived));
         // If the process died after rename, Core rechecks the saved archive approval.
         transitionPipeline(context, 'archive', 'done');
     }

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

@@ -0,0 +1,50 @@
+import { type PipelineContext } from '../../pipeline/pipeline-state.js';
+/**
+ * Baseline on touch: when the blast radius of a change reaches code no
+ * capability covers, the plan gains a Baseline task group (characterization
+ * tests of today's behaviour plus a minimal as-built spec) that must pass
+ * against the unchanged code before the developer touches the module.
+ */
+export declare const BASELINE_SCHEMA_VERSION = 1;
+export declare const BASELINE_FILE = "baseline.json";
+/** Error code of the host blocker when characterization tests fail on the base code. */
+export declare const BASELINE_BLOCKER = "baseline_characterization_failed";
+export interface BlastRadiusFile {
+    repositoryId: string;
+    path: string;
+}
+export interface BaselineDetection {
+    blastRadius: string[];
+    covered: string[];
+    uncovered: string[];
+    skipped: string[];
+}
+export interface BaselineRecord {
+    schemaVersion: typeof BASELINE_SCHEMA_VERSION;
+    change: string;
+    /** `not-needed`: every touched module is covered; `planned`: the architect added the Baseline group; `passed`/`failed`: characterization on the base code; `violated`: the baseline stage edited non-test files. */
+    status: 'not-needed' | 'planned' | 'passed' | 'failed' | 'violated';
+    recordedAt: string;
+    detection: BaselineDetection;
+    /** Characterization test files the developer wrote in the baseline stage. */
+    tests: string[];
+    receiptId?: string;
+    reason?: string;
+}
+/** Files the design names under its Blast radius heading (backticked paths, or the first path-like token of a bullet). */
+export declare function blastRadiusFiles(context: Pick<PipelineContext, 'repositories' | 'artifactRepositoryId'>, design: string): BlastRadiusFile[];
+/**
+ * Intersects the design's blast radius with the capability map and the path
+ * mentions in the canonical specs. Only existing code files can need a
+ * baseline: new files, tests, documentation and lockfiles are skipped.
+ */
+export declare function detectBaseline(context: PipelineContext, change: string): BaselineDetection;
+/** Throws a repairable error unless tasks.md has a Baseline group with a task and a delta spec adds at least one requirement. */
+export declare function validateBaselinePlan(context: PipelineContext, change: string): void;
+/** Test files among changed files (the characterization tests). */
+export declare function testEdits(files: readonly string[]): string[];
+/** Files of the baseline stage that are not tests: the module must stay untouched until characterization passes. */
+export declare function nonTestEdits(files: readonly string[]): string[];
+export declare function baselinePath(context: Pick<PipelineContext, 'backlogRoot' | 'runId'>): string;
+export declare function writeBaselineRecord(context: PipelineContext, entry: Omit<BaselineRecord, 'schemaVersion' | 'recordedAt'>): BaselineRecord;
+export declare function readBaselineRecord(context: Pick<PipelineContext, 'backlogRoot' | 'runId'>): BaselineRecord | null;

package/dist/agent-runtime/graph/baseline.js

@@ -0,0 +1,145 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pipelineStateDirectory } from '../../pipeline/pipeline-state.js';
+import { TEST_FILE, readChangeDelta } from '../../pipeline/spec-trace.js';
+import { TEST_FILE_PATTERN } from '../compact/test-reachability.js';
+import { child, write } from './artifacts.js';
+import { readCapabilityMap, qualifiedPath } from './capability-map.js';
+import { designSection } from './clarifications.js';
+/**
+ * Baseline on touch: when the blast radius of a change reaches code no
+ * capability covers, the plan gains a Baseline task group (characterization
+ * tests of today's behaviour plus a minimal as-built spec) that must pass
+ * against the unchanged code before the developer touches the module.
+ */
+export const BASELINE_SCHEMA_VERSION = 1;
+export const BASELINE_FILE = 'baseline.json';
+/** Error code of the host blocker when characterization tests fail on the base code. */
+export const BASELINE_BLOCKER = 'baseline_characterization_failed';
+const GENERIC_DIRECTORIES = new Set(['src', 'lib', 'app', 'apps', 'packages', 'server', 'client', 'test', 'tests', 'spec', 'specs', 'source', 'internal', 'pkg', 'cmd']);
+const NOT_CODE = /\.(?:md|mdx|txt|rst|adoc|lock|png|jpe?g|gif|svg|ico|webp|woff2?|ttf|eot|pdf|snap)$|(?:^|\/)(?:package-lock\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb|Cargo\.lock|go\.sum|poetry\.lock)$/i;
+const posix = (file) => file.replace(/\\/g, '/').replace(/^\.\//, '');
+/** Files the design names under its Blast radius heading (backticked paths, or the first path-like token of a bullet). */
+export function blastRadiusFiles(context, design) {
+    const lines = designSection(design, /\bblast\s+radius\b/i) ?? [];
+    const files = [];
+    for (const line of lines) {
+        const ticks = [...line.matchAll(/`([^`\s]+)`/g)].map(match => match[1]);
+        const bare = /^\s*(?:[-*+]|\d+\.)\s+([\w@.~/-][^\s:—–(]*[\w)])/.exec(line)?.[1];
+        for (const token of ticks.length ? ticks : bare ? [bare] : []) {
+            const qualified = /^([A-Za-z0-9][\w.-]*):(.+)$/.exec(token);
+            const repository = qualified && context.repositories.some(item => item.id === qualified[1]) ? qualified[1] : context.artifactRepositoryId;
+            const file = posix(qualified && repository === qualified[1] ? qualified[2] : token);
+            if (!/[/.]/.test(file) || file.startsWith('..') || path.isAbsolute(file))
+                continue;
+            if (!files.some(item => item.repositoryId === repository && item.path === file))
+                files.push({ repositoryId: repository, path: file });
+        }
+    }
+    return files;
+}
+function specText(context) {
+    const root = path.join(context.artifactRoot, 'openspec', 'specs');
+    try {
+        return readdirSync(root, { withFileTypes: true }).filter(entry => entry.isDirectory()).map(entry => {
+            try {
+                return readFileSync(path.join(root, entry.name, 'spec.md'), 'utf8');
+            }
+            catch {
+                return '';
+            }
+        }).join('\n');
+    }
+    catch {
+        return '';
+    }
+}
+/** A file is covered when the capability map lists it or a spec mentions it or one of its specific directories. */
+function covered(file, mapped, specs) {
+    if (mapped.has(file))
+        return true;
+    const plain = file.includes(':') ? file.slice(file.indexOf(':') + 1) : file;
+    if (specs.includes(plain))
+        return true;
+    const parts = plain.split('/').slice(0, -1);
+    for (let depth = parts.length; depth >= 1; depth--) {
+        const directory = parts.slice(0, depth).join('/');
+        if (depth === 1 && GENERIC_DIRECTORIES.has(directory))
+            continue;
+        if (specs.includes(directory + '/'))
+            return true;
+    }
+    return false;
+}
+/**
+ * Intersects the design's blast radius with the capability map and the path
+ * mentions in the canonical specs. Only existing code files can need a
+ * baseline: new files, tests, documentation and lockfiles are skipped.
+ */
+export function detectBaseline(context, change) {
+    const designFile = child(context.artifactRoot, 'openspec/changes/' + change + '/design.md');
+    const design = existsSync(designFile) ? readFileSync(designFile, 'utf8') : '';
+    const files = blastRadiusFiles(context, design);
+    const map = readCapabilityMap(context);
+    const mapped = new Set(Object.values(map.capabilities).flatMap(entry => entry.files));
+    const specs = specText(context);
+    const detection = { blastRadius: [], covered: [], uncovered: [], skipped: [] };
+    for (const file of files) {
+        const repository = context.repositories.find(item => item.id === file.repositoryId);
+        const name = qualifiedPath(context, file.repositoryId, file.path);
+        detection.blastRadius.push(name);
+        const absolute = repository ? path.resolve(repository.path, file.path) : undefined;
+        if (!absolute || !existsSync(absolute) || NOT_CODE.test(file.path) || TEST_FILE.test(file.path) || TEST_FILE_PATTERN.test(file.path) || /^(?:openspec|\.specrails)\//.test(file.path)) {
+            detection.skipped.push(name);
+            continue;
+        }
+        ;
+        (covered(name, mapped, specs) ? detection.covered : detection.uncovered).push(name);
+    }
+    return detection;
+}
+/** Throws a repairable error unless tasks.md has a Baseline group with a task and a delta spec adds at least one requirement. */
+export function validateBaselinePlan(context, change) {
+    const tasksFile = child(context.artifactRoot, 'openspec/changes/' + change + '/tasks.md');
+    const tasks = existsSync(tasksFile) ? readFileSync(tasksFile, 'utf8') : '';
+    const lines = tasks.split(/\r?\n/);
+    const heading = lines.findIndex(line => /^#{1,6}\s.*\bbaseline\b/i.test(line));
+    const next = heading < 0 ? -1 : lines.findIndex((line, index) => index > heading && /^#{1,6}\s/.test(line));
+    const group = heading < 0 ? [] : lines.slice(heading + 1, next < 0 ? undefined : next);
+    const problems = [];
+    if (!group.some(line => /^\s*-\s+\[[ x]\]/.test(line)))
+        problems.push('tasks.md needs a `## Baseline` task group (before the change tasks) with at least one task');
+    if (!readChangeDelta(context.artifactRoot, change).added.length)
+        problems.push('a delta spec needs the as-built requirements under `## ADDED Requirements`');
+    if (problems.length)
+        throw new Error(`Invalid baseline plan: ${problems.join(' and ')}. Update the artifacts through the workflow, then resend the same JSON reply.`);
+}
+/** Test files among changed files (the characterization tests). */
+export function testEdits(files) {
+    return files.filter(file => (TEST_FILE.test(file) || TEST_FILE_PATTERN.test(file)) && !/^(?:openspec|\.specrails)\//.test(file));
+}
+/** Files of the baseline stage that are not tests: the module must stay untouched until characterization passes. */
+export function nonTestEdits(files) {
+    // OpenSpec artifacts (the Baseline tasks and as-built spec, OpenSpec's own config) are not the module.
+    return files.filter(file => !(TEST_FILE.test(file) || TEST_FILE_PATTERN.test(file) || /^(?:openspec|\.specrails)\//.test(file)));
+}
+export function baselinePath(context) {
+    return path.join(pipelineStateDirectory(context), BASELINE_FILE);
+}
+export function writeBaselineRecord(context, entry) {
+    const record = { schemaVersion: BASELINE_SCHEMA_VERSION, recordedAt: new Date().toISOString(), ...entry };
+    write(baselinePath(context), JSON.stringify(record, null, 2) + '\n');
+    return record;
+}
+export function readBaselineRecord(context) {
+    try {
+        const file = baselinePath(context);
+        if (!existsSync(file))
+            return null;
+        const value = JSON.parse(readFileSync(file, 'utf8'));
+        return value && typeof value === 'object' && value.schemaVersion === BASELINE_SCHEMA_VERSION ? value : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/agent-runtime/graph/capability-map.d.ts

@@ -0,0 +1,29 @@
+import type { PipelineContext } from '../../pipeline/pipeline-state.js';
+/**
+ * `openspec/capability-map.json`: for every capability, the files archived
+ * changes touched. The archive node maintains it; baseline-on-touch reads it
+ * to decide whether the blast radius of a new change is already covered by a
+ * capability. Paths are repository-relative, prefixed `<repositoryId>:` for
+ * repositories other than the artifact repository.
+ */
+export declare const CAPABILITY_MAP_PATH = "openspec/capability-map.json";
+export declare const CAPABILITY_MAP_SCHEMA_VERSION = 1;
+export interface CapabilityEntry {
+    files: string[];
+    changes: string[];
+}
+export interface CapabilityMap {
+    schemaVersion: typeof CAPABILITY_MAP_SCHEMA_VERSION;
+    capabilities: Record<string, CapabilityEntry>;
+}
+export declare function readCapabilityMap(context: Pick<PipelineContext, 'artifactRoot'>): CapabilityMap;
+/** `<repositoryId>:<path>` outside the artifact repository, the bare path inside it. */
+export declare function qualifiedPath(context: Pick<PipelineContext, 'artifactRepositoryId'>, repositoryId: string, file: string): string;
+/** Capabilities a change's delta specs touch (active or archived change directory). */
+export declare function changeCapabilities(changeDirectory: string): string[];
+/**
+ * Merges an archived change into the map: its capabilities gain the files the
+ * run changed (OpenSpec artifacts and Core metadata excluded). Idempotent, so
+ * a repeated archive step after a crash records nothing twice.
+ */
+export declare function recordArchivedChange(context: PipelineContext, change: string, archiveDirectory: string): CapabilityMap;

package/dist/agent-runtime/graph/capability-map.js

@@ -0,0 +1,65 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { changeSet } from '../change-scope.js';
+import { child, write } from './artifacts.js';
+/**
+ * `openspec/capability-map.json`: for every capability, the files archived
+ * changes touched. The archive node maintains it; baseline-on-touch reads it
+ * to decide whether the blast radius of a new change is already covered by a
+ * capability. Paths are repository-relative, prefixed `<repositoryId>:` for
+ * repositories other than the artifact repository.
+ */
+export const CAPABILITY_MAP_PATH = 'openspec/capability-map.json';
+export const CAPABILITY_MAP_SCHEMA_VERSION = 1;
+const FILE_LIMIT = 2000;
+const CHANGE_LIMIT = 500;
+export function readCapabilityMap(context) {
+    try {
+        const file = child(context.artifactRoot, CAPABILITY_MAP_PATH);
+        if (!existsSync(file))
+            return { schemaVersion: CAPABILITY_MAP_SCHEMA_VERSION, capabilities: {} };
+        const value = JSON.parse(readFileSync(file, 'utf8'));
+        if (value?.schemaVersion !== CAPABILITY_MAP_SCHEMA_VERSION || !value.capabilities || typeof value.capabilities !== 'object')
+            return { schemaVersion: CAPABILITY_MAP_SCHEMA_VERSION, capabilities: {} };
+        return value;
+    }
+    catch {
+        return { schemaVersion: CAPABILITY_MAP_SCHEMA_VERSION, capabilities: {} };
+    }
+}
+/** `<repositoryId>:<path>` outside the artifact repository, the bare path inside it. */
+export function qualifiedPath(context, repositoryId, file) {
+    return repositoryId === context.artifactRepositoryId ? file : repositoryId + ':' + file;
+}
+/** Capabilities a change's delta specs touch (active or archived change directory). */
+export function changeCapabilities(changeDirectory) {
+    const specs = path.join(changeDirectory, 'specs');
+    try {
+        return readdirSync(specs, { withFileTypes: true }).filter(entry => entry.isDirectory() && existsSync(path.join(specs, entry.name, 'spec.md'))).map(entry => entry.name).sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Merges an archived change into the map: its capabilities gain the files the
+ * run changed (OpenSpec artifacts and Core metadata excluded). Idempotent, so
+ * a repeated archive step after a crash records nothing twice.
+ */
+export function recordArchivedChange(context, change, archiveDirectory) {
+    const capabilities = changeCapabilities(archiveDirectory);
+    const map = readCapabilityMap(context);
+    if (!capabilities.length)
+        return map;
+    const files = changeSet(context, change).flatMap(set => set.files.filter(file => file.status !== 'deleted' && !/^(?:openspec|\.specrails)\//.test(file.path)).map(file => qualifiedPath(context, set.repositoryId, file.path)));
+    for (const capability of capabilities) {
+        const entry = map.capabilities[capability] ?? { files: [], changes: [] };
+        map.capabilities[capability] = {
+            files: [...new Set([...entry.files, ...files])].sort().slice(0, FILE_LIMIT),
+            changes: [...new Set([...entry.changes, change])].slice(-CHANGE_LIMIT),
+        };
+    }
+    map.capabilities = Object.fromEntries(Object.entries(map.capabilities).sort(([left], [right]) => left.localeCompare(right, 'en')));
+    write(child(context.artifactRoot, CAPABILITY_MAP_PATH), JSON.stringify(map, null, 2) + '\n');
+    return map;
+}

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

@@ -0,0 +1,75 @@
+import { type PipelineContext } from '../../pipeline/pipeline-state.js';
+/**
+ * The architect's clarifications: the short list of ambiguities it found
+ * before planning, each with its impact and the default it would choose.
+ * A high-impact question without a safe default pauses the run (policy
+ * `ask-on-high`); everything else proceeds and is written down in design.md
+ * under Assumptions. Core also enforces a non-empty Non-Goals section.
+ */
+export declare const CLARIFICATIONS_SCHEMA_VERSION = 1;
+export declare const CLARIFICATION_LIMIT = 5;
+export declare const CLARIFICATION_IMPACTS: readonly ['high', 'medium', 'low'];
+export declare const CLARIFICATION_POLICIES: readonly ['ask-on-high', 'always-proceed'];
+export type ClarificationImpact = typeof CLARIFICATION_IMPACTS[number];
+export type ClarificationPolicy = typeof CLARIFICATION_POLICIES[number];
+export declare const DEFAULT_CLARIFICATION_POLICY: ClarificationPolicy;
+export interface Clarification {
+    question: string;
+    impact: ClarificationImpact;
+    /** The answer the architect would assume; null when no safe default exists. */
+    default: string | null;
+}
+/** The optional `clarifications` property of ARCHITECT_OUTPUT_SCHEMA. */
+export declare const CLARIFICATIONS_SCHEMA: Record<string, unknown>;
+/** Throws a repairable `Invalid architect clarifications` error for a malformed list. */
+export declare function parseClarifications(value: unknown): Clarification[];
+/** The clarifications that pause the run under the policy: high impact without a safe default. */
+export declare function blockingClarifications(clarifications: readonly Clarification[], policy?: ClarificationPolicy): Clarification[];
+/** True when a raw architect reply carries a high-impact clarification without a default: it may stop before authoring artifacts. */
+export declare function asksBeforePlanning(value: unknown): boolean;
+/** The single question the paused run carries (`pendingQuestion.question`). */
+export declare function clarificationQuestion(blocking: readonly Clarification[], lowConfidenceQuestion?: string): string;
+/**
+ * The content lines of a design.md section, or undefined when the section is
+ * absent. A section is a heading that contains the name (`## Non-Goals`,
+ * `## Goals / Non-Goals` without labels) or a bold label (`**Non-Goals:**`),
+ * which takes precedence; it ends at the next heading or label. HTML comments
+ * (template placeholders) and empty bullets do not count as content.
+ */
+export declare function designSection(markdown: string, name: RegExp): string[] | undefined;
+export declare const NON_GOALS: RegExp;
+export declare const ASSUMPTIONS: RegExp;
+/**
+ * Validates the active change's design.md once the architect proceeds:
+ * a non-empty Non-Goals section always, and a non-empty Assumptions section
+ * when it reported clarifications. Missing design.md is left to the design
+ * gate. Throws a repairable `Invalid design.md` error.
+ */
+export declare function validateDesignSections(context: PipelineContext, change: string, options: {
+    clarifications: readonly Clarification[];
+    policy?: ClarificationPolicy;
+}): void;
+export interface ClarificationsRecord {
+    schemaVersion: typeof CLARIFICATIONS_SCHEMA_VERSION;
+    change: string;
+    policy: ClarificationPolicy;
+    /** `awaiting-answers`: the run paused on `blocking`; `proceeded`: the architect planned on its defaults and the answers. */
+    status: 'awaiting-answers' | 'proceeded';
+    recordedAt: string;
+    clarifications: Clarification[];
+    /** The high-impact questions without a safe default the run paused on (empty once it proceeds). */
+    blocking: Clarification[];
+    /** Answers the requester gave so far, oldest first; authoritative for the design. */
+    answers: string[];
+    /** The Assumptions lines design.md records once the architect proceeds (empty when none). */
+    assumptions: string[];
+}
+export declare const CLARIFICATIONS_FILE = "clarifications.json";
+export declare function clarificationsPath(context: Pick<PipelineContext, 'backlogRoot' | 'runId'>): string;
+export declare function writeClarificationsRecord(context: PipelineContext, entry: Omit<ClarificationsRecord, 'schemaVersion' | 'recordedAt' | 'assumptions'> & {
+    assumptions?: string[];
+}): ClarificationsRecord;
+/** The Assumptions lines of the active change's design.md, for the host record. */
+export declare function designAssumptions(context: PipelineContext, change: string): string[];
+/** The latest clarifications record of a run, or null when the architect has not recorded one (or it is unreadable). */
+export declare function readClarificationsRecord(context: Pick<PipelineContext, 'backlogRoot' | 'runId'>): ClarificationsRecord | null;