specrails-core 6.6.4 → 6.7.0

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;

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

@@ -0,0 +1,158 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pipelineStateDirectory } from '../../pipeline/pipeline-state.js';
+import { child, write } from './artifacts.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 const CLARIFICATIONS_SCHEMA_VERSION = 1;
+export const CLARIFICATION_LIMIT = 5;
+export const CLARIFICATION_IMPACTS = ['high', 'medium', 'low'];
+export const CLARIFICATION_POLICIES = ['ask-on-high', 'always-proceed'];
+export const DEFAULT_CLARIFICATION_POLICY = 'ask-on-high';
+const TEXT_LIMIT = 2000;
+/** The optional `clarifications` property of ARCHITECT_OUTPUT_SCHEMA. */
+export const CLARIFICATIONS_SCHEMA = {
+    type: 'array', maxItems: CLARIFICATION_LIMIT,
+    description: 'Ambiguities found before planning; empty or omitted when the ticket is clear.',
+    items: { type: 'object', additionalProperties: false, required: ['question', 'impact', 'default'], properties: {
+            question: { type: 'string', minLength: 1, maxLength: TEXT_LIMIT },
+            impact: { type: 'string', enum: [...CLARIFICATION_IMPACTS] },
+            default: { type: ['string', 'null'], maxLength: TEXT_LIMIT, description: 'The answer you would assume, or null when no safe default exists.' },
+        } },
+};
+/** Throws a repairable `Invalid architect clarifications` error for a malformed list. */
+export function parseClarifications(value) {
+    if (value === undefined || value === null)
+        return [];
+    const fail = (detail) => { throw new Error('Invalid architect clarifications: ' + detail); };
+    if (!Array.isArray(value))
+        fail('expected an array');
+    const list = value;
+    if (list.length > CLARIFICATION_LIMIT)
+        fail(`at most ${CLARIFICATION_LIMIT} entries`);
+    return list.map((item, index) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            return fail(`entry ${index} must be an object`);
+        const entry = item;
+        if (typeof entry.question !== 'string' || !entry.question.trim())
+            return fail(`entry ${index} needs a question`);
+        if (!CLARIFICATION_IMPACTS.includes(entry.impact))
+            return fail(`entry ${index} impact must be one of ${CLARIFICATION_IMPACTS.join(', ')}`);
+        if (entry.default !== undefined && entry.default !== null && typeof entry.default !== 'string')
+            return fail(`entry ${index} default must be a string or null`);
+        const fallback = typeof entry.default === 'string' && entry.default.trim() ? entry.default.trim().slice(0, TEXT_LIMIT) : null;
+        return { question: entry.question.trim().slice(0, TEXT_LIMIT), impact: entry.impact, default: fallback };
+    });
+}
+/** The clarifications that pause the run under the policy: high impact without a safe default. */
+export function blockingClarifications(clarifications, policy = DEFAULT_CLARIFICATION_POLICY) {
+    return policy === 'ask-on-high' ? clarifications.filter(item => item.impact === 'high' && item.default === null) : [];
+}
+/** True when a raw architect reply carries a high-impact clarification without a default: it may stop before authoring artifacts. */
+export function asksBeforePlanning(value) {
+    return Array.isArray(value) && value.some(item => !!item && typeof item === 'object' && item.impact === 'high'
+        && !item.default?.toString().trim());
+}
+/** The single question the paused run carries (`pendingQuestion.question`). */
+export function clarificationQuestion(blocking, lowConfidenceQuestion) {
+    const questions = [...blocking.map(item => item.question), ...(lowConfidenceQuestion && !blocking.some(item => item.question === lowConfidenceQuestion) ? [lowConfidenceQuestion] : [])];
+    if (questions.length === 1)
+        return questions[0];
+    return ['Before planning, the architect needs answers to:', ...questions.map((question, index) => `${index + 1}. ${question}`)].join('\n');
+}
+const HEADING = /^\s{0,3}#{1,6}\s+(.*?)\s*#*\s*$/;
+/** A bold or underscored label on its own line, such as OpenSpec's `**Non-Goals:**`. */
+const LABEL = /^\s*(?:[-*+]\s+)?(?:\*\*|__)\s*([^*_]+?)\s*:?\s*(?:\*\*|__)\s*:?\s*(.*)$/;
+function meaningful(line) {
+    return line.replace(/<!--[\s\S]*?-->/g, '').replace(/^\s*(?:[-*+]|\d+\.)\s*$/, '').trim().length > 0;
+}
+/**
+ * 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 function designSection(markdown, name) {
+    const lines = markdown.replace(/<!--[\s\S]*?-->/g, '').split(/\r?\n/);
+    const collect = (start, inline, stopAtLabels) => {
+        const content = inline.trim() ? [inline.trim()] : [];
+        for (let index = start + 1; index < lines.length; index++) {
+            const line = lines[index];
+            if (HEADING.test(line) || (stopAtLabels && LABEL.test(line) && !LABEL.exec(line)[2].trim() && !/^\s*[-*+]\s/.test(line)))
+                break;
+            if (meaningful(line))
+                content.push(line.trim());
+        }
+        return content;
+    };
+    const label = lines.findIndex(line => { const match = LABEL.exec(line); return !!match && name.test(match[1]) && !HEADING.test(line); });
+    if (label >= 0)
+        return collect(label, LABEL.exec(lines[label])[2], true);
+    const heading = lines.findIndex(line => { const match = HEADING.exec(line); return !!match && name.test(match[1]); });
+    if (heading >= 0)
+        return collect(heading, '', false);
+    return undefined;
+}
+export const NON_GOALS = /\bnon[\s-]?goals?\b/i;
+export const ASSUMPTIONS = /\bassumptions?\b/i;
+/**
+ * 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 function validateDesignSections(context, change, options) {
+    const file = child(context.artifactRoot, 'openspec/changes/' + change + '/design.md');
+    if (!existsSync(file)) {
+        // Under always-proceed a reply that stopped on a question has nothing to proceed with.
+        if (options.policy === 'always-proceed' && options.clarifications.some(item => item.impact === 'high' && item.default === null))
+            throw new Error('Invalid architect reply: the clarification policy is always-proceed, so plan on your best default for every clarification, author the artifacts and record the defaults under `## Assumptions` in design.md.');
+        return;
+    }
+    const design = readFileSync(file, 'utf8');
+    const missing = [];
+    if (!designSection(design, NON_GOALS)?.length)
+        missing.push('a `## Non-Goals` section with at least one line naming what this change deliberately does not do');
+    if (options.clarifications.length && !designSection(design, ASSUMPTIONS)?.length)
+        missing.push('a `## Assumptions` section with one line per clarification you proceeded on (question and the answer you assumed)');
+    if (missing.length)
+        throw new Error(`Invalid design.md: it needs ${missing.join(' and ')}. Update design.md through the workflow's write_artifact action, then resend the same JSON reply.`);
+}
+export const CLARIFICATIONS_FILE = 'clarifications.json';
+export function clarificationsPath(context) {
+    return path.join(pipelineStateDirectory(context), CLARIFICATIONS_FILE);
+}
+export function writeClarificationsRecord(context, entry) {
+    const record = { schemaVersion: CLARIFICATIONS_SCHEMA_VERSION, change: entry.change, policy: entry.policy, status: entry.status, recordedAt: new Date().toISOString(), clarifications: entry.clarifications, blocking: entry.blocking, answers: entry.answers, assumptions: entry.assumptions ?? [] };
+    write(clarificationsPath(context), JSON.stringify(record, null, 2) + '\n');
+    return record;
+}
+/** The Assumptions lines of the active change's design.md, for the host record. */
+export function designAssumptions(context, change) {
+    try {
+        const file = child(context.artifactRoot, 'openspec/changes/' + change + '/design.md');
+        return existsSync(file) ? (designSection(readFileSync(file, 'utf8'), ASSUMPTIONS) ?? []).slice(0, 50).map(line => line.slice(0, TEXT_LIMIT)) : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** The latest clarifications record of a run, or null when the architect has not recorded one (or it is unreadable). */
+export function readClarificationsRecord(context) {
+    try {
+        const file = clarificationsPath(context);
+        if (!existsSync(file))
+            return null;
+        const value = JSON.parse(readFileSync(file, 'utf8'));
+        return value && typeof value === 'object' && value.schemaVersion === CLARIFICATIONS_SCHEMA_VERSION ? value : null;
+    }
+    catch {
+        return null;
+    }
+}