productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/conductor/families/specSwarm.js

@@ -0,0 +1,146 @@
+// Where the swarm hands off: the finalization pass that turns good product
+// thinking into an implementable packet (alpha_tester_fixes_v0 R-003).
+//
+// This used to read `foo spec-cleanup <packet>` — a command that has never
+// existed. `foo spec-cleanup` is not a CLI domain, it errors with "unknown
+// domain: spec-cleanup"; spec-cleanup is a *skill*. An agent handed a command
+// that does not exist either gives up or invents its own next move, which is
+// the one thing a handoff is supposed to prevent.
+const HANDOFF = "foo skill spec-cleanup";
+// Core lens roster (golden swarm-001 selection rationale, OQ-E2: the fast
+// tier draws the first N lenses; deep runs the full roster).
+const LENSES = [
+    "cpo",
+    "technical-architect",
+    "security-privacy-legal",
+    "applied-ai-eval",
+    "business-gm-pm",
+    "developer-experience",
+    "principal-product-designer",
+    "technical-lead",
+    "data-science",
+    "pmm",
+    "user-research",
+    "qa-release",
+    "content-design",
+    "strategy-competitive",
+    "product-ops-program",
+    "finance-cfo",
+    "accessibility-inclusion",
+    "dx-product",
+    "responsible-ai-safety",
+    "analytics-engineering",
+    "field",
+    "growth-pm",
+    "consumer-craft-pm",
+    "ai-technical-pm",
+    "platform-pm",
+];
+export const specSwarmFamily = {
+    family: "spec-swarm",
+    banner: "── foo ▸ swarm ──  expert lenses before user questions ──",
+    tagline: "expert lenses before user questions",
+    skillRef: "spec-swarm", // a `foo skill` argument, never a filesystem path
+    defaultDepth: "standard",
+    depths: {
+        fast: { lenses: 6, user_questions: 3, candidates_per_lens: 2, judges: 0, exhaustive: false },
+        standard: { lenses: 12, user_questions: 7, candidates_per_lens: 2, judges: 0, exhaustive: false },
+        deep: { lenses: 25, user_questions: 7, candidates_per_lens: 3, judges: 0, exhaustive: true },
+    },
+    phases: ["INTAKE", "LENSES", "PREFLIGHT", "RANK", "ASK", "REPORT"],
+    cells: {
+        rolePrefix: "lens-",
+        countKey: "lenses",
+        maxCount: 25,
+        pools: {
+            lens: { values: LENSES },
+        },
+    },
+    record: {
+        dir: "swarms",
+        frontmatter: (ctx) => [
+            "---",
+            `swarm_id: swarm-${ctx.at.slice(0, 10)}`,
+            `target: ${JSON.stringify(ctx.target)}`,
+            `depth: ${ctx.depth}`,
+            "decider: human            # expert answers carry forward unless the user disagrees",
+            // The decision fields the gates read live in the front matter — the
+            // record is prepared with them EMPTY and the swarm fills them before
+            // `check` can pass (the completion gate demands nonempty not_doing).
+            'minority_report: ""',
+            "not_doing: []",
+            'what_would_change_our_mind: ""',
+            `handoff: ${JSON.stringify(HANDOFF)}`,
+            "---",
+        ],
+        body: () => [
+            "",
+            "# Preflight routing table",
+            "",
+            "| Candidate question | Asking role | Experts consulted | Expert answer | Evidence / reason | Ask user? |",
+            "| --- | --- | --- | --- | --- | --- |",
+            "",
+            "# Swarm report",
+            "",
+            "# Judgment ledger",
+            "",
+            "| Judgment | Owner lens | Type | Evidence | Confidence | Dissent | User? |",
+            "| --- | --- | --- | --- | --- | --- | --- |",
+            "",
+            "# Decision",
+            "",
+        ],
+    },
+    // methodology-compiler-v0 T-004: the swarm's orchestration protocol moved
+    // out of skills/spec-swarm/SKILL.md prose into this compiled emission; the
+    // skill keeps only role-lens craft. Rationale lines ride with each rule.
+    contract: (ctx) => [
+        ctx.family.banner,
+        "",
+        `Target (read before any lens runs): ${ctx.target}`,
+        `Depth: ${ctx.depth} — ${ctx.tier.lenses} lenses · ${ctx.tier.candidates_per_lens} candidates per lens · user-question budget ${ctx.tier.user_questions} across the WHOLE swarm${ctx.tier.exhaustive ? " · exhaustive review" : ""}`,
+        "",
+        "Execute the phases in order. Leaf craft (how to be a good lens): run `foo skill spec-swarm`.",
+        `  ${ctx.family.phases.join(" → ")}`,
+        "",
+        "Protocol (conductor rules — each with its why):",
+        "  INTAKE    read the spec/packet and extract bet, user, workflow, MVP boundary, evidence boundary, risks, validation bar, cut line, open questions — lenses that skip intake re-ask answered questions.",
+        `  LENSES    each lens forms its top ${ctx.tier.candidates_per_lens} candidate question(s) grill-me shaped: question + recommended answer + evidence + type + dissent — a question already answered by the packet is dropped WITH the answering decision cited.`,
+        "  PREFLIGHT every candidate passes the routing gate before any user question: inspect spec/code/tests/docs first, ask the other lenses second, escalate only genuine user-judgment — never ask the user what another lens or the repo can answer.",
+        "  RANK      stack-rank survivors by: bet/user/source-boundary/cut-line impact, then MVP/validation impact, then risk reduction, then churn avoided; ask from the top only — lower-ranked questions become recorded assumptions or open questions, never budget overruns.",
+        "  ASK       one question at a time as numbered options, recommendation first marked (recommended) — the user answers with a digit; batching questions hides the ranking.",
+        "  REPORT    the seven sections, all mandatory: highest-leverage question · expert answers to override · deferred questions · judgment ledger · spec changes implied · finalization gate (spec-cleanup before implementation) · do-not-expand-yet.",
+        "",
+        "Lens roster (one cell per lens):",
+        ...ctx.cells.map((c) => `  ${c.role}: ${c.attrs.lens}`),
+        "",
+        "Routing table (render it — invisible expert routing is the failure mode):",
+        "  | Candidate question | Asking role | Experts consulted | Expert answer | Evidence / reason | Ask user? |",
+        "  Use 'No, carrying forward unless you disagree' for steerable defaults; 'Yes' only for true judgment calls.",
+        "Ledger types never collapse: repo-evidence | approved-context | role-expertise | agent-inference | user-judgment — the boundary between evidence, expertise, inference, and human judgment is the product.",
+        "Progress surface (what the USER sees WHILE lenses run — separate from the record above):",
+        `  Narrate the whole fan-out as ONE foo status line, not a per-lens agent tree — e.g. "🔄 doing — routing your brief past ${ctx.tier.lenses} expert lenses" while they run, then "✋ needs your input — synthesis ready" at the handoff. The lens count and machinery are plumbing; productfoo feels simple only when plumbing stays invisible.`,
+        `  If your harness insists on surfacing agents separately, label EVERY agent — every lens AND the preflight/rank/synthesis steps — as "Expert N" with ONE running counter that never resets between phases (the synthesis step included, e.g. "Expert ${Number(ctx.tier.lenses) + 1}"). The label is the NUMBER ALONE: never a lens id, a role name, or a step name — never "security-privacy-legal", "Chief Product Officer", "Preflight", "Synthesis". Each agent's final line is a bare COUNT — "Done — 2 candidate questions" — never which lens it was. "Expert 3 security-privacy-legal" and "Chief Product Officer" leak the roster exactly as loudly as lens:cpo did; a number with anything stapled to it is not anonymized.`,
+        "  WHICH experts foo routes to, in what order, and which it draws at each depth — ALL of it is the craft. A progress panel is the most screenshotted, most shared surface productfoo has; the roster does not belong in transient chrome.",
+        "  Numbered in the RUNTIME, named in the RECORD. Anonymity buys secrecy in the chrome, never in the product: in the routing table, judgment ledger, and report every judgment keeps its real owner lens — \"Security & Privacy raised this risk\" is what makes a judgment legible and overridable. Invisible expert routing is still the failure mode. And never write \"Expert 3\" into a report: a reader who did not watch the run cannot resolve a number back to a judgment.",
+        "Ground rules: no spec rewrite during the swarm; no new scope by default; expert-resolved answers stay visible and overridable; agent inference is never presented as fact.",
+        "",
+        `Swarm record scaffolded: ${ctx.recordPath}`,
+        "  Read that record before you fill it. productfoo's CLI wrote the file, not you — and a harness that guards blind overwrites refuses the first write to a file the session has never read, so filling it blind fails.",
+        "The user steers every carried-forward expert answer. The human is the Decider.",
+        "",
+    ],
+    gates: [
+        { type: "frontmatter-present", check: "target", field: "target", detail: "target captured", failDetail: "target missing from front matter" },
+        { type: "frontmatter-present", check: "depth", field: "depth", pattern: "(fast|standard|deep)", detail: "depth {value}", failDetail: "depth missing or invalid" },
+        { type: "section-present", check: "routing-table", heading: "Preflight routing table", detail: "routing table present", failDetail: "preflight routing table missing — expert routing was invisible" },
+        { type: "section-present", check: "ledger", heading: "Judgment ledger", detail: "judgment ledger present", failDetail: "judgment ledger missing" },
+        { type: "ledger-types", check: "ledger-taxonomy", taxonomy: ["repo-evidence", "approved-context", "role-expertise", "agent-inference", "user-judgment"] },
+        { type: "section-present", check: "report", heading: "Swarm report", detail: "swarm report present", failDetail: "swarm report missing" },
+        { type: "frontmatter-nonempty", check: "minority-report", field: "minority_report", detail: "dissent preserved", failDetail: "minority report empty — dissent was voted away" },
+        { type: "frontmatter-nonempty", check: "not-doing", field: "not_doing", detail: "explicit not-doing recorded", failDetail: 'missing "do not expand yet"' },
+        { type: "frontmatter-equals", check: "human-decider", field: "decider", expect: "human", detail: "human is the Decider", failDetail: "decider must be human, found: " },
+    ],
+    handoff: HANDOFF,
+    decider: "human",
+};

