@deftai/directive-core 0.103.0 → 0.105.0

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

@@ -1,18 +1,20 @@
 import { existsSync, mkdirSync, unlinkSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { SESSION_COMPLETED_AC_REMEDIATION, writeSessionCompletedMarker, } from "../check/session-completed-ac.js";
 import { InstrumentedVbriefCrud, persistCrudMetrics } from "../eval/crud-telemetry.js";
 import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
+import { applyClauseDerivationToPlan, maybeEmitAcceptanceStampFromChange, } from "../intake/clause-derivation.js";
 import { hasArtifactSuffix } from "../layout/resolve.js";
 import { evaluateCompletedPlanConsistency } from "../lifecycle/completed-consistency.js";
 import { evaluateLiteralAcceptanceFromPlan } from "../literal-acceptance/index.js";
 import { evaluateAcceptanceActivateGate } from "./acceptance-activate-gate.js";
-import { evaluateAcceptanceEvidenceGate, formatAcceptanceCompletionListing, } from "./acceptance-evidence.js";
+import { evaluateAcceptanceEvidenceGate, evaluateScopeCompleteAcceptanceWalk, formatAcceptanceCompletionListing, } from "./acceptance-evidence.js";
 import { append, canonicalLogPath, newDecisionId } from "./audit-log.js";
 import { atomicWriteBrief, formatBriefJson, readBriefForMutation } from "./brief-io.js";
 import { stampCompletionMetadata } from "./capacity-stamp.js";
 import { LIFECYCLE_FOLDERS, MOVE_LABELS, STATUS_PRECONDITIONS, STAY_LABELS, TRANSITIONS, } from "./constants.js";
 import { detectLifecycleFolder, updateDecomposedChildBackReferences, updateDecomposedParentBackReferences, } from "./decomposed-refs.js";
-import { classifyStoredDeliveryDisposition, evaluateDeliveryGate, stampDeliveryProvenance, } from "./delivery-evidence.js";
+import { classifyStoredDeliveryDisposition, evaluateDeliveryGate, resolveCompletionSessionId, stampDeliveryProvenance, } from "./delivery-evidence.js";
 import { evaluateEffortActivateGate } from "./effort-activate-gate.js";
 import { syncProjectDefinitionAfterScopeMove } from "./project-definition-sync.js";
 import { syncSpecificationAfterScopeMove } from "./specification-sync.js";
@@ -143,6 +145,19 @@ export function runTransition(action, filePath, now = new Date(), options = {})
         }
     }
     const nowIso = utcNowIso(now);
+    // #3360: hand-authored briefs run #3323 clause derivation on activate/promote.
+    // #3355: stamp is state-observed (before vs after), not derivation-notice-bound.
+    const previousAcceptance = planObj.acceptance;
+    let derivationNotice = "";
+    if (act === "activate" || act === "promote") {
+        const derivation = applyClauseDerivationToPlan(planObj, {
+            projectRoot,
+            emitStamp: false,
+        });
+        if (derivation.notice.length > 0) {
+            derivationNotice = derivation.notice;
+        }
+    }
     // #1581: fail closed before activating a scope that still has XL plan items.
     if (act === "activate") {
         const effortGate = evaluateEffortActivateGate(planObj);
@@ -170,7 +185,10 @@ export function runTransition(action, filePath, now = new Date(), options = {})
             return { ok: false, message: gate.message };
         }
         if (gate.provenance !== null) {
-            stampDeliveryProvenance(planObj, gate.provenance);
+            const sessionId = resolveCompletionSessionId(projectRoot);
+            stampDeliveryProvenance(planObj, sessionId !== null
+                ? { ...gate.provenance, completedSessionId: sessionId }
+                : gate.provenance);
         }
     }
     // #3240: per-criterion typed evidence or human-origin disposition before auto-advance.
@@ -207,6 +225,19 @@ export function runTransition(action, filePath, now = new Date(), options = {})
                     ? `${acceptanceListing}\n${literalGate.message}`
                     : literalGate.message;
         }
+        // #3357: verify:ac walk is a hard precondition. Disposition does not skip it.
+        const acWalk = evaluateScopeCompleteAcceptanceWalk(planObj, { projectRoot });
+        if (!acWalk.ok) {
+            return {
+                ok: false,
+                message: acWalk.message,
+                acceptanceReports: acceptanceGate.reports,
+            };
+        }
+        if (acWalk.message.length > 0) {
+            acceptanceListing =
+                acceptanceListing.length > 0 ? `${acceptanceListing}\n${acWalk.message}` : acWalk.message;
+        }
     }
     planObj.status = targetStatus;
     planObj.updated = nowIso;
@@ -218,7 +249,9 @@ export function runTransition(action, filePath, now = new Date(), options = {})
         advanceNonTerminalOwnItems(planObj.items, targetStatus);
     }
     if (act === "complete") {
-        stampCompletionMetadata(planObj, projectRoot, nowIso);
+        stampCompletionMetadata(planObj, projectRoot, nowIso, {
+            completedSessionId: resolveCompletionSessionId(projectRoot),
+        });
         // #3242 / epic #3237 Q4: after reconcile, completed lifecycle must match
         // plan.status=completed and terminal plan.items (compose with #3240).
         const consistency = evaluateCompletedPlanConsistency(planObj, {
@@ -249,6 +282,27 @@ export function runTransition(action, filePath, now = new Date(), options = {})
             return { ok: false, message: writeResult.message };
         }
         crud.recordTrustedUpdate(destPath, formatted);
+        if (act === "complete") {
+            const sessionId = resolveCompletionSessionId(projectRoot);
+            if (sessionId !== null) {
+                try {
+                    writeSessionCompletedMarker(projectRoot, {
+                        path: destPath,
+                        sessionId,
+                        completedAt: nowIso,
+                    });
+                }
+                catch {
+                    try {
+                        unlinkSync(destPath);
+                    }
+                    catch {
+                        /* dest rollback after marker failure */
+                    }
+                    return { ok: false, message: SESSION_COMPLETED_AC_REMEDIATION };
+                }
+            }
+        }
         try {
             unlinkSync(resolvedPath);
         }
@@ -280,7 +334,11 @@ export function runTransition(action, filePath, now = new Date(), options = {})
             };
         }
         syncSpecificationAfterScopeMove(data, resolvedPath, destPath, vbriefRoot, targetStatus);
+        if (act === "activate" || act === "promote") {
+            maybeEmitAcceptanceStampFromChange(projectRoot, previousAcceptance, planObj.acceptance);
+        }
         const moveMsg = `${actionLabel} ${basename}: ${currentFolder}/ -> ${targetFolder}/ (status: ${targetStatus})` +
+            (derivationNotice.length > 0 ? `\n${derivationNotice}` : "") +
             (acceptanceListing.length > 0 ? `\n${acceptanceListing}` : "");
         return {
             ok: true,
@@ -300,7 +358,11 @@ export function runTransition(action, filePath, now = new Date(), options = {})
         /* best-effort telemetry persistence */
     }
     const actionLabel = STAY_LABELS[act] ?? act.charAt(0).toUpperCase() + act.slice(1);
+    if (act === "activate" || act === "promote") {
+        maybeEmitAcceptanceStampFromChange(projectRoot, previousAcceptance, planObj.acceptance);
+    }
     const stayMsg = `${actionLabel} ${basename}: stays in ${currentFolder}/ (status: ${targetStatus})` +
+        (derivationNotice.length > 0 ? `\n${derivationNotice}` : "") +
         (acceptanceListing.length > 0 ? `\n${acceptanceListing}` : "");
     return {
         ok: true,

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