@deftai/directive-core 0.99.0 → 0.101.0

package/dist/scope/coverage-map.js

@@ -0,0 +1,558 @@
+/**
+ * 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 const COVERAGE_DISPOSITIONS = ["covered", "deferred", "split", "behavioral_delta"];
+export const BEHAVIORAL_DELTA_CHANGE_KINDS = [
+    "reorder_stages",
+    "remove_invariant",
+    "weaken_invariant",
+    "add_terminal_outcome",
+    "remove_fallback",
+    "change_fallback_order",
+    "other",
+];
+const DISPOSITION_SET = new Set(COVERAGE_DISPOSITIONS);
+const CHANGE_KIND_SET = new Set(BEHAVIORAL_DELTA_CHANGE_KINDS);
+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;
+}
+function asStrList(value) {
+    if (value === null || value === undefined)
+        return [];
+    if (typeof value === "string")
+        return value.trim().length > 0 ? [value.trim()] : [];
+    if (Array.isArray(value)) {
+        return value.map((item) => String(item).trim()).filter((s) => s.length > 0);
+    }
+    return [];
+}
+function isNegativeInvariant(item) {
+    if (item.negative_invariant === true || item.negativeInvariant === true)
+        return true;
+    const kind = item.kind ?? item.type;
+    if (typeof kind === "string" && kind.trim().toLowerCase() === "negative_invariant") {
+        return true;
+    }
+    const narrative = asRecord(item.narrative);
+    if (narrative !== null) {
+        if (narrative.NegativeInvariant === true || narrative.negative_invariant === true) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Collect authored parent requirement IDs (Q1).
+ * Sources: plan.items (nested) with id; plan.requirements; plan.metadata.requirement_ids.
+ */
+export function extractParentRequirements(parent) {
+    const root = asRecord(parent);
+    if (root === null)
+        return [];
+    const plan = asRecord(root.plan) ?? root;
+    const byId = new Map();
+    function add(id, title, negativeInvariant, path) {
+        const trimmed = id.trim();
+        if (!trimmed)
+            return;
+        const existing = byId.get(trimmed);
+        if (existing !== undefined) {
+            if (negativeInvariant && !existing.negativeInvariant) {
+                byId.set(trimmed, { ...existing, negativeInvariant: true });
+            }
+            return;
+        }
+        byId.set(trimmed, {
+            id: trimmed,
+            title: title.trim() || trimmed,
+            negativeInvariant,
+            path,
+        });
+    }
+    function visitItems(items, prefix) {
+        if (!Array.isArray(items))
+            return;
+        for (let i = 0; i < items.length; i += 1) {
+            const item = items[i];
+            if (typeof item !== "object" || item === null || Array.isArray(item))
+                continue;
+            const obj = item;
+            const path = `${prefix}[${i}]`;
+            if (isNonEmptyString(obj.id)) {
+                add(obj.id, String(obj.title ?? obj.id), isNegativeInvariant(obj), path);
+            }
+            visitItems(obj.items, `${path}.items`);
+            visitItems(obj.subItems, `${path}.subItems`);
+        }
+    }
+    visitItems(plan.items, "plan.items");
+    const requirements = plan.requirements;
+    if (Array.isArray(requirements)) {
+        for (let i = 0; i < requirements.length; i += 1) {
+            const req = requirements[i];
+            if (typeof req === "string" && req.trim()) {
+                add(req, req, false, `plan.requirements[${i}]`);
+                continue;
+            }
+            if (typeof req === "object" && req !== null && !Array.isArray(req)) {
+                const obj = req;
+                if (isNonEmptyString(obj.id)) {
+                    add(obj.id, String(obj.title ?? obj.id), isNegativeInvariant(obj), `plan.requirements[${i}]`);
+                }
+            }
+        }
+    }
+    const metadata = asRecord(plan.metadata);
+    if (metadata !== null) {
+        for (const id of asStrList(metadata.requirement_ids)) {
+            add(id, id, false, "plan.metadata.requirement_ids");
+        }
+        for (const id of asStrList(metadata.requirementIds)) {
+            add(id, id, false, "plan.metadata.requirementIds");
+        }
+    }
+    return [...byId.values()];
+}
+function parseDisposition(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const norm = raw.trim().toLowerCase();
+    return DISPOSITION_SET.has(norm) ? norm : null;
+}
+function parseChangeKind(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const norm = raw.trim().toLowerCase().replace(/-/g, "_");
+    return CHANGE_KIND_SET.has(norm) ? norm : null;
+}
+/**
+ * Normalize draft.coverage_map from object-map or array form into entry list.
+ */
+export function parseCoverageMap(raw) {
+    const errors = [];
+    const entries = [];
+    if (raw === null || raw === undefined) {
+        return { entries, errors };
+    }
+    const pushEntry = (parentId, body, loc) => {
+        const disposition = parseDisposition(body.disposition);
+        if (disposition === null) {
+            errors.push(`${loc}: disposition must be one of ${COVERAGE_DISPOSITIONS.join("|")} ` +
+                `(got ${JSON.stringify(body.disposition ?? null)})`);
+            return;
+        }
+        const entry = {
+            parent_requirement_id: parentId,
+            disposition,
+        };
+        const childIds = asStrList(body.child_story_ids ?? body.childStoryIds ?? body.story_ids);
+        if (childIds.length > 0)
+            entry.child_story_ids = childIds;
+        if (disposition === "deferred") {
+            const provRaw = asRecord(body.provenance) ?? body;
+            const reason = provRaw.reason ?? body.reason;
+            const targetStory = provRaw.target_story_id ??
+                provRaw.targetStoryId ??
+                body.target_story_id ??
+                body.targetStoryId;
+            const targetPath = provRaw.target_path ?? provRaw.targetPath ?? body.target_path ?? body.targetPath;
+            if (!isNonEmptyString(reason)) {
+                errors.push(`${loc}: disposition deferred requires provenance.reason`);
+            }
+            else if (!isNonEmptyString(targetStory) && !isNonEmptyString(targetPath)) {
+                errors.push(`${loc}: disposition deferred requires provenance.target_story_id and/or target_path`);
+            }
+            else {
+                entry.provenance = {
+                    reason: String(reason).trim(),
+                    ...(isNonEmptyString(targetStory) ? { target_story_id: targetStory.trim() } : {}),
+                    ...(isNonEmptyString(targetPath) ? { target_path: targetPath.trim() } : {}),
+                };
+            }
+        }
+        if (disposition === "split") {
+            const group = body.split_group ?? body.splitGroup;
+            const part = body.part;
+            if (!isNonEmptyString(group)) {
+                errors.push(`${loc}: disposition split requires split_group`);
+            }
+            else {
+                entry.split_group = group.trim();
+            }
+            if (part === null || part === undefined || String(part).trim() === "") {
+                errors.push(`${loc}: disposition split requires part`);
+            }
+            else {
+                entry.part = String(part).trim();
+            }
+        }
+        if (disposition === "behavioral_delta") {
+            const deltaId = body.delta_id ?? body.deltaId;
+            if (!isNonEmptyString(deltaId)) {
+                errors.push(`${loc}: disposition behavioral_delta requires delta_id (separate approval hook)`);
+            }
+            else {
+                entry.delta_id = deltaId.trim();
+            }
+        }
+        entries.push(entry);
+    };
+    if (Array.isArray(raw)) {
+        for (let i = 0; i < raw.length; i += 1) {
+            const item = raw[i];
+            const loc = `coverage_map[${i}]`;
+            if (typeof item !== "object" || item === null || Array.isArray(item)) {
+                errors.push(`${loc}: entry must be an object`);
+                continue;
+            }
+            const obj = item;
+            const parentId = obj.parent_requirement_id ?? obj.parentRequirementId ?? obj.id;
+            if (!isNonEmptyString(parentId)) {
+                errors.push(`${loc}: parent_requirement_id is required`);
+                continue;
+            }
+            pushEntry(parentId.trim(), obj, loc);
+        }
+        return { entries, errors };
+    }
+    const map = asRecord(raw);
+    if (map === null) {
+        errors.push("coverage_map must be an object map or array of entries");
+        return { entries, errors };
+    }
+    for (const [key, value] of Object.entries(map)) {
+        const loc = `coverage_map[${key}]`;
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+            errors.push(`${loc}: entry must be an object`);
+            continue;
+        }
+        const obj = value;
+        const parentId = obj.parent_requirement_id ?? obj.parentRequirementId ?? key;
+        if (!isNonEmptyString(parentId)) {
+            errors.push(`${loc}: parent_requirement_id is required`);
+            continue;
+        }
+        pushEntry(String(parentId).trim(), obj, loc);
+    }
+    return { entries, errors };
+}
+/**
+ * Parse draft.behavioral_deltas (array). Records missing required fields are rejected.
+ */
+export function parseBehavioralDeltas(raw) {
+    const errors = [];
+    const deltas = [];
+    const byId = new Map();
+    if (raw === null || raw === undefined) {
+        return { deltas, errors, byId };
+    }
+    if (!Array.isArray(raw)) {
+        errors.push("behavioral_deltas must be an array");
+        return { deltas, errors, byId };
+    }
+    for (let i = 0; i < raw.length; i += 1) {
+        const item = raw[i];
+        const loc = `behavioral_deltas[${i}]`;
+        if (typeof item !== "object" || item === null || Array.isArray(item)) {
+            errors.push(`${loc}: must be an object`);
+            continue;
+        }
+        const obj = item;
+        const deltaId = obj.delta_id ?? obj.deltaId;
+        const changeKind = parseChangeKind(obj.change_kind ?? obj.changeKind);
+        const parentIds = asStrList(obj.parent_requirement_ids ?? obj.parentRequirementIds);
+        const summary = obj.summary;
+        const before = obj.before;
+        const after = obj.after;
+        const rationale = obj.rationale;
+        const fieldErrors = [];
+        if (!isNonEmptyString(deltaId))
+            fieldErrors.push("delta_id");
+        if (parentIds.length === 0)
+            fieldErrors.push("parent_requirement_ids[]");
+        if (changeKind === null) {
+            fieldErrors.push(`change_kind (${BEHAVIORAL_DELTA_CHANGE_KINDS.join("|")})`);
+        }
+        if (!isNonEmptyString(summary))
+            fieldErrors.push("summary");
+        if (!isNonEmptyString(before))
+            fieldErrors.push("before");
+        if (!isNonEmptyString(after))
+            fieldErrors.push("after");
+        if (!isNonEmptyString(rationale))
+            fieldErrors.push("rationale");
+        if (fieldErrors.length > 0) {
+            errors.push(`${loc}: missing/invalid fields: ${fieldErrors.join(", ")}`);
+            continue;
+        }
+        const id = String(deltaId).trim();
+        if (byId.has(id)) {
+            errors.push(`${loc}: duplicate delta_id '${id}'`);
+            continue;
+        }
+        const record = {
+            delta_id: id,
+            parent_requirement_ids: parentIds,
+            change_kind: changeKind,
+            summary: String(summary).trim(),
+            before: String(before).trim(),
+            after: String(after).trim(),
+            rationale: String(rationale).trim(),
+        };
+        deltas.push(record);
+        byId.set(id, record);
+    }
+    return { deltas, errors, byId };
+}
+/**
+ * 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 function validateCoverageMap(opts) {
+    const requirements = extractParentRequirements(opts.parent);
+    const parentIds = requirements.map((r) => r.id);
+    const negativeIds = requirements.filter((r) => r.negativeInvariant).map((r) => r.id);
+    const reqById = new Map(requirements.map((r) => [r.id, r]));
+    const draft = asRecord(opts.draft) ?? {};
+    const parseErrors = [];
+    const { entries, errors: mapErrors } = parseCoverageMap(draft.coverage_map ?? draft.coverageMap);
+    parseErrors.push(...mapErrors);
+    const { byId: deltasById, errors: deltaErrors } = parseBehavioralDeltas(draft.behavioral_deltas ?? draft.behavioralDeltas);
+    parseErrors.push(...deltaErrors);
+    const entryReports = [];
+    const errors = [...parseErrors];
+    const coveredIds = new Set();
+    // parent_id → set of dispositions seen (conflicting dispositions fail closed)
+    const dispositionsByParent = new Map();
+    // parent_id → entry count (non-split may appear at most once; split uses parts)
+    const entryCountByParent = new Map();
+    // split_group → parent_id → set of parts
+    const splitParts = new Map();
+    if (parentIds.length === 0) {
+        const report = {
+            schema: "deft.decompose.coverage_report.v1",
+            ok: parseErrors.length === 0,
+            parent_requirement_ids: [],
+            negative_invariant_ids: [],
+            entries: [],
+            uncovered: [],
+            errors: parseErrors,
+        };
+        return { ok: report.ok, report, errors: parseErrors };
+    }
+    if (entries.length === 0 && parseErrors.length === 0) {
+        errors.push("coverage_map is required when the parent authors requirement IDs; " +
+            `uncovered: ${parentIds.join(", ")}`);
+    }
+    const knownStories = opts.storyIds !== undefined ? new Set(opts.storyIds) : null;
+    for (const entry of entries) {
+        const req = reqById.get(entry.parent_requirement_id);
+        const isNeg = req?.negativeInvariant === true;
+        const loc = `coverage_map[${entry.parent_requirement_id}]`;
+        if (req === undefined) {
+            const detail = `unknown parent_requirement_id '${entry.parent_requirement_id}' (not authored on parent)`;
+            errors.push(`${loc}: ${detail}`);
+            entryReports.push({
+                parent_requirement_id: entry.parent_requirement_id,
+                disposition: entry.disposition,
+                ok: false,
+                detail,
+                negative_invariant: false,
+            });
+            continue;
+        }
+        coveredIds.add(entry.parent_requirement_id);
+        const priorCount = entryCountByParent.get(entry.parent_requirement_id) ?? 0;
+        entryCountByParent.set(entry.parent_requirement_id, priorCount + 1);
+        let dispSet = dispositionsByParent.get(entry.parent_requirement_id);
+        if (dispSet === undefined) {
+            dispSet = new Set();
+            dispositionsByParent.set(entry.parent_requirement_id, dispSet);
+        }
+        dispSet.add(entry.disposition);
+        if (dispSet.size > 1) {
+            const detail = `conflicting dispositions for '${entry.parent_requirement_id}': ` +
+                `${[...dispSet].sort().join(", ")} (exactly one disposition per parent ID)`;
+            errors.push(`${loc}: ${detail}`);
+            entryReports.push({
+                parent_requirement_id: entry.parent_requirement_id,
+                disposition: entry.disposition,
+                ok: false,
+                detail,
+                negative_invariant: isNeg,
+            });
+            continue;
+        }
+        // Non-split dispositions must appear exactly once per parent ID (split uses ≥2 parts).
+        if (entry.disposition !== "split" && priorCount >= 1) {
+            const detail = `duplicate coverage entries for '${entry.parent_requirement_id}' ` +
+                `with disposition '${entry.disposition}' (one entry per parent ID; use split for multi-part)`;
+            errors.push(`${loc}: ${detail}`);
+            entryReports.push({
+                parent_requirement_id: entry.parent_requirement_id,
+                disposition: entry.disposition,
+                ok: false,
+                detail,
+                negative_invariant: isNeg,
+            });
+            continue;
+        }
+        if (entry.child_story_ids !== undefined && knownStories !== null) {
+            for (const sid of entry.child_story_ids) {
+                if (!knownStories.has(sid)) {
+                    errors.push(`${loc}: child_story_ids references unknown story '${sid}'`);
+                }
+            }
+        }
+        // deferred.target_story_id may name a future story outside this draft; do not
+        // require membership in storyIds (target_path alone is also valid provenance).
+        if (entry.disposition === "split") {
+            const group = entry.split_group ?? "";
+            const part = entry.part ?? "";
+            let byParent = splitParts.get(group);
+            if (byParent === undefined) {
+                byParent = new Map();
+                splitParts.set(group, byParent);
+            }
+            let parts = byParent.get(entry.parent_requirement_id);
+            if (parts === undefined) {
+                parts = new Set();
+                byParent.set(entry.parent_requirement_id, parts);
+            }
+            if (parts.has(part)) {
+                const detail = `duplicate split claim for '${entry.parent_requirement_id}' ` +
+                    `split_group='${group}' part='${part}' (each part must be unique)`;
+                errors.push(`${loc}: ${detail}`);
+                entryReports.push({
+                    parent_requirement_id: entry.parent_requirement_id,
+                    disposition: entry.disposition,
+                    ok: false,
+                    detail,
+                    negative_invariant: isNeg,
+                });
+                continue;
+            }
+            parts.add(part);
+        }
+        if (entry.disposition === "behavioral_delta") {
+            const deltaId = entry.delta_id;
+            if (!isNonEmptyString(deltaId)) {
+                // Already reported at parse time; keep entry report.
+                entryReports.push({
+                    parent_requirement_id: entry.parent_requirement_id,
+                    disposition: entry.disposition,
+                    ok: false,
+                    detail: "missing delta_id",
+                    negative_invariant: isNeg,
+                });
+                continue;
+            }
+            const delta = deltasById.get(deltaId);
+            if (delta === undefined) {
+                const detail = `behavioral_delta delta_id '${deltaId}' has no linked record in behavioral_deltas ` +
+                    `(separate approval hook)`;
+                errors.push(`${loc}: ${detail}`);
+                entryReports.push({
+                    parent_requirement_id: entry.parent_requirement_id,
+                    disposition: entry.disposition,
+                    ok: false,
+                    detail,
+                    negative_invariant: isNeg,
+                });
+                continue;
+            }
+            if (!delta.parent_requirement_ids.includes(entry.parent_requirement_id)) {
+                const detail = `behavioral_delta '${deltaId}' does not list parent_requirement_id ` +
+                    `'${entry.parent_requirement_id}'`;
+                errors.push(`${loc}: ${detail}`);
+                entryReports.push({
+                    parent_requirement_id: entry.parent_requirement_id,
+                    disposition: entry.disposition,
+                    ok: false,
+                    detail,
+                    negative_invariant: isNeg,
+                });
+                continue;
+            }
+        }
+        entryReports.push({
+            parent_requirement_id: entry.parent_requirement_id,
+            disposition: entry.disposition,
+            ok: true,
+            detail: `disposition=${entry.disposition}`,
+            negative_invariant: isNeg,
+        });
+    }
+    // Incomplete split groups: each parent_id under a split_group needs ≥2 distinct parts.
+    // A parent requirement may belong to at most one split_group (ambiguous multi-group fails closed).
+    const splitGroupsByParent = new Map();
+    for (const [group, byParent] of splitParts) {
+        for (const [parentId, parts] of byParent) {
+            let groups = splitGroupsByParent.get(parentId);
+            if (groups === undefined) {
+                groups = new Set();
+                splitGroupsByParent.set(parentId, groups);
+            }
+            groups.add(group);
+            if (parts.size < 2) {
+                errors.push(`coverage_map split_group '${group}' for '${parentId}' is incomplete ` +
+                    `(need ≥2 distinct parts; got ${parts.size}: ${[...parts].join(", ") || "(none)"})`);
+            }
+        }
+    }
+    for (const [parentId, groups] of splitGroupsByParent) {
+        if (groups.size > 1) {
+            errors.push(`coverage_map parent '${parentId}' appears in multiple split_groups ` +
+                `(${[...groups].sort().join(", ")}); use exactly one split_group per parent ID`);
+        }
+    }
+    const uncovered = parentIds.filter((id) => !coveredIds.has(id));
+    if (uncovered.length > 0) {
+        errors.push(`uncovered parent requirement IDs: ${uncovered.join(", ")}`);
+        for (const id of uncovered) {
+            const req = reqById.get(id);
+            const isNeg = req?.negativeInvariant === true;
+            if (isNeg) {
+                errors.push(`negative invariant '${id}' omitted without coverage or behavioral_delta ` +
+                    `(silent removal is forbidden)`);
+            }
+            entryReports.push({
+                parent_requirement_id: id,
+                disposition: null,
+                ok: false,
+                detail: isNeg ? "negative invariant uncovered (silent removal)" : "uncovered",
+                negative_invariant: isNeg,
+            });
+        }
+    }
+    const report = {
+        schema: "deft.decompose.coverage_report.v1",
+        ok: errors.length === 0,
+        parent_requirement_ids: parentIds,
+        negative_invariant_ids: negativeIds,
+        entries: entryReports,
+        uncovered,
+        errors,
+    };
+    return { ok: report.ok, report, errors };
+}
+/** Format a single-line machine-readable coverage report for CLI stdout. */
+export function formatCoverageReportLine(report) {
+    return `COVERAGE_REPORT ${JSON.stringify(report)}`;
+}
+//# sourceMappingURL=coverage-map.js.map

package/dist/scope/decompose.d.ts

@@ -34,6 +34,11 @@ export interface ApplyDecompositionOptions {
     draftPath: string;
     checkOnly: boolean;
     date: string;
+    /**
+     * Optional GitHub-style repo (owner/name). When omitted, resolved via
+     * DEFT_TRIAGE_REPO / git remote origin so repo-bound structural grants match (#3291).
+     */
+    repo?: string | null;
 }
 export declare function applyDecomposition(opts: ApplyDecompositionOptions): string[];
 /** CLI entry for scope-decompose (mirrors scope_decompose.py main()). */