@deftai/directive-core 0.90.0 → 0.91.0

package/dist/scope/main.js

@@ -3,6 +3,7 @@ import { dirname, join } from "node:path";
 import { maybeRunStalenessTickler } from "../staleness-tickler/run.js";
 import { reconcileUmbrellas, renderUmbrellasReport } from "../vbrief-reconcile/umbrellas.js";
 import { canonicalLogPath, readAll } from "./audit-log.js";
+import { batchPromote } from "./batch-promote.js";
 import { TRANSITIONS } from "./constants.js";
 import { batchDemote, DEFAULT_OLDER_THAN_DAYS, demoteOne, resolveDemoteFilePath, resolveFilePath, resolveProjectRootStrict, } from "./demote.js";
 import { completedPathForScopeMove, findOpenUmbrellaReferences, renderOpenUmbrellaWarning, } from "./open-umbrella-warning.js";
@@ -10,12 +11,13 @@ import { resolveProjectRoot } from "./project-context.js";
 import { recordWipCapOverride, runTransition } from "./transition.js";
 import { findByDecisionId, isAlreadyUndone, REVERSIBLE_ACTIONS, undoBatch, undoOne, } from "./undo.js";
 import { checkWipCap, formatWipCapRefusal } from "./wip-cap-check.js";
-const LIFECYCLE_USAGE_STDERR = "usage: scope_lifecycle.py [-h] [--project-root PROJECT_ROOT] [--force]\n" +
+const LIFECYCLE_USAGE_STDERR = "usage: scope_lifecycle.py [-h] [--project-root PROJECT_ROOT] [--force] [--batch]\n" +
     "                          {activate,block,cancel,complete,fail,promote,restore,unblock}\n" +
