@deftai/directive-core 0.104.0 → 0.106.0

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;

package/dist/scope-provenance/digest.js

@@ -69,9 +69,18 @@ export function extractPlanId(payload) {
 export function approvedScopeDir(projectRoot) {
     return join(resolve(projectRoot), ...APPROVED_SCOPE_DIR.split("/"));
 }
+export function approvedScopeSafePlanId(planId) {
+    return planId.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
 export function approvedScopeRecordPath(projectRoot, planId) {
-    const safe = planId.replace(/[^a-zA-Z0-9._-]/g, "_");
-    return join(approvedScopeDir(projectRoot), `${safe}.json`);
+    return join(approvedScopeDir(projectRoot), `${approvedScopeSafePlanId(planId)}.json`);
+}
+/** Repo-relative preimage path. */
+export function approvedScopeIntentRel(planId) {
+    return `.deft/approved-scope/${approvedScopeSafePlanId(planId)}.intent.json`;
+}
+export function approvedScopeIntentPath(projectRoot, planId) {
+    return join(approvedScopeDir(projectRoot), `${approvedScopeSafePlanId(planId)}.intent.json`);
 }
 /** Build an ApprovedScopeRecord from xBRIEF payload + metadata. */
 export function buildApprovedScopeRecord(input) {
@@ -87,17 +96,13 @@ export function buildApprovedScopeRecord(input) {
         fileScope,
         fileScopeDigest,
     };
+    const withIntent = input.intentDigest !== undefined
+        ? { ...record, intentDigest: input.intentDigest, digestAlgo: input.digestAlgo }
+        : record;
     if (input.humanApproval !== undefined) {
-        return {
-            ...record,
-            humanApproval: input.humanApproval,
-            xbriefBodyDigest: input.xbriefRawText !== undefined ? computeTextDigest(input.xbriefRawText) : undefined,
-        };
-    }
-    if (input.xbriefRawText !== undefined) {
-        return { ...record, xbriefBodyDigest: computeTextDigest(input.xbriefRawText) };
+        return { ...withIntent, humanApproval: input.humanApproval };
     }
-    return record;
+    return withIntent;
 }
 /** Persist approved-scope record (activation / renewed human approval). */
 export function writeApprovedScopeRecord(projectRoot, record) {

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

@@ -9,7 +9,7 @@
  * Migration: missing approved-scope records → warn (exit 0) unless --enforce.
  */
 import { type ApprovedScopeRecord } from "./digest.js";
-export type ScopeProvenanceViolationKind = "self-authorizing-scope-expansion" | "active-xbrief-modified-without-digest" | "digest-mismatch-without-renewal";
+export type ScopeProvenanceViolationKind = "self-authorizing-scope-expansion" | "active-xbrief-modified-without-digest" | "digest-mismatch-without-renewal" | "intent-drift" | "unclassified-key" | "intent-digest-mismatch" | "duplicate-key" | "duplicate-item-id" | "same-pr-intent-rewrite" | "first-activation-missing-intent-pin" | "legacy-intent-edit" | "intent-parse-error";
 export interface ScopeProvenanceFinding {
     readonly xbriefRelPath: string;
     readonly planId: string;
@@ -39,6 +39,10 @@ export interface ScopeProvenanceOptions {
     readonly approvedRecords?: readonly ApprovedScopeRecord[];
     /** Inject renewed-approval stamps keyed by planId (test seam). */
     readonly renewedApprovals?: ReadonlyMap<string, ApprovedScopeRecord["humanApproval"]>;
+    /** Inject `git show <base>:<rel>` (test seam; never working-tree). */
+    readonly readAtBase?: (relPath: string) => string | null;
+    /** Optional repo slug seed for live extract (mint uses resolveProjectRepo). */
+    readonly approvedReposSeed?: readonly string[];
 }
 /**
  * Resolve a PR-aware base ref. Bare `HEAD` only shows uncommitted changes, so

package/dist/scope-provenance/evaluate.js

@@ -12,7 +12,9 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { GitCommandError, GitNotFoundError } from "../encoding/git.js";
-import { computeFileScopeDigest, extractFileScope, extractPlanId, isHumanApprovalStamp, listApprovedScopeRecords, normalizeFileScope, readApprovedScopeRecord, scopeExpansion, } from "./digest.js";
+import { approvedScopeIntentRel, computeFileScopeDigest, extractFileScope, extractPlanId, isHumanApprovalStamp, listApprovedScopeRecords, normalizeFileScope, readApprovedScopeRecord, scopeExpansion, } from "./digest.js";
+import { bodyDigestIsAuthority, evaluateIntentForXbrief } from "./intent-evaluate.js";
+import { recoverApprovedScopePairs } from "./mint-artifacts.js";
 function git(args, projectRoot) {
     const result = spawnSync("git", args, {
         cwd: projectRoot,
@@ -203,7 +205,7 @@ 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 " +
@@ -236,6 +238,8 @@ export function parseApprovedScopeRecordRaw(raw) {
         const expected = computeFileScopeDigest(scopePaths);
         if (rec.fileScopeDigest !== expected)
             return null;
+        // xbriefBodyDigest is never authority (#3385 F4 / R6) — ignored if present.
+        bodyDigestIsAuthority(data);
         return data;
     }
     catch {
@@ -340,7 +344,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).",
             };
         }
     }
@@ -357,7 +361,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;
@@ -379,6 +383,7 @@ export function evaluateOneScopeProvenance(input) {
 export function evaluateScopeProvenance(projectRoot, options = {}) {
     const root = resolve(projectRoot);
     const enforce = options.enforce ?? false;
+    recoverApprovedScopePairs(root);
     let changed;
     /** Merge-base ref used for changed-file discovery (null when files injected). */
     let discoveryBaseRef = null;
@@ -523,6 +528,17 @@ export function evaluateScopeProvenance(projectRoot, options = {}) {
                 return (n.includes("/approved-scope/") &&
                     (n.endsWith(`/${safe}.json`) || n.endsWith(`${safe}.json`)));
             });
+        const preimageRel = planId !== null ? approvedScopeIntentRel(planId) : null;
+        const preimageInGitChange = preimageRel !== null &&
+            [...changedSet].some((p) => {
+                const n = normalizeRepoRelPath(p);
+                if (n === preimageRel || n.endsWith(`/${preimageRel}`))
+                    return true;
+                if (planId === null)
+                    return false;
+                const safe = planId.replace(/[^a-zA-Z0-9._-]/g, "_");
+                return n.includes("/approved-scope/") && n.endsWith(`/${safe}.intent.json`);
+            });
         // Disk-only / concurrent-rewrite inference (#3205):
         // Authority is the *approval record on the merge base*, not whether the
         // active xBRIEF path existed there. pending→active leaves the active path
@@ -555,7 +571,7 @@ export function evaluateScopeProvenance(projectRoot, options = {}) {
                 }
             }
         }
-        const approvalRecordRewritten = approvalInGitChange || approvalDiskOnly;
+        const approvalRecordRewritten = approvalInGitChange || approvalDiskOnly || preimageInGitChange;
         const recordMatchesCurrent = approved !== null &&
             !approvalRecordRewritten &&
             approved.fileScopeDigest ===
@@ -570,11 +586,11 @@ export function evaluateScopeProvenance(projectRoot, options = {}) {
                 planId: planId ?? rel,
                 kind: "self-authorizing-scope-expansion",
                 expandedPaths: currentScope,
-                detail: "approved-scope record rewritten in the same change set as the active xBRIEF; " +
+                detail: "approved-scope record or preimage rewritten in the same change set as the active xBRIEF; " +
                     "cannot self-authorize via concurrent approval rewrite",
                 remediation: "Commit human approval via `task scope:record-approved-scope` on the merge base " +
                     "(or a prior PR), then activate/expand without rewriting the approval in this " +
-                    "change set. Same-PR approval rewrites do not authorize expansion (#3145 / #3205).",
+                    "change set. Same-PR approval rewrites do not authorize expansion (#3145 / #3205 / #3385).",
             });
             continue;
         }
