@deftai/directive-core 0.106.0 → 0.107.0

package/dist/check/gate-lists.js

@@ -64,6 +64,7 @@ export const FRAMEWORK_CHECK_GATES = [
     "verify:encoding",
     "verify:cache-fresh",
     "verify:orphan-active",
+    "verify:completed-write-guard",
     "verify:license-sync",
     "verify:contract-drift",
     "toolchain:check",
@@ -111,6 +112,7 @@ export const CONSUMER_CHECK_GATES = [
     "verify:cache-fresh",
     "verify:wip-cap",
     "verify:orphan-active",
+    "verify:completed-write-guard",
     "doctor",
     "toolchain:check-consumer",
     // #3145 enforcement trio (test placement, scope provenance, gate composition)

package/dist/design-critique/exclusive-chip.d.ts

@@ -0,0 +1,33 @@
+import type { LabelClient } from "../vbrief-reconcile/types.js";
+/** Closed catalog. Last chip wins. Not an open `design-critique:*` glob. */
+export declare const DESIGN_CRITIQUE_CATALOG_CHIPS: readonly ["design-critique:mechanism-shaped", "design-critique:triage-ready"];
+export type DesignCritiqueCatalogChip = (typeof DESIGN_CRITIQUE_CATALOG_CHIPS)[number];
+export declare function isDesignCritiqueCatalogChip(name: string): name is DesignCritiqueCatalogChip;
+/**
+ * Remaining-set replace: GET current, drop the other catalog names, keep other
+ * facets, then PUT/PATCH this list. One write. No DELETE-then-POST window.
+ */
+export declare function remainingSetAfterDesignCritiqueChip(current: readonly string[], nextChip: string): string[];
+/**
+ * Fold exclusive catalog-chip replace into a LabelClient.apply add/remove
+ * mutation. Production writer: ScmLabelClient.apply.
+ */
+export declare function mergeDesignCritiqueExclusiveIntoApply(current: readonly string[], add: readonly string[], remove: readonly string[]): {
+    add: string[];
+    remove: string[];
+};
+/** Delta for LabelClient.apply (one add+remove mutation). */
+export declare function designCritiqueChipApplyDelta(current: readonly string[], nextChip: string): {
+    add: string[];
+    remove: string[];
+};
+/**
+ * Exclusive catalog-chip write via LabelClient.apply. GET current, then one
+ * apply(add, remove). Does not PUT a naive full wipe.
+ */
+export declare function applyDesignCritiqueCatalogChip(client: LabelClient, repo: string, issueNumber: number, nextChip: string): {
+    remaining: string[];
+    add: readonly string[];
+    remove: readonly string[];
+};
+//# sourceMappingURL=exclusive-chip.d.ts.map

package/dist/design-critique/exclusive-chip.js

@@ -0,0 +1,68 @@
+/** Closed catalog. Last chip wins. Not an open `design-critique:*` glob. */
+export const DESIGN_CRITIQUE_CATALOG_CHIPS = [
+    "design-critique:mechanism-shaped",
+    "design-critique:triage-ready",
+];
+const CATALOG = new Set(DESIGN_CRITIQUE_CATALOG_CHIPS);
+export function isDesignCritiqueCatalogChip(name) {
+    return CATALOG.has(name);
+}
+/**
+ * Remaining-set replace: GET current, drop the other catalog names, keep other
+ * facets, then PUT/PATCH this list. One write. No DELETE-then-POST window.
+ */
+export function remainingSetAfterDesignCritiqueChip(current, nextChip) {
+    if (!isDesignCritiqueCatalogChip(nextChip)) {
+        throw new Error(`not a design-critique catalog chip: ${nextChip} (closed set: ${DESIGN_CRITIQUE_CATALOG_CHIPS.join(", ")})`);
+    }
+    const remaining = current.filter((name) => !CATALOG.has(name));
+    remaining.push(nextChip);
+    return remaining;
+}
+/**
+ * Fold exclusive catalog-chip replace into a LabelClient.apply add/remove
+ * mutation. Production writer: ScmLabelClient.apply.
+ */
+export function mergeDesignCritiqueExclusiveIntoApply(current, add, remove) {
+    const catalogAdds = add.filter(isDesignCritiqueCatalogChip);
+    if (catalogAdds.length === 0) {
+        return { add: [...add], remove: [...remove] };
+    }
+    const nextChip = catalogAdds[catalogAdds.length - 1];
+    const delta = designCritiqueChipApplyDelta(current, nextChip);
+    const addSet = new Set(add.filter((name) => !isDesignCritiqueCatalogChip(name) || name === nextChip));
+    for (const name of delta.add)
+        addSet.add(name);
+    const removeSet = new Set(remove.filter((name) => name !== nextChip));
+    for (const name of delta.remove)
+        removeSet.add(name);
+    removeSet.delete(nextChip);
+    return { add: [...addSet], remove: [...removeSet] };
+}
+/** Delta for LabelClient.apply (one add+remove mutation). */
+export function designCritiqueChipApplyDelta(current, nextChip) {
+    if (!isDesignCritiqueCatalogChip(nextChip)) {
+        throw new Error(`not a design-critique catalog chip: ${nextChip} (closed set: ${DESIGN_CRITIQUE_CATALOG_CHIPS.join(", ")})`);
+    }
+    const currentSet = new Set(current);
+    const remove = DESIGN_CRITIQUE_CATALOG_CHIPS.filter((name) => name !== nextChip && currentSet.has(name));
+    const add = currentSet.has(nextChip) ? [] : [nextChip];
+    return { add, remove };
+}
+/**
+ * Exclusive catalog-chip write via LabelClient.apply. GET current, then one
+ * apply(add, remove). Does not PUT a naive full wipe.
+ */
+export function applyDesignCritiqueCatalogChip(client, repo, issueNumber, nextChip) {
+    const current = client.fetchLabels(repo, issueNumber);
+    const { add, remove } = designCritiqueChipApplyDelta(current, nextChip);
+    if (add.length > 0 || remove.length > 0) {
+        client.apply(repo, issueNumber, add, remove);
+    }
+    return {
+        remaining: remainingSetAfterDesignCritiqueChip(current, nextChip),
+        add,
+        remove,
+    };
+}
+//# sourceMappingURL=exclusive-chip.js.map

package/dist/design-critique/parent-audit.d.ts

@@ -0,0 +1,59 @@
+/** Parent-side substantiation deposit + fail-closed evaluator (#3651 / ADR-006). */
+export type AuditReading = "measured" | "asserted";
+export type AuditRole = "parent" | "critic" | "triage";
+export type AuditPremise = {
+    markerId: string;
+    sha?: string;
+    pointer?: string;
+    reading?: AuditReading;
+    introducedByRole: AuditRole;
+    /** Changes classification, residual, or next-build contract. */
+    loadBearing: boolean;
+};
+export type AuditClearance = {
+    markerId: string;
+    clearedByRole: AuditRole;
+    /** Critic artifact names this marker as its audit target. */
+    targetsMarker: boolean;
+};
+export type AuditEnvelope = {
+    /** Marker ids listed on `audit-targets:`. Empty means the field was omitted. */
+    auditTargets: string[];
+    /** Envelope explicitly set `audit-targets: none`. */
+    declaredNone: boolean;
+};
+export type AuditBindAttempt = {
+    allAcceptMap: boolean;
+    /** Marker ids the bind record still lists as unresolved. */
+    unresolvedMarkerIds: string[];
+};
+export type ParentAuditDeposit = {
+    premises: readonly AuditPremise[];
+    clearances: readonly AuditClearance[];
+    envelopes: readonly AuditEnvelope[];
+    /** Ids the next critic envelope must name. */
+    namedAuditTargets?: readonly string[];
+    bindAttempt?: AuditBindAttempt;
+};
+export type AuditFailureCode = "missing-token" | "parent-self-clear" | "silent-clear" | "bind-unresolved" | "envelope-omits-target" | "marker-collision";
+export type AuditFailure = {
+    code: AuditFailureCode;
+    detail: string;
+};
+export declare function parseAuditToken(token: string): {
+    markerId: string;
+    sha: string;
+    pointer: string;
+    reading: AuditReading;
+} | null;
+export declare function formatAuditToken(parts: {
+    markerId: string;
+    sha: string;
+    pointer: string;
+    reading: AuditReading;
+}): string;
+export declare function evaluateParentAudit(deposit: ParentAuditDeposit): {
+    ok: boolean;
+    failures: AuditFailure[];
+};
+//# sourceMappingURL=parent-audit.d.ts.map

package/dist/design-critique/parent-audit.js

@@ -0,0 +1,121 @@
+/** Parent-side substantiation deposit + fail-closed evaluator (#3651 / ADR-006). */
+const TOKEN_RE = /^audit:([A-Za-z0-9._-]+) sha=([0-9a-fA-F]{7,40}) pointer=(\S+) reading=(measured|asserted)$/;
+export function parseAuditToken(token) {
+    const match = TOKEN_RE.exec(token.trim());
+    if (!match)
+        return null;
+    return {
+        markerId: match[1] ?? "",
+        sha: match[2] ?? "",
+        pointer: match[3] ?? "",
+        reading: (match[4] ?? "asserted"),
+    };
+}
+export function formatAuditToken(parts) {
+    return `audit:${parts.markerId} sha=${parts.sha} pointer=${parts.pointer} reading=${parts.reading}`;
+}
+function independentlyCleared(markerId, clearances, colliding) {
+    if (colliding.has(markerId))
+        return false;
+    return clearances.some((c) => c.markerId === markerId && c.clearedByRole === "critic" && c.targetsMarker);
+}
+function collidingMarkerIds(premises) {
+    const counts = new Map();
+    for (const premise of premises) {
+        if (!premise.loadBearing)
+            continue;
+        counts.set(premise.markerId, (counts.get(premise.markerId) ?? 0) + 1);
+    }
+    return new Set([...counts.entries()].filter(([, n]) => n > 1).map(([id]) => id));
+}
+export function evaluateParentAudit(deposit) {
+    const failures = [];
+    const colliding = collidingMarkerIds(deposit.premises);
+    for (const id of colliding) {
+        failures.push({
+            code: "marker-collision",
+            detail: `load-bearing premises share marker ${id}`,
+        });
+    }
+    for (const premise of deposit.premises) {
+        if (!premise.loadBearing)
+            continue;
+        if (!premise.sha || !premise.pointer || !premise.reading) {
+            failures.push({
+                code: "missing-token",
+                detail: `premise ${premise.markerId} is missing sha, pointer, or reading`,
+            });
+            continue;
+        }
+        const token = formatAuditToken({
+            markerId: premise.markerId,
+            sha: premise.sha,
+            pointer: premise.pointer,
+            reading: premise.reading,
+        });
+        if (!parseAuditToken(token)) {
+            failures.push({
+                code: "missing-token",
+                detail: `premise ${premise.markerId} token failed grammar`,
+            });
+        }
+    }
+    for (const clearance of deposit.clearances) {
+        if (clearance.clearedByRole === "parent") {
+            failures.push({
+                code: "parent-self-clear",
+                detail: `parent cleared marker ${clearance.markerId}`,
+            });
+        }
+    }
+    const computedUnresolved = deposit.premises
+        .filter((p) => p.loadBearing && !independentlyCleared(p.markerId, deposit.clearances, colliding))
+        .map((p) => p.markerId);
+    const named = deposit.namedAuditTargets ?? [];
+    if (named.length > 0) {
+        if (deposit.envelopes.length === 0) {
+            failures.push({
+                code: "envelope-omits-target",
+                detail: `no envelope named audit targets ${named.join(",")}`,
+            });
+        }
+        for (const envelope of deposit.envelopes) {
+            if (envelope.declaredNone) {
+                failures.push({
+                    code: "envelope-omits-target",
+                    detail: "envelope declared none while named audit targets exist",
+                });
+                continue;
+            }
+            for (const id of named) {
+                if (!envelope.auditTargets.includes(id)) {
+                    failures.push({
+                        code: "envelope-omits-target",
+                        detail: `envelope omitted audit target ${id}`,
+                    });
+                }
+            }
+        }
+    }
+    const bind = deposit.bindAttempt;
+    if (bind) {
+        const declared = new Set(bind.unresolvedMarkerIds);
+        for (const id of computedUnresolved) {
+            if (!declared.has(id)) {
+                failures.push({
+                    code: "silent-clear",
+                    detail: `marker ${id} dropped from unresolved without critic clearance`,
+                });
+            }
+        }
+        const unresolvedForBind = [...new Set([...computedUnresolved, ...bind.unresolvedMarkerIds])];
+        if (bind.allAcceptMap && unresolvedForBind.length > 0) {
+            failures.push({
+                code: "bind-unresolved",
+                detail: `all-accept bind with unresolved markers ${unresolvedForBind.join(",")}`,
+            });
+        }
+    }
+    return { ok: failures.length === 0, failures };
+}
+//# sourceMappingURL=parent-audit.js.map

package/dist/doctor/checks.d.ts

@@ -106,6 +106,12 @@ export declare function checkCompletedLifecycleConsistency(projectRoot: string):
  * historical pre-#2862 corpora do not red-light doctor; scope:complete fails closed.
  */
 export declare function checkCompletedOpenItems(projectRoot: string): CheckResult;
+/**
+ * Surface completed/ artifacts that never passed runTransition (#3679).
+ * Exit-exempt so historical corpora do not red-light doctor; the change-set
+ * verify (`verify:completed-write-guard`) fails closed on new adds.
+ */
+export declare function checkCompletedUnguardedWrite(projectRoot: string): CheckResult;
 /**
  * Surface invalid coverageDebt + checkResume typed blocks (#3314).
  * Absent / default / valid typed values pass. Invalid blocks skip (advisory,

package/dist/doctor/checks.js

@@ -6,6 +6,7 @@ import { detectDualLayout, detectLegacyLayout, dualLayoutSignpostLine, legacyLay
 import { detectCanonicalVendoredManifest, isNpmManaged, NPM_MANAGED_SENTINEL_KEY, NPM_MANAGED_SENTINEL_VALUE, } from "../init-deposit/migrate.js";
 import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { scanCompletedLifecycleConsistency } from "../lifecycle/completed-consistency.js";
+import { scanCompletedWriteCorpus } from "../lifecycle/completed-write-guard.js";
 import { resolveCheckResume } from "../policy/check-resume.js";
 import { resolveCoverageDebt } from "../policy/coverage-debt.js";
 import { classifyXbriefSchemaDistance } from "../staleness-tickler/probe-xbrief.js";
@@ -34,6 +35,7 @@ export const DOCTOR_ADVISORY_FAIL_CHECKS = new Set([
     "stale-xbrief-schema-deposit",
     "typescript-7-side-by-side",
     "completed-open-items",
+    "completed-unguarded-write",
     "coverage-check-resume-policy",
 ]);
 /** True when a check fail must stay a warning (not lastErrorCount / exit 1). */
@@ -1167,6 +1169,37 @@ export function checkCompletedOpenItems(projectRoot) {
         },
     };
 }
