@deftai/directive-core 0.103.0 → 0.105.0

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

@@ -13,6 +13,8 @@
  * ITEM_CORE is not expanded with bare keys; verify:vbrief-conformance rejects them.
  */
 import type { GrantOrigin } from "../authz/types.js";
+import { type AcceptancePredicate } from "../product-first-done-gate/acceptance-resolver.js";
+import { type EvaluateVerifyAcOptions } from "../product-first-done-gate/evaluate.js";
 /** Canonical namespaced key for typed acceptance evidence (#3305 / #1620). */
 export declare const ACCEPTANCE_EVIDENCE_KEY: "x-directive/evidence";
 /** Canonical namespaced key for human-origin disposition (#3305 / #1620). */
@@ -55,6 +57,10 @@ export interface AcceptanceEvidenceGateResult {
     readonly ok: boolean;
     readonly message: string;
     readonly reports: readonly CriterionAcceptanceReport[];
+    /** How the #3357 walk obtained AC (#3387). */
+    readonly servedFrom?: "bank" | "cache" | "executed";
+    /** Which acceptance check decided the walk (#3497). Undefined when no walk ran. */
+    readonly predicate?: AcceptancePredicate;
 }
 export declare function isAcceptanceEvidenceKind(value: unknown): value is AcceptanceEvidenceKind;
 export declare function isAcceptanceDispositionKind(value: unknown): value is AcceptanceDispositionKind;
@@ -98,6 +104,27 @@ export declare function stampNamespacedEvidence(item: Record<string, unknown>, r
  * cannot carry both acceptance fields after a replace (#3305 Greptile P2).
  */
 export declare function stampNamespacedDisposition(item: Record<string, unknown>, record: AcceptanceDispositionRecord): void;
+/**
+ * Standing contract for scope:complete's acceptance precondition (#3357 / #3497).
+ *
+ * It no longer asserts a predicate ("empty or failing") — the actual predicate is
+ * named per refusal by the shared resolver. It also no longer tells operators to
+ * stamp by running verify:ac: verify:ac is the verifier and never writes the brief
+ * (a verifier that authors the acceptance it then checks is not a gate). Stamping
+ * happens at intake / promote via clause derivation (#3323).
+ */
+export declare const SCOPE_COMPLETE_ACCEPTANCE_REMEDIATION: string;
+/**
+ * Hard precondition for scope:complete (#3357 / #3267 / #3284).
+ *
+ * Runs the same verify:ac walk check uses, through the one shared option profile and
+ * the one shared verdict resolver (#3497) — so scope:complete can no longer report a
+ * different story than verify:ac about the same artifact. Disposition on plan items
+ * does not skip it. Briefs with no stamped plan.acceptance and no executable commands
+ * keep the legacy #3267 "nothing to run" pass so existing evidence-only fixtures stay
+ * valid.
+ */
+export declare function evaluateScopeCompleteAcceptanceWalk(plan: Record<string, unknown>, options?: EvaluateVerifyAcOptions): AcceptanceEvidenceGateResult;
 /**
  * Fail closed when any non-terminal plan item lacks suitable evidence or a human-origin disposition.
  */

package/dist/scope/acceptance-evidence.js

@@ -13,6 +13,8 @@
  * ITEM_CORE is not expanded with bare keys; verify:vbrief-conformance rejects them.
  */
 import { isHumanOrigin } from "../authz/origin.js";
+import { formatAcceptanceVerdict, resolveAcceptanceGateProfile, resolveAcceptanceVerdict, } from "../product-first-done-gate/acceptance-resolver.js";
+import { evaluateVerifyAcFromPlan, } from "../product-first-done-gate/evaluate.js";
 /** Canonical namespaced key for typed acceptance evidence (#3305 / #1620). */
 export const ACCEPTANCE_EVIDENCE_KEY = "x-directive/evidence";
 /** Canonical namespaced key for human-origin disposition (#3305 / #1620). */
@@ -369,6 +371,70 @@ function walkItems(items, pathPrefix, reports) {
         walkItems(obj.items, `${path}.items`, reports);
     });
 }
