@deftai/directive-core 0.77.0 → 0.79.0

package/dist/scope/transition.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, renameSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { InstrumentedVbriefCrud, persistCrudMetrics } from "../eval/crud-telemetry.js";
 import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
@@ -8,6 +8,7 @@ import { stampCompletionMetadata } from "./capacity-stamp.js";
 import { LIFECYCLE_FOLDERS, MOVE_LABELS, STATUS_PRECONDITIONS, STAY_LABELS, TRANSITIONS, } from "./constants.js";
 import { detectLifecycleFolder, updateDecomposedChildBackReferences, updateDecomposedParentBackReferences, } from "./decomposed-refs.js";
 import { syncProjectDefinitionAfterScopeMove } from "./project-definition-sync.js";
+import { syncSpecificationAfterScopeMove } from "./specification-sync.js";
 import { formatVbriefJson, utcNowIso } from "./vbrief-json.js";
 export function runTransition(action, filePath, now = new Date()) {
     if (!(action in TRANSITIONS)) {
@@ -101,30 +102,57 @@ export function runTransition(action, filePath, now = new Date()) {
     }
     const formatted = formatVbriefJson(data);
     const crud = new InstrumentedVbriefCrud({ now: () => now });
-    const writeResult = crud.update(resolvedPath, formatted, { trustedWrite: true });
-    if (!writeResult.ok) {
-        return { ok: false, message: writeResult.error ?? `CRUD update failed for ${resolvedPath}` };
-    }
-    try {
-        persistCrudMetrics(projectRoot, crud.getMetrics());
-    }
-    catch {
-        /* best-effort telemetry persistence */
-    }
     if (targetFolder !== null) {
         const destDir = join(vbriefRoot, targetFolder);
         mkdirSync(destDir, { recursive: true });
         const destPath = join(destDir, basename);
-        renameSync(resolvedPath, destPath);
+        if (existsSync(destPath)) {
+            return { ok: false, message: `Target already exists: ${destPath}` };
+        }
+        // #2578: stamp terminal status at the destination path in the same write as
+        // folder placement — never leave a non-terminal status under completed/.
+        const writeResult = crud.update(destPath, formatted, { trustedWrite: true });
+        if (!writeResult.ok) {
+            return { ok: false, message: writeResult.error ?? `CRUD update failed for ${destPath}` };
+        }
+        try {
+            unlinkSync(resolvedPath);
+        }
+        catch (err) {
+            try {
+                unlinkSync(destPath);
+            }
+            catch {
+                /* best-effort rollback */
+            }
+            return { ok: false, message: `Failed to remove source after move: ${String(err)}` };
+        }
+        try {
+            persistCrudMetrics(projectRoot, crud.getMetrics());
+        }
+        catch {
+            /* best-effort telemetry persistence */
+        }
         updateDecomposedParentBackReferences(data, resolvedPath, destPath, vbriefRoot);
         updateDecomposedChildBackReferences(data, resolvedPath, destPath, vbriefRoot);
         syncProjectDefinitionAfterScopeMove(data, resolvedPath, destPath, vbriefRoot, targetStatus);
+        syncSpecificationAfterScopeMove(data, resolvedPath, destPath, vbriefRoot, targetStatus);
         const actionLabel = MOVE_LABELS[act] ?? act.charAt(0).toUpperCase() + act.slice(1);
         return {
             ok: true,
             message: `${actionLabel} ${basename}: ${currentFolder}/ -> ${targetFolder}/ (status: ${targetStatus})`,
         };
     }
+    const writeResult = crud.update(resolvedPath, formatted, { trustedWrite: true });
+    if (!writeResult.ok) {
+        return { ok: false, message: writeResult.error ?? `CRUD update failed for ${resolvedPath}` };
+    }
+    try {
+        persistCrudMetrics(projectRoot, crud.getMetrics());
+    }
+    catch {
+        /* best-effort telemetry persistence */
+    }
     const actionLabel = STAY_LABELS[act] ?? act.charAt(0).toUpperCase() + act.slice(1);
     return {
         ok: true,

package/dist/session/cache-recovery.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Format a consumer-runnable `deft cache fetch-all` recovery command (#2574).
+ *
+ * Uses the space-separated CLI surface (not the colon task alias) and always
+ * includes required `--source` / `--repo` flags so following the hint literally
+ * reaches the handler instead of `unknown verb 'cache:fetch-all'`.
+ */
+export declare function formatCacheFetchAllRecoveryCommand(repo: string | null, options?: {
+    force?: boolean;
+}): string;
+/**
+ * Branch-aware recovery hint (#1953 Option 3, #2574 argv fix).
+ * Age-stale (or age+drift mixed) → --force bypasses TTL; drift-only → plain refetch.
+ */
+export declare function recoveryHintForStaleFailure(causes: Readonly<{
+    ageStale: boolean;
+    driftDetected: boolean;
+}>, repo?: string | null): string;
+//# sourceMappingURL=cache-recovery.d.ts.map

package/dist/session/cache-recovery.js

@@ -0,0 +1,26 @@
+import { formatFrameworkCommand } from "../render/framework-commands.js";
+const CACHE_FETCH_SOURCE = "github-issue";
+/**
+ * Format a consumer-runnable `deft cache fetch-all` recovery command (#2574).
+ *
+ * Uses the space-separated CLI surface (not the colon task alias) and always
+ * includes required `--source` / `--repo` flags so following the hint literally
+ * reaches the handler instead of `unknown verb 'cache:fetch-all'`.
+ */
+export function formatCacheFetchAllRecoveryCommand(repo, options = {}) {
+    const repoSlug = repo ?? "OWNER/NAME";
+    const args = ["cache", "fetch-all", "--source", CACHE_FETCH_SOURCE, "--repo", repoSlug];
+    if (options.force) {
+        args.push("--force");
+    }
+    return formatFrameworkCommand(args);
+}
+/**
+ * Branch-aware recovery hint (#1953 Option 3, #2574 argv fix).
+ * Age-stale (or age+drift mixed) → --force bypasses TTL; drift-only → plain refetch.
+ */
+export function recoveryHintForStaleFailure(causes, repo = null) {
+    const command = formatCacheFetchAllRecoveryCommand(repo, { force: causes.ageStale });
+    return `  Recovery: run \`${command}\` to refresh and reconcile upstream state.`;
+}
+//# sourceMappingURL=cache-recovery.js.map

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

@@ -1,3 +1,4 @@
+import { type EnvironmentContext } from "../platform/shell-context.js";
 import { type ResolveUserMdResult } from "../user-config/resolve-user-md.js";
 import type { GitRunner } from "./git.js";
 import { ritualStatePath } from "./ritual-sentinel.js";
@@ -40,6 +41,7 @@ export interface SessionStartOptions {
         exitCode: number;
     };
     readonly resolveUserMd?: (projectRoot: string) => ResolveUserMdResult;
+    readonly probeEnvironment?: () => EnvironmentContext;
 }
 export declare function parseDeferrals(rawValues: readonly string[]): {
     deferrals: Record<string, string>;

package/dist/session/session-start.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { runningInsideDeftRepo } from "../doctor/paths.js";
 import { emitSessionEvalReadback } from "../eval/readback.js";
 import { MIGRATE_COMPLETION_NUDGE, shouldEmitMigrateNudge } from "../init-deposit/migrate.js";
+import { detectEnvironmentContext, environmentContextToDict, formatEnvironmentContext, } from "../platform/shell-context.js";
 import { disclosureLine } from "../policy/disclosure.js";
 import { resolvePolicy } from "../policy/resolve.js";
 import { runDefaultMode } from "../triage/welcome/default-mode.js";
@@ -187,7 +188,7 @@ export function defaultBranchSync(projectRoot, runGit = defaultGitRunner) {
     }
     return { branch, upstream, ahead, behind, warning };
 }
-function runReadOnlySessionStart(projectRoot, options, instant) {
+function runReadOnlySessionStart(projectRoot, options, instant, environment) {
     const lines = [];
     const resolveUserMd = options.resolveUserMd ?? ((root) => resolveUserMdPath({ projectRoot: root }));
     const userMd = resolveUserMd(projectRoot);
@@ -198,6 +199,7 @@ function runReadOnlySessionStart(projectRoot, options, instant) {
         : safeDiagnostic;
     lines.push(READ_ONLY_ALIGNMENT_MESSAGE);
     lines.push(userMdLine);
+    lines.push(formatEnvironmentContext(environment));
     const resultPayload = {
         ready: true,
         exit_code: 0,
@@ -217,6 +219,7 @@ function runReadOnlySessionStart(projectRoot, options, instant) {
             found: userMd.found,
             diagnostic: userMd.diagnostic,
         },
+        environment: environmentContextToDict(environment),
         message: READ_ONLY_RESULT_MESSAGE,
     };
     return { code: 0, payload: resultPayload, lines };
@@ -226,16 +229,22 @@ export function runSessionStart(projectRoot, options = {}) {
     const instant = options.now ?? new Date();
     const deferrals = options.deferrals ?? {};
     const runGit = options.runGit ?? defaultGitRunner;
+    const environment = (options.probeEnvironment ?? detectEnvironmentContext)();
     if (posture === READ_ONLY_POSTURE) {
-        return runReadOnlySessionStart(projectRoot, options, instant);
+        return runReadOnlySessionStart(projectRoot, options, instant, environment);
     }
     const { head: gitHeadValue, error: gitError } = gitHead(projectRoot, runGit);
     if (gitHeadValue === null) {
         const payload = {
             ready: false,
+            environment: environmentContextToDict(environment),
             message: gitError ?? "could not resolve git HEAD",
         };
-        return { code: 2, payload, lines: [payload.message] };
+        return {
+            code: 2,
+            payload,
+            lines: [formatEnvironmentContext(environment), payload.message],
+        };
     }
     const quickSteps = recordDeferredSteps(QUICK_STEPS, deferrals, instant);
     const gatedSteps = recordDeferredSteps(GATED_STEPS, deferrals, instant);
@@ -265,6 +274,7 @@ export function runSessionStart(projectRoot, options = {}) {
         lines.push(message);
         lines.push(userMdLine);
     }
+    lines.push(formatEnvironmentContext(environment));
     if (!quickSteps.branch_policy) {
         const result = resolvePolicy(projectRoot);
         const message = disclosureLine(result);
@@ -377,6 +387,7 @@ export function runSessionStart(projectRoot, options = {}) {
             found: userMd.found,
             diagnostic: userMd.diagnostic,
         },
+        environment: environmentContextToDict(environment),
         message: code === 0 ? "session ritual recorded" : "session ritual failed",
     };
     return { code, payload: resultPayload, lines };

package/dist/session/verify-session-ritual.d.ts

@@ -1,5 +1,6 @@
 import { type GitRunner } from "./git.js";
 import { type DirectivePosture } from "./posture.js";
+export { formatCacheFetchAllRecoveryCommand, recoveryHintForStaleFailure, } from "./cache-recovery.js";
 export declare const ENV_SKIP = "DEFT_SESSION_RITUAL_SKIP";
 export { ENTRYPOINT_TIMEOUT_EXIT_CODE, ENTRYPOINT_TIMEOUT_SECONDS, } from "./ritual-entrypoint.js";
 export declare const GATED_ENTRYPOINT_COMMANDS: Readonly<Record<string, readonly string[]>>;
@@ -29,6 +30,22 @@ export interface VerifySessionRitualOptions {
     readonly envPosture?: string | undefined;
     readonly handoffText?: string | null;
 }
+export interface InspectSessionRitualOptions {
+    readonly tier?: "quick" | "gated";
+    readonly now?: Date;
+    readonly runGit?: GitRunner;
+    readonly posture?: DirectivePosture;
+    readonly envPosture?: string | undefined;
+    readonly handoffText?: string | null;
+}
+/**
+ * Read-only ritual-state inspection for host hooks.
+ *
+ * Unlike {@link verifySessionRitual}, this never runs missing gated entrypoints
+ * and never rewrites `.deft/ritual-state.json`. A PreToolUse decision must be a
+ * probe, not a hidden `doctor` / cache-refresh mutation boundary.
+ */
+export declare function inspectSessionRitual(projectRoot: string, options?: InspectSessionRitualOptions): VerifyResult;
 export declare function verifySessionRitual(projectRoot: string, options?: VerifySessionRitualOptions): VerifyResult;
 export declare function emitVerifyJson(result: VerifyResult): string;
 export declare function emitBypassWarning(result: VerifyResult): string;

package/dist/session/verify-session-ritual.js

@@ -7,6 +7,7 @@ import { defaultRitualRunner } from "./ritual-entrypoint.js";
 import { readRitualState, ritualStatePath, ritualStep, writeRitualState, } from "./ritual-sentinel.js";
 import { GATED_STEPS, QUICK_STEPS } from "./session-start.js";
 import { resolveSessionRitualStalenessHours } from "./staleness.js";
+export { formatCacheFetchAllRecoveryCommand, recoveryHintForStaleFailure, } from "./cache-recovery.js";
 export const ENV_SKIP = "DEFT_SESSION_RITUAL_SKIP";
 export { ENTRYPOINT_TIMEOUT_EXIT_CODE, ENTRYPOINT_TIMEOUT_SECONDS, } from "./ritual-entrypoint.js";
 export const GATED_ENTRYPOINT_COMMANDS = {
@@ -105,6 +106,69 @@ function evaluateLoadedState(projectRoot, state, input) {
     }
     return [0, `OK session ritual ${input.tier} tier is fresh.`];
 }
+/**
+ * Read-only ritual-state inspection for host hooks.
+ *
+ * Unlike {@link verifySessionRitual}, this never runs missing gated entrypoints
+ * and never rewrites `.deft/ritual-state.json`. A PreToolUse decision must be a
+ * probe, not a hidden `doctor` / cache-refresh mutation boundary.
+ */
+export function inspectSessionRitual(projectRoot, options = {}) {
+    const tier = options.tier ?? "quick";
+    const posture = resolveSessionPosture({
+        explicitPosture: options.posture ?? null,
+        envPosture: options.envPosture ?? process.env.DEFT_SESSION_POSTURE,
+        handoffText: options.handoffText,
+        tier,
+    });
+    const ritualStateRequired = posture === "mutation" && !ritualStateIsPostureAuthority();
+    const statePath = ritualStatePath(projectRoot);
+    if (posture === "read-only") {
+        return {
+            code: 0,
+            message: readOnlyPostureMessage(tier),
+            tier,
+            statePath,
+            bypassed: false,
+            wouldFailCode: null,
+            posture,
+            ritualStateRequired: false,
+        };
+    }
+    const missingStateFile = !existsSync(statePath);
+    const [state, err] = readRitualState(projectRoot);
+    if (state === null) {
+        const code = missingStateFile ? 1 : 2;
+        const startCommand = formatFrameworkCommand(["session:start"]);
+        return {
+            code,
+            message: code === 1
+                ? `${err}. Run \`${startCommand}\` before implementation dispatch.`
+                : (err ?? "ritual state invalid"),
+            tier,
+            statePath,
+            bypassed: false,
+            wouldFailCode: null,
+            posture,
+            ritualStateRequired,
+        };
+    }
+    const [code, message] = evaluateLoadedState(projectRoot, state, {
+        tier,
+        now: options.now ?? new Date(),
+        runGit: options.runGit,
+    });
+    return {
+        code,
+        message,
+        tier,
+        statePath,
+        bypassed: false,
+        wouldFailCode: null,
+        posture,
+        ritualStateRequired,
+    };
+}
 export function verifySessionRitual(projectRoot, options = {}) {
     const tier = options.tier ?? "quick";
     const posture = resolveSessionPosture({

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

@@ -364,6 +364,17 @@ export declare const registryData: {
             readonly see_also: readonly ["task eval:run", "task eval:report", "#1703"];
             readonly placeholder: false;
         };
+        readonly "task eval:triggers": {
+            readonly name: "task eval:triggers";
+            readonly summary: "Trigger routing coverage for Skills Index rules";
+            readonly refs: "(#1586)";
+            readonly description: "Offline skill-pi-trigger-eval compatible routing check: grades evals/trigger-cases.jsonl against REFERENCES.md Skills Index triggers (should-fire / should-not-fire per skill).";
+            readonly usage: "task eval:triggers [-- --json] [--project-root PATH]";
+            readonly flags: readonly [readonly ["--json", "(off)", "Emit the TriggerEvalReport JSON."], readonly ["--project-root PATH", "(cwd)", "Project root override (Taskfile threads USER_WORKING_DIR)."]];
+            readonly examples: readonly ["task eval:triggers", "task eval:triggers -- --json"];
+            readonly see_also: readonly ["task eval:health", "task verify:eval-triggers-relocation", "#1862"];
+            readonly placeholder: false;
+        };
         readonly "task eval:run": {
             readonly name: "task eval:run";
             readonly summary: "Tier 2 golden corpus eval for a model";
@@ -508,7 +519,7 @@ export declare const registryData: {
             readonly placeholder: false;
         };
     };
-    readonly categoriesTriage: readonly [readonly ["Session-start", readonly ["task triage:summary", "task verify:cache-fresh"]], readonly ["State verbs (mutate audit log)", readonly ["task triage:accept", "task triage:defer", "task triage:reject", "task triage:needs-ac", "task triage:mark-duplicate", "task triage:reset", "task triage:status", "task triage:history"]], readonly ["Read verbs", readonly ["task triage:queue", "task triage:audit", "task triage:show", "task triage:scope", "task triage:scope-drift", "task triage:classify"]], readonly ["Lifecycle", readonly ["task triage:bootstrap", "task triage:welcome", "task triage:reconcile"]], readonly ["Bulk variants", readonly ["task triage:bulk-accept", "task triage:bulk-reject", "task triage:bulk-defer", "task triage:bulk-needs-ac", "task triage:refresh-active", "task triage:smoketest"]], readonly ["Subscription mutation", readonly ["task triage:subscribe", "task triage:unsubscribe"]], readonly ["Archive / rotation", readonly ["task triage:audit:prune", "task triage:archive-list", "task triage:restore-from-archive", "task triage:audit-log:rotate", "task triage:metrics"]], readonly ["Framework eval (#1703)", readonly ["task eval:health", "task eval:run", "task eval:report"]]];
+    readonly categoriesTriage: readonly [readonly ["Session-start", readonly ["task triage:summary", "task verify:cache-fresh"]], readonly ["State verbs (mutate audit log)", readonly ["task triage:accept", "task triage:defer", "task triage:reject", "task triage:needs-ac", "task triage:mark-duplicate", "task triage:reset", "task triage:status", "task triage:history"]], readonly ["Read verbs", readonly ["task triage:queue", "task triage:audit", "task triage:show", "task triage:scope", "task triage:scope-drift", "task triage:classify"]], readonly ["Lifecycle", readonly ["task triage:bootstrap", "task triage:welcome", "task triage:reconcile"]], readonly ["Bulk variants", readonly ["task triage:bulk-accept", "task triage:bulk-reject", "task triage:bulk-defer", "task triage:bulk-needs-ac", "task triage:refresh-active", "task triage:smoketest"]], readonly ["Subscription mutation", readonly ["task triage:subscribe", "task triage:unsubscribe"]], readonly ["Archive / rotation", readonly ["task triage:audit:prune", "task triage:archive-list", "task triage:restore-from-archive", "task triage:audit-log:rotate", "task triage:metrics"]], readonly ["Framework eval (#1703)", readonly ["task eval:health", "task eval:triggers", "task eval:run", "task eval:report"]]];
     readonly categoriesScope: readonly [readonly ["Promote / demote", readonly ["task scope:promote", "task scope:demote"]], readonly ["Activate / complete", readonly ["task scope:activate", "task scope:complete", "task scope:fail", "task scope:cancel", "task scope:block", "task scope:unblock"]], readonly ["Reversibility", readonly ["task scope:undo", "task scope:restore"]], readonly ["Decomposition", readonly ["task scope:decompose"]]];
     readonly scriptSubcommandMap: {
         readonly triage_actions: {

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

@@ -548,6 +548,24 @@ export const registryData = {
             see_also: ["task eval:run", "task eval:report", "#1703"],
             placeholder: false,
         },
+        "task eval:triggers": {
+            name: "task eval:triggers",
+            summary: "Trigger routing coverage for Skills Index rules",
+            refs: "(#1586)",
+            description: "Offline skill-pi-trigger-eval compatible routing check: grades evals/trigger-cases.jsonl against REFERENCES.md Skills Index triggers (should-fire / should-not-fire per skill).",
+            usage: "task eval:triggers [-- --json] [--project-root PATH]",
+            flags: [
+                ["--json", "(off)", "Emit the TriggerEvalReport JSON."],
+                [
+                    "--project-root PATH",
+                    "(cwd)",
+                    "Project root override (Taskfile threads USER_WORKING_DIR).",
+                ],
+            ],
+            examples: ["task eval:triggers", "task eval:triggers -- --json"],
+            see_also: ["task eval:health", "task verify:eval-triggers-relocation", "#1862"],
+            placeholder: false,
+        },
         "task eval:run": {
             name: "task eval:run",
             summary: "Tier 2 golden corpus eval for a model",
@@ -829,7 +847,10 @@ export const registryData = {
                 "task triage:metrics",
             ],
         ],
-        ["Framework eval (#1703)", ["task eval:health", "task eval:run", "task eval:report"]],
+        [
+            "Framework eval (#1703)",
+            ["task eval:health", "task eval:triggers", "task eval:run", "task eval:report"],
+        ],
     ],
     categoriesScope: [
         ["Promote / demote", ["task scope:promote", "task scope:demote"]],

package/dist/triage/welcome/default-mode.js

@@ -1,4 +1,5 @@
 import { resolve } from "node:path";
+import { ensureTriageCacheHydrated } from "../../cache/empty-populate.js";
 import { maybeSelfHealCache } from "../../cache/fetch.js";
 import { FIRST_TIME_NUDGE, INCOMPLETE_NUDGE_TEMPLATE } from "./constants.js";
 import { classifyOnboarding, detectPriorState } from "./prior-state.js";
@@ -32,6 +33,7 @@ export function runDefaultMode(projectRoot, options = {}) {
     };
     const heal = options.selfHealFn ??
         ((root) => {
+            ensureTriageCacheHydrated(resolve(root));
             maybeSelfHealCache(resolve(root));
         });
     heal(projectRoot);

package/dist/triage/welcome/onboard.js

@@ -1,5 +1,6 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
+import { ensureTriageCacheHydrated } from "../../cache/empty-populate.js";
 import { maybeSelfHealCache } from "../../cache/fetch.js";
 import { resolveProjectDefinitionPath } from "../../layout/resolve.js";
 import { DEFAULT_WIP_CAP, SUBSCRIPTION_PRESETS, TRIAGE_SKILL_PATH } from "./constants.js";
@@ -57,6 +58,7 @@ export function runOnboardMode(projectRoot, options = {}) {
     }
     const heal = options.selfHealFn ??
         ((root) => {
+            ensureTriageCacheHydrated(resolve(root));
             maybeSelfHealCache(resolve(root));
         });
     heal(projectRoot);

package/dist/ts-check-lane/run-lane.d.ts

@@ -41,6 +41,11 @@ export interface RunTsLaneOptions {
     readonly runner?: LaneRunner;
     /** Injected sink for human-facing notices (defaults to stdout). */
     readonly out?: (message: string) => void;
+    /**
+     * Env used to resolve release coverage-debt before sanitizeTsLaneEnv strips
+     * DEFT_RELEASE_PREFLIGHT (#2618). Defaults to process.env.
+     */
+    readonly env?: NodeJS.ProcessEnv;
 }
 /** Windows command shims (.cmd/.bat) need a shell; native executables do not. */
 export declare function shouldUseShellForCommand(command: string, platform?: NodeJS.Platform): boolean;

package/dist/ts-check-lane/run-lane.js

@@ -20,6 +20,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { posix, win32 } from "node:path";
 import { BRANCH_GATE_BYPASS_ENV, RELEASE_PREFLIGHT_ENV } from "../release/constants.js";
+import { resolveCoverageDebtIssue } from "../vitest-runner/coverage-debt.js";
 /** Release Step-5 vars that must not leak into vitest via inherited pnpm env (#2434). */
 const TS_LANE_POISON_ENV_KEYS = [BRANCH_GATE_BYPASS_ENV, RELEASE_PREFLIGHT_ENV];
 /**
@@ -96,12 +97,20 @@ export function runTsLane(projectRoot, options) {
     const { pnpm } = options;
     const runner = options.runner ?? defaultRunner;
     const out = options.out ?? ((message) => process.stdout.write(`${message}\n`));
+    // Resolve debt from the pre-sanitize env: sanitizeTsLaneEnv strips
+    // DEFT_RELEASE_PREFLIGHT (required for the env-based debt path), so forward
+    // --allow-coverage-debt=#N on the vitest argv instead (#2618 / #2573).
+    const debt = resolveCoverageDebtIssue([], options.env ?? process.env);
+    const debtIssue = debt.kind === "valid" ? debt.issue : null;
     if (!pnpm) {
         out(SKIP_NOTICE);
         return 0;
     }
     for (const command of LANE_COMMANDS) {
         const argv = [pnpm, ...command];
+        if (debtIssue !== null && command[1] === "test") {
+            argv.push("--", `--allow-coverage-debt=${debtIssue}`);
+        }
         const result = runner(argv, projectRoot);
         const code = result.status;
         // A null status means the child was terminated by a signal (SIGKILL / OOM /

package/dist/vbrief-reconcile/labels.d.ts

@@ -14,6 +14,9 @@ export interface ReconcileLabelsOptions {
     readonly repo?: string | null;
     readonly dryRun?: boolean;
     readonly client?: LabelClient;
+    /** Opt in to mutating issues outside the resolved project repo (#2601). */
+    readonly allowCrossRepo?: boolean;
+    readonly repoAllowlist?: readonly string[];
 }
 export declare function reconcileLabels(projectRoot: string, options?: ReconcileLabelsOptions): [number, ReconcileLabelsOutcome];
 export declare function renderLabelsReport(outcome: ReconcileLabelsOutcome): string;

package/dist/vbrief-reconcile/labels.js

@@ -4,6 +4,7 @@ import { hasArtifactSuffix, resolveLifecycleRoot, stripArtifactSuffix } from "..
 import { call } from "../scm/call.js";
 import { extractIssueRef } from "../triage/reconcile/parse-uri.js";
 import { depResolved, RESOLVED_FOLDERS } from "./graph.js";
+import { isRepoMutationAllowed } from "./repo-guard.js";
 import { allScopeIds, asStrList } from "./swarm-deps.js";
 export const SCAN_FOLDERS = ["proposed", "pending", "active"];
 export const MANAGED_LABELS = ["status:blocked", "epic", "status:tracker", "rfc"];
@@ -163,6 +164,19 @@ export function reconcileLabels(projectRoot, options = {}) {
                 ? metadata.swarm
                 : {};
             const desired = computeDesiredLabels(plan, hasUnresolvedDeps(swarm, knownIds));
+            // Guard before any SCM read so cross-repo refusal is explicit (#2601 / Greptile P1).
+            const mutateGate = isRepoMutationAllowed(effectiveRepo, root, {
+                allowCrossRepo: options.allowCrossRepo,
+                allowlist: options.repoAllowlist,
+                explicitRepo: options.repo ?? null,
+            });
+            if (!mutateGate.allowed) {
+                outcome.errors.push({
+                    story_id: storyId,
+                    message: mutateGate.reason ?? `refusing cross-repo mutation on ${effectiveRepo}`,
+                });
+                continue;
+            }
             let current;
             try {
                 current = client.fetchLabels(effectiveRepo, number);

package/dist/vbrief-reconcile/main.d.ts

@@ -7,6 +7,7 @@ export interface CliOptions {
     scenario?: string | null;
     all?: boolean;
     fixtureRoot?: string | null;
+    allowCrossRepo?: boolean;
 }
 export declare function usage(): void;
 export declare function runGraph(opts: CliOptions): number;

package/dist/vbrief-reconcile/main.js

@@ -28,6 +28,8 @@ function parseOptions(rest) {
         }
         else if (arg === "--force")
             opts.force = true;
+        else if (arg === "--allow-cross-repo")
+            opts.allowCrossRepo = true;
         else if (arg === "--dry-run")
             opts.dryRun = true;
         else if (arg === "--json")
@@ -46,7 +48,7 @@ function parseOptions(rest) {
     return opts;
 }
 export function usage() {
-    process.stderr.write("usage: vbrief-reconcile <graph|labels|umbrellas> [--project-root PATH] [--dry-run] [--json] [--force] [--repo OWNER/NAME]\n" +
+    process.stderr.write("usage: vbrief-reconcile <graph|labels|umbrellas> [--project-root PATH] [--dry-run] [--json] [--force] [--repo OWNER/NAME] [--allow-cross-repo]\n" +
         "       vbrief-reconcile parity --scenario NAME [--fixture-root PATH]\n" +
         "       vbrief-reconcile parity --all [--fixture-root PATH]\n");
 }
@@ -70,7 +72,11 @@ export function runGraph(opts) {
 }
 export function runLabels(opts) {
     const root = resolve(opts.projectRoot ?? ".");
-    const [code, outcome] = reconcileLabels(root, { repo: opts.repo, dryRun: opts.dryRun });
+    const [code, outcome] = reconcileLabels(root, {
+        repo: opts.repo,
+        dryRun: opts.dryRun,
+        allowCrossRepo: opts.allowCrossRepo,
+    });
     if (code === 2) {
         if (opts.json) {
             process.stdout.write(`${JSON.stringify({ error: "no vbrief/ directory found" })}\n`);
@@ -88,7 +94,11 @@ export function runLabels(opts) {
 }
 export function runUmbrellas(opts) {
     const root = resolve(opts.projectRoot ?? ".");
-    const [code, outcome] = reconcileUmbrellas(root, { repo: opts.repo, dryRun: opts.dryRun });
+    const [code, outcome] = reconcileUmbrellas(root, {
+        repo: opts.repo,
+        dryRun: opts.dryRun,
+        allowCrossRepo: opts.allowCrossRepo,
+    });
     if (code === 2) {
         if (opts.json) {
             process.stdout.write(`${JSON.stringify({ error: "no vbrief/ directory found" })}\n`);

package/dist/vbrief-reconcile/parity-scenarios.js

@@ -291,7 +291,11 @@ export function runParityScenario(name, options) {
                 ],
             });
             const client = options.labelClient ?? new MemoryLabelClient();
-            const [code, outcome] = reconcileLabels(root, { client, dryRun: true });
+            const [code, outcome] = reconcileLabels(root, {
+                client,
+                dryRun: true,
+                repo: "deftai/directive",
+            });
             return {
                 scenario: name,
                 ok: true,
@@ -314,7 +318,11 @@ export function runParityScenario(name, options) {
                 ],
             });
             const client = options.labelClient ?? new MemoryLabelClient();
-            const [code, outcome] = reconcileLabels(root, { client, dryRun: true });
+            const [code, outcome] = reconcileLabels(root, {
+                client,
+                dryRun: true,
+                repo: "deftai/directive",
+            });
             return {
                 scenario: name,
                 ok: true,
@@ -342,6 +350,7 @@ export function runParityScenario(name, options) {
                 client,
                 dryRun: true,
                 now: FIXED_NOW.toISOString().replace(/\.\d{3}Z$/, "Z"),
+                repo: "deftai/directive",
             });
             return {
                 scenario: name,
@@ -367,8 +376,13 @@ export function runParityScenario(name, options) {
             });
             const client = options.umbrellaClient ?? SHARED_UMBRELLA_CLIENT;
             const now = FIXED_NOW.toISOString().replace(/\.\d{3}Z$/, "Z");
-            reconcileUmbrellas(root, { client, dryRun: false, now });
-            const [code, outcome] = reconcileUmbrellas(root, { client, dryRun: true, now });
+            reconcileUmbrellas(root, { client, dryRun: false, now, repo: "deftai/directive" });
+            const [code, outcome] = reconcileUmbrellas(root, {
+                client,
+                dryRun: true,
+                now,
+                repo: "deftai/directive",
+            });
             return {
                 scenario: name,
                 ok: true,

package/dist/vbrief-reconcile/repo-guard.d.ts

@@ -0,0 +1,17 @@
+export interface RepoMutateGuardOptions {
+    readonly allowCrossRepo?: boolean;
+    readonly allowlist?: readonly string[];
+    readonly explicitRepo?: string | null;
+}
+/** Normalize owner/name slugs for case-insensitive comparison. */
+export declare function normalizeRepoSlug(repo: string): string;
+/**
+ * Fail-closed gate before SCM label/comment mutations (#2601).
+ * Cross-repo targets are refused unless explicitly opted in or allowlisted.
+ */
+export declare function isRepoMutationAllowed(targetRepo: string, projectRoot: string, options?: RepoMutateGuardOptions): {
+    readonly allowed: boolean;
+    readonly projectRepo: string | null;
+    readonly reason?: string;
+};
+//# sourceMappingURL=repo-guard.d.ts.map