@deftai/directive-core 0.104.0 → 0.105.0

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

@@ -0,0 +1,149 @@
+/**
+ * Verify-time intent pin evaluation (#3376 R2–R6 / #3385).
+ *
+ * Reads base-committed record + preimage (never working-tree copies).
+ * Legacy records (no intentDigest) authorize paths only; intent edits warn.
+ * xbriefBodyDigest is never authority.
+ */
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { compareExtractedIntent } from "./compare-intent.js";
+import { approvedScopeIntentRel } from "./digest.js";
+import { extractIntentFromPayload, extractIntentFromRaw, } from "./extract-intent.js";
+import { computeIntentDigest, INTENT_DIGEST_ALGO } from "./intent-digest.js";
+import { parseJsonRejectingDuplicateKeys } from "./json-tokenizer.js";
+export function parseIntentPreimageRaw(raw) {
+    try {
+        const data = JSON.parse(raw);
+        if (data === null || typeof data !== "object" || Array.isArray(data))
+            return null;
+        const rec = data;
+        if (rec.schemaVersion !== 1)
+            return null;
+        if (rec.algo !== INTENT_DIGEST_ALGO)
+            return null;
+        if (rec.plan === null || typeof rec.plan !== "object" || Array.isArray(rec.plan))
+            return null;
+        if (!Array.isArray(rec.approvedRepos))
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+function remint() {
+    return ("Remint via `task scope:record-approved-scope -- <xbrief-path> --actor <you> --confirm` " +
+        "and commit `.deft/approved-scope/<plan-id>.json` plus `.intent.json` on the merge base. " +
+        "Read the preimage before committing (#3385).");
+}
+function mapCompare(f) {
+    if (f.kind === "unclassified-key")
+        return "unclassified-key";
+    return "intent-drift";
+}
+function finding(input, kind, detail, warnOnly = false) {
+    return {
+        kind,
+        planId: input.planId,
+        xbriefRelPath: input.xbriefRelPath,
+        detail,
+        remediation: remint(),
+        warnOnly,
+    };
+}
+function readBase(input, rel) {
+    if (input.readAtBase !== undefined)
+        return input.readAtBase(rel);
+    return null;
+}
+function decisionExists(input, rel) {
+    const fromBase = readBase(input, rel);
+    if (fromBase !== null)
+        return true;
+    const full = join(resolve(input.projectRoot), ...rel.split("/"));
+    return existsSync(full);
+}
+/**
+ * Evaluate intent pin for one modified active xBRIEF.
+ * Returns [] when intent is not in play (unmodified, or nothing to check).
+ */
+export function evaluateIntentForXbrief(input) {
+    if (!input.xbriefModified)
+        return [];
+    const parsed = parseJsonRejectingDuplicateKeys(input.liveRaw);
+    if (!parsed.ok) {
+        return [finding(input, "duplicate-key", parsed.error)];
+    }
+    const liveExtract = extractIntentFromPayload(parsed.value, {
+        projectRoot: input.projectRoot,
+        approvedReposSeed: input.approvedReposSeed,
+    });
+    if (!liveExtract.ok) {
+        if (liveExtract.error.includes("duplicate items[].id")) {
+            return [finding(input, "duplicate-item-id", liveExtract.error)];
+        }
+        return [finding(input, "intent-parse-error", liveExtract.error)];
+    }
+    if (input.approvalRewritten || input.preimageRewritten) {
+        return [
+            finding(input, "same-pr-intent-rewrite", "approved-scope record or preimage rewritten in the same change set; " +
+                "cannot self-authorize intent"),
+        ];
+    }
+    const hasIntent = input.approved !== null &&
+        typeof input.approved.intentDigest === "string" &&
+        input.approved.intentDigest.length > 0;
+    if (!hasIntent) {
+        return evaluateLegacyIntent(input, liveExtract.preimage);
+    }
+    const preimageRel = approvedScopeIntentRel(input.planId);
+    const basePreimageRaw = readBase(input, preimageRel);
+    if (basePreimageRaw === null) {
+        if (input.currentScopeNonEmpty) {
+            return [
+                finding(input, "first-activation-missing-intent-pin", "first activation with nonempty scope requires a base-committed record + preimage"),
+            ];
+        }
+        return [];
+    }
+    const basePreimage = parseIntentPreimageRaw(basePreimageRaw);
+    if (basePreimage === null) {
+        return [finding(input, "intent-digest-mismatch", "base preimage is malformed")];
+    }
+    const expected = computeIntentDigest(basePreimage);
+    if (expected !== input.approved?.intentDigest) {
+        return [
+            finding(input, "intent-digest-mismatch", "base preimage digest does not match record intentDigest"),
+        ];
+    }
+    const compared = compareExtractedIntent(basePreimage, liveExtract.preimage, {
+        changedFiles: input.changedFiles,
+        decisionExists: (rel) => decisionExists(input, rel),
+    });
+    return compared.findings.map((f) => finding(input, mapCompare(f), f.detail));
+}
+function evaluateLegacyIntent(input, live) {
+    const baseRaw = readBase(input, input.xbriefRelPath);
+    if (baseRaw === null) {
+        return [];
+    }
+    const baseExtract = extractIntentFromRaw(baseRaw, {
+        projectRoot: input.projectRoot,
+        approvedReposSeed: input.approvedReposSeed,
+    });
+    if (!baseExtract.ok)
+        return [];
+    const compared = compareExtractedIntent(baseExtract.preimage, live, {
+        changedFiles: input.changedFiles,
+        decisionExists: (rel) => decisionExists(input, rel),
+    });
+    if (compared.ok)
+        return [];
+    return compared.findings.map((f) => finding(input, "legacy-intent-edit", f.detail, true));
+}
+/** Explicit: never treat xbriefBodyDigest as authority. */
+export function bodyDigestIsAuthority(_rec) {
+    return false;
+}
+//# sourceMappingURL=intent-evaluate.js.map

package/dist/scope-provenance/json-tokenizer.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Validating JSON tokenizer for scope-provenance intent parse (#3385 F3 / E9).
+ *
+ * JSON.parse collapses duplicate object keys; a reviver never sees them.
+ * This scanner rejects duplicate keys (including nested) and does not treat
+ * JSON-looking text inside string values as structure.
+ */
+export interface JsonParseOk {
+    readonly ok: true;
+    readonly value: unknown;
+}
+export interface JsonParseErr {
+    readonly ok: false;
+    readonly error: string;
+}
+export type JsonParseResult = JsonParseOk | JsonParseErr;
+/** Parse JSON and reject duplicate object keys (nested included). */
+export declare function parseJsonRejectingDuplicateKeys(text: string): JsonParseResult;
+//# sourceMappingURL=json-tokenizer.d.ts.map

package/dist/scope-provenance/json-tokenizer.js

@@ -0,0 +1,225 @@
+/**
+ * Validating JSON tokenizer for scope-provenance intent parse (#3385 F3 / E9).
+ *
+ * JSON.parse collapses duplicate object keys; a reviver never sees them.
+ * This scanner rejects duplicate keys (including nested) and does not treat
+ * JSON-looking text inside string values as structure.
+ */
+class Scanner {
+    s;
+    i = 0;
+    constructor(s) {
+        this.s = s;
+    }
+    parseDocument() {
+        this.skipWs();
+        const value = this.parseValue();
+        this.skipWs();
+        if (this.i < this.s.length) {
+            throw new Error(`trailing content at ${this.i}`);
+        }
+        return value;
+    }
+    peek() {
+        return this.s[this.i] ?? "";
+    }
+    next() {
+        const ch = this.s[this.i] ?? "";
+        this.i += 1;
+        return ch;
+    }
+    skipWs() {
+        while (this.i < this.s.length) {
+            const c = this.s[this.i];
+            if (c === " " || c === "\t" || c === "\n" || c === "\r") {
+                this.i += 1;
+                continue;
+            }
+            break;
+        }
+    }
+    parseValue() {
+        this.skipWs();
+        const c = this.peek();
+        if (c === '"')
+            return this.parseString();
+        if (c === "{")
+            return this.parseObject();
+        if (c === "[")
+            return this.parseArray();
+        if (c === "t" || c === "f")
+            return this.parseLiteralBool();
+        if (c === "n")
+            return this.parseNull();
+        if (c === "-" || (c >= "0" && c <= "9"))
+            return this.parseNumber();
+        throw new Error(`unexpected token at ${this.i}`);
+    }
+    parseObject() {
+        this.next(); // {
+        this.skipWs();
+        const out = {};
+        const seen = new Set();
+        if (this.peek() === "}") {
+            this.next();
+            return out;
+        }
+        while (true) {
+            this.skipWs();
+            if (this.peek() !== '"') {
+                throw new Error(`expected object key at ${this.i}`);
+            }
+            const key = this.parseString();
+            if (seen.has(key)) {
+                throw new Error(`duplicate key ${JSON.stringify(key)}`);
+            }
+            seen.add(key);
+            this.skipWs();
+            if (this.next() !== ":") {
+                throw new Error(`expected ':' after key at ${this.i}`);
+            }
+            out[key] = this.parseValue();
+            this.skipWs();
+            const sep = this.next();
+            if (sep === "}")
+                return out;
+            if (sep !== ",") {
+                throw new Error(`expected ',' or '}' at ${this.i}`);
+            }
+        }
+    }
+    parseArray() {
+        this.next(); // [
+        this.skipWs();
+        const out = [];
+        if (this.peek() === "]") {
+            this.next();
+            return out;
+        }
+        while (true) {
+            out.push(this.parseValue());
+            this.skipWs();
+            const sep = this.next();
+            if (sep === "]")
+                return out;
+            if (sep !== ",") {
+                throw new Error(`expected ',' or ']' at ${this.i}`);
+            }
+        }
+    }
+    parseString() {
+        this.next(); // "
+        let out = "";
+        while (this.i < this.s.length) {
+            const c = this.next();
+            if (c === '"')
+                return out;
+            if (c === "\\") {
+                out += this.parseEscape();
+                continue;
+            }
+            if (c.charCodeAt(0) < 0x20) {
+                throw new Error(`unescaped control in string at ${this.i}`);
+            }
+            out += c;
+        }
+        throw new Error("unterminated string");
+    }
+    parseEscape() {
+        const c = this.next();
+        switch (c) {
+            case '"':
+            case "\\":
+            case "/":
+                return c;
+            case "b":
+                return "\b";
+            case "f":
+                return "\f";
+            case "n":
+                return "\n";
+            case "r":
+                return "\r";
+            case "t":
+                return "\t";
+            case "u": {
+                const hex = this.s.slice(this.i, this.i + 4);
+                if (!/^[0-9a-fA-F]{4}$/.test(hex)) {
+                    throw new Error(`invalid unicode escape at ${this.i}`);
+                }
+                this.i += 4;
+                return String.fromCharCode(parseInt(hex, 16));
+            }
+            default:
+                throw new Error(`invalid escape at ${this.i}`);
+        }
+    }
+    parseNumber() {
+        const start = this.i;
+        if (this.peek() === "-")
+            this.next();
+        if (this.peek() === "0") {
+            this.next();
+        }
+        else {
+            if (this.peek() < "1" || this.peek() > "9") {
+                throw new Error(`invalid number at ${start}`);
+            }
+            while (this.peek() >= "0" && this.peek() <= "9")
+                this.next();
+        }
+        if (this.peek() === ".") {
+            this.next();
+            if (this.peek() < "0" || this.peek() > "9") {
+                throw new Error(`invalid fraction at ${this.i}`);
+            }
+            while (this.peek() >= "0" && this.peek() <= "9")
+                this.next();
+        }
+        if (this.peek() === "e" || this.peek() === "E") {
+            this.next();
+            if (this.peek() === "+" || this.peek() === "-")
+                this.next();
+            if (this.peek() < "0" || this.peek() > "9") {
+                throw new Error(`invalid exponent at ${this.i}`);
+            }
+            while (this.peek() >= "0" && this.peek() <= "9")
+                this.next();
+        }
+        const n = Number(this.s.slice(start, this.i));
+        if (!Number.isFinite(n)) {
+            throw new Error(`invalid number at ${start}`);
+        }
+        return n;
+    }
+    parseLiteralBool() {
+        if (this.s.startsWith("true", this.i)) {
+            this.i += 4;
+            return true;
+        }
+        if (this.s.startsWith("false", this.i)) {
+            this.i += 5;
+            return false;
+        }
+        throw new Error(`invalid literal at ${this.i}`);
+    }
+    parseNull() {
+        if (this.s.startsWith("null", this.i)) {
+            this.i += 4;
+            return null;
+        }
+        throw new Error(`invalid literal at ${this.i}`);
+    }
+}
+/** Parse JSON and reject duplicate object keys (nested included). */
+export function parseJsonRejectingDuplicateKeys(text) {
+    try {
+        const value = new Scanner(text).parseDocument();
+        return { ok: true, value };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: msg };
+    }
+}
+//# sourceMappingURL=json-tokenizer.js.map

package/dist/scope-provenance/known-machine.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Known-machine vs extracted classification for plan.* (#3376 R1 / #3385 F1).
+ *
+ * Seeded from the #3376 corpus inventory (capacity stamps, completion
+ * provenance, swarm readiness, tags-as-label-mirror). Growing this list MUST
+ * land with a writer annotation in KNOWN_MACHINE_WRITERS (same-PR CI rule)
+ * and MUST NOT change existing intent digests.
+ */
+export type KeyClass = "extract" | "extract-partial" | "machine" | "unknown";
+/** Recursive walk nodes (not pinned wholesale). */
+export declare const PARTIAL_NODES: Set<string>;
+/** plan.* keys that are machine space (never hash inputs). */
+export declare const PLAN_MACHINE_KEYS: Set<string>;
+/** plan.metadata.* machine keys / wholesale machine subtrees. */
+export declare const METADATA_MACHINE_KEYS: Set<string>;
+/** plan.metadata.swarm.* machine keys. */
+export declare const SWARM_MACHINE_KEYS: Set<string>;
+/** plan.items[] machine keys (raw planRef is machine; parentId is extracted). */
+export declare const ITEM_MACHINE_KEYS: Set<string>;
+/** reference fields that are never extracted. */
+export declare const REFERENCE_MACHINE_KEYS: Set<string>;
+/** Item fields copied into the preimage when present. */
+export declare const ITEM_EXTRACT_KEYS: readonly ["id", "title", "summary", "narrative", "type"];
+/** Swarm fields extracted as intent (prose + file_scope for review). */
+export declare const SWARM_EXTRACT_KEYS: Set<string>;
+/**
+ * Writer annotation for each known-machine key. Adding a key without an entry
+ * fails the same-PR writer-discipline test (#3385 F1).
+ */
+export declare const KNOWN_MACHINE_WRITERS: Readonly<Record<string, {
+    writer: string;
+}>>;
+export declare function classifyPlanPath(path: string): KeyClass;
+export declare function classifyItemKey(key: string): KeyClass;
+export declare function classifyReferenceKey(key: string): KeyClass;
+/** Every known-machine leaf that the writer-discipline test enumerates. */
+export declare function allKnownMachineLeaves(): string[];
+//# sourceMappingURL=known-machine.d.ts.map

package/dist/scope-provenance/known-machine.js

@@ -0,0 +1,157 @@
+/**
+ * Known-machine vs extracted classification for plan.* (#3376 R1 / #3385 F1).
+ *
+ * Seeded from the #3376 corpus inventory (capacity stamps, completion
+ * provenance, swarm readiness, tags-as-label-mirror). Growing this list MUST
+ * land with a writer annotation in KNOWN_MACHINE_WRITERS (same-PR CI rule)
+ * and MUST NOT change existing intent digests.
+ */
+/** Recursive walk nodes (not pinned wholesale). */
+export const PARTIAL_NODES = new Set(["", "metadata", "metadata.swarm"]);
+/** plan.* keys that are machine space (never hash inputs). */
+export const PLAN_MACHINE_KEYS = new Set([
+    "status",
+    "updated",
+    "created",
+    "createdAt",
+    "updatedAt",
+    "completed",
+    "percentComplete",
+    "tags",
+    "planRef",
+    "plan_ref",
+]);
+/** plan.metadata.* machine keys / wholesale machine subtrees. */
+export const METADATA_MACHINE_KEYS = new Set([
+    "capacityBucket",
+    "capacityBucketSource",
+    "completionProvenance",
+    "deliveryDisposition",
+    "handoffState",
+    "parent_lineage",
+    "parentLineage",
+    "x-migrator",
+]);
+/** plan.metadata.swarm.* machine keys. */
+export const SWARM_MACHINE_KEYS = new Set([
+    "readiness",
+    "parallel_safe",
+    "verify_commands",
+    "expected_outputs",
+    "depends_on",
+    "conflict_group",
+    "size",
+    "file_scope_confidence",
+    "model_tier",
+]);
+/** plan.items[] machine keys (raw planRef is machine; parentId is extracted). */
+export const ITEM_MACHINE_KEYS = new Set([
+    "status",
+    "completed",
+    "percentComplete",
+    "effort",
+    "updated",
+    "created",
+    "planRef",
+    "plan_ref",
+]);
+/** reference fields that are never extracted. */
+export const REFERENCE_MACHINE_KEYS = new Set(["TrustLevel", "trustLevel"]);
+/** Item fields copied into the preimage when present. */
+export const ITEM_EXTRACT_KEYS = ["id", "title", "summary", "narrative", "type"];
+/** Swarm fields extracted as intent (prose + file_scope for review). */
+export const SWARM_EXTRACT_KEYS = new Set([
+    "file_scope",
+    "missing_traces_justification",
+    "acceptance_criteria_justification",
+    "notes",
+]);
+/**
+ * Writer annotation for each known-machine key. Adding a key without an entry
+ * fails the same-PR writer-discipline test (#3385 F1).
+ */
+export const KNOWN_MACHINE_WRITERS = {
+    "plan.status": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.updated": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.created": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.createdAt": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.updatedAt": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.completed": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.percentComplete": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.tags": { writer: "packages/core/src/intake/issue-ingest.ts" },
+    "plan.planRef": { writer: "packages/core/src/scope/decomposed-refs.ts" },
+    "plan.plan_ref": { writer: "packages/core/src/scope/decomposed-refs.ts" },
+    "plan.metadata.capacityBucket": { writer: "packages/core/src/scope/capacity-stamp.ts" },
+    "plan.metadata.capacityBucketSource": { writer: "packages/core/src/scope/capacity-stamp.ts" },
+    "plan.metadata.completionProvenance": { writer: "packages/core/src/scope/delivery-evidence.ts" },
+    "plan.metadata.deliveryDisposition": { writer: "packages/core/src/scope/delivery-evidence.ts" },
+    "plan.metadata.handoffState": { writer: "packages/core/src/scope/delivery-evidence.ts" },
+    "plan.metadata.parent_lineage": { writer: "packages/core/src/scope/parent-lineage.ts" },
+    "plan.metadata.parentLineage": { writer: "packages/core/src/scope/parent-lineage.ts" },
+    "plan.metadata.x-migrator": { writer: "packages/core/src/xbrief-migrate" },
+    "plan.metadata.swarm.readiness": { writer: "packages/core/src/swarm/complete-cohort.ts" },
+    "plan.metadata.swarm.parallel_safe": { writer: "packages/core/src/swarm/complete-cohort.ts" },
+    "plan.metadata.swarm.verify_commands": { writer: "packages/core/src/swarm/launch.ts" },
+    "plan.metadata.swarm.expected_outputs": { writer: "packages/core/src/swarm/launch.ts" },
+    "plan.metadata.swarm.depends_on": { writer: "packages/core/src/swarm/launch.ts" },
+    "plan.metadata.swarm.conflict_group": { writer: "packages/core/src/swarm/launch.ts" },
+    "plan.metadata.swarm.size": { writer: "packages/core/src/swarm/launch.ts" },
+    "plan.metadata.swarm.file_scope_confidence": { writer: "packages/core/src/swarm/launch.ts" },
+    "plan.metadata.swarm.model_tier": { writer: "packages/core/src/swarm/launch.ts" },
+    "plan.items[].status": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.items[].completed": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.items[].percentComplete": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.items[].effort": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.items[].updated": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.items[].created": { writer: "packages/core/src/scope/transition.ts" },
+    "plan.items[].planRef": { writer: "packages/core/src/scope/decomposed-refs.ts" },
+    "plan.items[].plan_ref": { writer: "packages/core/src/scope/decomposed-refs.ts" },
+    "plan.references[].TrustLevel": { writer: "packages/core/src/intake/issue-ingest.ts" },
+    "plan.references[].trustLevel": { writer: "packages/core/src/intake/issue-ingest.ts" },
+};
+export function classifyPlanPath(path) {
+    if (PARTIAL_NODES.has(path))
+        return "extract-partial";
+    if (path === "items" ||
+        path === "references" ||
+        path === "metadata" ||
+        path === "metadata.swarm") {
+        return "extract-partial";
+    }
+    if (PLAN_MACHINE_KEYS.has(path))
+        return "machine";
+    if (path.startsWith("metadata.") && METADATA_MACHINE_KEYS.has(path.slice("metadata.".length))) {
+        return "machine";
+    }
+    if (path.startsWith("metadata.swarm.")) {
+        const leaf = path.slice("metadata.swarm.".length);
+        if (SWARM_MACHINE_KEYS.has(leaf))
+            return "machine";
+        if (SWARM_EXTRACT_KEYS.has(leaf))
+            return "extract";
+        return "unknown";
+    }
+    if (path === "edges" || path === "title" || path === "narratives" || path === "acceptance") {
+        return "extract";
+    }
+    if (path === "architecture" || path === "id")
+        return "extract";
+    return "unknown";
+}
+export function classifyItemKey(key) {
+    if (ITEM_MACHINE_KEYS.has(key))
+        return "machine";
+    if (ITEM_EXTRACT_KEYS.includes(key))
+        return "extract";
+    return "unknown";
+}
+export function classifyReferenceKey(key) {
+    if (REFERENCE_MACHINE_KEYS.has(key))
+        return "machine";
+    return "extract";
+}
+/** Every known-machine leaf that the writer-discipline test enumerates. */
+export function allKnownMachineLeaves() {
+    return Object.keys(KNOWN_MACHINE_WRITERS).sort((a, b) => a.localeCompare(b));
+}
+//# sourceMappingURL=known-machine.js.map