+/**
+ * Standing contract for scope:complete's acceptance precondition (#3357 / #3497).
+ *
+ * It no longer asserts a predicate ("empty or failing") — the actual predicate is
+ * named per refusal by the shared resolver. It also no longer tells operators to
+ * stamp by running verify:ac: verify:ac is the verifier and never writes the brief
+ * (a verifier that authors the acceptance it then checks is not a gate). Stamping
+ * happens at intake / promote via clause derivation (#3323).
+ */
+export const SCOPE_COMPLETE_ACCEPTANCE_REMEDIATION = "scope:complete requires executable plan.acceptance that runs green; stamp commands on " +
+    "plan.acceptance.commands (or plan.metadata.swarm.verify_commands) — task verify:ac verifies, " +
+    "it does not stamp — then re-run task verify:ac -- <completing-xbrief> " +
+    "(disposition is not a substitute) (#3357/#3497)";
+/**
+ * Hard precondition for scope:complete (#3357 / #3267 / #3284).
+ *
+ * Runs the same verify:ac walk check uses, through the one shared option profile and
+ * the one shared verdict resolver (#3497) — so scope:complete can no longer report a
+ * different story than verify:ac about the same artifact. Disposition on plan items
+ * does not skip it. Briefs with no stamped plan.acceptance and no executable commands
+ * keep the legacy #3267 "nothing to run" pass so existing evidence-only fixtures stay
+ * valid.
+ */
+export function evaluateScopeCompleteAcceptanceWalk(plan, options = {}) {
+    const stamped = plan.acceptance !== undefined;
+    const profile = resolveAcceptanceGateProfile("complete");
+    const walk = evaluateVerifyAcFromPlan(plan, {
+        ...options,
+        checkIntegrated: profile.checkIntegrated,
+        captureFromNarratives: options.captureFromNarratives ?? profile.captureFromNarratives,
+        reuseMode: options.reuseMode ?? profile.reuseMode,
+    });
+    const rejectedCount = walk.rejected?.length ?? 0;
+    const hadWork = walk.runs.length > 0 || walk.commands.length > 0 || rejectedCount > 0;
+    const servedFrom = walk.servedFrom ?? "executed";
+    if (!stamped && !hadWork) {
+        return {
+            ok: true,
+            message: "Acceptance walk not required (no stamped plan.acceptance) (#3357)",
+            reports: [],
+            servedFrom: "executed",
+        };
+    }
+    const verdict = resolveAcceptanceVerdict(walk);
+    if (walk.ok) {
+        return {
+            ok: true,
+            message: walk.message,
+            reports: [],
+            servedFrom,
+            predicate: verdict.predicate,
+        };
+    }
+    return {
+        ok: false,
+        // Name the check that refused and the value it read BEFORE the standing
+        // contract, so the first line the operator sees is the actual cause (#3497).
+        message: `scope:complete refused acceptance — ${formatAcceptanceVerdict(verdict)}\n` +
+            `${SCOPE_COMPLETE_ACCEPTANCE_REMEDIATION}\n${walk.message}`,
+        reports: [],
+        servedFrom,
+        predicate: verdict.predicate,
+    };
+}
 /**
  * Fail closed when any non-terminal plan item lacks suitable evidence or a human-origin disposition.
  */

package/dist/scope/capacity-stamp.d.ts

@@ -19,6 +19,8 @@ export interface StampCompletionOptions {
      * tests so the fallback path is exercised without a network call.
      */
     readonly liveLabelReader?: LabelReader;
+    /** Session that ran scope:complete; check uses this to target xbrief/completed (#3357). */
+    readonly completedSessionId?: string | null;
 }
 /** Stamp completedAt + label-matched capacityBucket onto a completing vBRIEF (#1419, #2237). */
 export declare function stampCompletionMetadata(plan: Record<string, unknown>, projectRoot: string, timestamp: string, options?: StampCompletionOptions): void;

