@deftai/directive-core 0.106.0 → 0.108.0

package/dist/scm/readiness-cli.js

@@ -5,6 +5,7 @@
  * Exit 0 when ready; exit 1 when not ready (loud diagnostic); exit 2 on bad flags.
  */
 import { fileURLToPath } from "node:url";
+import { INSTALLATION_IDENTITY_ISSUE_URL, PRINCIPAL_KIND_USER, } from "../intake/github-auth-modes.js";
 import { clearScmReadyCache, formatScmReadinessLines, probeScmReadiness, scmReadinessToDict, } from "./readiness.js";
 export function parseScmReadinessArgs(argv) {
     const out = {};
@@ -30,6 +31,26 @@ export function parseScmReadinessArgs(argv) {
             }
             out.depth = value;
         }
+        else if (arg === "--repo") {
+            const value = argv[++i];
+            if (value === undefined || value.startsWith("-")) {
+                return { args: out, error: "--repo expects owner/repo" };
+            }
+            out.repo = value;
+        }
+        else if (arg === "--expected-login") {
+            const value = argv[++i];
+            if (value === undefined || value.startsWith("-")) {
+                return { args: out, error: "--expected-login expects a GitHub login" };
+            }
+            out.expectedLogin = value;
+        }
+        else if (arg === "--expected-app-slug" || arg === "--expected-installation-id") {
+            return {
+                args: out,
+                error: `${arg} is not accepted; GitHub App installation identity is deferred to ${INSTALLATION_IDENTITY_ISSUE_URL}`,
+            };
+        }
         else if (arg === "--help" || arg === "-h") {
             out.help = true;
         }
@@ -43,8 +64,19 @@ export function parseScmReadinessArgs(argv) {
     return { args: out, error: null };
 }
 const USAGE = "usage: deft scm:status [--json] [--deep|--shallow|--depth shallow|deep]\n" +
+    "                       [--repo OWNER/REPO] [--expected-login LOGIN]\n" +
     "  Report SCM (gh/ghx) availability + auth state in this execution env (#2275).\n" +
+    "  Deep probes derive the target repo (flag / GH_REPO / GITHUB_REPOSITORY / origin)\n" +
+    "  and compare an expected user login when one is supplied (#3665).\n" +
+    "  GitHub App installation identity is deferred to #3693.\n" +
     "  Exit 0 ready / 1 not ready / 2 config error.\n";
+function expectedPrincipalFromArgs(args) {
+    const login = args.expectedLogin?.trim() ?? "";
+    if (login.length > 0) {
+        return { kind: PRINCIPAL_KIND_USER, login };
+    }
+    return undefined;
+}
 export function scmReadinessMain(args, options = {}) {
     const writeOut = options.writeOut ?? ((s) => process.stdout.write(s));
     const writeErr = options.writeErr ?? ((s) => process.stderr.write(s));
@@ -52,12 +84,21 @@ export function scmReadinessMain(args, options = {}) {
         writeOut(USAGE);
         return 0;
     }
+    const expectedPrincipal = expectedPrincipalFromArgs(args);
+    if (expectedPrincipal !== undefined && "error" in expectedPrincipal) {
+        writeErr(`error: ${expectedPrincipal.error}\n${USAGE}`);
+        return 2;
+    }
     const depth = args.depth ?? (args.deep ? "deep" : "shallow");
     // Explicit probe always re-evaluates (credentials may have changed since
     // session:start). Clears the process-scoped requireScmReady cache too.
     clearScmReadyCache();
     const probe = options.probe ?? probeScmReadiness;
-    const report = probe({ depth });
+    const report = probe({
+        depth,
+        repo: args.repo,
+        expectedPrincipal,
+    });
     if (args.json) {
         writeOut(`${JSON.stringify(scmReadinessToDict(report), null, 2)}\n`);
     }

package/dist/scm/readiness.d.ts

@@ -18,7 +18,7 @@
  * env token presence + optional short `gh auth status`). Deep API validation
  * is opt-in via `deep: true` (session:start --with-network).
  */
