@deftai/directive-core 0.99.0 → 0.100.0

package/dist/scope/decompose.js

@@ -6,14 +6,18 @@
  * A caller supplies a draft with child story definitions; this module validates
  * that draft, writes the child story vBRIEFs, and updates the parent scope references.
  */
-import { accessSync, constants, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { referenceTypeMatches } from "@deftai/directive-types";
+import { evaluateDecomposeStructuralApply, sha256Hex } from "../authz/decompose-apply.js";
+import { claimSingleUseGrantForApply } from "../authz/store.js";
 import { containedWrite } from "../fs/contained-write.js";
 import { ProjectionContainmentError } from "../fs/projection-containment.js";
 import { hasArtifactSuffix, LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, resolveLifecycleRoot, } from "../layout/resolve.js";
 import { referenceWithDefaultTrust, slugify } from "../vbrief-build/build.js";
 import { EMITTED_VBRIEF_VERSION } from "../vbrief-build/constants.js";
+import { formatCoverageReportLine, validateCoverageMap } from "./coverage-map.js";
+import { buildParentLineageArtifact } from "./parent-lineage.js";
 import { formatBriefJson } from "./vbrief-json.js";
 // ---------------------------------------------------------------------------
 // Constants
@@ -35,6 +39,13 @@ export class DecompositionError extends Error {
 // File I/O helpers
 // ---------------------------------------------------------------------------
 function loadJson(path) {
+    return loadJsonWithRaw(path).data;
+}
+/**
+ * Single-read load: parse + return exact on-disk bytes used for #3239 digest binding.
+ * Avoids TOCTOU between validation snapshot and authz hash.
+ */
+function loadJsonWithRaw(path) {
     let raw;
     try {
         raw = readFileSync(path, "utf8");
@@ -52,7 +63,7 @@ function loadJson(path) {
     if (typeof data !== "object" || data === null || Array.isArray(data)) {
         throw new DecompositionError(`${path}: expected a JSON object`);
     }
-    return data;
+    return { data: data, raw };
 }
 function writeJson(projectRoot, path, data) {
     // #2980 wave D: product write sink routes through containedWrite.
@@ -684,6 +695,10 @@ export function validateDraft(stories) {
         if (parallelSafe !== true && parallelSafe !== false) {
             issues.push("plan.metadata.swarm.parallel_safe");
         }
+        // Parity with swarm:readiness (#3252): large work cannot be concurrent.
+        if (sw.size === "large" && parallelSafe === true) {
+            issues.push("size=large cannot be parallel_safe=true");
+        }
         if (items.length === 0)
             issues.push("plan.items");
         if (items.length > 0 && !itemsHaveAcceptance(items)) {
@@ -777,7 +792,7 @@ function childFilename(story, stId, title, date) {
     return `${date}-${sl}.vbrief.json`;
 }
 function buildChildVbrief(opts) {
-    const { story, storyId: stId, storyIndex, parent, parentRel, status } = opts;
+    const { story, storyId: stId, storyIndex, parent, parentRel, status, parentLineage } = opts;
     const title = String(story.title ?? stId);
     const sw = swarmMeta(story);
     const items = itemsFromStory(stId, story);
@@ -786,6 +801,9 @@ function buildChildVbrief(opts) {
         : {};
     metadata.kind = "story";
     metadata.swarm = sw;
+    if (parentLineage !== undefined && parentLineage !== null) {
+        metadata.parent_lineage = parentLineage;
+    }
     const parentPlan = typeof parent.plan === "object" && parent.plan !== null && !Array.isArray(parent.plan)
         ? parent.plan
         : {};
@@ -812,9 +830,17 @@ export function applyDecomposition(opts) {
     const { projectRoot, parentPath, draftPath, checkOnly, date } = opts;
     const vbriefDirPath = vbriefDir(projectRoot);
     const parent = loadJson(parentPath);
-    const draft = loadJson(draftPath);
+    // Single draft read: digest must bind the exact bytes used to build child docs (#3239 P1).
+    const { data: draft, raw: draftRaw } = loadJsonWithRaw(draftPath);
+    const draftDigest = sha256Hex(draftRaw);
     const stories = storySpecs(draft);
     const stIds = validateDraft(stories);
+    // #3238: semantic fidelity — parent requirement IDs + coverage map (structure only).
+    const coverage = validateCoverageMap({ parent, draft, storyIds: stIds });
+    if (!coverage.ok) {
+        const summary = coverage.errors.join("; ");
+        throw new DecompositionError(`semantic coverage failed: ${summary}\n${formatCoverageReportLine(coverage.report)}`);
+    }
     let outputDir;
     const draftOutputDir = draft.output_dir;
     if (typeof draftOutputDir === "string" && draftOutputDir.trim().length > 0) {
@@ -843,6 +869,35 @@ export function applyDecomposition(opts) {
     }
     const parentRel = relToVbrief(vbriefDirPath, parentPath);
     const actions = [`VALIDATED ${stories.length} story decomposition draft`];
+    // Machine-readable coverage report (always emit when parent authored IDs or map present).
+    if (coverage.report.parent_requirement_ids.length > 0 || coverage.report.entries.length > 0) {
+        actions.push(formatCoverageReportLine(coverage.report));
+    }
+    // #3241: stamp full parent coverage artifacts onto every child so story-ready /
+    // preflight can re-check lineage without re-reading the decompose draft.
+    // When parent authors requirement IDs, durable parent_plan_id is mandatory —
+    // omit/skip would let an exact-path replacement pass identity-unchecked.
+    const draftRec = draft;
+    const parentPlanRec = typeof parent.plan === "object" && parent.plan !== null && !Array.isArray(parent.plan)
+        ? parent.plan
+        : {};
+    const parentPlanId = typeof parentPlanRec.id === "string" && parentPlanRec.id.trim().length > 0
+        ? parentPlanRec.id.trim()
+        : undefined;
+    let parentLineageArtifact = null;
+    if (coverage.report.parent_requirement_ids.length > 0) {
+        if (parentPlanId === undefined) {
+            throw new DecompositionError("parent authors requirement IDs but has no non-empty plan.id — " +
+                "refuse decompose without durable parent identity for parent_plan_id stamp (#3241)");
+        }
+        parentLineageArtifact = buildParentLineageArtifact({
+            coverage_map: draftRec.coverage_map ?? draftRec.coverageMap,
+            behavioral_deltas: draftRec.behavioral_deltas ?? draftRec.behavioralDeltas,
+            parent_requirement_ids: coverage.report.parent_requirement_ids,
+            negative_invariant_ids: coverage.report.negative_invariant_ids,
+            parent_plan_id: parentPlanId,
+        });
+    }
     const childPaths = [];
     const childDocs = [];
     for (let i = 0; i < stories.length; i += 1) {
@@ -865,6 +920,7 @@ export function applyDecomposition(opts) {
             parent,
             parentRel,
             status: storyStatus,
+            parentLineage: parentLineageArtifact,
         });
         childPaths.push({ target, storyId: stId, title });
         childDocs.push(child);
@@ -873,13 +929,20 @@ export function applyDecomposition(opts) {
     }
     if (checkOnly)
         return actions;
-    for (const { target } of childPaths) {
-        mkdirSync(dirname(target), { recursive: true });
-    }
-    for (let i = 0; i < childPaths.length; i += 1) {
-        // biome-ignore lint/style/noNonNullAssertion: loop bound ensures these exist
-        writeJson(projectRoot, childPaths[i].target, childDocs[i]);
+    // #3239: structural apply requires human-origin grant bound to exact draft digest
+    // from the single load above. --check is ungated (returned earlier).
+    const authz = evaluateDecomposeStructuralApply({
+        projectRoot,
+        parentPath,
+        draftPath,
+        draftDigest,
+    });
+    if (!authz.allowed) {
+        throw new DecompositionError(authz.reason);
     }
+    actions.push(`AUTHZ grant=${authz.humanApprovalRef ?? "unknown"} digest=${draftDigest.slice(0, 12)}`);
+    // Parent mutation validation before claim/writes so invalid parents do not
+    // spend a single-use grant (#3239).
     let parentPlan = parent.plan;
     if (parentPlan === null || parentPlan === undefined) {
         parentPlan = {};
@@ -918,7 +981,58 @@ export function applyDecomposition(opts) {
     planObj.references = dedupeReferences(references
         .filter((r) => typeof r === "object" && r !== null && !Array.isArray(r))
         .map((r) => r));
-    writeJson(projectRoot, parentPath, parent);
+    // Exclusive claim: revalidate under lock → mark single-use usedAt → write all
+    // children + parent; apply throw rolls usedAt back for retry (#3239 residual).
+    // Partial child files created in this attempt are best-effort removed so retry
+    // is not blocked by "child already exists".
+    const writeProtected = () => {
+        const created = [];
+        try {
+            for (const { target } of childPaths) {
+                mkdirSync(dirname(target), { recursive: true });
+            }
+            for (let i = 0; i < childPaths.length; i += 1) {
+                // biome-ignore lint/style/noNonNullAssertion: loop bound ensures these exist
+                const target = childPaths[i].target;
+                // biome-ignore lint/style/noNonNullAssertion: loop bound ensures these exist
+                writeJson(projectRoot, target, childDocs[i]);
+                created.push(target);
+            }
+            writeJson(projectRoot, parentPath, parent);
+        }
+        catch (err) {
+            for (const path of created.reverse()) {
+                try {
+                    rmSync(path, { force: true });
+                }
+                catch {
+                    /* best-effort rollback of this attempt's children */
+                }
+            }
+            throw err;
+        }
+    };
+    if (authz.humanApprovalRef !== null) {
+        const claim = claimSingleUseGrantForApply(projectRoot, authz.humanApprovalRef, {
+            revalidate: (grant) => {
+                const again = evaluateDecomposeStructuralApply({
+                    projectRoot,
+                    parentPath,
+                    draftPath,
+                    draftDigest,
+                    grants: [grant],
+                });
+                return again.allowed ? { ok: true } : { ok: false, reason: again.reason };
+            },
+            apply: writeProtected,
+        });
+        if (!claim.ok) {
+            throw new DecompositionError(claim.reason);
+        }
+    }
+    else {
+        writeProtected();
+    }
     actions.push(`UPDATE ${parentRel} references`);
     return actions;
 }

package/dist/scope/index.d.ts

@@ -1,12 +1,15 @@
+export * from "./acceptance-evidence.js";
 export * from "./audit-log.js";
 export * from "./batch-promote.js";
 export * from "./constants.js";
+export * from "./coverage-map.js";
 export * from "./decomposed-refs.js";
 export * from "./delivery-evidence.js";
 export * from "./demote.js";
 export * from "./effort-activate-gate.js";
 export * from "./main.js";
 export * from "./open-umbrella-warning.js";
+export * from "./parent-lineage.js";
 export * from "./project-context.js";
 export * from "./promote-from-issue.js";
 export * from "./promote-path.js";

package/dist/scope/index.js

@@ -1,12 +1,15 @@
+export * from "./acceptance-evidence.js";
 export * from "./audit-log.js";
 export * from "./batch-promote.js";
 export * from "./constants.js";
+export * from "./coverage-map.js";
 export * from "./decomposed-refs.js";
 export * from "./delivery-evidence.js";
 export * from "./demote.js";
 export * from "./effort-activate-gate.js";
 export * from "./main.js";
 export * from "./open-umbrella-warning.js";
+export * from "./parent-lineage.js";
 export * from "./project-context.js";
 export * from "./promote-from-issue.js";
 export * from "./promote-path.js";

package/dist/scope/parent-lineage.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Parent-lineage gates for story-ready and pre-PR/preflight (#3241 / epic #3237).
+ *
+ * After #3238 coverage artifacts exist, a green child can still contradict parent
+ * invariants unless build/review gates re-check structure. This module:
+ *   - resolves parent via plan.planRef (or plan references)
+ *   - when parent authors requirement IDs, requires child coverage artifacts
+ *   - reuses validateCoverageMap (structure-only; no LLM judgment)
+ *   - classifies defects: child_spec | parent_child_drift
+ *
+ * Backward compatible: no parent link, or parent with zero requirement IDs → N/A pass.
+ */
+import { type CoverageReport } from "./coverage-map.js";
+export declare const PARENT_LINEAGE_SCHEMA: "deft.scope.parent_lineage.v1";
+/** Defect classes for gate output (#3241 AC: distinguish child-spec vs parent/child drift). */
+export declare const LINEAGE_DEFECT_CLASSES: readonly ["child_spec", "parent_child_drift"];
+export type LineageDefectClass = (typeof LINEAGE_DEFECT_CLASSES)[number];
+export interface ParentLineageResult {
+    readonly ok: boolean;
+    /** False when lineage does not apply (no parent / parent has no requirement IDs). */
+    readonly applicable: boolean;
+    readonly defect_class: LineageDefectClass | null;
+    readonly message: string;
+    readonly parent_path: string | null;
+    readonly parent_requirement_ids: readonly string[];
+    readonly negative_invariant_ids: readonly string[];
+    readonly coverage_report: CoverageReport | null;
+    readonly errors: readonly string[];
+}
+type JsonObj = Record<string, unknown>;
+/**
+ * Walk up from a child artifact path to find the lifecycle root (xbrief/ or vbrief/).
+ */
+export declare function findLifecycleRootFromArtifact(artifactPath: string): string | null;
+/**
+ * Resolve plan.planRef (or similar relative ref) against a lifecycle root.
+ * Rejects absolute paths and `..` traversal.
+ */
+export declare function resolveParentPathFromRef(planRef: string, lifecycleRoot: string): {
+    path: string | null;
+    error: string | null;
+};
+/**
+ * Extract coverage draft surface from a child xBRIEF for validateCoverageMap.
+ * Prefer plan.metadata.parent_lineage, then plan.metadata, then plan/root.
+ */
+export declare function extractChildCoverageDraft(child: unknown): {
+    draft: JsonObj | null;
+    source: string | null;
+    hasCoverageMapKey: boolean;
+};
+/**
+ * Build the parent_lineage metadata block stamped onto decomposed children (#3241).
+ */
+export declare function buildParentLineageArtifact(opts: {
+    coverage_map?: unknown;
+    behavioral_deltas?: unknown;
+    parent_requirement_ids?: readonly string[];
+    negative_invariant_ids?: readonly string[];
+    /** Stable parent plan.id for lifecycle-fallback identity (exact match). */
+    parent_plan_id?: string;
+}): JsonObj;
+/** Read plan.id from a loaded parent document (plan.id or root id). */
+export declare function extractPlanId(doc: unknown): string | null;
+/**
+ * Scan lifecycle folders for artifacts whose plan.id exactly equals parentPlanId.
+ * Returns every match (caller enforces uniqueness). Does not use basenames.
+ */
+export declare function findParentsByPlanId(lifecycleRoot: string, parentPlanId: string): Array<{
+    path: string;
+    data: JsonObj;
+}>;
+/**
+ * Load parent for lineage checks.
+ *
+ * 1. Prefer the exact planRef path when it exists; require plan.id match when
+ *    the child stamps parent_plan_id (path replacement with a different plan is rejected).
+ * 2. When the exact path is missing AND the child stamps parent_plan_id: recover by
+ *    scanning lifecycle folders for plan.id === parent_plan_id and accepting ONLY
+ *    when exactly one artifact matches. This handles lifecycle moves when child
+ *    planRef rewrite lagged — not silent basename recovery of unrelated files.
+ * 3. Without a durable stamp, stale/missing planRef fails closed (no basename guess).
+ */
+export declare function loadParentExact(parentPath: string, opts?: {
+    expectedParentPlanId?: string | null;
+    lifecycleRoot?: string | null;
+}): {
+    ok: true;
+    data: JsonObj;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+    path: string;
+};
+/** Stamped parent_plan_id from child plan.metadata.parent_lineage (if any). */
+export declare function extractStampedParentPlanId(child: unknown): string | null;
+/**
+ * Pure parent-lineage evaluation for an in-memory child + optional parent.
+ * When parent is omitted, uses parentPath / project layout from options.
+ */
+export declare function evaluateParentLineage(opts: {
+    child: unknown;
+    /** Absolute path to the child artifact (used to locate lifecycle root). */
+    childPath?: string;
+    /** Pre-loaded parent document (skips disk load). */
+    parent?: unknown;
+    /** Explicit absolute parent path (also used for messaging). */
+    parentPath?: string;
+    /** Project root for resolving planRef when childPath is absent. */
+    projectRoot?: string;
+    /** When true, skip lineage (tests / opt-out). Default false. */
+    skip?: boolean;
+}): ParentLineageResult;
+/**
+ * Convenience: load child from path and evaluate lineage.
+ */
+export declare function evaluateParentLineageAtPath(childPath: string, options?: {
+    projectRoot?: string;
+    skip?: boolean;
+}): ParentLineageResult;
+/** One-line machine-readable lineage summary for gate stdout. */
+export declare function formatParentLineageLine(result: ParentLineageResult): string;
+export {};
+//# sourceMappingURL=parent-lineage.d.ts.map