@deftai/directive-core 0.98.1 → 0.100.0

package/dist/preflight/evaluate.js

@@ -1,6 +1,7 @@
 import { readFileSync, statSync } from "node:fs";
 import { basename, dirname } from "node:path";
 import { evaluateIntentCeilingFromEnv } from "../policy/intent-ceiling.js";
+import { evaluateParentLineage, formatParentLineageLine, } from "../scope/parent-lineage.js";
 /** Canonical eligibility folder — only vbrief/active/ may spawn implementation. */
 export const ACTIVE_FOLDER = "active";
 /** Canonical eligibility status — only `running` signals an active handoff. */
@@ -37,8 +38,12 @@ function nodeJsonErrorToPythonMsg(nodeMessage) {
  * Pure evaluator — returns `{ exitCode, message }`. Never throws; every error
  * path collapses to exit 1 with an actionable message. Faithful to
  * `scripts/preflight_implementation.py::evaluate`.
+ *
+ * #3241: after active+running + intent ceiling, re-check parent requirement
+ * lineage (coverage + approved behavioral deltas). Fail closed on missing
+ * coverage or undeclared deltas when the parent authors requirement IDs.
  */
-export function evaluate(vbriefPath) {
+export function evaluate(vbriefPath, options = {}) {
     const path = vbriefPath;
     let st;
     try {
@@ -134,11 +139,37 @@ export function evaluate(vbriefPath) {
             message: buildReject(path, intent.reason),
         };
     }
+    // #3241 pre-PR / implementation preflight: parent lineage fail-closed.
+    const lineage = evaluateParentLineage({
+        child: record,
+        childPath: path,
+        projectRoot: options.projectRoot,
+        skip: options.skipParentLineage === true,
+    });
+    if (!lineage.ok) {
+        const defect = lineage.defect_class !== null ? ` [defect_class=${lineage.defect_class}]` : "";
+        return {
+            exitCode: 1,
+            parentLineage: lineage,
+            message: buildReject(path, `${lineage.message}${defect}\n  ${formatParentLineageLine(lineage)}`),
+        };
+    }
+    // Keep the historical OK line when lineage is N/A (backward-compatible tests / agents).
+    const message = lineage.applicable
+        ? `OK ${path} -- ready for implementation. parent lineage OK ` +
+            `(${lineage.parent_requirement_ids.length} req IDs` +
+            (lineage.negative_invariant_ids.length > 0
+                ? `, ${lineage.negative_invariant_ids.length} negative invariants`
+                : "") +
+            `).`
+        : `OK ${path} -- ready for implementation.`;
     return {
         exitCode: 0,
-        message: `OK ${path} -- ready for implementation.`,
+        parentLineage: lineage,
+        message,
     };
 }
+export { evaluateParentLineage, formatParentLineageLine, } from "../scope/parent-lineage.js";
 /** Structured `--json` payload (sorted keys), mirroring Python `_emit_json`. */
 export function emitJson(vbriefPath, exitCode, message) {
     const payload = {

package/dist/render/framework-commands.js

@@ -85,6 +85,9 @@ export const COMMANDS = {
     "verify:orphan-active": spec("verify:orphan-active", "verify_orphan_active:main", {
         projectRootArg: "--project-root",
     }),
+    "verify:completed-tracked": spec("verify:completed-tracked", "verify_completed_tracked:main", {
+        projectRootArg: "--project-root",
+    }),
     "verify:pack-drift": spec("verify:pack-drift", "pack_render:main", {
         defaultArgs: ["--check"],
         cwd: "framework",
@@ -299,6 +302,7 @@ const ENTRYPOINT_VERB = {
     "preflight_cache:main": "preflight-cache",
     "preflight_wip_cap:main": "verify-wip-cap",
     "verify_orphan_active:main": "verify-orphan-active",
+    "verify_completed_tracked:main": "verify-completed-tracked",
     "pack_render:main": "pack-render",
     "validate_strategy_output:main": "validate-strategy-output",
     "vbrief_validate:main": "vbrief-validate",

package/dist/scope/acceptance-evidence.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Per-acceptance-criterion evidence / disposition for scope:complete (#3240 / epic #3237 Q3).
+ *
+ * Merge ancestry alone must not auto-complete acceptance items. Each non-terminal
+ * plan item needs either typed evidence or a human-origin disposition before complete
+ * may advance it. Kind suitability: merge/review alone cannot satisfy smoke, UAT,
+ * deploy, or observed_behavior requirements.
+ */
+import type { GrantOrigin } from "../authz/types.js";
+/** Closed evidence kinds (locked Q3). */
+export declare const ACCEPTANCE_EVIDENCE_KINDS: readonly ["test", "review", "merge", "deploy", "smoke", "uat", "observed_behavior"];
+export type AcceptanceEvidenceKind = (typeof ACCEPTANCE_EVIDENCE_KINDS)[number];
+/** Closed dispositions (locked Q3). */
+export declare const ACCEPTANCE_DISPOSITIONS: readonly ["waived", "deferred", "not_applicable"];
+export type AcceptanceDispositionKind = (typeof ACCEPTANCE_DISPOSITIONS)[number];
+/**
+ * Axes that merge/review evidence alone cannot satisfy.
+ * Matches epic #3237 Q3 suitability rule.
+ */
+export declare const STRICT_ACCEPTANCE_AXES: readonly ["deploy", "smoke", "uat", "observed_behavior"];
+export type StrictAcceptanceAxis = (typeof STRICT_ACCEPTANCE_AXES)[number];
+export interface AcceptanceEvidenceRecord {
+    readonly kind: AcceptanceEvidenceKind;
+    readonly pointer: string;
+    readonly recorded_at: string;
+    readonly recorded_by: string;
+}
+export interface AcceptanceDispositionRecord {
+    readonly disposition: AcceptanceDispositionKind;
+    readonly reason: string;
+    /** Human-origin provenance (kind + actor required; other GrantOrigin fields optional). */
+    readonly provenance: Pick<GrantOrigin, "kind" | "actor"> & Partial<GrantOrigin>;
+    readonly recorded_at: string;
+    readonly resume_when?: string;
+}
+export interface CriterionAcceptanceReport {
+    readonly path: string;
+    readonly title: string;
+    readonly outcome: "evidence" | "disposition" | "already_terminal" | "missing" | "invalid";
+    readonly detail: string;
+    readonly evidence?: AcceptanceEvidenceRecord;
+    readonly disposition?: AcceptanceDispositionRecord;
+}
+export interface AcceptanceEvidenceGateResult {
+    readonly ok: boolean;
+    readonly message: string;
+    readonly reports: readonly CriterionAcceptanceReport[];
+}
+export declare function isAcceptanceEvidenceKind(value: unknown): value is AcceptanceEvidenceKind;
+export declare function isAcceptanceDispositionKind(value: unknown): value is AcceptanceDispositionKind;
+/**
+ * Infer strict axes a criterion requires from explicit fields and title/Acceptance text.
+ * Explicit `requires` / `requiredEvidenceKind` / `acceptanceAxis` wins when valid.
+ */
+export declare function inferRequiredStrictAxes(item: Record<string, unknown>): StrictAcceptanceAxis[];
+/**
+ * Whether evidence.kind is suitable for the criterion's required strict axes.
+ * merge and review never satisfy smoke/UAT/deploy/observed_behavior.
+ *
+ * A single evidence.kind covers only that axis. When free-text inference yields
+ * multiple axes (e.g. "smoke after deploy"), every required axis must match the
+ * same kind — which is only possible when the axes are identical. Otherwise use
+ * explicit `requires` / `acceptanceAxis` for a single axis, split the criterion,
+ * or record a human-origin disposition (#3240 Greptile P1).
+ */
+export declare function isEvidenceKindSuitable(kind: AcceptanceEvidenceKind, requiredAxes: readonly StrictAcceptanceAxis[]): boolean;
+/**
+ * Fail closed when any non-terminal plan item lacks suitable evidence or a human-origin disposition.
+ */
+export declare function evaluateAcceptanceEvidenceGate(plan: Record<string, unknown>): AcceptanceEvidenceGateResult;
+/**
+ * Format a short multi-line listing of evidence/disposition for every criterion
+ * (including already-terminal) for complete success output.
+ */
+export declare function formatAcceptanceCompletionListing(reports: readonly CriterionAcceptanceReport[]): string;
+//# sourceMappingURL=acceptance-evidence.d.ts.map

package/dist/scope/acceptance-evidence.js

@@ -0,0 +1,348 @@
+/**
+ * Per-acceptance-criterion evidence / disposition for scope:complete (#3240 / epic #3237 Q3).
+ *
+ * Merge ancestry alone must not auto-complete acceptance items. Each non-terminal
+ * plan item needs either typed evidence or a human-origin disposition before complete
+ * may advance it. Kind suitability: merge/review alone cannot satisfy smoke, UAT,
+ * deploy, or observed_behavior requirements.
+ */
+import { isHumanOrigin } from "../authz/origin.js";
+/** Closed evidence kinds (locked Q3). */
+export const ACCEPTANCE_EVIDENCE_KINDS = [
+    "test",
+    "review",
+    "merge",
+    "deploy",
+    "smoke",
+    "uat",
+    "observed_behavior",
+];
+/** Closed dispositions (locked Q3). */
+export const ACCEPTANCE_DISPOSITIONS = ["waived", "deferred", "not_applicable"];
+/**
+ * Axes that merge/review evidence alone cannot satisfy.
+ * Matches epic #3237 Q3 suitability rule.
+ */
+export const STRICT_ACCEPTANCE_AXES = ["deploy", "smoke", "uat", "observed_behavior"];
+const EVIDENCE_KIND_SET = new Set(ACCEPTANCE_EVIDENCE_KINDS);
+const DISPOSITION_SET = new Set(ACCEPTANCE_DISPOSITIONS);
+const STRICT_AXIS_SET = new Set(STRICT_ACCEPTANCE_AXES);
+/** Item statuses that still represent unfinished acceptance work (#2862 / #3240). */
+const NON_TERMINAL_ITEM_STATUSES = new Set(["pending", "proposed", "running"]);
+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;
+}
+export function isAcceptanceEvidenceKind(value) {
+    return typeof value === "string" && EVIDENCE_KIND_SET.has(value.trim().toLowerCase());
+}
+export function isAcceptanceDispositionKind(value) {
+    return typeof value === "string" && DISPOSITION_SET.has(value.trim().toLowerCase());
+}
+/**
+ * Infer strict axes a criterion requires from explicit fields and title/Acceptance text.
+ * Explicit `requires` / `requiredEvidenceKind` / `acceptanceAxis` wins when valid.
+ */
+export function inferRequiredStrictAxes(item) {
+    const explicit = [
+        item.requires,
+        item.requiredEvidenceKind,
+        item.required_evidence_kind,
+        item.acceptanceAxis,
+        item.acceptance_axis,
+    ];
+    for (const raw of explicit) {
+        if (typeof raw !== "string")
+            continue;
+        const norm = raw.trim().toLowerCase().replace(/-/g, "_");
+        if (STRICT_AXIS_SET.has(norm)) {
+            return [norm];
+        }
+    }
+    const narrative = asRecord(item.narrative);
+    const parts = [];
+    if (typeof item.title === "string")
+        parts.push(item.title);
+    if (typeof item.id === "string")
+        parts.push(item.id);
+    if (narrative !== null) {
+        for (const key of ["Acceptance", "acceptance", "Description", "description", "Test", "test"]) {
+            if (typeof narrative[key] === "string")
+                parts.push(narrative[key]);
+        }
+    }
+    const text = parts.join("\n").toLowerCase();
+    const found = [];
+    // Order: longer / more specific phrases first so "observed behavior" wins over generic.
+    if (/\bobserved[_\s-]?behavior\b/.test(text) ||
+        /\bobserved behaviour\b/.test(text) ||
+        /\brunning behaviour\b/.test(text) ||
+        /\brunning behavior\b/.test(text)) {
+        found.push("observed_behavior");
+    }
+    if (/\buat\b/.test(text) || /\buser acceptance\b/.test(text)) {
+        found.push("uat");
+    }
+    if (/\bsmoke\b/.test(text)) {
+        found.push("smoke");
+    }
+    if (/\bdeploy(?:ment|ed|s)?\b/.test(text)) {
+        found.push("deploy");
+    }
+    return found;
+}
+/**
+ * Whether evidence.kind is suitable for the criterion's required strict axes.
+ * merge and review never satisfy smoke/UAT/deploy/observed_behavior.
+ *
+ * A single evidence.kind covers only that axis. When free-text inference yields
+ * multiple axes (e.g. "smoke after deploy"), every required axis must match the
+ * same kind — which is only possible when the axes are identical. Otherwise use
+ * explicit `requires` / `acceptanceAxis` for a single axis, split the criterion,
+ * or record a human-origin disposition (#3240 Greptile P1).
+ */
+export function isEvidenceKindSuitable(kind, requiredAxes) {
+    if (requiredAxes.length === 0) {
+        return true;
+    }
+    if (kind === "merge" || kind === "review") {
+        return false;
+    }
+    // All required strict axes must be covered by this single evidence kind.
+    return requiredAxes.every((axis) => kind === axis);
+}
+function parseEvidence(raw) {
+    const obj = asRecord(raw);
+    if (obj === null) {
+        return { ok: false, message: "evidence must be an object" };
+    }
+    const kindRaw = typeof obj.kind === "string" ? obj.kind.trim().toLowerCase() : "";
+    if (!isAcceptanceEvidenceKind(kindRaw)) {
+        return {
+            ok: false,
+            message: `unknown or missing evidence.kind ${JSON.stringify(obj.kind)}; ` +
+                `allowed: ${ACCEPTANCE_EVIDENCE_KINDS.join("|")}`,
+        };
+    }
+    if (!isNonEmptyString(obj.pointer)) {
+        return { ok: false, message: "evidence.pointer is required (non-empty string)" };
+    }
+    if (!isNonEmptyString(obj.recorded_at)) {
+        return { ok: false, message: "evidence.recorded_at is required" };
+    }
+    if (!isNonEmptyString(obj.recorded_by)) {
+        return { ok: false, message: "evidence.recorded_by is required" };
+    }
+    return {
+        ok: true,
+        record: {
+            kind: kindRaw,
+            pointer: obj.pointer.trim(),
+            recorded_at: obj.recorded_at.trim(),
+            recorded_by: obj.recorded_by.trim(),
+        },
+    };
+}
+function parseDisposition(raw) {
+    const obj = asRecord(raw);
+    if (obj === null) {
+        return { ok: false, message: "disposition must be an object" };
+    }
+    const dispRaw = typeof obj.disposition === "string" ? obj.disposition.trim().toLowerCase() : "";
+    if (!isAcceptanceDispositionKind(dispRaw)) {
+        return {
+            ok: false,
+            message: `unknown or missing disposition.disposition ${JSON.stringify(obj.disposition)}; ` +
+                `allowed: ${ACCEPTANCE_DISPOSITIONS.join("|")}`,
+        };
+    }
+    if (!isNonEmptyString(obj.reason)) {
+        return { ok: false, message: "disposition.reason is required" };
+    }
+    if (!isNonEmptyString(obj.recorded_at)) {
+        return { ok: false, message: "disposition.recorded_at is required" };
+    }
+    const provenance = asRecord(obj.provenance);
+    if (provenance === null) {
+        return { ok: false, message: "disposition.provenance is required (human-origin)" };
+    }
+    // Reuse authz human-origin gate (#2944) so agent-self stamps cannot waive criteria.
+    const originForCheck = {
+        kind: String(provenance.kind ?? ""),
+        actor: String(provenance.actor ?? ""),
+        mintedAt: typeof provenance.mintedAt === "string" ? provenance.mintedAt : "",
+        mintedVia: typeof provenance.mintedVia === "string" ? provenance.mintedVia : "",
+        eventRef: typeof provenance.eventRef === "string" ? provenance.eventRef : null,
+    };
+    if (!isHumanOrigin(originForCheck)) {
+        return {
+            ok: false,
+            message: "disposition.provenance must be human-origin " +
+                "(kind operator-cli|operator-session|human-event + non-agent actor)",
+        };
+    }
+    const record = {
+        disposition: dispRaw,
+        reason: obj.reason.trim(),
+        provenance: {
+            kind: originForCheck.kind,
+            actor: originForCheck.actor,
+            ...(originForCheck.mintedAt.length > 0 ? { mintedAt: originForCheck.mintedAt } : {}),
+            ...(originForCheck.mintedVia.length > 0 ? { mintedVia: originForCheck.mintedVia } : {}),
+            ...(originForCheck.eventRef !== null ? { eventRef: originForCheck.eventRef } : {}),
+        },
+        recorded_at: obj.recorded_at.trim(),
+    };
+    if (isNonEmptyString(obj.resume_when)) {
+        return {
+            ok: true,
+            record: { ...record, resume_when: obj.resume_when.trim() },
+        };
+    }
+    return { ok: true, record };
+}
+function itemLabel(item, path) {
+    if (typeof item.title === "string" && item.title.trim().length > 0) {
+        return item.title.trim();
+    }
+    if (typeof item.id === "string" && item.id.trim().length > 0) {
+        return item.id.trim();
+    }
+    return path;
+}
+function evaluateOneItem(item, path) {
+    const title = itemLabel(item, path);
+    const status = String(item.status ?? "");
+    if (!NON_TERMINAL_ITEM_STATUSES.has(status)) {
+        return {
+            path,
+            title,
+            outcome: "already_terminal",
+            detail: `status=${status || "(empty)"} (not advanced)`,
+        };
+    }
+    const hasEvidence = item.evidence !== undefined && item.evidence !== null;
+    const hasDisposition = item.disposition !== undefined && item.disposition !== null;
+    if (hasEvidence && hasDisposition) {
+        return {
+            path,
+            title,
+            outcome: "invalid",
+            detail: "exactly one of evidence or disposition required; both present",
+        };
+    }
+    if (!hasEvidence && !hasDisposition) {
+        return {
+            path,
+            title,
+            outcome: "missing",
+            detail: "no evidence or disposition; scope:complete refuses to auto-complete (#3240)",
+        };
+    }
+    if (hasDisposition) {
+        const parsed = parseDisposition(item.disposition);
+        if (!parsed.ok) {
+            return { path, title, outcome: "invalid", detail: parsed.message };
+        }
+        return {
+            path,
+            title,
+            outcome: "disposition",
+            detail: `${parsed.record.disposition}: ${parsed.record.reason}`,
+            disposition: parsed.record,
+        };
+    }
+    const parsed = parseEvidence(item.evidence);
+    if (!parsed.ok) {
+        return { path, title, outcome: "invalid", detail: parsed.message };
+    }
+    const requiredAxes = inferRequiredStrictAxes(item);
+    if (!isEvidenceKindSuitable(parsed.record.kind, requiredAxes)) {
+        const axes = requiredAxes.length > 0 ? requiredAxes.join("|") : "(none)";
+        return {
+            path,
+            title,
+            outcome: "invalid",
+            detail: `evidence.kind=${parsed.record.kind} is not suitable for required axis/axes [${axes}]; ` +
+                `merge/review alone cannot satisfy smoke|uat|deploy|observed_behavior (#3240)`,
+            evidence: parsed.record,
+        };
+    }
+    return {
+        path,
+        title,
+        outcome: "evidence",
+        detail: `${parsed.record.kind} @ ${parsed.record.pointer}`,
+        evidence: parsed.record,
+    };
+}
+function walkItems(items, pathPrefix, reports) {
+    if (!Array.isArray(items)) {
+        return;
+    }
+    items.forEach((item, index) => {
+        if (item === null || typeof item !== "object" || Array.isArray(item)) {
+            return;
+        }
+        const obj = item;
+        const path = `${pathPrefix}[${index}]`;
+        reports.push(evaluateOneItem(obj, path));
+        walkItems(obj.subItems, `${path}.subItems`, reports);
+        walkItems(obj.items, `${path}.items`, reports);
+    });
+}
+/**
+ * Fail closed when any non-terminal plan item lacks suitable evidence or a human-origin disposition.
+ */
+export function evaluateAcceptanceEvidenceGate(plan) {
+    const reports = [];
+    walkItems(plan.items, "items", reports);
+    const blockers = reports.filter((r) => r.outcome === "missing" || r.outcome === "invalid");
+    if (blockers.length === 0) {
+        const lines = reports
+            .filter((r) => r.outcome === "evidence" || r.outcome === "disposition")
+            .map((r) => `  - ${r.path} "${r.title}": ${r.outcome} (${r.detail})`);
+        const summary = lines.length > 0
+            ? `Acceptance evidence gate passed (#3240):\n${lines.join("\n")}`
+            : "Acceptance evidence gate passed (#3240): no non-terminal criteria";
+        return { ok: true, message: summary, reports };
+    }
+    const lines = blockers.map((r) => `  - ${r.path} "${r.title}": ${r.detail}`);
+    return {
+        ok: false,
+        message: `Acceptance evidence required for scope:complete (#3240). ` +
+            `${blockers.length} criterion/criteria missing suitable evidence or disposition:\n` +
+            `${lines.join("\n")}\n` +
+            `Each non-terminal plan item needs evidence ` +
+            `{kind: test|review|merge|deploy|smoke|uat|observed_behavior, pointer, recorded_at, recorded_by} ` +
+            `or disposition {disposition: waived|deferred|not_applicable, reason, provenance (human-origin), recorded_at}. ` +
+            `merge/review alone cannot satisfy smoke|uat|deploy|observed_behavior criteria.`,
+        reports,
+    };
+}
+/**
+ * Format a short multi-line listing of evidence/disposition for every criterion
+ * (including already-terminal) for complete success output.
+ */
+export function formatAcceptanceCompletionListing(reports) {
+    if (reports.length === 0) {
+        return "Acceptance criteria: (none)";
+    }
+    const lines = reports.map((r) => {
+        if (r.outcome === "evidence" && r.evidence) {
+            return `  - ${r.path} "${r.title}": evidence kind=${r.evidence.kind} pointer=${r.evidence.pointer}`;
+        }
+        if (r.outcome === "disposition" && r.disposition) {
+            return (`  - ${r.path} "${r.title}": disposition=${r.disposition.disposition} ` +
+                `reason=${r.disposition.reason}`);
+        }
+        return `  - ${r.path} "${r.title}": ${r.outcome} (${r.detail})`;
+    });
+    return `Acceptance criteria:\n${lines.join("\n")}`;
+}
+//# sourceMappingURL=acceptance-evidence.js.map

package/dist/scope/coverage-map.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Parent-requirement coverage map for scope:decompose semantic fidelity (#3238 / epic #3237).
+ *
+ * When a parent scope authors stable requirement IDs, a decomposition draft must
+ * declare a machine-readable coverage map for every ID. Dispositions are a closed
+ * enum (covered | deferred | split | behavioral_delta) with required side fields.
+ * Negative invariants cannot be silently dropped: omit → fail closed; intentional
+ * change requires disposition behavioral_delta with a linked delta record.
+ *
+ * No LLM/prose semantic-equivalence judgment — structure only (Q1/Q7/Q8 locks).
+ */
+export declare const COVERAGE_DISPOSITIONS: readonly ["covered", "deferred", "split", "behavioral_delta"];
+export type CoverageDisposition = (typeof COVERAGE_DISPOSITIONS)[number];
+export declare const BEHAVIORAL_DELTA_CHANGE_KINDS: readonly ["reorder_stages", "remove_invariant", "weaken_invariant", "add_terminal_outcome", "remove_fallback", "change_fallback_order", "other"];
+export type BehavioralDeltaChangeKind = (typeof BEHAVIORAL_DELTA_CHANGE_KINDS)[number];
+export interface ParentRequirement {
+    readonly id: string;
+    readonly title: string;
+    readonly negativeInvariant: boolean;
+    readonly path: string;
+}
+export interface DeferredProvenance {
+    readonly reason: string;
+    readonly target_story_id?: string;
+    readonly target_path?: string;
+}
+export interface CoverageMapEntry {
+    readonly parent_requirement_id: string;
+    readonly disposition: CoverageDisposition;
+    readonly child_story_ids?: readonly string[];
+    readonly provenance?: DeferredProvenance;
+    readonly split_group?: string;
+    readonly part?: string;
+    readonly delta_id?: string;
+}
+export interface BehavioralDeltaRecord {
+    readonly delta_id: string;
+    readonly parent_requirement_ids: readonly string[];
+    readonly change_kind: BehavioralDeltaChangeKind;
+    readonly summary: string;
+    readonly before: string;
+    readonly after: string;
+    readonly rationale: string;
+}
+export interface CoverageEntryReport {
+    readonly parent_requirement_id: string;
+    readonly disposition: string | null;
+    readonly ok: boolean;
+    readonly detail: string;
+    readonly negative_invariant: boolean;
+}
+export interface CoverageReport {
+    readonly schema: "deft.decompose.coverage_report.v1";
+    readonly ok: boolean;
+    readonly parent_requirement_ids: readonly string[];
+    readonly negative_invariant_ids: readonly string[];
+    readonly entries: readonly CoverageEntryReport[];
+    readonly uncovered: readonly string[];
+    readonly errors: readonly string[];
+}
+export interface CoverageValidationResult {
+    readonly ok: boolean;
+    readonly report: CoverageReport;
+    readonly errors: readonly string[];
+}
+/**
+ * Collect authored parent requirement IDs (Q1).
+ * Sources: plan.items (nested) with id; plan.requirements; plan.metadata.requirement_ids.
+ */
+export declare function extractParentRequirements(parent: unknown): ParentRequirement[];
+/**
+ * Normalize draft.coverage_map from object-map or array form into entry list.
+ */
+export declare function parseCoverageMap(raw: unknown): {
+    entries: CoverageMapEntry[];
+    errors: string[];
+};
+/**
+ * Parse draft.behavioral_deltas (array). Records missing required fields are rejected.
+ */
+export declare function parseBehavioralDeltas(raw: unknown): {
+    deltas: BehavioralDeltaRecord[];
+    errors: string[];
+    byId: Map<string, BehavioralDeltaRecord>;
+};
+/**
+ * Validate coverage map against parent requirements and optional story ids.
+ * When the parent authors zero requirement IDs, validation is a no-op success
+ * (backward compatible with pre-#3238 drafts).
+ */
+export declare function validateCoverageMap(opts: {
+    parent: unknown;
+    draft: unknown;
+    storyIds?: readonly string[];
+}): CoverageValidationResult;
+/** Format a single-line machine-readable coverage report for CLI stdout. */
+export declare function formatCoverageReportLine(report: CoverageReport): string;
+//# sourceMappingURL=coverage-map.d.ts.map