package/dist-public/src/conductor/familyDelivery.d.ts

@@ -0,0 +1,6 @@
+import { type FamilyPack } from "./pack.js";
+import type { Depth } from "./types.js";
+export declare function familyPacksNotBundledMessage(name: string): string;
+export declare function isKnownFamily(name: string): boolean;
+export declare function clearFamilyPackCache(): void;
+export declare function resolveFamilyPack(name: string, depth: Depth, lean: boolean): Promise<FamilyPack>;

package/dist-public/src/conductor/familyDelivery.js

@@ -0,0 +1,37 @@
+// Resolve bundled family definitions; missing package files are installation errors.
+import { SkillDeliveryError } from "../skillLocal.js";
+import { renderFamilyPack } from "./pack.js";
+const LOCAL_FAMILIES = {
+    ideate: () => import("./families/ideate.js").then((m) => m.ideateFamily),
+    interview: () => import("./families/interview.js").then((m) => m.interviewFamily),
+    "spec-swarm": () => import("./families/specSwarm.js").then((m) => m.specSwarmFamily),
+};
+export function familyPacksNotBundledMessage(name) {
+    return `family packs for "${name}" are not bundled with this productfoo install.`;
+}
+export function isKnownFamily(name) {
+    return Object.prototype.hasOwnProperty.call(LOCAL_FAMILIES, name);
+}
+const packCache = new Map();
+export function clearFamilyPackCache() {
+    packCache.clear();
+}
+export async function resolveFamilyPack(name, depth, lean) {
+    if (!isKnownFamily(name)) {
+        throw new SkillDeliveryError("not-found", `"${name}" is not a known foo method (expected: ${Object.keys(LOCAL_FAMILIES).join(", ")}).`);
+    }
+    const key = `${name}:${depth}:${lean ? 1 : 0}`;
+    const cached = packCache.get(key);
+    if (cached !== undefined)
+        return cached;
+    let family;
+    try {
+        family = await LOCAL_FAMILIES[name]();
+    }
+    catch (cause) {
+        throw new SkillDeliveryError("not-found", familyPacksNotBundledMessage(name), { cause });
+    }
+    const pack = renderFamilyPack(family, depth, lean);
+    packCache.set(key, pack);
+    return pack;
+}

