@deftai/directive-core 0.91.0 → 0.93.0

package/dist/swarm/complete-cohort.js

@@ -2,6 +2,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { detectLifecycleFolder } from "../scope/decomposed-refs.js";
+import { classifyStoredDeliveryDisposition, } from "../scope/delivery-evidence.js";
 import { runTransition } from "../scope/transition.js";
 import { collectChildUris, collectPlanRefs, resolveVbriefRef } from "../scope/vbrief-ref.js";
 import { MAX_FIXPOINT_PASSES, TERMINAL_FOLDERS } from "./constants.js";
@@ -115,17 +116,38 @@ function parentCandidatesFrom(plan, vbriefDir) {
     }
     return out;
 }
-function completeStory(storyPath, vbriefDir, projectRoot, settled, dryRun) {
+function transitionOptionsFor(storyPath, delivery) {
+    if (delivery === null || delivery === undefined) {
+        return { verifier: "swarm:complete-cohort" };
+    }
+    const pathKey = resolve(storyPath);
+    const evidence = delivery.evidenceByPath?.get(pathKey) ??
+        delivery.evidenceByPath?.get(storyPath) ??
+        delivery.defaultEvidence ??
+        null;
+    return {
+        deliveryEvidence: evidence,
+        nonDeliveryDisposition: delivery.nonDeliveryDisposition,
+        assumeEvidenceValidated: delivery.assumeEvidenceValidated,
+        verifier: delivery.verifier ?? "swarm:complete-cohort",
+    };
+}
+function completeStory(args) {
+    const { storyPath, vbriefDir, projectRoot, settled, dryRun, delivery } = args;
     const folder = detectLifecycleFolder(storyPath);
     const relpath = rel(storyPath, projectRoot);
     if (folder !== null && TERMINAL_FOLDERS.includes(folder)) {
         settled.add(resolve(storyPath));
+        const plan = loadPlan(storyPath);
+        const disposition = folder === "completed" && plan !== null ? classifyStoredDeliveryDisposition(plan) : "unknown";
         return {
             kind: "story",
             path: relpath,
             action: "noop",
             ok: true,
-            detail: `already in ${folder}/`,
+            detail: folder === "completed"
+                ? `already in ${folder}/ (deliveryDisposition=${disposition})`
+                : `already in ${folder}/`,
         };
     }
     if (folder !== "active") {
@@ -147,7 +169,7 @@ function completeStory(storyPath, vbriefDir, projectRoot, settled, dryRun) {
             detail: "would complete active/ -> completed/",
         };
     }
-    const result = runTransition("complete", storyPath);
+    const result = runTransition("complete", storyPath, new Date(), transitionOptionsFor(storyPath, delivery));
     if (result.ok) {
         settled.add(resolve(join(vbriefDir, "completed", storyPath.split(/[/\\]/).pop() ?? "")));
     }
@@ -159,7 +181,8 @@ function completeStory(storyPath, vbriefDir, projectRoot, settled, dryRun) {
         detail: result.message,
     };
 }
-function completeParent(parentPath, vbriefDir, projectRoot, settled, dryRun) {
+function completeParent(args) {
+    const { parentPath, vbriefDir, projectRoot, settled, dryRun, delivery } = args;
     const folder = detectLifecycleFolder(parentPath);
     const relpath = rel(parentPath, projectRoot);
     if (folder !== null && TERMINAL_FOLDERS.includes(folder)) {
@@ -217,7 +240,7 @@ function completeParent(parentPath, vbriefDir, projectRoot, settled, dryRun) {
         }
         current = join(vbriefDir, "active", parentPath.split(/[/\\]/).pop() ?? "");
     }
-    const completeResult = runTransition("complete", current);
+    const completeResult = runTransition("complete", current, new Date(), transitionOptionsFor(current, delivery));
     if (completeResult.ok) {
         settled.add(resolve(join(vbriefDir, "completed", parentPath.split(/[/\\]/).pop() ?? "")));
     }
@@ -229,7 +252,12 @@ function completeParent(parentPath, vbriefDir, projectRoot, settled, dryRun) {
         detail: completeResult.message,
     };
 }
-export function sweepCohort(storyPaths, projectRoot, dryRun) {
+export function sweepCohort(storyPaths, projectRoot, dryRun, delivery) {
+    return sweepCohortWithArgs({ storyPaths, projectRoot, dryRun, delivery: delivery ?? null });
+}
+function sweepCohortWithArgs(args) {
+    const { storyPaths, projectRoot, dryRun } = args;
+    const delivery = args.delivery ?? null;
     let vbriefDir;
     try {
         vbriefDir = resolveLifecycleRoot(projectRoot);
@@ -275,7 +303,14 @@ export function sweepCohort(storyPaths, projectRoot, dryRun) {
                 }
             }
         }
-        result.stories.push(completeStory(storyPath, vbriefDir, projectRoot, settled, dryRun));
+        result.stories.push(completeStory({
+            storyPath,
+            vbriefDir,
+            projectRoot,
+            settled,
+            dryRun,
+            delivery,
+        }));
     }
     const finalized = new Set();
     let passes = 0;
@@ -294,7 +329,14 @@ export function sweepCohort(storyPaths, projectRoot, dryRun) {
             if (!allChildrenSettled(parentPlan, vbriefDir, settled, dryRun)) {
                 continue;
             }
-            const record = completeParent(candidate, vbriefDir, projectRoot, settled, dryRun);
+            const record = completeParent({
+                parentPath: candidate,
+                vbriefDir,
+                projectRoot,
+                settled,
+                dryRun,
+                delivery,
+            });
             result.parents.push(record);
             finalized.add(candidate);
             progressed = true;
@@ -403,7 +445,12 @@ export function completeCohort(args) {
         }
         return { exitCode: 2, stdout: "", stderr };
     }
-    const result = sweepCohort(paths, projectRoot, args.dryRun ?? false);
+    const result = sweepCohortWithArgs({
+        storyPaths: paths,
+        projectRoot,
+        dryRun: args.dryRun ?? false,
+        delivery: args.delivery ?? null,
+    });
     result.errors.push(...errors);
     if (args.emitJson) {
         return {

package/dist/swarm/finalize-cohort-cli.js

@@ -7,6 +7,7 @@ export function parseFinalizeCohortArgv(argv) {
     let repo = null;
     let projectRoot = ".";
     let baseBranch = "master";
+    let deliveryBranch = null;
     let label = null;
     let dryRun = false;
     let noCommit = false;
@@ -51,6 +52,13 @@ export function parseFinalizeCohortArgv(argv) {
             baseBranch = next;
             i += 1;
         }
+        else if (arg === "--delivery-branch" && next !== undefined) {
+            deliveryBranch = next;
+            i += 1;
+        }
+        else if (arg?.startsWith("--delivery-branch=")) {
+            deliveryBranch = arg.slice("--delivery-branch=".length);
+        }
         else if (arg === "--label" && next !== undefined) {
             label = next;
             i += 1;
@@ -77,6 +85,7 @@ export function parseFinalizeCohortArgv(argv) {
         repo,
         projectRoot,
         baseBranch,
+        deliveryBranch,
         label,
         dryRun,
         noCommit,

package/dist/swarm/finalize-cohort.d.ts

@@ -12,6 +12,8 @@ export interface FinalizeCohortResult {
     readonly commit_sha: string | null;
     readonly branch: string | null;
     readonly pr_url: string | null;
+    readonly delivery_branch: string | null;
+    readonly delivery_errors: readonly string[];
     readonly errors: readonly string[];
     readonly warnings: readonly string[];
     readonly ok: boolean;
@@ -21,7 +23,13 @@ export interface FinalizeCohortArgs {
     readonly storyTokens?: readonly string[];
     readonly repo?: string | null;
     readonly projectRoot?: string;
+    /**
+     * Swarm/PR base for the post-merge lifecycle sweep PR only.
+     * Distinct from plan.policy.deliveryBranch (#3041).
+     */
     readonly baseBranch?: string;
+    /** Override delivery branch for this run (defaults to policy/git default). */
+    readonly deliveryBranch?: string | null;
     readonly label?: string | null;
     readonly dryRun?: boolean;
     readonly noCommit?: boolean;

package/dist/swarm/finalize-cohort.js

@@ -1,8 +1,11 @@
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { evaluate as evaluateBranchPolicy } from "../branch/evaluate.js";
+import { extractIssueRef } from "../capacity/backfill.js";
 import { resolveLifecycleRoot } from "../layout/resolve.js";
+import { resolveDeliveryBranch } from "../policy/delivery-branch.js";
 import { defaultRunGh, fetchClosingIssuesReferences } from "../pr-protected-issues/gh.js";
+import { classifyStoredDeliveryDisposition, evidenceFromPrPayload, verifyDeliveryAncestry, } from "../scope/delivery-evidence.js";
 import { completeCohort } from "./complete-cohort.js";
 import { EXIT_CONFIG_ERROR, EXIT_GATE_FAILED, EXIT_OK } from "./constants.js";
 import { completedBriefReferencesIssue, resolveStories } from "./launch.js";
@@ -55,45 +58,73 @@ function parseRepo(repo) {
     }
     return { owner: repo.slice(0, slash), name: repo.slice(slash + 1) };
 }
-function fetchPrMergedAt(prNumber, repo, runGh) {
+function fetchPrDeliverySnapshot(prNumber, repo, deliveryBranch, runGh) {
     const parsed = parseRepo(repo);
     if (parsed === null) {
-        return { mergedAt: null, error: `invalid --repo value: ${JSON.stringify(repo)}` };
+        return { snapshot: null, error: `invalid --repo value: ${JSON.stringify(repo)}` };
     }
     const path = `repos/${parsed.owner}/${parsed.name}/pulls/${prNumber}`;
     const result = runGh(["gh", "api", path]);
     if (result.returncode !== 0) {
         return {
-            mergedAt: null,
+            snapshot: null,
             error: `gh api ${path} failed: ${result.stderr.trim() || result.stdout.trim()}`,
         };
     }
     try {
-        const parsed = JSON.parse(result.stdout);
-        if (parsed === null || typeof parsed !== "object") {
+        const body = JSON.parse(result.stdout);
+        if (body === null || typeof body !== "object") {
             return {
-                mergedAt: null,
+                snapshot: null,
                 error: `unexpected gh api response for PR #${prNumber}: not a JSON object`,
             };
         }
-        const payload = parsed;
+        const payload = body;
         const mergedAt = payload.merged_at;
-        if (mergedAt === null) {
-            return { mergedAt: null, error: `PR #${prNumber} is not merged yet.` };
+        if (mergedAt === null || typeof mergedAt !== "string" || mergedAt.length === 0) {
+            return { snapshot: null, error: `PR #${prNumber} is not merged yet.` };
         }
-        if (typeof mergedAt !== "string" || mergedAt.length === 0) {
-            return { mergedAt: null, error: `PR #${prNumber} is not merged yet.` };
-        }
-        return { mergedAt, error: null };
+        const base = payload.base;
+        const prBase = typeof base === "object" &&
+            base !== null &&
+            !Array.isArray(base) &&
+            typeof base.ref === "string"
+            ? String(base.ref)
+            : null;
+        const mergeCommitSha = typeof payload.merge_commit_sha === "string" && payload.merge_commit_sha.length > 0
+            ? payload.merge_commit_sha
+            : null;
+        const evidence = evidenceFromPrPayload(payload, prNumber, repo, deliveryBranch);
+        return {
+            snapshot: {
+                mergedAt,
+                prBase,
+                mergeCommitSha,
+                payload,
+                evidence,
+            },
+            error: null,
+        };
     }
     catch (exc) {
         const message = exc instanceof Error ? exc.message : String(exc);
         return {
-            mergedAt: null,
+            snapshot: null,
             error: `failed to parse gh api response for PR #${prNumber}: ${message}`,
         };
     }
 }
+/** Adapt swarm runText to the session GitRunner shape used by delivery-evidence. */
+function asGitRunner(runGit) {
+    return (projectRoot, args) => {
+        const result = runGit(["git", ...args], { cwd: projectRoot });
+        return {
+            code: result.returncode,
+            stdout: result.stdout,
+            stderr: result.stderr,
+        };
+    };
+}
 function fetchClosingIssues(prNumber, repo, runGh) {
     const parsed = parseRepo(repo);
     if (parsed === null) {
@@ -280,14 +311,34 @@ export function finalizeCohort(args) {
     const projectRoot = resolve(args.projectRoot ?? process.cwd());
     const runGh = args.runGh ?? defaultRunGh;
     const runGit = args.runGit ?? runText;
+    const gitRunner = asGitRunner(runGit);
     const prNumbers = [...(args.prNumbers ?? [])].sort((a, b) => a - b);
     const storyTokens = splitCsv(args.storyTokens ?? []);
     const repo = args.repo ?? process.env.GH_REPO ?? null;
+    // baseBranch is for the lifecycle sweep PR only — not delivery proof (#3041).
     const baseBranch = args.baseBranch ?? "master";
     const dryRun = args.dryRun ?? false;
     const noCommit = args.noCommit ?? false;
     const noOpenPr = args.noOpenPr ?? false;
     const errors = [];
+    const deliveryErrors = [];
+    // plan.policy.deliveryBranch (or git default) is SoT. CLI may only fill when policy is
+    // not typed — never redefine a typed delivery branch to an integration target (#3041).
+    const policyDelivery = resolveDeliveryBranch(projectRoot, gitRunner);
+    const cliDelivery = args.deliveryBranch !== null &&
+        args.deliveryBranch !== undefined &&
+        args.deliveryBranch.trim().length > 0
+        ? args.deliveryBranch.trim()
+        : null;
+    if (cliDelivery !== null && cliDelivery !== policyDelivery.branch) {
+        if (policyDelivery.source === "typed") {
+            errors.push(`--delivery-branch '${cliDelivery}' conflicts with plan.policy.deliveryBranch ` +
+                `'${policyDelivery.branch}'. Typed policy wins; do not redefine delivery via CLI (#3041).`);
+        }
+    }
+    const deliveryBranch = policyDelivery.source === "typed"
+        ? policyDelivery.branch
+        : (cliDelivery ?? policyDelivery.branch);
     if (!existsSync(projectRoot)) {
         return buildResponse({
             projectRoot,
@@ -300,6 +351,8 @@ export function finalizeCohort(args) {
             commitSha: null,
             branch: null,
             prUrl: null,
+            deliveryBranch,
+            deliveryErrors: [],
             errors: [`project root does not exist: ${projectRoot}`],
             warnings: [],
             ok: false,
@@ -319,6 +372,8 @@ export function finalizeCohort(args) {
             commitSha: null,
             branch: null,
             prUrl: null,
+            deliveryBranch,
+            deliveryErrors: [],
             errors: [`no xbrief/ directory under project root: ${projectRoot}`],
             warnings: [],
             ok: false,
@@ -327,27 +382,63 @@ export function finalizeCohort(args) {
         });
     }
     const closingIssues = new Set();
-    if (prNumbers.length > 0) {
+    /** Per-closing-issue delivery evidence so multi-PR cohorts do not collapse provenance (#3041). */
+    const evidenceByIssue = new Map();
+    const validatedPrs = [];
+    if (prNumbers.length > 0 && errors.length === 0) {
         if (repo === null || repo.length === 0) {
             errors.push("--repo OWNER/REPO is required when --pr is supplied (or set $GH_REPO).");
         }
         else {
             for (const prNumber of prNumbers) {
-                const merged = fetchPrMergedAt(prNumber, repo, runGh);
-                if (merged.error !== null) {
-                    errors.push(merged.error);
+                const fetched = fetchPrDeliverySnapshot(prNumber, repo, deliveryBranch, runGh);
+                if (fetched.error !== null || fetched.snapshot === null) {
+                    errors.push(fetched.error ?? `PR #${prNumber}: delivery snapshot unavailable`);
                     continue;
                 }
+                const snap = fetched.snapshot;
+                // base.ref must equal configured deliveryBranch — integration bases fail closed (#3041).
+                if (snap.prBase === null || snap.prBase.length === 0) {
+                    deliveryErrors.push(`PR #${prNumber}: missing base.ref; cannot verify delivery branch (#3041).`);
+                    continue;
+                }
+                if (snap.prBase !== deliveryBranch) {
+                    deliveryErrors.push(`PR #${prNumber}: base.ref '${snap.prBase}' is not the delivery branch ` +
+                        `'${deliveryBranch}'. Merged-to-integration is not delivery evidence (#3041). ` +
+                        `(Note: --base-branch only controls the lifecycle sweep PR target, not delivery.)`);
+                    continue;
+                }
+                if (snap.mergeCommitSha === null) {
+                    deliveryErrors.push(`PR #${prNumber}: missing merge_commit_sha; cannot prove delivery ancestry (#3041).`);
+                    continue;
+                }
+                // Refresh remote delivery ref and require merge commit ancestry (#3041).
+                const ancestry = verifyDeliveryAncestry(projectRoot, snap.mergeCommitSha, deliveryBranch, gitRunner);
+                if (!ancestry.ok) {
+                    deliveryErrors.push(`PR #${prNumber}: ${ancestry.error}`);
+                    continue;
+                }
+                validatedPrs.push(prNumber);
+                const prEvidence = {
+                    ...snap.evidence,
+                    deliveryBranch,
+                    deliveryCommit: ancestry.remoteTip,
+                    verifier: "swarm:finalize-cohort",
+                };
                 const closing = fetchClosingIssues(prNumber, repo, runGh);
                 if (closing.error !== null) {
                     errors.push(closing.error);
                 }
                 for (const issue of closing.issues) {
                     closingIssues.add(issue);
+                    evidenceByIssue.set(issue, prEvidence);
                 }
             }
         }
     }
+    if (deliveryErrors.length > 0) {
+        errors.push(...deliveryErrors);
+    }
     if (storyTokens.length === 0 && closingIssues.size === 0) {
         errors.push("empty cohort: pass --pr <numbers> and/or --stories <ids|paths>.");
     }
@@ -393,8 +484,33 @@ export function finalizeCohort(args) {
         const completedBrief = completedBriefReferencesIssue(projectRoot, issue);
         const issueClosed = completedBrief || fetchIssueClosed(issue, repo, runGh);
         if (completedBrief || issueClosed) {
+            let dispositionNote = "";
+            if (completedBrief) {
+                try {
+                    const completedDir = resolve(projectRoot, "xbrief", "completed");
+                    // Best-effort surface of legacy delivery disposition for completed briefs (#3041).
+                    if (existsSync(completedDir)) {
+                        for (const name of readdirSync(completedDir)) {
+                            if (!name.endsWith(".json"))
+                                continue;
+                            const raw = JSON.parse(readFileSync(resolve(completedDir, name), "utf8"));
+                            if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+                                continue;
+                            const plan = raw.plan;
+                            if (typeof plan !== "object" || plan === null || Array.isArray(plan))
+                                continue;
+                            const disposition = classifyStoredDeliveryDisposition(plan);
+                            dispositionNote = ` deliveryDisposition=${disposition}`;
+                            break;
+                        }
+                    }
+                }
+                catch {
+                    /* best-effort disposition surfacing for legacy completed records */
+                }
+            }
             const reason = completedBrief
-                ? "a completed brief already exists"
+                ? `a completed brief already exists${dispositionNote}`
                 : "the issue is already closed";
             warnings.push(`#${issue}: no active story references this closing issue; skipped (${reason}).`);
         }
@@ -417,17 +533,78 @@ export function finalizeCohort(args) {
             commitSha: null,
             branch: null,
             prUrl: null,
+            deliveryBranch,
+            deliveryErrors,
             errors,
             warnings,
             ok: cleanNoop,
             emitJson: args.emitJson ?? false,
             exitCode: cleanNoop
                 ? EXIT_OK
-                : errors.some((e) => e.includes("not merged"))
+                : errors.some((e) => e.includes("not merged") || e.includes("delivery"))
                     ? EXIT_GATE_FAILED
                     : EXIT_CONFIG_ERROR,
         });
     }
+    // When --pr was supplied, every PR must pass delivery validation before sweep (#3041).
+    if (prNumbers.length > 0 && validatedPrs.length !== prNumbers.length && errors.length > 0) {
+        return buildResponse({
+            projectRoot,
+            dryRun,
+            noCommit,
+            prNumbers,
+            storyPaths,
+            closingIssues: [...closingIssues],
+            sweep: null,
+            commitSha: null,
+            branch: null,
+            prUrl: null,
+            deliveryBranch,
+            deliveryErrors,
+            errors,
+            warnings,
+            ok: false,
+            emitJson: args.emitJson ?? false,
+            exitCode: EXIT_GATE_FAILED,
+        });
+    }
+    // Stories without PR-backed delivery evidence still hit the complete gate; if
+    // only --stories was supplied, complete-cohort fails closed for code-bearing
+    // scopes unless callers pass evidence (finalize requires --pr for delivery).
+    if (prNumbers.length === 0 && evidenceByIssue.size === 0) {
+        warnings.push("No --pr supplied: code-bearing stories require delivery evidence or " +
+            "will fail closed at scope:complete (#3041).");
+    }
+    // Bind each story path to the evidence of its closing-issue PR (no cohort-wide collapse).
+    const evidenceByPath = new Map();
+    for (const storyPath of storyPaths) {
+        try {
+            const raw = JSON.parse(readFileSync(storyPath, "utf8"));
+            if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+                continue;
+            }
+            const plan = raw.plan;
+            if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+                continue;
+            }
+            const [, issueNum] = extractIssueRef(plan);
+            if (issueNum !== null) {
+                const bound = evidenceByIssue.get(issueNum);
+                if (bound !== undefined) {
+                    evidenceByPath.set(resolve(storyPath), bound);
+                }
+            }
+        }
+        catch {
+            /* unreadable brief — complete gate fails closed later if code-bearing */
+        }
+    }
+    // Single-PR cohorts: every story inherits that PR's evidence when issue binding misses
+    // (operator --stories + one --pr is the common finalize path).
+    let defaultEvidence = null;
+    if (validatedPrs.length === 1 && evidenceByIssue.size > 0) {
+        defaultEvidence = evidenceByIssue.values().next().value ?? null;
+    }
     let commitSha = null;
     let branch = null;
     let prUrl = null;
@@ -447,11 +624,21 @@ export function finalizeCohort(args) {
             }
         }
     }
+    const hasDelivery = evidenceByPath.size > 0 || defaultEvidence !== null;
     const sweepResult = completeCohort({
         stories: storyPaths,
         projectRoot,
         dryRun,
         emitJson: false,
+        delivery: hasDelivery
+            ? {
+                evidenceByPath,
+                defaultEvidence,
+                // Ancestry already verified above; avoid double remote fetch on each story.
+                assumeEvidenceValidated: true,
+                verifier: "swarm:finalize-cohort",
+            }
+            : null,
     });
     if (sweepResult.exitCode !== 0) {
         errors.push("cohort completion sweep failed.");
@@ -466,6 +653,8 @@ export function finalizeCohort(args) {
             commitSha: null,
             branch: null,
             prUrl: null,
+            deliveryBranch,
+            deliveryErrors,
             errors,
             warnings,
             ok: false,
@@ -503,6 +692,8 @@ export function finalizeCohort(args) {
         commitSha,
         branch,
         prUrl,
+        deliveryBranch,
+        deliveryErrors,
         errors,
         warnings,
         ok,
@@ -522,6 +713,8 @@ function buildResponse(input) {
         commit_sha: input.commitSha,
         branch: input.branch,
         pr_url: input.prUrl,
+        delivery_branch: input.deliveryBranch,
+        delivery_errors: input.deliveryErrors,
         errors: input.errors,
         warnings: input.warnings,
         ok: input.ok,
@@ -539,6 +732,9 @@ function buildResponse(input) {
             `(${input.storyPaths.length} stor${input.storyPaths.length === 1 ? "y" : "ies"})`,
         `  Project root: ${input.projectRoot}`,
     ];
+    if (input.deliveryBranch !== null) {
+        lines.push(`  Delivery branch: ${input.deliveryBranch}`);
+    }
     if (input.prNumbers.length > 0) {
         lines.push(`  PRs: ${input.prNumbers.map((n) => `#${n}`).join(", ")}`);
     }

package/dist/user-config/experimental-rules.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Safe USER.md Experimental Rules toggle (#46).
+ *
+ * Pure string helpers that add/remove only the three canonical meta-philosophy
+ * reference lines (SOUL / morals / code-field). Personal and Defaults section
+ * bodies are never rewritten — only the `## Experimental Rules` region changes.
+ *
+ * Detection matches lines under `## Experimental Rules` that contain the deposit
+ * path (`meta/SOUL.md`, …); enable writes the canonical setup-skill bullet.
+ * Custom bullets for other topics in the same section are preserved.
+ */
+export type ExperimentalMetaId = "soul" | "morals" | "code-field";
+export interface ExperimentalMetaEntry {
+    readonly id: ExperimentalMetaId;
+    /** Path fragment matched in USER.md lines (e.g. `meta/SOUL.md`). */
+    readonly path: string;
+    /** Canonical bullet written when enabling. */
+    readonly line: string;
+}
+/** Canonical Experimental Rules entries (setup Phase 1 steps 5a–5c). */
+export declare const EXPERIMENTAL_META_ENTRIES: readonly ExperimentalMetaEntry[];
+export type ExperimentalRulesState = Record<ExperimentalMetaId, boolean>;
+/**
+ * Parse on/off state for the three experimental meta entries.
+ * A path is ON only when a line under `## Experimental Rules` mentions it —
+ * mentions in Personal/Defaults/prose do not count (writes are section-scoped).
+ */
+export declare function parseExperimentalRulesState(userMdText: string): ExperimentalRulesState;
+/**
+ * Apply desired Experimental Rules on/off state.
+ *
+ * - Only mutates the `## Experimental Rules` region (or inserts/removes it).
+ * - Personal / Defaults content is left byte-identical outside that region.
+ * - Enabling uses the canonical setup-skill lines; disabling drops path matches.
+ * - Custom non-meta bullets under the section are preserved.
+ * - When all three are off and no custom bullets remain, the section is removed.
+ */
+export declare function applyExperimentalRulesState(userMdText: string, desired: ExperimentalRulesState): string;
+/**
+ * Toggle a single experimental meta entry; leave the other two unchanged.
+ */
+export declare function setExperimentalRule(userMdText: string, id: ExperimentalMetaId, enabled: boolean): string;
+//# sourceMappingURL=experimental-rules.d.ts.map