@deftai/directive-core 0.104.0 → 0.105.0

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

package/dist/scope-provenance/compare-intent.js

@@ -0,0 +1,233 @@
+/**
+ * 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 { DECISION_FILE_SUFFIX, DECISIONS_DIR_REL } from "../decision/schema.js";
+import { GITHUB_ISSUE_REF_TYPES } from "../intake/reconcile-issues.js";
+import { slugFromGithubIssueUri } from "./extract-intent.js";
+import { sortKeysDeep } from "./intent-digest.js";
+import { classifyPlanPath } from "./known-machine.js";
+const EM_DASH = "\u2014";
+const DECISION_LINE = new RegExp(`^- (${DECISIONS_DIR_REL.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/[^\\s]+${DECISION_FILE_SUFFIX.replace(".", "\\.")}) ${EM_DASH} (.+)$`);
+function canon(value) {
+    return JSON.stringify(sortKeysDeep(value));
+}
+function asRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    return value;
+}
+function splitDecisionLines(raw) {
+    if (typeof raw !== "string")
+        return [];
+    return raw
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+}
+function refKey(ref) {
+    return `${String(ref.type ?? "")}\n${String(ref.uri ?? "")}`;
+}
+function narrativesOf(plan) {
+    return asRecord(plan.narratives) ?? {};
+}
+function compareScalars(basePlan, livePlan, findings) {
+    const skip = new Set(["references", "narratives", "items", "parentId"]);
+    const keys = new Set([...Object.keys(basePlan), ...Object.keys(livePlan)]);
+    for (const key of keys) {
+        if (skip.has(key))
+            continue;
+        if (key === "metadata") {
+            if (canon(basePlan.metadata) !== canon(livePlan.metadata)) {
+                findings.push({
+                    kind: "intent-drift",
+                    path: "metadata",
+                    detail: "extracted metadata drifted from the base preimage",
+                });
+            }
+            continue;
+        }
+        if (canon(basePlan[key]) !== canon(livePlan[key])) {
+            findings.push({
+                kind: "intent-drift",
+                path: key,
+                detail: `extracted ${key} drifted from the base preimage`,
+            });
+        }
+    }
+}
+function compareItems(baseItems, liveItems, findings) {
+    if (canon(baseItems ?? []) !== canon(liveItems ?? [])) {
+        findings.push({
+            kind: "intent-drift",
+            path: "items",
+            detail: "extracted items drifted from the base preimage",
+        });
+    }
+}
+function compareNarratives(basePlan, livePlan, options, findings) {
+    const baseN = narrativesOf(basePlan);
+    const liveN = narrativesOf(livePlan);
+    const keys = new Set([...Object.keys(baseN), ...Object.keys(liveN)]);
+    for (const key of keys) {
+        if (key === "Decisions")
+            continue;
+        if (canon(baseN[key]) !== canon(liveN[key])) {
+            findings.push({
+                kind: "intent-drift",
+                path: `narratives.${key}`,
+                detail: `extracted narratives.${key} drifted from the base preimage`,
+            });
+        }
+    }
+    const baseLines = splitDecisionLines(baseN.Decisions);
+    const liveLines = splitDecisionLines(liveN.Decisions);
+    if (liveLines.length < baseLines.length) {
+        findings.push({
+            kind: "decisions-mutation",
+            path: "narratives.Decisions",
+            detail: "Decisions lines were deleted; preimage lines are law",
+        });
+        return;
+    }
+    for (let i = 0; i < baseLines.length; i += 1) {
+        if (liveLines[i] !== baseLines[i]) {
+            findings.push({
+                kind: "decisions-mutation",
+                path: "narratives.Decisions",
+                detail: "existing Decisions lines were edited; only append is allowed",
+            });
+            return;
+        }
+    }
+    const changed = new Set((options.changedFiles ?? []).map((p) => p.replace(/\\/g, "/")));
+    for (const line of liveLines.slice(baseLines.length)) {
+        const m = DECISION_LINE.exec(line);
+        if (m === null) {
+            findings.push({
+                kind: "decisions-mutation",
+                path: "narratives.Decisions",
+                detail: `appended Decisions line is not '- <${DECISIONS_DIR_REL}>/…${DECISION_FILE_SUFFIX} ${EM_DASH} <summary>'`,
+            });
+            continue;
+        }
+        const rel = m[1] ?? "";
+        const onBaseOrChange = changed.has(rel) || Boolean(options.decisionExists?.(rel));
+        if (!onBaseOrChange) {
+            findings.push({
+                kind: "decision-pointer-missing",
+                path: "narratives.Decisions",
+                detail: `Decisions pointer ${rel} is not on base and not in the change set`,
+            });
+        }
+    }
+}
+function compareReferences(base, live, findings) {
+    const baseRefs = Array.isArray(base.plan.references)
+        ? base.plan.references
+        : [];
+    const liveRefs = Array.isArray(live.plan.references)
+        ? live.plan.references
+        : [];
+    const liveByKey = new Map();
+    for (const ref of liveRefs) {
+        liveByKey.set(refKey(ref), ref);
+    }
+    for (const ref of baseRefs) {
+        const key = refKey(ref);
+        const liveRef = liveByKey.get(key);
+        if (liveRef === undefined) {
+            findings.push({
+                kind: "reference-mutation",
+                path: "references",
+                detail: `origin reference removed: ${String(ref.uri ?? "")}`,
+            });
+            continue;
+        }
+        if (canon(ref) !== canon(liveRef)) {
+            findings.push({
+                kind: "reference-mutation",
+                path: "references",
+                detail: `origin reference edited: ${String(ref.uri ?? "")}`,
+            });
+        }
+    }
+    const baseKeys = new Set(baseRefs.map(refKey));
+    const approved = new Set(base.approvedRepos.map((s) => s.toLowerCase()));
+    for (const ref of liveRefs) {
+        if (baseKeys.has(refKey(ref)))
+            continue;
+        const type = String(ref.type ?? "");
+        if (!GITHUB_ISSUE_REF_TYPES.has(type)) {
+            findings.push({
+                kind: "ref-type-not-appendable",
+                path: "references",
+                detail: `appended reference type ${JSON.stringify(type)} is not in GITHUB_ISSUE_REF_TYPES`,
+            });
+            continue;
+        }
+        const uri = typeof ref.uri === "string" ? ref.uri : "";
+        const slug = slugFromGithubIssueUri(uri);
+        if (slug === null || !approved.has(slug)) {
+            findings.push({
+                kind: "repo-not-approved",
+                path: "references",
+                detail: `appended github-issue URL is not in the base preimage approvedRepos: ${uri}`,
+            });
+        }
+    }
+}
+function compareUnknownKeys(base, live, findings) {
+    const baseUnknown = new Set(base.unknownPaths);
+    const basePlan = asRecord(base.plan) ?? {};
+    for (const path of live.unknownPaths) {
+        if (baseUnknown.has(path))
+            continue;
+        const top = path.split(".")[0] ?? path;
+        if (top in basePlan && classifyPlanPath(top) === "unknown")
+            continue;
+        const parts = path.split(".");
+        let cursor = base.plan;
+        let present = true;
+        for (const part of parts) {
+            const rec = asRecord(cursor);
+            if (rec === null || !(part in rec)) {
+                present = false;
+                break;
+            }
+            cursor = rec[part];
+        }
+        if (present)
+            continue;
+        findings.push({
+            kind: "unclassified-key",
+            path,
+            detail: `unclassified key ${path} is absent from the base preimage`,
+        });
+    }
+}
+/**
+ * Compare a live extraction to the base-committed preimage.
+ * One entry point covers scalar equality and guarded append (R2 / R5).
+ */
+export function compareExtractedIntent(base, live, options = {}) {
+    const findings = [];
+    const basePlan = asRecord(base.plan) ?? {};
+    const livePlan = asRecord(live.plan) ?? {};
+    if (canon(basePlan.parentId) !== canon(livePlan.parentId)) {
+        findings.push({
+            kind: "intent-drift",
+            path: "parentId",
+            detail: "parent identity changed (silent reparent)",
+        });
+    }
+    compareScalars(basePlan, livePlan, findings);
+    compareItems(basePlan.items, livePlan.items, findings);
+    compareNarratives(basePlan, livePlan, options, findings);
+    compareReferences(base, live, findings);
+    compareUnknownKeys(base, live, findings);
+    return { ok: findings.length === 0, findings };
+}
+//# sourceMappingURL=compare-intent.js.map

