agent-dealer 1.2.7 → 1.2.8

package/bundle/shared/dist/execution-contract.js

@@ -0,0 +1,307 @@
+import { z } from "zod";
+/**
+ * NOT-306: frozen Dealer execution contracts compiled from Planner-authored
+ * Linear tickets.
+ *
+ * A Planner brief carries its execution semantics as canonical Markdown
+ * headings in the ticket description. This module is the ONE implementation
+ * that parses, validates, and structures those headings — shared by the web
+ * intake, the API routes, and (through the API) the CLI, so no intake path
+ * keeps its own regex or drifts from the others.
+ *
+ * The ticket description stays the untouched source of truth; the contract is
+ * derived data. A description with none of the canonical headings is a
+ * compatible legacy issue (contract `null`) and existing/manual issues are
+ * never blocked.
+ */
+export const EXECUTION_CONTRACT_VERSION = "v1";
+export const ExecutionMode = z.enum(["feature", "bug fix", "refactor", "investigation", "split child"]);
+const EXECUTION_MODES = ExecutionMode.options;
+export const ExecutionContractCriterion = z.object({
+    text: z.string(),
+    /** Raw `Evidence:` line body (where to look, action/command, expected result). */
+    evidence: z.string().nullable(),
+});
+export const ExecutionContractV1 = z.object({
+    version: z.literal(EXECUTION_CONTRACT_VERSION),
+    executionMode: ExecutionMode,
+    nonGoals: z.array(z.string()),
+    exitPredicate: z.string(),
+    onePrStoppingPoint: z.string(),
+    acceptanceCriteria: z.array(ExecutionContractCriterion),
+});
+/** Display names of the canonical `##` headings, in ticket order. */
+export const EXECUTION_CONTRACT_HEADINGS = {
+    executionMode: "Builder execution mode",
+    nonGoals: "Non-goals",
+    exitPredicate: "Exit predicate",
+    onePrStoppingPoint: "One-PR stopping point",
+    acceptanceCriteria: "Acceptance criteria",
+};
+/** Actionable validation failure — callers map this to a 400, never a silent drop. */
+export class ExecutionContractError extends Error {
+    constructor(message) {
+        super(`Execution contract: ${message}`);
+        this.name = "ExecutionContractError";
+    }
+}
+const SECTION_KEYS = Object.keys(EXECUTION_CONTRACT_HEADINGS);
+/** Canonical key for a raw `##` heading: lowercase, hyphens→spaces, collapsed. */
+function normalizeHeadingName(raw) {
+    return raw.trim().toLowerCase().replace(/[-_]+/g, " ").replace(/\s+/g, " ").trim();
+}
+const CANONICAL_BY_NORMALIZED = Object.fromEntries(SECTION_KEYS.map((key) => [
+    normalizeHeadingName(EXECUTION_CONTRACT_HEADINGS[key]),
+    key,
+]));
+/** The four Planner-signal headings. `Acceptance criteria` alone stays legacy. */
+const SIGNAL_KEYS = [
+    "executionMode",
+    "nonGoals",
+    "exitPredicate",
+    "onePrStoppingPoint",
+];
+/** Split Markdown into `##`-level sections (only `##`, never `#` or `###`). */
+function splitSections(description) {
+    const lines = description.split("\n");
+    const sections = [];
+    let current = null;
+    for (const line of lines) {
+        const heading = line.match(/^##\s+(.+?)\s*$/);
+        if (heading?.[1] !== undefined) {
+            if (current)
+                sections.push({ name: current.name, body: current.body.join("\n") });
+            current = { name: heading[1].trim(), body: [] };
+        }
+        else if (current) {
+            current.body.push(line);
+        }
+    }
+    if (current)
+        sections.push({ name: current.name, body: current.body.join("\n") });
+    return sections;
+}
+/** Normalize an execution-mode value (`Bug-Fix` → `bug fix`); null when unknown. */
+function normalizeExecutionMode(raw) {
+    const collapsed = raw
+        .trim()
+        .toLowerCase()
+        .replace(/[-_]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        // Planner tickets punctuate the value as prose (`Feature.`); trailing
+        // sentence punctuation is not part of the mode.
+        .replace(/[.\u3002!?;:,'"\)\]]+$/g, "")
+        .trim();
+    if (collapsed === "bugfix")
+        return "bug fix";
+    const found = EXECUTION_MODES.find((m) => m === collapsed);
+    return (found ?? null);
+}
+function requireSection(sections, key) {
+    const section = sections.get(key);
+    if (!section) {
+        throw new ExecutionContractError(`missing \`## ${EXECUTION_CONTRACT_HEADINGS[key]}\` — a ticket with any execution-contract heading must carry all five contract sections`);
+    }
+    return section;
+}
+function parseNonGoals(body) {
+    const items = [];
+    for (const line of body.split("\n")) {
+        if (!line.trim())
+            continue;
+        const item = line.match(/^\s*(?:[-*+]|\d+[.)])\s+(.+?)\s*$/);
+        if (!item?.[1]) {
+            throw new ExecutionContractError(`\`## Non-goals\` must be a Markdown list — got a non-list line: "${line.trim()}"`);
+        }
+        items.push(item[1]);
+    }
+    if (items.length === 0) {
+        throw new ExecutionContractError("`## Non-goals` must list at least one non-goal");
+    }
+    return items;
+}
+function parseExitPredicate(body) {
+    const text = body.trim();
+    if (!text) {
+        throw new ExecutionContractError("`## Exit predicate` must be one observable completion statement (got empty)");
+    }
+    if (/\n\s*\n/.test(text)) {
+        throw new ExecutionContractError("`## Exit predicate` must be one observable completion statement (a single paragraph)");
+    }
+    return text;
+}
+function parseOnePrStoppingPoint(body) {
+    const text = body.trim();
+    if (!text) {
+        throw new ExecutionContractError("`## One-PR stopping point` must state the boundary where this worker must stop (got empty)");
+    }
+    return text;
+}
+const CHECKBOX_RE = /^\s*[-*]\s+\[([ xX])\]\s+(.*)$/;
+// Planner/Linear evidence lines carry the ticket's nested bullet (`  * Evidence: ...`);
+// accept an optional bullet marker so that canonical shape parses as evidence.
+const EVIDENCE_RE = /^\s*(?:[-*+]\s+)?Evidence\s*:\s*(.*)$/i;
+const BULLET_RE = /^\s*(?:[-*+]|\d+[.)])\s+/;
+function normalizeCriterionText(raw) {
+    return raw.trim().replace(/\s+/g, " ").toLowerCase();
+}
+function parseAcceptanceCriteria(body) {
+    const criteria = [];
+    const seen = new Map();
+    let current = null;
+    let hasEvidence = false;
+    const flush = () => {
+        if (current)
+            criteria.push(current);
+        current = null;
+        hasEvidence = false;
+    };
+    for (const line of body.split("\n")) {
+        if (!line.trim())
+            continue;
+        const checkbox = line.match(CHECKBOX_RE);
+        if (checkbox) {
+            flush();
+            const text = (checkbox[2] ?? "").trim();
+            if (!text) {
+                throw new ExecutionContractError("`## Acceptance criteria` has a checkbox item with no text");
+            }
+            const key = normalizeCriterionText(text);
+            const first = seen.get(key);
+            if (first !== undefined) {
+                throw new ExecutionContractError(`\`## Acceptance criteria\` has a duplicate criterion: "${first}" — keep each criterion exactly once`);
+            }
+            seen.set(key, text);
+            current = { text, evidence: null };
+            continue;
+        }
+        const evidence = line.match(EVIDENCE_RE);
+        if (evidence) {
+            if (!current) {
+                throw new ExecutionContractError("`## Acceptance criteria` has an `Evidence:` line before any criterion — indent it under the criterion it belongs to");
+            }
+            if (hasEvidence) {
+                throw new ExecutionContractError(`\`## Acceptance criteria\` has two \`Evidence:\` lines for one criterion ("${current.text}") — keep exactly one`);
+            }
+            const value = (evidence[1] ?? "").trim();
+            if (!value) {
+                throw new ExecutionContractError(`\`## Acceptance criteria\` has an empty \`Evidence:\` line for "${current.text}" — state where to look, the action/command, and the expected result`);
+            }
+            current.evidence = value;
+            hasEvidence = true;
+            continue;
+        }
+        if (BULLET_RE.test(line)) {
+            throw new ExecutionContractError(`\`## Acceptance criteria\` items must be checkboxes (\`- [ ] text\`) with an optional indented \`Evidence:\` line — got a plain bullet: "${line.trim()}"`);
+        }
+        throw new ExecutionContractError(`\`## Acceptance criteria\` lines must be \`- [ ]\` checkbox items or indented \`Evidence:\` lines — got: "${line.trim()}"`);
+    }
+    flush();
+    if (criteria.length === 0) {
+        throw new ExecutionContractError("`## Acceptance criteria` must contain at least one `- [ ]` checkbox item");
+    }
+    return criteria;
+}
+/** Re-serialize contract criteria as the legacy acceptance-criteria text column. */
+export function renderContractAcceptanceCriteria(contract) {
+    const lines = [];
+    for (const criterion of contract.acceptanceCriteria) {
+        lines.push(`- [ ] ${criterion.text}`);
+        if (criterion.evidence)
+            lines.push(`  Evidence: ${criterion.evidence}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Compile a ticket description into its execution contract. Throws
+ * {@link ExecutionContractError} with an actionable message once any
+ * contract-signal heading is present and the brief is ambiguous or malformed.
+ * Never throws for a completely contract-free (legacy) description.
+ */
+export function compileExecutionContract(description) {
+    if (!description?.trim()) {
+        return { contract: null, acceptanceCriteria: null, hasContractHeadings: false };
+    }
+    const found = new Map();
+    for (const section of splitSections(description)) {
+        const key = CANONICAL_BY_NORMALIZED[normalizeHeadingName(section.name)];
+        if (!key)
+            continue;
+        const prev = found.get(key);
+        if (prev) {
+            throw new ExecutionContractError(`duplicate \`## ${EXECUTION_CONTRACT_HEADINGS[key]}\` section — keep exactly one and move the extra content into it`);
+        }
+        found.set(key, { name: section.name, key, body: section.body });
+    }
+    if (found.size === 0) {
+        return { contract: null, acceptanceCriteria: null, hasContractHeadings: false };
+    }
+    const hasSignal = SIGNAL_KEYS.some((key) => found.has(key));
+    if (!hasSignal) {
+        // `## Acceptance criteria` alone is the pre-contract Linear intake shape:
+        // keep extracting its raw text exactly as before, without validation.
+        const raw = found.get("acceptanceCriteria").body.trim();
+        return { contract: null, acceptanceCriteria: raw || null, hasContractHeadings: true };
+    }
+    const modeSection = requireSection(found, "executionMode");
+    const modeLines = modeSection.body.split("\n").map((l) => l.trim()).filter(Boolean);
+    if (modeLines.length !== 1) {
+        throw new ExecutionContractError(`\`## Builder execution mode\` must state exactly one execution mode (got ${modeLines.length} non-empty lines)`);
+    }
+    const executionMode = normalizeExecutionMode(modeLines[0]);
+    if (!executionMode) {
+        throw new ExecutionContractError(`unknown execution mode "${modeLines[0]}" — use exactly one of: ${EXECUTION_MODES.join(" | ")}`);
+    }
+    const nonGoals = parseNonGoals(requireSection(found, "nonGoals").body);
+    const exitPredicate = parseExitPredicate(requireSection(found, "exitPredicate").body);
+    const onePrStoppingPoint = parseOnePrStoppingPoint(requireSection(found, "onePrStoppingPoint").body);
+    const acceptanceCriteria = parseAcceptanceCriteria(requireSection(found, "acceptanceCriteria").body);
+    const contract = {
+        version: EXECUTION_CONTRACT_VERSION,
+        executionMode,
+        nonGoals,
+        exitPredicate,
+        onePrStoppingPoint,
+        acceptanceCriteria,
+    };
+    return {
+        contract,
+        acceptanceCriteria: renderContractAcceptanceCriteria(contract),
+        hasContractHeadings: true,
+    };
+}
+/** True when the description carries any Planner-signal heading (a contract ticket). */
+export function hasExecutionContractSignal(description) {
+    if (!description?.trim())
+        return false;
+    for (const section of splitSections(description)) {
+        const key = CANONICAL_BY_NORMALIZED[normalizeHeadingName(section.name)];
+        if (key && SIGNAL_KEYS.includes(key))
+            return true;
+    }
+    return false;
+}
+/**
+ * Resolve the issue-row fields derived from a ticket description: validate the
+ * contract when signal headings are present (throws) and fill a missing
+ * legacy acceptance-criteria value from the description. An explicitly
+ * provided non-empty value always wins — the contract never silently drops it.
+ */
+export function resolveIssueContractFields(description, explicitAcceptanceCriteria) {
+    const compiled = compileExecutionContract(description ?? null);
+    const explicit = explicitAcceptanceCriteria?.trim() ? explicitAcceptanceCriteria : null;
+    return {
+        executionContract: compiled.contract,
+        acceptanceCriteria: explicit ?? compiled.acceptanceCriteria ?? null,
+    };
+}
+/** Best-effort contract for read paths — legacy/unparseable descriptions read as null. */
+export function tryCompileContract(description) {
+    try {
+        return compileExecutionContract(description).contract;
+    }
+    catch {
+        return null;
+    }
+}

package/bundle/shared/dist/execution-contract.test.d.ts

@@ -0,0 +1,2 @@
+/** Planner-authored Linear ticket carrying every contract-v1 heading. */
+export declare const FULL_CONTRACT_DESCRIPTION = "Ship the frozen execution contract for Planner tickets.\n\n## Builder execution mode\nfeature\n\n## Non-goals\n- Selecting a playbook or reasoning about implementation architecture\n- Adding a generic workflow/schema editor\n\n## Exit predicate\nImporting a Planner-authored Linear ticket yields a versioned frozen execution contract visible in Dealer and both worker prompts.\n\n## One-PR stopping point\nStop after the contract compiles from ticket Markdown, persists/freezes with the Issue workflow, appears read-only in Issue Detail, and renders in developer/reviewer prompts.\n\n## Acceptance criteria\n- [ ] Full ticket imports into the exact structured schema\n  Evidence: shared compiler fixtures | run the compiler test | every field asserted\n- [ ] Legacy issues without headings still start\n  Evidence: migration tests | run the legacy suite | green\n";