@ramplab/generator 0.1.0

package/dist/pass1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pass1.d.ts","sourceRoot":"","sources":["../src/pass1.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAI7C,OAAO,EAAwB,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAC7E,OAAO,EAA6B,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,EAAe,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAE7E,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,MAAM,MAAM,sBAAsB,GAAG,IAAI,CACvC,iBAAiB,EACjB,MAAM,GAAG,QAAQ,GAAG,aAAa,GAAG,WAAW,CAChD,CAAC;AAEF,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,KAAK,GAAG,QAAQ,GAAG,UAAU,CAAC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,IAAI,EAAE,OAAO,CAAC;IACd,gEAAgE;IAChE,UAAU,EAAE,gBAAgB,CAAC;IAC7B,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC;IAC5C,yEAAyE;IACzE,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,kDAAkD;IAClD,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,yEAAyE;IACzE,MAAM,EAAE,WAAW,CAAC;IACpB;;;OAGG;IACH,SAAS,EAAE,cAAc,CAAC;CAC3B;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,sBAA2B,GAClC,OAAO,CAAC,sBAAsB,CAAC,CA2FjC"}

package/dist/pass1.js

@@ -0,0 +1,81 @@
+import { createAgentSdkRunner } from './agentSdkRunner.js';
+import { assembleLab } from './assembleStage.js';
+import { runAuthorStage } from './authorStage.js';
+import { selectFlagshipModule } from './flagship.js';
+import { assertDirectory, sumCosts } from './generateLab.js';
+import { runMapStage } from './mapStage.js';
+import { resolveStageModels } from './pipeline.js';
+import { resolveAnchors } from './resolveAnchors.js';
+export async function generateLabPass1(repoDir, config = {}) {
+    assertDirectory(repoDir);
+    const clock = config.clock ?? Date.now;
+    const startedAtMs = clock();
+    const models = resolveStageModels(config.models);
+    const runner = config.runner ?? createAgentSdkRunner();
+    const policy = config.resolutionPolicy ?? 'drop';
+    const emit = (event) => config.onProgress?.(event);
+    const stages = [];
+    emit({ type: 'stage-started', pass: 'pass1', stage: 'map' });
+    const mapStartedMs = clock();
+    const mapResult = await runMapStage(runner, repoDir, {
+        model: models.map,
+        ...(config.labId !== undefined ? { labId: config.labId } : {}),
+        ...(config.maxRetries !== undefined ? { maxRetries: config.maxRetries } : {}),
+    });
+    stages.push({
+        stage: 'map',
+        durationMs: clock() - mapStartedMs,
+        ...(mapResult.costUsd !== undefined ? { costUsd: mapResult.costUsd } : {}),
+    });
+    emit({ type: 'stage-completed', pass: 'pass1', stage: 'map' });
+    // The map alone is already renderable: stream it out before authoring.
+    emit({
+        type: 'spec-updated',
+        pass: 'pass1',
+        spec: resolveAnchors(mapResult.spec, repoDir, { policy }).spec,
+    });
+    // Flagship choice is mechanical (trace candidates first, intake override
+    // respected, centrality fallback) — no model call, so it costs nothing and
+    // cannot hallucinate. See flagship.ts.
+    const flagship = selectFlagshipModule(mapResult.spec, config.intake, mapResult.traceCandidates);
+    emit({ type: 'stage-started', pass: 'pass1', stage: 'author' });
+    const authorStartedMs = clock();
+    const authorResult = await runAuthorStage(runner, repoDir, {
+        model: models.author,
+        plan: { modules: [flagship.plannedModule] },
+        concurrency: 1,
+        ...(config.maxRetries !== undefined ? { maxRetries: config.maxRetries } : {}),
+        onModuleAuthored: (authored) => emit({
+            type: 'module-authored',
+            pass: 'pass1',
+            moduleId: authored.module.id,
+            attempts: authored.attempts,
+        }),
+    });
+    stages.push({
+        stage: 'author',
+        durationMs: clock() - authorStartedMs,
+        ...(authorResult.costUsd !== undefined ? { costUsd: authorResult.costUsd } : {}),
+    });
+    emit({ type: 'stage-completed', pass: 'pass1', stage: 'author' });
+    // "Lightly verified": assembly revalidates the merged spec and resolves
+    // every anchor; the adversarial verifier agent is pass 2's job.
+    emit({ type: 'stage-started', pass: 'pass1', stage: 'assemble' });
+    const assembleStartedMs = clock();
+    const { spec, report } = assembleLab(mapResult.spec, authorResult.modules.map((m) => m.module), repoDir, { policy, leadModuleId: flagship.plannedModule.id });
+    stages.push({ stage: 'assemble', durationMs: clock() - assembleStartedMs });
+    emit({ type: 'stage-completed', pass: 'pass1', stage: 'assemble' });
+    emit({ type: 'spec-updated', pass: 'pass1', spec });
+    return {
+        spec,
+        resolution: report,
+        models,
+        costUsd: sumCosts(mapResult.costUsd, authorResult.costUsd),
+        attempts: mapResult.attempts,
+        flagship,
+        authorAttempts: Object.fromEntries(authorResult.modules.map((m) => [m.module.id, m.attempts])),
+        timing: { startedAtMs, durationMs: clock() - startedAtMs, stages },
+        mapResult,
+    };
+}
+//# sourceMappingURL=pass1.js.map

