specrails-core 5.2.2 → 5.3.0

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

@@ -0,0 +1,210 @@
+export type PipelinePhase = 'architect' | 'developer' | 'reviewer' | 'archive' | 'ship' | 'ci';
+export type PhaseStatus = 'pending' | 'running' | 'done' | 'blocked' | 'failed' | 'skipped';
+export interface PipelineSpec {
+    id: string | number;
+    title: string;
+    description: string;
+    repositoryIds?: string[];
+    acceptanceCriteria?: string[];
+}
+export interface PipelineRepository {
+    id: string;
+    name: string;
+    path: string;
+    baseSha?: string;
+}
+export interface PipelineContext {
+    schemaVersion: 1;
+    runId: string;
+    backlogRoot: string;
+    backlogPath?: string;
+    artifactRoot: string;
+    artifactRepositoryId: string;
+    repositories: PipelineRepository[];
+    ownership: {
+        git: 'host' | 'core';
+        backlog: 'host' | 'core';
+        worktrees: 'host' | 'core';
+    };
+    specs: PipelineSpec[];
+}
+export interface VerificationCommand {
+    repositoryId: string;
+    command: string;
+    args: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+}
+/** `unverified` admits a full request whose commands do not cover every repository
+ *  (or cover none): the receipt then records which repositories ran no check. */
+export interface VerificationRequest {
+    kind: 'full' | 'scoped';
+    commands: VerificationCommand[];
+    unverified?: boolean;
+}
+export interface CommandReceipt {
+    repositoryId: string;
+    command: string;
+    args: string[];
+    cwd: string;
+    environmentPolicy?: 'isolated-transport-v1';
+    environmentHash: string;
+    environmentKeys: string[];
+    environmentOverrideKeys: string[];
+    environmentOverridesHash: string;
+    exitCode: number;
+    durationMs: number;
+    output: string;
+}
+export interface VerificationReceipt {
+    id: string;
+    kind: 'full' | 'scoped';
+    scopeHash: string;
+    candidateHash: string;
+    commands: CommandReceipt[];
+    completedAt: string;
+    valid: boolean;
+    reason?: string;
+    /** Repositories in scope that this receipt ran no command for (explicitly admitted by the request). */
+    unverifiedRepositories?: string[];
+}
+export interface AcceptanceCriterion {
+    specId: string;
+    criterionIndex: number;
+    requirement: string;
+    status: 'met' | 'exception' | 'blocked' | 'pending';
+    evidence: string[];
+    exception?: {
+        reason: string;
+        impact: string;
+        material: boolean;
+        acceptedBy: 'reviewer' | 'user' | 'host';
+        approvalEvidence: string;
+    };
+}
+export interface AcceptanceCheck {
+    name: string;
+    status: 'passed' | 'failed' | 'unavailable';
+    required: boolean;
+    evidence: string[];
+    /** What was measured and what remains outside the measurement. */
+    scope: string;
+    limitations: string;
+}
+export interface AcceptanceReport {
+    criteria: AcceptanceCriterion[];
+    checks: AcceptanceCheck[];
+    findings: string[];
+}
+export interface AcceptanceReceipt extends AcceptanceReport {
+    scopeHash: string;
+    candidateHash: string;
+    artifactHash: string;
+    recordedAt: string;
+}
+export interface PipelineCompletion {
+    implementation: 'complete' | 'incomplete';
+    validation: 'verified' | 'with-exceptions' | 'pending' | 'blocked';
+    archive: PhaseStatus;
+    delivery: 'pending-host' | 'complete' | 'pending';
+    reasons: string[];
+}
+interface PhaseRecord {
+    startedAt?: string;
+    durationMs?: number;
+    attempts?: number;
+    status: PhaseStatus;
+    reason?: string;
+    candidateHash?: string;
+    artifactHash?: string;
+    completedAt?: string;
+}
+export interface PipelineState {
+    schemaVersion: 1;
+    runId: string;
+    change: string;
+    context: PipelineContext;
+    scopeHash: string;
+    revision: number;
+    createdAt: string;
+    updatedAt: string;
+    phases: Record<PipelinePhase, PhaseRecord>;
+    verification?: VerificationReceipt;
+    acceptance?: AcceptanceReceipt;
+    archivePath?: string;
+    archiveApproval?: {
+        candidateHash: string;
+        artifactHash: string;
+        confidenceHash: string;
+        acceptanceHash: string;
+    };
+    artifactExclusions: string[];
+    preview?: {
+        baseHash: string;
+        files: PreviewFile[];
+        createdAt: string;
+    };
+}
+export interface PreviewFile {
+    repositoryId: string;
+    path: string;
+    operation: 'write' | 'delete';
+    sourcePath?: string;
+    contentHash?: string;
+}
+export declare function verificationEnvironment(env: NodeJS.ProcessEnv, overrides?: Record<string, string>, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
+export declare function validatePipelineContext(input: unknown): PipelineContext;
+export declare function pipelineStateDirectory(context: PipelineContext): string;
+export declare function fingerprintCandidate(state: PipelineState): string;
+export declare function initializePipeline(contextInput: unknown, change: string): PipelineState;
+declare function inspectReceipt(state: PipelineState, env?: NodeJS.ProcessEnv): {
+    valid: boolean;
+    reasons: string[];
+    receipt?: VerificationReceipt;
+};
+/** The frozen requirements an acceptance report must certify, in scope order. */
+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;
+declare function inspectAcceptance(state: PipelineState): {
+    valid: boolean;
+    status: PipelineCompletion['validation'];
+    reasons: string[];
+    receipt?: AcceptanceReceipt;
+};
+export declare function recordAcceptance(contextInput: unknown, input: unknown): PipelineState;
+export declare function checkArchive(contextInput: unknown): PipelineState;
+export declare function transitionPipeline(contextInput: unknown, phase: PipelinePhase, status: PhaseStatus, reason?: string): PipelineState;
+export declare function inspectPipeline(contextInput: unknown): {
+    schemaVersion: 1;
+    runId: string;
+    change: string;
+    context: PipelineContext;
+    stateDir: string;
+    resumePhase: PipelinePhase | null;
+    phases: PipelineState['phases'];
+    verification: ReturnType<typeof inspectReceipt>;
+    acceptance: ReturnType<typeof inspectAcceptance>;
+    completion: PipelineCompletion;
+};
+/**
+ * Native executables retain structured argv; Windows script shims need cmd.
+ * This runtime is copied as one standalone module into .specrails/runtime,
+ * without installer util/exec. Keep this builtins-only equivalent local rather
+ * than importing a helper absent from installed projects. Like runCommand, it
+ * handles Windows shims; unlike a shell string it refuses ambiguous arguments.
+ */
+export declare function verificationInvocation(command: string, args: string[], cwd: string, platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): {
+    command: string;
+    args: string[];
+    windowsVerbatimArguments?: boolean;
+};
+export declare function verifyPipeline(contextInput: unknown, raw: unknown, log?: (text: string) => void, signal?: AbortSignal): Promise<VerificationReceipt>;
+/** Validate a check plan without creating state or executing commands. */
+export declare function validateVerificationRequest(contextInput: unknown, raw: unknown): void;
+export declare function preparePreview(contextInput: unknown, raw: unknown): PipelineState;
+export declare function applyPreview(contextInput: unknown, verificationRequest: unknown, log?: (text: string) => void): Promise<VerificationReceipt>;
+export declare function runPipelineCommand(flags: Record<string, string | boolean>, positionals: string[]): Promise<number>;
+export declare function runPipelineCli(argv: string[]): Promise<number>;
+export {};

package/dist/installer/runtime/pipeline-state.js

@@ -4,15 +4,34 @@ import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, re
 import path from 'node:path';
 const PHASES = ['architect', 'developer', 'reviewer', 'archive', 'ship', 'ci'];
 // Session identity belongs to the agent transport, not the checked application.
-// Keep this list explicit: provider configuration, application inputs and host
-// scope/configuration (including SPECRAILS_*) must still invalidate receipts.
+// Remove these from check subprocesses too, so ignored identity cannot become
+// an unrecorded test input. Explicit command.env inputs remain bound overrides.
+// Keep provider configuration, application inputs and host scope/configuration
+// (including SPECRAILS_*) in the evidence; never exclude an entire prefix.
 const TRANSPORT_ENV_KEYS = new Set([
     '_', 'PWD', 'OLDPWD', 'SHLVL',
+    'AI_AGENT', 'CLAUDECODE', 'CLAUDE_CODE_ENTRYPOINT', 'CLAUDE_CODE_EXECPATH', 'CLAUDE_EFFORT',
     'CLAUDE_PID', 'CLAUDE_CODE_SESSION_ID', 'CLAUDE_CODE_MESSAGING_SOCKET',
     'CLAUDE_CODE_MESSAGING_TOKEN', 'CLAUDE_CODE_CHILD_SESSION',
 ]);
 function verificationEnvironmentKeys(env, overrideKeys = []) {
-    return Object.keys(env).filter((key) => env[key] !== undefined && !TRANSPORT_ENV_KEYS.has(key) && !overrideKeys.includes(key)).sort();
+    return Object.keys(normalizeVerificationEnvironment(env)).filter((key) => !TRANSPORT_ENV_KEYS.has(key) && !overrideKeys.includes(key)).sort();
+}
+function normalizeVerificationEnvironment(env, platform = process.platform) {
+    const result = Object.create(null);
+    for (const [raw, value] of Object.entries(env)) {
+        if (value === undefined)
+            continue;
+        const key = platform === 'win32' ? raw.toUpperCase() : raw;
+        if (Object.hasOwn(result, key) && result[key] !== value)
+            fail('Ambiguous verification environment key: ' + key);
+        result[key] = value;
+    }
+    return result;
+}
+export function verificationEnvironment(env, overrides = {}, platform = process.platform) {
+    const normalized = normalizeVerificationEnvironment(env, platform);
+    return { ...Object.fromEntries(Object.entries(normalized).filter(([key]) => !TRANSPORT_ENV_KEYS.has(key))), ...normalizeVerificationEnvironment(overrides, platform) };
 }
 const ID = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
 const slug = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -255,15 +274,28 @@ function trackedFiles(repo) {
     const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
     env.GIT_CONFIG_NOSYSTEM = '1';
     env.GIT_CONFIG_GLOBAL = process.platform === 'win32' ? 'NUL' : '/dev/null';
-    const result = spawnSync('git', ['-c', 'core.excludesFile=', '-C', repo.path, 'ls-files', '-z', '--cached', '--others', '--exclude-standard'], { env, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024, windowsHide: true });
-    if (result.error || result.status !== 0)
-        fail('Cannot fingerprint repository ' + repo.name + ': ' + (result.error?.message ?? result.stderr));
-    return [...new Set(result.stdout.split('\0').filter(Boolean))].sort();
+    const list = (args) => {
+        const result = spawnSync('git', ['-c', 'core.excludesFile=', '-C', repo.path, 'ls-files', '-z', ...args], { env, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024, windowsHide: true });
+        if (result.error || result.status !== 0)
+            fail('Cannot fingerprint repository ' + repo.name + ': ' + (result.error?.message ?? result.stderr));
+        return result.stdout.split('\0').filter(Boolean);
+    };
+    const tracked = new Set(list(['--cached']));
+    return [...new Set([...tracked, ...list(['--others', '--exclude-standard'])])].sort().map(file => ({ file, tracked: tracked.has(file) }));
+}
+function untrackedAgentMemory(relative) {
+    // Native project memory can be written automatically after a role finishes,
+    // even when the role keeps explicit notes under stateDir. Exclude only known
+    // generated memory roots; tracked files and provider settings/skills still
+    // belong to the candidate. Do not hide arbitrary provider directory content.
+    return ['.claude', '.codex', '.gemini', '.kimi-code', '.specrails'].some(provider => relative === provider + '/agent-memory' || relative.startsWith(provider + '/agent-memory/'));
 }
 export function fingerprintCandidate(state) {
     const entries = state.context.repositories.map((repo) => ({
         id: repo.id, path: repo.path,
-        files: trackedFiles(repo).filter((file) => !excluded(state, repo, relativeUnix(file))).map((file) => [relativeUnix(file), fileFingerprint(path.join(repo.path, file))]),
+        files: trackedFiles(repo)
+            .filter(({ file, tracked }) => !excluded(state, repo, relativeUnix(file)) && (tracked || !untrackedAgentMemory(relativeUnix(file))))
+            .map(({ file }) => [relativeUnix(file), fileFingerprint(path.join(repo.path, file))]),
     }));
     return digest(canonical(entries));
 }
@@ -314,7 +346,8 @@ export function initializePipeline(contextInput, change) {
     });
 }
 function environmentHash(keys, overrides = {}, env = process.env) {
-    return digest(canonical(Object.fromEntries(keys.map((key) => [key, overrides[key] ?? env[key] ?? null]))));
+    const normalized = normalizeVerificationEnvironment(env);
+    return digest(canonical(Object.fromEntries(keys.map((key) => [key, overrides[key] ?? normalized[key] ?? null]))));
 }
 function inspectReceipt(state, env = process.env) {
     const receipt = state.verification;
@@ -330,9 +363,19 @@ function inspectReceipt(state, env = process.env) {
     for (const command of receipt.commands) {
         if (command.exitCode !== 0)
             reasons.push('Command failed: ' + command.command);
+        if (command.environmentPolicy !== 'isolated-transport-v1')
+            reasons.push('Verification environment policy changed; run full verification again: ' + command.command);
         const currentKeys = verificationEnvironmentKeys(env, command.environmentOverrideKeys ?? []);
-        if (canonical(currentKeys) !== canonical(command.environmentKeys) || command.environmentHash !== environmentHash(currentKeys, {}, env))
-            reasons.push('Verification environment changed: ' + command.command);
+        if (canonical(currentKeys) !== canonical(command.environmentKeys) || command.environmentHash !== environmentHash(currentKeys, {}, env)) {
+            const previousKeys = command.environmentKeys ?? [];
+            const added = currentKeys.filter(key => !previousKeys.includes(key));
+            const removed = previousKeys.filter(key => !currentKeys.includes(key));
+            // Names explain process handoff drift without retaining or revealing
+            // values. A changed aggregate hash cannot identify which value changed.
+            const summarize = (keys) => keys.slice(0, 10).map(key => JSON.stringify(key)).join(', ') + (keys.length > 10 ? ` (+${keys.length - 10} more)` : '');
+            const details = [added.length ? 'added keys: ' + summarize(added) : '', removed.length ? 'removed keys: ' + summarize(removed) : ''].filter(Boolean);
+            reasons.push('Verification environment changed: ' + command.command + ' (' + (details.join('; ') || 'recorded environment values differ') + ')');
+        }
     }
     return { valid: reasons.length === 0, reasons: [...new Set(reasons)], receipt };
 }
@@ -374,6 +417,14 @@ function frozenCriteria(context) {
     return context.specs.flatMap(spec => (spec.acceptanceCriteria?.length ? spec.acceptanceCriteria : [spec.description || spec.title])
         .map((requirement, criterionIndex) => ({ specId: String(spec.id), criterionIndex, requirement })));
 }
+/** The frozen requirements an acceptance report must certify, in scope order. */
+export function frozenAcceptanceCriteria(contextInput) {
+    return frozenCriteria(validatePipelineContext(contextInput));
+}
+/** Validates a report against the frozen scope without recording it; throws the same errors `recordAcceptance` would. */
+export function validateAcceptanceReport(contextInput, input) {
+    return acceptanceReport(validatePipelineContext(contextInput), input);
+}
 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) {
@@ -651,12 +702,14 @@ export function verificationInvocation(command, args, cwd, platform = process.pl
     const quote = (value) => '"' + value + '"';
     return { command: env.ComSpec ?? env.COMSPEC ?? 'cmd.exe', args: ['/d', '/s', '/c', '"' + [resolved, ...args].map(quote).join(' ') + '"'], windowsVerbatimArguments: true };
 }
-async function executeCheck(command, log) {
+async function executeCheck(command, log, signal) {
     const started = Date.now();
-    const overrideKeys = Object.keys(command.env ?? {}).sort();
+    const overrides = normalizeVerificationEnvironment(command.env ?? {});
+    const overrideKeys = Object.keys(overrides).sort();
     const keys = verificationEnvironmentKeys(process.env, overrideKeys);
     const hash = environmentHash(keys);
-    const overridesHash = digest(canonical(command.env ?? {}));
+    const overridesHash = digest(canonical(overrides));
+    const env = verificationEnvironment(process.env, overrides);
     let output = '';
     let exitCode = -1;
     await new Promise((resolve) => {
@@ -665,10 +718,29 @@ async function executeCheck(command, log) {
         let done = false;
         const finish = (code) => { if (done)
             return; done = true; exitCode = code; if (timer)
-            clearTimeout(timer); resolve(); };
+            clearTimeout(timer); signal?.removeEventListener('abort', abort); resolve(); };
+        const stop = (reason) => {
+            output += '\n' + reason;
+            if (child?.pid) {
+                if (process.platform === 'win32')
+                    spawnSync('taskkill', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true });
+                else {
+                    try {
+                        process.kill(-child.pid, 'SIGKILL');
+                    }
+                    catch { /* already exited */ }
+                }
+            }
+            finish(-1);
+        };
+        const abort = () => stop('Verification command cancelled');
+        if (signal?.aborted) {
+            abort();
+            return;
+        }
         try {
-            const invocation = verificationInvocation(command.command, command.args, command.cwd);
-            child = spawn(invocation.command, invocation.args, { windowsVerbatimArguments: invocation.windowsVerbatimArguments, cwd: command.cwd, env: { ...process.env, ...command.env }, shell: false, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+            const invocation = verificationInvocation(command.command, command.args, command.cwd, process.platform, env);
+            child = spawn(invocation.command, invocation.args, { windowsVerbatimArguments: invocation.windowsVerbatimArguments, cwd: command.cwd, env, shell: false, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
         }
         catch (error) {
             output = String(error);
@@ -680,31 +752,19 @@ async function executeCheck(command, log) {
         child.stderr?.on('data', receive);
         child.on('error', (error) => { output += error.message; finish(-1); });
         child.on('close', (code) => finish(code ?? -1));
-        timer = setTimeout(() => {
-            output += '\nVerification command timed out';
-            if (child.pid) {
-                if (process.platform === 'win32')
-                    spawnSync('taskkill', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true });
-                else {
-                    try {
-                        process.kill(-child.pid, 'SIGKILL');
-                    }
-                    catch { /* already exited */ }
-                }
-            }
-            finish(-1);
-        }, command.timeoutMs);
+        signal?.addEventListener('abort', abort, { once: true });
+        timer = setTimeout(() => stop('Verification command timed out'), command.timeoutMs);
     });
-    return { repositoryId: command.repositoryId, command: command.command, args: command.args, cwd: command.cwd, environmentHash: hash, environmentKeys: keys, environmentOverrideKeys: overrideKeys, environmentOverridesHash: overridesHash, exitCode, durationMs: Date.now() - started, output };
+    return { repositoryId: command.repositoryId, command: command.command, args: command.args, cwd: command.cwd, environmentPolicy: 'isolated-transport-v1', environmentHash: hash, environmentKeys: keys, environmentOverrideKeys: overrideKeys, environmentOverridesHash: overridesHash, exitCode, durationMs: Date.now() - started, output };
 }
-export async function verifyPipeline(contextInput, raw, log = () => { }) {
+export async function verifyPipeline(contextInput, raw, log = () => { }, signal) {
     const context = validatePipelineContext(contextInput);
-    const { request, commands } = verificationPlan(context, raw);
+    const { request, commands, unverifiedRepositories } = verificationPlan(context, raw);
     const state = readState(context);
     const candidateHash = fingerprintCandidate(state);
     const results = [];
     for (const command of commands) {
-        results.push(await executeCheck(command, log));
+        results.push(await executeCheck(command, log, signal));
         if (results[results.length - 1].exitCode !== 0)
             break;
     }
@@ -715,6 +775,7 @@ export async function verifyPipeline(contextInput, raw, log = () => { }) {
             id: randomUUID(), kind: request.kind, scopeHash: state.scopeHash, candidateHash, commands: results,
             completedAt: new Date().toISOString(), valid: !changed && results.length === commands.length && results.every((result) => result.exitCode === 0),
             ...(changed ? { reason: 'Candidate changed during verification' } : results.some((result) => result.exitCode !== 0) ? { reason: 'A verification command failed' } : {}),
+            ...(unverifiedRepositories.length ? { unverifiedRepositories } : {}),
         };
         atomicJson(safeChild(pipelineStateDirectory(context), 'receipts/' + receipt.id + '.json'), receipt);
         if (receipt.kind === 'full' || !receipt.valid || !current.verification)
@@ -725,12 +786,20 @@ export async function verifyPipeline(contextInput, raw, log = () => { }) {
 }
 function verificationPlan(context, raw) {
     const request = object(raw);
-    if (!['full', 'scoped'].includes(String(request.kind)) || !Array.isArray(request.commands) || request.commands.length === 0 || request.commands.length > 100)
+    const unverified = request.unverified === true;
+    if (request.unverified !== undefined && typeof request.unverified !== 'boolean')
+        fail('Verification unverified flag must be boolean');
+    if (!['full', 'scoped'].includes(String(request.kind)) || !Array.isArray(request.commands) || (request.commands.length === 0 && !unverified) || request.commands.length > 100)
         fail('Verification requires bounded structured commands');
     const commands = request.commands.map((command) => validateCommand(context, command));
-    if (request.kind === 'full' && context.repositories.some((repo) => !commands.some((command) => command.repositoryId === repo.id)))
+    const unverifiedRepositories = context.repositories.filter((repo) => !commands.some((command) => command.repositoryId === repo.id)).map((repo) => repo.id);
+    if (request.kind === 'full' && !unverified && unverifiedRepositories.length)
         fail('Full verification must cover every selected repository');
-    return { request, commands };
+    return { request, commands, unverifiedRepositories: request.kind === 'full' && unverified ? unverifiedRepositories : [] };
+}
+/** Validate a check plan without creating state or executing commands. */
+export function validateVerificationRequest(contextInput, raw) {
+    verificationPlan(validatePipelineContext(contextInput), raw);
 }
 export function preparePreview(contextInput, raw) {
     const context = validatePipelineContext(contextInput);