@deftai/directive-core 0.96.0 → 0.97.0

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

@@ -0,0 +1,67 @@
+/**
+ * Approved-scope digest helpers (#3145).
+ *
+ * At activation/approval time, record an immutable digest of the human-approved
+ * file_scope. PR verification compares the live active xBRIEF against this
+ * baseline so same-PR xBRIEF edits cannot self-authorize new paths.
+ */
+/** Immutable approved-scope record written under `.deft/approved-scope/`. */
+export interface ApprovedScopeRecord {
+    readonly schemaVersion: 1;
+    /** Repo-relative path of the active xBRIEF at approval time. */
+    readonly xbriefRelPath: string;
+    readonly planId: string;
+    /** ISO-8601 UTC timestamp of approval / activation. */
+    readonly approvedAt: string;
+    /** Sorted unique file_scope paths frozen at approval. */
+    readonly fileScope: readonly string[];
+    /** sha256 hex of normalized file_scope lines. */
+    readonly fileScopeDigest: string;
+    /**
+     * Optional human-origin stamp (refs #2944). When present on renewal,
+     * re-approval is accepted. Agent-only stamps are ignored by evaluate.
+     */
+    readonly humanApproval?: {
+        readonly kind: string;
+        readonly actor: string;
+        readonly mintedAt: string;
+        readonly mintedVia?: string;
+    };
+    /** Digest of the full xBRIEF canonical JSON body (optional stronger pin). */
+    readonly xbriefBodyDigest?: string;
+}
+export declare const APPROVED_SCOPE_DIR = ".deft/approved-scope";
+/** Normalize and sort scope paths for stable digests. */
+export declare function normalizeFileScope(paths: readonly string[]): string[];
+/** sha256 hex of normalized file_scope (one path per line). */
+export declare function computeFileScopeDigest(paths: readonly string[]): string;
+/** sha256 hex of raw UTF-8 text. */
+export declare function computeTextDigest(text: string): string;
+/** Extract plan.metadata.swarm.file_scope from an xBRIEF payload. */
+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 approvedScopeRecordPath(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"];
+    readonly xbriefRawText?: string;
+}): ApprovedScopeRecord;
+/** Persist approved-scope record (activation / renewed human approval). */
+export declare function writeApprovedScopeRecord(projectRoot: string, record: ApprovedScopeRecord): string;
+/** Load one approved-scope record by plan id, or null if missing. */
+export declare function readApprovedScopeRecord(projectRoot: string, planId: string): ApprovedScopeRecord | null;
+/** Load all approved-scope records under `.deft/approved-scope/`. */
+export declare function listApprovedScopeRecords(projectRoot: string): ApprovedScopeRecord[];
+/**
+ * Paths present in `current` but not in `approved` (normalized).
+ * These are the expansion set that cannot self-authorize.
+ */
+export declare function scopeExpansion(approved: readonly string[], current: readonly string[]): string[];
+/** True when actor/kind look like human provenance (mirrors authz subset). */
+export declare function isHumanApprovalStamp(stamp: ApprovedScopeRecord["humanApproval"] | null | undefined): boolean;
+//# sourceMappingURL=digest.d.ts.map

package/dist/scope-provenance/digest.js

