specrails-core 6.6.5 → 6.7.1

package/dist/agent-runtime/graph/review-brief.js

@@ -0,0 +1,127 @@
+/**
+ * The reviewer's risk brief: an optional, advisory companion to the verdict that
+ * tells a human what changed, what the change leans on, what no test exercises
+ * and where to look first. It never feeds the approval gate (review-policy.ts).
+ */
+export const REVIEW_BRIEF_SCHEMA_VERSION = 1;
+/** At most this many risks reach the brief; the rest become acceptance findings. */
+export const REVIEW_BRIEF_RISK_LIMIT = 5;
+const LIST_LIMIT = 20;
+const TEXT_LIMIT = 2000;
+export const REVIEW_RISK_SEVERITIES = ['high', 'medium', 'low'];
+export const REVIEW_RISK_AREAS = ['data', 'security', 'api', 'ux', 'performance', 'ops', 'other'];
+export const REVIEW_INVARIANT_STATUSES = ['kept', 'changed', 'at-risk'];
+const text = { type: 'string', minLength: 1 };
+const items = (properties) => ({ type: 'array', items: { type: 'object', additionalProperties: false, required: Object.keys(properties), properties } });
+/** The optional `brief` property of REVIEW_OUTPUT_SCHEMA. Every list is optional and may be empty. */
+export const REVIEW_BRIEF_SCHEMA = {
+    type: 'object', additionalProperties: false,
+    description: 'Optional risk brief for the human who merges the change. Advisory only: it never changes the verdict.',
+    properties: {
+        behaviourChanges: items({ what: text, where: { ...text, description: 'file:line' }, userVisible: { type: 'boolean' } }),
+        invariantsTouched: items({ invariant: text, evidence: { ...text, description: 'file:line or file:start-end' }, status: { type: 'string', enum: [...REVIEW_INVARIANT_STATUSES] } }),
+        untested: items({ path: text, why: text }),
+        risks: items({ severity: { type: 'string', enum: [...REVIEW_RISK_SEVERITIES] }, area: { type: 'string', enum: [...REVIEW_RISK_AREAS] }, whatToLookAt: text, ref: { ...text, description: 'file:line' } }),
+        humanChecks: { type: 'array', items: text },
+        divergences: items({ capability: text, requirement: text, observed: text }),
+    },
+};
+class BriefError extends Error {
+    constructor(detail) { super('Invalid review brief: ' + detail); }
+}
+function field(value, where) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new BriefError(`${where} must be a non-empty string`);
+    return value.trim().slice(0, TEXT_LIMIT);
+}
+function member(value, allowed, where) {
+    if (typeof value !== 'string' || !allowed.includes(value))
+        throw new BriefError(`${where} must be one of ${allowed.join(', ')}`);
+    return value;
+}
+function list(value, name, parse) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!Array.isArray(value))
+        throw new BriefError(`${name} must be an array`);
+    return value.map((item, index) => {
+        const where = `${name}[${index}]`;
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            throw new BriefError(`${where} must be an object`);
+        return parse(item, where);
+    });
+}
+const SEVERITY_RANK = { high: 0, medium: 1, low: 2 };
+/**
+ * Validates and normalizes a reviewer brief. Absent (`undefined`/`null`) means
+ * no brief; an empty object is a valid, empty brief. Risks are ordered by
+ * severity (stable within a severity) and capped at REVIEW_BRIEF_RISK_LIMIT;
+ * the rest are returned as `overflow`. Throws `Invalid review brief: …` when
+ * malformed, which the role invoker treats as repairable.
+ */
+export function parseReviewBrief(value) {
+    if (value === undefined || value === null)
+        return { overflow: [] };
+    if (typeof value !== 'object' || Array.isArray(value))
+        throw new BriefError('brief must be an object');
+    const raw = value;
+    const brief = {};
+    const behaviourChanges = list(raw.behaviourChanges, 'behaviourChanges', (item, where) => {
+        if (typeof item.userVisible !== 'boolean')
+            throw new BriefError(`${where}.userVisible must be a boolean`);
+        return { what: field(item.what, where + '.what'), where: field(item.where, where + '.where'), userVisible: item.userVisible };
+    });
+    const invariantsTouched = list(raw.invariantsTouched, 'invariantsTouched', (item, where) => ({
+        invariant: field(item.invariant, where + '.invariant'), evidence: field(item.evidence, where + '.evidence'), status: member(item.status, REVIEW_INVARIANT_STATUSES, where + '.status'),
+    }));
+    const untested = list(raw.untested, 'untested', (item, where) => ({ path: field(item.path, where + '.path'), why: field(item.why, where + '.why') }));
+    const risks = list(raw.risks, 'risks', (item, where) => ({
+        severity: member(item.severity, REVIEW_RISK_SEVERITIES, where + '.severity'), area: member(item.area, REVIEW_RISK_AREAS, where + '.area'),
+        whatToLookAt: field(item.whatToLookAt, where + '.whatToLookAt'), ref: field(item.ref, where + '.ref'),
+    }));
+    let humanChecks;
+    if (raw.humanChecks !== undefined && raw.humanChecks !== null) {
+        if (!Array.isArray(raw.humanChecks))
+            throw new BriefError('humanChecks must be an array');
+        humanChecks = raw.humanChecks.map((item, index) => field(item, `humanChecks[${index}]`));
+    }
+    const divergences = list(raw.divergences, 'divergences', (item, where) => ({
+        capability: field(item.capability, where + '.capability'), requirement: field(item.requirement, where + '.requirement'), observed: field(item.observed, where + '.observed'),
+    }));
+    let overflow = [];
+    if (behaviourChanges)
+        brief.behaviourChanges = behaviourChanges.slice(0, LIST_LIMIT);
+    if (invariantsTouched)
+        brief.invariantsTouched = invariantsTouched.slice(0, LIST_LIMIT);
+    if (untested)
+        brief.untested = untested.slice(0, LIST_LIMIT);
+    if (risks) {
+        const ordered = risks.map((risk, index) => ({ risk, index })).sort((a, b) => SEVERITY_RANK[a.risk.severity] - SEVERITY_RANK[b.risk.severity] || a.index - b.index).map(entry => entry.risk);
+        brief.risks = ordered.slice(0, REVIEW_BRIEF_RISK_LIMIT);
+        overflow = ordered.slice(REVIEW_BRIEF_RISK_LIMIT);
+    }
+    if (humanChecks)
+        brief.humanChecks = humanChecks.slice(0, LIST_LIMIT);
+    if (divergences)
+        brief.divergences = divergences.slice(0, LIST_LIMIT);
+    return { brief, overflow };
+}
+/** One acceptance finding line for a risk that did not fit in the brief. */
+export function riskFinding(risk) {
+    return `Additional ${risk.severity} ${risk.area} risk (beyond the brief's top ${REVIEW_BRIEF_RISK_LIMIT}): ${risk.whatToLookAt} (${risk.ref})`;
+}
+/**
+ * Applies the repair policy: on the first reply a malformed brief throws so the
+ * role invoker spends its single repair turn; on the repaired reply it is
+ * dropped with a diagnostic instead of failing the review.
+ */
+export function settleReviewBrief(value, options) {
+    try {
+        return parseReviewBrief(value);
+    }
+    catch (error) {
+        if (options.repairable)
+            throw error;
+        return { overflow: [], diagnostic: `Review brief dropped after the repair turn: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}

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

@@ -10,6 +10,7 @@ import { performance } from 'node:perf_hooks';
 import { frozenAcceptanceCriteria, pipelineStateDirectory } from '../../pipeline/pipeline-state.js';
 import { AgentExecutionError, unknownUsage } from '../executor-types.js';
 import { ROLE_INSTRUCTIONS_VERSION, repairInstructions } from '../prompts.js';
+import { asksBeforePlanning } from './clarifications.js';
 import { parseAgentObject } from './artifacts.js';
 /** Executor failures that mean "this session cannot be continued", not "the role failed". */
 const SESSION_FALLBACK_CODES = new Set(['session_not_found', 'session_expired', 'session_unsupported']);
@@ -138,9 +139,10 @@ export function createRoleInvoker(deps) {
                     parseError = error;
                 }
             }
-            // A genuine architect question can precede artifact creation. Completed
-            // role results must prove this invocation used the workflow, not an old visit.
-            if (!(role === 'architect' && output?.confidence === 'low'))
+            // A genuine architect question (low confidence, or a high-impact
+            // clarification without a safe default) can precede artifact creation.
+            // Completed role results must prove this invocation used the workflow, not an old visit.
+            if (!(role === 'architect' && (output?.confidence === 'low' || asksBeforePlanning(output?.clarifications))))
                 workflow?.assertParticipation(cursor);
             if (structured && !output && !options.lenient)
                 throw new Error('Invalid structured role response: ' + (parseError instanceof Error ? parseError.message : 'missing object'));

package/dist/agent-runtime/graph/spec-trace-record.d.ts

@@ -0,0 +1,33 @@
+import { type PipelineContext, type VerificationReceipt } from '../../pipeline/pipeline-state.js';
+import { SPEC_TRACE_SCHEMA_VERSION, type SpecTraceReport } from '../../pipeline/spec-trace.js';
+/** What the verification record, the reviewer and the acceptance findings carry; the full report stays in spec-trace.json. */
+export interface SpecTraceSummary {
+    schemaVersion: typeof SPEC_TRACE_SCHEMA_VERSION;
+    receiptId: string | null;
+    summary: string;
+    requirements: number;
+    demonstrated: number;
+    touched: string[];
+    touchedUndemonstrated: Array<{
+        id: string;
+        reason: string;
+    }>;
+    untagged: Array<{
+        tag: string;
+        file: string;
+        line: number;
+    }>;
+    /** Absolute path of the full report. */
+    path: string;
+}
+export declare function specTracePath(context: Pick<PipelineContext, 'backlogRoot' | 'runId'>): string;
+/**
+ * Scans the specs and tests after a passing verification, binds the report to
+ * the receipt and writes `spec-trace.json`. Advisory and fail-open: any error
+ * yields `undefined` and never changes the verification outcome.
+ */
+export declare function recordSpecTrace(context: PipelineContext, change: string, receipt: Pick<VerificationReceipt, 'id' | 'commands'>, reportedTests?: readonly string[]): SpecTraceSummary | undefined;
+/** The latest report of a run, or null when verification has not passed yet (or the file is unreadable). */
+export declare function readSpecTraceReport(context: Pick<PipelineContext, 'backlogRoot' | 'runId'>): SpecTraceReport | null;
+/** The acceptance finding that records the advisory trace next to the receipt. */
+export declare function specTraceFinding(trace: SpecTraceSummary): string;

package/dist/agent-runtime/graph/spec-trace-record.js

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pipelineStateDirectory } from '../../pipeline/pipeline-state.js';
+import { SPEC_TRACE_FILE, SPEC_TRACE_SCHEMA_VERSION, traceSpecs, traceSummary } from '../../pipeline/spec-trace.js';
+import { commandReachesTest } from '../compact/test-reachability.js';
+import { write } from './artifacts.js';
+const LIST_LIMIT = 50;
+export function specTracePath(context) {
+    return path.join(pipelineStateDirectory(context), SPEC_TRACE_FILE);
+}
+/**
+ * Scans the specs and tests after a passing verification, binds the report to
+ * the receipt and writes `spec-trace.json`. Advisory and fail-open: any error
+ * yields `undefined` and never changes the verification outcome.
+ */
+export function recordSpecTrace(context, change, receipt, reportedTests = []) {
+    try {
+        const single = context.repositories.length === 1 ? context.repositories[0] : undefined;
+        const testFiles = single ? reportedTests.map(file => path.isAbsolute(file) ? path.relative(single.path, file) : file).filter(file => file && !file.startsWith('..')).map(file => ({ repositoryId: single.id, file })) : [];
+        const report = traceSpecs({
+            specsRoot: context.artifactRoot, changes: [change],
+            repositories: context.repositories.map(repository => ({ id: repository.id, root: repository.path })),
+            testFiles, receipt: { id: receipt.id, commands: receipt.commands.map(command => {
+                    // Receipts record the absolute working directory; reachability wants it relative to the repository.
+                    const root = context.repositories.find(item => item.id === command.repositoryId)?.path;
+                    const cwd = root && command.cwd ? path.relative(root, path.resolve(root, command.cwd)) : '';
+                    return { repositoryId: command.repositoryId, command: command.command, args: command.args, ...(cwd && !cwd.startsWith('..') ? { cwd } : {}), exitCode: command.exitCode };
+                }) },
+            reaches: commandReachesTest,
+        });
+        const file = specTracePath(context);
+        write(file, JSON.stringify(report, null, 2) + '\n');
+        return summarize(report, file, context.repositories.length > 1);
+    }
+    catch {
+        return undefined;
+    }
+}
+function summarize(report, file, multiple) {
+    const reasons = new Map(report.undemonstrated.map(item => [item.id, item.reason]));
+    return {
+        schemaVersion: report.schemaVersion, receiptId: report.receiptId, summary: traceSummary(report), requirements: report.requirements, demonstrated: report.demonstrated.length,
+        touched: report.touched.slice(0, LIST_LIMIT), touchedUndemonstrated: report.touchedUndemonstrated.slice(0, LIST_LIMIT).map(id => ({ id, reason: reasons.get(id) ?? 'no-test' })),
+        untagged: report.untagged.slice(0, LIST_LIMIT).map(tag => ({ tag: tag.tag, file: (multiple ? tag.repositoryId + ':' : '') + tag.file, line: tag.line })),
+        path: file,
+    };
+}
+/** The latest report of a run, or null when verification has not passed yet (or the file is unreadable). */
+export function readSpecTraceReport(context) {
+    try {
+        const file = specTracePath(context);
+        if (!existsSync(file))
+            return null;
+        const value = JSON.parse(readFileSync(file, 'utf8'));
+        return value && typeof value === 'object' && value.schemaVersion === SPEC_TRACE_SCHEMA_VERSION ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The acceptance finding that records the advisory trace next to the receipt. */
+export function specTraceFinding(trace) {
+    const touched = trace.touched.length ? `; touched by this change ${trace.touched.length - trace.touchedUndemonstrated.length}/${trace.touched.length}${trace.touchedUndemonstrated.length ? ' (not demonstrated: ' + trace.touchedUndemonstrated.map(item => item.id).join(', ') + ')' : ''}` : '';
+    return `Spec trace (advisory, receipt ${trace.receiptId ?? 'unknown'}): ${trace.summary}${touched}.`;
+}

package/dist/agent-runtime/graph/state.d.ts

@@ -14,6 +14,8 @@ export interface ArchitectureRecord {
     question?: string;
     /** True when a low-confidence design proceeded on stated assumptions instead of asking. */
     assumed?: boolean;
+    /** Ambiguities the architect reported before planning (see clarifications.ts). */
+    clarifications?: import('./clarifications.js').Clarification[];
 }
 export interface DeveloperRecord {
     summary: string;
@@ -52,6 +54,8 @@ export interface VerificationRecord {
     selfMutation?: import('../../pipeline/pipeline-state.js').VerificationSelfMutation;
     /** Files verification regenerated that the host kept in the candidate; roles must not revert them. Sticky for the run. */
     adoptedOutputs?: import('../../pipeline/pipeline-state.js').CandidateFileChange[];
+    /** Advisory requirement ↔ test trace of a passing verification (spec-trace.json), bound to `receiptId`. */
+    specTrace?: import('./spec-trace-record.js').SpecTraceSummary;
 }
 export interface ReviewRecord {
     sessionId?: string;
@@ -62,6 +66,10 @@ export interface ReviewRecord {
     score: number;
     aspects: Record<string, number>;
     candidateHash?: string;
+    /** Advisory risk brief (see review-brief.ts); never part of the approval gate. */
+    brief?: import('./review-brief.js').ReviewBrief;
+    /** Why a malformed brief was dropped after the repair turn. */
+    briefDiagnostic?: string;
 }
 export interface ArchiveRecord {
     archivePath: string;

package/dist/agent-runtime/index.d.ts

@@ -11,6 +11,13 @@ export * from './core-host.js';
 export * from './graph/state.js';
 export { coreNodes, developerRecord, buildAcceptanceReport, MAX_DEEPEN_PASSES, type CoreNodeDeps } from './graph/nodes.js';
 export { DEFAULT_REVIEW_POLICY, REVIEW_ASPECTS, evaluateReview, resolveReviewPolicy, type ReviewAspect, type ReviewPolicy } from './graph/review-policy.js';
+export { REVIEW_BRIEF_RISK_LIMIT, REVIEW_BRIEF_SCHEMA, REVIEW_BRIEF_SCHEMA_VERSION, parseReviewBrief, type ReviewBrief, type ReviewRisk } from './graph/review-brief.js';
+export { REVIEW_BRIEF_FILE, readReviewBriefRecord, reviewBriefPath, type ReviewBriefRecord } from './graph/review-brief-record.js';
+export { BASELINE_BLOCKER, BASELINE_FILE, BASELINE_SCHEMA_VERSION, baselinePath, blastRadiusFiles, detectBaseline, readBaselineRecord, type BaselineDetection, type BaselineRecord } from './graph/baseline.js';
+export { CAPABILITY_MAP_PATH, CAPABILITY_MAP_SCHEMA_VERSION, readCapabilityMap, type CapabilityMap } from './graph/capability-map.js';
+export { SPEC_TRACE_FILE, SPEC_TRACE_SCHEMA_VERSION, requirementSlug, requirementId, traceSpecs, touchedRequirements, type SpecTraceReport, type SpecTraceInput } from '../pipeline/spec-trace.js';
+export { readSpecTraceReport, specTracePath, type SpecTraceSummary } from './graph/spec-trace-record.js';
+export { CLARIFICATIONS_FILE, CLARIFICATIONS_SCHEMA, CLARIFICATIONS_SCHEMA_VERSION, CLARIFICATION_POLICIES, blockingClarifications, designSection, parseClarifications, readClarificationsRecord, clarificationsPath, type Clarification, type ClarificationPolicy, type ClarificationsRecord } from './graph/clarifications.js';
 export { createRoleInvoker, type Accept, type InvokeOptions, type InvokeOutcome, type RoleInvoker, type RoleInvokerDeps } from './graph/roles.js';
 export { parseAgentObject } from './graph/artifacts.js';
 export { FileCheckpointSaver, type GraphStoreIO, type SerializedGraphStore } from './graph-checkpointer.js';

package/dist/agent-runtime/index.js

@@ -11,6 +11,13 @@ export * from './core-host.js';
 export * from './graph/state.js';
 export { coreNodes, developerRecord, buildAcceptanceReport, MAX_DEEPEN_PASSES } from './graph/nodes.js';
 export { DEFAULT_REVIEW_POLICY, REVIEW_ASPECTS, evaluateReview, resolveReviewPolicy } from './graph/review-policy.js';
+export { REVIEW_BRIEF_RISK_LIMIT, REVIEW_BRIEF_SCHEMA, REVIEW_BRIEF_SCHEMA_VERSION, parseReviewBrief } from './graph/review-brief.js';
+export { REVIEW_BRIEF_FILE, readReviewBriefRecord, reviewBriefPath } from './graph/review-brief-record.js';
+export { BASELINE_BLOCKER, BASELINE_FILE, BASELINE_SCHEMA_VERSION, baselinePath, blastRadiusFiles, detectBaseline, readBaselineRecord } from './graph/baseline.js';
+export { CAPABILITY_MAP_PATH, CAPABILITY_MAP_SCHEMA_VERSION, readCapabilityMap } from './graph/capability-map.js';
+export { SPEC_TRACE_FILE, SPEC_TRACE_SCHEMA_VERSION, requirementSlug, requirementId, traceSpecs, touchedRequirements } from '../pipeline/spec-trace.js';
+export { readSpecTraceReport, specTracePath } from './graph/spec-trace-record.js';
+export { CLARIFICATIONS_FILE, CLARIFICATIONS_SCHEMA, CLARIFICATIONS_SCHEMA_VERSION, CLARIFICATION_POLICIES, blockingClarifications, designSection, parseClarifications, readClarificationsRecord, clarificationsPath } from './graph/clarifications.js';
 export { createRoleInvoker } from './graph/roles.js';
 export { parseAgentObject } from './graph/artifacts.js';
 export { FileCheckpointSaver } from './graph-checkpointer.js';

package/dist/agent-runtime/openspec.d.ts

@@ -6,6 +6,7 @@ export declare const ROLE_SKILLS: {
     readonly developer: 'openspec-apply-change';
     readonly reviewer: 'openspec-verify-change';
 };
+export declare const DEFAULT_PROJECT_CONFIG = "schema: spec-driven\n";
 export interface OpenSpecRoleContext {
     evidenceScope?: {
         backlogRoot: string;

package/dist/agent-runtime/openspec.js

@@ -11,7 +11,7 @@ export const OPENSPEC_VERSION = '1.14.3';
 export const ROLE_SKILLS = { architect: 'openspec-ff-change', developer: 'openspec-apply-change', reviewer: 'openspec-verify-change' };
 /** Where `openspec init --tools` writes each provider's skills (Codex and Kimi moved in 1.14). */
 const OPENSPEC_SKILL_DIRECTORIES = { claude: '.claude', codex: '.agents', gemini: '.gemini', kimi: '.kimi-code' };
-const DEFAULT_PROJECT_CONFIG = 'schema: spec-driven\n';
+export const DEFAULT_PROJECT_CONFIG = 'schema: spec-driven\n';
 /** Saved built-in contexts retain their original shape; new roles carry explicit policy. */
 export function openSpecPolicy(context) {
     const legacy = isBuiltinRole(context.role) ? BUILTIN_ROLE_POLICY[context.role] : undefined;

package/dist/agent-runtime/project-rules.d.ts

@@ -0,0 +1,139 @@
+import type { PipelineContext } from '../pipeline/pipeline-state.js';
+import type { ExecutorRegistry } from './executors.js';
+import type { AgentExecutor, AgentUsage, RuntimeConfig } from './executor-types.js';
+export declare const RULES_INVENTORY_VERSION = 1;
+export declare const RULES_FILE = ".specrails/rules.json";
+export declare const RULE_SOURCE_FILES: readonly ['CLAUDE.md', 'AGENTS.md', 'CONTRIBUTING.md', '.github/CONTRIBUTING.md', 'docs/CONTRIBUTING.md'];
+export declare const GATE_KINDS: readonly ['lint', 'format', 'typecheck', 'test', 'architecture', 'hook', 'ci', 'spec'];
+export declare const RULE_STATUSES: readonly ['enforcedBy', 'automatable', 'humanOnly', 'unclassified'];
+export type GateKind = typeof GATE_KINDS[number];
+export type RuleStatus = typeof RULE_STATUSES[number];
+export interface RulesGate {
+    id: string;
+    kind: GateKind;
+    /** Shell-free command line a host can run from the repository root. */
+    command: string;
+    /** Repository-relative file that revealed the gate. */
+    source: string;
+}
+export interface ProjectRule {
+    /** Stable across line moves: hash of the source file and the normalized statement. */
+    id: string;
+    text: string;
+    /** `<repository-relative file>:<line>` of the statement's first line. */
+    source: string;
+    status: RuleStatus;
+    /** With `enforcedBy`: the gate id (or the named test/check) that already enforces the rule. */
+    enforcedBy?: string;
+    /** With `automatable`: the check that would enforce it. */
+    proposedCheck?: string;
+}
+export interface RulesClassification {
+    status: 'classified' | 'cached' | 'offline' | 'unavailable' | 'failed' | 'empty';
+    provider?: string;
+    model?: string;
+    reason?: string;
+    classifiedAt?: string;
+    usage?: AgentUsage;
+}
+export interface RulesInventory {
+    schemaVersion: 1;
+    generatedAt: string;
+    gates: RulesGate[];
+    rules: ProjectRule[];
+    classification: RulesClassification;
+}
+/** JSON with comments and trailing commas (tsconfig, biome.jsonc). */
+export declare function parseJsonc(text: string): unknown;
+/** `run:` commands of a GitHub workflow (single line, literal `|` and folded `>` block scalars). */
+export declare function workflowRunCommands(text: string): string[];
+/** Deterministic gate discovery for one repository root. */
+export declare function discoverGates(root: string): RulesGate[];
+export declare function ruleId(file: string, text: string): string;
+/**
+ * Rule statements of one instruction file: list items (with their wrapped
+ * continuation lines) and strongly normative paragraph sentences, outside code
+ * fences, tables and Specrails-managed blocks.
+ */
+export declare function parseRuleStatements(text: string, file: string): Array<{
+    text: string;
+    source: string;
+}>;
+/** Every rule statement of the instruction files present in `root`, deduplicated, with stable ids. */
+export declare function collectRuleStatements(root: string): ProjectRule[];
+export declare const RULES_CLASSIFICATION_SCHEMA: {
+    readonly type: 'object';
+    readonly additionalProperties: false;
+    readonly required: readonly ['rules'];
+    readonly properties: {
+        readonly rules: {
+            readonly type: 'array';
+            readonly items: {
+                readonly type: 'object';
+                readonly additionalProperties: false;
+                readonly required: readonly ['id', 'status'];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: 'string';
+                    };
+                    readonly status: {
+                        readonly enum: readonly ['enforcedBy', 'automatable', 'humanOnly'];
+                    };
+                    readonly enforcedBy: {
+                        readonly type: 'string';
+                    };
+                    readonly proposedCheck: {
+                        readonly type: 'string';
+                    };
+                };
+            };
+        };
+    };
+};
+export declare function classificationPrompt(gates: readonly RulesGate[], rules: readonly ProjectRule[]): string;
+/** Applies a model reply to the parsed rules: only known ids and statuses; text and source never change. */
+export declare function applyClassification(rules: readonly ProjectRule[], reply: Record<string, unknown>): {
+    rules: ProjectRule[];
+    classified: number;
+};
+export declare function readRulesInventory(file: string): RulesInventory | undefined;
+export interface RulesInventoryOptions {
+    /** Repository whose gates and instruction files are inventoried. */
+    root: string;
+    /** Directory holding `.specrails/` (rules.json and agent-runtime.json); defaults to `root`. */
+    artifactRoot?: string;
+    /** false: deterministic only (gates + rules, unclassified unless cached). */
+    classify?: boolean;
+    /** Ignore cached classifications and classify every rule again. */
+    reclassify?: boolean;
+    /** Runtime configuration; defaults to `<artifactRoot>/.specrails/agent-runtime.json`. */
+    config?: RuntimeConfig;
+    /** Programmatic executors (tests, hosts) replacing configured ones. */
+    executors?: Record<string, AgentExecutor>;
+    registry?: ExecutorRegistry;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    now?: () => Date;
+}
+/**
+ * Builds and writes `.specrails/rules.json`. Rules whose statement did not
+ * change keep their previous classification, so a re-run (and `init`) only
+ * classifies what is new; the classification never blocks the inventory.
+ */
+export declare function runRulesInventory(options: RulesInventoryOptions): Promise<{
+    file: string;
+    inventory: RulesInventory;
+}>;
+/** What the runtime hands the roles: the human-only rules and the discovered gates. */
+export interface ProjectRulesContext {
+    humanOnly: Array<Pick<ProjectRule, 'text' | 'source'>>;
+    gates: Array<Pick<RulesGate, 'id' | 'kind' | 'command'>>;
+}
+/** Reads `.specrails/rules.json` next to the run's backlog, else in the artifact repository. */
+export declare function projectRulesContext(context: Pick<PipelineContext, 'backlogRoot' | 'artifactRoot'>): ProjectRulesContext | undefined;
+/** `specrails-core rules inventory [--root <dir>] [--artifact-root <dir>] [--offline] [--reclassify] [--json]`. */
+export declare function runRulesCommand(flags: Record<string, string | boolean>, positionals: string[], io?: {
+    stdout?: (text: string) => void;
+    stderr?: (text: string) => void;
+    executors?: Record<string, AgentExecutor>;
+}): Promise<number>;