package/dist/pass1.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pass1.js","sourceRoot":"","sources":["../src/pass1.ts"],"names":[],"mappings":"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"}

package/dist/pipeline.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Pipeline plumbing shared by every generation stage (PLAN.md §4).
+ *
+ * Two concerns live here, both deliberately tiny so later slices (plan,
+ * author, verify, assemble) reuse them unchanged:
+ *
+ * - **Per-stage model configuration.** Reasoning-heavy stages default to
+ *   `claude-sonnet-5`; the **map** stage defaults to Haiku (structural
+ *   exploration — an A/B measured it 2× faster / 4.4× cheaper with usable
+ *   quality; see `evals/results/pass1-timing.md`). Callers override per stage
+ *   so validation runs can A/B alternatives (PLAN.md §10).
+ * - **The `ModelRunner` boundary.** Stage logic never talks to the Claude
+ *   Agent SDK directly — it hands a `StageRequest` to an injected runner and
+ *   gets text back. CI tests inject a fake runner; the live path injects
+ *   `createAgentSdkRunner()`. This is the seam that keeps model calls out of
+ *   CI.
+ */
+/** The five pipeline stages, in execution order (PLAN.md §4). */
+export declare const GENERATION_STAGES: readonly ["map", "plan", "author", "verify", "assemble"];
+export type GenerationStageName = (typeof GENERATION_STAGES)[number];
+/** Default for reasoning-heavy stages: plan, author, verify, assemble (PLAN.md §10). */
+export declare const DEFAULT_STAGE_MODEL = "claude-sonnet-5";
+/**
+ * The map stage's default. Mapping is structural exploration + summarization,
+ * not authoring — an A/B on localsend (2026-07-09) measured Haiku 2× faster
+ * and 4.4× cheaper here with usable quality, while authoring quality visibly
+ * dropped on Haiku (see `evals/results/pass1-timing.md`). The map also streams
+ * first, so this is the lever that pulls first-paint toward the 3–5 min target.
+ */
+export declare const MAP_STAGE_MODEL = "claude-haiku-4-5-20251001";
+/** Per-stage model overrides; omitted stages fall back to the stage default. */
+export type StageModelConfig = Partial<Record<GenerationStageName, string>>;
+/**
+ * Expand a (possibly partial) per-stage model map into a complete one: every
+ * stage present, defaulting per {@link STAGE_DEFAULT_MODELS} (Haiku map,
+ * Sonnet elsewhere), with explicit overrides honored verbatim.
+ */
+export declare function resolveStageModels(overrides?: StageModelConfig): Record<GenerationStageName, string>;
+/** One request across the model boundary: everything a runner needs. */
+export interface StageRequest {
+    stage: GenerationStageName;
+    /** Model id for this stage, already resolved through the config map. */
+    model: string;
+    /** The repository being analyzed — a plain local directory. */
+    repoDir: string;
+    /** Full instructions for the agent, including the output contract. */
+    prompt: string;
+    /** 1-based attempt counter; > 1 means this is a retry after invalid output. */
+    attempt: number;
+}
+/** What comes back across the boundary. */
+export interface StageResponse {
+    /** The agent's final text output (expected to contain JSON). */
+    output: string;
+    /** Cost of this call in USD, when the runner can report it. */
+    costUsd?: number;
+}
+/**
+ * The injectable agent-invocation boundary. Implementations:
+ * - `createAgentSdkRunner()` — the real Claude Agent SDK (live runs),
+ * - fakes/recordings in tests (no API calls in CI).
+ */
+export interface ModelRunner {
+    runStage(request: StageRequest): Promise<StageResponse>;
+}
+/**
+ * Run `fn` over `items` with at most `limit` promises in flight: a fixed
+ * pool of workers pulls the next index until the list is exhausted, and
+ * `Promise.all` joins the pool. Results keep input order. Shared by every
+ * fan-out stage (author, verify).
+ */
+export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]>;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,iEAAiE;AACjE,eAAO,MAAM,iBAAiB,0DAA2D,CAAC;AAE1F,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,8BAA8B,CAAC;AAW3D,gFAAgF;AAChF,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC,CAAC;AAE5E;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,GAAE,gBAAqB,GAC/B,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAMrC;AAED,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,mBAAmB,CAAC;IAC3B,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,2CAA2C;AAC3C,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACzD;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAC3C,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,CAAC,EAAE,CAAC,CAed"}

