specrails-core 6.6.0 → 6.6.2

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

@@ -414,7 +414,7 @@ export class CliExecutor {
             request.onEvent?.({ kind: 'usage', usage: parsed.usage });
             if (parsed.failureKind) {
                 const message = parsed.failureKind === 'max_turns'
-                    ? `${this.provider} reached the configured limit of ${request.maxTurns ?? 100} turns for ${request.role}. Inspect partial changes before recovery; a higher limit requires a new run configuration.`
+                    ? `${this.provider} reached the configured limit of ${request.maxTurns ?? 100} turns for ${request.role}. Raise maxTurns for role ${request.role}${request.maxTurns === undefined ? ' (unset: Core default 100)' : ''} and start a new run; partial changes stay in the worktree for inspection.`
                     : parsed.failureKind === 'cost_budget' ? `${this.provider} reached its configured cost budget.` : `${this.provider} exhausted structured output retries.`;
                 throw new AgentExecutionError(message, parsed.failureKind, parsed.usage);
             }

package/dist/agent-runtime/engine/pieces/openspec.js

@@ -1,4 +1,5 @@
 import { archivedOpenSpecChange, archiveOpenSpecChange } from '../../graph/artifacts.js';
+import { describeArchivePreflight, previewOpenSpecArchive } from '../../graph/archive-preflight.js';
 import { OpenSpecCommandError, resolveOpenSpecCli, runOpenSpec } from '../../openspec.js';
 import { EngineError } from '../contracts.js';
 import { boundedText, json, paramsSchema, text } from './shared.js';
@@ -39,7 +40,16 @@ export function openSpecPieces(bindings) {
                 const item = report.items?.find(entry => entry.id === change && entry.type === 'change');
                 if (!item || typeof item.valid !== 'boolean')
                     throw new EngineError('openspec_invalid_output', 'OpenSpec validation did not report the requested change');
-                return { outcome: exited && item.valid ? 'pass' : 'fail', output: json(report) };
+                // The planning role only learns why it was sent back through history.
+                const note = (suffix, value) => [{ id: context.frame.attemptId + ':' + suffix, transition: context.frame.transition, attempt: context.frame.attempt, ordinal: 0, nodePath: context.frame.nodePath, text: boundedText(value) }];
+                if (!exited || !item.valid) {
+                    const issues = (item.issues ?? []).filter(issue => issue.level === 'ERROR').slice(0, 20).map(issue => `- ${issue.path ? issue.path + ': ' : ''}${issue.message ?? 'invalid'}`);
+                    return { outcome: 'fail', output: json(report), history: note('validate', [`OpenSpec validation failed for change ${change}.`, ...issues].join('\n')) };
+                }
+                const preflight = await previewOpenSpecArchive(deps.context.artifactRoot, change, context.signal);
+                if (!preflight.valid)
+                    return { outcome: 'fail', output: json({ ...report, archivePreflight: preflight }), history: note('archive-preflight', describeArchivePreflight(change, preflight)) };
+                return { outcome: 'pass', output: json(report) };
             },
         }, {
             descriptor: { kind: 'openspec-archive', paramsSchema: { ...schema, properties: { ...schema.properties, requiresVerified: { type: 'boolean' }, reviewedCandidate: { type: 'string' }, approvedCandidate: { type: 'string' } } }, outcomes: ['next', 'failed'], effect: 'write', requiresAI: false },

package/dist/agent-runtime/graph/archive-preflight.d.ts

@@ -0,0 +1,32 @@
+export interface ArchiveRequirementFinding {
+    path: string;
+    line: number;
+    requirement: string;
+}
+export type ArchivePreflight = {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+    findings: ArchiveRequirementFinding[];
+};
+/**
+ * Requirements OpenSpec rejects when it rebuilds a main spec on archive: its spec parser reads only
+ * the first non-empty body line before any heading and needs SHALL or MUST there. Delta validation
+ * skips `**Key**:` metadata lines, so a delta (or a pre-existing main-spec requirement) can pass
+ * `openspec validate` and still abort the archive.
+ */
+export declare function requirementsWithoutKeyword(markdown: string): Array<{
+    line: number;
+    requirement: string;
+}>;
+/**
+ * Dry-runs `openspec archive` on a disposable copy of `openspec/`, so a change that validates but
+ * cannot be archived is caught while its author can still edit the plan. Nothing in the
+ * artifact root is written.
+ */
+export declare function previewOpenSpecArchive(artifactRoot: string, change: string, signal?: AbortSignal): Promise<ArchivePreflight>;
+/** Plain-text guidance for the planning role's history. */
+export declare function describeArchivePreflight(change: string, preflight: Extract<ArchivePreflight, {
+    valid: false;
+}>): string;

package/dist/agent-runtime/graph/archive-preflight.js

@@ -0,0 +1,98 @@
+import { cpSync, existsSync, lstatSync, mkdtempSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { artifactPath, OpenSpecCommandError, resolveOpenSpecCli, runOpenSpec } from '../openspec.js';
+const ANSI = new RegExp(String.fromCharCode(27) + '\\[[0-9;]*m', 'g');
+/**
+ * Requirements OpenSpec rejects when it rebuilds a main spec on archive: its spec parser reads only
+ * the first non-empty body line before any heading and needs SHALL or MUST there. Delta validation
+ * skips `**Key**:` metadata lines, so a delta (or a pre-existing main-spec requirement) can pass
+ * `openspec validate` and still abort the archive.
+ */
+export function requirementsWithoutKeyword(markdown) {
+    const lines = markdown.split('\n'), findings = [];
+    for (let index = 0; index < lines.length; index++) {
+        const header = lines[index].match(/^###\s+Requirement:\s*(.*)$/);
+        if (!header)
+            continue;
+        let body;
+        for (let next = index + 1; next < lines.length; next++) {
+            const text = lines[next].trim();
+            if (text.startsWith('#'))
+                break;
+            if (text) {
+                body = next;
+                break;
+            }
+        }
+        const text = body === undefined ? header[1] : lines[body];
+        if (!text.includes('SHALL') && !text.includes('MUST'))
+            findings.push({ line: (body ?? index) + 1, requirement: header[1].trim() });
+    }
+    return findings;
+}
+function assertNoSymlinks(root) {
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        if (entry.isSymbolicLink())
+            throw new Error('OpenSpec archive refuses symlink trees');
+        if (entry.isDirectory())
+            assertNoSymlinks(path.join(root, entry.name));
+    }
+}
+function capabilityFindings(artifactRoot, change) {
+    const deltas = path.join(artifactRoot, 'openspec/changes', change, 'specs');
+    if (!existsSync(deltas))
+        return [];
+    const findings = [];
+    for (const capability of readdirSync(deltas).sort()) {
+        for (const relative of [`openspec/changes/${change}/specs/${capability}/spec.md`, `openspec/specs/${capability}/spec.md`]) {
+            const file = path.join(artifactRoot, relative);
+            if (!existsSync(file) || !lstatSync(file).isFile())
+                continue;
+            for (const finding of requirementsWithoutKeyword(readFileSync(file, 'utf8')))
+                findings.push({ path: relative, ...finding });
+        }
+    }
+    return findings;
+}
+/**
+ * Dry-runs `openspec archive` on a disposable copy of `openspec/`, so a change that validates but
+ * cannot be archived is caught while its author can still edit the plan. Nothing in the
+ * artifact root is written.
+ */
+export async function previewOpenSpecArchive(artifactRoot, change, signal) {
+    const source = artifactPath(artifactRoot, 'openspec');
+    assertNoSymlinks(source);
+    const staging = mkdtempSync(path.join(os.tmpdir(), 'specrails-archive-preflight-'));
+    try {
+        cpSync(source, path.join(staging, 'openspec'), { recursive: true });
+        let output;
+        try {
+            output = await runOpenSpec(resolveOpenSpecCli(), staging, ['archive', change, '--yes'], signal);
+        }
+        catch (error) {
+            if (!(error instanceof OpenSpecCommandError) || error.exitCode === undefined || error.exitCode < 1)
+                throw error;
+            output = `${error.stdout}\n${error.message}`;
+        }
+        const archiveRoot = path.join(staging, 'openspec/changes/archive');
+        const archived = existsSync(archiveRoot) && readdirSync(archiveRoot).some(name => name.endsWith('-' + change));
+        if (archived && !existsSync(path.join(staging, 'openspec/changes', change)))
+            return { valid: true };
+        const reason = output.replace(ANSI, '').split('\n').map(line => line.trimEnd()).filter(Boolean).join('\n').slice(-2000);
+        return { valid: false, reason, findings: capabilityFindings(artifactRoot, change) };
+    }
+    finally {
+        rmSync(staging, { recursive: true, force: true });
+    }
+}
+/** Plain-text guidance for the planning role's history. */
+export function describeArchivePreflight(change, preflight) {
+    const located = preflight.findings.map(finding => `- ${finding.path}:${finding.line} "${finding.requirement}"`).join('\n');
+    return [
+        `OpenSpec validates change ${change}, but archiving it would fail. OpenSpec's archive output:`,
+        preflight.reason,
+        ...(located ? ['Requirements whose first body line has no SHALL or MUST (OpenSpec reads only that line when it rebuilds a main spec):', located,
+            'Put the SHALL/MUST statement on the line right after "### Requirement: …". For a requirement that only exists in openspec/specs, restate it under "## MODIFIED Requirements" in this change\'s delta with the corrected first line.'] : []),
+    ].join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "6.6.0",
+  "version": "6.6.2",
   "description": "Agent workflow engine for specrails-desktop: provider-independent installer and programmatic agent runtime for Claude Code and Codex",
   "type": "module",
   "exports": {