@deftai/directive-core 0.99.0 → 0.101.0

package/dist/scope/acceptance-evidence.js

@@ -0,0 +1,422 @@
+/**
+ * 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.
+ *
+ * Canonical item keys are namespaced under #1620 / #3305 (Option B):
+ * - plan.items[].x-directive/evidence
+ * - plan.items[].x-directive/disposition
+ * Bare `evidence` / `disposition` are not valid typed evidence (no dual-read).
+ * ITEM_CORE is not expanded with bare keys; verify:vbrief-conformance rejects them.
+ */
+import { isHumanOrigin } from "../authz/origin.js";
+/** Canonical namespaced key for typed acceptance evidence (#3305 / #1620). */
+export const ACCEPTANCE_EVIDENCE_KEY = "x-directive/evidence";
+/** Canonical namespaced key for human-origin disposition (#3305 / #1620). */
+export const ACCEPTANCE_DISPOSITION_KEY = "x-directive/disposition";
+/** 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;
+}
+/**
+ * Read only namespaced acceptance fields (#3305). Bare `evidence` / `disposition`
+ * are never treated as success (no permanent dual-read).
+ */
+export function readNamespacedAcceptanceFields(item) {
+    const evidence = item[ACCEPTANCE_EVIDENCE_KEY];
+    const disposition = item[ACCEPTANCE_DISPOSITION_KEY];
+    return {
+        evidence,
+        disposition,
+        hasEvidence: evidence !== undefined && evidence !== null,
+        hasDisposition: disposition !== undefined && disposition !== null,
+        hasBareEvidence: item.evidence !== undefined && item.evidence !== null,
+        hasBareDisposition: item.disposition !== undefined && item.disposition !== null,
+    };
+}
+/** Clear bare and namespaced acceptance fields so stamps never leave dual/conflicting keys. */
+function clearAcceptanceStampFields(item) {
+    delete item.evidence;
+    delete item.disposition;
+    delete item[ACCEPTANCE_EVIDENCE_KEY];
+    delete item[ACCEPTANCE_DISPOSITION_KEY];
+}
+/**
+ * Stamp typed evidence under the canonical namespaced key only.
+ * Clears bare evidence/disposition and any prior namespaced disposition so the item
+ * cannot carry both acceptance fields after a replace (#3305 Greptile P2).
+ */
+export function stampNamespacedEvidence(item, record) {
+    clearAcceptanceStampFields(item);
+    item[ACCEPTANCE_EVIDENCE_KEY] = {
+        kind: record.kind,
+        pointer: record.pointer,
+        recorded_at: record.recorded_at,
+        recorded_by: record.recorded_by,
+    };
+}
+/**
+ * Stamp human-origin disposition under the canonical namespaced key only.
+ * Clears bare evidence/disposition and any prior namespaced evidence so the item
+ * cannot carry both acceptance fields after a replace (#3305 Greptile P2).
+ */
+export function stampNamespacedDisposition(item, record) {
+    clearAcceptanceStampFields(item);
+    const body = {
+        disposition: record.disposition,
+        reason: record.reason,
+        provenance: { ...record.provenance },
+        recorded_at: record.recorded_at,
+    };
+    if (record.resume_when !== undefined) {
+        body.resume_when = record.resume_when;
+    }
+    item[ACCEPTANCE_DISPOSITION_KEY] = body;
+}
+function evaluateOneItem(item, path) {
+    const title = itemLabel(item, path);
+    const status = String(item.status ?? "");
+    if (!NON_TERMINAL_ITEM_STATUSES.has(status)) {
+        // Already-terminal: complete does not re-validate typed evidence (#3240 / #3305).
+        // Suitability/provenance apply only when advancing non-terminal items. Pre-marking
+        // items completed with narrative-only fields still skips the typed gate — that is
+        // intentional for fail/cancel and historical terminals, not a silent dual success path.
+        return {
+            path,
+            title,
+            outcome: "already_terminal",
+            detail: `status=${status || "(empty)"} (not advanced; typed evidence not re-checked)`,
+        };
+    }
+    const fields = readNamespacedAcceptanceFields(item);
+    const { hasEvidence, hasDisposition, hasBareEvidence, hasBareDisposition } = fields;
+    if (hasEvidence && hasDisposition) {
+        return {
+            path,
+            title,
+            outcome: "invalid",
+            detail: `exactly one of ${ACCEPTANCE_EVIDENCE_KEY} or ${ACCEPTANCE_DISPOSITION_KEY} required; both present`,
+        };
+    }
+    if (!hasEvidence && !hasDisposition) {
+        const bareHint = hasBareEvidence || hasBareDisposition
+            ? ` bare evidence/disposition ignored — use ${ACCEPTANCE_EVIDENCE_KEY} or ${ACCEPTANCE_DISPOSITION_KEY} (#3305);`
+            : "";
+        return {
+            path,
+            title,
+            outcome: "missing",
+            detail: `no ${ACCEPTANCE_EVIDENCE_KEY} or ${ACCEPTANCE_DISPOSITION_KEY};` +
+                `${bareHint} scope:complete refuses to auto-complete (#3240)`,
+        };
+    }
+    if (hasDisposition) {
+        const parsed = parseDisposition(fields.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(fields.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 / #3305). ` +
+            `${blockers.length} criterion/criteria missing suitable evidence or disposition:\n` +
+            `${lines.join("\n")}\n` +
+            `Each non-terminal plan item needs ${ACCEPTANCE_EVIDENCE_KEY} ` +
+            `{kind: test|review|merge|deploy|smoke|uat|observed_behavior, pointer, recorded_at, recorded_by} ` +
+            `or ${ACCEPTANCE_DISPOSITION_KEY} {disposition: waived|deferred|not_applicable, reason, provenance (human-origin), recorded_at}. ` +
+            `Bare evidence/disposition keys are not valid (#1620 / #3305). ` +
+            `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