specrails-core 5.3.0 → 5.5.0

package/dist/agent-runtime/compact/architect.d.ts

@@ -0,0 +1,349 @@
+import type { AgentResult } from '../executor-types.js';
+import { type CompactEnv } from './step.js';
+/** The load-bearing tokens of a criterion: identifiers (`createGame`, `applyInput`, `tick`), numbers and hyphenated terms — never prose words. */
+export declare function criterionTokens(text: string): string[];
+export interface Inventory {
+    greenfield: boolean;
+    languages: string[];
+    frameworks: string[];
+    keyFiles: string[];
+    tests: string[];
+    notes: string;
+}
+export interface Proposal {
+    why: string;
+    whatChanges: string[];
+    capabilities: {
+        new: string[];
+        modified: string[];
+    };
+    impact: string[];
+}
+export interface Design {
+    context: string;
+    goals: string[];
+    nonGoals: string[];
+    decisions: {
+        title: string;
+        choice: string;
+        why: string;
+    }[];
+    risks: {
+        risk: string;
+        mitigation: string;
+    }[];
+}
+export interface Spec {
+    name: string;
+    requirements: {
+        name: string;
+        text: string;
+        scenarios: {
+            name: string;
+            when: string;
+            then: string;
+        }[];
+    }[];
+}
+export interface Tasks {
+    groups: {
+        title: string;
+        tasks: string[];
+    }[];
+    verification: {
+        repositoryId: string;
+        command: string;
+        args: string[];
+    }[];
+    blockingQuestion?: string;
+}
+export declare const INVENTORY_SCHEMA: {
+    type: string;
+    additionalProperties: boolean;
+    required: string[];
+    properties: {
+        greenfield: {
+            type: string;
+        };
+        languages: {
+            type: string;
+            items: {
+                type: string;
+            };
+        };
+        frameworks: {
+            type: string;
+            items: {
+                type: string;
+            };
+        };
+        keyFiles: {
+            type: string;
+            items: {
+                type: string;
+            };
+        };
+        tests: {
+            type: string;
+            items: {
+                type: string;
+            };
+        };
+        notes: {
+            type: string;
+        };
+    };
+};
+export declare const PROPOSAL_SCHEMA: {
+    type: string;
+    additionalProperties: boolean;
+    required: string[];
+    properties: {
+        why: {
+            type: string;
+        };
+        whatChanges: {
+            type: string;
+            items: {
+                type: string;
+            };
+        };
+        capabilities: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                new: {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                };
+                modified: {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                };
+            };
+        };
+        impact: {
+            type: string;
+            items: {
+                type: string;
+            };
+        };
+    };
+};
+export declare const DESIGN_SCHEMA: {
+    type: string;
+    additionalProperties: boolean;
+    required: string[];
+    properties: {
+        context: {
+            type: string;
+        };
+        goals: {
+            type: string;
+            items: {
+                type: string;
+            };
+        };
+        nonGoals: {
+            type: string;
+            items: {
+                type: string;
+            };
+        };
+        decisions: {
+            type: string;
+            items: {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: {
+                    title: {
+                        type: string;
+                    };
+                    choice: {
+                        type: string;
+                    };
+                    why: {
+                        type: string;
+                    };
+                };
+            };
+        };
+        risks: {
+            type: string;
+            items: {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: {
+                    risk: {
+                        type: string;
+                    };
+                    mitigation: {
+                        type: string;
+                    };
+                };
+            };
+        };
+    };
+};
+export declare const SPEC_SCHEMA: {
+    type: string;
+    additionalProperties: boolean;
+    required: string[];
+    properties: {
+        name: {
+            type: string;
+        };
+        requirements: {
+            type: string;
+            items: {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: {
+                    name: {
+                        type: string;
+                    };
+                    text: {
+                        type: string;
+                    };
+                    scenarios: {
+                        type: string;
+                        items: {
+                            type: string;
+                            additionalProperties: boolean;
+                            required: string[];
+                            properties: {
+                                name: {
+                                    type: string;
+                                };
+                                when: {
+                                    type: string;
+                                };
+                                then: {
+                                    type: string;
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+};
+export declare const TASKS_SCHEMA: {
+    type: string;
+    additionalProperties: boolean;
+    required: string[];
+    properties: {
+        groups: {
+            type: string;
+            items: {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: {
+                    title: {
+                        type: string;
+                    };
+                    tasks: {
+                        type: string;
+                        items: {
+                            type: string;
+                        };
+                    };
+                };
+            };
+        };
+        verification: {
+            type: string;
+            items: {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: {
+                    repositoryId: {
+                        type: string;
+                    };
+                    command: {
+                        type: string;
+                    };
+                    args: {
+                        type: string;
+                        items: {
+                            type: string;
+                        };
+                    };
+                };
+            };
+        };
+        blockingQuestion: {
+            type: string;
+        };
+    };
+};
+/** True when no repository holds anything but OpenSpec artifacts and repository boilerplate. */
+export declare function hostGreenfield(roots: string[]): boolean;
+/** Rendered with the exact headings `openspec instructions proposal` returns. */
+export declare function renderProposal(proposal: Proposal, capabilityNames: {
+    new: string[];
+    modified: string[];
+}): string;
+export declare function renderDesign(design: Design, greenfield: boolean): string;
+/** True when any media/font file exists under the roots (bounded walk, dot/dependency dirs skipped). */
+export declare function hasBinaryAssets(roots: readonly string[], limit?: number): boolean;
+/**
+ * One requirement lives in exactly one capability. A small model given
+ * "write the requirements of capability X" restates the WHOLE ticket under
+ * every capability (observed: 20 requirements for 8 obligations across
+ * sound-effects / audio-controls / gameplay-events, three near-identical
+ * lists). Later capabilities lose the requirements an earlier one already
+ * holds (same normalized name, or ≥ 0.6 token overlap of the SHALL text);
+ * a capability left empty is dropped. Returns the kept specs and the drops.
+ */
+export declare function dedupeSpecRequirements(specs: readonly Spec[]): {
+    specs: Spec[];
+    dropped: Array<{
+        capability: string;
+        requirement: string;
+        keptIn: string;
+    }>;
+};
+/**
+ * Every acceptance criterion of the ticket must reach a spec, or the plan
+ * (which is validated against the specs) can legitimately skip it (observed:
+ * the ticket listed soft-drop among the SFX actions; no spec mentioned it,
+ * no task implemented it). Criteria with no identifier/number token in any
+ * requirement text are appended verbatim to the best-matching capability,
+ * as the requester's own words.
+ */
+export declare function coverCriteria(specs: Spec[], criteria: readonly string[]): {
+    specs: Spec[];
+    added: string[];
+};
+export declare function renderSpec(spec: Spec): string;
+export declare function renderTasks(groups: {
+    title: string;
+    tasks: string[];
+}[]): string;
+/**
+ * Rejects plans a small model tends to produce: tasks that "implement" by
+ * writing next to the frozen OpenSpec plan (verify then fails with
+ * "Architecture artifacts changed after design approval") and plans made only
+ * of documents/specs. Returned text is fed back to the model for ONE retry.
+ */
+export declare function validateTaskPlan(value: Record<string, unknown>, repositories: string[], requirements?: readonly string[]): string | undefined;
+/** Test seam for the task normaliser. */
+export declare function normalizeTasksForTest(raw: Record<string, unknown>, repositories?: string[]): Tasks;
+/**
+ * The compact architect: a bounded inventory, four tool-less structured steps
+ * and host-rendered OpenSpec artifacts written through the official workflow, so
+ * the graph's participation and completeness checks pass unchanged.
+ */
+export declare function runCompactArchitect(env: CompactEnv): Promise<AgentResult>;