-    "                          file\n" +
-    "scope_lifecycle.py: error: the following arguments are required: action, file\n";
+    "                          [file ...]\n" +
+    "scope_lifecycle.py: error: the following arguments are required: action, file\n" +
+    "(promote --batch may omit file and promotes all proposed/ scopes; #3011)\n";
 function parseLifecycleArgv(argv) {
-    if (argv.length < 2) {
+    if (argv.length < 1) {
         return { args: null, error: "usage" };
     }
     const action = argv[0] ?? "";
@@ -25,6 +27,8 @@ function parseLifecycleArgv(argv) {
     let file = "";
     let projectRoot;
     let force = false;
+    let batch = false;
+    const batchFiles = [];
     for (let i = 1; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === undefined) {
@@ -33,6 +37,9 @@ function parseLifecycleArgv(argv) {
         if (arg === "--force") {
             force = true;
         }
+        else if (arg === "--batch") {
+            batch = true;
+        }
         else if (arg === "--project-root") {
             projectRoot = argv[i + 1];
             i += 1;
@@ -40,13 +47,36 @@ function parseLifecycleArgv(argv) {
         else if (arg?.startsWith("--project-root=")) {
             projectRoot = arg.slice("--project-root=".length);
         }
-        else if (!arg.startsWith("-") && file.length === 0) {
-            file = arg;
+        else if (!arg.startsWith("-")) {
+            if (batch) {
+                batchFiles.push(arg);
+            }
+            else if (file.length === 0) {
+                file = arg;
+            }
+            else {
+                return { args: null, error: "usage" };
+            }
         }
         else {
             return { args: null, error: "usage" };
         }
     }
+    if (batch) {
+        if (action !== "promote") {
+            return { args: null, error: "usage" };
+        }
+        return {
+            args: {
+                action,
+                file: file.length > 0 ? file : "",
+                projectRoot,
+                force,
+                batch: true,
+                batchFiles: batchFiles.length > 0 ? batchFiles : file.length > 0 ? [file] : [],
+            },
+        };
+    }
     if (file.length === 0) {
         return { args: null, error: "usage" };
     }
@@ -61,7 +91,28 @@ export function lifecycleMain(argv) {
         }
         return 2;
     }
-    const { action, file, projectRoot, force } = parsed.args;
+    const { action, file, projectRoot, force, batch, batchFiles } = parsed.args;
+    if (batch === true && action === "promote") {
+        const result = batchPromote({
+            files: batchFiles && batchFiles.length > 0 ? batchFiles : undefined,
+            force: force === true,
+            projectRoot,
+        });
+        for (const line of result.messages) {
+            process.stdout.write(`${line}\n`);
+        }
+        for (const line of result.skipped) {
+            process.stdout.write(`  skipped: ${line}\n`);
+        }
+        if (!result.ok && result.exitCode !== 0) {
+            for (const line of result.messages) {
+                if (line.startsWith("ERROR:") || line.includes("WIP cap")) {
+                    process.stderr.write(`${line}\n`);
+                }
+            }
+        }
+        return result.exitCode;
+    }
     const [filePath, error] = resolveFilePath(file, projectRoot);
     if (error !== null || filePath === null) {
         process.stderr.write(`Error: ${error}\n`);

package/dist/scope/wip-cap-check.d.ts

@@ -7,5 +7,11 @@ export interface WipCapCheck {
 }
 /** Resolve WIP cap and decide if promotion is allowed (#1124). */
 export declare function checkWipCap(projectRoot: string, force?: boolean): WipCapCheck;
+/**
+ * WIP check for promoting `additional` scopes in one batch (#3011).
+ * Single promote is `additional = 1` (same as historic count >= cap refuse).
+ * Batch of N refuses when `count + N > cap` unless `--force`.
+ */
+export declare function checkWipCapForAdditional(projectRoot: string, additional: number, force?: boolean): WipCapCheck;
 export declare function formatWipCapRefusal(check: WipCapCheck): string;
 //# sourceMappingURL=wip-cap-check.d.ts.map

package/dist/scope/wip-cap-check.js

@@ -1,10 +1,21 @@
 import { countVbriefWip, resolveWipCap } from "../policy/wip.js";
 /** Resolve WIP cap and decide if promotion is allowed (#1124). */
 export function checkWipCap(projectRoot, force = false) {
+    return checkWipCapForAdditional(projectRoot, 1, force);
+}
+/**
+ * WIP check for promoting `additional` scopes in one batch (#3011).
+ * Single promote is `additional = 1` (same as historic count >= cap refuse).
+ * Batch of N refuses when `count + N > cap` unless `--force`.
+ */
+export function checkWipCapForAdditional(projectRoot, additional, force = false) {
     const capResult = resolveWipCap(projectRoot);
     const cap = capResult.cap;
     const count = countVbriefWip(projectRoot);
-    const overCap = count >= cap;
+    const add = Math.max(0, Math.floor(additional));
+    // Single-promote parity: refuse when already at/over cap before adding one.
+    // Batch: refuse when current + additional would exceed the cap.
+    const overCap = add <= 1 ? count >= cap : count + add > cap;
     if (!overCap) {
         return { allowed: true, cap, count, source: capResult.source, forceOverride: false };
     }
@@ -18,6 +29,7 @@ export function formatWipCapRefusal(check) {
         "Either:\n" +
         "  task scope:demote <existing>                              # return one to proposed/\n" +
         "  task scope:demote --batch --older-than-days 30            # bulk relief (D9 folded into D1)\n" +
-        "  task scope:promote <file> --force                          # override (logged)");
+        "  task scope:promote <file> --force                          # override (logged)\n" +
+        "  task scope:promote --batch --force                         # batch override (#3011)");
 }
 //# sourceMappingURL=wip-cap-check.js.map

package/dist/session/session-start.d.ts

@@ -1,4 +1,5 @@
 import { type EnvironmentContext } from "../platform/shell-context.js";
+import { type ProbeScmReadinessOptions, type ScmReadinessReport } from "../scm/readiness.js";
 import { type ResolveUserMdResult } from "../user-config/resolve-user-md.js";
 import type { GitRunner } from "./git.js";
 import { type ReleaseAvailabilityProbeOptions } from "./release-availability.js";
@@ -86,6 +87,12 @@ export interface SessionStartOptions {
     readonly allowOptionalNetwork?: boolean;
     /** Process env for network opt-in resolution (tests inject). */
     readonly env?: NodeJS.ProcessEnv;
+    /**
+     * #2275: SCM tooling + auth readiness probe for mismatched/headless envs.
+     * Defaults to probeScmReadiness; shallow on hot path, deep when optional
+     * network is enabled. Inject in tests.
+     */
+    readonly probeScm?: (options: ProbeScmReadinessOptions) => ScmReadinessReport;
 }
 /** Format preferred `session:start` recovery command for cold vs re-arm (#2992). */
 export declare function formatSessionStartRecoveryCommand(tier?: SessionCeremonyTier): string;

package/dist/session/session-start.js

@@ -9,6 +9,7 @@ import { humanMergeDisclosureLine, resolveHumanMergePolicy, } from "../policy/re
 import { resolvePolicy } from "../policy/resolve.js";
 import { maybeFormatProductSignalConsentPrompt } from "../product-signal/consent-prompt.js";
 import { formatFrameworkCommand } from "../render/framework-commands.js";
+import { formatScmReadinessLines, probeScmReadiness, scmReadinessToDict, } from "../scm/readiness.js";
 import { maybeRunStalenessTickler } from "../staleness-tickler/run.js";
 import { runDefaultMode } from "../triage/welcome/default-mode.js";
 import { resolveUserMdPath } from "../user-config/resolve-user-md.js";
@@ -292,6 +293,44 @@ export function defaultBranchSync(projectRoot, runGit = defaultGitRunner) {
     }
     return { branch, upstream, ahead, behind, warning };
 }
+/**
+ * Resolve SCM readiness for session orientation (#2275).
+ * Shallow by default (PATH + auth status); deep when optional network is on.
+ * Never throws — session:start must not hard-block on SCM absence.
+ */
+function resolveSessionScmReadiness(options, allowOptionalNetwork) {
+    const probe = options.probeScm ?? probeScmReadiness;
+    try {
+        return probe({
+            depth: allowOptionalNetwork ? "deep" : "shallow",
+            env: options.env,
+        });
+    }
+    catch {
+        return {
+            ready: false,
+            binary: null,
+            binaryPath: null,
+            authState: "unknown",
+            githubAuthMode: "host-gh",
+            runtimeMode: "local-unsandboxed",
+            injectedTokenPresent: false,
+            depth: allowOptionalNetwork ? "deep" : "shallow",
+            detail: "SCM readiness probe failed unexpectedly; treating SCM-dependent gates as skipped",
+            remediation: null,
+            skippedGates: [
+                "triage:queue",
+                "issue:ingest",
+                "pr:*",
+                "reconcile:issues",
+                "cache:fetch-all",
+                "scm:*",
+            ],
+            login: null,
+            failureKind: "probe_error",
+        };
+    }
+}
 function runReadOnlySessionStart(projectRoot, options, instant, environment) {
     const lines = [];
     const resolveUserMd = options.resolveUserMd ?? ((root) => resolveUserMdPath({ projectRoot: root }));
@@ -301,9 +340,12 @@ function runReadOnlySessionStart(projectRoot, options, instant, environment) {
     const userMdLine = userMd.found
         ? `USER.md resolved (${userMd.rung}): ${safePath}`
         : safeDiagnostic;
+    // #2275: report SCM availability even on read-only alignment (shallow; no network).
+    const scm = resolveSessionScmReadiness(options, false);
     lines.push(READ_ONLY_ALIGNMENT_MESSAGE);
     lines.push(userMdLine);
     lines.push(formatEnvironmentContext(environment));
+    lines.push(...formatScmReadinessLines(scm));
     const resultPayload = {
         ready: true,
         exit_code: 0,
@@ -324,6 +366,7 @@ function runReadOnlySessionStart(projectRoot, options, instant, environment) {
             diagnostic: userMd.diagnostic,
         },
         environment: environmentContextToDict(environment),
+        scm: scmReadinessToDict(scm),
         message: READ_ONLY_RESULT_MESSAGE,
     };
     return { code: 0, payload: resultPayload, lines };
@@ -364,10 +407,13 @@ function runSessionRearm(projectRoot, options, instant, environment) {
         ? `USER.md resolved (${userMd.rung}): ${safePath}`
         : safeDiagnostic;
     const alignmentMessage = `${READ_ONLY_ALIGNMENT_MESSAGE} ${userMdLine}`;
+    // #2275: re-arm still reports SCM state (shallow; no network).
+    const scm = resolveSessionScmReadiness(options, false);
     const lines = [
         READ_ONLY_ALIGNMENT_MESSAGE,
         userMdLine,
         formatEnvironmentContext(environment),
+        ...formatScmReadinessLines(scm),
         REARM_SKIPPED_FAT_PATH_MESSAGE,
     ];
     // Light branch-policy disclosure (local only) so re-arm still surfaces policy state.
@@ -484,6 +530,7 @@ function runSessionRearm(projectRoot, options, instant, environment) {
                 diagnostic: userMd.diagnostic,
             },
             environment: environmentContextToDict(environment),
+            scm: scmReadinessToDict(scm),
             message: code === 0 ? "session ritual re-armed" : "session ritual re-arm failed",
         },
         lines,
@@ -594,6 +641,12 @@ export function runSessionStart(projectRoot, options = {}) {
         stepTimings.push({ name: "alignment", duration_ms: 0, skipped: true });
     }
     lines.push(formatEnvironmentContext(environment));
+    // #2275: SCM tooling + auth readiness — shallow on hot path, deep with --with-network.
+    // Never fails session:start; reports which SCM-dependent gates are skipped.
+    const scmStepStarted = performance.now();
+    const scm = resolveSessionScmReadiness(options, allowOptionalNetwork);
+    lines.push(...formatScmReadinessLines(scm));
+    stepTimings.push({ name: "scm_readiness", duration_ms: elapsedMs(scmStepStarted) });
     if (!quickSteps.branch_policy) {
         const stepStarted = performance.now();
         const result = resolvePolicy(projectRoot);
@@ -793,6 +846,7 @@ export function runSessionStart(projectRoot, options = {}) {
             diagnostic: userMd.diagnostic,
         },
         environment: environmentContextToDict(environment),
+        scm: scmReadinessToDict(scm),
         message: code === 0 ? "session ritual recorded" : "session ritual failed",
     };
     // #2994: local process-cost event (best-effort; never blocks ceremony).

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.90.0",
+  "version": "0.91.0",
   "description": "TypeScript engine core for the Directive framework.",
   "license": "MIT",
   "type": "module",
@@ -334,8 +334,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.90.0",
-    "@deftai/directive-types": "^0.90.0",
+    "@deftai/directive-content": "^0.91.0",
+    "@deftai/directive-types": "^0.91.0",
     "archiver": "^8.0.0"
   },
   "scripts": {