@deftai/directive-core 0.99.0 → 0.101.0

package/dist/run-summary/path.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Resolve where run-summary JSONL should go (#3282 emission matrix).
+ *
+ * - `DEFT_RUN_SUMMARY_PATH=<path>` → append JSONL there (explicit; warn once on write fail)
+ * - `DEFT_RUN_SUMMARY_PATH=-` → stdout lines prefixed `DEFT-TLM:`
+ * - unset → repo-root `.deft-run-summary.json` only when .gitignore covers it; else silent
+ */
+import { type RunSummaryDestination } from "./types.js";
+export { DEFAULT_RUN_SUMMARY_BASENAME, ENV_RUN_SUMMARY_PATH, RUN_SUMMARY_STDOUT_PREFIX, RUN_SUMMARY_WRITE_WARNING, } from "./types.js";
+/**
+ * True when a .gitignore line covers the default run-summary basename.
+ * Matches exact line or trailing slash variants; ignores comments.
+ */
+export declare function gitignoreCoversRunSummary(projectRoot: string, basename?: string): boolean;
+export interface ResolveRunSummaryDestinationOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    /** Test seam for gitignore coverage. */
+    readonly gitignoreCovers?: (projectRoot: string) => boolean;
+}
+/**
+ * Resolve emission destination for the run-summary matrix (#3282).
+ * Never throws — fail-open consumers treat resolution errors as silent.
+ */
+export declare function resolveRunSummaryDestination(projectRoot: string, options?: ResolveRunSummaryDestinationOptions): RunSummaryDestination;
+//# sourceMappingURL=path.d.ts.map

package/dist/run-summary/path.js