@@ -0,0 +1,188 @@
+/**
+ * Approved-scope digest helpers (#3145).
+ *
+ * At activation/approval time, record an immutable digest of the human-approved
+ * file_scope. PR verification compares the live active xBRIEF against this
+ * baseline so same-PR xBRIEF edits cannot self-authorize new paths.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
+export const APPROVED_SCOPE_DIR = ".deft/approved-scope";
+/** Normalize and sort scope paths for stable digests. */
+export function normalizeFileScope(paths) {
+    const out = new Set();
+    for (const p of paths) {
+        if (typeof p !== "string")
+            continue;
+        const n = p.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+        if (n.length > 0)
+            out.add(n);
+    }
+    return [...out].sort((a, b) => a.localeCompare(b));
+}
+/** sha256 hex of normalized file_scope (one path per line). */
+export function computeFileScopeDigest(paths) {
+    const normalized = normalizeFileScope(paths);
+    const payload = `${normalized.join("\n")}\n`;
+    return createHash("sha256").update(payload, "utf8").digest("hex");
+}
+/** sha256 hex of raw UTF-8 text. */
+export function computeTextDigest(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+/** Extract plan.metadata.swarm.file_scope from an xBRIEF payload. */
+export function extractFileScope(payload) {
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+        return [];
+    }
+    const plan = payload.plan;
+    if (plan === null || typeof plan !== "object" || Array.isArray(plan)) {
+        return [];
+    }
+    const metadata = plan.metadata;
+    if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) {
+        return [];
+    }
+    const swarm = metadata.swarm;
+    if (swarm === null || typeof swarm !== "object" || Array.isArray(swarm)) {
+        return [];
+    }
+    const fileScope = swarm.file_scope;
+    if (!Array.isArray(fileScope))
+        return [];
+    return fileScope.filter((x) => typeof x === "string");
+}
+/** Extract plan.id from an xBRIEF payload. */
+export function extractPlanId(payload) {
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+        return null;
+    }
+    const plan = payload.plan;
+    if (plan === null || typeof plan !== "object" || Array.isArray(plan)) {
+        return null;
+    }
+    const id = plan.id;
+    return typeof id === "string" && id.trim().length > 0 ? id.trim() : null;
+}
+export function approvedScopeDir(projectRoot) {
+    return join(resolve(projectRoot), ...APPROVED_SCOPE_DIR.split("/"));
+}
+export function approvedScopeRecordPath(projectRoot, planId) {
+    const safe = planId.replace(/[^a-zA-Z0-9._-]/g, "_");
+    return join(approvedScopeDir(projectRoot), `${safe}.json`);
+}
+/** Build an ApprovedScopeRecord from xBRIEF payload + metadata. */
+export function buildApprovedScopeRecord(input) {
+    const planId = extractPlanId(input.payload) ?? basename(input.xbriefRelPath, ".xbrief.json");
+    const fileScope = normalizeFileScope(extractFileScope(input.payload));
+    const fileScopeDigest = computeFileScopeDigest(fileScope);
+    const approvedAt = input.approvedAt ?? new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+    const record = {
+        schemaVersion: 1,
+        xbriefRelPath: input.xbriefRelPath.replace(/\\/g, "/"),
+        planId,
+        approvedAt,
+        fileScope,
+        fileScopeDigest,
+    };
+    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 record;
+}
+/** Persist approved-scope record (activation / renewed human approval). */
+export function writeApprovedScopeRecord(projectRoot, record) {
+    const dir = approvedScopeDir(projectRoot);
+    mkdirSync(dir, { recursive: true });
+    const path = approvedScopeRecordPath(projectRoot, record.planId);
+    containedWrite({
+        root: resolve(projectRoot),
+        target: path,
+        data: `${JSON.stringify(record, null, 2)}\n`,
+        mode: "replace",
+    });
+    return path;
+}
+/** Load one approved-scope record by plan id, or null if missing. */
+export function readApprovedScopeRecord(projectRoot, planId) {
+    const path = approvedScopeRecordPath(projectRoot, planId);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+            return null;
+        const rec = raw;
+        if (typeof rec.fileScopeDigest !== "string" || !Array.isArray(rec.fileScope))
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+/** Load all approved-scope records under `.deft/approved-scope/`. */
+export function listApprovedScopeRecords(projectRoot) {
+    const dir = approvedScopeDir(projectRoot);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const name of readdirSync(dir)) {
+        if (!name.endsWith(".json"))
+            continue;
+        try {
+            const raw = JSON.parse(readFileSync(join(dir, name), "utf8"));
+            if (raw !== null && typeof raw === "object" && !Array.isArray(raw)) {
+                const rec = raw;
+                if (typeof rec.fileScopeDigest === "string")
+                    out.push(rec);
+            }
+        }
+        catch {
+            // skip malformed
+        }
+    }
+    return out;
+}
+/**
+ * Paths present in `current` but not in `approved` (normalized).
+ * These are the expansion set that cannot self-authorize.
+ */
+export function scopeExpansion(approved, current) {
+    const base = new Set(normalizeFileScope(approved));
+    return normalizeFileScope(current).filter((p) => !base.has(p));
+}
+/** True when actor/kind look like human provenance (mirrors authz subset). */
+export function isHumanApprovalStamp(stamp) {
+    if (stamp === null || stamp === undefined)
+        return false;
+    const kind = (stamp.kind ?? "").trim().toLowerCase();
+    const actor = (stamp.actor ?? "").trim().toLowerCase();
+    if (kind.length === 0 || actor.length === 0)
+        return false;
+    if (actor === "agent" || actor.startsWith("agent:") || actor === "self")
+        return false;
+    if (kind === "agent" || kind === "self" || kind === "xbrief" || kind === "dispatch")
+        return false;
+    // Accept common human kinds from #2944 surface
+    const humanKinds = new Set([
+        "cli",
+        "operator",
+        "human",
+        "user",
+        "github-user",
+        "interactive",
+        "renewed-approval",
+    ]);
+    return humanKinds.has(kind) || kind.startsWith("human");
+}
+//# sourceMappingURL=digest.js.map

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

