@tangle-network/starter-foundry 0.5.4 → 0.7.0

package/dist/lib/buildout-traces.js

@@ -80,4 +80,70 @@ export const VERTICAL_TO_PARTNER = {
 export function isBuildoutSlug(slug) {
     return slug.startsWith('-private-var-folders-') && slug.includes('factory-local-phase2-');
 }
+/**
+ * Append a BuildoutEvent to the pipeline. Atomic (O_APPEND) — safe to call
+ * from multiple concurrent processes. Creates the containing directory on
+ * first call.
+ *
+ * Example (blueprint-agent):
+ *
+ * ```ts
+ * import { emitBuildoutEvent } from '@tangle-network/starter-foundry'
+ *
+ * await emitBuildoutEvent({
+ *   sessionId: run.id,
+ *   sourceModel: 'blueprint-agent-vb',
+ *   sourcePath: run.manifestPath,
+ *   scenarioId: run.scenarioId,
+ *   partnerGuess: run.verticalId,
+ *   replayRound: run.round,
+ *   initialPrompt: run.prompt,
+ *   addedPackages: run.packagesInstalled.map((n) => ({ pm: 'pnpm', name: n })),
+ *   addedDirs: run.dirsCreated,
+ *   rewrittenFiles: run.filesEdited,
+ *   outcome: {
+ *     source: 'vb-execution',
+ *     allPass: run.verification.allPass,
+ *     blendedScore: run.verification.blendedScore,
+ *     failingLayers: run.verification.failingLayers,
+ *     shotsRun: run.verification.shotsRun,
+ *     shotsToConvergence: run.verification.shotsToConvergence,
+ *     wallMs: run.wallMs,
+ *     toolCallsTotal: run.toolCallsTotal,
+ *   },
+ * })
+ * ```
+ *
+ * Downstream: our capability-gap detector, template-rewrite analyzer, and
+ * meta-harness training data will pick up these events on the next
+ * `run-buildout-pipeline.mjs` invocation.
+ */
+export async function emitBuildoutEvent(input, options = {}) {
+    if (!input.sessionId)
+        throw new Error('emitBuildoutEvent: sessionId is required');
+    if (!input.sourceModel)
+        throw new Error('emitBuildoutEvent: sourceModel is required');
+    const event = {
+        schemaVersion: BUILDOUT_SCHEMA_VERSION,
+        sessionId: input.sessionId,
+        sourcePath: input.sourcePath ?? '',
+        sourceModel: input.sourceModel,
+        scenarioId: input.scenarioId ?? null,
+        partnerGuess: input.partnerGuess ?? null,
+        replayRound: input.replayRound ?? null,
+        firstTs: input.firstTs ?? null,
+        lastTs: input.lastTs ?? null,
+        initialPrompt: input.initialPrompt ?? null,
+        addedPackages: input.addedPackages ?? [],
+        addedDirs: input.addedDirs ?? [],
+        rewrittenFiles: input.rewrittenFiles ?? [],
+        outcome: input.outcome ?? null,
+    };
+    const { mkdir, appendFile } = await import('node:fs/promises');
+    const { dirname } = await import('node:path');
+    const targetPath = options.path ?? DEFAULT_PATHS.buildoutsJsonl;
+    await mkdir(dirname(targetPath), { recursive: true });
+    await appendFile(targetPath, `${JSON.stringify(event)}\n`, 'utf8');
+    return event;
+}
 //# sourceMappingURL=buildout-traces.js.map

package/dist/lib/buildout-traces.js.map

@@ -1 +1 @@
-{"version":3,"file":"buildout-traces.js","sourceRoot":"","sources":["../../src/lib/buildout-traces.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,qDAAqD;AACrD,EAAE;AACF,uEAAuE;AACvE,8DAA8D;AAC9D,EAAE;AACF,6CAA6C;AAC7C,6CAA6C;AAC7C,gEAAgE;AAChE,EAAE;AACF,8DAA8D;AAC9D,6CAA6C;AAC7C,0DAA0D;AAC1D,EAAE;AACF,gCAAgC;AAChC,wCAAwC;AACxC,uEAAuE;AACvE,EAAE;AACF,uDAAuD;AACvD,uEAAuE;AACvE,yEAAyE;AACzE,wEAAwE;AACxE,qBAAqB;AACrB,0DAA0D;AAC1D,0DAA0D;AAC1D,EAAE;AACF,wEAAwE;AACxE,uEAAuE;AACvE,yCAAyC;AAEzC,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAA;AAgFxC,uDAAuD;AACvD,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,cAAc,EAAE,gCAAgC;IAChD,UAAU,EAAE,4CAA4C;IACxD,WAAW,EAAE,wCAAwC;IACrD,WAAW,EAAE,gBAAgB;IAC7B,YAAY,EAAE,gCAAgC;CAC/C,CAAA;AAED,MAAM,UAAU,eAAe;IAC7B,OAAO;QACL,aAAa,EAAE,uBAAuB;QACtC,MAAM,EAAE,EAAE;QACV,QAAQ,EAAE,EAAE;QACZ,OAAO,EAAE,IAAI;KACd,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IAKpC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,sEAAsE,CAAC,CAAA;IAC5F,IAAI,CAAC,CAAC;QAAE,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAA;IAC1E,OAAO;QACL,YAAY,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI;QAC1B,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI;QACxB,WAAW,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC,IAAI,IAAI;KACtD,CAAA;AACH,CAAC;AAED,kFAAkF;AAClF,MAAM,CAAC,MAAM,mBAAmB,GAA2B;IACzD,aAAa,EAAE,qBAAqB;IACpC,iBAAiB,EAAE,qBAAqB;IACxC,WAAW,EAAE,iBAAiB;IAC9B,WAAW,EAAE,gBAAgB;IAC7B,uBAAuB,EAAE,mBAAmB;IAC5C,uBAAuB,EAAE,mBAAmB;CAC7C,CAAA;AAED,gEAAgE;AAChE,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI,CAAC,UAAU,CAAC,uBAAuB,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,uBAAuB,CAAC,CAAA;AAC3F,CAAC"}
+{"version":3,"file":"buildout-traces.js","sourceRoot":"","sources":["../../src/lib/buildout-traces.ts"],"names":[],"mappings":"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"}

package/dist/lib/canary.d.ts

@@ -0,0 +1,38 @@
+export interface CanaryExperiment {
+    name: string;
+    /** 0..1 — fraction of consumers routed to canary */
+    percent: number;
+    /** ISO timestamp after which the experiment is considered inactive */
+    expiresAt?: string | null;
+    /** Optional explicit consumer key allowlist (always routed to canary) */
+    force?: string[];
+    /** Optional explicit consumer key denylist (always routed to main) */
+    exclude?: string[];
+}
+export type CanaryBucket = 'canary' | 'main';
+/**
+ * Core A/B decision primitive. Given a consumer key and an experiment,
+ * returns which bucket the consumer lands in.
+ *
+ * Deterministic: the same `(consumerKey, experiment.name)` tuple always
+ * produces the same bucket. Change the experiment name (not just the
+ * percentage) to re-randomize.
+ */
+export declare function decideCanaryBucket(consumerKey: string, experiment: CanaryExperiment): CanaryBucket;
+/**
+ * Select the registry version (canary vs main) for a given consumer.
+ * Returns an absolute path the composer should use as its registry root.
+ *
+ * Falls back to `registry/` if:
+ *   - experiment routes the consumer to main
+ *   - `registry-canary/` doesn't exist on disk (guard against missing dir)
+ */
+export declare function selectCanaryVersion(consumerKey: string, experiment: CanaryExperiment): Promise<{
+    bucket: CanaryBucket;
+    registryRoot: string;
+}>;
+/**
+ * Default 5%-canary experiment the CI/CD pipeline promotes by name.
+ * Tests import this to exercise the canonical config.
+ */
+export declare const DEFAULT_CANARY_EXPERIMENT: CanaryExperiment;

package/dist/lib/canary.js

@@ -0,0 +1,91 @@
+/**
+ * Canary release routing.
+ *
+ * Routes a configurable fraction of compose requests to a canary registry
+ * (parallel to `registry/` at `registry-canary/`). Decision is deterministic
+ * given a `consumerKey`, so the same consumer always lands in the same bucket
+ * for the lifetime of an experiment — no session-affinity store needed.
+ *
+ * Hash function: FNV-1a 32-bit over `experiment:consumerKey`. The output is
+ * uniformly distributed so `mod 10000 < pct*100` gives the target split to
+ * within ±0.5pp over any reasonable sample of consumer keys.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { resolveRepoRoot } from './fs.js';
+const FNV_OFFSET_32 = 0x811c9dc5;
+const FNV_PRIME_32 = 0x01000193;
+/**
+ * FNV-1a 32-bit. Deterministic and dependency-free. Output is [0, 2^32).
+ * Multiplication is force-truncated with Math.imul to avoid 53-bit float drift
+ * on strings > ~6 chars where the running product silently overflows.
+ */
+function fnv1a32(input) {
+    let hash = FNV_OFFSET_32;
+    for (let i = 0; i < input.length; i++) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, FNV_PRIME_32);
+    }
+    return hash >>> 0;
+}
+/**
+ * Core A/B decision primitive. Given a consumer key and an experiment,
+ * returns which bucket the consumer lands in.
+ *
+ * Deterministic: the same `(consumerKey, experiment.name)` tuple always
+ * produces the same bucket. Change the experiment name (not just the
+ * percentage) to re-randomize.
+ */
+export function decideCanaryBucket(consumerKey, experiment) {
+    if (experiment.exclude?.includes(consumerKey))
+        return 'main';
+    if (experiment.force?.includes(consumerKey))
+        return 'canary';
+    if (experiment.expiresAt) {
+        const expires = Date.parse(experiment.expiresAt);
+        if (!Number.isNaN(expires) && Date.now() > expires)
+            return 'main';
+    }
+    const pct = Math.max(0, Math.min(1, experiment.percent));
+    if (pct <= 0)
+        return 'main';
+    if (pct >= 1)
+        return 'canary';
+    // 4-digit resolution — 0.01% granularity is plenty for 5% rollouts.
+    const bucket = fnv1a32(`${experiment.name}:${consumerKey}`) % 10000;
+    return bucket < Math.floor(pct * 10000) ? 'canary' : 'main';
+}
+/**
+ * Select the registry version (canary vs main) for a given consumer.
+ * Returns an absolute path the composer should use as its registry root.
+ *
+ * Falls back to `registry/` if:
+ *   - experiment routes the consumer to main
+ *   - `registry-canary/` doesn't exist on disk (guard against missing dir)
+ */
+export async function selectCanaryVersion(consumerKey, experiment) {
+    const repoRoot = await resolveRepoRoot();
+    const mainRoot = path.join(repoRoot, 'registry');
+    const canaryRoot = path.join(repoRoot, 'registry-canary');
+    const bucket = decideCanaryBucket(consumerKey, experiment);
+    if (bucket === 'main')
+        return { bucket, registryRoot: mainRoot };
+    try {
+        const stat = await fs.stat(canaryRoot);
+        if (!stat.isDirectory())
+            return { bucket: 'main', registryRoot: mainRoot };
+    }
+    catch {
+        return { bucket: 'main', registryRoot: mainRoot };
+    }
+    return { bucket: 'canary', registryRoot: canaryRoot };
+}
+/**
+ * Default 5%-canary experiment the CI/CD pipeline promotes by name.
+ * Tests import this to exercise the canonical config.
+ */
+export const DEFAULT_CANARY_EXPERIMENT = {
+    name: 'registry-canary-v1',
+    percent: 0.05,
+};
+//# sourceMappingURL=canary.js.map

