specrails-core 6.6.4 → 6.7.0

package/dist/shared/secret-redaction.js

@@ -0,0 +1,184 @@
+/**
+ * Deterministic secret redaction for text and structured values that Core
+ * persists for display (the agent session journal).
+ *
+ * Every pattern is bounded: quantifiers have explicit upper limits and no
+ * pattern nests unbounded repetition, so the work per input character is
+ * constant and a 1 MB string redacts in linear time. PEM blocks are found with
+ * `indexOf`, not a regex, for the same reason.
+ *
+ * The rules favour leaking less over keeping every byte: a value assigned to a
+ * secret-like name is replaced even when it is not a credential (for example
+ * `token = readToken()` in a file read). Words that merely contain a secret
+ * word are not names: `author`, `authority`, `authenticate`, `max_tokens` and
+ * `tokenizer` stay readable. Bare `session` / `sessionId` are protocol
+ * identifiers and are not redacted; `session_token`, `session_secret`,
+ * `session_key` and `session_cookie` are.
+ *
+ * Known limits (documented in docs/agent-sessions/journal.md):
+ * - A secret split across two separately redacted strings (for example two
+ *   streamed output deltas) can leak the part after the split.
+ * - Short flags such as `mysql -pSECRET` and secrets with no recognisable name
+ *   or format are not detected.
+ *
+ * `src/pipeline/pipeline-state.ts` keeps its own self-contained
+ * `redactRuntimeText` because it is copied into projects and may only use Node
+ * built-ins; it is not replaced by this module.
+ */
+export const REDACTED = '[REDACTED]';
+const MAX_PEM_BODY = 16_384;
+/**
+ * Secret words inside a normalized (lower-case, `_`-separated) name.
+ * `auth` must end a word so `author`/`authority`/`authenticate` do not match.
+ * `token` must not be followed by `s`/`iz` so token counts and tokenizers stay.
+ */
+const SECRET_NAME = /(?:passw(?:or)?d|passphrase|secret|token(?!s|iz)|api_?key|access_?key|private_?key|signing_?key|encryption_?key|credentials?|(?:^|_)auth(?:orization)?(?:_|$)|bearer|cookie|session_(?:token|secret|key|cookie))/;
+/** Lower-case and split camelCase / kebab-case / dotted names into `_` words. */
+function normalizeName(name) {
+    return name
+        .slice(0, 128)
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_');
+}
+/** True when a key, variable or flag name looks like it holds a secret. */
+export function isSecretName(name) {
+    return SECRET_NAME.test(normalizeName(name));
+}
+// ── Inline patterns ─────────────────────────────────────────────────────────
+/** Well-known credential formats, replaced wherever they appear. */
+const KNOWN_FORMATS = [
+    // OpenAI / Anthropic style keys: sk-..., sk-proj-..., sk-ant-...; must contain a digit.
+    /\bsk-(?=[A-Za-z0-9_-]{0,200}\d)[A-Za-z0-9_-]{20,512}/g,
+    // GitHub tokens.
+    /\bgh[pousr]_[A-Za-z0-9]{36,255}\b/g,
+    /\bgithub_pat_[A-Za-z0-9_]{22,255}\b/g,
+    // GitLab and npm tokens.
+    /\bglpat-[A-Za-z0-9_-]{20,255}\b/g,
+    /\bnpm_[A-Za-z0-9]{36,255}\b/g,
+    // Slack tokens.
+    /\bxox[abeoprs]-[A-Za-z0-9-]{10,255}/g,
+    /\bxapp-[A-Za-z0-9-]{10,255}/g,
+    // AWS access key ids.
+    /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g,
+    // Google API keys.
+    /\bAIza[0-9A-Za-z_-]{35}(?![0-9A-Za-z_-])/g,
+    // JSON Web Tokens.
+    /\beyJ[A-Za-z0-9_-]{8,4096}\.eyJ[A-Za-z0-9_-]{8,4096}\.[A-Za-z0-9_-]{8,4096}/g,
+];
+/** `Authorization: Bearer x`, `"authorization": "Basic x"`, `Proxy-Authorization=...`; keeps the scheme. */
+const AUTHORIZATION_HEADER = /\b((?:proxy-)?authorization["']?[ \t]{0,8}[:=][ \t]{0,8}["']?)((?:bearer|basic|token|digest|negotiate)[ \t]{1,8})?([^\s"'`,;]{1,4096})/gi;
+/** A standalone `Bearer <token>` (the token must be long enough not to be prose). */
+const BEARER = /\b(bearer[ \t]{1,8})([A-Za-z0-9._~+/-]{16,4096}=*)/gi;
+/** `scheme://user:password@host` → keeps the user and host. */
+const URL_CREDENTIALS = /\b([a-z][a-z0-9+.-]{0,20}:\/\/[^\s:/@]{1,256}:)([^\s/@]{1,256})(@)/gi;
+/**
+ * `--token v`, `--api-key=v`, `--password "v"`: the flag name must END with the
+ * secret word, so `--password-stdin` or `--token-file` are left alone; a value
+ * starting with `-` is the next flag, not a secret.
+ */
+const SECRET_FLAG = /(^|[\s"'=])(--?(?:[a-z0-9]{1,24}[-_]){0,4}(?:token|api[-_]?key|apikey|password|passwd|passphrase|secret|private[-_]?key|access[-_]?key|auth|credentials?))(=|[ \t]{1,8})("[^"\n]{0,4096}"|'[^'\n]{0,4096}'|[^\s"'-][^\s"']{0,4095})/gi;
+/**
+ * `NAME=value`, `NAME: value`, `"name": "value"`, `export NAME='v'` where the
+ * name contains a secret word. The name starts at a non-name character so
+ * matching is attempted only at word starts; `isSecretName` then refines it.
+ */
+const ASSIGNMENT = /(?<![A-Za-z0-9_.-])(["']?)([A-Za-z_][A-Za-z0-9_.-]{0,127})\1([ \t]{0,4}[:=][ \t]{0,4})("[^"\n]{0,4096}"|'[^'\n]{0,4096}'|\[REDACTED\][^\s"',;&|<>(){}[\]]{1,4096}|(?![ \t]|\/\/)[^\s"',;&|<>(){}[\]]{1,4096})/g;
+/** Values that are not secrets even after a secret-like name (types, flags, empty literals). */
+const KEPT_VALUES = new Set(['', 'true', 'false', 'null', 'undefined', 'none', 'string', 'number', 'boolean', 'unknown', 'any', 'required', 'optional']);
+const PEM_BEGIN = /-----BEGIN [A-Z0-9 ]{0,40}PRIVATE KEY-----/g;
+function replaceValue(quoted) {
+    if (quoted.startsWith('"') && quoted.endsWith('"') && quoted.length >= 2)
+        return `"${REDACTED}"`;
+    if (quoted.startsWith("'") && quoted.endsWith("'") && quoted.length >= 2)
+        return `'${REDACTED}'`;
+    return REDACTED;
+}
+/** PEM private key blocks: BEGIN..END, or BEGIN plus its base64 body when END is missing (truncated output). */
+function redactPem(text) {
+    if (!text.includes('PRIVATE KEY-----'))
+        return text;
+    let out = '';
+    let cursor = 0;
+    // The next END marker is searched once and reused, so a text full of BEGIN
+    // markers without END stays linear.
+    let nextEnd = -2;
+    PEM_BEGIN.lastIndex = 0;
+    for (let match = PEM_BEGIN.exec(text); match; match = PEM_BEGIN.exec(text)) {
+        const begin = match.index;
+        if (begin < cursor)
+            continue;
+        const bodyStart = begin + match[0].length;
+        if (nextEnd !== -1 && nextEnd < bodyStart)
+            nextEnd = text.indexOf('-----END ', bodyStart);
+        const endMarker = nextEnd;
+        let stop;
+        if (endMarker >= 0 && endMarker - bodyStart <= MAX_PEM_BODY) {
+            const close = text.indexOf('-----', endMarker + 9);
+            stop = close >= 0 && close - endMarker <= 60 ? close + 5 : endMarker + 9;
+        }
+        else {
+            stop = bodyStart;
+            const limit = Math.min(text.length, bodyStart + MAX_PEM_BODY);
+            while (stop < limit && /[A-Za-z0-9+/=\s]/.test(text[stop]))
+                stop++;
+        }
+        out += text.slice(cursor, begin) + REDACTED;
+        cursor = stop;
+        PEM_BEGIN.lastIndex = Math.max(stop, bodyStart);
+    }
+    return out + text.slice(cursor);
+}
+/**
+ * Replace secrets inside free text. Idempotent: redacting a redacted string
+ * returns it unchanged. Non-secret text is returned byte for byte.
+ */
+export function redactSecrets(text) {
+    if (text.length === 0)
+        return text;
+    let result = redactPem(text);
+    for (const pattern of KNOWN_FORMATS)
+        result = result.replace(pattern, REDACTED);
+    result = result.replace(AUTHORIZATION_HEADER, (_match, prefix, scheme) => `${prefix}${scheme ?? ''}${REDACTED}`);
+    result = result.replace(BEARER, (_match, prefix) => `${prefix}${REDACTED}`);
+    result = result.replace(URL_CREDENTIALS, (_match, prefix, _password, at) => `${prefix}${REDACTED}${at}`);
+    result = result.replace(SECRET_FLAG, (_match, lead, flag, separator, value) => `${lead}${flag}${separator}${replaceValue(value)}`);
+    result = result.replace(ASSIGNMENT, (match, quote, name, separator, value, offset, whole) => {
+        if (!isSecretName(name))
+            return match;
+        const bare = value.replace(/^["']|["']$/g, '');
+        if (bare === REDACTED || KEPT_VALUES.has(bare.toLowerCase()) || bare.startsWith('$'))
+            return match;
+        // `Authorization: Bearer [REDACTED]` was already handled: do not take the scheme for the value.
+        if (whole.slice(offset + match.length, offset + match.length + 24).trimStart().startsWith(REDACTED))
+            return match;
+        return `${quote}${name}${quote}${separator}${replaceValue(value)}`;
+    });
+    return result;
+}
+/**
+ * Redact a JSON-like value: object entries whose key is secret-like have their
+ * string leaves replaced; every other string goes through `redactSecrets`.
+ * Numbers, booleans and null are kept (a numeric `max_tokens` stays readable).
+ * Returns a new value; the input is not mutated. Depth is bounded.
+ */
+export function redactSecretsDeep(value) {
+    return redactValue(value, false, 0);
+}
+const MAX_DEPTH = 32;
+function redactValue(value, secret, depth) {
+    if (typeof value === 'string')
+        return secret ? (value.length === 0 ? value : REDACTED) : redactSecrets(value);
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (depth >= MAX_DEPTH)
+        return secret ? REDACTED : value;
+    if (Array.isArray(value))
+        return value.map((item) => redactValue(item, secret, depth + 1));
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        out[key] = redactValue(item, secret || isSecretName(key), depth + 1);
+    }
+    return out;
+}

package/integration-contract.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "5.2",
+  "schemaVersion": "5.9",
   "providers": {
     "claude": {
       "cli": {
@@ -242,6 +242,7 @@
       "fork",
       "signal",
       "cancel",
+      "pause",
       "host"
     ],
     "cliPresentationOperations": [
@@ -254,6 +255,126 @@
     "eventStream": "run/resume emit JSON lines typed workflow-event, agent-event, verification-output, span ({traceId, spanId, name, stepId, attempt, visit, startedAt, endedAt, status, usage?, error?}) and a final runtime-result",
     "reviewGate": "review.minScore and review.aspects may only tighten Core's own gate (minScore 70, security 75, other aspects 60); the pipeline journal enforces the floor",
     "acceptance": "The reviewer certifies every frozen acceptance criterion by specId and criterionIndex; Core records the verification commands it ran as required checks and binds the report to the exact candidate before the reviewer verdict",
+    "reviewBrief": {
+      "version": 1,
+      "capability": "reviewBrief",
+      "advisory": "The reviewer's optional risk brief never changes the approval gate",
+      "runResult": "runtime-result.reviewBrief: {schemaVersion: 1, change, approved, score, recordedAt, brief | null, diagnostic?} | null (engine 1 builtin runs)",
+      "recordPath": "<backlogRoot>/.specrails/pipeline/<runId>/review-brief.json",
+      "confidenceScore": "openspec/changes/<change>/confidence-score.json brief (approved verdicts; archived with the change)",
+      "stepOutput": "reviewer step output brief / briefDiagnostic; engine 2 implementation output review.brief",
+      "documentation": "docs/agent-runtime.md#reviewer-risk-brief"
+    },
+    "architectClarifications": {
+      "version": 1,
+      "capability": "architectClarifications",
+      "output": "architect reply clarifications: [{question, impact: high|medium|low, default: string | null}] (at most 5) before planning",
+      "policy": "config architect.clarifications: ask-on-high (default) | always-proceed",
+      "pause": "ask-on-high and a high-impact clarification with default null pauses the run with pendingQuestion (the questions, numbered when several); resume --answer feeds the answer to the architect as authoritative",
+      "proceed": "otherwise the architect plans on its defaults and records them under Assumptions in design.md",
+      "designSections": "design.md must contain a non-empty Non-Goals section (and Assumptions when clarifications were listed); a missing section spends the architect's single repair turn",
+      "runResult": "runtime-result.clarifications: {schemaVersion: 1, change, policy, status: awaiting-answers | proceeded, recordedAt, clarifications, blocking, answers, assumptions} | null (engine 1 builtin runs)",
+      "recordPath": "<backlogRoot>/.specrails/pipeline/<runId>/clarifications.json",
+      "stepOutput": "architect step output clarifications; graph state architecture.clarifications",
+      "documentation": "docs/agent-runtime.md#architect-clarifications"
+    },
+    "specTrace": {
+      "version": 1,
+      "capability": "specTrace",
+      "requirementId": "<capability>/<slug> from '### Requirement: <name>' in openspec/specs/<capability>/spec.md (and the change's ADDED/MODIFIED/RENAMED deltas); slug: NFKD without accents, lowercase, every run of non-alphanumerics one '-', no leading or trailing '-'",
+      "testTags": "[spec:<capability>/<slug>] in a test title, or a '// spec: <capability>/<slug>' comment ('# spec:' for Python and shell) on the line before the test; any language",
+      "states": "demonstrated: tagged test file reached by a verification command that exited 0; undemonstrated: reason no-test | not-executed | failed; untagged: tags that match no requirement (advisory)",
+      "report": "{schemaVersion: 1, generatedAt, changes, evidence: receipt | tests-passed | none, receiptId, requirements, demonstrated[{id, name, tests}], undemonstrated[{id, name, reason, tests}], untagged[{tag, repositoryId, file, line, form}], touched, touchedUndemonstrated, scannedFiles}",
+      "reportPath": "<backlogRoot>/.specrails/pipeline/<runId>/spec-trace.json (written after each passing verification, bound to the receipt id)",
+      "runResult": "runtime-result.specTrace: the report | null (engine 1 builtin runs)",
+      "advisory": "The trace never changes verification or acceptance status; the acceptance report carries a finding 'Spec trace (advisory, receipt <id>): Requirements demonstrated X/Y…', the reviewer treats a touched requirement without a demonstrated tag as an issue",
+      "divergences": "reviewer check 9 fills brief.divergences[{capability, requirement, observed}] with spec claims of touched capabilities the code contradicts",
+      "cli": "specrails-core pipeline trace [--root <dir>] [--context <context.json>] [--change <name>[,...]] [--tests <glob>[,...]] [--tests-passed] [--check] [--json] [--out <file>]; installed projects also get node .specrails/runtime/trace.mjs; normal mode exits 0, --check exits 1 when a requirement touched by the change is not demonstrated",
+      "driftSweepDefinition": "src/agent-runtime/engine/__fixtures__/drift-sweep.json (read-only role-turn of a host-declared read role drift-auditor; structured output {divergences[{capability, requirement, observed}], unchecked[]})",
+      "documentation": "docs/agent-runtime.md#requirement-traceability"
+    },
+    "baselineOnTouch": {
+      "version": 1,
+      "capability": "baselineOnTouch",
+      "config": "baselineOnTouch: boolean (default false) in .specrails/agent-runtime.json",
+      "capabilityMap": "openspec/capability-map.json {schemaVersion: 1, capabilities: {<capability>: {files: string[], changes: string[]}}}; the archive step merges the files each archived change touched into every capability of its delta specs (paths prefixed '<repositoryId>:' outside the artifact repository); excluded from the reviewed candidate",
+      "detection": "after planning, design.md Blast radius files that exist, are code (not tests, docs or lockfiles) and appear neither in the capability map nor as a path or specific directory in openspec/specs are uncovered",
+      "plan": "uncovered files make the architect add a '## 0. Baseline' task group (characterization tests of current behaviour plus a minimal as-built spec under ADDED Requirements, requirements tagged per specTrace) in the same session",
+      "hardRule": "the developer's first turn writes only the Baseline group; Core refuses non-test edits and runs the verification plan on the unchanged code; failure stops the run (status blocked, error code baseline_characterization_failed) before the developer touches the module",
+      "recordPath": "<backlogRoot>/.specrails/pipeline/<runId>/baseline.json {schemaVersion: 1, change, status: not-needed | planned | passed | failed | violated, recordedAt, detection {blastRadius, covered, uncovered, skipped}, tests, receiptId?, reason?}",
+      "runResult": "runtime-result.baseline: the record | null (engine 1 builtin runs)",
+      "cost": "baseline turns run with invocation kind 'baseline'; efficiencySummary.invocations.byKind.baseline and efficiencySummary.baseline {invocations, roles, costUsd, inputTokens, outputTokens} keep their spend apart",
+      "documentation": "docs/agent-runtime.md#baseline-on-touch"
+    },
+    "rulesInventory": {
+      "version": 1,
+      "capability": "rulesInventory",
+      "cli": "specrails-core rules inventory [--root <repo>] [--artifact-root <dir>] [--offline] [--reclassify] [--json]; exits 0 and always writes the inventory (classification problems are reported in classification.status); init runs it offline after installing",
+      "path": "<artifactRoot>/.specrails/rules.json (the directory that holds .specrails/agent-runtime.json); the runtime reads <backlogRoot>/.specrails/rules.json, then <artifactRoot>/.specrails/rules.json",
+      "schema": "{schemaVersion: 1, generatedAt, gates[{id, kind: lint | format | typecheck | test | architecture | hook | ci | spec, command, source}], rules[{id, text, source: '<file>:<line>', status: enforcedBy | automatable | humanOnly | unclassified, enforcedBy?, proposedCheck?}], classification {status: classified | cached | offline | unavailable | failed | empty, provider?, model?, reason?, classifiedAt?, usage?}}",
+      "gates": "deterministic discovery in the repository: package scripts (lint, format, typecheck, test, architecture, openspec), lint/format configs (ESLint, Biome, Prettier, Ruff, Black, mypy, golangci-lint, rustfmt, clippy, RuboCop), tsconfig strict, architecture tests and dependency-cruiser, git hooks (.husky, .githooks, pre-commit, lefthook), check-like run steps of .github/workflows, openspec validate",
+      "rules": "list items and strongly normative sentences of CLAUDE.md, AGENTS.md, CONTRIBUTING.md (also .github/ and docs/), outside code fences, tables and specrails-managed blocks; at most 200; id r-<12 hex> = hash of file and statement, stable across line moves",
+      "classification": "one provider call (agents.architect of .specrails/agent-runtime.json, read-only, no role instructions) classifies only rules without a cached classification; the model never adds, drops or rewrites a statement; offline, without configuration or on failure the rules stay unclassified",
+      "reviewer": "humanOnly rules are listed to the reviewer, who copies the ones the change could break into brief.humanChecks",
+      "verification": "with no host verification configured, the architect is offered the discovered gate commands as the default verification proposal for the artifact repository",
+      "claudeInstructions": "Claude Code installs get the sentinel-managed block (<!-- specrails-managed:start/end -->) in the root CLAUDE.md, like codex AGENTS.md, gemini GEMINI.md and kimi .kimi-code/AGENTS.md",
+      "documentation": "docs/agent-runtime.md#project-rules-inventory"
+    },
+    "failureClassification": {
+      "version": 1,
+      "capability": "failureClassification",
+      "kinds": [
+        "tests_failed",
+        "provider_limit",
+        "environment",
+        "blocked",
+        "timeout",
+        "tool_inactivity",
+        "crash",
+        "unknown"
+      ],
+      "record": "{kind, phase?, rounds?, resetAt?, detail?, resumablePhase?, confidence: high | low}",
+      "runResult": "runtime-result.failure and runtime-status.failure (both engines): the record when the run status is failed or blocked; absent otherwise. A run Core could not start (fatal argument or configuration error) carries none.",
+      "semantics": "classified only from signals the run already produced (status, the failing step or node, error codes and messages); a failure it cannot tie to a documented signal is kind unknown with confidence low and a host must show it as an unknown cause. phase is the failing step id (engine 1) or node path (engine 2); rounds counts visits of correction steps; resetAt is the provider's own wording of the reset time, never reformatted; detail is one bounded sentence from the run's own error; resumablePhase is the step runtime resume continues from when resuming can help (blocked runs and transient kinds), absent for a plain failed verification.",
+      "kindMeaning": {
+        "tests_failed": "verification kept failing, or the correction loop stopped on the same failing change",
+        "provider_limit": "the provider reported a session, usage, rate or quota limit",
+        "environment": "the host environment cannot run verification (credentials, toolchain, setup command, non-deterministic generated output, edits outside the scope)",
+        "blocked": "a configured limit stopped the run: baseline characterization, attempt or budget limits, a reviewer rejecting the same change",
+        "timeout": "the total execution or active-duration limit elapsed",
+        "tool_inactivity": "the agent produced no tool call, reply or usage within the idle limit",
+        "crash": "the provider process, endpoint, lease or storage failed under the run",
+        "unknown": "no documented signal matched"
+      },
+      "compatibility": "additive: hosts ignore an absent field; an older Core never emits it and the host derives a low-confidence diagnosis from the error text",
+      "documentation": "docs/agent-runtime.md#failure-classification"
+    },
+    "findingLocations": {
+      "version": 1,
+      "capability": "findingLocations",
+      "record": "acceptance.findingLocations[] = {finding, path, line?, endLine?}",
+      "location": "state.json acceptance.findingLocations in the run's pipeline directory, next to acceptance.findings (which stays string[])",
+      "semantics": "finding is the zero-based index into acceptance.findings; path is repository-relative with forward slashes (never absolute, never containing ..); line and endLine are 1-based and optional (endLine only with line, greater than it). Core drops a malformed anchor instead of failing the review, keeps at most 50 and one per finding, and never invents a location: a finding without an entry is unanchored.",
+      "compatibility": "additive: hosts ignore an absent field and render the finding unanchored; an older Core never emits it",
+      "documentation": "docs/agent-runtime.md#finding-locations"
+    },
+    "pauseRuns": {
+      "version": 1,
+      "capability": "pauseRuns",
+      "cli": "specrails-core runtime pause --context <json> | --run-dir <dir> [--request-id <id>] [--reason <token>]; engine 2 runs only; always exits 0 with one line {type: runtime-pause-result, runId, requestId, reason, outcome, status, createdAt?}",
+      "reason": "lowercase token matching ^[a-z][a-z0-9-]{0,63}$, default requested (Desktop's daily budget guard sends budget)",
+      "outcomes": [
+        "requested",
+        "paused",
+        "already-paused",
+        "not-running",
+        "terminal"
+      ],
+      "semantics": "requested: the run executes under a live lease; the idempotent inbox request (same request id and reason returns the original record, a different reason is control_conflict) lets every admitted attempt finish and commit, refuses the next admission, settles status paused and releases the lease (the run process exits 2). paused: an ownerless run still marked running is settled paused directly. already-paused, not-running (failed, interrupted, blocked) and terminal (succeeded, cancelled, completed) change nothing. A run of another Core package is refused with resume_incompatible.",
+      "status": "runtime status and runtime-result state.pause {requestId, reason, at} while a requested pause holds the run (no pendingInterrupts); events pause_requested {requestId, reason} and workflow_paused {requestId, reason}",
+      "resume": "runtime resume continues a paused run from its last committed step without repeating it and discards pause requests that arrived before the resume",
+      "documentation": "docs/agent-runtime.md#pausing-a-run"
+    },
     "configSchemaPath": "schemas/agent-runtime.schema.json",
     "configSchemaExport": "specrails-core/schemas/agent-runtime.schema.json",
     "projectConfigPath": ".specrails/agent-runtime.json",
@@ -291,10 +412,10 @@
     },
     "recovery": "Explicit resume uses frozen configuration and revalidates Core evidence; interrupted writes require named recovery; grants persist until evidence invalidation.",
     "delivery": "Core implements through archive; the host owns worktrees, commits, pushes, PRs and backlog delivery. A standalone continuation does not restart Desktop delivery.",
-    "specificationFormat": "Architect specs contain complete main-spec replacements, including unchanged requirements; archive does not merge partial delta snippets.",
+    "specificationFormat": "Architect specs are OpenSpec delta specs authored through the official fast-forward skill (ADDED/MODIFIED/REMOVED/RENAMED requirements); existing requirements are preserved through delta semantics and merged into main specs by OpenSpec archive. Complete replacement specs are not fabricated.",
     "compatibility": "Additive to integration schema 4 and execution context schema 1. Legacy workflows and profile v1 remain supported. Hosts must check RUNTIME_API_VERSION, not infer runtime support from Core major version.",
     "documentation": "docs/agent-runtime.md",
-    "instructionsVersion": "14",
+    "instructionsVersion": "17",
     "workflowVersion": "7",
     "engines": [
       1,
@@ -303,7 +424,7 @@
     "engine": {
       "version": 2,
       "definitionSchema": "schemas/workflow-definition.schema.json",
-      "nodeKindsVersion": 7
+      "nodeKindsVersion": 8
     },
     "nodeKinds": [
       "prompt",
@@ -324,7 +445,8 @@
       "component",
       "map",
       "implementation",
-      "join"
+      "join",
+      "derive-change"
     ],
     "implementationSteps": {
       "version": 1,
@@ -346,6 +468,47 @@
     "structuredOutput": "Claude receives --json-schema and Codex --output-schema for architect/reviewer replies; other providers are parsed leniently.",
     "resumeBudget": "An explicit resume resets the transition ceiling and grants the developer a fresh maxAttempts budget.",
     "defaultImplementationEngine": true,
+    "deriveChange": {
+      "version": 1,
+      "capability": "deriveChange",
+      "nodeKind": "derive-change",
+      "role": "deriver",
+      "roleAssignment": "Core engine role: access read, artifacts all, openspecSkill openspec-ff-change; takes agents.architect's provider assignment; instructions are Core's and the id is reserved for custom roles",
+      "params": {
+        "change": "required; the run's frozen change name ({{run.changeId}})",
+        "summaryPath": "optional; file relative to <backlogRoot>/.specrails/pipeline/<runId>/, at most 32768 bytes, no symlinks or .. segments; absent or empty derives from the diff alone; optional front matter 'transcriptTurns: <n>'",
+        "feedback": "optional string (at most 32000 characters, normally {{run.latestFindings}}); when non-blank the deriver re-derives the existing change in place after a correction round, with the findings bounded to 8000 characters as untrusted fenced data under '## Re-derivation after a correction round'",
+        "timeoutMs": "optional",
+        "idleTimeoutMs": "optional"
+      },
+      "outcomes": [
+        "pass",
+        "fail"
+      ],
+      "diff": "change-scope changeSet: repositories[].baseSha (or HEAD at first measurement) to the working tree; untracked files present at the first measurement are pre-existing; .specrails/ and the change's own openspec/changes/<change>/ are excluded",
+      "emptyChangeSet": "node fails with error code empty_change_set before any provider call",
+      "derivationArtifact": "<backlogRoot>/.specrails/pipeline/<runId>/agent-workflow/artifacts/<scope-node digest>/derivation.json; the absolute path is output.derivationPath and the report is output.derivation",
+      "derivationFields": [
+        "schemaVersion",
+        "change",
+        "base",
+        "head",
+        "files",
+        "explained",
+        "unexplainedFiles",
+        "tasks",
+        "requirementsAdded",
+        "requirementsModified",
+        "confidence",
+        "transcriptTurnsUsed",
+        "repositories",
+        "unexplainedOmitted"
+      ],
+      "verificationProposals": "output.structured.verification (at most 20, architect schema); bind them with verify additionalCommandsFrom: <derive node id>",
+      "reviewer": "A reviewer role-turn in the same run receives derivation.json; every unexplained file is an issue",
+      "correctionLoop": "role-turn stance 'fixer' (write roles only; the built-in developer takes the FIXER instructions, rolePrompts.fixer and config.fixer in a fresh session). flow-spec routes a rejected review or a failing check to at most correctionLimit (2) rounds of fix then derive (feedback) then check then review; a fixer turn that leaves $outputs.fix.candidateHash equal to $outputs.check.candidateHash, or a spent budget, ends at end node changes-requested with reason 'Flow → Spec: the reviewer requested changes that <n> correction round(s) did not resolve. Latest findings: <findings>'",
+      "referenceDefinition": "src/agent-runtime/engine/__fixtures__/flow-spec.json"
+    },
     "openRoles": {
       "version": 1,
       "builtinRoles": [
@@ -412,8 +575,15 @@
       ],
       "capabilities": [
         "sessions",
-        "delegation"
-      ]
+        "delegation",
+        "flowSessions"
+      ],
+      "deliveries": [
+        "queue",
+        "steer",
+        "interrupt"
+      ],
+      "interruptDelivery": "session.send delivery 'interrupt' cuts the running turn (turn.completed status 'interrupted', partial text kept) and runs the input as the next turn, ahead of inputs queued before it; on an idle session it behaves like 'queue'. Drivers declare capabilities.interrupt 'native' (provider primitive) or 'emulated'; runtime api advertises flowSessions"
     }
   },
   "execution": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "6.6.4",
+  "version": "6.7.0",
   "description": "Agent workflow engine for specrails-desktop: provider-independent installer and programmatic agent runtime for Claude Code and Codex",
   "type": "module",
   "exports": {
@@ -82,23 +82,23 @@
     "test:coverage": "npm run build && vitest run --coverage",
     "dogfood": "npm run build && node bin/specrails-core.mjs init --yes",
     "prepack": "npm run build",
-    "test:scripts": "node --test scripts/release-utils.test.mjs scripts/ci-tests.test.mjs scripts/evaluate-definition-corpus.test.mjs",
+    "test:scripts": "node --test scripts/release-utils.test.mjs scripts/ci-tests.test.mjs scripts/evaluate-definition-corpus.test.mjs scripts/contract-policy.test.mjs",
     "test:engine-spikes": "npm run build && node scripts/run-engine-spikes.mjs",
     "check:package": "npm run build && node scripts/verify-package.mjs",
     "ci": "npm run typecheck && npm run test:scripts && npm run test:coverage && npm run check:package"
   },
   "dependencies": {
-    "@fission-ai/openspec": "1.4.1",
-    "@langchain/core": "1.2.14",
-    "@langchain/langgraph": "1.4.18",
-    "@langchain/langgraph-checkpoint": "1.1.5",
-    "@modelcontextprotocol/sdk": "1.31.0",
+    "@fission-ai/openspec": "1.14.3",
+    "@langchain/core": "1.2.18",
+    "@langchain/langgraph": "1.5.1",
+    "@langchain/langgraph-checkpoint": "1.2.0",
+    "@modelcontextprotocol/sdk": "1.32.1",
     "ajv": "^8.20.0",
     "cross-spawn": "7.0.6",
     "js-yaml": "^5.4.3",
     "picocolors": "^1.1.1",
     "semver": "^7.8.5",
-    "zod": "4.6.5"
+    "zod": "4.6.7"
   },
   "devDependencies": {
     "@types/cross-spawn": "6.0.6",

package/pinned-versions.json

@@ -1,4 +1,4 @@
 {
   "$comment": "Pinned versions of third-party tools the installer fetches via npx. Edit and commit to bump deliberately.",
-  "openspec": "1.4.1"
+  "openspec": "1.14.3"
 }

package/schemas/agent-runtime.schema.json

@@ -137,6 +137,7 @@
     "verification": { "type": "array", "items": { "$ref": "#/definitions/checkCommand" } },
     "setup": { "type": "array", "description": "Idempotent commands the verify piece runs sequentially in the admitted workspace before each verification plan; a failing setup command blocks the run instead of starting a correction round.", "items": { "$ref": "#/definitions/checkCommand" } },
     "approvalBeforeArchive": { "type": "boolean" },
+    "baselineOnTouch": { "type": "boolean", "description": "When the blast radius reaches code no capability covers (openspec/capability-map.json or a path named in openspec/specs), the architect adds a Baseline task group (characterization tests plus a minimal as-built spec) whose tests must pass on the unchanged code before the developer touches the module. Default false." },
     "review": { "type": "object", "additionalProperties": false, "description": "Review gate thresholds; unset fields keep Core's defaults (score 70, security 75, other aspects 60).", "properties": {
       "minScore": { "$ref": "#/definitions/score" },
       "aspects": { "type": "object", "additionalProperties": false, "properties": {
@@ -145,7 +146,8 @@
       } }
     } },
     "architect": { "type": "object", "additionalProperties": false, "properties": {
-      "onLowConfidence": { "enum": ["ask", "proceed"], "description": "After one autonomous investigation pass, a still-low design either pauses with its question (ask, default) or proceeds on stated assumptions (proceed)." }
+      "onLowConfidence": { "enum": ["ask", "proceed"], "description": "After one autonomous investigation pass, a still-low design either pauses with its question (ask, default) or proceeds on stated assumptions (proceed)." },
+      "clarifications": { "enum": ["ask-on-high", "always-proceed"], "description": "Before planning, a high-impact clarification without a safe default either pauses the run with its question (ask-on-high, default) or the architect proceeds on stated assumptions written under Assumptions in design.md (always-proceed)." }
     } }
   },
   "definitions": {

package/schemas/workflow-definition.schema.json

@@ -251,6 +251,7 @@
             "component",
             "implementation",
             "implementation-step",
+            "derive-change",
             "artifact-contract",
             "end"
           ]

package/templates/settings/codex-config.toml

@@ -10,8 +10,9 @@ model = "{{MODEL_NAME}}"
 model_reasoning_effort = "medium"
 
 # Sandbox mode applied to interactive `codex` sessions launched from this
-# project. The desktop app passes `--sandbox workspace-write` per-spawn so this
-# setting only affects manual terminal use of codex inside this repo.
+# project. specrails runtime spawns set their own sandbox per invocation
+# (`danger-full-access` for write roles, `read-only` for read-only roles), so
+# this setting only affects manual terminal use of codex inside this repo.
 # Values: "read-only" | "workspace-write" | "danger-full-access".
 sandbox_mode = "workspace-write"