-import { findInjectedToken, type GhRunner, GITHUB_AUTH_MODE_HOST_GH, GITHUB_AUTH_MODE_INJECTED_TOKEN } from "../intake/github-auth-modes.js";
+import { type ExpectedGithubWorkerPrincipal, findInjectedToken, type GhRunner, GITHUB_AUTH_MODE_HOST_GH, GITHUB_AUTH_MODE_INJECTED_TOKEN } from "../intake/github-auth-modes.js";
 import { type RuntimeCapabilityReport } from "../intake/platform-capabilities.js";
 import { type WhichFn } from "./binary.js";
 import { BINARY_PREFERENCE } from "./constants.js";
@@ -41,6 +41,8 @@ export interface ScmReadinessReport {
     readonly githubAuthMode: string;
     /** Runtime mode from the #1557a probe. */
     readonly runtimeMode: string;
+    /** Stable id naming why the runtime was classified that way (#3859). */
+    readonly runtimeModeReason: string | null;
     /** Whether an injected token env var is present (value never reported). */
     readonly injectedTokenPresent: boolean;
     /** Probe depth used for this report. */
@@ -64,6 +66,7 @@ export interface ProbeScmReadinessOptions {
     readonly runtimeReport?: RuntimeCapabilityReport;
     readonly githubAuthMode?: string | null;
     readonly repo?: string;
+    readonly expectedPrincipal?: ExpectedGithubWorkerPrincipal | null;
     readonly runGh?: GhRunner;
     /** When false, skip even `gh auth status` on the shallow path (tests / pure PATH). */
     readonly checkAuthStatus?: boolean;

package/dist/scm/readiness.js

@@ -21,6 +21,7 @@
 import { spawnSync } from "node:child_process";
 import { findInjectedToken, GITHUB_AUTH_MODE_HOST_GH, GITHUB_AUTH_MODE_INJECTED_TOKEN, inferGithubAuthMode, validateGithubAuthForWorker, } from "../intake/github-auth-modes.js";
 import { getPlatformCapabilities, probeRuntimeCapabilities, } from "../intake/platform-capabilities.js";
+import { EXPLICIT_SELECTION_REMEDIATION, GITHUB_AUTH_MODE_ENV, RUNTIME_REASON_CURSOR_MARKER_AMBIGUOUS, } from "../platform/cursor-managed-runtime.js";
 import { defaultWhich } from "./binary.js";
 import { BINARY_PREFERENCE } from "./constants.js";
 import { ScmStubError } from "./errors.js";
@@ -105,7 +106,12 @@ function mapDeepFailureToAuthState(result) {
         return "missing-token";
     if (result.failureKind === "gh_auth_failed")
         return "unauthenticated";
-    if (result.failureKind === "api_unreachable" || result.failureKind === "repo_access_denied") {
+    if (result.failureKind === "api_unreachable" ||
+        result.failureKind === "repo_access_denied" ||
+        result.failureKind === "missing_expected_principal" ||
+        result.failureKind === "principal_mismatch" ||
+        result.failureKind === "missing_target_repo" ||
+        result.failureKind === "installation_identity_unverifiable") {
         return "unauthenticated";
     }
     return "unknown";
@@ -133,6 +139,7 @@ export function probeScmReadiness(options = {}) {
             authState: "binary-absent",
             githubAuthMode,
             runtimeMode: runtimeReport.runtimeMode,
+            runtimeModeReason: runtimeReport.runtimeModeReason ?? null,
             injectedTokenPresent,
             depth,
             detail,
@@ -144,9 +151,11 @@ export function probeScmReadiness(options = {}) {
     }
     // Injected-token mode without a token is a hard not-ready even before auth status.
     if (githubAuthMode === GITHUB_AUTH_MODE_INJECTED_TOKEN && !injectedTokenPresent) {
+        const ambiguousRuntime = runtimeReport.runtimeModeReason === RUNTIME_REASON_CURSOR_MARKER_AMBIGUOUS;
         const detail = "injected-token mode requires GH_TOKEN, GITHUB_TOKEN, or GH_ENTERPRISE_TOKEN; " +
             `binary=${binary} present but SCM-dependent gates skipped ` +
-            `(runtime_mode=${runtimeReport.runtimeMode})`;
+            `(runtime_mode=${runtimeReport.runtimeMode}` +
+            `${runtimeReport.runtimeModeReason ? `, reason=${runtimeReport.runtimeModeReason}` : ""})`;
         return {
             ready: false,
             binary,
@@ -154,10 +163,15 @@ export function probeScmReadiness(options = {}) {
             authState: "missing-token",
             githubAuthMode,
             runtimeMode: runtimeReport.runtimeMode,
+            runtimeModeReason: runtimeReport.runtimeModeReason ?? null,
             injectedTokenPresent: false,
             depth,
             detail,
-            remediation: REMEDIATION_MISSING_TOKEN,
+            // An ambiguous Cursor runtime is the #3859 case: name the explicit opt-in
+            // here, because this is where the operator actually meets the block.
+            remediation: ambiguousRuntime
+                ? `${EXPLICIT_SELECTION_REMEDIATION}\n\n${REMEDIATION_MISSING_TOKEN}`
+                : REMEDIATION_MISSING_TOKEN,
             skippedGates: [...SCM_DEPENDENT_GATES],
             login: null,
             failureKind: "missing_injected_token",
@@ -192,6 +206,7 @@ export function probeScmReadiness(options = {}) {
             environ: env,
             runtimeReport,
             repo: options.repo,
+            expectedPrincipal: options.expectedPrincipal,
             runGh: deepRunner,
         });
         if (deep.ok) {
@@ -203,6 +218,7 @@ export function probeScmReadiness(options = {}) {
                 authState: "authenticated",
                 githubAuthMode: deep.githubAuthMode,
                 runtimeMode: runtimeReport.runtimeMode,
+                runtimeModeReason: runtimeReport.runtimeModeReason ?? null,
                 injectedTokenPresent,
                 depth,
                 detail: `SCM ready: ${binary} present, ${deep.githubAuthMode} authenticated${loginPart} (deep)`,
@@ -220,6 +236,7 @@ export function probeScmReadiness(options = {}) {
             authState,
             githubAuthMode: deep.githubAuthMode,
             runtimeMode: runtimeReport.runtimeMode,
+            runtimeModeReason: runtimeReport.runtimeModeReason ?? null,
             injectedTokenPresent,
             depth,
             detail: `SCM not ready: ${deep.detail}`,
@@ -241,6 +258,7 @@ export function probeScmReadiness(options = {}) {
             authState: "unknown",
             githubAuthMode,
             runtimeMode: runtimeReport.runtimeMode,
+            runtimeModeReason: runtimeReport.runtimeModeReason ?? null,
             injectedTokenPresent,
             depth,
             detail,
@@ -262,6 +280,7 @@ export function probeScmReadiness(options = {}) {
             authState: "unauthenticated",
             githubAuthMode,
             runtimeMode: runtimeReport.runtimeMode,
+            runtimeModeReason: runtimeReport.runtimeModeReason ?? null,
             injectedTokenPresent,
             depth,
             detail,
@@ -278,6 +297,7 @@ export function probeScmReadiness(options = {}) {
         authState: "authenticated",
         githubAuthMode,
         runtimeMode: runtimeReport.runtimeMode,
+        runtimeModeReason: runtimeReport.runtimeModeReason ?? null,
         injectedTokenPresent,
         depth,
         detail: `SCM ready: ${binary} present, ${githubAuthMode} authenticated (shallow)`,
@@ -296,6 +316,7 @@ export function scmReadinessToDict(report) {
         auth_state: report.authState,
         github_auth_mode: report.githubAuthMode,
         runtime_mode: report.runtimeMode,
+        runtime_mode_reason: report.runtimeModeReason,
         injected_token_present: report.injectedTokenPresent,
         depth: report.depth,
         detail: report.detail,
@@ -318,7 +339,14 @@ export function formatScmReadinessLines(report) {
     }
     lines.push(`[deft scm] ${report.detail}`);
     if (report.skippedGates.length > 0) {
-        lines.push(`[deft scm] skipped gates: ${report.skippedGates.join(", ")}`);
+        // Name the classification reason next to the skip: a silent skip is what
+        // makes this failure costly, because work-selection surfaces go dark (#3859).
+        const reason = report.runtimeModeReason ? ` (reason: ${report.runtimeModeReason})` : "";
+        lines.push(`[deft scm] skipped gates: ${report.skippedGates.join(", ")}${reason}`);
+        if (report.runtimeModeReason === RUNTIME_REASON_CURSOR_MARKER_AMBIGUOUS) {
+            lines.push(`[deft scm] runtime is ambiguous; set ${GITHUB_AUTH_MODE_ENV}=host-gh to authorize ` +
+                "the host gh credential store on a machine you control (#3859)");
+        }
     }
     lines.push("[deft scm] run SCM-dependent gates only after auth is ready, or from a matched env; " +
         "see content/scm/github.md § Mismatched/headless SCM readiness (#2275)");
@@ -381,13 +409,15 @@ export function requireScmReady(options = {}) {
     if (hermeticAuthSkip) {
         // Production path uses assertScmBinaryPresent (not test-only).
         const binary = assertScmBinaryPresent(options.whichFn);
+        const hermeticRuntime = options.runtimeReport ?? getPlatformCapabilities();
         const report = {
             ready: true,
             binary,
             binaryPath: options.whichFn?.(binary) ?? null,
             authState: "unknown",
             githubAuthMode: GITHUB_AUTH_MODE_HOST_GH,
-            runtimeMode: (options.runtimeReport ?? getPlatformCapabilities()).runtimeMode,
+            runtimeMode: hermeticRuntime.runtimeMode,
+            runtimeModeReason: hermeticRuntime.runtimeModeReason ?? null,
             injectedTokenPresent: findInjectedToken(options.env ?? process.env) !== null,
             depth: "shallow",
             detail: `SCM binary present (${binary}); auth status not checked (hermetic)`,

package/dist/scope/decompose.js

@@ -17,6 +17,7 @@ import { hasArtifactSuffix, LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, resolveL
 import { resolveRepo } from "../triage/queue/repo.js";
 import { referenceWithDefaultTrust, slugify } from "../vbrief-build/build.js";
 import { EMITTED_VBRIEF_VERSION } from "../vbrief-build/constants.js";
+import { READY_REQUIRES_PARALLEL_SAFE } from "../vbrief-validation/story-quality.js";
 import { formatCoverageReportLine, validateCoverageMap } from "./coverage-map.js";
 import { buildParentLineageArtifact } from "./parent-lineage.js";
 import { formatBriefJson } from "./vbrief-json.js";
@@ -407,7 +408,7 @@ export function storyQualityIssues(opts) {
         issues.push(...fileScopeIssues(swarm));
         issues.push(...verifyCommandIssues(swarm));
         if (swarm.parallel_safe === false) {
-            issues.push("readiness=ready requires parallel_safe=true; use readiness=sequential or needs_refinement for non-concurrent work");
+            issues.push(READY_REQUIRES_PARALLEL_SAFE);
         }
         if (swarm.file_scope_confidence === "low") {
             issues.push("readiness=ready requires file_scope_confidence above low");

package/dist/scope/delivery-evidence.d.ts

@@ -16,6 +16,29 @@ export declare const NON_DELIVERY_DISPOSITIONS: readonly ["cancelled", "supersed
 export type NonDeliveryDisposition = (typeof NON_DELIVERY_DISPOSITIONS)[number];
 /** Delivery verification outcome for completion provenance. */
 export type DeliveryDisposition = "delivered" | "merged_to_integration" | "not_delivered" | NonDeliveryDisposition | "unknown" | "unverified";
+/**
+ * This is a historical audit snapshot stamped onto
+ * `plan.metadata.completionProvenance` at `scope:complete` (#3041 / #3690).
+ *
+ * Completed xBRIEFs have full standing as a record of *what is* and zero
+ * authority over *what to build next* (#3383). Fields stay because they
+ * answer a later reconstruction question after branches are deleted and
+ * refs move. A field does not need a current production-code reader.
+ *
+ * Reconstruction groups:
+ * - Identity and location: `repository`, `implementationCommit`, `prNumber`,
+ *   `prBase`, `deliveryBranch`
+ * - Delivery evidence: `mergeCommit`, `deliveryCommit`, `disposition`,
+ *   `handoffState`
+ * - Verification attribution: `verifiedAt`, `verifier`
+ * - Explicit operator-supplied facts: `deployed`, `uatVerified` (never
+ *   inferred from Git)
+ *
+ * `completedSessionId` is duplicated. This nested copy is stamped so the
+ * snapshot is self-contained. Consumers (`verify:ac` /
+ * `session-completed-ac`) read the sibling
+ * `plan.metadata.completedSessionId`, not this field.
+ */
 export interface CompletionProvenance {
     readonly repository: string | null;
     readonly implementationCommit: string | null;
@@ -32,7 +55,10 @@ export interface CompletionProvenance {
     readonly deployed: boolean | null;
     /** Always null unless explicitly supplied — never inferred from Git (#3041). */
     readonly uatVerified: boolean | null;
-    /** Session that completed the brief; used by check to target xbrief/completed (#3357). */
+    /**
+     * Nested session correlation for a self-contained snapshot.
+     * Consumers read sibling `plan.metadata.completedSessionId`, not this field.
+     */
     readonly completedSessionId?: string | null;
 }
 export interface DeliveryEvidenceInput {

package/dist/scope/index.d.ts

@@ -8,6 +8,7 @@ export * from "./decomposed-refs.js";
 export * from "./delivery-evidence.js";
 export * from "./demote.js";
 export * from "./effort-activate-gate.js";
+export * from "./lifecycle-write.js";
 export * from "./main.js";
 export * from "./open-umbrella-warning.js";
 export * from "./parent-lineage.js";

package/dist/scope/index.js

@@ -8,6 +8,7 @@ export * from "./decomposed-refs.js";
 export * from "./delivery-evidence.js";
 export * from "./demote.js";
 export * from "./effort-activate-gate.js";
+export * from "./lifecycle-write.js";
 export * from "./main.js";
 export * from "./open-umbrella-warning.js";
 export * from "./parent-lineage.js";

package/dist/scope/lifecycle-write.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Transition-write fingerprint for completed/ artifacts (#3679).
+ *
+ * Distinct from completionProvenance (#3686): this only records that
+ * runTransition wrote the blob. Non-code-bearing completes and scope:fail
+ * stamp this and still omit delivery provenance.
+ */
+export declare const LIFECYCLE_WRITE_KEY: "lifecycleWrite";
+export type LifecycleWriteAction = "complete" | "fail";
+export interface LifecycleWriteStamp {
+    readonly action: LifecycleWriteAction;
+    readonly writtenAt: string;
+}
+/** Worker-facing leftover-land path after a scope-provenance strip (#3476 / #3679). */
+export declare const LEFTOVER_LAND_PR_REMEDIATION: string;
+/** Stamp that runTransition wrote this plan into completed/. */
+export declare function stampLifecycleWrite(plan: Record<string, unknown>, action: LifecycleWriteAction, writtenAt: string): void;
+/**
+ * True when a completed/ blob shows verb evidence.
+ * Accepts the new stamp, legacy completedAt (pre-#3679 complete), or failed status
+ * (scope:fail never stamped provenance and must keep passing).
+ */
+export declare function hasTransitionWrite(plan: Record<string, unknown>): boolean;
+//# sourceMappingURL=lifecycle-write.d.ts.map

package/dist/scope/lifecycle-write.js

@@ -0,0 +1,64 @@
+/**
+ * Transition-write fingerprint for completed/ artifacts (#3679).
+ *
+ * Distinct from completionProvenance (#3686): this only records that
+ * runTransition wrote the blob. Non-code-bearing completes and scope:fail
+ * stamp this and still omit delivery provenance.
+ */
+export const LIFECYCLE_WRITE_KEY = "lifecycleWrite";
+/** Worker-facing leftover-land path after a scope-provenance strip (#3476 / #3679). */
+export const LEFTOVER_LAND_PR_REMEDIATION = "After a provenance-gated product PR strips active/ from the change set, " +
+    "the designed remainder is a leftover land PR (#3476): run `task scope:complete` " +
+    "after merge (it can stamp a brief already in completed/), then land that artifact. " +
+    "Do not git-add a completed/ husk to skip the verb.";
+function asRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+function metadataRecord(plan) {
+    const existing = asRecord(plan.metadata);
+    if (existing !== null) {
+        return existing;
+    }
+    const created = {};
+    plan.metadata = created;
+    return created;
+}
+/** Stamp that runTransition wrote this plan into completed/. */
+export function stampLifecycleWrite(plan, action, writtenAt) {
+    const meta = metadataRecord(plan);
+    meta[LIFECYCLE_WRITE_KEY] = { action, writtenAt };
+}
+function hasLifecycleWriteStamp(plan) {
+    const meta = asRecord(plan.metadata);
+    if (meta === null) {
+        return false;
+    }
+    const stamp = asRecord(meta[LIFECYCLE_WRITE_KEY]);
+    if (stamp === null) {
+        return false;
+    }
+    const action = stamp.action;
+    const writtenAt = stamp.writtenAt;
+    return ((action === "complete" || action === "fail") &&
+        typeof writtenAt === "string" &&
+        writtenAt.trim().length > 0);
+}
+/**
+ * True when a completed/ blob shows verb evidence.
+ * Accepts the new stamp, legacy completedAt (pre-#3679 complete), or failed status
+ * (scope:fail never stamped provenance and must keep passing).
+ */
+export function hasTransitionWrite(plan) {
+    if (hasLifecycleWriteStamp(plan)) {
+        return true;
+    }
+    const meta = asRecord(plan.metadata);
+    if (meta !== null && typeof meta.completedAt === "string" && meta.completedAt.trim().length > 0) {
+        return true;
+    }
+    return String(plan.status ?? "") === "failed";
+}
+//# sourceMappingURL=lifecycle-write.js.map

package/dist/scope/main.js

@@ -17,10 +17,12 @@ import { findByDecisionId, isAlreadyUndone, REVERSIBLE_ACTIONS, undoBatch, undoO
 const LIFECYCLE_USAGE_STDERR = "usage: deft scope:<action> [file] [--batch] [--from-issue N] [--repo OWNER/NAME]\n" +
     "                          [--force] [--project-root PATH] [--strict] [--force-no-cache]\n" +
     "                          [--path PATH]\n" +
+    "  complete also accepts: --merge-commit SHA --pr N [--pr-base BRANCH] [--delivery-branch BRANCH]\n" +
     "  actions: activate, block, cancel, complete, fail, promote, restore, unblock\n" +
     "The verb already encodes the action (e.g. deft scope:promote <file>). Do not pass the action again.\n" +
     "(promote --batch may omit file and promotes all proposed/ scopes; #3011)\n" +
-    "(promote --from-issue=N may omit file; #1136)\n";
+    "(promote --from-issue=N may omit file; #1136)\n" +
+    "(complete --merge-commit / --pr are required for code-bearing delivery evidence; #3041 / #3721)\n";
 function parseLifecycleArgv(argv) {
     if (argv.length < 1) {
         return { args: null, error: "usage" };

package/dist/scope/project-definition-sync.js

@@ -1,16 +1,23 @@
 import { dirname, resolve } from "node:path";
-import { resolveProjectDefinitionPath } from "../layout/resolve.js";
-import { atomicWriteProjectDefinition, loadProjectDefinitionForMutation, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
+import { withProjectDefinitionMutation } from "../vbrief-build/project-definition-mutation.js";
 import { syncRegistryArtifactAfterScopeMove } from "./registry-artifact-sync.js";
 /** Fail-closed sync of PROJECT-DEFINITION after a lifecycle move (#1527 / #2131). */
 export function syncProjectDefinitionAfterScopeMove(scopeData, oldPath, newPath, vbriefRoot, targetStatus) {
     const projectRoot = dirname(resolve(vbriefRoot));
     try {
-        projectDefinitionMutationLock(projectRoot, () => {
-            const projectDefPath = resolveProjectDefinitionPath(projectRoot);
-            syncRegistryArtifactAfterScopeMove(projectDefPath, scopeData, oldPath, newPath, vbriefRoot, targetStatus, {
-                loadForMutation: () => loadProjectDefinitionForMutation(projectRoot),
-                persist: (path, data) => atomicWriteProjectDefinition(path, data),
+        withProjectDefinitionMutation(projectRoot, (mutation) => {
+            syncRegistryArtifactAfterScopeMove(
+            // The artifact the lock captured, not an independent re-resolution (#3796).
+            mutation.artifactPath, scopeData, oldPath, newPath, vbriefRoot, targetStatus, {
+                loadForMutation: () => [mutation.load(), mutation.artifactPath],
+                persist: (path, data) => {
+                    // The registry sync echoes back the path it was handed, so a
+                    // mismatch means something re-resolved the artifact mid-section.
+                    if (resolve(path) !== resolve(mutation.artifactPath)) {
+                        throw new Error("refusing to persist PROJECT-DEFINITION to a path other than the locked artifact");
+                    }
+                    mutation.persist(data);
+                },
             });
         });
         return null;

package/dist/scope/transition.js

@@ -16,6 +16,7 @@ import { LIFECYCLE_FOLDERS, MOVE_LABELS, STATUS_PRECONDITIONS, STAY_LABELS, TRAN
 import { detectLifecycleFolder, updateDecomposedChildBackReferences, updateDecomposedParentBackReferences, } from "./decomposed-refs.js";
 import { classifyStoredDeliveryDisposition, evaluateDeliveryGate, resolveCompletionSessionId, stampDeliveryProvenance, } from "./delivery-evidence.js";
 import { evaluateEffortActivateGate } from "./effort-activate-gate.js";
+import { stampLifecycleWrite } from "./lifecycle-write.js";
 import { syncProjectDefinitionAfterScopeMove } from "./project-definition-sync.js";
 import { syncSpecificationAfterScopeMove } from "./specification-sync.js";
 import { utcNowIso } from "./vbrief-json.js";
@@ -81,7 +82,9 @@ export function runTransition(action, filePath, now = new Date(), options = {})
         };
     }
     const { allowedSources, targetFolder, targetStatus } = TRANSITIONS[act];
-    if (!allowedSources.includes(currentFolder)) {
+    const restampCompleted = act === "complete" && currentFolder === "completed";
+    if (!restampCompleted &&
+        !allowedSources.includes(currentFolder)) {
         const allowedStr = allowedSources.map((s) => `${s}/`).join(", ");
         return {
             ok: false,
@@ -103,15 +106,9 @@ export function runTransition(action, filePath, now = new Date(), options = {})
     const requiredStatus = STATUS_PRECONDITIONS[act];
     if (requiredStatus !== undefined) {
         if (currentStatus === targetStatus) {
-            // Surface legacy delivery disposition on already-completed briefs (#3041).
-            let dispositionSuffix = "";
-            if (act === "complete" && currentFolder === "completed") {
-                const disposition = classifyStoredDeliveryDisposition(planObj);
-                dispositionSuffix = ` (deliveryDisposition=${disposition})`;
-            }
             return {
                 ok: true,
-                message: `No-op: ${basename} is already ${targetStatus} in ${currentFolder}/${dispositionSuffix}`,
+                message: `No-op: ${basename} is already ${targetStatus} in ${currentFolder}/`,
             };
         }
         if (currentStatus !== requiredStatus) {
@@ -122,14 +119,30 @@ export function runTransition(action, filePath, now = new Date(), options = {})
             };
         }
     }
+    const nowIso = utcNowIso(now);
+    const vbriefRoot = dirname(dirname(resolvedPath));
+    const projectRoot = dirname(vbriefRoot);
+    // #3679: lift #3041 already-completed handling out of STATUS_PRECONDITIONS
+    // so complete can stamp a brief already in completed/ without a folder trip.
+    if (restampCompleted) {
+        return restampCompletedBrief({
+            resolvedPath,
+            basename,
+            data,
+            planObj,
+            projectRoot,
+            vbriefRoot,
+            now,
+            nowIso,
+            options,
+        });
+    }
     if (targetFolder !== null && targetFolder === currentFolder) {
         return {
             ok: true,
             message: `No-op: ${basename} is already in ${currentFolder}/ (status: ${currentStatus})`,
         };
     }
-    const vbriefRoot = dirname(dirname(resolvedPath));
-    const projectRoot = dirname(vbriefRoot);
     if (targetFolder !== null) {
         const destDir = join(vbriefRoot, targetFolder);
         try {
@@ -144,7 +157,6 @@ export function runTransition(action, filePath, now = new Date(), options = {})
             throw err;
         }
     }
-    const nowIso = utcNowIso(now);
     // #3360: hand-authored briefs run #3323 clause derivation on activate/promote.
     // #3355: stamp is state-observed (before vs after), not derivation-notice-bound.
     const previousAcceptance = planObj.acceptance;
@@ -190,6 +202,7 @@ export function runTransition(action, filePath, now = new Date(), options = {})
                 ? { ...gate.provenance, completedSessionId: sessionId }
                 : gate.provenance);
         }
+        stampLifecycleWrite(planObj, "complete", nowIso);
     }
     // #3240: per-criterion typed evidence or human-origin disposition before auto-advance.
     let acceptanceReports;
@@ -266,6 +279,9 @@ export function runTransition(action, filePath, now = new Date(), options = {})
             };
         }
     }
+    if (act === "fail") {
+        stampLifecycleWrite(planObj, "fail", nowIso);
+    }
     const formatted = formatBriefJson(data);
     const crud = new InstrumentedVbriefCrud({ now: () => now });
     if (targetFolder !== null) {
@@ -370,6 +386,69 @@ export function runTransition(action, filePath, now = new Date(), options = {})
         acceptanceReports,
     };
 }
+/**
+ * Stamp a brief already in completed/ (#3679). Runs the #3041 delivery gate
+ * and writes in place so recovery does not need a folder round-trip.
+ * The #3041 deliveryDisposition suffix now actually executes for complete.
+ */
+function restampCompletedBrief(args) {
+    const { resolvedPath, basename, data, planObj, projectRoot, vbriefRoot, now, nowIso, options } = args;
+    const gate = evaluateDeliveryGate({
+        projectRoot,
+        plan: planObj,
+        nowIso,
+        evidence: options.deliveryEvidence,
+        nonDeliveryDisposition: options.nonDeliveryDisposition,
+        runGit: options.runGit,
+        verifier: options.verifier ?? "scope:complete",
+        assumeEvidenceValidated: options.assumeEvidenceValidated,
+    });
+    if (!gate.ok) {
+        return { ok: false, message: gate.message };
+    }
+    if (gate.provenance !== null) {
+        const sessionId = resolveCompletionSessionId(projectRoot);
+        stampDeliveryProvenance(planObj, sessionId !== null ? { ...gate.provenance, completedSessionId: sessionId } : gate.provenance);
+    }
+    planObj.status = "completed";
+    planObj.updated = nowIso;
+    stampEnvelopeUpdated(data, nowIso);
+    stampCompletionMetadata(planObj, projectRoot, nowIso, {
+        completedSessionId: resolveCompletionSessionId(projectRoot),
+    });
+    stampLifecycleWrite(planObj, "complete", nowIso);
+    const writeResult = atomicWriteBrief(resolvedPath, data, vbriefRoot, { projectRoot });
+    if (!writeResult.ok) {
+        return { ok: false, message: writeResult.message };
+    }
+    const crud = new InstrumentedVbriefCrud({ now: () => now });
+    crud.recordTrustedUpdate(resolvedPath, formatBriefJson(data));
+    try {
+        persistCrudMetrics(projectRoot, crud.getMetrics());
+    }
+    catch {
+        /* best-effort telemetry persistence */
+    }
+    const sessionId = resolveCompletionSessionId(projectRoot);
+    if (sessionId !== null) {
+        try {
+            writeSessionCompletedMarker(projectRoot, {
+                path: resolvedPath,
+                sessionId,
+                completedAt: nowIso,
+            });
+        }
+        catch {
+            return { ok: false, message: SESSION_COMPLETED_AC_REMEDIATION };
+        }
+    }
+    const disposition = classifyStoredDeliveryDisposition(planObj);
+    return {
+        ok: true,
+        message: `Restamped ${basename} in completed/ (status: completed, ` +
+            `deliveryDisposition=${disposition})`,
+    };
+}
 export function recordWipCapOverride(filePath, projectRoot, check, now = new Date()) {
     try {
         const rel = resolve(filePath).startsWith(resolve(projectRoot))

package/dist/scope-provenance/evaluate.js

@@ -209,7 +209,11 @@ function remediationForExpansion() {
         "`.deft/approved-scope/<plan-id>.json` with a humanApproval stamp). Commit that " +
         "approval on the merge base (or a prior PR) before expanding or activating the " +
         "scoped xBRIEF in the implementation change set. Editing the active xBRIEF alone " +
-        "does not authorize new paths (#3145 / #3205). See content/docs/scope-provenance.md.");
+        "does not authorize new paths (#3145 / #3205). See content/docs/scope-provenance.md. " +
+        "If you cannot mint a digest (human TTY required), drop active/ from this product " +
+        "change set and land the completed artifact in a leftover land PR after merge (#3476). " +
+        "Run `task scope:complete` on the brief (it can stamp a file already in completed/). " +
+        "Do not git-add a completed/ husk to skip that PR (#3679).");
 }
 /**
  * Parse + lightly validate an approved-scope JSON blob (base-ref `git show` or disk).