@@ -0,0 +1,78 @@
+/**
+ * Resolve where run-summary JSONL should go (#3282 emission matrix).
+ *
+ * - `DEFT_RUN_SUMMARY_PATH=<path>` → append JSONL there (explicit; warn once on write fail)
+ * - `DEFT_RUN_SUMMARY_PATH=-` → stdout lines prefixed `DEFT-TLM:`
+ * - unset → repo-root `.deft-run-summary.json` only when .gitignore covers it; else silent
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { DEFAULT_RUN_SUMMARY_BASENAME, ENV_RUN_SUMMARY_PATH, } from "./types.js";
+export { DEFAULT_RUN_SUMMARY_BASENAME, ENV_RUN_SUMMARY_PATH, RUN_SUMMARY_STDOUT_PREFIX, RUN_SUMMARY_WRITE_WARNING, } from "./types.js";
+/**
+ * True when a .gitignore line covers the default run-summary basename.
+ * Matches exact line or trailing slash variants; ignores comments.
+ */
+export function gitignoreCoversRunSummary(projectRoot, basename = DEFAULT_RUN_SUMMARY_BASENAME) {
+    const giPath = join(projectRoot, ".gitignore");
+    if (!existsSync(giPath)) {
+        return false;
+    }
+    let text;
+    try {
+        text = readFileSync(giPath, "utf8");
+    }
+    catch {
+        return false;
+    }
+    const targets = new Set([basename, basename.replace(/^\.\//, "")]);
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line.length === 0 || line.startsWith("#"))
+            continue;
+        // Strip trailing inline comments carefully (space + #).
+        const bare = line.replace(/\s+#.*$/, "").trim();
+        if (targets.has(bare) || targets.has(bare.replace(/^\//, ""))) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Resolve emission destination for the run-summary matrix (#3282).
+ * Never throws — fail-open consumers treat resolution errors as silent.
+ */
+export function resolveRunSummaryDestination(projectRoot, options = {}) {
+    try {
+        const env = options.env ?? process.env;
+        const raw = env[ENV_RUN_SUMMARY_PATH];
+        if (raw !== undefined && raw.trim() === "-") {
+            return { kind: "stdout" };
+        }
+        if (raw !== undefined && raw.trim().length > 0) {
+            const trimmed = raw.trim();
+            const path = isAbsolute(trimmed) ? resolve(trimmed) : resolve(projectRoot, trimmed);
+            return {
+                kind: "file",
+                path,
+                truncateOnSessionStart: false,
+                explicit: true,
+            };
+        }
+        // Unset: default path only with gitignore coverage.
+        const covers = options.gitignoreCovers?.(projectRoot) ?? gitignoreCoversRunSummary(projectRoot);
+        if (!covers) {
+            return { kind: "silent" };
+        }
+        return {
+            kind: "file",
+            path: resolve(projectRoot, DEFAULT_RUN_SUMMARY_BASENAME),
+            truncateOnSessionStart: true,
+            explicit: false,
+        };
+    }
+    catch {
+        return { kind: "silent" };
+    }
+}
+//# sourceMappingURL=path.js.map

package/dist/run-summary/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Run-summary telemetry types (#3282).
+ *
+ * Event-driven JSONL lines for harness collection. Silent by default unless
+ * `DEFT_RUN_SUMMARY_PATH` is set (or the gitignored default path is writable).
+ */
+export declare const RUN_SUMMARY_SCHEMA_VERSION: 1;
+/** Env var that opts into / redirects run-summary JSONL (#3282). */
+export declare const ENV_RUN_SUMMARY_PATH = "DEFT_RUN_SUMMARY_PATH";
+/** Repo-root default collectible path when gitignore coverage is present. */
+export declare const DEFAULT_RUN_SUMMARY_BASENAME = ".deft-run-summary.json";
+/** Prefix for stdout lines when `DEFT_RUN_SUMMARY_PATH=-`. */
+export declare const RUN_SUMMARY_STDOUT_PREFIX = "DEFT-TLM:";
+/** One warning when an explicitly requested write fails. */
+export declare const RUN_SUMMARY_WRITE_WARNING = "[deft run-summary] failed to write DEFT_RUN_SUMMARY_PATH telemetry (fail-open; exit codes unchanged)";
+export declare const RUN_SUMMARY_EVENT_KINDS: readonly ["session_start", "dial_transition", "check_invocation"];
+export type RunSummaryEventKind = (typeof RUN_SUMMARY_EVENT_KINDS)[number];
+export interface RunSummaryBaseFields {
+    readonly schema_version: typeof RUN_SUMMARY_SCHEMA_VERSION;
+    readonly session_id: string;
+    readonly framework_version: string;
+    /** Monotonic per-emitter sequence (1-based). */
+    readonly seq: number;
+    readonly ts: string;
+    readonly event: RunSummaryEventKind;
+}
+export interface SessionStartRunSummaryPayload {
+    readonly ceremony_dial?: Record<string, unknown>;
+    readonly preflight?: Record<string, unknown>;
+    readonly ceremony_tier?: string;
+    readonly ready?: boolean;
+    readonly exit_code?: number;
+    /** #3286: orientation surfaces composed into session:start (graduation trigger). */
+    readonly orientation_call_count?: number;
+    readonly orientation_compact?: boolean;
+    readonly deposit_sha?: string;
+    readonly orientation_later_status?: string;
+    readonly orientation_sections?: readonly Record<string, unknown>[];
+}
+export interface DialTransitionRunSummaryPayload {
+    readonly from: string | null;
+    readonly to: string;
+    readonly reason: string;
+    readonly evidence?: string;
+}
+export interface CheckGateOutcome {
+    readonly id: string;
+    readonly status: "run" | "skipped" | "failed";
+    readonly exit_code?: number;
+    readonly cause?: string;
+    readonly remedy?: string;
+    readonly from_cache?: boolean;
+}
+export interface CheckInvocationRunSummaryPayload {
+    readonly target: string;
+    readonly exit_code: number;
+    readonly degraded?: boolean;
+    readonly gates: readonly CheckGateOutcome[];
+}
+export type RunSummaryPayload = SessionStartRunSummaryPayload | DialTransitionRunSummaryPayload | CheckInvocationRunSummaryPayload;
+export type RunSummaryLine = RunSummaryBaseFields & {
+    readonly payload: RunSummaryPayload;
+};
+export type RunSummaryDestination = {
+    readonly kind: "silent";
+} | {
+    readonly kind: "stdout";
+} | {
+    readonly kind: "file";
+    readonly path: string;
+    /** Truncate default-path file on session_start only. */
+    readonly truncateOnSessionStart: boolean;
+    /** Explicit path (env set) vs default gitignored path. */
+    readonly explicit: boolean;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/run-summary/types.js

@@ -0,0 +1,21 @@
+/**
+ * Run-summary telemetry types (#3282).
+ *
+ * Event-driven JSONL lines for harness collection. Silent by default unless
+ * `DEFT_RUN_SUMMARY_PATH` is set (or the gitignored default path is writable).
+ */
+export const RUN_SUMMARY_SCHEMA_VERSION = 1;
+/** Env var that opts into / redirects run-summary JSONL (#3282). */
+export const ENV_RUN_SUMMARY_PATH = "DEFT_RUN_SUMMARY_PATH";
+/** Repo-root default collectible path when gitignore coverage is present. */
+export const DEFAULT_RUN_SUMMARY_BASENAME = ".deft-run-summary.json";
+/** Prefix for stdout lines when `DEFT_RUN_SUMMARY_PATH=-`. */
+export const RUN_SUMMARY_STDOUT_PREFIX = "DEFT-TLM:";
+/** One warning when an explicitly requested write fails. */
+export const RUN_SUMMARY_WRITE_WARNING = "[deft run-summary] failed to write DEFT_RUN_SUMMARY_PATH telemetry (fail-open; exit codes unchanged)";
+export const RUN_SUMMARY_EVENT_KINDS = [
+    "session_start",
+    "dial_transition",
+    "check_invocation",
+];
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,110 @@
+/**
+ * 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 type { GrantOrigin } from "../authz/types.js";
+/** Canonical namespaced key for typed acceptance evidence (#3305 / #1620). */
+export declare const ACCEPTANCE_EVIDENCE_KEY: "x-directive/evidence";
+/** Canonical namespaced key for human-origin disposition (#3305 / #1620). */
+export declare const ACCEPTANCE_DISPOSITION_KEY: "x-directive/disposition";
+/** 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;
+/**
+ * Read only namespaced acceptance fields (#3305). Bare `evidence` / `disposition`
+ * are never treated as success (no permanent dual-read).
+ */
+export declare function readNamespacedAcceptanceFields(item: Record<string, unknown>): {
+    readonly evidence: unknown;
+    readonly disposition: unknown;
+    readonly hasEvidence: boolean;
+    readonly hasDisposition: boolean;
+    readonly hasBareEvidence: boolean;
+    readonly hasBareDisposition: boolean;
+};
+/**
+ * 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 declare function stampNamespacedEvidence(item: Record<string, unknown>, record: AcceptanceEvidenceRecord): void;
+/**
+ * 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 declare function stampNamespacedDisposition(item: Record<string, unknown>, record: AcceptanceDispositionRecord): void;
+/**
+ * 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