@maintainabilityai/research-runner 0.1.1

package/dist/schemas/prd-doc.d.ts

@@ -0,0 +1,249 @@
+/**
+ * PrdDoc — the published PRD artifact + the grounding block the refinement
+ * loop accumulates over iterations.
+ */
+import { z } from 'zod';
+export declare const GroundingBlock: z.ZodObject<{
+    final_iteration: z.ZodNumber;
+    /** Per-iteration scores from both experts (length = iterations * 2). */
+    iterations: z.ZodArray<z.ZodObject<{
+        expert: z.ZodEnum<["architecture", "security"]>;
+        iteration: z.ZodNumber;
+        score: z.ZodNumber;
+        severity: z.ZodEnum<["PASS", "MINOR", "MAJOR", "BLOCKING"]>;
+        covered_ids: z.ZodArray<z.ZodString, "many">;
+        missing_ids: z.ZodArray<z.ZodString, "many">;
+        changes: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        expert: "architecture" | "security";
+        iteration: number;
+        score: number;
+        severity: "PASS" | "MINOR" | "MAJOR" | "BLOCKING";
+        covered_ids: string[];
+        missing_ids: string[];
+        changes: string[];
+    }, {
+        expert: "architecture" | "security";
+        iteration: number;
+        score: number;
+        severity: "PASS" | "MINOR" | "MAJOR" | "BLOCKING";
+        covered_ids: string[];
+        missing_ids: string[];
+        changes: string[];
+    }>, "many">;
+    /** Deterministic citation-coverage check independent of LLM scores. */
+    citation_coverage: z.ZodObject<{
+        threats_in_scope: z.ZodNumber;
+        threats_covered_by_sr: z.ZodNumber;
+        calm_nodes_in_scope: z.ZodNumber;
+        calm_nodes_cited_by_fr: z.ZodNumber;
+        self_reported_no_count: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        threats_in_scope: number;
+        threats_covered_by_sr: number;
+        calm_nodes_in_scope: number;
+        calm_nodes_cited_by_fr: number;
+        self_reported_no_count: number;
+    }, {
+        threats_in_scope: number;
+        threats_covered_by_sr: number;
+        calm_nodes_in_scope: number;
+        calm_nodes_cited_by_fr: number;
+        self_reported_no_count: number;
+    }>;
+    /** Final composite score combining LLM expert + citation signals. */
+    final_score: z.ZodNumber;
+    passed: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    final_iteration: number;
+    iterations: {
+        expert: "architecture" | "security";
+        iteration: number;
+        score: number;
+        severity: "PASS" | "MINOR" | "MAJOR" | "BLOCKING";
+        covered_ids: string[];
+        missing_ids: string[];
+        changes: string[];
+    }[];
+    citation_coverage: {
+        threats_in_scope: number;
+        threats_covered_by_sr: number;
+        calm_nodes_in_scope: number;
+        calm_nodes_cited_by_fr: number;
+        self_reported_no_count: number;
+    };
+    final_score: number;
+    passed: boolean;
+}, {
+    final_iteration: number;
+    iterations: {
+        expert: "architecture" | "security";
+        iteration: number;
+        score: number;
+        severity: "PASS" | "MINOR" | "MAJOR" | "BLOCKING";
+        covered_ids: string[];
+        missing_ids: string[];
+        changes: string[];
+    }[];
+    citation_coverage: {
+        threats_in_scope: number;
+        threats_covered_by_sr: number;
+        calm_nodes_in_scope: number;
+        calm_nodes_cited_by_fr: number;
+        self_reported_no_count: number;
+    };
+    final_score: number;
+    passed: boolean;
+}>;
+export type GroundingBlock = z.infer<typeof GroundingBlock>;
+export declare const PrdDoc: z.ZodObject<{
+    run_id: z.ZodString;
+    topic: z.ZodString;
+    generated_at: z.ZodEffects<z.ZodString, string, string>;
+    body_md: z.ZodString;
+    grounding: z.ZodObject<{
+        final_iteration: z.ZodNumber;
+        /** Per-iteration scores from both experts (length = iterations * 2). */
+        iterations: z.ZodArray<z.ZodObject<{
+            expert: z.ZodEnum<["architecture", "security"]>;
+            iteration: z.ZodNumber;
+            score: z.ZodNumber;
+            severity: z.ZodEnum<["PASS", "MINOR", "MAJOR", "BLOCKING"]>;
+            covered_ids: z.ZodArray<z.ZodString, "many">;
+            missing_ids: z.ZodArray<z.ZodString, "many">;
+            changes: z.ZodArray<z.ZodString, "many">;
+        }, "strip", z.ZodTypeAny, {
+            expert: "architecture" | "security";
+            iteration: number;
+            score: number;
+            severity: "PASS" | "MINOR" | "MAJOR" | "BLOCKING";
+            covered_ids: string[];
+            missing_ids: string[];
+            changes: string[];
+        }, {
+            expert: "architecture" | "security";
+            iteration: number;
+            score: number;
+            severity: "PASS" | "MINOR" | "MAJOR" | "BLOCKING";
+            covered_ids: string[];
+            missing_ids: string[];
+            changes: string[];
+        }>, "many">;
+        /** Deterministic citation-coverage check independent of LLM scores. */
+        citation_coverage: z.ZodObject<{
+            threats_in_scope: z.ZodNumber;
+            threats_covered_by_sr: z.ZodNumber;
+            calm_nodes_in_scope: z.ZodNumber;
+            calm_nodes_cited_by_fr: z.ZodNumber;
+            self_reported_no_count: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            threats_in_scope: number;
+            threats_covered_by_sr: number;
+            calm_nodes_in_scope: number;
+            calm_nodes_cited_by_fr: number;
+            self_reported_no_count: number;
+        }, {
+            threats_in_scope: number;
+            threats_covered_by_sr: number;
+            calm_nodes_in_scope: number;
+            calm_nodes_cited_by_fr: number;
+            self_reported_no_count: number;
+        }>;
+        /** Final composite score combining LLM expert + citation signals. */
+        final_score: z.ZodNumber;
+        passed: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        final_iteration: number;
+        iterations: {
+            expert: "architecture" | "security";
+            iteration: number;
+            score: number;
+            severity: "PASS" | "MINOR" | "MAJOR" | "BLOCKING";
+            covered_ids: string[];
+            missing_ids: string[];
+            changes: string[];
+        }[];
+        citation_coverage: {
+            threats_in_scope: number;
+            threats_covered_by_sr: number;
+            calm_nodes_in_scope: number;
+            calm_nodes_cited_by_fr: number;
+            self_reported_no_count: number;
+        };
+        final_score: number;
+        passed: boolean;
+    }, {
+        final_iteration: number;
+        iterations: {
+            expert: "architecture" | "security";
+            iteration: number;
+            score: number;
+            severity: "PASS" | "MINOR" | "MAJOR" | "BLOCKING";
+            covered_ids: string[];
+            missing_ids: string[];
+            changes: string[];
+        }[];
+        citation_coverage: {
+            threats_in_scope: number;
+            threats_covered_by_sr: number;
+            calm_nodes_in_scope: number;
+            calm_nodes_cited_by_fr: number;
+            self_reported_no_count: number;
+        };
+        final_score: number;
+        passed: boolean;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    topic: string;
+    run_id: string;
+    generated_at: string;
+    body_md: string;
+    grounding: {
+        final_iteration: number;
+        iterations: {
+            expert: "architecture" | "security";
+            iteration: number;
+            score: number;
+            severity: "PASS" | "MINOR" | "MAJOR" | "BLOCKING";
+            covered_ids: string[];
+            missing_ids: string[];
+            changes: string[];
+        }[];
+        citation_coverage: {
+            threats_in_scope: number;
+            threats_covered_by_sr: number;
+            calm_nodes_in_scope: number;
+            calm_nodes_cited_by_fr: number;
+            self_reported_no_count: number;
+        };
+        final_score: number;
+        passed: boolean;
+    };
+}, {
+    topic: string;
+    run_id: string;
+    generated_at: string;
+    body_md: string;
+    grounding: {
+        final_iteration: number;
+        iterations: {
+            expert: "architecture" | "security";
+            iteration: number;
+            score: number;
+            severity: "PASS" | "MINOR" | "MAJOR" | "BLOCKING";
+            covered_ids: string[];
+            missing_ids: string[];
+            changes: string[];
+        }[];
+        citation_coverage: {
+            threats_in_scope: number;
+            threats_covered_by_sr: number;
+            calm_nodes_in_scope: number;
+            calm_nodes_cited_by_fr: number;
+            self_reported_no_count: number;
+        };
+        final_score: number;
+        passed: boolean;
+    };
+}>;
+export type PrdDoc = z.infer<typeof PrdDoc>;

package/dist/schemas/prd-doc.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrdDoc = exports.GroundingBlock = void 0;
+/**
+ * PrdDoc — the published PRD artifact + the grounding block the refinement
+ * loop accumulates over iterations.
+ */
+const zod_1 = require("zod");
+const primitives_1 = require("./primitives");
+/** One iteration's expert review record — both arch + sec contribute one each. */
+const ExpertReviewRecord = zod_1.z.object({
+    expert: zod_1.z.enum(['architecture', 'security']),
+    iteration: zod_1.z.number().int().min(1).max(5),
+    score: zod_1.z.number().min(0).max(1),
+    severity: zod_1.z.enum(['PASS', 'MINOR', 'MAJOR', 'BLOCKING']),
+    covered_ids: zod_1.z.array(zod_1.z.string()),
+    missing_ids: zod_1.z.array(zod_1.z.string()),
+    changes: zod_1.z.array(zod_1.z.string()),
+});
+exports.GroundingBlock = zod_1.z.object({
+    final_iteration: zod_1.z.number().int().min(1).max(5),
+    /** Per-iteration scores from both experts (length = iterations * 2). */
+    iterations: zod_1.z.array(ExpertReviewRecord),
+    /** Deterministic citation-coverage check independent of LLM scores. */
+    citation_coverage: zod_1.z.object({
+        threats_in_scope: zod_1.z.number().int().nonnegative(),
+        threats_covered_by_sr: zod_1.z.number().int().nonnegative(),
+        calm_nodes_in_scope: zod_1.z.number().int().nonnegative(),
+        calm_nodes_cited_by_fr: zod_1.z.number().int().nonnegative(),
+        self_reported_no_count: zod_1.z.number().int().nonnegative(),
+    }),
+    /** Final composite score combining LLM expert + citation signals. */
+    final_score: zod_1.z.number().min(0).max(1),
+    passed: zod_1.z.boolean(),
+});
+exports.PrdDoc = zod_1.z.object({
+    run_id: primitives_1.RunId,
+    topic: zod_1.z.string(),
+    generated_at: primitives_1.IsoTimestamp,
+    body_md: zod_1.z.string().min(1),
+    grounding: exports.GroundingBlock,
+});

package/dist/schemas/prd-manifest.d.ts

@@ -0,0 +1,171 @@
+/**
+ * PrdManifest — the machine-readable spec the spec-ready-handler reads on
+ * the code-repo side to generate an RCTRO implementation issue.
+ *
+ * Lives alongside the PRD markdown as `<topic>.manifest.json`.
+ */
+import { z } from 'zod';
+/**
+ * Per-BAR impact classification. The PRD manifest carries the same set of
+ * BARs the platform spans (when scope is platform) or just the single BAR
+ * (when scope is bar), each tagged with the confidence that PRD work
+ * actually touches it. `notify-code-repos.yml` reads this to decide which
+ * code repos get a landing-issue (HIGH only) and which get a footer
+ * mention as "other BARs in the platform — review needed?" (LOW).
+ *
+ * HIGH: the BAR owns at least one CALM node referenced by an endpoint, or
+ *       owns at least one threat cited by a security requirement.
+ * LOW : the BAR is part of the platform but has no direct citation in
+ *       the manifest. Could still be impacted (shared infra, dependency
+ *       chains) but no concrete signal from the PRD.
+ */
+declare const ImpactedBar: z.ZodObject<{
+    bar_id: z.ZodString;
+    repos: z.ZodArray<z.ZodString, "many">;
+    confidence: z.ZodEnum<["high", "low"]>;
+    reasoning: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    bar_id: string;
+    confidence: "high" | "low";
+    repos: string[];
+    reasoning: string;
+}, {
+    bar_id: string;
+    confidence: "high" | "low";
+    repos: string[];
+    reasoning: string;
+}>;
+export type ImpactedBar = z.infer<typeof ImpactedBar>;
+export declare const PrdManifest: z.ZodObject<{
+    run_id: z.ZodString;
+    prd_topic: z.ZodString;
+    /** Mesh repo SHA at PRD publish time. */
+    mesh_sha: z.ZodString;
+    /**
+     * Code repos `notify-code-repos.yml` opens a landing-issue in. Equals
+     * the union of `impacted_bars[].repos` for HIGH-confidence entries.
+     * LOW-confidence BARs are NOT included here — they only surface as
+     * footer mentions in the HIGH BARs' landing-issues.
+     */
+    target_repos: z.ZodArray<z.ZodString, "many">;
+    /**
+     * Per-BAR impact classification. Drives which repos in `target_repos`
+     * get an issue and what "Why this repo?" reasoning the issue body
+     * carries. See ImpactedBar above for the HIGH vs LOW semantics.
+     */
+    impacted_bars: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        bar_id: z.ZodString;
+        repos: z.ZodArray<z.ZodString, "many">;
+        confidence: z.ZodEnum<["high", "low"]>;
+        reasoning: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        bar_id: string;
+        confidence: "high" | "low";
+        repos: string[];
+        reasoning: string;
+    }, {
+        bar_id: string;
+        confidence: "high" | "low";
+        repos: string[];
+        reasoning: string;
+    }>, "many">>;
+    endpoints: z.ZodArray<z.ZodObject<{
+        /** HTTP method + path, e.g. "POST /favorites". */
+        signature: z.ZodString;
+        /** CALM node id this endpoint resides in. */
+        calm_node: z.ZodString;
+        /** FR-NN id from the PRD body that specifies this endpoint. */
+        fr_id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        signature: string;
+        calm_node: string;
+        fr_id: string;
+    }, {
+        signature: string;
+        calm_node: string;
+        fr_id: string;
+    }>, "many">;
+    security_requirements: z.ZodArray<z.ZodObject<{
+        /** SR-NN id from the PRD body. */
+        id: z.ZodString;
+        /** Citations: THR-NNN, A0X, NIST-XX-NN — at least one required. */
+        citations: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        citations: string[];
+    }, {
+        id: string;
+        citations: string[];
+    }>, "many">;
+    /** Final grounding state from the refinement loop. */
+    grounding: z.ZodObject<{
+        final_score: z.ZodNumber;
+        threshold: z.ZodNumber;
+        iterations: z.ZodNumber;
+        passed: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        iterations: number;
+        final_score: number;
+        passed: boolean;
+        threshold: number;
+    }, {
+        iterations: number;
+        final_score: number;
+        passed: boolean;
+        threshold: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    mesh_sha: string;
+    run_id: string;
+    grounding: {
+        iterations: number;
+        final_score: number;
+        passed: boolean;
+        threshold: number;
+    };
+    prd_topic: string;
+    target_repos: string[];
+    impacted_bars: {
+        bar_id: string;
+        confidence: "high" | "low";
+        repos: string[];
+        reasoning: string;
+    }[];
+    endpoints: {
+        signature: string;
+        calm_node: string;
+        fr_id: string;
+    }[];
+    security_requirements: {
+        id: string;
+        citations: string[];
+    }[];
+}, {
+    mesh_sha: string;
+    run_id: string;
+    grounding: {
+        iterations: number;
+        final_score: number;
+        passed: boolean;
+        threshold: number;
+    };
+    prd_topic: string;
+    target_repos: string[];
+    endpoints: {
+        signature: string;
+        calm_node: string;
+        fr_id: string;
+    }[];
+    security_requirements: {
+        id: string;
+        citations: string[];
+    }[];
+    impacted_bars?: {
+        bar_id: string;
+        confidence: "high" | "low";
+        repos: string[];
+        reasoning: string;
+    }[] | undefined;
+}>;
+export type PrdManifest = z.infer<typeof PrdManifest>;
+export {};

package/dist/schemas/prd-manifest.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrdManifest = void 0;
+/**
+ * PrdManifest — the machine-readable spec the spec-ready-handler reads on
+ * the code-repo side to generate an RCTRO implementation issue.
+ *
+ * Lives alongside the PRD markdown as `<topic>.manifest.json`.
+ */
+const zod_1 = require("zod");
+const primitives_1 = require("./primitives");
+const Endpoint = zod_1.z.object({
+    /** HTTP method + path, e.g. "POST /favorites". */
+    signature: zod_1.z.string(),
+    /** CALM node id this endpoint resides in. */
+    calm_node: zod_1.z.string(),
+    /** FR-NN id from the PRD body that specifies this endpoint. */
+    fr_id: zod_1.z.string().regex(/^FR-\d+$/),
+});
+const SecurityRequirement = zod_1.z.object({
+    /** SR-NN id from the PRD body. */
+    id: zod_1.z.string().regex(/^SR-\d+$/),
+    /** Citations: THR-NNN, A0X, NIST-XX-NN — at least one required. */
+    citations: zod_1.z.array(zod_1.z.string().regex(/^(THR-\d+|A\d{2}|NIST-[A-Z]{2}-\d+)$/)).min(1),
+});
+/**
+ * Per-BAR impact classification. The PRD manifest carries the same set of
+ * BARs the platform spans (when scope is platform) or just the single BAR
+ * (when scope is bar), each tagged with the confidence that PRD work
+ * actually touches it. `notify-code-repos.yml` reads this to decide which
+ * code repos get a landing-issue (HIGH only) and which get a footer
+ * mention as "other BARs in the platform — review needed?" (LOW).
+ *
+ * HIGH: the BAR owns at least one CALM node referenced by an endpoint, or
+ *       owns at least one threat cited by a security requirement.
+ * LOW : the BAR is part of the platform but has no direct citation in
+ *       the manifest. Could still be impacted (shared infra, dependency
+ *       chains) but no concrete signal from the PRD.
+ */
+const ImpactedBar = zod_1.z.object({
+    bar_id: zod_1.z.string(),
+    repos: zod_1.z.array(zod_1.z.string().regex(/^[\w.-]+\/[\w.-]+$/)),
+    confidence: zod_1.z.enum(['high', 'low']),
+    reasoning: zod_1.z.string(),
+});
+exports.PrdManifest = zod_1.z.object({
+    run_id: primitives_1.RunId,
+    prd_topic: zod_1.z.string(),
+    /** Mesh repo SHA at PRD publish time. */
+    mesh_sha: primitives_1.GitSha,
+    /**
+     * Code repos `notify-code-repos.yml` opens a landing-issue in. Equals
+     * the union of `impacted_bars[].repos` for HIGH-confidence entries.
+     * LOW-confidence BARs are NOT included here — they only surface as
+     * footer mentions in the HIGH BARs' landing-issues.
+     */
+    target_repos: zod_1.z.array(zod_1.z.string().regex(/^[\w.-]+\/[\w.-]+$/)).min(1),
+    /**
+     * Per-BAR impact classification. Drives which repos in `target_repos`
+     * get an issue and what "Why this repo?" reasoning the issue body
+     * carries. See ImpactedBar above for the HIGH vs LOW semantics.
+     */
+    impacted_bars: zod_1.z.array(ImpactedBar).default([]),
+    endpoints: zod_1.z.array(Endpoint),
+    security_requirements: zod_1.z.array(SecurityRequirement),
+    /** Final grounding state from the refinement loop. */
+    grounding: zod_1.z.object({
+        final_score: zod_1.z.number().min(0).max(1),
+        threshold: zod_1.z.number().min(0).max(1),
+        iterations: zod_1.z.number().int().min(1).max(5),
+        passed: zod_1.z.boolean(),
+    }),
+});

package/dist/schemas/primitives.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared primitive enums + branded types used across every other schema.
+ * Importing from here keeps the surface coherent and lets downstream tests
+ * assert against canonical literal unions instead of free strings.
+ */
+import { z } from 'zod';
+export declare const GuardrailMode: z.ZodEnum<["strict", "default", "lenient"]>;
+export type GuardrailMode = z.infer<typeof GuardrailMode>;
+export declare const GroundingMode: z.ZodEnum<["strict", "default", "lenient"]>;
+export type GroundingMode = z.infer<typeof GroundingMode>;
+export declare const LlmProvider: z.ZodEnum<["anthropic", "openai", "azure-openai", "github-models"]>;
+export type LlmProvider = z.infer<typeof LlmProvider>;
+/**
+ * Providers that route through GitHub Models / Copilot use the workflow's
+ * GITHUB_TOKEN with `permissions: models: read` — no separate API key needs
+ * to live as a repo secret.
+ */
+export declare function providerNeedsApiKey(p: LlmProvider): boolean;
+/**
+ * Research / PRD scope. Portfolio scope was dropped — too abstract for
+ * the agents to produce a targeted PRD. A run must be anchored to a
+ * concrete architectural surface: a platform (multiple BARs sharing a
+ * CALM model) or a single BAR.
+ */
+export declare const ScopeLevel: z.ZodEnum<["platform", "bar"]>;
+export type ScopeLevel = z.infer<typeof ScopeLevel>;
+export declare const ResearchPath: z.ZodEnum<["research", "archaeology"]>;
+export type ResearchPath = z.infer<typeof ResearchPath>;
+export declare const PrdMode: z.ZodEnum<["shallow", "deep"]>;
+export type PrdMode = z.infer<typeof PrdMode>;
+export declare const SearchProvider: z.ZodEnum<["tavily", "arxiv", "uspto", "hackernews"]>;
+export type SearchProvider = z.infer<typeof SearchProvider>;
+/** Run id format: `RES-YYYY-MM-DD-<8 hex>` (research) or `PRD-...` (prd). */
+export declare const RunId: z.ZodString;
+export type RunId = z.infer<typeof RunId>;
+/** SHA-256 hex digest (64 chars). */
+export declare const Sha256: z.ZodString;
+export type Sha256 = z.infer<typeof Sha256>;
+/** Git commit SHA (7-40 hex chars). */
+export declare const GitSha: z.ZodString;
+export type GitSha = z.infer<typeof GitSha>;
+/** ISO-8601 timestamp. We accept anything Date.parse can handle. */
+export declare const IsoTimestamp: z.ZodEffects<z.ZodString, string, string>;
+export type IsoTimestamp = z.infer<typeof IsoTimestamp>;
+/** Confidence rating attached to research conclusions. */
+export declare const Confidence: z.ZodEnum<["HIGH", "MEDIUM", "LOW"]>;
+export type Confidence = z.infer<typeof Confidence>;

package/dist/schemas/primitives.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Confidence = exports.IsoTimestamp = exports.GitSha = exports.Sha256 = exports.RunId = exports.SearchProvider = exports.PrdMode = exports.ResearchPath = exports.ScopeLevel = exports.LlmProvider = exports.GroundingMode = exports.GuardrailMode = void 0;
+exports.providerNeedsApiKey = providerNeedsApiKey;
+/**
+ * Shared primitive enums + branded types used across every other schema.
+ * Importing from here keeps the surface coherent and lets downstream tests
+ * assert against canonical literal unions instead of free strings.
+ */
+const zod_1 = require("zod");
+exports.GuardrailMode = zod_1.z.enum(['strict', 'default', 'lenient']);
+exports.GroundingMode = zod_1.z.enum(['strict', 'default', 'lenient']);
+exports.LlmProvider = zod_1.z.enum(['anthropic', 'openai', 'azure-openai', 'github-models']);
+/**
+ * Providers that route through GitHub Models / Copilot use the workflow's
+ * GITHUB_TOKEN with `permissions: models: read` — no separate API key needs
+ * to live as a repo secret.
+ */
+function providerNeedsApiKey(p) {
+    return p !== 'github-models';
+}
+/**
+ * Research / PRD scope. Portfolio scope was dropped — too abstract for
+ * the agents to produce a targeted PRD. A run must be anchored to a
+ * concrete architectural surface: a platform (multiple BARs sharing a
+ * CALM model) or a single BAR.
+ */
+exports.ScopeLevel = zod_1.z.enum(['platform', 'bar']);
+exports.ResearchPath = zod_1.z.enum(['research', 'archaeology']);
+exports.PrdMode = zod_1.z.enum(['shallow', 'deep']);
+exports.SearchProvider = zod_1.z.enum(['tavily', 'arxiv', 'uspto', 'hackernews']);
+/** Run id format: `RES-YYYY-MM-DD-<8 hex>` (research) or `PRD-...` (prd). */
+exports.RunId = zod_1.z.string().regex(/^(RES|PRD)-\d{4}-\d{2}-\d{2}-[0-9a-f]{8}$/);
+/** SHA-256 hex digest (64 chars). */
+exports.Sha256 = zod_1.z.string().regex(/^[0-9a-f]{64}$/);
+/** Git commit SHA (7-40 hex chars). */
+exports.GitSha = zod_1.z.string().regex(/^[0-9a-f]{7,40}$/);
+/** ISO-8601 timestamp. We accept anything Date.parse can handle. */
+exports.IsoTimestamp = zod_1.z.string().refine(v => !Number.isNaN(Date.parse(v)), { message: 'Must be an ISO-8601 timestamp parseable by Date.parse' });
+/** Confidence rating attached to research conclusions. */
+exports.Confidence = zod_1.z.enum(['HIGH', 'MEDIUM', 'LOW']);

package/dist/schemas/query-plan.d.ts

@@ -0,0 +1,33 @@
+/**
+ * QueryPlan — per-provider query specialisation produced by `plan_queries`.
+ *
+ * Counts and per-provider rules are STRICT (the design doc's "Why this format
+ * choice" section: each search backend reads queries differently and one
+ * generic query plan gets sub-optimal recall everywhere).
+ *
+ * Web queries MUST include the current year for recency anchoring; arxiv
+ * queries are short technical phrases (3-6 words); patent queries use AND
+ * operators; community queries are casual 2-3 word HN-style phrases.
+ */
+import { z } from 'zod';
+export declare const QueryPlan: z.ZodObject<{
+    /** Exactly 5 natural-language web queries; each must contain a 4-digit year. */
+    web: z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">;
+    /** Exactly 3 short technical phrases for arXiv. */
+    arxiv: z.ZodArray<z.ZodString, "many">;
+    /** Exactly 3 USPTO queries — keyword sets joined with AND. */
+    patent: z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">;
+    /** Exactly 3 casual HackerNews-style phrases. */
+    community: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    arxiv: string[];
+    web: string[];
+    patent: string[];
+    community: string[];
+}, {
+    arxiv: string[];
+    web: string[];
+    patent: string[];
+    community: string[];
+}>;
+export type QueryPlan = z.infer<typeof QueryPlan>;

package/dist/schemas/query-plan.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryPlan = void 0;
+/**
+ * QueryPlan — per-provider query specialisation produced by `plan_queries`.
+ *
+ * Counts and per-provider rules are STRICT (the design doc's "Why this format
+ * choice" section: each search backend reads queries differently and one
+ * generic query plan gets sub-optimal recall everywhere).
+ *
+ * Web queries MUST include the current year for recency anchoring; arxiv
+ * queries are short technical phrases (3-6 words); patent queries use AND
+ * operators; community queries are casual 2-3 word HN-style phrases.
+ */
+const zod_1 = require("zod");
+exports.QueryPlan = zod_1.z.object({
+    /** Exactly 5 natural-language web queries; each must contain a 4-digit year. */
+    web: zod_1.z.array(zod_1.z.string().min(3).refine(v => /\b(19|20|21)\d{2}\b/.test(v), { message: 'Web query must contain a 4-digit year for recency anchoring' })).length(5),
+    /** Exactly 3 short technical phrases for arXiv. */
+    arxiv: zod_1.z.array(zod_1.z.string().min(3).max(80)).length(3),
+    /** Exactly 3 USPTO queries — keyword sets joined with AND. */
+    patent: zod_1.z.array(zod_1.z.string().min(3).refine(v => /\bAND\b/.test(v), { message: 'Patent query must join keywords with explicit AND operators' })).length(3),
+    /** Exactly 3 casual HackerNews-style phrases. */
+    community: zod_1.z.array(zod_1.z.string().min(2).max(40)).length(3),
+});