package/dist/lib/canary.js.map

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

package/dist/lib/capability-inferrer.d.ts

@@ -1,4 +1,4 @@
-export interface PackageCapabilityMap {
+interface PackageCapabilityMap {
     schemaVersion: 1;
     mapping: Record<string, {
         capability: string | null;
@@ -6,7 +6,7 @@ export interface PackageCapabilityMap {
         note?: string;
     }>;
 }
-export interface BuildoutLike {
+interface BuildoutLike {
     sessionId: string;
     initialPrompt: string | null;
     scenarioId: string | null;
@@ -20,13 +20,13 @@ export interface BuildoutLike {
         blendedScore: number;
     } | null;
 }
-export interface InferredCapability {
+interface InferredCapability {
     capability: string;
     confidence: number;
     source: 'package' | 'dir';
     sourceToken: string;
 }
-export interface CapabilityMapSummary {
+interface CapabilityMapSummary {
     distinctPackages: number;
     mappedPackages: number;
     unmappedPackages: number;
@@ -38,3 +38,4 @@ export declare function loadCapabilityMap(path?: string): PackageCapabilityMap;
 export declare function inferCapabilities(buildout: BuildoutLike, map: PackageCapabilityMap): InferredCapability[];
 /** Summary stats over a mapping (for diagnostic CLIs / tests). */
 export declare function summarizeMap(map: PackageCapabilityMap): CapabilityMapSummary;
+export {};

package/dist/lib/compose-prompt.d.ts

@@ -16,7 +16,8 @@
  * are React-flavored) and made them duplicate the canonical agent instruction
  * wording across their codebase. This function is the single supported entrypoint.
  */
-import type { ComposeResult, ComposeSpec } from '../types.js';
+import { type ComposeWorkspaceResult } from './workspace.js';
+import type { ComposeResult, ComposeSpec, WorkspaceSpec } from '../types.js';
 export interface ComposeFromPromptOptions {
     /** Free-text user prompt — drives family routing and industry detection. */
     prompt: string;
@@ -34,17 +35,17 @@ export type ComposeFromPromptResult = {
     contextMessage: string;
 } | {
     kind: 'workspace';
-    reason: string;
+    spec: WorkspaceSpec;
+    result: ComposeWorkspaceResult;
+    contextMessage: string;
 } | {
     kind: 'error';
     error: string;
 };
 /**
- * Compose a scaffold from a free-text prompt. Returns a discriminated union
- * so callers handle workspace and error cases explicitly.
+ * Compose a scaffold from a free-text prompt. Returns a discriminated union.
  *
- * Workspace prompts (multi-project) are not composed automatically — they
- * need a workspace spec, and the caller should fall through to from-scratch
- * agent build or call composeWorkspace directly.
+ * Auto-dispatches to composeStarter or composeWorkspace based on the plan
+ * kind — downstream callers don't need to branch on plan.kind themselves.
  */
 export declare function composeFromPrompt(options: ComposeFromPromptOptions): Promise<ComposeFromPromptResult>;

package/dist/lib/compose-prompt.js

@@ -18,14 +18,13 @@
  */
 import { composeStarter } from './compose.js';
 import { planPrompt } from './prompt-planner.js';
+import { composeWorkspace } from './workspace.js';
 import { getComposedScaffoldContext } from './agent-context.js';
 /**
- * Compose a scaffold from a free-text prompt. Returns a discriminated union
- * so callers handle workspace and error cases explicitly.
+ * Compose a scaffold from a free-text prompt. Returns a discriminated union.
  *
- * Workspace prompts (multi-project) are not composed automatically — they
- * need a workspace spec, and the caller should fall through to from-scratch
- * agent build or call composeWorkspace directly.
+ * Auto-dispatches to composeStarter or composeWorkspace based on the plan
+ * kind — downstream callers don't need to branch on plan.kind themselves.
  */
 export async function composeFromPrompt(options) {
     const { prompt, outDir, partner = null, projectName = 'scaffold' } = options;
@@ -39,12 +38,25 @@ export async function composeFromPrompt(options) {
     catch (err) {
         return { kind: 'error', error: `planPrompt failed: ${err.message}` };
     }
-    if (plan.kind !== 'starter') {
+    if (plan.kind === 'workspace') {
+        const spec = plan.spec;
+        let result;
+        try {
+            result = await composeWorkspace({ spec, outDir });
+        }
+        catch (err) {
+            return { kind: 'error', error: `composeWorkspace failed: ${err.message}` };
+        }
         return {
             kind: 'workspace',
-            reason: 'multi-project workspace prompts are not auto-composed; caller should compose each project explicitly',
+            spec,
+            result,
+            contextMessage: getComposedWorkspaceContext(result),
         };
     }
+    if (plan.kind !== 'starter') {
+        return { kind: 'error', error: `planPrompt returned unexpected kind: ${plan.kind}` };
+    }
     // planPrompt has already attached capabilities, industry, and family-default
     // capabilities (tailwind + shadcn for React families). The spec is ready to compose.
     const spec = {
@@ -65,4 +77,15 @@ export async function composeFromPrompt(options) {
         contextMessage: getComposedScaffoldContext(result),
     };
 }
+function getComposedWorkspaceContext(result) {
+    const lines = [
+        `Composed workspace with ${result.projectCount} project(s) at ${result.outDir}.`,
+        `Launch plan written to ${result.launchPlanPath}.`,
+        `Workspace report written to ${result.workspaceReportPath}.`,
+        '',
+        'Projects:',
+        ...result.projects.map((p) => `  - ${p.id} (${p.components.family}) → ${p.path}`),
+    ];
+    return lines.join('\n');
+}
 //# sourceMappingURL=compose-prompt.js.map

package/dist/lib/compose-prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"compose-prompt.js","sourceRoot":"","sources":["../../src/lib/compose-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAChD,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAA;AA8B/D;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAiC;IAEjC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,EAAE,WAAW,GAAG,UAAU,EAAE,GAAG,OAAO,CAAA;IAE5E,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,oBAAoB,EAAE,CAAA;IACvD,CAAC;IAED,IAAI,IAAI,CAAA;IACR,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,UAAU,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAA;IAC9C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,sBAAuB,GAAa,CAAC,OAAO,EAAE,EAAE,CAAA;IACjF,CAAC;IAED,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO;YACL,IAAI,EAAE,WAAW;YACjB,MAAM,EAAE,sGAAsG;SAC/G,CAAA;IACH,CAAC;IAED,6EAA6E;IAC7E,qFAAqF;IACrF,MAAM,IAAI,GAAgB;QACxB,GAAG,IAAI,CAAC,IAAI;QACZ,WAAW;KACZ,CAAA;IAED,IAAI,MAAqB,CAAA;IACzB,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,cAAc,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAA;IACjD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,0BAA2B,GAAa,CAAC,OAAO,EAAE,EAAE,CAAA;IACrF,CAAC;IAED,OAAO;QACL,IAAI,EAAE,SAAS;QACf,IAAI;QACJ,MAAM;QACN,cAAc,EAAE,0BAA0B,CAAC,MAAM,CAAC;KACnD,CAAA;AACH,CAAC"}
+{"version":3,"file":"compose-prompt.js","sourceRoot":"","sources":["../../src/lib/compose-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAChD,OAAO,EAAE,gBAAgB,EAA+B,MAAM,gBAAgB,CAAA;AAC9E,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAA;AAgC/D;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAiC;IAEjC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,EAAE,WAAW,GAAG,UAAU,EAAE,GAAG,OAAO,CAAA;IAE5E,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,oBAAoB,EAAE,CAAA;IACvD,CAAC;IAED,IAAI,IAAI,CAAA;IACR,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,UAAU,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAA;IAC9C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,sBAAuB,GAAa,CAAC,OAAO,EAAE,EAAE,CAAA;IACjF,CAAC;IAED,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAqB,CAAA;QACvC,IAAI,MAA8B,CAAA;QAClC,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,gBAAgB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAA;QACnD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,4BAA6B,GAAa,CAAC,OAAO,EAAE,EAAE,CAAA;QACvF,CAAC;QACD,OAAO;YACL,IAAI,EAAE,WAAW;YACjB,IAAI;YACJ,MAAM;YACN,cAAc,EAAE,2BAA2B,CAAC,MAAM,CAAC;SACpD,CAAA;IACH,CAAC;IAED,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,wCAAwC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAA;IACtF,CAAC;IAED,6EAA6E;IAC7E,qFAAqF;IACrF,MAAM,IAAI,GAAgB;QACxB,GAAG,IAAI,CAAC,IAAI;QACZ,WAAW;KACZ,CAAA;IAED,IAAI,MAAqB,CAAA;IACzB,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,cAAc,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAA;IACjD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,0BAA2B,GAAa,CAAC,OAAO,EAAE,EAAE,CAAA;IACrF,CAAC;IAED,OAAO;QACL,IAAI,EAAE,SAAS;QACf,IAAI;QACJ,MAAM;QACN,cAAc,EAAE,0BAA0B,CAAC,MAAM,CAAC;KACnD,CAAA;AACH,CAAC;AAED,SAAS,2BAA2B,CAAC,MAA8B;IACjE,MAAM,KAAK,GAAG;QACZ,2BAA2B,MAAM,CAAC,YAAY,kBAAkB,MAAM,CAAC,MAAM,GAAG;QAChF,0BAA0B,MAAM,CAAC,cAAc,GAAG;QAClD,+BAA+B,MAAM,CAAC,mBAAmB,GAAG;QAC5D,EAAE;QACF,WAAW;QACX,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,UAAU,CAAC,MAAM,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;KAClF,CAAA;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC"}

package/dist/lib/compose-seed.d.ts

@@ -0,0 +1,15 @@
+import type { ComposeSpec } from '../types.js';
+/**
+ * Derive the 32-byte replay seed for a compose spec. Pure function of
+ * the spec shape — not of time, random, or env unless the operator
+ * explicitly overrides via STARTER_FOUNDRY_SEED.
+ */
+export declare function deriveComposeSeed(spec: ComposeSpec, envSeed?: string): Buffer;
+/**
+ * Convenience: first 4 bytes as uint32 (for modulo picks).
+ */
+export declare function seedToUint32(seed: Buffer): number;
+/**
+ * Convenience: hex-encoded seed for logging + audit trails.
+ */
+export declare function seedToHex(seed: Buffer): string;

package/dist/lib/compose-seed.js

@@ -0,0 +1,44 @@
+// compose-seed.ts — deterministic seed for bit-identical replay of
+// composeStarter(). Every component of the compose result that's
+// seed-dependent (variant picks, library version picks, brand-tokens
+// hash fallback) reads a single 32-byte seed derived from:
+//
+//   SHA-256(projectName + "|" + family + "|" + sorted(layers).join(",") + "|" + partnerId)
+//
+// Plus an optional STARTER_FOUNDRY_SEED env override for testing or
+// explicit replay. Passing the same spec + same seed to composeStarter
+// must produce byte-identical output — the reproducibility guarantee
+// consumers need for signed audit trails + supply-chain provenance.
+import { createHash } from 'node:crypto';
+/**
+ * Derive the 32-byte replay seed for a compose spec. Pure function of
+ * the spec shape — not of time, random, or env unless the operator
+ * explicitly overrides via STARTER_FOUNDRY_SEED.
+ */
+export function deriveComposeSeed(spec, envSeed) {
+    const override = envSeed ?? process.env['STARTER_FOUNDRY_SEED'];
+    if (override && /^[a-f0-9]{64}$/i.test(override)) {
+        return Buffer.from(override, 'hex');
+    }
+    const layers = [...(spec.layers ?? [])].sort().join(',');
+    const parts = [
+        spec.projectName,
+        spec.family,
+        layers,
+        spec.partner ?? '',
+    ];
+    return createHash('sha256').update(parts.join('|')).digest();
+}
+/**
+ * Convenience: first 4 bytes as uint32 (for modulo picks).
+ */
+export function seedToUint32(seed) {
+    return seed.readUInt32BE(0);
+}
+/**
+ * Convenience: hex-encoded seed for logging + audit trails.
+ */
+export function seedToHex(seed) {
+    return seed.toString('hex');
+}
+//# sourceMappingURL=compose-seed.js.map

package/dist/lib/compose-seed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-seed.js","sourceRoot":"","sources":["../../src/lib/compose-seed.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,iEAAiE;AACjE,qEAAqE;AACrE,2DAA2D;AAC3D,EAAE;AACF,2FAA2F;AAC3F,EAAE;AACF,oEAAoE;AACpE,uEAAuE;AACvE,qEAAqE;AACrE,oEAAoE;AAEpE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAGxC;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAiB,EAAE,OAAgB;IACnE,MAAM,QAAQ,GAAG,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAA;IAC/D,IAAI,QAAQ,IAAI,iBAAiB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACjD,OAAO,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAA;IACrC,CAAC;IACD,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACxD,MAAM,KAAK,GAAG;QACZ,IAAI,CAAC,WAAW;QAChB,IAAI,CAAC,MAAM;QACX,MAAM;QACN,IAAI,CAAC,OAAO,IAAI,EAAE;KACnB,CAAA;IACD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAA;AAC9D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAA;AAC7B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;AAC7B,CAAC"}

package/dist/lib/compose.js

@@ -2,7 +2,9 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { generateBuildPlan } from './build-plan.js';
 import { ensureDir, sanitizePackageName, writeJson } from './fs.js';
+import { renderIndustryFirstTurn } from './industry-flows.js';
 import { buildVariables, resolveComponents, resolveTemplateObject } from './registry.js';
+import { selectTemplateVersion } from './selection.js';
 import { emit, traced } from './telemetry.js';
 const HTML_LIKE_EXTS = new Set(['.tsx', '.jsx', '.html']);
 function escapeHtmlChars(value) {
@@ -84,6 +86,11 @@ export async function composeStarter({ spec, outDir }) {
     });
     const layers = result.components.layers;
     const industry = layers.find((l) => l.startsWith('industry:')) ?? null;
+    // Observe what diverse-serve would pick from the template-library for
+    // this compose. Doesn't change file resolution (registry/ is still the
+    // canonical serve path); purely a telemetry signal so we can see the
+    // env flag wiring in production traces before we flip default behavior.
+    const diverseVersion = selectTemplateVersion(spec.family, spec.projectName);
     emit('compose', {
         family: spec.family,
         layers,
@@ -91,6 +98,8 @@ export async function composeStarter({ spec, outDir }) {
         partner: spec.partner ?? null,
         industry,
         durationMs,
+        templateVersion: diverseVersion,
+        diverseServe: process.env['STARTER_FOUNDRY_DIVERSE_SERVE'] === '1' || process.env['STARTER_FOUNDRY_DIVERSE_SERVE'] === 'true',
     });
     return result;
 }
@@ -115,6 +124,39 @@ async function mergeMediaManifests(outDir) {
     await fs.writeFile(manifestPath, `${JSON.stringify(merged, null, 2)}\n`, 'utf8');
     return merged.slots;
 }
+// Merge each applied layer's declared packageDeps into the composed
+// package.json. Runs after every file is written so the family's package.json
+// is on disk; we read it, merge, write back. No-op if the family has no
+// package.json (Rust/Go/Python scaffolds).
+async function mergeLayerPackageDeps(outDir, layers) {
+    const pkgPath = path.join(outDir, 'package.json');
+    let pkg;
+    try {
+        pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
+    }
+    catch {
+        return;
+    }
+    let touched = false;
+    for (const layer of layers) {
+        const deps = layer.packageDeps;
+        if (!deps)
+            continue;
+        if (deps.dependencies) {
+            const existing = (pkg.dependencies ?? {});
+            pkg.dependencies = { ...existing, ...deps.dependencies };
+            touched = true;
+        }
+        if (deps.devDependencies) {
+            const existing = (pkg.devDependencies ?? {});
+            pkg.devDependencies = { ...existing, ...deps.devDependencies };
+            touched = true;
+        }
+    }
+    if (!touched)
+        return;
+    await fs.writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+}
 async function composeStarterInner(spec, outDir) {
     const components = await resolveComponents(spec);
     const variables = buildVariables({
@@ -141,6 +183,7 @@ async function composeStarterInner(spec, outDir) {
             filesWritten.push(resolvedTarget);
         }
     }
+    await mergeLayerPackageDeps(outDir, components.layers);
     const composeReport = {
         spec,
         components: {
@@ -166,13 +209,40 @@ async function composeStarterInner(spec, outDir) {
     // Generate llms.txt — machine-readable project description for AI agents
     const llmsTxt = buildLlmsTxt(spec, components, composeReport.contextHints);
     await fs.writeFile(path.join(outDir, 'llms.txt'), `${llmsTxt}\n`, 'utf8');
+    // Generate SBOM (CycloneDX) from the composed scaffold's dep manifest.
+    const { writeSbom } = await import('./sbom.js');
+    const sbomPath = await writeSbom(outDir, spec.projectName);
+    // Collect optional prompt-fragment.md files from family + partner.
+    const promptFragment = await collectPromptFragment(components);
     return {
         outDir,
         filesWritten: [...new Set([...filesWritten, 'AGENTS.md', 'CLAUDE.md', 'llms.txt'])].sort(),
         composeReportPath: path.join(outDir, '.starter-foundry', 'compose-report.json'),
         components: composeReport.components,
+        promptFragment,
+        sbomPath,
     };
 }
+async function collectPromptFragment(components) {
+    const fragments = [];
+    const familyFrag = path.join(components.family.baseDir, 'prompt-fragment.md');
+    try {
+        fragments.push(await fs.readFile(familyFrag, 'utf8'));
+    }
+    catch {
+        // Optional file — absence is fine.
+    }
+    if (components.partner) {
+        const partnerFrag = path.join(components.partner.baseDir, 'prompt-fragment.md');
+        try {
+            fragments.push(await fs.readFile(partnerFrag, 'utf8'));
+        }
+        catch {
+            // Optional.
+        }
+    }
+    return fragments.join('\n\n---\n\n').trim();
+}
 function buildLlmsTxt(spec, components, contextHints) {
     const lines = [
         `# ${spec.projectName}`,
@@ -211,7 +281,12 @@ function buildAgentsMd(spec, components, contextHints, mediaSlots = []) {
     // bare `pnpm install`/`pnpm dev` calls (they race the agent's edits, have
     // no error taxonomy, and aren't tracked by the runtime).
     lines.push('## Step 0 — Start the dev server (do this FIRST)', '', 'Before reading anything else in this file, run this command in `bash` to start the dev server. The user is waiting for a preview. This is idempotent — safe to call multiple times (returns the same pid). It auto-installs dependencies on first call, so you do NOT need to run `pnpm install` separately. Subsequent edits hot-reload via HMR; do NOT call this again to restart unless the response says you should.', '', '```bash', 'curl -fsS -X POST "http://localhost:${SIDECAR_PORT:-9000}/process/ensure-dev-server" -H "Content-Type: application/json" -H "Authorization: Bearer ${SIDECAR_AUTH_TOKEN}" -d \'{}\'', '```', '', 'The `SIDECAR_PORT` and `SIDECAR_AUTH_TOKEN` env vars are pre-set in your bash environment — you do NOT need to look them up.', '', 'CRITICAL: Do NOT run `pnpm install`, `pnpm dev`, `npm install`, `npm run dev`, `next dev`, `vite`, `cargo run`, or any other dev/install command via `bash` directly. The command above handles all of that AND tracks the dev process for the runtime so the user\'s preview pane wires up automatically. Running them directly bypasses the runtime tracking and the user will not see a preview.', '', 'The response is JSON: `{ "success": true, "data": { "pid": ..., "family": "node-pnpm", "command": "...", "startedNow": true|false, "installRan": true|false } }`. On error: `{ "success": false, "error": { "code": "...", "message": "..." } }` with codes `WORKSPACE_NOT_FOUND | NO_RUNNABLE_PROJECT | INSTALL_FAILED | DEV_COMMAND_NOT_FOUND | DEV_PROCESS_EXITED | PORT_BIND_FAILED`. React to each: `INSTALL_FAILED` → read the `log` field, fix `package.json`, call again; `DEV_COMMAND_NOT_FOUND` → add a `dev` script to `package.json`, call again; `DEV_PROCESS_EXITED` → read `log`, fix the bug in `src/`, call again.', '');
-    lines.push('## What\'s here', '', `This project was scaffolded by starter-foundry. The user\'s prompt drove the choices below — read their prompt first, it takes priority over everything in this file.`, '', `- **Family:** \`${spec.family}\``, `- **Layers:** ${components.layers.map((l) => `\`${l.group}:${l.id}\``).join(', ')}`);
+    // User's prompt — echo it near the top so the agent sees its brief
+    // before the scaffold's default behavior.
+    if (spec.userPrompt) {
+        lines.push('## User\'s brief (takes priority over everything else in this file)', '', `> ${spec.userPrompt.replace(/\n/g, '\n> ')}`, '');
+    }
+    lines.push('## What\'s here', '', `This project was scaffolded by starter-foundry. The choices below were made deterministically from the user's brief.`, '', `- **Family:** \`${spec.family}\``, `- **Layers:** ${components.layers.map((l) => `\`${l.group}:${l.id}\``).join(', ')}`);
     if (components.partner) {
         lines.push(`- **Partner:** \`${components.partner.id}\``);
     }
@@ -241,6 +316,34 @@ function buildAgentsMd(spec, components, contextHints, mediaSlots = []) {
             lines.push(`- **Integrations:** ${buildPlan.integrations.join(', ')}`);
         lines.push('');
     }
+    if (buildPlan.placeholders.length > 0) {
+        lines.push('## Placeholders — MUST replace', '', 'These files ship DEFAULT content so the preview renders before your first edit. You MUST replace them with product-specific behavior for the user\'s brief. Rewriting `personalize.json` updates brand strings only — it does NOT replace the content in these files. Treat this list as required-to-rewrite.', '');
+        for (const { source, path, description } of buildPlan.placeholders) {
+            lines.push(`- \`${path}\` — ${description} _(${source})_`);
+        }
+        lines.push('');
+    }
+    // Industry first-turn flow — steers the agent toward the right first
+    // feature for the product archetype. Empty string when no industry:*
+    // layer is attached or the industry isn't in the known map.
+    const industryBlock = renderIndustryFirstTurn(components.layers.map((l) => `${l.group}:${l.id}`));
+    if (industryBlock) {
+        lines.push(industryBlock);
+    }
+    if (buildPlan.domainFirstSteps.length > 0) {
+        lines.push('## Domain first moves', '', 'Runtime-specific actions declared by the selected family + layers + partner. Do these before generic setup — they prevent the most common class of first-turn mistakes for this stack.', '');
+        for (const { source, step } of buildPlan.domainFirstSteps) {
+            lines.push(`- **[${source}]** ${step}`);
+        }
+        lines.push('');
+    }
+    if (buildPlan.domainGotchas.length > 0) {
+        lines.push('## Gotchas', '', 'Traps specific to this stack — read before you hit them.', '');
+        for (const { source, note } of buildPlan.domainGotchas) {
+            lines.push(`- **[${source}]** ${note}`);
+        }
+        lines.push('');
+    }
     if (buildPlan.designDirective) {
         lines.push('## Design', '', buildPlan.designDirective, '');
     }
@@ -251,6 +354,8 @@ function buildAgentsMd(spec, components, contextHints, mediaSlots = []) {
         }
         lines.push('', 'Skip any slots that don\'t apply. Add new ones if the product needs them.', '');
     }
+    // Progressive disclosure — turn-order sections agents pattern-match on.
+    lines.push('## Turn 1 (do these before writing features)', '', '1. Call the dev-server route from Step 0 (above). Wait for success.', '2. Read the user\'s brief (above) and the Placeholders section.', '3. Rewrite `personalize.json` + `personalize.css` (brand strings + palette). These are render-time — preview updates on next refresh, no rebuild.', '4. Delete or rewrite EVERY file in the Placeholders list. Not optional.', '5. Only after (3) + (4) do you start feature work.', '', '## Before first preview screenshot', '', '- Confirm the landing surface renders the user\'s product (no default KPI cards from a dashboard template).', '- Brand strings in `personalize.json` are product-specific, not the scaffold default.', '- Any placeholder file in the list above has been replaced or deleted.', '', '## Before shipping', '', '- Run the family\'s validate script (see Key files above).', '- Re-check Gotchas (above) against what you built — those traps bite most at ship time.', '- If you added deps, they\'re in `package.json`; if you added routes/pages, they\'re reachable.', '');
     lines.push('## How to use this scaffold', '', 'This is a starting point, not a contract. You own every file.', '', '- **Customize freely.** Replace components, change the layout, swap the color scheme — whatever fits the user\'s product.', '- **The scaffold saves you setup time** — Tailwind, shadcn/ui, path aliases, and framework config are ready. Don\'t redo them.', '- **Check `.starter-foundry/compose-report.json`** if you want to see which layer wrote which file.', '- **Update this file** as the project evolves. Delete sections that no longer apply.');
     return lines.join('\n');
 }