@deftai/directive-core 0.90.0 → 0.92.0

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/triage/welcome/index.d.ts

@@ -3,5 +3,5 @@ export { type DefaultModeOptions, formatWelcomeCommand, normalizeTaskPrefix, run
 export { DEFAULT_ONBOARD_PRESET, type OnboardOptions, type OnboardOutcome, runOnboardMode, } from "./onboard.js";
 export { candidatesLogPath, classifyOnboarding, detectPriorState, type PriorState, pendingDecisionsNudgeLine, } from "./prior-state.js";
 export { computeSummary, emitOneliner, formatOneLiner, formatSummary, type SummaryResult, } from "./summary.js";
-export { appendAuditEntry, previewWipRelief, type ReliefPreview, subscriptionPreset, writeTriageScope, writeWipCap, } from "./writers.js";
+export { appendAuditEntry, previewWipRelief, type ReliefPreview, subscriptionPreset, writeTriageScope, writeWipCap, writeWipCapDecision, } from "./writers.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/triage/welcome/index.js

@@ -3,5 +3,5 @@ export { formatWelcomeCommand, normalizeTaskPrefix, runDefaultMode, } from "./de
 export { DEFAULT_ONBOARD_PRESET, runOnboardMode, } from "./onboard.js";
 export { candidatesLogPath, classifyOnboarding, detectPriorState, pendingDecisionsNudgeLine, } from "./prior-state.js";
 export { computeSummary, emitOneliner, formatOneLiner, formatSummary, } from "./summary.js";
-export { appendAuditEntry, previewWipRelief, subscriptionPreset, writeTriageScope, writeWipCap, } from "./writers.js";
+export { appendAuditEntry, previewWipRelief, subscriptionPreset, writeTriageScope, writeWipCap, writeWipCapDecision, } from "./writers.js";
 //# sourceMappingURL=index.js.map

package/dist/triage/welcome/onboard.js

@@ -7,7 +7,7 @@ import { DEFAULT_WIP_CAP, SUBSCRIPTION_PRESETS, TRIAGE_SKILL_PATH } from "./cons
 import { formatWelcomeCommand } from "./default-mode.js";
 import { detectPriorState } from "./prior-state.js";
 import { emitOneliner } from "./summary.js";
-import { previewWipRelief, subscriptionPreset, writeTriageScope, writeWipCap } from "./writers.js";
+import { previewWipRelief, subscriptionPreset, writeTriageScope, writeWipCap, writeWipCapDecision, } from "./writers.js";
 /** Default triage-scope preset applied when `--onboard` is run without `--preset`. */
 export const DEFAULT_ONBOARD_PRESET = "small";
 function failure(exitCode) {
@@ -66,8 +66,14 @@ export function runOnboardMode(projectRoot, options = {}) {
     const [triageScopeChanged] = writeTriageScope(projectRoot, rules, { presetLabel: preset });
     let wipCapChanged = false;
     if (wipCap !== null) {
+        // writeWipCap also records out-of-band decision-provenance (#1694).
         [wipCapChanged] = writeWipCap(projectRoot, wipCap);
     }
+    else {
+        // Accepting the framework default is a real onboarding decision: record it
+        // without materializing plan.policy.wipCap (#1694 / #1186 D1 / #1250).
+        writeWipCapDecision(projectRoot, { acceptedDefault: true });
+    }
     emitOneliner(projectRoot, {
         writeHistory: options.writeHistory !== false,
         now: options.now,

package/dist/triage/welcome/prior-state.d.ts

@@ -3,7 +3,14 @@ export interface PriorState {
     readonly triageScopeSummary: string;
     readonly cacheEmpty: boolean;
     readonly cacheEntryCount: number;
+    /** True when plan.policy.wipCap is materialized (deliberate non-default override). */
     readonly wipCapSet: boolean;
+    /**
+     * True when an out-of-band decision-provenance marker records that the
+     * operator considered WIP cap (#1694). Orthogonal to {@link wipCapSet}:
+     * accepting the framework default sets this without materializing the field.
+     */
+    readonly wipCapDecided: boolean;
     readonly wipCap: number;
     readonly wipCount: number;
     readonly auditLogPresent: boolean;

package/dist/triage/welcome/prior-state.js

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { hasArtifactSuffix, resolveAuditPath, resolveLifecycleRoot, resolveProjectDefinitionPath, } from "../../layout/resolve.js";
-import { readPlanPolicy } from "../../policy/plan-extensions.js";
+import { readPlanOnboarding, readPlanPolicy } from "../../policy/plan-extensions.js";
 import { resolveCandidatesLogPath } from "../cache-path.js";
 import { CACHE_DIR_NAME, CACHE_SOURCE, DEFAULT_WIP_CAP, SUBSCRIPTION_PRESETS, WIP_LIFECYCLE_DIRS, } from "./constants.js";
 function loadProjectDefinition(projectRoot) {
@@ -152,6 +152,17 @@ export function detectPriorState(projectRoot) {
             wipCapSet = true;
         }
     }
+    // Decision-provenance is out-of-band from the value field (#1694 / #1695).
+    // Accepting the framework default records wipCapDecided without materializing
+    // plan.policy.wipCap. A materialized override also counts as a decision.
+    const onboarding = readPlanOnboarding(plan);
+    let wipCapDecided = false;
+    if (typeof onboarding === "object" && onboarding !== null && !Array.isArray(onboarding)) {
+        wipCapDecided = onboarding.wipCapDecided === true;
+    }
+    if (wipCapSet) {
+        wipCapDecided = true;
+    }
     const [scopeSet, scopeLabel] = summarizeScope(scopeRules);
     const cacheCount = countCacheEntries(projectRoot);
     return {
@@ -160,6 +171,7 @@ export function detectPriorState(projectRoot) {
         cacheEmpty: cacheCount === 0,
         cacheEntryCount: cacheCount,
         wipCapSet,
+        wipCapDecided,
         wipCap,
         wipCount: countWip(projectRoot),
         auditLogPresent: existsSync(candidatesLogPath(projectRoot)),
@@ -167,10 +179,12 @@ export function detectPriorState(projectRoot) {
     };
 }
 export function classifyOnboarding(state) {
+    // wipCap onboarding completeness is decision-provenance, not field presence
+    // (#1694). Omission of plan.policy.wipCap with wipCapDecided=true is fully set up.
     const signals = {
         "candidates.jsonl": state.auditLogPresent,
         triageScope: state.triageScopeSet,
-        wipCap: state.wipCapSet,
+        wipCap: state.wipCapDecided,
     };
     const present = Object.keys(signals).filter((k) => signals[k]);
     const missing = Object.keys(signals).filter((k) => !signals[k]);

package/dist/triage/welcome/writers.d.ts

@@ -3,6 +3,16 @@ export declare function writeTriageScope(projectRoot: string, rules: Array<Recor
     presetLabel: string;
     actor?: string;
 }): [boolean, string];
+/**
+ * Record out-of-band WIP-cap decision provenance without materializing
+ * `plan.policy.wipCap` (#1694). Accepting the framework default is a real
+ * onboarding decision and MUST be representable without writing the value field.
+ */
+export declare function writeWipCapDecision(projectRoot: string, options?: {
+    actor?: string;
+    acceptedDefault?: boolean;
+    value?: number | null;
+}): [boolean, string];
 export declare function writeWipCap(projectRoot: string, wipCap: number, options?: {
     actor?: string;
 }): [boolean, string];

package/dist/triage/welcome/writers.js

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, s
 import { dirname, join, resolve } from "node:path";
 import { containedWrite } from "../../fs/contained-write.js";
 import { hasArtifactSuffix, resolveLifecycleFolder, resolveProjectDefinitionPath, } from "../../layout/resolve.js";
-import { migrateLegacyPolicyKey, PLAN_POLICY_KEY } from "../../policy/plan-extensions.js";
+import { migrateLegacyPolicyKey, PLAN_ONBOARDING_KEY, PLAN_POLICY_KEY, } from "../../policy/plan-extensions.js";
 import { projectDefinitionMutationLock } from "../../vbrief-build/project-definition-io.js";
 import { AUDIT_LOG_REL_PATH, DEFAULT_RELIEF_AGE_DAYS, DEFAULT_WIP_CAP, SUBSCRIPTION_PRESETS, WELCOME_AUDIT_TAG, } from "./constants.js";
 function projectDefinitionPath(projectRoot) {
@@ -97,6 +97,57 @@ export function writeTriageScope(projectRoot, rules, options = { presetLabel: "c
         return [changed, auditEntry];
     });
 }
+/**
+ * Record out-of-band WIP-cap decision provenance without materializing
+ * `plan.policy.wipCap` (#1694). Accepting the framework default is a real
+ * onboarding decision and MUST be representable without writing the value field.
+ */
+export function writeWipCapDecision(projectRoot, options = {}) {
+    return projectDefinitionMutationLock(projectRoot, () => {
+        const path = projectDefinitionPath(projectRoot);
+        if (!existsSync(path))
+            throw new Error(`PROJECT-DEFINITION not found at ${path}`);
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
+        }
+        const data = parsed;
+        const plan = data.plan;
+        if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+            throw new Error("PROJECT-DEFINITION 'plan' is not an object");
+        }
+        const planRec = plan;
+        const previous = planRec[PLAN_ONBOARDING_KEY];
+        const previousRec = typeof previous === "object" && previous !== null && !Array.isArray(previous)
+            ? previous
+            : {};
+        const alreadyDecided = previousRec.wipCapDecided === true;
+        const acceptedDefault = options.acceptedDefault ?? true;
+        const actor = options.actor ?? WELCOME_AUDIT_TAG;
+        // Rebuild cleanly so acceptedDefault=true never retains a prior custom value.
+        const next = {
+            wipCapDecided: true,
+            acceptedDefault,
+            decidedAt: utcIso(),
+            actor,
+        };
+        if (!acceptedDefault && options.value !== undefined && options.value !== null) {
+            next.value = options.value;
+        }
+        planRec[PLAN_ONBOARDING_KEY] = next;
+        atomicWrite(projectRoot, path, data);
+        const changed = !alreadyDecided || previousRec.acceptedDefault !== acceptedDefault;
+        const auditEntry = [
+            `actor=${actor}`,
+            `field=${PLAN_ONBOARDING_KEY}.wipCapDecided`,
+            "value=true",
+            `acceptedDefault=${acceptedDefault ? "true" : "false"}`,
+            `changed=${changed ? "true" : "false"}`,
+        ].join(" ");
+        appendAuditEntry(projectRoot, auditEntry);
+        return [changed, auditEntry];
+    });
+}
 export function writeWipCap(projectRoot, wipCap, options = {}) {
     if (!Number.isInteger(wipCap) || wipCap < 1) {
         throw new Error(`wipCap must be a positive int, got ${JSON.stringify(wipCap)}`);
@@ -125,8 +176,27 @@ export function writeWipCap(projectRoot, wipCap, options = {}) {
         const policyRec = policy;
         const previous = policyRec.wipCap;
         const actor = options.actor ?? WELCOME_AUDIT_TAG;
+        // Always record decision-provenance out-of-band (#1694). Accepting the
+        // default omits the value field but still marks the decision complete.
+        // Rebuild the onboarding record (do not spread a prior custom `value` into
+        // an acceptedDefault=true payload -- that is contradictory provenance).
+        const acceptedDefault = wipCap === DEFAULT_WIP_CAP;
+        const onboardingRecord = {
+            wipCapDecided: true,
+            acceptedDefault,
+            decidedAt: utcIso(),
+            actor,
+        };
+        if (!acceptedDefault) {
+            onboardingRecord.value = wipCap;
+        }
+        planRec[PLAN_ONBOARDING_KEY] = onboardingRecord;
         if (previous === undefined && wipCap === DEFAULT_WIP_CAP) {
-            return [false, ""];
+            atomicWrite(projectRoot, path, data);
+            const auditEntry = `actor=${actor} field=${PLAN_ONBOARDING_KEY}.wipCapDecided value=true ` +
+                `acceptedDefault=true changed=true note=default-no-materialize`;
+            appendAuditEntry(projectRoot, auditEntry);
+            return [true, auditEntry];
         }
         if (previous !== undefined && wipCap === DEFAULT_WIP_CAP) {
             delete policyRec.wipCap;

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