@@ -0,0 +1,82 @@
+/**
+ * verify:scope-provenance evaluation (#3145).
+ *
+ * Detects same-PR active xBRIEF expansion that would self-authorize new
+ * implementation paths. Requires renewed human approval (updated digest record
+ * with human stamp); the modified xBRIEF alone is never sufficient.
+ *
+ * Three-state exit: 0 clean / 1 self-authorization / 2 config.
+ * 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 interface ScopeProvenanceFinding {
+    readonly xbriefRelPath: string;
+    readonly planId: string;
+    readonly kind: ScopeProvenanceViolationKind;
+    readonly expandedPaths: readonly string[];
+    readonly detail: string;
+    readonly remediation: string;
+}
+export interface ScopeProvenanceResult {
+    readonly exitCode: 0 | 1 | 2;
+    readonly findings: readonly ScopeProvenanceFinding[];
+    readonly message: string;
+}
+export interface ScopeProvenanceOptions {
+    /**
+     * When true, missing digests on modified active xBRIEFs fail closed.
+     * Default false = migration warn path.
+     */
+    readonly enforce?: boolean;
+    /** Base ref for diff (default HEAD). */
+    readonly baseRef?: string;
+    /** Inject changed files (repo-relative POSIX). */
+    readonly changedFiles?: readonly string[];
+    /** Inject active xBRIEF payloads: relPath -> raw JSON text. */
+    readonly activeXbriefs?: ReadonlyMap<string, string>;
+    /** Inject approved records (skips disk). */
+    readonly approvedRecords?: readonly ApprovedScopeRecord[];
+    /** Inject renewed-approval stamps keyed by planId (test seam). */
+    readonly renewedApprovals?: ReadonlyMap<string, ApprovedScopeRecord["humanApproval"]>;
+}
+/**
+ * Resolve a PR-aware base ref. Bare `HEAD` only shows uncommitted changes, so
+ * CI/PR checkouts would miss committed active-xBRIEF expansion. Prefer
+ * origin/master (or main) for merge-base comparison.
+ * Returns null when no merge-base candidate exists (caller fails closed).
+ */
+export declare function resolveDefaultBaseRef(projectRoot: string): string | null;
+/**
+ * Normalize git --name-only paths (including C-quoted paths).
+ * Decode C-quotes BEFORE converting remaining backslashes to `/` so escape
+ * sequences are not destroyed. Consecutive octal escapes decode as UTF-8
+ * bytes (e.g. \\303\\251 → é) so Unicode xBRIEF paths match filesystem names.
+ */
+export declare function unquoteGitPath(raw: string): string;
+/** Normalize repo-relative paths for exact set membership (always POSIX separators). */
+export declare function normalizeRepoRelPath(p: string): string;
+/**
+ * True when `rel` appears in the changed-path set under any normalization that
+ * Git C-quoting / slash folding may produce (Greptile conf=4 residual).
+ */
+export declare function changedSetHasPath(changedSet: ReadonlySet<string>, rel: string): boolean;
+/**
+ * Pure evaluation of one active xBRIEF against its approved baseline.
+ * Exported for unit tests without git.
+ */
+export declare function evaluateOneScopeProvenance(input: {
+    readonly xbriefRelPath: string;
+    readonly currentPayload: unknown;
+    readonly approved: ApprovedScopeRecord | null;
+    readonly xbriefModifiedInChangeSet: boolean;
+    readonly enforce: boolean;
+    readonly renewedHumanApproval?: ApprovedScopeRecord["humanApproval"] | null;
+}): ScopeProvenanceFinding | null;
+/**
+ * Evaluate scope provenance for a project (or pure injected seams).
+ */
+export declare function evaluateScopeProvenance(projectRoot: string, options?: ScopeProvenanceOptions): ScopeProvenanceResult;
+/** Re-export builder for activation hook callers. */
+export { buildApprovedScopeRecord, writeApprovedScopeRecord } from "./digest.js";
+//# sourceMappingURL=evaluate.d.ts.map