+/**
+ * Surface completed/ artifacts that never passed runTransition (#3679).
+ * Exit-exempt so historical corpora do not red-light doctor; the change-set
+ * verify (`verify:completed-write-guard`) fails closed on new adds.
+ */
+export function checkCompletedUnguardedWrite(projectRoot) {
+    const checkName = "completed-unguarded-write";
+    const result = scanCompletedWriteCorpus(projectRoot);
+    if (result.findings.length === 0) {
+        return {
+            name: checkName,
+            status: "pass",
+            detail: "Completed write-guard OK (#3679): no completed/ artifacts lack a runTransition write",
+            data: { finding_count: 0, scanned: result.scanned },
+        };
+    }
+    const message = `Completed unguarded writes (#3679, advisory). ` +
+        `${result.findings.length} artifact(s) under completed/ have no runTransition write:\n` +
+        result.findings.map((f) => `  - ${f.detail}`).join("\n") +
+        `\nNew adds fail closed via verify:completed-write-guard; historical corpus is advisory.`;
+    return {
+        name: checkName,
+        status: "fail",
+        detail: message,
+        data: {
+            finding_count: result.findings.length,
+            advisory: true,
+            findings: result.findings.map((f) => ({ rel_path: f.relPath, detail: f.detail })),
+        },
+    };
+}
 /**
  * Surface invalid coverageDebt + checkResume typed blocks (#3314).
  * Absent / default / valid typed values pass. Invalid blocks skip (advisory,
@@ -1248,6 +1281,7 @@ export function runChecksImpl(projectRoot, seams = {}) {
         checks.push(checkCoverageCheckResumePolicy(projectRoot));
         checks.push(checkCompletedLifecycleConsistency(projectRoot));
         checks.push(checkCompletedOpenItems(projectRoot));
+        checks.push(checkCompletedUnguardedWrite(projectRoot));
         return {
             projectRoot,
             installRoot: null,
@@ -1270,6 +1304,7 @@ export function runChecksImpl(projectRoot, seams = {}) {
     checks.push(checkCoverageCheckResumePolicy(projectRoot));
     checks.push(checkCompletedLifecycleConsistency(projectRoot));
     checks.push(checkCompletedOpenItems(projectRoot));
+    checks.push(checkCompletedUnguardedWrite(projectRoot));
     return {
         projectRoot,
         installRoot,

package/dist/hooks/dest-form.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Product dest-form classifier for in-repo Shell mutations (#3438).
+ *
+ * NEW harvest — do not reuse `classifyShellAuthzOps` / `listShellOps` as-is.
+ * Those return [] for `git checkout --` / `rm` of ordinary product paths.
+ *
+ * ! Resolves a target for ONE shape only: a single simple command. Everything
+ * else is recognized and fail-closed. Reconstructing a target from shell state
+ * was implemented and withdrawn — cwd depends on operator precedence, on exit
+ * status, on subshell boundaries, and on git config, and every resolution rule
+ * added produced its own fence bypass. Do not add it back; widen the recognized
+ * *forms* instead, and see `content/contracts/path-write-fence.md`.
+ *
+ * Residual known-open (recognition, not resolution): `python -c`,
+ * `cmd /c copy`, obfuscated `bash -c`.
+ *
+ * Commit-time active-scope is out of this slice (#3438), and ⊗ do not weaken
+ * Edit to match Shell. Keep this sentence on ONE line: acceptance clause 4 is
+ * verified by a literal token search, so wrapping it silently fails the gate.
+ */
+export type ProductDestFormKind = "git-checkout" | "git-restore" | "rm" | "rmdir";
+export interface ProductDestForm {
+    readonly kind: ProductDestFormKind;
+    readonly path: string;
+    /**
+     * True when the target is not provable — a glob/variable or leading `~` dest,
+     * a git context option, or any command that is not a single simple one. The
+     * dispatcher denies these outright; `path` is then only for the message, and
+     * is `SHELL_DEST_EXPANSION_SENTINEL` when no token can be named.
+     */
+    readonly expansion?: boolean;
+}
+/** Injected write target for expansion dests so the fence cannot match a literal glob. */
+export declare const SHELL_DEST_EXPANSION_SENTINEL = "__shell_dest_expansion__";
+/**
+ * Inject a dest path so `inspectMutationGates` sees the same write target as Edit/Write.
+ * Preserves original payload fields (command, posture markers).
+ */
+export declare function payloadWithInjectedWriteTarget(payload: unknown, destPath: string): Record<string, unknown>;
+/**
+ * Classify recognized product dest-forms in a shell command (#3438 v1 list).
+ * Empty when the command is not `git checkout -- <paths>`, `git restore`, or `rm`/`rmdir`.
+ */
+export declare function destFormHasExpansion(path: string): boolean;
+export declare function classifyProductDestForms(command: string): ProductDestForm[];
+//# sourceMappingURL=dest-form.d.ts.map