@@ -586,6 +602,50 @@ export function evaluateScopeProvenance(projectRoot, options = {}) {
             enforce,
             renewedHumanApproval: renewed ?? (recordMatchesCurrent ? approved?.humanApproval : null),
         });
+        const readAtBase = (baseRel) => {
+            if (options.readAtBase !== undefined)
+                return options.readAtBase(baseRel);
+            if (discoveryBaseRef === null || discoveryBaseRef === "")
+                return null;
+            try {
+                return readRepoFileAtRef(root, discoveryBaseRef, baseRel);
+            }
+            catch {
+                return null;
+            }
+        };
+        const intentHits = evaluateIntentForXbrief({
+            projectRoot: root,
+            xbriefRelPath: rel,
+            liveRaw: raw,
+            livePayload: payload,
+            planId: planId ?? rel,
+            approved,
+            xbriefModified: modified,
+            approvalRewritten: approvalRecordRewritten,
+            preimageRewritten: preimageInGitChange,
+            currentScopeNonEmpty: normalizeFileScope(extractFileScope(payload)).length > 0,
+            baseRef: discoveryBaseRef,
+            changedFiles: changed,
+            readAtBase,
+            approvedReposSeed: options.approvedReposSeed,
+        });
+        for (const hit of intentHits) {
+            const mapped = {
+                xbriefRelPath: hit.xbriefRelPath,
+                planId: hit.planId,
+                kind: hit.kind,
+                expandedPaths: [],
+                detail: hit.detail,
+                remediation: hit.remediation,
+            };
+            if (hit.warnOnly) {
+                softFindings.push(mapped);
+            }
+            else {
+                findings.push(mapped);
+            }
+        }
         if (finding === null)
             continue;
         // Soft migration: body-only edits (empty file_scope) without digest when !enforce.

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

