@deftai/directive-core 0.68.1 → 0.70.0

package/dist/resolution/skew-policy.js

@@ -0,0 +1,120 @@
+/**
+ * Three-band engine-vs-pin skew policy for the resolution spine (#2264, #2199).
+ *
+ * Content is always forward-migrated (`update`) before any gate runs; this
+ * policy governs whether a globally-reachable engine that differs from the pin
+ * may be used, and how loudly:
+ *
+ * - `engine == pin`                        -> proceed silently (trace only).
+ * - `engine > pin` within the skew window  -> proceed, emit a loud delta, `update` first.
+ * - `engine > pin` beyond the window       -> fail closed non-interactively (require
+ *                                              `--accept-engine-jump`; prompt when interactive).
+ *                                              `DEFT_ACCEPT_ENGINE_SKEW=1` is the CI escape.
+ * - `engine < pin`                         -> reject the global, fall through the ladder.
+ */
+import { compareSemver, parseSemver } from "./pin.js";
+/** Default skew window pre-1.0, measured in minor versions. */
+export const DEFAULT_ENGINE_SKEW_WINDOW = 3;
+/** Environment variable that acts as the CI / non-interactive escape hatch. */
+export const ACCEPT_ENGINE_SKEW_ENV = "DEFT_ACCEPT_ENGINE_SKEW";
+function resolveWindow(opts) {
+    const raw = opts.engineSkewWindow;
+    if (typeof raw === "number" && Number.isInteger(raw) && raw >= 0)
+        return raw;
+    return DEFAULT_ENGINE_SKEW_WINDOW;
+}
+function escapeHatchActive(opts) {
+    if (opts.acceptEngineJump === true)
+        return true;
+    const env = opts.env ?? process.env;
+    return env[ACCEPT_ENGINE_SKEW_ENV] === "1";
+}
+/**
+ * Classify the `engine > pin` skew band. Pre-1.0 (pin major 0) the window is
+ * measured in minors; post-1.0 the window collapses to "same major".
+ */
+function classifyAheadBand(engine, pin, window) {
+    const [engineMajor, engineMinor] = engine;
+    const [pinMajor, pinMinor] = pin;
+    if (pinMajor === 0) {
+        if (engineMajor > 0)
+            return "beyond-window";
+        return engineMinor - pinMinor <= window ? "within-window" : "beyond-window";
+    }
+    return engineMajor === pinMajor ? "within-window" : "beyond-window";
+}
+/**
+ * Evaluate the three-band skew policy for a reachable engine against the pin.
+ * Unparseable versions fail closed (a version we cannot order is not safe to run).
+ */
+export function evaluateSkew(engineVersion, pinVersion, opts = {}) {
+    const engine = parseSemver(engineVersion);
+    const pin = parseSemver(pinVersion);
+    if (engine === null || pin === null) {
+        return {
+            band: "unknown",
+            decision: "fail-closed",
+            message: `cannot order engine (${engineVersion ?? "unknown"}) against pin (${pinVersion ?? "unknown"}); refusing to run an unorderable engine`,
+            requiresUpdateFirst: false,
+            escapeHatchUsed: false,
+        };
+    }
+    const cmp = compareSemver(engineVersion, pinVersion);
+    if (cmp === 0) {
+        return {
+            band: "match",
+            decision: "proceed-silent",
+            message: null,
+            requiresUpdateFirst: false,
+            escapeHatchUsed: false,
+        };
+    }
+    if (cmp === -1) {
+        return {
+            band: "engine-behind",
+            decision: "reject-global",
+            message: `engine ${engineVersion} is behind pin ${pinVersion}; rejecting global engine and falling through the ladder`,
+            requiresUpdateFirst: false,
+            escapeHatchUsed: false,
+        };
+    }
+    // engine > pin
+    const window = resolveWindow(opts);
+    const band = classifyAheadBand(engine, pin, window);
+    if (band === "within-window") {
+        return {
+            band,
+            decision: "proceed-loud-update",
+            message: `engine ${engineVersion} is ahead of pin ${pinVersion} within the skew window; proceeding after content update`,
+            requiresUpdateFirst: true,
+            escapeHatchUsed: false,
+        };
+    }
+    // beyond-window
+    if (escapeHatchActive(opts)) {
+        return {
+            band,
+            decision: "proceed-loud-update",
+            message: `engine ${engineVersion} is a large jump ahead of pin ${pinVersion}; accepted via escape hatch (--accept-engine-jump / ${ACCEPT_ENGINE_SKEW_ENV}=1)`,
+            requiresUpdateFirst: true,
+            escapeHatchUsed: true,
+        };
+    }
+    if (opts.interactive === true) {
+        return {
+            band,
+            decision: "prompt",
+            message: `engine ${engineVersion} is a large jump ahead of pin ${pinVersion}; prompt the operator to confirm (or pass --accept-engine-jump)`,
+            requiresUpdateFirst: true,
+            escapeHatchUsed: false,
+        };
+    }
+    return {
+        band,
+        decision: "fail-closed",
+        message: `engine ${engineVersion} is a large jump ahead of pin ${pinVersion}; failing closed. Re-run with --accept-engine-jump or ${ACCEPT_ENGINE_SKEW_ENV}=1`,
+        requiresUpdateFirst: false,
+        escapeHatchUsed: false,
+    };
+}
+//# sourceMappingURL=skew-policy.js.map

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