package/dist-public/src/conductor/familyPackArtifact.d.ts

@@ -0,0 +1,4 @@
+import { type FamilyPack } from "./pack.js";
+import type { Depth, FamilyDefinition } from "./types.js";
+export declare function renderFamilyPackArtifact(family: FamilyDefinition): string;
+export declare function parseFamilyPackArtifact(text: string, family: string, depth: Depth, lean: boolean): FamilyPack;

package/dist-public/src/conductor/familyPackArtifact.js

@@ -0,0 +1,260 @@
+import { canonicalJson } from "../trustEnvelope.js";
+import { renderFamilyPack } from "./pack.js";
+const PREFIX = "# Foo signed family packs v1\n\n```json foo-family-packs\n";
+const SUFFIX = "\n```\n";
+const DEPTHS = ["fast", "standard", "deep"];
+const MAX_ARTIFACT_BYTES = 256 * 1024;
+const SAFE_NAME = /^[a-z][a-z0-9-]{0,63}$/;
+const SAFE_KEY = /^[a-z][a-z0-9_]{0,63}$/;
+const SAFE_PATTERN = /^[A-Za-z0-9_().|^$-]{1,256}$/;
+const SAFE_HEADING = /^[A-Za-z0-9][A-Za-z0-9 _&:,'"/-]{0,255}$/;
+function variantKey(depth, lean) {
+    return `${depth}:${lean ? 1 : 0}`;
+}
+function exactKeys(value, expected) {
+    const actual = Object.keys(value).sort();
+    const wanted = [...expected].sort();
+    return actual.length === wanted.length && actual.every((key, index) => key === wanted[index]);
+}
+function plain(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringList(value, maxItems = 512) {
+    return Array.isArray(value)
+        && value.length <= maxItems
+        && value.every((entry) => typeof entry === "string" && Buffer.byteLength(entry, "utf8") <= 32 * 1024);
+}
+function boundedString(value, maxBytes = 4096) {
+    return typeof value === "string" && Buffer.byteLength(value, "utf8") <= maxBytes;
+}
+function validPattern(value) {
+    if (typeof value !== "string" || !SAFE_PATTERN.test(value))
+        return false;
+    try {
+        void new RegExp(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function validGate(value) {
+    if (!plain(value) || typeof value.type !== "string" || typeof value.check !== "string"
+        || !SAFE_NAME.test(value.check)) {
+        return false;
+    }
+    const commonFrontmatter = () => typeof value.field === "string"
+        && SAFE_KEY.test(value.field)
+        && boundedString(value.detail)
+        && boundedString(value.failDetail);
+    switch (value.type) {
+        case "frontmatter-present": {
+            const hasPattern = Object.hasOwn(value, "pattern");
+            return exactKeys(value, hasPattern
+                ? ["type", "check", "field", "pattern", "detail", "failDetail"]
+                : ["type", "check", "field", "detail", "failDetail"])
+                && commonFrontmatter()
+                && (!hasPattern || validPattern(value.pattern));
+        }
+        case "frontmatter-nonempty":
+            return exactKeys(value, ["type", "check", "field", "detail", "failDetail"])
+                && commonFrontmatter();
+        case "frontmatter-equals":
+            return exactKeys(value, ["type", "check", "field", "expect", "detail", "failDetail"])
+                && commonFrontmatter()
+                && boundedString(value.expect, 1024);
+        case "diversity-meter":
+            return exactKeys(value, ["type", "check", "floorCap", "floorKey"])
+                && Number.isSafeInteger(value.floorCap)
+                && value.floorCap >= 0
+                && value.floorCap <= 1024
+                && typeof value.floorKey === "string"
+                && SAFE_KEY.test(value.floorKey);
+        case "diversity-provenance":
+            return exactKeys(value, ["type", "check"]);
+        // frames-v1 (#697): both new gates are closed shapes — frame-reasoning
+        // carries no payload beyond its check name, and versioned-keyline is the
+        // frontmatter-nonempty shape gated on the record's contract version.
+        case "frame-reasoning":
+        case "ideate-falsification":
+        case "ideate-decision":
+            return exactKeys(value, ["type", "check"]);
+        case "versioned-keyline":
+            return exactKeys(value, ["type", "check", "field", "detail", "failDetail"])
+                && commonFrontmatter();
+        case "section-present":
+            return exactKeys(value, ["type", "check", "heading", "detail", "failDetail"])
+                && typeof value.heading === "string"
+                && SAFE_HEADING.test(value.heading)
+                && boundedString(value.detail)
+                && boundedString(value.failDetail);
+        case "ledger-types":
+            return exactKeys(value, ["type", "check", "taxonomy"])
+                && stringList(value.taxonomy, 64)
+                && value.taxonomy.length > 0
+                && value.taxonomy.every((entry) => SAFE_NAME.test(entry));
+        default:
+            return false;
+    }
+}
+function validGates(value) {
+    return Array.isArray(value)
+        && value.length > 0
+        && value.length <= 64
+        && value.every(validGate);
+}
+function validTier(value) {
+    if (!plain(value) || Object.keys(value).length > 32)
+        return false;
+    return Object.entries(value).every(([key, entry]) => SAFE_KEY.test(key)
+        && (typeof entry === "boolean"
+            || (typeof entry === "number" && Number.isSafeInteger(entry) && entry >= 0 && entry <= 1024)));
+}
+function validDepthMap(value) {
+    return plain(value)
+        && exactKeys(value, DEPTHS)
+        && DEPTHS.every((depth) => validTier(value[depth]));
+}
+function validCells(value) {
+    if (value === null)
+        return true;
+    if (!plain(value)
+        || !exactKeys(value, ["rolePrefix", "countKey", "maxCount", "pools", "seed"])
+        || typeof value.rolePrefix !== "string"
+        || !SAFE_KEY.test(value.countKey)
+        || !Number.isSafeInteger(value.maxCount)
+        || value.maxCount < 1
+        || value.maxCount > 64
+        || !plain(value.pools)
+        || Object.keys(value.pools).length > 32) {
+        return false;
+    }
+    for (const [attribute, pool] of Object.entries(value.pools)) {
+        if (!SAFE_KEY.test(attribute)
+            || !plain(pool)
+            || !exactKeys(pool, Object.hasOwn(pool, "cycleKey") ? ["values", "cycleKey"] : ["values"])
+            || !stringList(pool.values, 64)
+            || pool.values.length === 0
+            || pool.values.some((entry) => !SAFE_NAME.test(entry))
+            || (Object.hasOwn(pool, "cycleKey") && (typeof pool.cycleKey !== "string" || !SAFE_KEY.test(pool.cycleKey)))) {
+            return false;
+        }
+    }
+    if (value.seed !== null) {
+        if (!plain(value.seed)
+            || !exactKeys(value.seed, ["attr", "base", "step"])
+            || typeof value.seed.attr !== "string"
+            || !SAFE_KEY.test(value.seed.attr)
+            || !Number.isSafeInteger(value.seed.base)
+            || !Number.isSafeInteger(value.seed.step)) {
+            return false;
+        }
+    }
+    return true;
+}
+const PACK_KEYS = [
+    "family",
+    "banner",
+    "tagline",
+    "skillRef",
+    "defaultDepth",
+    "phases",
+    "handoff",
+    "decider",
+    "depth",
+    "lean",
+    "depths",
+    "cells",
+    "recordDir",
+    "contract",
+    "frontmatter",
+    "body",
+    "gates",
+];
+function validPack(value, family, depth, lean) {
+    if (!plain(value)
+        || !exactKeys(value, PACK_KEYS)
+        || value.family !== family
+        || value.depth !== depth
+        || value.lean !== lean
+        || value.skillRef !== family
+        || value.decider !== "human"
+        || !DEPTHS.includes(value.defaultDepth)
+        || typeof value.banner !== "string"
+        || typeof value.tagline !== "string"
+        || typeof value.handoff !== "string"
+        || !stringList(value.phases, 32)
+        || !validDepthMap(value.depths)
+        || !validCells(value.cells)
+        || !stringList(value.contract)
+        || !stringList(value.frontmatter)
+        || !stringList(value.body)
+        || !validGates(value.gates)) {
+        return false;
+    }
+    // V1 serves only ideate. Pinning the one writable directory makes a signed
+    // release bug fail closed before path.resolve can observe an escape.
+    return family === "ideate" && value.recordDir === "ideas";
+}
+export function renderFamilyPackArtifact(family) {
+    const variants = {};
+    for (const depth of DEPTHS) {
+        for (const lean of [false, true]) {
+            variants[variantKey(depth, lean)] = renderFamilyPack(family, depth, lean);
+        }
+    }
+    const payload = {
+        schema_version: "1",
+        family: family.family,
+        variants,
+    };
+    return `${PREFIX}${canonicalJson(payload)}${SUFFIX}`;
+}
+function deepFreeze(value) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        for (const entry of Object.values(value))
+            deepFreeze(entry);
+        Object.freeze(value);
+    }
+    return value;
+}
+export function parseFamilyPackArtifact(text, family, depth, lean) {
+    const invalid = () => {
+        throw new TypeError("invalid signed family-pack artifact");
+    };
+    if (!SAFE_NAME.test(family)
+        || Buffer.byteLength(text, "utf8") > MAX_ARTIFACT_BYTES
+        || !text.startsWith(PREFIX)
+        || !text.endsWith(SUFFIX)) {
+        return invalid();
+    }
+    let value;
+    try {
+        value = JSON.parse(text.slice(PREFIX.length, -SUFFIX.length));
+    }
+    catch {
+        return invalid();
+    }
+    if (!plain(value)
+        || !exactKeys(value, ["schema_version", "family", "variants"])
+        || value.schema_version !== "1"
+        || value.family !== family
+        || !plain(value.variants)) {
+        return invalid();
+    }
+    const expectedVariants = DEPTHS.flatMap((candidateDepth) => [
+        variantKey(candidateDepth, false),
+        variantKey(candidateDepth, true),
+    ]);
+    if (!exactKeys(value.variants, expectedVariants))
+        return invalid();
+    for (const candidateDepth of DEPTHS) {
+        for (const candidateLean of [false, true]) {
+            if (!validPack(value.variants[variantKey(candidateDepth, candidateLean)], family, candidateDepth, candidateLean)) {
+                return invalid();
+            }
+        }
+    }
+    const selected = value.variants[variantKey(depth, lean)];
+    return deepFreeze(selected);
+}

package/dist-public/src/conductor/ideateDecision.d.ts

@@ -0,0 +1,6 @@
+import { type OrchestrationResult } from "../orchestrationResult.js";
+export declare const DECISION_CONTRACT = "decisions-v2";
+export declare function hasDecisionContract(record: string): boolean;
+export declare function checkFalsification(record: string): string[];
+export declare function checkDecision(record: string): string[];
+export declare function decisionResult(record: string): OrchestrationResult;