package/dist/pipeline.js

@@ -0,0 +1,70 @@
+/**
+ * Pipeline plumbing shared by every generation stage (PLAN.md §4).
+ *
+ * Two concerns live here, both deliberately tiny so later slices (plan,
+ * author, verify, assemble) reuse them unchanged:
+ *
+ * - **Per-stage model configuration.** Reasoning-heavy stages default to
+ *   `claude-sonnet-5`; the **map** stage defaults to Haiku (structural
+ *   exploration — an A/B measured it 2× faster / 4.4× cheaper with usable
+ *   quality; see `evals/results/pass1-timing.md`). Callers override per stage
+ *   so validation runs can A/B alternatives (PLAN.md §10).
+ * - **The `ModelRunner` boundary.** Stage logic never talks to the Claude
+ *   Agent SDK directly — it hands a `StageRequest` to an injected runner and
+ *   gets text back. CI tests inject a fake runner; the live path injects
+ *   `createAgentSdkRunner()`. This is the seam that keeps model calls out of
+ *   CI.
+ */
+/** The five pipeline stages, in execution order (PLAN.md §4). */
+export const GENERATION_STAGES = ['map', 'plan', 'author', 'verify', 'assemble'];
+/** Default for reasoning-heavy stages: plan, author, verify, assemble (PLAN.md §10). */
+export const DEFAULT_STAGE_MODEL = 'claude-sonnet-5';
+/**
+ * The map stage's default. Mapping is structural exploration + summarization,
+ * not authoring — an A/B on localsend (2026-07-09) measured Haiku 2× faster
+ * and 4.4× cheaper here with usable quality, while authoring quality visibly
+ * dropped on Haiku (see `evals/results/pass1-timing.md`). The map also streams
+ * first, so this is the lever that pulls first-paint toward the 3–5 min target.
+ */
+export const MAP_STAGE_MODEL = 'claude-haiku-4-5-20251001';
+/** Per-stage default models — Haiku for map, Sonnet everywhere else. */
+const STAGE_DEFAULT_MODELS = {
+    map: MAP_STAGE_MODEL,
+    plan: DEFAULT_STAGE_MODEL,
+    author: DEFAULT_STAGE_MODEL,
+    verify: DEFAULT_STAGE_MODEL,
+    assemble: DEFAULT_STAGE_MODEL,
+};
+/**
+ * Expand a (possibly partial) per-stage model map into a complete one: every
+ * stage present, defaulting per {@link STAGE_DEFAULT_MODELS} (Haiku map,
+ * Sonnet elsewhere), with explicit overrides honored verbatim.
+ */
+export function resolveStageModels(overrides = {}) {
+    const resolved = {};
+    for (const stage of GENERATION_STAGES) {
+        resolved[stage] = overrides[stage] ?? STAGE_DEFAULT_MODELS[stage];
+    }
+    return resolved;
+}
+/**
+ * Run `fn` over `items` with at most `limit` promises in flight: a fixed
+ * pool of workers pulls the next index until the list is exhausted, and
+ * `Promise.all` joins the pool. Results keep input order. Shared by every
+ * fan-out stage (author, verify).
+ */
+export async function mapWithConcurrency(items, limit, fn) {
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (true) {
+            const index = nextIndex++;
+            if (index >= items.length)
+                return;
+            results[index] = await fn(items[index]);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,iEAAiE;AACjE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,CAAU,CAAC;AAI1F,wFAAwF;AACxF,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,2BAA2B,CAAC;AAE3D,wEAAwE;AACxE,MAAM,oBAAoB,GAAwC;IAChE,GAAG,EAAE,eAAe;IACpB,IAAI,EAAE,mBAAmB;IACzB,MAAM,EAAE,mBAAmB;IAC3B,MAAM,EAAE,mBAAmB;IAC3B,QAAQ,EAAE,mBAAmB;CAC9B,CAAC;AAKF;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,YAA8B,EAAE;IAEhC,MAAM,QAAQ,GAAG,EAAyC,CAAC;IAC3D,KAAK,MAAM,KAAK,IAAI,iBAAiB,EAAE,CAAC;QACtC,QAAQ,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,IAAI,oBAAoB,CAAC,KAAK,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAgCD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAmB,EACnB,KAAa,EACb,EAA2B;IAE3B,MAAM,OAAO,GAAG,IAAI,KAAK,CAAI,KAAK,CAAC,MAAM,CAAC,CAAC;IAC3C,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CACxB,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,EACzC,KAAK,IAAmB,EAAE;QACxB,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,KAAK,GAAG,SAAS,EAAE,CAAC;YAC1B,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM;gBAAE,OAAO;YAClC,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,CAAM,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC,CACF,CAAC;IACF,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3B,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/planStage.d.ts

@@ -0,0 +1,141 @@
+import { z } from 'zod';
+import { type LabSpec } from '@ramplab/spec';
+import { type LeadIntake } from './intake.js';
+import type { ModelRunner } from './pipeline.js';
+/**
+ * The curriculum-plan stage (PLAN.md §4, pass 2): given the map-stage output
+ * (the system map is the model's index of the repo's subsystems), an agent
+ * plans the lab as a **journey, not a survey** (issue #18). The curriculum
+ * contract, enforced by the parse gate where it can be mechanical:
+ *
+ * - **Module 1 is an end-to-end trace** of one front-door user action. When
+ *   the flagship trace was already selected (see `flagship.ts`), the plan's
+ *   first module must carry its id, and its title/focus are canonicalized
+ *   from the selection after parsing — pass 2's re-authoring of the pass-1
+ *   preview stays canonical instead of re-negotiated per run.
+ * - **Dependency order, concrete to abstract**: each module relies only on
+ *   what earlier modules taught.
+ * - **The learner-state ledger**: every planned module declares `assumes`
+ *   (what the learner knows on arrival) and `teaches` (what it adds). The
+ *   author stage hands each parallel author its slice, buying narrative
+ *   continuity without serializing the fan-out.
+ * - **The final module is always "your first contribution"** (id
+ *   `first-contribution`): starter areas, test conventions, CI gates, PR
+ *   norms — thin if the repo's material is thin, never fabricated.
+ *
+ * The plan is **pipeline-internal state** — it never appears in a lab spec,
+ * so its schema lives here, not in `@ramplab/spec`. Downstream, the author
+ * stage fans out one agent per planned module and the assemble stage merges
+ * the authored modules in plan order.
+ *
+ * Budget semantics: the cap is a **config property, not a repo property**.
+ * The prompt asks for at most `budget.maxModules` modules; if the model
+ * over-delivers anyway, the plan is truncated to the cap after validation.
+ * Truncation drops modules from the end of the middle: the opening trace
+ * and the landing `first-contribution` module always survive, because they
+ * are curriculum invariants, not centrality picks.
+ */
+/** Default cap on planned modules when the config does not set one. */
+export declare const DEFAULT_MAX_MODULES = 6;
+/** The centrality budget: caps scope by config, never by repo size. */
+export interface CurriculumBudget {
+    /**
+     * Hard cap on the number of authored modules (the map stage's overview
+     * module is not counted against it).
+     * @default 6
+     */
+    maxModules?: number;
+    /**
+     * Free-form scope steering from the lead's intake ("focus on billing",
+     * "skip the legacy importer"). Injected into the plan prompt verbatim.
+     */
+    scopeHints?: string[];
+}
+/**
+ * The mandated landing module (issue #18): every curriculum ends with "your
+ * first contribution" under this id, so its presence is a mechanical check.
+ */
+export declare const LANDING_MODULE_ID = "first-contribution";
+/**
+ * Internal Zod schema for one planned module. Deliberately NOT part of
+ * `@ramplab/spec`: the plan (including the learner-state ledger) is an
+ * intermediate artifact between stages and never reaches the lab spec.
+ */
+export declare const plannedModuleSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    focus: z.ZodString;
+    keyFiles: z.ZodArray<z.ZodString>;
+    assumes: z.ZodArray<z.ZodString>;
+    teaches: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare const curriculumPlanSchema: z.ZodObject<{
+    modules: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        focus: z.ZodString;
+        keyFiles: z.ZodArray<z.ZodString>;
+        assumes: z.ZodArray<z.ZodString>;
+        teaches: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PlannedModule = z.infer<typeof plannedModuleSchema>;
+export type CurriculumPlan = z.infer<typeof curriculumPlanSchema>;
+export interface PlanStageOptions {
+    model: string;
+    /** The map-stage output — its system map seeds the centrality ranking. */
+    mapSpec: LabSpec;
+    budget?: CurriculumBudget;
+    /**
+     * The lead's intake answers (PLAN.md §4 curation loop). Rendered into the
+     * plan prompt so they steer module selection and ordering.
+     */
+    intake?: LeadIntake;
+    /**
+     * The flagship trace module selected in `flagship.ts` (pass 1's preview
+     * module). When present, the plan's first module must carry this id (parse
+     * gate) and its title/focus are canonicalized from it after parsing, so
+     * pass 2 re-authors the same trace the learner previewed in pass 1. Absent
+     * when the map yielded no usable trace candidates — the prompt then asks
+     * the planner to pick its own front-door action for module 1.
+     */
+    traceModule?: PlannedModule;
+    /**
+     * How many times to re-prompt after schema-invalid output.
+     * @default 1
+     */
+    maxRetries?: number;
+}
+export interface PlanStageResult {
+    /** Validated plan, ordered most-central-first, capped at the budget. */
+    plan: CurriculumPlan;
+    /** Total attempts made (1 = no retry needed). */
+    attempts: number;
+    /** Summed cost across attempts, if the runner reports cost. */
+    costUsd: number | undefined;
+}
+/** Raised when the model's output stays schema-invalid after all retries. */
+export declare class PlanStageError extends Error {
+    readonly attempts: number;
+    readonly lastFailure: string;
+    constructor(attempts: number, lastFailure: string);
+}
+export declare function runPlanStage(runner: ModelRunner, repoDir: string, options: PlanStageOptions): Promise<PlanStageResult>;
+type ParseOutcome = {
+    ok: true;
+    plan: CurriculumPlan;
+} | {
+    ok: false;
+    failure: string;
+};
+/**
+ * The parse gate: schema validation (ledger fields, landing module, ids)
+ * plus the flagship-trace contract when a trace module was pre-selected —
+ * the first module must carry the trace's id, and its title/focus are then
+ * overwritten with the canonical selection so the trace's identity is owned
+ * by flagship selection, not re-negotiated by the planner. The planner still
+ * owns the trace module's keyFiles (it explored the repo) and its ledger.
+ */
+export declare function parsePlan(output: string, traceModule?: PlannedModule): ParseOutcome;
+export {};
+//# sourceMappingURL=planStage.d.ts.map

package/dist/planStage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planStage.d.ts","sourceRoot":"","sources":["../src/planStage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAY,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAuB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAEnE,OAAO,KAAK,EAAE,WAAW,EAAiB,MAAM,eAAe,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAKD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,uBAAuB,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;iBAiB9B,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;;;;;;iBAiC7B,CAAC;AAEL,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,IAAI,EAAE,cAAc,CAAC;IACrB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED,6EAA6E;AAC7E,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CASlD;AAED,wBAAsB,YAAY,CAChC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CAsC1B;AAeD,KAAK,YAAY,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAExF;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,aAAa,GAAG,YAAY,CAuBnF"}