@@ -1,3 +1,4 @@
+import { type ResolveUserMdResult } from "../user-config/resolve-user-md.js";
 import type { GitRunner } from "./git.js";
 import { ritualStatePath } from "./ritual-sentinel.js";
 export declare const QUICK_STEPS: readonly ["alignment", "branch_policy", "triage_welcome"];
@@ -30,6 +31,7 @@ export interface SessionStartOptions {
     readonly verifyTools?: (output: (line: string) => void) => {
         exitCode: number;
     };
+    readonly resolveUserMd?: (projectRoot: string) => ResolveUserMdResult;
 }
 export declare function parseDeferrals(rawValues: readonly string[]): {
     deferrals: Record<string, string>;

package/dist/session/session-start.js

@@ -4,6 +4,7 @@ import { MIGRATE_COMPLETION_NUDGE, shouldEmitMigrateNudge } from "../init-deposi
 import { disclosureLine } from "../policy/disclosure.js";
 import { resolvePolicy } from "../policy/resolve.js";
 import { runDefaultMode } from "../triage/welcome/default-mode.js";
+import { resolveUserMdPath } from "../user-config/resolve-user-md.js";
 import { verifyRequiredTools } from "../verify-env/verify-tools.js";
 import { defaultGitRunner, gitHead, worktreePath } from "./git.js";
 import { newRitualStatePayload, ritualStatePath, ritualStep, writeRitualState, } from "./ritual-sentinel.js";
@@ -194,10 +195,30 @@ export function runSessionStart(projectRoot, options = {}) {
     const quickSteps = recordDeferredSteps(QUICK_STEPS, deferrals, instant);
     const gatedSteps = recordDeferredSteps(GATED_STEPS, deferrals, instant);
     const lines = [];
+    // Resolve USER.md via the shared first-hit-wins resolver so the alignment
+    // step finds preferences automatically in mismatched / headless sandboxes
+    // with zero manual DEFT_USER_PATH (#2271 / #2124). Never throws: an absent
+    // USER.md degrades to a clear diagnostic below.
+    const resolveUserMd = options.resolveUserMd ?? ((root) => resolveUserMdPath({ projectRoot: root }));
+    const userMd = resolveUserMd(projectRoot);
     if (!quickSteps.alignment) {
         const message = "Deft Directive active -- AGENTS.md loaded.";
-        quickSteps.alignment = ritualStep({ ok: true, ts: instant, message });
+        // Sanitize newlines on the data-derived path/diagnostic before they land in
+        // the ritual-step message / terminal output (matches doctor's CWE-116
+        // handling); DEFT_USER_PATH is only trimmed, so an embedded newline could
+        // otherwise survive into multi-line output.
+        const safePath = userMd.path.replace(/\r?\n/g, " ");
+        const safeDiagnostic = userMd.diagnostic.replace(/\r?\n/g, " ");
+        const userMdLine = userMd.found
+            ? `USER.md resolved (${userMd.rung}): ${safePath}`
+            : safeDiagnostic;
+        quickSteps.alignment = ritualStep({
+            ok: true,
+            ts: instant,
+            message: `${message} ${userMdLine}`,
+        });
         lines.push(message);
+        lines.push(userMdLine);
     }
     if (!quickSteps.branch_policy) {
         const result = resolvePolicy(projectRoot);
@@ -287,6 +308,12 @@ export function runSessionStart(projectRoot, options = {}) {
         state_path: statePath,
         quick_steps: quickSteps,
         gated_steps: gatedSteps,
+        user_md: {
+            path: userMd.path,
+            rung: userMd.rung,
+            found: userMd.found,
+            diagnostic: userMd.diagnostic,
+        },
         message: code === 0 ? "session ritual recorded" : "session ritual failed",
     };
     return { code, payload: resultPayload, lines };

package/dist/swarm/routing.js

@@ -186,7 +186,9 @@ export function resolveDispatchProvider(environ = process.env) {
  * Keys that would mutate the prototype chain rather than set an own property
  * if used as a computed object key. Rejected for provider/role names so a
  * malicious routing input cannot pollute `Object.prototype` (CodeQL
- * js/prototype-polluting-assignment).
+ * js/prototype-polluting-assignment). This validation guard produces the
+ * caller-facing error; the null-prototype write targets in
+ * `writeModelDecision` are the structural backstop CodeQL recognizes.
  */
 const FORBIDDEN_ROUTING_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 function assertSafeRoutingKey(kind, key) {
@@ -203,9 +205,14 @@ export function writeModelDecision(path, provider, role, decision) {
     assertSafeRoutingKey("provider", provider);
     assertSafeRoutingKey("role", role);
     const { data } = loadRoutingFile(path);
-    const file = data ?? {};
+    // Null-prototype write targets so a computed provider/role key can only ever
+    // set an own property and can never reach `Object.prototype`, even if the
+    // validation guard above regresses. CodeQL's js/prototype-polluting-assignment
+    // barrier does not track the interprocedural `assertSafeRoutingKey` guard, so
+    // this structural sink is what closes alert #52.
+    const file = Object.assign(Object.create(null), data ?? {});
     const existing = providerBlockOf(file, provider);
-    const block = existing ?? {};
+    const block = Object.assign(Object.create(null), existing ?? {});
     block[role] = {
         model: decision.model,
         mode: decision.mode ??

package/dist/triage/bulk/index.d.ts

@@ -88,12 +88,21 @@ export declare function excludeLogged(candidates: Iterable<IssuePayload>, option
 export declare function bulkAction(actionKey: string, repo: string, options?: BulkActionOptions): number;
 export declare function createFilesystemCacheModule(): CacheModule;
 export declare function createFilesystemCandidatesLogModule(logPath?: string): CandidatesLogModule;
+/**
+ * Native TypeScript bulk actions module (#2279).
+ *
+ * The bulk path defaults to this factory instead of {@link createPythonActionsModule}
+ * so `triage:bulk-*` never spawns a project-local `scripts/triage_actions.py`
+ * (an arbitrary-code-execution trust boundary a malicious checkout could plant).
+ * Each verb delegates to the already-native per-issue triage actions
+ * (`@deftai/directive-core/triage/actions`, #1725) bound to `createDefaultDeps(projectRoot)`.
+ */
+export declare function createNativeActionsModule(projectRoot: string): TriageActionsModule;
 export declare function createPythonActionsModule(scriptsDir: string): TriageActionsModule;
 export interface DefaultBulkDepsOptions {
     readonly cacheRoot?: string;
     readonly candidatesLogPath?: string;
-    readonly scriptsDir?: string;
-    readonly deftRoot?: string;
+    readonly projectRoot?: string;
 }
 export declare function bulkActionWithDefaults(actionKey: string, repo: string, options?: BulkActionOptions & DefaultBulkDepsOptions): number;
 //# sourceMappingURL=index.d.ts.map

package/dist/triage/bulk/index.js

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { resolveEvalPath } from "../../layout/resolve.js";
+import { createDefaultDeps, accept as nativeAccept, deferAction as nativeDefer, needsAc as nativeNeedsAc, reject as nativeReject, } from "../actions/index.js";
 export const ACTION_FN_NAMES = {
     accept: "accept",
     reject: "reject",
@@ -402,6 +403,40 @@ export function createFilesystemCandidatesLogModule(logPath = resolveEvalPath(pr
         },
     };
 }
+/**
+ * Native TypeScript bulk actions module (#2279).
+ *
+ * The bulk path defaults to this factory instead of {@link createPythonActionsModule}
+ * so `triage:bulk-*` never spawns a project-local `scripts/triage_actions.py`
+ * (an arbitrary-code-execution trust boundary a malicious checkout could plant).
+ * Each verb delegates to the already-native per-issue triage actions
+ * (`@deftai/directive-core/triage/actions`, #1725) bound to `createDefaultDeps(projectRoot)`.
+ */
+export function createNativeActionsModule(projectRoot) {
+    const deps = createDefaultDeps(projectRoot);
+    return {
+        accept(n, repo) {
+            nativeAccept(n, repo, deps, { projectRoot });
+        },
+        reject(n, repo, ...args) {
+            let reason = "";
+            const first = args[0];
+            if (typeof first === "object" && first !== null && "reason" in first) {
+                reason = String(first.reason);
+            }
+            else if (typeof first === "string") {
+                reason = first;
+            }
+            nativeReject(n, repo, reason, deps, { projectRoot });
+        },
+        defer(n, repo) {
+            nativeDefer(n, repo, "bulk defer", deps, { projectRoot });
+        },
+        needs_ac(n, repo) {
+            nativeNeedsAc(n, repo, deps, { projectRoot });
+        },
+    };
+}
 export function createPythonActionsModule(scriptsDir) {
     const runAction = (cmd, issueNumber, repo, extra = []) => {
         const result = spawnSync("uv", [
@@ -442,14 +477,16 @@ export function createPythonActionsModule(scriptsDir) {
     };
 }
 export function bulkActionWithDefaults(actionKey, repo, options = {}) {
-    const deftRoot = options.deftRoot ?? process.cwd();
-    const scriptsDir = options.scriptsDir ?? join(deftRoot, "scripts");
+    // #2279: the bulk path no longer resolves a `scripts/` dir from DEFT_ROOT /
+    // the project cwd. It defaults to the native TypeScript actions module so a
+    // malicious project-local `scripts/triage_actions.py` can never be executed.
+    const projectRoot = options.projectRoot ?? process.cwd();
     return bulkAction(actionKey, repo, {
         ...options,
-        cacheRoot: options.cacheRoot ?? join(deftRoot, ".deft-cache"),
+        cacheRoot: options.cacheRoot ?? join(projectRoot, ".deft-cache"),
         cacheModule: options.cacheModule ?? createFilesystemCacheModule(),
         candidatesLogModule: options.candidatesLogModule ?? createFilesystemCandidatesLogModule(options.candidatesLogPath),
-        actionsModule: options.actionsModule ?? createPythonActionsModule(scriptsDir),
+        actionsModule: options.actionsModule ?? createNativeActionsModule(projectRoot),
     });
 }
 //# sourceMappingURL=index.js.map

package/dist/triage/help/registry-data.d.ts

@@ -191,11 +191,11 @@ export declare const registryData: {
         readonly "task triage:welcome": {
             readonly name: "task triage:welcome";
             readonly summary: "Single-entry-point upgrade ritual";
-            readonly refs: "(N3 / #1143)";
-            readonly description: "6-phase onboarding ritual: detect prior state, prompt for subscription scope, run triage:bootstrap, prompt for wipCap, offer WIP relief, print triage:summary. Idempotent on re-run; safe entrypoint for fresh consumers.";
-            readonly usage: "task triage:welcome [-- --no-subprocess]";
-            readonly flags: readonly [readonly ["--no-subprocess", "(off)", "Dry-mode: don't shell out to sibling tasks."]];
-            readonly examples: readonly ["task triage:welcome"];
+            readonly refs: "(N3 / #1143, #2295)";
+            readonly description: "6-phase onboarding ritual: detect prior state, prompt for subscription scope, run triage:bootstrap, prompt for wipCap, offer WIP relief, print triage:summary. Idempotent on re-run; safe entrypoint for fresh consumers. Pass --onboard for the non-interactive path that applies a triage-scope preset (and optional --wip-cap) without prompting -- the form agents/CI use.";
+            readonly usage: "task triage:welcome [-- --onboard [--preset small|mid|mega] [--wip-cap N]] [--no-subprocess]";
+            readonly flags: readonly [readonly ["--onboard", "(off)", "Non-interactive onboarding: apply a triage-scope preset (and optional WIP cap) without prompting."], readonly ["--preset small|mid|mega", "small", "Subscription-scope preset applied by --onboard."], readonly ["--wip-cap N", "(policy default)", "Persist an explicit in-flight scope cap during --onboard (positive integer)."], readonly ["--no-subprocess", "(off)", "Dry-mode: don't shell out to sibling tasks."]];
+            readonly examples: readonly ["task triage:welcome", "task triage:welcome -- --onboard --preset small"];
             readonly see_also: readonly ["task triage:bootstrap", "task triage:summary", "#1119 / N3"];
             readonly placeholder: false;
         };

package/dist/triage/help/registry-data.js

@@ -296,11 +296,24 @@ export const registryData = {
         "task triage:welcome": {
             name: "task triage:welcome",
             summary: "Single-entry-point upgrade ritual",
-            refs: "(N3 / #1143)",
-            description: "6-phase onboarding ritual: detect prior state, prompt for subscription scope, run triage:bootstrap, prompt for wipCap, offer WIP relief, print triage:summary. Idempotent on re-run; safe entrypoint for fresh consumers.",
-            usage: "task triage:welcome [-- --no-subprocess]",
-            flags: [["--no-subprocess", "(off)", "Dry-mode: don't shell out to sibling tasks."]],
-            examples: ["task triage:welcome"],
+            refs: "(N3 / #1143, #2295)",
+            description: "6-phase onboarding ritual: detect prior state, prompt for subscription scope, run triage:bootstrap, prompt for wipCap, offer WIP relief, print triage:summary. Idempotent on re-run; safe entrypoint for fresh consumers. Pass --onboard for the non-interactive path that applies a triage-scope preset (and optional --wip-cap) without prompting -- the form agents/CI use.",
+            usage: "task triage:welcome [-- --onboard [--preset small|mid|mega] [--wip-cap N]] [--no-subprocess]",
+            flags: [
+                [
+                    "--onboard",
+                    "(off)",
+                    "Non-interactive onboarding: apply a triage-scope preset (and optional WIP cap) without prompting.",
+                ],
+                ["--preset small|mid|mega", "small", "Subscription-scope preset applied by --onboard."],
+                [
+                    "--wip-cap N",
+                    "(policy default)",
+                    "Persist an explicit in-flight scope cap during --onboard (positive integer).",
+                ],
+                ["--no-subprocess", "(off)", "Dry-mode: don't shell out to sibling tasks."],
+            ],
+            examples: ["task triage:welcome", "task triage:welcome -- --onboard --preset small"],
             see_also: ["task triage:bootstrap", "task triage:summary", "#1119 / N3"],
             placeholder: false,
         },

package/dist/triage/scope/cli.d.ts

@@ -6,13 +6,14 @@ export interface ParsedCliArgs {
     addLabel: string | undefined;
     addMilestone: string | undefined;
     ignoreLabel: string | undefined;
+    setPreset: string | undefined;
     diffFromUpstream: boolean;
     source: string;
     cacheRoot: string | undefined;
     count: number | undefined;
 }
 export declare function parseCliArgs(argv: string[]): ParsedCliArgs;
-export declare const CLI_HELP = "usage: triage_scope.py [-h] [--project-root PROJECT_ROOT] [--list]\n                       [--refresh-denominator] [--repo REPO]\n                       [--add-label ADD_LABEL] [--add-milestone ADD_MILESTONE]\n                       [--ignore-label IGNORE_LABEL] [--diff-from-upstream]\n                       [--source SOURCE] [--cache-root CACHE_ROOT]\n                       [--count COUNT]\n\nInspect, mutate, and diff the typed plan.policy.triageScope[] subscription +\nplan.policy.triageScopeIgnores[] (#1131 / D12, #1133 / D14, #1182 / D14c).\nRead paths never trigger a recompute; use --refresh-denominator to update the\ncoverage cache. Mutation flags --add-label / --add-milestone / --ignore-label\nare idempotent and atomic; every mutation appends a subscription-change audit\nentry to vbrief/.eval/subscription-history.jsonl.\n";
+export declare const CLI_HELP = "usage: triage_scope.py [-h] [--project-root PROJECT_ROOT] [--list]\n                       [--refresh-denominator] [--repo REPO]\n                       [--add-label ADD_LABEL] [--add-milestone ADD_MILESTONE]\n                       [--ignore-label IGNORE_LABEL] [--set-preset PRESET]\n                       [--diff-from-upstream]\n                       [--source SOURCE] [--cache-root CACHE_ROOT]\n                       [--count COUNT]\n\nInspect, mutate, and diff the typed plan.policy.triageScope[] subscription +\nplan.policy.triageScopeIgnores[] (#1131 / D12, #1133 / D14, #1182 / D14c).\nRead paths never trigger a recompute; use --refresh-denominator to update the\ncoverage cache. Mutation flags --add-label / --add-milestone / --ignore-label /\n--set-preset are idempotent and atomic; every mutation appends a\nsubscription-change audit entry to vbrief/.eval/subscription-history.jsonl.\n--set-preset small|mid|mega overwrites plan.policy.triageScope[] with a named\nsubscription preset via the same writer that backs triage:welcome --onboard (#2301).\n";
 /** Run triage:scope CLI; returns exit code and captured output for parity. */
 export declare function runCliCapture(argv: string[]): {
     code: number;

package/dist/triage/scope/cli.js

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { coveragePath, writeCoverageDenominator } from "./coverage.js";
-import { addLabelToIgnores, addLabelToScope, addMilestoneToScope, computeDiffFromUpstream, fetchUpstreamLabelsAndMilestones, renderDiffReport, } from "./mutations.js";
+import { addLabelToIgnores, addLabelToScope, addMilestoneToScope, computeDiffFromUpstream, fetchUpstreamLabelsAndMilestones, renderDiffReport, setScopePreset, } from "./mutations.js";
 import { subscriptionHash } from "./normalize.js";
 import { pyListRepr } from "./python-repr.js";
 import { renderIgnores, renderList } from "./renderers.js";
@@ -17,6 +17,7 @@ export function parseCliArgs(argv) {
         addLabel: undefined,
         addMilestone: undefined,
         ignoreLabel: undefined,
+        setPreset: undefined,
         diffFromUpstream: false,
         source: "github-issue",
         cacheRoot: undefined,
@@ -60,6 +61,12 @@ export function parseCliArgs(argv) {
         }
         else if (arg?.startsWith("--ignore-label="))
             parsed.ignoreLabel = arg.slice("--ignore-label=".length);
+        else if (arg === "--set-preset") {
+            parsed.setPreset = argv[i + 1];
+            i += 1;
+        }
+        else if (arg?.startsWith("--set-preset="))
+            parsed.setPreset = arg.slice("--set-preset=".length);
         else if (arg === "--source") {
             parsed.source = argv[i + 1] ?? "github-issue";
             i += 1;
@@ -86,16 +93,19 @@ export function parseCliArgs(argv) {
 export const CLI_HELP = `usage: triage_scope.py [-h] [--project-root PROJECT_ROOT] [--list]
                        [--refresh-denominator] [--repo REPO]
                        [--add-label ADD_LABEL] [--add-milestone ADD_MILESTONE]
-                       [--ignore-label IGNORE_LABEL] [--diff-from-upstream]
+                       [--ignore-label IGNORE_LABEL] [--set-preset PRESET]
+                       [--diff-from-upstream]
                        [--source SOURCE] [--cache-root CACHE_ROOT]
                        [--count COUNT]
 
 Inspect, mutate, and diff the typed plan.policy.triageScope[] subscription +
 plan.policy.triageScopeIgnores[] (#1131 / D12, #1133 / D14, #1182 / D14c).
 Read paths never trigger a recompute; use --refresh-denominator to update the
-coverage cache. Mutation flags --add-label / --add-milestone / --ignore-label
-are idempotent and atomic; every mutation appends a subscription-change audit
-entry to vbrief/.eval/subscription-history.jsonl.
+coverage cache. Mutation flags --add-label / --add-milestone / --ignore-label /
+--set-preset are idempotent and atomic; every mutation appends a
+subscription-change audit entry to vbrief/.eval/subscription-history.jsonl.
+--set-preset small|mid|mega overwrites plan.policy.triageScope[] with a named
+subscription preset via the same writer that backs triage:welcome --onboard (#2301).
 `;
 function handleMutation(projectRoot, args) {
     const out = { stdout: [], stderr: [] };
@@ -115,6 +125,10 @@ function handleMutation(projectRoot, args) {
             [changed, message] = addLabelToIgnores(projectRoot, args.ignoreLabel);
             verb = "ignore-label";
         }
+        else if (args.setPreset !== undefined) {
+            [changed, message] = setScopePreset(projectRoot, args.setPreset);
+            verb = "set-preset";
+        }
         else {
             throw new Error("internal: mutation flag set but no handler matched");
         }
@@ -148,12 +162,13 @@ export function runCliCapture(argv) {
         args.addLabel !== undefined ? "--add-label" : null,
         args.addMilestone !== undefined ? "--add-milestone" : null,
         args.ignoreLabel !== undefined ? "--ignore-label" : null,
+        args.setPreset !== undefined ? "--set-preset" : null,
     ].filter((f) => f !== null);
     if (mutationFlags.length > 1) {
         return {
             code: 2,
             stdout: "",
-            stderr: "triage:scope: --add-label / --add-milestone / --ignore-label " +
+            stderr: "triage:scope: --add-label / --add-milestone / --ignore-label / --set-preset " +
                 `are mutually exclusive (got ${pyListRepr(mutationFlags)}).\n`,
         };
     }
@@ -171,6 +186,15 @@ export function runCliCapture(argv) {
         if (mutation.code !== 0) {
             return { code: mutation.code, stdout: stdout.join(""), stderr: stderr.join("") };
         }
+        // A preset write comes from the trusted SUBSCRIPTION_PRESETS constant (the
+        // same source the onboard path writes). The `mega` preset intentionally
+        // ships an `explicit-watch` scaffold with an empty `issues` list for the
+        // operator to fill in, which the strict hand-edit validator below flags.
+        // Bypass that re-validation for a preset write so `--set-preset` reports the
+        // successful, persisted mutation instead of a spurious exit 1 (#2301).
+        if (args.setPreset !== undefined) {
+            return { code: 0, stdout: stdout.join(""), stderr: stderr.join("") };
+        }
     }
     const data = loadProjectDefinition(projectRoot);
     const rules = resolveScopeRules(projectRoot, data);

package/dist/triage/scope/mutations.d.ts

@@ -18,4 +18,14 @@ export declare function fetchUpstreamLabelsAndMilestones(repo: string, binary?:
 export declare function addLabelToScope(projectRoot: string, label: string, actor?: string | null): [boolean, string];
 export declare function addMilestoneToScope(projectRoot: string, milestone: string, actor?: string | null): [boolean, string];
 export declare function addLabelToIgnores(projectRoot: string, label: string): [boolean, string];
+/** Valid subscription preset keys for `triage:scope --set-preset` (#2301). */
+export declare function scopePresetKeys(): string[];
+/**
+ * Overwrite plan.policy.triageScope with a named subscription preset (#2301).
+ * Reuses the shared `subscriptionPreset` + `writeTriageScope` helper that backs
+ * `triage:welcome --onboard`, so the write path (namespaced key, legacy-key
+ * migration, audit trail, mutation lock) stays identical across surfaces rather
+ * than being duplicated here.
+ */
+export declare function setScopePreset(projectRoot: string, presetKey: string): [boolean, string];
 //# sourceMappingURL=mutations.d.ts.map

package/dist/triage/scope/mutations.js

@@ -1,5 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { SUBPROCESS_MAX_BUFFER } from "../../subprocess/max-buffer.js";
+import { SUBSCRIPTION_PRESETS } from "../welcome/constants.js";
+import { subscriptionPreset, writeTriageScope } from "../welcome/writers.js";
 import { collectMilestoneSubscribedNames, rulesRequestIsOpen } from "./milestone.js";
 import { addIgnore, subscribe } from "./mutations-core.js";
 import { resolveScopeIgnores, resolveScopeRules } from "./resolve.js";
@@ -200,4 +202,24 @@ export function addLabelToIgnores(projectRoot, label) {
         throw new Error(`label must be a non-empty string; got ${JSON.stringify(label)}`);
     return addIgnore(projectRoot, label);
 }
+/** Valid subscription preset keys for `triage:scope --set-preset` (#2301). */
+export function scopePresetKeys() {
+    return Object.keys(SUBSCRIPTION_PRESETS);
+}
+/**
+ * Overwrite plan.policy.triageScope with a named subscription preset (#2301).
+ * Reuses the shared `subscriptionPreset` + `writeTriageScope` helper that backs
+ * `triage:welcome --onboard`, so the write path (namespaced key, legacy-key
+ * migration, audit trail, mutation lock) stays identical across surfaces rather
+ * than being duplicated here.
+ */
+export function setScopePreset(projectRoot, presetKey) {
+    const key = presetKey.trim();
+    const validKeys = scopePresetKeys();
+    if (!validKeys.includes(key)) {
+        throw new Error(`unknown preset ${JSON.stringify(presetKey)}; valid presets: ${validKeys.join(", ")}`);
+    }
+    const rules = subscriptionPreset(key);
+    return writeTriageScope(projectRoot, rules, { presetLabel: key });
+}
 //# sourceMappingURL=mutations.js.map

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

@@ -1,10 +1,9 @@
-export declare const PROJECT_DEFINITION_REL_PATH = "vbrief/PROJECT-DEFINITION.vbrief.json";
 export declare const CACHE_DIR_NAME = ".deft-cache";
 export declare const CACHE_SOURCE = "github-issue";
 export declare const CANDIDATES_RELPATH: readonly ["vbrief", ".eval", "candidates.jsonl"];
 export declare const WIP_LIFECYCLE_DIRS: readonly ["pending", "active"];
 export declare const AUDIT_LOG_REL_PATH = "meta/policy-changes.log";
-export declare const DEFAULT_WIP_CAP = 10;
+export declare const DEFAULT_WIP_CAP = 20;
 export declare const DEFAULT_RELIEF_AGE_DAYS = 30;
 export declare const TRIAGE_SKILL_PATH = "skills/deft-directive-triage/SKILL.md";
 export declare const WELCOME_AUDIT_TAG = "triage-welcome";

package/dist/triage/welcome/constants.js

@@ -1,10 +1,9 @@
-export const PROJECT_DEFINITION_REL_PATH = "vbrief/PROJECT-DEFINITION.vbrief.json";
 export const CACHE_DIR_NAME = ".deft-cache";
 export const CACHE_SOURCE = "github-issue";
 export const CANDIDATES_RELPATH = ["vbrief", ".eval", "candidates.jsonl"];
 export const WIP_LIFECYCLE_DIRS = ["pending", "active"];
 export const AUDIT_LOG_REL_PATH = "meta/policy-changes.log";
-export const DEFAULT_WIP_CAP = 10;
+export const DEFAULT_WIP_CAP = 20;
 export const DEFAULT_RELIEF_AGE_DAYS = 30;
 export const TRIAGE_SKILL_PATH = "skills/deft-directive-triage/SKILL.md";
 export const WELCOME_AUDIT_TAG = "triage-welcome";

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

@@ -1,5 +1,6 @@
 export * from "./constants.js";
 export { type DefaultModeOptions, formatWelcomeCommand, normalizeTaskPrefix, runDefaultMode, type WelcomeOutcome, } from "./default-mode.js";
+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";

package/dist/triage/welcome/index.js

@@ -1,5 +1,6 @@
 export * from "./constants.js";
 export { formatWelcomeCommand, normalizeTaskPrefix, runDefaultMode, } from "./default-mode.js";
+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";

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

@@ -0,0 +1,35 @@
+/** Default triage-scope preset applied when `--onboard` is run without `--preset`. */
+export declare const DEFAULT_ONBOARD_PRESET = "small";
+export interface OnboardOptions {
+    /** Triage-scope preset key; defaults to {@link DEFAULT_ONBOARD_PRESET}. */
+    readonly preset?: string | null;
+    /** Explicit WIP cap to persist; omitted keeps the current/default cap. */
+    readonly wipCap?: number | null;
+    readonly output?: (line: string) => void;
+    readonly writeHistory?: boolean;
+    readonly taskPrefix?: string | null;
+    readonly selfHealFn?: (projectRoot: string) => void;
+    readonly now?: Date;
+}
+export interface OnboardOutcome {
+    readonly exitCode: number;
+    readonly presetApplied: string | null;
+    readonly triageScopeChanged: boolean;
+    readonly wipCapApplied: number | null;
+    readonly wipCapChanged: boolean;
+    readonly reliefOffered: boolean;
+}
+/**
+ * Non-interactive onboarding for `deft triage:welcome --onboard` (#2295).
+ *
+ * The welcome nudges point every fresh consumer at `--onboard`; this wires that
+ * command to the already-tested core writers instead of the old "not
+ * implemented" stub. It writes the chosen triage-scope preset and (optionally)
+ * a WIP cap via {@link writeTriageScope} / {@link writeWipCap} -- which already
+ * target the canonical `x-directive/policy` key and migrate any legacy bare
+ * block -- previews WIP relief when at/over cap, then prints a completion
+ * summary and the next-step guidance. Flag-driven by design: agents/CI pass
+ * `--preset` / `--wip-cap`; sensible defaults apply otherwise.
+ */
+export declare function runOnboardMode(projectRoot: string, options?: OnboardOptions): OnboardOutcome;
+//# sourceMappingURL=onboard.d.ts.map