specrails-core 6.5.0 → 6.6.1

package/dist/installer/phases/install-config.js

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import yaml from 'js-yaml';
+import { dump, loadAll } from 'js-yaml';
 import { FilesystemError, InstallerError } from '../util/errors.js';
 import { pathExists, readTextFile, writeFileLf } from '../util/fs.js';
 import { warn } from '../util/logger.js';
@@ -72,7 +72,14 @@ export function loadInstallConfig(configPath) {
     const raw = readTextFile(configPath);
     let parsed;
     try {
-        parsed = yaml.load(raw);
+        // js-yaml 5 `load()` throws on a stream with no document (empty or
+        // comment-only file). Keep reporting that as a non-mapping config, and
+        // keep rejecting multi-document streams as `load()` did.
+        const documents = loadAll(raw);
+        if (documents.length > 1) {
+            throw new Error('expected a single document in the stream, but found more');
+        }
+        parsed = documents[0];
     }
     catch (err) {
         throw new InvalidConfigError([`YAML parse error: ${err.message}`]);
@@ -258,7 +265,7 @@ function isExactModelIdentifier(value) {
  */
 export function writeInstallConfig(configPath, config) {
     try {
-        const text = yaml.dump(config, { lineWidth: 120, noRefs: true });
+        const text = dump(config, { lineWidth: 120, noRefs: true });
         writeFileLf(configPath, text);
     }
     catch (err) {

package/dist/installer/util/paths.d.ts

@@ -6,7 +6,31 @@
  *
  * Audited by vitest spec `reserved-paths.test.ts`.
  */
-export declare const RESERVED_PATHS: readonly [".specrails/profiles/", ".claude/agents/custom-", ".kimi-code/skills/custom-", ".kimi-code/skills/rails/custom-"];
+export declare const RESERVED_PATHS: readonly [
+/**
+ * .specrails/profiles/** — project + desktop-app-authored profile JSON.
+ * specrails-desktop writes profile files here and expects them preserved
+ * across specrails-core updates.
+ */
+'.specrails/profiles/', 
+/**
+ * .claude/agents/custom-*.md — user-authored custom agents, kept
+ * distinct from the bundled sr-* agents so updates never overwrite
+ * them.
+ */
+'.claude/agents/custom-', 
+/**
+ * `.kimi-code/skills/custom-<id>/...` — user-authored Kimi role skills.
+ * Kimi discovers skills only one directory below `skills/`, so custom roles
+ * share the flat namespace with managed `sr-*` and workflow skills.
+ */
+'.kimi-code/skills/custom-', 
+/**
+ * Pre-release compatibility: preserve a legacy nested custom role until the
+ * installer can atomically migrate it to the flat path. A destination
+ * collision is never overwritten or deleted automatically.
+ */
+'.kimi-code/skills/rails/custom-'];
 /**
  * Returns true when a repo-relative path falls inside a reserved
  * region. Accepts both POSIX (/) and Windows (\) separators; the

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

@@ -107,6 +107,22 @@ export interface VerificationReceipt {
     reason?: string;
     /** Repositories in scope that this receipt ran no command for (explicitly admitted by the request). */
     unverifiedRepositories?: string[];
+    /** Candidate files the verification commands themselves added, modified or removed (absent when the candidate did not move). */
+    selfMutation?: VerificationSelfMutation;
+}
+export interface CandidateFileChange {
+    repositoryId: string;
+    path: string;
+    change: 'added' | 'modified' | 'removed';
+}
+/** What verification wrote into its own candidate: the files (bounded, `omittedFiles` counts the rest) and the commands that executed in the run. */
+export interface VerificationSelfMutation {
+    files: CandidateFileChange[];
+    omittedFiles?: number;
+    commands: Array<{
+        repositoryId: string;
+        label: string;
+    }>;
 }
 export interface AcceptanceCriterion {
     specId: string;
@@ -232,7 +248,19 @@ export interface CandidateManifest {
     }>;
 }
 export declare function candidateManifest(state: CandidateScope): CandidateManifest;
+export declare function candidateManifestHash(manifest: CandidateManifest): string;
 export declare function fingerprintCandidate(state: CandidateScope): string;
+/** Files that differ between two manifests of the same scope, sorted by repository, then path. */
+export declare function diffCandidateManifests(before: CandidateManifest, after: CandidateManifest): CandidateFileChange[];
+/** `1 candidate file: a` / `4 candidate files: a, b, c and 1 more`, shared by receipts and failure summaries. */
+export declare function describeModifiedFiles(mutation: Pick<VerificationSelfMutation, 'files' | 'omittedFiles'>): string;
+/**
+ * A receipt whose candidate moved while it ran. During a verify step no role
+ * turn runs, so a manifest diff around the run attributes the change to the
+ * verification commands themselves (a lint pre-step regenerating a tracked
+ * file); without both manifests the generic reason stays.
+ */
+export declare function candidateChangedReceipt(receipt: VerificationReceipt, before: CandidateManifest | undefined, after: (() => CandidateManifest) | undefined): VerificationReceipt;
 export declare function initializePipeline(contextInput: unknown, change: string): PipelineState;
 /** Host-owned binding, including immutable harness bytes outside the candidate. */
 export declare function bindVerificationPlan(contextInput: PipelineContext, hash: string, files: Array<{
@@ -309,6 +337,9 @@ export interface VerificationRunOptions {
 /** Persistence and candidate ownership are bound by the host, never inferred from a journal path. */
 export interface VerificationEvidencePort {
     candidateHash: string;
+    /** The manifest `candidateHash` was computed from; with `currentManifest`, an invalidated receipt names the files verification modified. */
+    candidateManifest?: CandidateManifest;
+    currentManifest?(): CandidateManifest;
     scopeHash: string;
     planHash?: string;
     previous?: VerificationReceipt;
@@ -335,21 +366,15 @@ export interface VerificationEvidenceQuery {
 export declare function persistCheckEvidence(context: PipelineContext, result: CommandReceipt, planHash: string, candidateHash: string): void;
 /** Historical read: no live repository validation, source execution or lifecycle mutation. */
 export declare function readVerificationEvidence(context: Pick<PipelineContext, 'backlogRoot' | 'runId'>, query?: VerificationEvidenceQuery): {
-    nextCursor?: string | undefined;
     schemaVersion: number;
     available: boolean;
     items: Record<string, unknown>[];
     truncated: boolean;
+    nextCursor?: string | undefined;
 } | {
     schemaVersion: number;
     available: boolean;
     items: {
-        sources: {
-            id: string;
-            displayPath: string;
-            byteCount: number;
-            hash: string;
-        }[];
         schemaVersion: 1;
         runId: string;
         id: string;
@@ -358,9 +383,9 @@ export declare function readVerificationEvidence(context: Pick<PipelineContext,
         label: string;
         origin: string[];
         required: true;
-        disposition: "executed" | "reused" | "not-run";
+        disposition: 'executed' | 'reused' | 'not-run';
         reusedFrom?: string;
-        status: "passed" | "failed" | "cancelled" | "interrupted" | "unavailable";
+        status: 'passed' | 'failed' | 'cancelled' | 'interrupted' | 'unavailable';
         reuseReason?: string;
         recordedAt: string;
         execution: {
@@ -382,16 +407,22 @@ export declare function readVerificationEvidence(context: Pick<PipelineContext,
         stderrBytes: number;
         stdoutHash: string;
         stderrHash: string;
+        sources: {
+            id: string;
+            displayPath: string;
+            byteCount: number;
+            hash: string;
+        }[];
     }[];
     truncated: boolean;
 } | {
-    nextCursor?: string | undefined;
+    items?: undefined;
     schemaVersion: number;
     available: boolean;
     text: string;
     byteCount: number;
     totalBytes: number;
     truncated: boolean;
-    items?: undefined;
+    nextCursor?: string | undefined;
 };
 export {};

package/dist/pipeline/pipeline-state.js

@@ -407,7 +407,45 @@ export function candidateManifest(state) {
     }));
     return { schemaVersion: 1, scopeHash: state.scopeHash, repositories: entries };
 }
-export function fingerprintCandidate(state) { return digest(canonical(candidateManifest(state).repositories)); }
+export function candidateManifestHash(manifest) { return digest(canonical(manifest.repositories)); }
+export function fingerprintCandidate(state) { return candidateManifestHash(candidateManifest(state)); }
+/** Files that differ between two manifests of the same scope, sorted by repository, then path. */
+export function diffCandidateManifests(before, after) {
+    const changes = [];
+    for (const repositoryId of [...new Set([...before.repositories, ...after.repositories].map(repo => repo.id))].sort()) {
+        const old = new Map(before.repositories.find(repo => repo.id === repositoryId)?.files ?? []);
+        const current = new Map(after.repositories.find(repo => repo.id === repositoryId)?.files ?? []);
+        for (const file of [...new Set([...old.keys(), ...current.keys()])].sort()) {
+            const change = !old.has(file) ? 'added' : !current.has(file) ? 'removed' : old.get(file) !== current.get(file) ? 'modified' : undefined;
+            if (change)
+                changes.push({ repositoryId, path: file, change });
+        }
+    }
+    return changes;
+}
+const SELF_MUTATION_FILE_LIMIT = 200;
+/** `1 candidate file: a` / `4 candidate files: a, b, c and 1 more`, shared by receipts and failure summaries. */
+export function describeModifiedFiles(mutation) {
+    const total = mutation.files.length + (mutation.omittedFiles ?? 0), shown = mutation.files.slice(0, 3).map(file => file.path);
+    return `${total} candidate file${total === 1 ? '' : 's'}: ${shown.join(', ')}${total > shown.length ? ` and ${total - shown.length} more` : ''}`;
+}
+/**
+ * A receipt whose candidate moved while it ran. During a verify step no role
+ * turn runs, so a manifest diff around the run attributes the change to the
+ * verification commands themselves (a lint pre-step regenerating a tracked
+ * file); without both manifests the generic reason stays.
+ */
+export function candidateChangedReceipt(receipt, before, after) {
+    if (receipt.selfMutation)
+        return { ...receipt, valid: false };
+    const files = before && after ? diffCandidateManifests(before, after()) : [];
+    if (!files.length)
+        return { ...receipt, valid: false, reason: 'Candidate changed during verification' };
+    const selfMutation = { files: files.slice(0, SELF_MUTATION_FILE_LIMIT), ...(files.length > SELF_MUTATION_FILE_LIMIT ? { omittedFiles: files.length - SELF_MUTATION_FILE_LIMIT } : {}),
+        commands: receipt.commands.filter(command => command.disposition !== 'reused' && command.disposition !== 'not-run').map(command => ({ repositoryId: command.repositoryId, label: command.label ?? command.key ?? [command.command, ...command.args].join(' ').slice(0, 256) })) };
+    const failed = receipt.commands.some(command => command.exitCode !== 0);
+    return { ...receipt, valid: false, reason: `${failed ? 'A verification command failed. ' : ''}Verification commands modified ${describeModifiedFiles(selfMutation)}`, selfMutation };
+}
 function activeArtifactPath(state) { return state.archivePath ?? path.join(state.context.artifactRoot, 'openspec', 'changes', state.change); }
 function artifactFingerprint(state) {
     const root = activeArtifactPath(state);
@@ -1154,19 +1192,19 @@ export async function verifyPipeline(contextInput, raw, log = () => { }, signal,
     const identityProblems = planReasons(state, typeof request.planHash === 'string' ? request.planHash : undefined);
     if (identityProblems.length)
         fail(identityProblems.join('; '));
-    const candidateHash = fingerprintCandidate(state);
+    const manifest = candidateManifest(state), candidateHash = candidateManifestHash(manifest);
     const isCurrent = () => {
         const current = readState(context);
         return fingerprintCandidate(current) === candidateHash && current.revision === state.revision && planReasons(current, request.planHash).length === 0;
     };
     return executeVerification(context, raw, {
-        candidateHash, scopeHash: state.scopeHash, planHash: state.verificationPlan?.hash, previous,
+        candidateHash, candidateManifest: manifest, currentManifest: () => candidateManifest(readState(context)), scopeHash: state.scopeHash, planHash: state.verificationPlan?.hash, previous,
         isCurrent: () => locked(context, isCurrent),
         persistCheck: (result, planHash, candidate) => persistCheckEvidence(context, result, planHash, candidate),
         commitReceipt: receipt => locked(context, () => {
             const current = readState(context);
             if (!isCurrent())
-                receipt = { ...receipt, valid: false, reason: 'Candidate changed during verification' };
+                receipt = candidateChangedReceipt(receipt, manifest, () => candidateManifest(current));
             atomicJson(safeChild(pipelineStateDirectory(context), 'receipts/' + receipt.id + '.json'), receipt);
             if (receipt.kind === 'full' || !receipt.valid || !current.verification)
                 current.verification = receipt;
@@ -1249,12 +1287,13 @@ export async function executeVerification(contextInput, raw, evidence, log = ()
         notRunEvidenceIds.push(id);
     }
     const changed = !evidence.isCurrent();
-    const receipt = await evidence.commitReceipt({
+    const draft = {
         id: randomUUID(), ...(evidence.planHash ? { planHash: evidence.planHash } : {}), kind: request.kind, scopeHash: evidence.scopeHash, candidateHash, commands: results, ...(notRunEvidenceIds.length ? { notRunEvidenceIds } : {}),
-        completedAt: new Date().toISOString(), valid: !changed && !signal?.aborted && (options.deadline === undefined || Date.now() <= options.deadline) && 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' } : {}),
+        completedAt: new Date().toISOString(), valid: !signal?.aborted && (options.deadline === undefined || Date.now() <= options.deadline) && results.length === commands.length && results.every((result) => result.exitCode === 0),
+        ...(results.some((result) => result.exitCode !== 0) ? { reason: 'A verification command failed' } : {}),
         ...(unverifiedRepositories.length ? { unverifiedRepositories } : {}),
-    });
+    };
+    const receipt = await evidence.commitReceipt(changed ? candidateChangedReceipt(draft, evidence.candidateManifest, evidence.currentManifest && (() => evidence.currentManifest())) : draft);
     if (!receipt.valid)
         for (const result of results) {
             await options.onEvidence?.('check-invalidated', { executionId: result.evidenceId ?? '', repositoryId: result.repositoryId, checkId: result.key ?? '', label: result.label ?? result.command, reason: receipt.reason ?? 'Verification did not complete successfully' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "6.5.0",
+  "version": "6.6.1",
   "description": "Agent workflow engine for specrails-desktop: provider-independent installer and programmatic agent runtime for Claude Code and Codex",
   "type": "module",
   "exports": {
@@ -89,23 +89,25 @@
   },
   "dependencies": {
     "@fission-ai/openspec": "1.4.1",
-    "@langchain/core": "1.2.10",
-    "@langchain/langgraph": "1.4.14",
+    "@langchain/core": "1.2.14",
+    "@langchain/langgraph": "1.4.18",
     "@langchain/langgraph-checkpoint": "1.1.5",
-    "@modelcontextprotocol/sdk": "1.29.0",
+    "@modelcontextprotocol/sdk": "1.31.0",
     "ajv": "^8.20.0",
     "cross-spawn": "7.0.6",
-    "js-yaml": "^4.1.0",
+    "js-yaml": "^5.4.3",
     "picocolors": "^1.1.1",
-    "zod": "4.6.2"
+    "semver": "^7.8.5",
+    "zod": "4.6.5"
   },
   "devDependencies": {
     "@types/cross-spawn": "6.0.6",
-    "@types/js-yaml": "^4.0.9",
-    "@types/node": "^22.10.2",
-    "@vitest/coverage-v8": "^4.1.5",
-    "typescript": "^5.7.2",
-    "vitest": "^4.1.5"
+    "@types/node": "^26.6.5",
+    "@types/semver": "^7.8.0",
+    "@vitest/coverage-v8": "^5.0.3",
+    "js-yaml-4": "npm:js-yaml@^4.3.2",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
   },
   "license": "MIT",
   "author": "fjpulidop"

package/schemas/agent-runtime.schema.json

@@ -12,7 +12,7 @@
       "planning": { "enum": ["full", "proportional"] }, "acceptDeveloperChecks": { "type": "boolean" },
       "verification": { "type": "object", "additionalProperties": false, "properties": { "maxConcurrency": { "type": "integer", "minimum": 1, "maximum": 4 } } }
     } },
-    "guardrails": { "type": "object", "additionalProperties": false, "properties": { "plan-validation": { "type": "boolean" }, "genuine-blocking-question": { "type": "boolean" }, "plan-language-hint": { "type": "boolean" }, "frozen-plan-writes": { "type": "boolean" }, "primary-language": { "type": "boolean" }, "duplicate-sibling": { "type": "boolean" }, "one-test-per-module": { "type": "boolean" }, "empty-write": { "type": "boolean" }, "evidence-gated-ticking": { "type": "boolean" }, "inventory-retry": { "type": "boolean" }, "synthetic-corrections": { "type": "boolean" }, "silent-group-closure": { "type": "boolean" }, "verify-per-group": { "type": "boolean" }, "test-reachability": { "type": "boolean" }, "exit-code-honesty": { "type": "boolean" }, "environment-repair": { "type": "boolean" }, "lockfile-repair": { "type": "boolean" }, "verify-idle-timeout": { "type": "boolean" } } },
+    "guardrails": { "type": "object", "additionalProperties": false, "properties": { "plan-validation": { "type": "boolean" }, "genuine-blocking-question": { "type": "boolean" }, "plan-language-hint": { "type": "boolean" }, "frozen-plan-writes": { "type": "boolean" }, "primary-language": { "type": "boolean" }, "duplicate-sibling": { "type": "boolean" }, "one-test-per-module": { "type": "boolean" }, "empty-write": { "type": "boolean" }, "evidence-gated-ticking": { "type": "boolean" }, "inventory-retry": { "type": "boolean" }, "synthetic-corrections": { "type": "boolean" }, "silent-group-closure": { "type": "boolean" }, "verify-per-group": { "type": "boolean" }, "test-reachability": { "type": "boolean" }, "exit-code-honesty": { "type": "boolean" }, "environment-repair": { "type": "boolean" }, "lockfile-repair": { "type": "boolean" }, "verify-idle-timeout": { "type": "boolean" }, "verification-output-adoption": { "type": "boolean" } } },
     "rolePrompts": { "type": "object", "propertyNames": { "pattern": "^[a-z][a-z0-9-]{0,63}$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 20000, "pattern": "\\S" }, "properties": {
       "architect": { "type": "string", "minLength": 1, "maxLength": 20000, "pattern": "\\S" },
       "developer": { "type": "string", "minLength": 1, "maxLength": 20000, "pattern": "\\S" },