@ramplab/generator 0.1.0

package/dist/live.js

@@ -0,0 +1,213 @@
+/**
+ * Live-run entry for the generator — the documented real-model path.
+ *
+ * Usage (from the repo root):
+ *
+ *   ANTHROPIC_API_KEY=... pnpm --filter @ramplab/generator run live -- <repoDir> [outFile] [--pass1 | --full]
+ *
+ * The key is optional. With `ANTHROPIC_API_KEY` unset the Agent SDK falls
+ * through to the Claude Code login, which spends session allowance instead of
+ * API credit — the way to populate the library without a metered bill. Either
+ * way the run prints which credential it took before it starts. Note that a
+ * shell which sources this repo's `.env` has the key set: unset it deliberately.
+ *
+ * Runs against the given plain local directory with the real Claude Agent
+ * SDK, prints progress and a resolution summary to stderr, and writes the
+ * resulting lab-spec JSON to `outFile` (default `lab-spec.json` in the
+ * current directory) — ready to load into the playground.
+ *
+ * Modes (the two-pass runtime, PLAN.md §4):
+ * - default: the map-stage tracer (repo map + intro module).
+ * - `--pass1`: pass 1 — map + ONE flagship module: the most representative
+ *   front-door trace action the map proposed (intake can override; subsystem
+ *   centrality is the fallback), lightly verified (anchor resolution only).
+ *   Streams progress events, prints which trace action was selected and why
+ *   (basis), and prints the measured pass-1 timing.
+ * - `--full`: pass 2 — the full pipeline (map → curriculum plan → parallel
+ *   authoring → assemble → adversarial verification), printing progress
+ *   events as they arrive.
+ *
+ * Optional env:
+ * - RAMPLAB_MAP_MODEL / RAMPLAB_PLAN_MODEL / RAMPLAB_AUTHOR_MODEL /
+ *   RAMPLAB_VERIFY_MODEL override the per-stage models.
+ * - RAMPLAB_MAX_MODULES caps the curriculum budget (full mode; default 6).
+ */
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { createAgentSdkRunner, describeAuth } from './agentSdkRunner.js';
+import { generateLab } from './generateLab.js';
+import { generateLabPass1 } from './pass1.js';
+/**
+ * One line naming the selected flagship and its basis — trace action first
+ * (the issue-#18 design), node fallback spelled out — so iteration reviews
+ * know exactly what pass 1 chose and why.
+ */
+function describeFlagship(flagship) {
+    const why = {
+        trace: 'most representative front-door action proposed by the map',
+        'trace-intake': `intake hint "${flagship.matchedHint ?? ''}" matched this action`,
+        intake: `no usable trace candidates — node fallback; ` +
+            `intake hint "${flagship.matchedHint ?? ''}" matched this node`,
+        centrality: `no usable trace candidates — node fallback by subsystem centrality ` +
+            `(degree ${flagship.degree ?? 0})`,
+    }[flagship.basis];
+    return flagship.traceAction !== undefined
+        ? `Flagship trace: "${flagship.traceAction}" → module "${flagship.plannedModule.id}" ` +
+            `(basis: ${flagship.basis} — ${why}).`
+        : `Flagship: module "${flagship.plannedModule.id}" (node ${flagship.nodeId ?? '?'}, ` +
+            `basis: ${flagship.basis} — ${why}).`;
+}
+function printProgress(event) {
+    switch (event.type) {
+        case 'stage-started':
+            console.error(`[${event.pass}] ${event.stage}: started`);
+            break;
+        case 'stage-completed':
+            console.error(`[${event.pass}] ${event.stage}: completed`);
+            break;
+        case 'module-authored':
+            console.error(`[${event.pass}] authored module "${event.moduleId}" ` +
+                `(${event.attempts} attempt${event.attempts === 1 ? '' : 's'})`);
+            break;
+        case 'spec-updated':
+            console.error(`[${event.pass}] spec updated — ${event.spec.base.modules.length} module(s) renderable`);
+            break;
+    }
+}
+/** Read `--flag N` out of argv as a positive integer. */
+function numericFlag(args, flag) {
+    const at = args.indexOf(flag);
+    if (at === -1)
+        return { ok: true, value: undefined };
+    const raw = args[at + 1];
+    const value = Number(raw);
+    if (raw === undefined || !Number.isInteger(value) || value < 1) {
+        return { ok: false, error: `${flag} needs a positive integer, got "${raw ?? ''}".` };
+    }
+    return { ok: true, value };
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const full = args.includes('--full');
+    const pass1 = args.includes('--pass1');
+    // The same two guards the eval harness raises by default (its tier-1
+    // findings): the SDK's 50-turn default gets exhausted by one authoring
+    // session on a real repo, and author-stage schema drift occasionally needs
+    // a second retry. This entry could not reach either until now, so a
+    // single-repo pressing was the one path still running on the low cap.
+    const turns = numericFlag(args, '--max-turns');
+    const retries = numericFlag(args, '--max-retries');
+    for (const parsed of [turns, retries]) {
+        if (!parsed.ok) {
+            console.error(parsed.error);
+            process.exitCode = 2;
+            return;
+        }
+    }
+    const maxTurns = turns.ok ? turns.value : undefined;
+    const maxRetries = retries.ok ? retries.value : undefined;
+    const positional = args.filter((arg, index) => !arg.startsWith('--') &&
+        // Drop the value that followed a numeric flag, not every matching token.
+        !(index > 0 && (args[index - 1] === '--max-turns' || args[index - 1] === '--max-retries')));
+    const [repoDirArg, outArg] = positional;
+    if (repoDirArg === undefined || (full && pass1)) {
+        console.error('Usage: pnpm --filter @ramplab/generator run live -- <repoDir> [outFile] ' +
+            '[--pass1 | --full] [--max-turns N] [--max-retries N]');
+        process.exitCode = 2;
+        return;
+    }
+    // Either credential runs the pipeline; the run just has to say which.
+    console.error(`Auth: ${describeAuth().label}`);
+    const repoDir = resolve(repoDirArg);
+    const outFile = resolve(outArg ?? 'lab-spec.json');
+    const models = {};
+    if (process.env['RAMPLAB_MAP_MODEL'] !== undefined) {
+        models.map = process.env['RAMPLAB_MAP_MODEL'];
+    }
+    if (process.env['RAMPLAB_PLAN_MODEL'] !== undefined) {
+        models.plan = process.env['RAMPLAB_PLAN_MODEL'];
+    }
+    if (process.env['RAMPLAB_AUTHOR_MODEL'] !== undefined) {
+        models.author = process.env['RAMPLAB_AUTHOR_MODEL'];
+    }
+    if (process.env['RAMPLAB_VERIFY_MODEL'] !== undefined) {
+        models.verify = process.env['RAMPLAB_VERIFY_MODEL'];
+    }
+    const maxModulesEnv = process.env['RAMPLAB_MAX_MODULES'];
+    const maxModules = maxModulesEnv !== undefined ? Number(maxModulesEnv) : undefined;
+    if (maxModules !== undefined && (!Number.isInteger(maxModules) || maxModules < 1)) {
+        console.error(`RAMPLAB_MAX_MODULES must be a positive integer, got "${maxModulesEnv}".`);
+        process.exitCode = 2;
+        return;
+    }
+    // A raised cap is still a hard guard, just a roomier one.
+    const runner = maxTurns !== undefined ? createAgentSdkRunner({ maxTurns }) : undefined;
+    if (maxTurns !== undefined || maxRetries !== undefined) {
+        console.error(`Guards: max-turns=${maxTurns ?? 'default'}, max-retries=${maxRetries ?? 'default'}`);
+    }
+    if (pass1) {
+        console.error(`Generating pass-1 preview lab for ${repoDir} ...`);
+        const result = await generateLabPass1(repoDir, {
+            ...(Object.keys(models).length > 0 ? { models } : {}),
+            ...(runner !== undefined ? { runner } : {}),
+            ...(maxRetries !== undefined ? { maxRetries } : {}),
+            onProgress: printProgress,
+        });
+        writeFileSync(outFile, `${JSON.stringify(result.spec, null, 2)}\n`, 'utf8');
+        const seconds = (result.timing.durationMs / 1000).toFixed(1);
+        console.error(`Pass 1 done in ${seconds}s (map attempts: ${result.attempts}).`);
+        console.error(`Models: map=${result.models.map}, author=${result.models.author}`);
+        console.error(describeFlagship(result.flagship));
+        const { summary } = result.resolution;
+        console.error(`Anchors: ${summary.resolvedAnchors}/${summary.totalAnchors} resolved; ` +
+            `units: ${summary.resolvedUnits}/${summary.totalUnits} kept, ` +
+            `${summary.unresolvedUnits} dropped.`);
+        console.error(result.costUsd !== undefined
+            ? `Cost: $${result.costUsd.toFixed(4)}`
+            : 'Cost: not reported by the runner.');
+        console.error(`Spec written to ${outFile} — load it in apps/playground to view.`);
+        return;
+    }
+    const config = {
+        full,
+        ...(Object.keys(models).length > 0 ? { models } : {}),
+        ...(maxModules !== undefined ? { budget: { maxModules } } : {}),
+        ...(runner !== undefined ? { runner } : {}),
+        ...(maxRetries !== undefined ? { maxRetries } : {}),
+        ...(full ? { onProgress: printProgress } : {}),
+    };
+    console.error(`Generating ${full ? 'full-pipeline' : 'map-stage'} lab for ${repoDir} ...`);
+    const started = Date.now();
+    const result = await generateLab(repoDir, config);
+    const seconds = ((Date.now() - started) / 1000).toFixed(1);
+    writeFileSync(outFile, `${JSON.stringify(result.spec, null, 2)}\n`, 'utf8');
+    const { summary } = result.resolution;
+    console.error(`Done in ${seconds}s (map attempts: ${result.attempts}).`);
+    console.error(full
+        ? `Models: map=${result.models.map}, plan=${result.models.plan}, ` +
+            `author=${result.models.author}, verify=${result.models.verify}`
+        : `Model (map stage): ${result.models.map}`);
+    if (result.plan !== undefined) {
+        console.error(`Plan: ${result.plan.modules.length} module(s) — ` +
+            result.plan.modules.map((m) => m.id).join(', '));
+    }
+    console.error(`Anchors: ${summary.resolvedAnchors}/${summary.totalAnchors} resolved; ` +
+        `units: ${summary.resolvedUnits}/${summary.totalUnits} kept, ` +
+        `${summary.unresolvedUnits} dropped.`);
+    if (result.verification !== undefined) {
+        const v = result.verification;
+        console.error(`Verification: ${v.summary.verified}/${v.summary.totalClaims} claims verified ` +
+            `(pass rate ${(v.summary.passRate * 100).toFixed(1)}%); dropped ` +
+            `${v.drops.widgets.length} widget(s), ${v.drops.questions.length} quiz question(s), ` +
+            `${v.drops.modules.length} emptied module(s).`);
+    }
+    console.error(result.costUsd !== undefined
+        ? `Cost: $${result.costUsd.toFixed(4)}`
+        : 'Cost: not reported by the runner.');
+    console.error(`Spec written to ${outFile} — load it in apps/playground to view.`);
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=live.js.map

package/dist/live.js.map

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

package/dist/mapStage.d.ts

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+import { type LabSpec } from '@ramplab/spec';
+import type { ModelRunner } from './pipeline.js';
+/**
+ * The map stage (PLAN.md §4, pass 1): an agent explores the repository and
+ * produces (a) a system-map widget of the architecture, (b) one module of
+ * anchored callouts introducing the repo, and (c) 2–3 candidate "front door"
+ * trace actions — real user-triggered entry-point scenarios ("an HTTP
+ * request is served", "a file is sent") with the files along each action's
+ * path. The candidates seed flagship selection (issue #18): the lab's
+ * opening module traces one of them end to end.
+ *
+ * The model returns a small JSON payload; this module owns the output
+ * contract (prompt), the payload → LabSpec assembly, and the bounded retry
+ * on schema-invalid output. Validation is a single path: the assembled spec
+ * must pass `parseLabSpec` — there is no separate payload schema to drift
+ * out of sync with `@ramplab/spec`. Trace candidates are deliberately
+ * advisory: a malformed candidate is dropped (flagship selection has a
+ * mechanical fallback), never a reason to reject the whole map.
+ */
+export interface MapStageOptions {
+    model: string;
+    /** Lab id; defaults to a slug of the repo directory name. */
+    labId?: string;
+    /**
+     * How many times to re-prompt after schema-invalid output.
+     * @default 1
+     */
+    maxRetries?: number;
+}
+/**
+ * One candidate "front door" user action proposed by the map agent — an
+ * entry-point scenario a real user triggers, with the files along its path.
+ * Pipeline-internal (never part of the lab spec): it exists to seed the
+ * flagship trace selection in `flagship.ts`.
+ */
+export declare const traceCandidateSchema: z.ZodObject<{
+    id: z.ZodString;
+    action: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    keyFiles: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type TraceCandidate = z.infer<typeof traceCandidateSchema>;
+export interface MapStageResult {
+    /** A valid lab spec — not yet anchor-resolved. */
+    spec: LabSpec;
+    /** Total attempts made (1 = no retry needed). */
+    attempts: number;
+    /** Summed cost across attempts, if the runner reports cost. */
+    costUsd: number | undefined;
+    /**
+     * Candidate front-door trace actions, most representative first. Always
+     * present (possibly empty) on fresh runs; optional so map results captured
+     * before issue #18 (e.g. a reused `config.mapResult`) remain valid — every
+     * consumer must treat a missing/empty list as "no candidates" and fall
+     * back mechanically.
+     */
+    traceCandidates?: TraceCandidate[];
+}
+/** Raised when the model's output stays schema-invalid after all retries. */
+export declare class MapStageError extends Error {
+    readonly attempts: number;
+    /** The validation failure of the final attempt. */
+    readonly lastFailure: string;
+    constructor(attempts: number, lastFailure: string);
+}
+export declare function runMapStage(runner: ModelRunner, repoDir: string, options: MapStageOptions): Promise<MapStageResult>;
+/**
+ * Lenient trace-candidate parsing: keep every entry that satisfies
+ * {@link traceCandidateSchema} (first occurrence wins on a duplicate id),
+ * silently drop the rest. Advisory data gets advisory validation — flagship
+ * selection falls back to centrality when nothing usable survives, so a
+ * sloppy candidate must never fail (or force a retry of) the map stage.
+ */
+export declare function parseTraceCandidates(payload: Record<string, unknown>): TraceCandidate[];
+/**
+ * Pull a JSON value out of agent output that may wrap it in prose or a
+ * markdown fence. Tries, in order: the raw text, the last ```json fence,
+ * and the outermost `{...}` span.
+ */
+export declare function extractJson(output: string): unknown;
+/** Turn a directory name into a schema-valid kebab-case lab id. */
+export declare function slugify(name: string): string;
+//# sourceMappingURL=mapStage.d.ts.map

package/dist/mapStage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapStage.d.ts","sourceRoot":"","sources":["../src/mapStage.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAA8B,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAiB,MAAM,eAAe,CAAC;AAEhE;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;iBAW/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,IAAI,EAAE,OAAO,CAAC;IACd,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;CACpC;AAED,6EAA6E;AAC7E,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CASlD;AAED,wBAAsB,WAAW,CAC/B,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,CAqCzB;AAsDD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,EAAE,CAYvF;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAuBnD;AAqFD,mEAAmE;AACnE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM5C"}

package/dist/mapStage.js

@@ -0,0 +1,241 @@
+import { basename } from 'node:path';
+import { z } from 'zod';
+import { idSchema, safeParseLabSpec } from '@ramplab/spec';
+/**
+ * One candidate "front door" user action proposed by the map agent — an
+ * entry-point scenario a real user triggers, with the files along its path.
+ * Pipeline-internal (never part of the lab spec): it exists to seed the
+ * flagship trace selection in `flagship.ts`.
+ */
+export const traceCandidateSchema = z.object({
+    /** Stable kebab-case id — becomes the trace module's id when selected. */
+    id: idSchema,
+    /** The user-visible action, e.g. "an HTTP request is served". */
+    action: z.string().min(1, 'trace candidate action must be non-empty'),
+    /** Optional one-liner: where the action enters and what it passes through. */
+    description: z.string().min(1).optional(),
+    /** Repo-relative files along the action's path, entry point first. */
+    keyFiles: z
+        .array(z.string().min(1))
+        .min(1, 'a trace candidate needs at least one key file'),
+});
+/** Raised when the model's output stays schema-invalid after all retries. */
+export class MapStageError extends Error {
+    attempts;
+    /** The validation failure of the final attempt. */
+    lastFailure;
+    constructor(attempts, lastFailure) {
+        super(`Map stage failed: model output did not produce a valid lab spec after ` +
+            `${attempts} attempt${attempts === 1 ? '' : 's'}.\nLast failure:\n${lastFailure}`);
+        this.name = 'MapStageError';
+        this.attempts = attempts;
+        this.lastFailure = lastFailure;
+    }
+}
+export async function runMapStage(runner, repoDir, options) {
+    const maxRetries = options.maxRetries ?? 1;
+    const maxAttempts = 1 + Math.max(0, maxRetries);
+    const labId = options.labId ?? slugify(basename(repoDir));
+    const basePrompt = buildMapPrompt();
+    let costUsd;
+    let lastFailure = 'no attempt was made';
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const prompt = attempt === 1 ? basePrompt : `${basePrompt}\n\n${retryPreamble(lastFailure)}`;
+        const response = await runner.runStage({
+            stage: 'map',
+            model: options.model,
+            repoDir,
+            prompt,
+            attempt,
+        });
+        if (response.costUsd !== undefined) {
+            costUsd = (costUsd ?? 0) + response.costUsd;
+        }
+        const outcome = assembleSpec(response.output, labId);
+        if (outcome.ok) {
+            return {
+                spec: outcome.spec,
+                attempts: attempt,
+                costUsd,
+                traceCandidates: outcome.traceCandidates,
+            };
+        }
+        lastFailure = outcome.failure;
+    }
+    throw new MapStageError(maxAttempts, lastFailure);
+}
+/**
+ * Parse the model's text output as the map-stage payload and assemble the
+ * lab spec around it. Any problem — unparseable JSON, wrong envelope, or a
+ * spec-schema violation — becomes a `failure` string that feeds the retry
+ * prompt verbatim.
+ */
+function assembleSpec(output, labId) {
+    const json = extractJson(output);
+    if (json === undefined) {
+        return { ok: false, failure: 'The output did not contain a parseable JSON object.' };
+    }
+    if (typeof json !== 'object' || json === null || Array.isArray(json)) {
+        return { ok: false, failure: 'The output JSON must be an object.' };
+    }
+    const payload = json;
+    const callouts = Array.isArray(payload['callouts']) ? payload['callouts'] : [];
+    const candidate = {
+        schemaVersion: 1,
+        id: labId,
+        title: payload['title'],
+        base: {
+            modules: [
+                {
+                    id: 'repo-overview',
+                    title: payload['moduleTitle'],
+                    ...(typeof payload['moduleSummary'] === 'string'
+                        ? { summary: payload['moduleSummary'] }
+                        : {}),
+                    widgets: [payload['systemMap'], ...callouts],
+                },
+            ],
+        },
+        overlay: [],
+    };
+    const parsed = safeParseLabSpec(candidate);
+    if (!parsed.success) {
+        return { ok: false, failure: parsed.error };
+    }
+    return { ok: true, spec: parsed.data, traceCandidates: parseTraceCandidates(payload) };
+}
+/**
+ * Lenient trace-candidate parsing: keep every entry that satisfies
+ * {@link traceCandidateSchema} (first occurrence wins on a duplicate id),
+ * silently drop the rest. Advisory data gets advisory validation — flagship
+ * selection falls back to centrality when nothing usable survives, so a
+ * sloppy candidate must never fail (or force a retry of) the map stage.
+ */
+export function parseTraceCandidates(payload) {
+    const raw = payload['traceCandidates'];
+    if (!Array.isArray(raw))
+        return [];
+    const seen = new Set();
+    const candidates = [];
+    for (const entry of raw) {
+        const parsed = traceCandidateSchema.safeParse(entry);
+        if (!parsed.success || seen.has(parsed.data.id))
+            continue;
+        seen.add(parsed.data.id);
+        candidates.push(parsed.data);
+    }
+    return candidates;
+}
+/**
+ * Pull a JSON value out of agent output that may wrap it in prose or a
+ * markdown fence. Tries, in order: the raw text, the last ```json fence,
+ * and the outermost `{...}` span.
+ */
+export function extractJson(output) {
+    const candidates = [output.trim()];
+    const fences = [...output.matchAll(/```(?:json)?\s*\n([\s\S]*?)```/g)];
+    const lastFence = fences[fences.length - 1];
+    if (lastFence?.[1] !== undefined) {
+        candidates.push(lastFence[1].trim());
+    }
+    const first = output.indexOf('{');
+    const last = output.lastIndexOf('}');
+    if (first !== -1 && last > first) {
+        candidates.push(output.slice(first, last + 1));
+    }
+    for (const candidate of candidates) {
+        try {
+            return JSON.parse(candidate);
+        }
+        catch {
+            // try the next extraction strategy
+        }
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Prompting
+// ---------------------------------------------------------------------------
+function retryPreamble(failure) {
+    return (`IMPORTANT — your previous attempt was rejected because it did not ` +
+        `validate against the lab spec schema:\n\n${failure}\n\n` +
+        `Fix these problems and respond again with ONLY the corrected JSON object.`);
+}
+function buildMapPrompt() {
+    return `You are analyzing the repository in your working directory to build the "map" stage of a codebase onboarding lab: an architecture overview a new hire sees first.
+
+Explore the repository using the read-only tools available to you (Read, Glob, Grep). Do not modify anything.
+
+When you are done exploring, respond with ONLY a single JSON object (no prose before or after) with exactly this shape:
+
+{
+  "title": "<the project's REAL name, verbatim, followed by ' Onboarding Lab' — e.g. 'Caddy Onboarding Lab'>",
+  "moduleTitle": "<title for the intro module>",
+  "moduleSummary": "<2-3 sentence orientation for a new engineer>",
+  "systemMap": {
+    "id": "system-map",
+    "type": "system-map",
+    "title": "<diagram title>",
+    "nodes": [
+      {
+        "id": "<kebab-case-id>",
+        "label": "<short label>",
+        "description": "<what this part does>",
+        "anchors": [{ "file": "<repo-relative path>", "symbol": "<identifier in that file>", "lines": { "start": N, "end": M } }]
+      }
+    ],
+    "edges": [
+      { "from": "<node-id>", "to": "<node-id>", "label": "<what flows here>", "anchors": [{ "file": "...", "symbol": "..." }] }
+    ]
+  },
+  "callouts": [
+    {
+      "id": "<kebab-case-id>",
+      "type": "callout",
+      "kind": "why" | "warning" | "connects-to",
+      "title": "<optional short title>",
+      "body": "<one teachable insight about this codebase>",
+      "anchors": [{ "file": "<repo-relative path>", "symbol": "<identifier>", "lines": { "start": N, "end": M } }]
+    }
+  ],
+  "traceCandidates": [
+    {
+      "id": "<kebab-case-id>",
+      "action": "<a 'front door' user action, e.g. 'an HTTP request is served', 'a file is sent'>",
+      "description": "<one sentence: where the action enters and what it passes through>",
+      "keyFiles": ["<repo-relative file on the action's path, entry point first>", "..."]
+    }
+  ]
+}
+
+Trace candidates — the lab's opening module will follow ONE real user action end to end through the code, and you are proposing the candidates:
+- Propose 2 or 3, each a scenario a real user actually triggers from outside (a request served, a file sent, a command run) — not an internal subroutine.
+- Order them most representative first: the first candidate should be the action whose path exercises the most of this codebase's core.
+- "keyFiles" lists 2-6 files you actually read, in the order the action reaches them, entry point first.
+- Candidates are advisory: a malformed candidate is dropped rather than causing rejection, so keep them simple and real.
+
+Hard requirements — the JSON is machine-validated and rejected on any violation:
+- The "title" MUST use the project's REAL name exactly as it appears in the repository — take it verbatim from the "name" field in package.json, the project title in the README, or failing those the repository/directory name — then append " Onboarding Lab". Do NOT invent, guess, abbreviate, translate, rebrand, or otherwise alter the name (for example, never turn "cal.com" into "Cal.diy"). Copy the real name character for character; a wrong project name is a credibility failure on a customer's own repo.
+- Every "id" is kebab-case: lowercase letters, digits, and hyphens, starting with a letter or digit.
+- The system map has at least one node; every edge's "from"/"to" names an existing node id; node ids are unique.
+- Any node with a "description" and any edge with a "label" MUST carry at least one anchor. Bare structural nodes/edges (no description/label) may omit anchors.
+- Every callout MUST carry at least one anchor. Produce 3 to 6 callouts introducing the repo (why it is structured this way, warnings about gotchas, how parts connect).
+- Anchors are mechanically verified against the repository:
+  - "file" is a repo-relative path to a file that exists.
+  - "lines", if given, is a 1-based inclusive range within the file's real line count.
+  - "symbol", if given, appears as a whole token inside the anchored region.
+  Only anchor code you actually read. Content whose anchors fail verification is dropped from the lab.
+- Do not include a "fingerprint" field on any anchor.
+- In every prose string (node "description"s, edge "label"s, callout "body"s and "title"s), wrap each code identifier, symbol, type, function, file path, and package name in backticks the moment it appears — e.g. \`ServeHTTP\`, \`caddyhttp.Server\`, \`internal/caddyhttp/server.go\`. The renderer sets backticked spans as inline code.
+- Strings are non-empty. "kind" is exactly one of "why", "warning", "connects-to".`;
+}
+// ---------------------------------------------------------------------------
+/** Turn a directory name into a schema-valid kebab-case lab id. */
+export function slugify(name) {
+    const slug = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return slug.length > 0 ? slug : 'generated-lab';
+}
+//# sourceMappingURL=mapStage.js.map

package/dist/mapStage.js.map

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

package/dist/pass1.d.ts

@@ -0,0 +1,85 @@
+import type { LabSpec } from '@ramplab/spec';
+import { type FlagshipSelection } from './flagship.js';
+import { type GenerateLabConfig } from './generateLab.js';
+import { type MapStageResult } from './mapStage.js';
+import { type GenerationStageName } from './pipeline.js';
+import { type ResolutionReport } from './resolveAnchors.js';
+/**
+ * `generateLabPass1(repoDir, config)` — pass 1 of the two-pass runtime
+ * (PLAN.md §4): the ~3–5 minute streamed preview, the self-serve "whoa"
+ * moment. Map the repo, pick ONE flagship module — the most representative
+ * front-door trace action the map proposed, authored as "follow this action
+ * end to end through the code"; intake hints can override, and subsystem
+ * centrality remains the fallback when the map yields no usable candidates
+ * (see `flagship.ts`) — author only that module, and assemble a small valid
+ * lab spec: the system-map overview module plus the flagship module.
+ *
+ * **A separate entry point, not another `generateLab` flag — deliberately.**
+ * `generateLab` already multiplexes tracer/full on one result type via
+ * optional fields; a third mode would make every field's presence contingent
+ * on flag combinations. Pass 1 has its own result shape (flagship selection,
+ * timing, a `mapResult` to hand to pass 2) and its own verification
+ * semantics, so it gets its own function with non-optional fields. Both
+ * entry points share `GenerateLabConfig` (minus the pass-2-only knobs) and
+ * all stage plumbing.
+ *
+ * **Lightly verified (the plan's words):** validation + anchor resolution
+ * only — every claim in the preview provably points at real code (unresolved
+ * units are dropped/flagged per policy), but the adversarial verifier agent
+ * does NOT run. That is pass 2's job; spending verifier calls here would
+ * blow the 3–5 minute target for content pass 2 re-authors anyway.
+ *
+ * **Streaming:** progress surfaces through `config.onProgress` (see
+ * `progress.ts`) tagged `pass: 'pass1'` — the callback IS the streaming
+ * seam; no network transport in this slice. `spec-updated` fires first with
+ * the overview-only spec (renderable the moment the map lands) and again
+ * with the final two-module spec.
+ *
+ * **Timing:** measured with `config.clock` (injected in tests; defaults to
+ * `Date.now` on the live path) and reported as `timing` in the result.
+ */
+export type GenerateLabPass1Config = Omit<GenerateLabConfig, 'full' | 'budget' | 'concurrency' | 'mapResult'>;
+/** One stage's share of a pass's wall clock (and spend, when reported). */
+export interface StageTiming {
+    stage: 'map' | 'author' | 'assemble';
+    durationMs: number;
+    costUsd?: number;
+}
+export interface Pass1Timing {
+    /** `clock()` at entry. */
+    startedAtMs: number;
+    /** Total wall-clock duration of pass 1 in milliseconds. */
+    durationMs: number;
+    /**
+     * Per-stage split (#31): committed telemetry used to record only the total,
+     * so a 40-minute run couldn't say whether the map or the author ate it —
+     * the A/B in `evals/results/pass1-timing.md` had to be hand-timed. Now every
+     * run is attributable.
+     */
+    stages: StageTiming[];
+}
+export interface GenerateLabPass1Result {
+    /** The validated, anchor-resolved preview spec: overview + flagship. */
+    spec: LabSpec;
+    /** Anchor-resolution report over the assembled preview spec. */
+    resolution: ResolutionReport;
+    /** The fully-resolved per-stage model map used for this run. */
+    models: Record<GenerationStageName, string>;
+    /** Total model cost in USD (map + flagship authoring), when reported. */
+    costUsd: number | undefined;
+    /** Map-stage attempts (1 = first output was already valid). */
+    attempts: number;
+    /** Which system-map node became the flagship module, and why. */
+    flagship: FlagshipSelection;
+    /** Authoring attempts for the flagship module. */
+    authorAttempts: Record<string, number>;
+    /** Wall-clock timing of the whole pass (PLAN.md's 3–5 minute target). */
+    timing: Pass1Timing;
+    /**
+     * The raw map-stage output. Hand it to pass 2 as `config.mapResult` so the
+     * full pipeline skips its map stage instead of re-mapping the repo.
+     */
+    mapResult: MapStageResult;
+}
+export declare function generateLabPass1(repoDir: string, config?: GenerateLabPass1Config): Promise<GenerateLabPass1Result>;
+//# sourceMappingURL=pass1.d.ts.map