@@ -0,0 +1,43 @@
+/**
+ * Extract intent preimage from a live xBRIEF (#3376 R1–R5 / #3385 F1–F2).
+ *
+ * Unknown plan.* keys are extracted (pinned), not rejected. Known-machine keys
+ * are omitted. plan.tags is machine; plan.edges is extracted.
+ */
+import { GITHUB_ISSUE_REF_TYPES } from "../intake/reconcile-issues.js";
+import { INTENT_DIGEST_ALGO } from "./intent-digest.js";
+export declare const INTENT_PREIMAGE_SCHEMA: 1;
+export interface IntentPreimage {
+    readonly schemaVersion: typeof INTENT_PREIMAGE_SCHEMA;
+    readonly algo: typeof INTENT_DIGEST_ALGO;
+    readonly plan: Record<string, unknown>;
+    readonly approvedRepos: readonly string[];
+    /** Paths classified unknown at extract (for verify unclassified-key). */
+    readonly unknownPaths: readonly string[];
+}
+export interface ExtractIntentOk {
+    readonly ok: true;
+    readonly preimage: IntentPreimage;
+}
+export interface ExtractIntentErr {
+    readonly ok: false;
+    readonly error: string;
+}
+export type ExtractIntentResult = ExtractIntentOk | ExtractIntentErr;
+export interface ExtractIntentOptions {
+    readonly projectRoot?: string;
+    readonly approvedReposSeed?: readonly string[];
+    readonly readFile?: (absPath: string) => string | null;
+}
+export declare function slugFromGithubIssueUri(uri: string): string | null;
+export declare function resolveParentPlanId(planRef: string, projectRoot: string, readFile?: (absPath: string) => string | null): {
+    id: string;
+} | {
+    error: string;
+};
+/** Extract from a parsed payload (tokenizer already applied). */
+export declare function extractIntentFromPayload(payload: unknown, options?: ExtractIntentOptions): ExtractIntentResult;
+/** Parse raw text (duplicate-key reject) then extract. */
+export declare function extractIntentFromRaw(raw: string, options?: ExtractIntentOptions): ExtractIntentResult;
+export { GITHUB_ISSUE_REF_TYPES };
+//# sourceMappingURL=extract-intent.d.ts.map