package/dist/scope-provenance/digest.d.ts

@@ -27,8 +27,15 @@ export interface ApprovedScopeRecord {
         readonly mintedAt: string;
         readonly mintedVia?: string;
     };
-    /** Digest of the full xBRIEF canonical JSON body (optional stronger pin). */
+    /**
+     * Legacy optional body digest. Wave 1 (#3384 F4) does not write this on new
+     * records. Do not treat it as authority (Wave 2 #3385 / R6).
+     */
     readonly xbriefBodyDigest?: string;
+    /** Checksum of the base-committed `.intent.json` preimage (#3385). */
+    readonly intentDigest?: string;
+    /** Digest algorithm name; Wave 2 writes `intent-extract-v1`. */
+    readonly digestAlgo?: string;
 }
 export declare const APPROVED_SCOPE_DIR = ".deft/approved-scope";
 /** Normalize and sort scope paths for stable digests. */
@@ -42,14 +49,24 @@ export declare function extractFileScope(payload: unknown): string[];
 /** Extract plan.id from an xBRIEF payload. */
 export declare function extractPlanId(payload: unknown): string | null;
 export declare function approvedScopeDir(projectRoot: string): string;
+export declare function approvedScopeSafePlanId(planId: string): string;
 export declare function approvedScopeRecordPath(projectRoot: string, planId: string): string;
+/** Repo-relative preimage path. */
+export declare function approvedScopeIntentRel(planId: string): string;
+export declare function approvedScopeIntentPath(projectRoot: string, planId: string): string;
 /** Build an ApprovedScopeRecord from xBRIEF payload + metadata. */
 export declare function buildApprovedScopeRecord(input: {
     readonly xbriefRelPath: string;
     readonly payload: unknown;
     readonly approvedAt?: string;
     readonly humanApproval?: ApprovedScopeRecord["humanApproval"];
+    /**
+     * Ignored. Wave 1 (#3384 F4) no longer writes `xbriefBodyDigest` on new records.
+     * Kept so existing callers do not have to drop the field in the same change.
+     */
     readonly xbriefRawText?: string;
+    readonly intentDigest?: string;
+    readonly digestAlgo?: string;
 }): ApprovedScopeRecord;
 /** Persist approved-scope record (activation / renewed human approval). */
 export declare function writeApprovedScopeRecord(projectRoot: string, record: ApprovedScopeRecord): string;