@deftai/directive-core 0.104.0 → 0.106.0

package/dist/scope/delivery-evidence.js

@@ -175,7 +175,7 @@ export function verifyDeliveryAncestry(projectRoot, mergeCommit, deliveryBranch,
         return {
             ok: false,
             error: `merge commit ${mergeCommit} is not an ancestor of refreshed remote delivery ref ` +
-                `${refresh.remoteRef} (${remoteTip}). Intermediate/integration-only merges are not delivery evidence (#3041).`,
+                `${refresh.remoteRef} (${remoteTip}).`,
             remoteTip,
         };
     }
@@ -199,14 +199,21 @@ function buildProvenance(input) {
         uatVerified: e.uatVerified ?? null,
     };
 }
+function deliveryEvidenceRemediation(deliveryBranch) {
+    return (`Pass scope:complete -- --merge-commit <sha> (and --pr <n> if you have one). ` +
+        `When develop is the real delivery target, type plan.policy.deliveryBranch ` +
+        `(task policy:show --field=deliveryBranch). ` +
+        `When ${deliveryBranch} is delivery, wait until the merge commit is an ancestor of ` +
+        `origin/${deliveryBranch}, then complete. Do not use --non-delivery for work that shipped.`);
+}
 /**
- * Gate delivered completion for a code-bearing scope (#3041).
+ * Gate delivered completion for a code-bearing scope (#3041 / #3380).
  *
  * Returns ok=true with provenance when:
  * - scope is not code-bearing (provenance may be null or non-code note), OR
  * - explicit non-delivery disposition is provided, OR
- * - durable delivery evidence validates (PR base == deliveryBranch, merge commit
- *   ancestor of refreshed remote delivery ref).
+ * - merge commit is an ancestor of the refreshed remote delivery ref (prBase is
+ *   provenance only; it need not equal deliveryBranch).
  */
 export function evaluateDeliveryGate(options) {
     const runGit = options.runGit ?? defaultGitRunner;
@@ -267,10 +274,8 @@ export function evaluateDeliveryGate(options) {
         return {
             ok: false,
             message: `Delivery evidence required for code-bearing scope completion (#3041). ` +
-                `Provide merge/PR delivery proof (merge commit ancestor of remote ` +
-                `'${deliveryBranch}') or an explicit --non-delivery disposition ` +
-                `(${NON_DELIVERY_DISPOSITIONS.join("|")}). ` +
-                `Merged-to-integration alone is not delivery.`,
+                `A merge commit that is an ancestor of refreshed origin/${deliveryBranch} is delivery; ` +
+                `PR base is provenance only. ${deliveryEvidenceRemediation(deliveryBranch)}`,
             provenance: null,
             codeBearing: true,
         };
@@ -294,27 +299,11 @@ export function evaluateDeliveryGate(options) {
             };
         }
     }