package/dist/scope/capacity-stamp.js

@@ -86,6 +86,10 @@ export function stampCompletionMetadata(plan, projectRoot, timestamp, options =
     }
     const meta = metadata;
     meta.completedAt = timestamp;
+    const sessionId = options.completedSessionId?.trim() ?? "";
+    if (sessionId.length > 0) {
+        meta.completedSessionId = sessionId;
+    }
     const existing = meta.capacityBucket;
     if (typeof existing === "string" && existing.trim().length > 0) {
         return;

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

@@ -32,6 +32,8 @@ 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). */
+    readonly completedSessionId?: string | null;
 }
 export interface DeliveryEvidenceInput {
     readonly repository?: string | null;
@@ -67,6 +69,10 @@ export interface DeliveryGateResult {
     readonly provenance: CompletionProvenance | null;
     readonly codeBearing: boolean;
 }
+/**
+ * Session id for a completing brief (#3357). Prefer DEFT_SESSION_ID, then ritual-state.
+ */
+export declare function resolveCompletionSessionId(projectRoot: string, env?: NodeJS.ProcessEnv): string | null;
 export declare function isNonDeliveryDisposition(value: unknown): value is NonDeliveryDisposition;
 /** True when the brief is treated as code-bearing for the delivery gate (#3041). */
 export declare function isCodeBearingScope(plan: Record<string, unknown>): boolean;
@@ -93,13 +99,13 @@ export declare function verifyDeliveryAncestry(projectRoot: string, mergeCommit:
     remoteTip: string | null;
 };
 /**
- * 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 declare function evaluateDeliveryGate(options: DeliveryGateOptions): DeliveryGateResult;
 /** Stamp completion provenance onto plan.metadata (mutates plan). */

package/dist/scope/delivery-evidence.js

@@ -9,6 +9,7 @@
  */
 import { resolveDeliveryBranch } from "../policy/delivery-branch.js";
 import { defaultGitRunner, gitIsAncestor } from "../session/git.js";
+import { readRitualState } from "../session/ritual-sentinel.js";
 /** Handoff states that Git delivery can assert (deploy/UAT never inferred). */
 export const HANDOFF_STATES = [
     "implemented",
@@ -29,6 +30,18 @@ function asRecord(value) {
     }
     return null;
 }
+/**
+ * Session id for a completing brief (#3357). Prefer DEFT_SESSION_ID, then ritual-state.
+ */
+export function resolveCompletionSessionId(projectRoot, env = process.env) {
+    const fromEnv = typeof env.DEFT_SESSION_ID === "string" ? env.DEFT_SESSION_ID.trim() : "";
+    if (fromEnv.length > 0) {
+        return fromEnv;
+    }
+    const [state] = readRitualState(projectRoot);
+    const id = state?.sessionId.trim() ?? "";
+    return id.length > 0 ? id : null;
+}
 export function isNonDeliveryDisposition(value) {
     return (typeof value === "string" && NON_DELIVERY_DISPOSITIONS.includes(value));
 }
@@ -162,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,
         };
     }
@@ -186,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;
@@ -254,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,
         };
@@ -281,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,
         };
@@ -326,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,
@@ -380,6 +388,10 @@ export function stampDeliveryProvenance(plan, provenance) {
         // Deploy/UAT are explicit-only; default null so readers never infer from Git.
         deployed: provenance.deployed,
         uatVerified: provenance.uatVerified,
+        ...(typeof provenance.completedSessionId === "string" &&
+            provenance.completedSessionId.trim().length > 0
+            ? { completedSessionId: provenance.completedSessionId.trim() }
+            : {}),
     };
     meta.deliveryDisposition = provenance.disposition;
     meta.handoffState = provenance.handoffState;

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/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