@deftai/directive-core 0.105.0 → 0.107.0

package/dist/scm/main.js

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import { extractFlag } from "./argv.js";
 import { buildCommand } from "./build-command.js";
 import { REST_OPT_IN_VERBS } from "./constants.js";
+import { DESIGN_CRITIQUE_CHIP_VERB, runDesignCritiqueChip } from "./design-critique-chip.js";
 import { ScmStubError } from "./errors.js";
 import { requireScmReady } from "./readiness.js";
 import { runRestList, runRestView } from "./rest-dispatch.js";
@@ -30,13 +31,26 @@ function guardScmReady(options) {
 export function main(argv, options = {}) {
     if (argv.length < 2) {
         process.stderr.write("usage: scm.py <namespace> <verb> [pass-through args...]\n" +
-            "       (v1 stub: namespace=issue, verb=list|view|close|edit)\n" +
+            "       (v1 stub: namespace=issue, verb=list|view|close|edit|design-critique-chip)\n" +
             "       --rest opt-in is supported on issue view/list (#976)\n");
         return 2;
     }
     const namespace = argv[0] ?? "";
     const verb = argv[1] ?? "";
     let extra = argv.slice(2);
+    if (namespace === "issue" && verb === DESIGN_CRITIQUE_CHIP_VERB) {
+        const blocked = guardScmReady(options);
+        if (blocked !== null)
+            return blocked;
+        const result = runDesignCritiqueChip(extra, { client: options.labelClient });
+        if (result.stdout.length > 0) {
+            process.stdout.write(result.stdout);
+        }
+        if (result.stderr.length > 0) {
+            process.stderr.write(result.stderr);
+        }
+        return result.exitCode;
+    }
     const [restMode, afterRest] = extractFlag(extra, "--rest");
     extra = afterRest;
     if (restMode) {

package/dist/scm/readiness-cli.d.ts

@@ -10,6 +10,8 @@ export interface ScmReadinessCliArgs {
     readonly deep?: boolean;
     readonly depth?: ScmProbeDepth;
     readonly help?: boolean;
+    readonly repo?: string;
+    readonly expectedLogin?: string;
 }
 export declare function parseScmReadinessArgs(argv: readonly string[]): {
     args: ScmReadinessCliArgs;

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";
@@ -64,6 +64,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

@@ -105,7 +105,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";
@@ -192,6 +197,7 @@ export function probeScmReadiness(options = {}) {
             environ: env,
             runtimeReport,
             repo: options.repo,
+            expectedPrincipal: options.expectedPrincipal,
             runGh: deepRunner,
         });
         if (deep.ok) {

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

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { dirname } from "node:path";
 import { maybeRunStalenessTickler } from "../staleness-tickler/run.js";
+import { interceptHelp } from "../triage/help/index.js";
 import { reconcileUmbrellas, renderUmbrellasReport } from "../vbrief-reconcile/umbrellas.js";
 import { canonicalLogPath, readAll } from "./audit-log.js";
 import { batchPromote } from "./batch-promote.js";
@@ -13,14 +14,15 @@ import { promoteFromIssue } from "./promote-from-issue.js";
 import { promotePath } from "./promote-path.js";
 import { runTransition } from "./transition.js";
 import { findByDecisionId, isAlreadyUndone, REVERSIBLE_ACTIONS, undoBatch, undoOne, } from "./undo.js";
-const LIFECYCLE_USAGE_STDERR = "usage: scope_lifecycle.py [-h] [--project-root PROJECT_ROOT] [--force] [--batch]\n" +
-    "                          [--from-issue N] [--repo OWNER/NAME] [--strict] [--force-no-cache]\n" +
+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" +
-    "                          {activate,block,cancel,complete,fail,promote,restore,unblock}\n" +
-    "                          [file ...]\n" +
-    "scope_lifecycle.py: error: the following arguments are required: action, file\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" };
@@ -50,6 +52,8 @@ function parseLifecycleArgv(argv) {
         if (arg === undefined) {
             return { args: null, error: "usage" };
         }
+        if (arg === "--")
+            continue;
         if (arg === "--force") {
             force = true;
         }
@@ -236,6 +240,14 @@ function parseLifecycleArgv(argv) {
 }
 /** Main entry for scope_lifecycle.py parity. */
 export function lifecycleMain(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        const helpRc = interceptHelp("scope_lifecycle", argv);
+        if (helpRc !== null) {
+            return helpRc;
+        }
+        process.stdout.write(LIFECYCLE_USAGE_STDERR);
+        return 0;
+    }
     const parsed = parseLifecycleArgv(argv);
     if (parsed.args === null) {
         if (parsed.error === "usage") {

package/dist/scope/promote-from-issue.js

@@ -195,7 +195,7 @@ export function promoteFromIssue(options) {
                 return {
                     ok: false,
                     message: `No triage-cache decision for #${n} (${repoSafe}). ` +
-                        `Accept first: task triage:accept -- --issue ${n} --repo ${repoSafe} ` +
+                        `Accept first: deft triage:accept --issue ${n} --repo ${repoSafe} ` +
                         `(or omit --strict to soft-warn and proceed; --force-no-cache skips the gate).`,
                     exitCode: 1,
                     warnings,
@@ -212,7 +212,7 @@ export function promoteFromIssue(options) {
                 ok: false,
                 message: `Refusing promote for #${n} (${repoSafe}): latest triage decision is '${sanitizeMsg(latest.decision)}' ` +
                     `(decision_id=${latest.decision_id}). ` +
-                    `Accept first: task triage:accept -- --issue ${n} --repo ${repoSafe} ` +
+                    `Accept first: deft triage:accept --issue ${n} --repo ${repoSafe} ` +
                     `or override with --force-no-cache.`,
                 exitCode: 1,
                 warnings,
@@ -315,8 +315,8 @@ export function promoteFromIssue(options) {
         return {
             ok: false,
             message: `No proposed/ scope artifact found for issue #${n} (${repoSafe}). ` +
-                `Ingest first (task triage:accept -- --issue ${n} --repo ${repoSafe}) ` +
-                `or pass an explicit path: task scope:promote -- <path>.`,
+                `Ingest first (deft triage:accept --issue ${n} --repo ${repoSafe}) ` +
+                `or pass an explicit path: deft scope:promote <path>.`,
             exitCode: 1,
             warnings,
             repo,
@@ -330,7 +330,7 @@ export function promoteFromIssue(options) {
         return {
             ok: false,
             message: `Multiple proposed/ artifacts match issue #${n}; refuse to guess.\n${list}\n` +
-                `Promote one path explicitly: task scope:promote -- <path> ` +
+                `Promote one path explicitly: deft scope:promote <path> ` +
                 `or re-run with --path <one-of-the-above>.`,
             exitCode: 1,
             warnings,

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

@@ -205,11 +205,15 @@ function listActiveXbriefPaths(projectRoot) {
 }
 function remediationForExpansion() {
     return ("Renew human approval: re-record the approved-scope digest after operator review " +
-        "(`task scope:record-approved-scope -- <xbrief-path> --actor <you>` writes " +
+        "(`task scope:record-approved-scope -- <xbrief-path> --actor <you> --confirm` writes " +
         "`.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).
@@ -344,7 +348,7 @@ export function evaluateOneScopeProvenance(input) {
                 detail: "active xBRIEF modified with a non-human (agent/missing) approved-scope stamp; " +
                     "only humanApproval stamps authorize non-empty file_scope",
                 remediation: "Record a human-origin approval via `task scope:record-approved-scope -- " +
-                    "<xbrief-path> --actor <you>` (#3145 / #3205).",
+                    "<xbrief-path> --actor <you> --confirm` (#3145 / #3205).",
             };
         }
     }
@@ -361,7 +365,7 @@ export function evaluateOneScopeProvenance(input) {
                 detail: "active xBRIEF modified with a non-human approved-scope stamp (scope shrink/noise path); " +
                     "only humanApproval stamps authorize non-empty file_scope",
                 remediation: "Record a human-origin approval via `task scope:record-approved-scope -- " +
-                    "<xbrief-path> --actor <you>` (#3145 / #3205).",
+                    "<xbrief-path> --actor <you> --confirm` (#3145 / #3205).",
             };
         }
         return null;

package/dist/session/ac-pass-banking.d.ts

@@ -173,6 +173,11 @@ export interface MaybeBankOnAcPassInput {
     readonly executableRuns: number;
     readonly quiet?: boolean;
     readonly productStateHash?: string | null;
+    /**
+     * Bank a verified-pass walk even when no shell runs were recorded (#3558).
+     * Soft/advisory empty passes still skip via executableRuns === 0.
+     */
+    readonly verifiedPass?: boolean;
 }
 export interface MaybeBankOnAcPassResult {
     readonly banked: boolean;