productfoo 0.0.0-stage → 1.0.1

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

@@ -0,0 +1,237 @@
+// Deterministic coverage and consistency checks, not a factual truth oracle.
+// The harness performs the research/critique; productfoo keeps unknowns visible and
+// prevents refuted premises from silently returning in a polished decision.
+import { ideateContractVersion, ideateFrontmatter, parseIdeaObjects } from "./diversity.js";
+import { renderOrchestrationResult } from "../orchestrationResult.js";
+export const DECISION_CONTRACT = "decisions-v2";
+const object = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
+const text = (v) => typeof v === "string" && v.trim().length > 0 && !/^(TODO|null)$/i.test(v.trim());
+const strings = (v) => Array.isArray(v) && v.every(text);
+const normalized = (v) => v.trim().replace(/\s+/g, " ").toLowerCase();
+export function hasDecisionContract(record) {
+    return ideateContractVersion(record) === DECISION_CONTRACT;
+}
+function block(record, name, errors) {
+    const matches = [...record.matchAll(new RegExp("^```json " + name + "\\s*\\r?\\n([\\s\\S]*?)^```[ \\t]*$", "gm"))];
+    if (matches.length !== 1) {
+        errors.push(`store exactly one json ${name} block (found ${matches.length})`);
+        return null;
+    }
+    try {
+        const value = JSON.parse(matches[0][1]);
+        if (object(value))
+            return value;
+    }
+    catch { /* The field name is sufficient; never echo arbitrary source text. */ }
+    errors.push(`${name} must be a JSON object`);
+    return null;
+}
+function fields(value, names, label, errors) {
+    for (const name of names)
+        if (!text(value[name]))
+            errors.push(`${label}.${name} must contain text`);
+}
+function readFalsification(record, errors) {
+    const value = block(record, "falsification", errors);
+    if (!value)
+        return null;
+    const start = errors.length;
+    if (!Array.isArray(value.claims))
+        errors.push("falsification.claims must be an array");
+    else
+        for (const [index, entry] of value.claims.entries()) {
+            const at = `falsification.claims[${index}]`;
+            if (!object(entry)) {
+                errors.push(`${at} must be an object`);
+                continue;
+            }
+            fields(entry, ["claim", "consequence"], at, errors);
+            if (typeof entry.verdict !== "string" || !["supported", "refuted", "unknown"].includes(entry.verdict))
+                errors.push(`${at}.verdict must be supported, refuted, or unknown`);
+            if (!Array.isArray(entry.evidence))
+                errors.push(`${at}.evidence must be an array`);
+            else {
+                if (entry.verdict !== "unknown" && entry.evidence.length === 0)
+                    errors.push(`${at}: ${entry.verdict} requires a cited observation`);
+                for (const observation of entry.evidence) {
+                    if (!object(observation))
+                        errors.push(`${at}.evidence must contain source/observation objects`);
+                    else
+                        fields(observation, ["source", "observation"], `${at}.evidence`, errors);
+                }
+            }
+        }
+    if (!strings(value.excluded_ideas))
+        errors.push("falsification.excluded_ideas must be an array of idea IDs");
+    return errors.length === start ? value : null;
+}
+export function checkFalsification(record) {
+    if (!hasDecisionContract(record))
+        return ["early falsification requires a decisions-v2 record; older records cannot prove this check"];
+    const errors = [];
+    if ([...record.matchAll(/```json ideas\s*\n/g)].length !== 1)
+        errors.push("store exactly one json ideas block before checking claims");
+    const review = readFalsification(record, errors);
+    const parsed = parseIdeaObjects(record);
+    if (!parsed.present || !parsed.ideas.length)
+        errors.push("store the idea pool before checking its claims");
+    errors.push(...parsed.errors);
+    if (!review)
+        return errors;
+    const claims = new Map();
+    for (const claim of review.claims) {
+        const key = normalized(claim.claim);
+        if (claims.has(key))
+            errors.push(`duplicate claim review: ${claim.claim}`);
+        claims.set(key, claim);
+    }
+    const ids = new Set(parsed.ideas.map((idea) => idea.id));
+    for (const id of review.excluded_ideas)
+        if (!ids.has(id))
+            errors.push(`excluded idea does not exist: ${id}`);
+    const used = new Set();
+    for (const idea of parsed.ideas) {
+        for (const claim of idea.claims_relied_on) {
+            const key = normalized(claim);
+            used.add(key);
+            if (!text(claim)) {
+                errors.push(`${idea.id}: claims_relied_on contains an empty claim`);
+                continue;
+            }
+            const reviewed = claims.get(key);
+            if (!reviewed)
+                errors.push(`${idea.id}: unreviewed claim: ${claim}`);
+            else if (reviewed.verdict === "refuted" && !review.excluded_ideas.includes(idea.id))
+                errors.push(`${idea.id}: refuted premise requires exclusion; revise as a new idea with corrected claims`);
+        }
+    }
+    for (const [key, claim] of claims)
+        if (!used.has(key))
+            errors.push(`review names a claim absent from the stored pool: ${claim.claim}`);
+    return errors;
+}
+function readGrounding(record, errors) {
+    const value = block(record, "grounding", errors);
+    if (!value)
+        return null;
+    const start = errors.length;
+    if (!strings(value.searched) || !value.searched.length)
+        errors.push("grounding.searched must name the local locations actually searched");
+    if (!Array.isArray(value.sources))
+        errors.push("grounding.sources must be an array");
+    else
+        for (const source of value.sources) {
+            if (!object(source))
+                errors.push("grounding.sources must contain source/takeaway objects");
+            else
+                fields(source, ["source", "takeaway"], "grounding.sources", errors);
+        }
+    fields(value, ["gap"], "grounding", errors);
+    return errors.length === start ? value : null;
+}
+function readDecision(record, errors) {
+    const value = block(record, "decision", errors);
+    if (!value)
+        return null;
+    const start = errors.length;
+    fields(value, ["recommendation", "rationale", "new_contribution", "dissent", "next_action"], "decision", errors);
+    for (const key of ["idea_ids", "assumptions", "not_doing"]) {
+        if (!strings(value[key]))
+            errors.push(`decision.${key} must be an array of non-empty strings`);
+    }
+    if (Array.isArray(value.not_doing) && !value.not_doing.length)
+        errors.push("decision.not_doing must name a cut");
+    if (!object(value.confidence) || typeof value.confidence.level !== "string" || !["low", "medium", "high"].includes(value.confidence.level) || !text(value.confidence.reason))
+        errors.push("decision.confidence requires level (low/medium/high) and reason");
+    if (!object(value.experiment))
+        errors.push("decision.experiment must be an object");
+    else
+        fields(value.experiment, ["action", "effort", "pass", "fail"], "decision.experiment", errors);
+    if (!Array.isArray(value.alternatives) || value.alternatives.length > 2)
+        errors.push("decision.alternatives must contain at most 2 alternatives");
+    else
+        for (const alt of value.alternatives) {
+            if (!object(alt)) {
+                errors.push("decision.alternatives must contain objects");
+                continue;
+            }
+            fields(alt, ["direction", "choose_when"], "decision.alternatives", errors);
+            if (!strings(alt.idea_ids) || !alt.idea_ids.length)
+                errors.push("each alternative must identify its source ideas");
+        }
+    if (!Array.isArray(value.builds_on) || value.builds_on.length > 3)
+        errors.push("decision.builds_on must contain at most 3 prior-work references");
+    else
+        for (const source of value.builds_on) {
+            if (!object(source))
+                errors.push("decision.builds_on must contain source/delta objects");
+            else
+                fields(source, ["source", "delta"], "decision.builds_on", errors);
+        }
+    return errors.length === start ? value : null;
+}
+function resultFrom(decision, review) {
+    // The page carries enough to understand the refutation and find its source;
+    // raw observations remain complete in the record and never consume its budget.
+    const short = (value) => {
+        const words = value.trim().split(/\s+/);
+        const excerpt = words.slice(0, 35).join(" ").slice(0, 280);
+        return excerpt.length < value.trim().length ? `${excerpt}…` : excerpt;
+    };
+    const refuted = review.claims.filter((claim) => claim.verdict === "refuted");
+    return {
+        recommendation: [decision.recommendation, decision.rationale, `What this adds: ${decision.new_contribution}`,
+            ...decision.builds_on.map((s) => `Builds on ${s.source}: ${s.delta}`),
+            `Confidence: ${decision.confidence.level} — ${decision.confidence.reason}`,
+            `Assumptions: ${decision.assumptions.length ? decision.assumptions.join("; ") : "No unresolved empirical premise recorded."}`].join("\n"),
+        alternatives: decision.alternatives.map((a) => `${a.direction} — choose when ${a.choose_when}`),
+        falsified: [
+            ...refuted.slice(0, 3).map((c) => `${short(c.claim)} — ${short(c.evidence[0].observation)} (${c.evidence[0].source}). ${short(c.consequence)}`),
+            ...(refuted.length ? [`${refuted.length > 3 ? `${refuted.length - 3} further refuted claims; ` : ""}complete observations remain in the backing record.`] : []),
+        ],
+        dissent: decision.dissent,
+        what_would_change_our_mind: decision.experiment.fail,
+        next_action: [`First test: ${decision.experiment.action}`, `Effort: ${decision.experiment.effort}`, `Pass: ${decision.experiment.pass}`, `Proposed cuts: ${decision.not_doing.join("; ")}`, decision.next_action].join("\n"),
+    };
+}
+export function checkDecision(record) {
+    const errors = checkFalsification(record);
+    const review = readFalsification(record, errors);
+    const grounding = readGrounding(record, errors);
+    const decision = readDecision(record, errors);
+    if (!review || !grounding || !decision)
+        return [...new Set(errors)];
+    if (ideateFrontmatter(record)?.recommendation !== decision.recommendation)
+        errors.push("frontmatter recommendation must match decision.recommendation exactly");
+    const ideas = new Map(parseIdeaObjects(record).ideas.map((idea) => [idea.id, idea]));
+    const claims = new Map(review.claims.map((c) => [normalized(c.claim), c]));
+    const disclosed = new Set(decision.assumptions.map(normalized));
+    for (const id of [...decision.idea_ids, ...decision.alternatives.flatMap((a) => a.idea_ids)]) {
+        const idea = ideas.get(id);
+        if (!idea)
+            errors.push(`decision references an unknown idea: ${id}`);
+        else {
+            if (review.excluded_ideas.includes(id))
+                errors.push(`decision revives excluded idea: ${id}`);
+            for (const claim of idea.claims_relied_on) {
+                if (claims.get(normalized(claim))?.verdict === "unknown" && !disclosed.has(normalized(claim)))
+                    errors.push(`decision must disclose unresolved assumption: ${claim}`);
+            }
+        }
+    }
+    const sources = new Set(grounding.sources.map((s) => s.source));
+    if (sources.size && !decision.builds_on.length)
+        errors.push("decision must explain what it adds to the prior work found");
+    for (const source of decision.builds_on)
+        if (!sources.has(source.source))
+            errors.push(`decision cites prior work absent from grounding: ${source.source}`);
+    if (renderOrchestrationResult(resultFrom(decision, review)).trim().split(/\s+/).length > 600)
+        errors.push("decision exceeds the 600-word result budget; keep the full evidence in the backing record");
+    return [...new Set(errors)];
+}
+export function decisionResult(record) {
+    const errors = checkDecision(record);
+    if (errors.length)
+        throw new Error(errors.join("; "));
+    return resultFrom(readDecision(record, []), readFalsification(record, []));
+}

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

@@ -0,0 +1,26 @@
+import type { Depth, FamilyDefinition, GateSpec } from "./types.js";
+export interface FamilyPack {
+    family: string;
+    banner: string;
+    tagline: string;
+    skillRef: string;
+    defaultDepth: Depth;
+    phases: readonly string[];
+    handoff: string;
+    decider: "human";
+    depth: Depth;
+    lean: boolean;
+    depths: FamilyDefinition["depths"];
+    cells: FamilyDefinition["cells"];
+    recordDir: string | null;
+    contract: string[];
+    frontmatter: string[] | null;
+    body: string[] | null;
+    gates: GateSpec[];
+}
+export declare function renderFamilyPack(family: FamilyDefinition, depth: Depth, lean: boolean): FamilyPack;
+export declare function contractFromPack(pack: FamilyPack, target: string, at: string): string[];
+export declare function recordFromPack(pack: FamilyPack, target: string, at: string): {
+    frontmatter: string[];
+    body: string[];
+} | null;

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

@@ -0,0 +1,75 @@
+// methodology-as-data (R-001/R-002): a FamilyPack is a family definition
+// rendered to DATA so the shipped client can run a family it does not hold.
+//
+// The move: everything in a family's emitted contract/record is determined by
+// (family, depth, lean) EXCEPT two values that are the user's alone — the target
+// (their idea / work item) and the run timestamp. So the server renders the
+// contract/record once, with sentinels standing in for those two, using the
+// EXACT same render functions (byte-compat is automatic — no re-expressed
+// template to drift). The client fetches the pack and substitutes the real
+// target + timestamp back in locally. The target never leaves the machine (B1);
+// the wire request carries only {token, family, depth, lean} — enums and a bool.
+//
+// The engine that ships stays generic (cell arithmetic, gate evaluation, this
+// substitution); the methodology PROSE + roster + gates travel in the pack,
+// fetched per run, never written to the tester's disk.
+import { renderContext, slugify } from "./engine.js";
+// Sentinels: alphanumeric and unmistakable, so no methodology prose collides
+// with them and each of the derived forms (raw / slug / JSON) stays distinct.
+const S_TARGET = "Zx9TargetSentinel9xZ";
+const S_TARGET_SLUG = slugify(S_TARGET); // "zx9targetsentinel9xz" — lowercased, alnum-only
+const S_TARGET_JSON = JSON.stringify(S_TARGET); // "\"Zx9TargetSentinel9xZ\""
+const S_AT = "0000-00-00T00:00:00.000Z";
+const S_AT_DATE = S_AT.slice(0, 10); // "0000-00-00" — the only slice of `at` any family uses
+// Server side: render a family to a pack for one (depth, lean). Uses the real
+// render functions with sentinel target + at, so the bytes match a local run.
+export function renderFamilyPack(family, depth, lean) {
+    const ctx = { ...renderContext(family, S_TARGET, depth, S_AT, "/"), lean };
+    return {
+        family: family.family,
+        banner: family.banner,
+        tagline: family.tagline,
+        skillRef: family.skillRef,
+        defaultDepth: family.defaultDepth,
+        phases: family.phases,
+        handoff: family.handoff,
+        decider: family.decider,
+        depth,
+        lean,
+        depths: family.depths,
+        cells: family.cells,
+        recordDir: family.record ? family.record.dir : null,
+        contract: family.contract(ctx),
+        frontmatter: family.record ? family.record.frontmatter(ctx) : null,
+        body: family.record ? family.record.body(ctx) : null,
+        gates: family.gates,
+    };
+}
+// Client side: put the user's real target + timestamp back into sentinelised
+// lines. Order is load-bearing: the JSON form is replaced before the raw form
+// (the raw sentinel is a substring of the quoted JSON form), and the slug form
+// is lowercase so it never collides with the mixed-case raw form.
+function substitute(lines, target, at) {
+    const slug = slugify(target);
+    const json = JSON.stringify(target);
+    const atDate = at.slice(0, 10);
+    return lines.map((line) => line
+        .split(S_TARGET_JSON).join(json)
+        .split(S_TARGET).join(target)
+        .split(S_TARGET_SLUG).join(slug)
+        .split(S_AT_DATE).join(atDate));
+}
+// The client's stand-ins for renderContract / scaffoldRecord bodies, driven by
+// a fetched pack instead of a local family. recordPath falls out of the
+// substitution (it is dir + at-date + slug, all substituted).
+export function contractFromPack(pack, target, at) {
+    return substitute(pack.contract, target, at);
+}
+export function recordFromPack(pack, target, at) {
+    if (pack.frontmatter === null || pack.body === null)
+        return null;
+    return {
+        frontmatter: substitute(pack.frontmatter, target, at),
+        body: substitute(pack.body, target, at),
+    };
+}

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

@@ -0,0 +1,111 @@
+export type Depth = "fast" | "standard" | "deep";
+export type Tier = Record<string, number | boolean>;
+export interface Cell {
+    role: string;
+    attrs: Record<string, string | number>;
+}
+export interface CellRule {
+    rolePrefix: string;
+    countKey: string;
+    maxCount?: number;
+    pools: Record<string, {
+        values: readonly string[];
+        cycleKey?: string;
+    }>;
+    seed?: {
+        attr: string;
+        base: number;
+        step: number;
+    };
+}
+export type GateSpec = {
+    type: "frontmatter-present";
+    check: string;
+    field: string;
+    pattern?: string;
+    detail: string;
+    failDetail: string;
+} | {
+    type: "frontmatter-nonempty";
+    check: string;
+    field: string;
+    detail: string;
+    failDetail: string;
+} | {
+    type: "frontmatter-equals";
+    check: string;
+    field: string;
+    expect: string;
+    detail: string;
+    failDetail: string;
+} | {
+    type: "diversity-meter";
+    check: string;
+    floorCap: number;
+    floorKey: string;
+} | {
+    type: "diversity-provenance";
+    check: string;
+} | {
+    type: "section-present";
+    check: string;
+    heading: string;
+    detail: string;
+    failDetail: string;
+} | {
+    type: "ledger-types";
+    check: string;
+    taxonomy: readonly string[];
+} | {
+    type: "frame-reasoning";
+    check: string;
+} | {
+    type: "ideate-falsification" | "ideate-decision";
+    check: string;
+} | {
+    type: "versioned-keyline";
+    check: string;
+    field: string;
+    detail: string;
+    failDetail: string;
+};
+export interface RecordTemplate {
+    dir: string;
+    frontmatter: (ctx: RenderContext) => string[];
+    body: (ctx: RenderContext) => string[];
+}
+export interface FamilyDefinition {
+    family: string;
+    banner: string;
+    tagline: string;
+    skillRef: string;
+    depths: Record<Depth, Tier>;
+    defaultDepth: Depth;
+    phases: readonly string[];
+    cells: CellRule | null;
+    record: RecordTemplate | null;
+    contract: (ctx: RenderContext) => string[];
+    gates: GateSpec[];
+    handoff: string;
+    decider: "human";
+}
+export interface RenderContext {
+    family: FamilyDefinition;
+    target: string;
+    depth: Depth;
+    tier: Tier;
+    cells: Cell[];
+    at: string;
+    recordPath: string | null;
+    root: string;
+    lean?: boolean;
+}
+export interface GateFinding {
+    check: string;
+    ok: boolean;
+    detail: string;
+}
+export interface GateResult {
+    ok: boolean;
+    findings: GateFinding[];
+}

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

@@ -0,0 +1,7 @@
+// methodology-compiler-v0 (R-001) — the conductor engine's data model.
+// A methodology family is DATA: depth tiers, phases, cell assignment, record
+// scaffold, emitted-contract template, and gate specs. The engine renders
+// contracts and verifies records; it never generates ideas, never calls a
+// model, and never ships to testers. Orchestration expressed here stops
+// existing as servable prose (R-002); only leaf prompts stay servable (R-003).
+export {};

package/dist-public/src/configPath.d.ts

@@ -0,0 +1,2 @@
+/** Preserve project-root overrides while keeping bundled data in config/. */
+export declare function configPath(root: string, name: string): string;

package/dist-public/src/configPath.js

@@ -0,0 +1,7 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+/** Preserve project-root overrides while keeping bundled data in config/. */
+export function configPath(root, name) {
+    const override = path.join(root, name);
+    return existsSync(override) ? override : path.join(root, "config", name);
+}

package/dist-public/src/discoveryArtifacts.d.ts

@@ -0,0 +1,54 @@
+export declare const DISCOVERY_SCHEMA_VERSION: "0.1";
+export type DiscoveryLifecycle = "draft" | "awaiting_interview" | "awaiting_match" | "ambiguous_match" | "needs_source_approval" | "needs_provider_access" | "needs_provider_connector" | "needs_research_proof" | "ready_to_synthesize" | "needs_review" | "complete" | "revoked";
+export type DiscoveryActor = {
+    type: "human" | "agent";
+    id: string;
+};
+export type DiscoveryWrite = {
+    path: string;
+    action: "created" | "updated" | "removed";
+};
+export type DiscoveryRun = {
+    schema_version: "0.1";
+    study_id: string;
+    goal: string;
+    lane: "study_linked";
+    target: {
+        name: string;
+        organization: string;
+        public_url?: string;
+        provenance: string;
+    };
+    match: {
+        provider: string;
+        connection_alias: string;
+        expected_local_date: string | null;
+        timezone: string;
+        required_participants: string[];
+        required_title_tokens: string[];
+    };
+    source: {
+        provider: string;
+        connection_alias: string;
+        stable_url: string | null;
+    };
+    state: DiscoveryLifecycle;
+    source_state: "excluded" | "approved" | "revoked";
+    access_state: "unknown" | "available" | "denied";
+    proof_state: "missing" | "ready" | "consumed";
+    created_at: string;
+    updated_at: string;
+    provenance: string;
+};
+export type DiscoveryValidation = {
+    ok: boolean;
+    errors: string[];
+    studies: number;
+    inbox: boolean;
+};
+export declare function loadDiscoveryRun(studyDir: string): DiscoveryRun;
+export declare function validateDiscoveryPath(root: string, target?: string): DiscoveryValidation;
+export declare function locateStudy(root: string, studyId: string): string | null;
+export declare function transitionDiscoveryRun(studyDir: string, next: DiscoveryLifecycle, actor: DiscoveryActor, now: string): DiscoveryWrite[];
+export type DiscoveryCandidateClass = "real-study" | "product-spec" | "method-research" | "synthetic-rehearsal" | "not-discovery";
+export declare function classifyDiscoveryCandidate(filePath: string, text: string): DiscoveryCandidateClass;