-    if (prBase !== null && prBase !== deliveryBranch) {
-        const provenance = buildProvenance({
-            evidence,
-            deliveryBranch,
-            disposition: "merged_to_integration",
-            handoffState: "merged_to_integration",
-            nowIso: options.nowIso,
-            verifier,
-        });
-        return {
-            ok: false,
-            message: `PR base '${prBase}' is not the configured delivery branch '${deliveryBranch}'. ` +
-                `A merge into an intermediate/feature/integration branch is not delivery evidence (#3041).`,
-            provenance,
-            codeBearing: true,
-        };
-    }
     if (mergeCommit === null) {
         return {
             ok: false,
-            message: "Delivery evidence missing merge_commit_sha; cannot prove ancestry on delivery branch (#3041).",
+            message: "Delivery evidence missing merge_commit_sha; cannot prove ancestry on delivery branch (#3041). " +
+                deliveryEvidenceRemediation(deliveryBranch),
             provenance: null,
             codeBearing: true,
         };
@@ -339,9 +328,15 @@ export function evaluateDeliveryGate(options) {
     const ancestry = verifyDeliveryAncestry(options.projectRoot, mergeCommit, deliveryBranch, runGit);
     if (!ancestry.ok) {
         const integrationOnly = prBase !== null && prBase !== deliveryBranch;
+        const ancestryMsg = ancestry.error ?? "delivery ancestry check failed";
+        const rem = deliveryEvidenceRemediation(deliveryBranch);
+        const message = integrationOnly
+            ? `${ancestryMsg} PR base '${prBase}' is provenance only; ` +
+                `the merge is not yet on origin/${deliveryBranch}. ${rem}`
+            : `${ancestryMsg} ${rem}`;
         return {
             ok: false,
-            message: ancestry.error ?? "delivery ancestry check failed",
+            message,
             provenance: buildProvenance({
                 evidence,
                 deliveryBranch,

package/dist/scope/index.d.ts

@@ -12,6 +12,7 @@ export * from "./main.js";
 export * from "./open-umbrella-warning.js";
 export * from "./parent-lineage.js";
 export * from "./project-context.js";
+export * from "./project-invariant-coverage.js";
 export * from "./promote-from-issue.js";
 export * from "./promote-path.js";
 export * from "./transition.js";

package/dist/scope/index.js

@@ -12,6 +12,7 @@ export * from "./main.js";
 export * from "./open-umbrella-warning.js";
 export * from "./parent-lineage.js";
 export * from "./project-context.js";
+export * from "./project-invariant-coverage.js";
 export * from "./promote-from-issue.js";
 export * from "./promote-path.js";
 export * from "./transition.js";

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,12 +14,11 @@ 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" +
+    "  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";
 function parseLifecycleArgv(argv) {
@@ -50,6 +50,8 @@ function parseLifecycleArgv(argv) {
         if (arg === undefined) {
             return { args: null, error: "usage" };
         }
+        if (arg === "--")
+            continue;
         if (arg === "--force") {
             force = true;
         }
@@ -236,6 +238,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/parent-lineage.js

@@ -98,20 +98,21 @@ export function extractChildCoverageDraft(child) {
     candidates.push({ source: "plan", obj: plan });
     candidates.push({ source: "root", obj: root });
     for (const c of candidates) {
+        const nestedCoverage = asRecord(c.obj.coverage);
         const hasMap = "coverage_map" in c.obj ||
             "coverageMap" in c.obj ||
-            asRecord(c.obj.coverage)?.coverage_map !== undefined;
+            nestedCoverage?.coverage_map !== undefined ||
+            nestedCoverage?.coverageMap !== undefined;
         if (!hasMap)
             continue;
-        const coverageNested = asRecord(c.obj.coverage);
         const coverage_map = c.obj.coverage_map ??
             c.obj.coverageMap ??
-            coverageNested?.coverage_map ??
-            coverageNested?.coverageMap;
+            nestedCoverage?.coverage_map ??
+            nestedCoverage?.coverageMap;
         const behavioral_deltas = c.obj.behavioral_deltas ??
             c.obj.behavioralDeltas ??
-            coverageNested?.behavioral_deltas ??
-            coverageNested?.behavioralDeltas;
+            nestedCoverage?.behavioral_deltas ??
+            nestedCoverage?.behavioralDeltas;
         return {
             draft: {
                 coverage_map,

package/dist/scope/project-invariant-coverage.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Project-invariant coverage + applicability (#3425 Story A).
+ *
+ * Reuses the #3238 coverage_map parser and side-field rules. `split` is
+ * excluded at project level. Optional `not_applicable` requires a reason.
+ * Applicability is a pure intersection of contract surface × file_scope.
+ */
+import type { ProjectInvariant } from "../policy/project-invariants.js";
+export declare const PROJECT_INVARIANT_DISPOSITIONS: readonly ["covered", "deferred", "behavioral_delta", "not_applicable"];
+export type ProjectInvariantDisposition = (typeof PROJECT_INVARIANT_DISPOSITIONS)[number];
+export interface ApplicableInvariant {
+    readonly id: string;
+    readonly reason: "path" | "module" | "unresolved-module";
+}
+export interface ProjectInvariantCoverageResult {
+    readonly ok: boolean;
+    readonly applicableIds: readonly string[];
+    readonly missingIds: readonly string[];
+    readonly errors: readonly string[];
+}
+export type GlobDepth = "exact" | "one" | "subtree";
+export interface ClassifiedGlob {
+    readonly prefix: string;
+    readonly depth: GlobDepth;
+    readonly leadingDoubleStar: boolean;
+}
+/**
+ * Classify a path/glob without regular expressions (CodeQL js/polynomial-redos).
+ * Unstarred paths are directory prefixes (file_scope semantics).
+ */
+export declare function classifyGlob(glob: string): ClassifiedGlob;
+/** Strip glob tails so prefix comparison stays path-shaped. */
+export declare function normalizeGlobAsPath(glob: string): string;
+/**
+ * True when two path/glob strings can name a shared tree.
+ * `/*` is one segment; `/**` / unstarred file_scope paths are subtrees.
+ */
+export declare function pathGlobsIntersect(left: string, right: string): boolean;
+/**
+ * Invariants whose contract surface intersects `fileScope`.
+ * Empty file_scope → empty intersection (no disposition required).
+ * Unresolved module ids (no pathGlobs mapping) are treated as applicable.
+ */
+export declare function applicableProjectInvariants(invariants: readonly ProjectInvariant[], fileScope: readonly string[], modulePathGlobs?: Readonly<Record<string, readonly string[]>>): ApplicableInvariant[];
+/**
+ * Completeness of coverage_map dispositions for applicable project invariant IDs.
+ * Extra coverage_map keys (e.g. parent requirement IDs) are ignored.
+ * Empty applicable set is a no-op success.
+ */
+export declare function validateProjectInvariantCoverage(opts: {
+    applicableIds: readonly string[];
+    draft: unknown;
+}): ProjectInvariantCoverageResult;
+//# sourceMappingURL=project-invariant-coverage.d.ts.map

package/dist/scope/project-invariant-coverage.js

@@ -0,0 +1,322 @@
+/**
+ * Project-invariant coverage + applicability (#3425 Story A).
+ *
+ * Reuses the #3238 coverage_map parser and side-field rules. `split` is
+ * excluded at project level. Optional `not_applicable` requires a reason.
+ * Applicability is a pure intersection of contract surface × file_scope.
+ */
+import { matchPath, normalizePath } from "../orchestration/pathspec.js";
+import { parseBehavioralDeltas, parseCoverageMap } from "./coverage-map.js";
+export const PROJECT_INVARIANT_DISPOSITIONS = [
+    "covered",
+    "deferred",
+    "behavioral_delta",
+    "not_applicable",
+];
+function asRecord(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/**
+ * Classify a path/glob without regular expressions (CodeQL js/polynomial-redos).
+ * Unstarred paths are directory prefixes (file_scope semantics).
+ */
+export function classifyGlob(glob) {
+    let p = normalizePath(glob).trim();
+    if (p.endsWith("/"))
+        p = p.slice(0, -1);
+    if (p === "**") {
+        return { prefix: "", depth: "subtree", leadingDoubleStar: true };
+    }
+    if (p.startsWith("**/")) {
+        let rest = p.slice(3);
+        if (rest.endsWith("/*"))
+            rest = rest.slice(0, -2);
+        const inner = rest.indexOf("/**");
+        if (inner >= 0)
+            rest = rest.slice(0, inner);
+        return { prefix: rest, depth: "subtree", leadingDoubleStar: true };
+    }
+    const starStar = p.indexOf("/**");
+    if (starStar >= 0) {
+        return { prefix: p.slice(0, starStar), depth: "subtree", leadingDoubleStar: false };
+    }
+    if (p.endsWith("/*")) {
+        return { prefix: p.slice(0, -2), depth: "one", leadingDoubleStar: false };
+    }
+    if (p.includes("*") || p.includes("?")) {
+        const slashStar = p.indexOf("/*");
+        if (slashStar >= 0) {
+            return { prefix: p.slice(0, slashStar), depth: "subtree", leadingDoubleStar: false };
+        }
+        return { prefix: p, depth: "subtree", leadingDoubleStar: false };
+    }
+    return { prefix: p, depth: "subtree", leadingDoubleStar: false };
+}
+/** Strip glob tails so prefix comparison stays path-shaped. */
+export function normalizeGlobAsPath(glob) {
+    return classifyGlob(glob).prefix;
+}
+function remainderUnder(child, parent) {
+    if (child === parent)
+        return "";
+    const stem = parent.length === 0 ? "" : `${parent}/`;
+    if (parent.length === 0)
+        return child;
+    if (!child.startsWith(stem))
+        return null;
+    return child.slice(stem.length);
+}
+function depthAllows(depth, remainder) {
+    if (depth === "subtree")
+        return true;
+    if (depth === "exact")
+        return remainder.length === 0;
+    return remainder.length > 0 && !remainder.includes("/");
+}
+/**
+ * True when two path/glob strings can name a shared tree.
+ * `/*` is one segment; `/**` / unstarred file_scope paths are subtrees.
+ */
+export function pathGlobsIntersect(left, right) {
+    const a = normalizePath(left).trim();
+    const b = normalizePath(right).trim();
+    if (a.length === 0 || b.length === 0)
+        return false;
+    if (a === b)
+        return true;
+    if (matchPath(a, b) || matchPath(b, a))
+        return true;
+    const ca = classifyGlob(a);
+    const cb = classifyGlob(b);
+    if (ca.prefix.length === 0 && cb.prefix.length === 0)
+        return true;
+    const aUnderB = remainderUnder(ca.prefix, cb.prefix);
+    if (aUnderB !== null && depthAllows(cb.depth, aUnderB))
+        return true;
+    const bUnderA = remainderUnder(cb.prefix, ca.prefix);
+    if (bUnderA !== null && depthAllows(ca.depth, bUnderA))
+        return true;
+    if (ca.leadingDoubleStar && suffixMatch(cb.prefix, ca.prefix))
+        return true;
+    if (cb.leadingDoubleStar && suffixMatch(ca.prefix, cb.prefix))
+        return true;
+    return false;
+}
+function suffixMatch(path, suffix) {
+    if (suffix.length === 0 || path.length === 0)
+        return false;
+    return path === suffix || path.endsWith(`/${suffix}`);
+}
+function surfacePaths(invariant, modulePathGlobs) {
+    const paths = [...invariant.contractSurface.paths];
+    const unresolvedModuleIds = [];
+    for (const moduleId of invariant.contractSurface.moduleIds) {
+        const mapped = modulePathGlobs[moduleId];
+        if (mapped === undefined || mapped.length === 0) {
+            unresolvedModuleIds.push(moduleId);
+            continue;
+        }
+        paths.push(...mapped);
+    }
+    return { paths, unresolvedModuleIds };
+}
+function anyPathOverlap(left, right) {
+    for (const a of left) {
+        for (const b of right) {
+            if (pathGlobsIntersect(a, b))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Invariants whose contract surface intersects `fileScope`.
+ * Empty file_scope → empty intersection (no disposition required).
+ * Unresolved module ids (no pathGlobs mapping) are treated as applicable.
+ */
+export function applicableProjectInvariants(invariants, fileScope, modulePathGlobs = {}) {
+    const scope = fileScope.map((s) => s.trim()).filter((s) => s.length > 0);
+    if (scope.length === 0)
+        return [];
+    const out = [];
+    for (const invariant of invariants) {
+        const { paths, unresolvedModuleIds } = surfacePaths(invariant, modulePathGlobs);
+        if (unresolvedModuleIds.length > 0) {
+            out.push({ id: invariant.id, reason: "unresolved-module" });
+            continue;
+        }
+        if (anyPathOverlap(paths, scope)) {
+            const viaModule = invariant.contractSurface.moduleIds.length > 0 && paths.length > 0;
+            out.push({
+                id: invariant.id,
+                reason: viaModule && invariant.contractSurface.paths.length === 0 ? "module" : "path",
+            });
+        }
+    }
+    return out;
+}
+function peelNotApplicable(raw) {
+    const notApplicable = [];
+    const errors = [];
+    if (raw === null || raw === undefined) {
+        return { remainder: raw, notApplicable, errors };
+    }
+    const takeReason = (body) => {
+        const nested = asRecord(body.provenance);
+        const reason = nested?.reason ?? body.reason;
+        return isNonEmptyString(reason) ? reason.trim() : null;
+    };
+    if (Array.isArray(raw)) {
+        const remainder = [];
+        for (let i = 0; i < raw.length; i += 1) {
+            const item = raw[i];
+            const loc = `coverage_map[${i}]`;
+            const rec = asRecord(item);
+            if (rec === null) {
+                remainder.push(item);
+                continue;
+            }
+            const disposition = rec.disposition;
+            if (typeof disposition === "string" &&
+                disposition.trim().toLowerCase() === "not_applicable") {
+                const id = rec.parent_requirement_id ?? rec.parentRequirementId ?? rec.id;
+                if (!isNonEmptyString(id)) {
+                    errors.push(`${loc}: parent_requirement_id is required`);
+                    continue;
+                }
+                const reason = takeReason(rec);
+                if (reason === null) {
+                    errors.push(`${loc}: disposition not_applicable requires reason`);
+                }
+                notApplicable.push({ id: id.trim(), reason, loc });
+                continue;
+            }
+            remainder.push(item);
+        }
+        return { remainder, notApplicable, errors };
+    }
+    const map = asRecord(raw);
+    if (map === null) {
+        return { remainder: raw, notApplicable, errors };
+    }
+    const remainder = {};
+    for (const [key, value] of Object.entries(map)) {
+        const loc = `coverage_map[${key}]`;
+        const rec = asRecord(value);
+        if (rec === null) {
+            remainder[key] = value;
+            continue;
+        }
+        const disposition = rec.disposition;
+        if (typeof disposition === "string" && disposition.trim().toLowerCase() === "not_applicable") {
+            const id = rec.parent_requirement_id ?? rec.parentRequirementId ?? key;
+            if (!isNonEmptyString(id)) {
+                errors.push(`${loc}: parent_requirement_id is required`);
+                continue;
+            }
+            const reason = takeReason(rec);
+            if (reason === null) {
+                errors.push(`${loc}: disposition not_applicable requires reason`);
+            }
+            notApplicable.push({ id: String(id).trim(), reason, loc });
+            continue;
+        }
+        remainder[key] = value;
+    }
+    return { remainder, notApplicable, errors };
+}
+function extractCoverageRaw(draft) {
+    const rec = asRecord(draft);
+    if (rec === null)
+        return undefined;
+    if (rec.coverage_map !== undefined || rec.coverageMap !== undefined) {
+        return rec.coverage_map ?? rec.coverageMap;
+    }
+    const plan = asRecord(rec.plan);
+    if (plan === null)
+        return undefined;
+    if (plan.coverage_map !== undefined || plan.coverageMap !== undefined) {
+        return plan.coverage_map ?? plan.coverageMap;
+    }
+    const metadata = asRecord(plan.metadata);
+    if (metadata === null)
+        return undefined;
+    return metadata.coverage_map ?? metadata.coverageMap;
+}
+function extractDeltasRaw(draft) {
+    const rec = asRecord(draft);
+    if (rec === null)
+        return undefined;
+    if (rec.behavioral_deltas !== undefined || rec.behavioralDeltas !== undefined) {
+        return rec.behavioral_deltas ?? rec.behavioralDeltas;
+    }
+    const plan = asRecord(rec.plan);
+    if (plan === null)
+        return undefined;
+    return plan.behavioral_deltas ?? plan.behavioralDeltas;
+}
+/**
+ * Completeness of coverage_map dispositions for applicable project invariant IDs.
+ * Extra coverage_map keys (e.g. parent requirement IDs) are ignored.
+ * Empty applicable set is a no-op success.
+ */
+export function validateProjectInvariantCoverage(opts) {
+    const applicableIds = [...new Set(opts.applicableIds.map((id) => id.trim()).filter(Boolean))];
+    const errors = [];
+    const coverageRaw = extractCoverageRaw(opts.draft);
+    const peeled = peelNotApplicable(coverageRaw);
+    errors.push(...peeled.errors);
+    const { entries, errors: mapErrors } = parseCoverageMap(peeled.remainder);
+    errors.push(...mapErrors);
+    const { byId: deltasById, errors: deltaErrors } = parseBehavioralDeltas(extractDeltasRaw(opts.draft));
+    errors.push(...deltaErrors);
+    const applicableSet = new Set(applicableIds);
+    const byId = new Map();
+    for (const entry of entries) {
+        if (!applicableSet.has(entry.parent_requirement_id)) {
+            continue;
+        }
+        if (entry.disposition === "split") {
+            errors.push(`coverage_map[${entry.parent_requirement_id}]: disposition split is excluded at project level`);
+            continue;
+        }
+        if (byId.has(entry.parent_requirement_id)) {
+            errors.push(`coverage_map[${entry.parent_requirement_id}]: duplicate coverage entries ` +
+                `(one disposition per project invariant ID)`);
+            continue;
+        }
+        byId.set(entry.parent_requirement_id, entry);
+        if (entry.disposition === "behavioral_delta") {
+            const deltaId = entry.delta_id;
+            if (isNonEmptyString(deltaId) && !deltasById.has(deltaId)) {
+                errors.push(`coverage_map[${entry.parent_requirement_id}]: behavioral_delta delta_id '${deltaId}' ` +
+                    `has no linked record in behavioral_deltas`);
+            }
+        }
+    }
+    const addressed = new Set();
+    for (const na of peeled.notApplicable) {
+        addressed.add(na.id);
+    }
+    for (const id of byId.keys()) {
+        addressed.add(id);
+    }
+    const missingIds = applicableIds.filter((id) => !addressed.has(id));
+    if (missingIds.length > 0) {
+        errors.push(`uncovered applicable project invariant IDs: ${missingIds.join(", ")} ` +
+            `(declare coverage_map[<id>].disposition as ${PROJECT_INVARIANT_DISPOSITIONS.join("|")})`);
+    }
+    return {
+        ok: errors.length === 0,
+        applicableIds,
+        missingIds,
+        errors,
+    };
+}
+//# sourceMappingURL=project-invariant-coverage.js.map

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

@@ -154,7 +154,7 @@ export function runTransition(action, filePath, now = new Date(), options = {})
             projectRoot,
             emitStamp: false,
         });
-        if (derivation.applied) {
+        if (derivation.notice.length > 0) {
             derivationNotice = derivation.notice;
         }
     }

package/dist/scope-provenance/compare-intent.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Public compare entry for extracted intent (#3376 R2 / R5 / #3385 F1–F2).
+ *
+ * Scalars are byte-equal after canonicalize. Decisions and references[] are
+ * guarded-append. Unclassified key only when unknown AND absent from base.
+ */
+import { type IntentPreimage } from "./extract-intent.js";
+export type IntentCompareKind = "intent-drift" | "unclassified-key" | "reference-mutation" | "decisions-mutation" | "repo-not-approved" | "ref-type-not-appendable" | "decision-pointer-missing";
+export interface IntentCompareFinding {
+    readonly kind: IntentCompareKind;
+    readonly path: string;
+    readonly detail: string;
+}
+export interface IntentCompareResult {
+    readonly ok: boolean;
+    readonly findings: readonly IntentCompareFinding[];
+}
+export interface CompareIntentOptions {
+    readonly changedFiles?: readonly string[];
+    readonly decisionExists?: (relPath: string) => boolean;
+}
+/**
+ * Compare a live extraction to the base-committed preimage.
+ * One entry point covers scalar equality and guarded append (R2 / R5).
+ */
+export declare function compareExtractedIntent(base: IntentPreimage, live: IntentPreimage, options?: CompareIntentOptions): IntentCompareResult;
+//# sourceMappingURL=compare-intent.d.ts.map