@deftai/directive-core 0.87.0 → 0.89.0

package/dist/authz/templates.js

@@ -0,0 +1,241 @@
+/**
+ * AFK grant templates (#1095 Wave 4 + #871 Wave 5).
+ *
+ * Templates are **presets** on the Wave 1 mint path only:
+ * they call mintHumanOriginGrant / operator-cli origin.
+ *
+ * ⊗ Do not invent a second authorization SoT under ~/.deft/session-auth
+ *   that agents can self-mint as alternate permission.
+ */
+import { mintHumanOriginGrant } from "./actions.js";
+import { normaliseClosedVerbTarget, targetSurfaceCandidates } from "./closed-verb.js";
+import { builtinReleaseVerbClassification, getVerbRow, } from "./verb-classification.js";
+/** Canonical AFK template names for Wave 4 release-class closed verbs. */
+export const CLOSED_VERB_TEMPLATE_NAMES = [
+    "release-cut",
+    "release-publish",
+    "release-rollback",
+];
+/** Walk-away finish-loop template (#871 Wave 5) — not a release closed-verb. */
+export const FINISH_LOOP_TEMPLATE_NAME = "finish-loop";
+/** All AFK templates accepted by `authz:grant --template`. */
+export const AFK_TEMPLATE_NAMES = [
+    ...CLOSED_VERB_TEMPLATE_NAMES,
+    FINISH_LOOP_TEMPLATE_NAME,
+];
+/**
+ * AuthzOperation set covered by the finish-loop template.
+ * Release-class ops are explicitly carved out (operator must mint a release-* grant).
+ */
+export const FINISH_LOOP_OPERATIONS = [
+    "edit",
+    "push",
+    "pr",
+    "merge",
+];
+/** Default AFK window for finish-loop (matches issue #871 walk-away notes). */
+export const FINISH_LOOP_DEFAULT_EXPIRY_HOURS = 8;
+export function isClosedVerbTemplateName(name) {
+    return CLOSED_VERB_TEMPLATE_NAMES.includes(name.trim().toLowerCase());
+}
+export function isFinishLoopTemplateName(name) {
+    return name.trim().toLowerCase() === FINISH_LOOP_TEMPLATE_NAME;
+}
+export function isAfkTemplateName(name) {
+    return AFK_TEMPLATE_NAMES.includes(name.trim().toLowerCase());
+}
+function parseExpiryHours(defaultExpiry) {
+    const m = /^(\d+)\s*h$/i.exec(defaultExpiry.trim());
+    if (m !== null)
+        return Number(m[1]);
+    return 1;
+}
+function isoExpiry(now, hours) {
+    return new Date(now.getTime() + hours * 3600 * 1000).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/**
+ * Resolve template → mint input (operations + surfaces). Pure; no I/O.
+ * Always routes operations through Wave 1 AuthzOperation names.
+ */
+export function resolveClosedVerbTemplate(input) {
+    const name = input.template.trim().toLowerCase();
+    if (!isClosedVerbTemplateName(name)) {
+        throw new Error(`unknown closed-verb template '${input.template}'; expected one of: ${CLOSED_VERB_TEMPLATE_NAMES.join(", ")}` +
+            (isFinishLoopTemplateName(input.template)
+                ? ` (use resolveFinishLoopTemplate / mintFinishLoopTemplateGrant for finish-loop)`
+                : ""));
+    }
+    const target = input.target.trim();
+    if (target.length === 0) {
+        throw new Error(`template ${name} requires a non-empty --target`);
+    }
+    const table = input.classification ?? builtinReleaseVerbClassification();
+    const row = getVerbRow(table, name);
+    if (row === null) {
+        throw new Error(`verb classification missing row for template ${name}`);
+    }
+    // Prefer the precise closed-verb operation (least privilege); deployment is
+    // accepted at evaluate time as a broader alternative but not minted by default.
+    const op = name;
+    const surfaces = targetSurfaceCandidates(target);
+    // Prefer canonical version form without forcing only-v prefix ambiguity.
+    const norm = normaliseClosedVerbTarget(target);
+    const surfaceList = surfaces.length > 0 ? surfaces : norm !== null ? [norm, `v${norm}`] : [target];
+    let expiresAt = input.expiresAt ?? null;
+    if (expiresAt === null || expiresAt === undefined) {
+        const hours = parseExpiryHours(row.default_expiry);
+        const now = input.now ?? new Date();
+        expiresAt = isoExpiry(now, hours);
+    }
+    return {
+        operations: [op],
+        surfaces: surfaceList,
+        expiresAt,
+        template: name,
+    };
+}
+/**
+ * Resolve finish-loop AFK template → mint ops (edit/push/pr/merge). Pure; no I/O.
+ * Does not mint release-class operations.
+ */
+export function resolveFinishLoopTemplate(input) {
+    let expiresAt = input.expiresAt ?? null;
+    if (expiresAt === null || expiresAt === undefined) {
+        const hours = input.durationHours !== undefined && Number.isFinite(input.durationHours)
+            ? Math.max(1, Math.floor(input.durationHours))
+            : FINISH_LOOP_DEFAULT_EXPIRY_HOURS;
+        expiresAt = isoExpiry(input.now ?? new Date(), hours);
+    }
+    return {
+        operations: [...FINISH_LOOP_OPERATIONS],
+        surfaces: input.surfaces !== undefined ? [...input.surfaces] : [],
+        expiresAt,
+        template: FINISH_LOOP_TEMPLATE_NAME,
+    };
+}
+/**
+ * Mint a human-origin grant for an AFK closed-verb template.
+ * **Sole mint path:** mintHumanOriginGrant (operator-cli). No session-auth SoT.
+ */
+export function mintClosedVerbTemplateGrant(input) {
+    // Production dual-mint guard: templates never open an independent session-auth mint.
+    const dualMint = assertNoIndependentSessionAuthMint();
+    if (dualMint.sessionAuthIsAuthority || dualMint.mintPath !== "mintHumanOriginGrant") {
+        throw new Error("closed-verb template mint refused: dual authorization SoT is forbidden (#1095)");
+    }
+    const resolved = resolveClosedVerbTemplate({
+        template: input.template,
+        target: input.target,
+        now: input.now,
+        expiresAt: input.expiresAt,
+        classification: input.classification,
+    });
+    const mintInput = {
+        projectRoot: input.projectRoot,
+        actor: input.actor ?? "operator",
+        operations: resolved.operations,
+        surfaces: resolved.surfaces,
+        expiresAt: resolved.expiresAt,
+        singleUse: input.singleUse === true,
+        planRef: input.planRef ?? null,
+        repo: input.repo ?? null,
+        branch: input.branch ?? null,
+        pinActive: input.pinActive,
+        eventRef: input.eventRef ?? `template:${resolved.template}`,
+        now: input.now,
+    };
+    return mintHumanOriginGrant(mintInput);
+}
+/**
+ * Mint a human-origin grant for the walk-away finish-loop template (#871).
+ * Covers edit/push/pr/merge only — never release-cut / release-publish / release-rollback.
+ * **Sole mint path:** mintHumanOriginGrant (operator-cli).
+ */
+export function mintFinishLoopTemplateGrant(input) {
+    const dualMint = assertNoIndependentSessionAuthMint();
+    if (dualMint.sessionAuthIsAuthority || dualMint.mintPath !== "mintHumanOriginGrant") {
+        throw new Error("finish-loop template mint refused: dual authorization SoT is forbidden (#871 / #1095)");
+    }
+    const resolved = resolveFinishLoopTemplate({
+        now: input.now,
+        expiresAt: input.expiresAt,
+        durationHours: input.durationHours,
+        surfaces: input.surfaces,
+    });
+    const mintInput = {
+        projectRoot: input.projectRoot,
+        actor: input.actor ?? "operator",
+        operations: resolved.operations,
+        surfaces: resolved.surfaces,
+        expiresAt: resolved.expiresAt,
+        singleUse: input.singleUse === true,
+        planRef: input.planRef ?? null,
+        repo: input.repo ?? null,
+        branch: input.branch ?? null,
+        storyIds: input.storyIds,
+        issueIds: input.issueIds,
+        cohortId: input.cohortId ?? null,
+        pinActive: input.pinActive,
+        eventRef: input.eventRef ?? `template:${FINISH_LOOP_TEMPLATE_NAME}`,
+        now: input.now,
+    };
+    return mintHumanOriginGrant(mintInput);
+}
+/**
+ * Dispatch AFK template mint by name. Closed-verb templates require target;
+ * finish-loop does not.
+ */
+export function mintAfkTemplateGrant(input) {
+    const name = input.template.trim().toLowerCase();
+    if (isFinishLoopTemplateName(name)) {
+        return mintFinishLoopTemplateGrant({
+            projectRoot: input.projectRoot,
+            actor: input.actor,
+            expiresAt: input.expiresAt,
+            singleUse: input.singleUse,
+            planRef: input.planRef,
+            repo: input.repo,
+            branch: input.branch,
+            surfaces: input.surfaces,
+            storyIds: input.storyIds,
+            issueIds: input.issueIds,
+            cohortId: input.cohortId,
+            now: input.now,
+            pinActive: input.pinActive,
+            eventRef: input.eventRef,
+            durationHours: input.durationHours,
+        });
+    }
+    if (!isClosedVerbTemplateName(name)) {
+        throw new Error(`unknown AFK template '${input.template}'; expected one of: ${AFK_TEMPLATE_NAMES.join(", ")}`);
+    }
+    if (input.target === null || input.target === undefined || input.target.trim().length === 0) {
+        throw new Error(`template ${name} requires a non-empty --target`);
+    }
+    return mintClosedVerbTemplateGrant({
+        projectRoot: input.projectRoot,
+        template: name,
+        target: input.target,
+        actor: input.actor,
+        expiresAt: input.expiresAt,
+        singleUse: input.singleUse,
+        planRef: input.planRef,
+        repo: input.repo,
+        branch: input.branch,
+        now: input.now,
+        classification: input.classification,
+        pinActive: input.pinActive,
+        eventRef: input.eventRef,
+    });
+}
+/**
+ * Assert that authorization for closed verbs must not use an independent
+ * session-auth mint engine. Used by unit tests as a dual-mint guard.
+ */
+export function assertNoIndependentSessionAuthMint() {
+    return {
+        mintPath: "mintHumanOriginGrant",
+        sessionAuthIsAuthority: false,
+    };
+}
+//# sourceMappingURL=templates.js.map

package/dist/authz/types.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Human-origin approval grants + UAT mutation lease (#2944 Wave 1 / #2948 L1–L2).
+ *
+ * Threat model (aligned agent, not malice): lifecycle/xBRIEF/dispatch tokens the
+ * agent authors must not independently satisfy implementation-approval gates.
+ * Local-file forgery by a credential-compromised agent remains #983-class OOS.
+ */
+/** Operation classes bound on a grant (Wave 1 structural binding + Wave 4 closed verbs). */
+export declare const AUTHZ_OPERATIONS: readonly ["edit", "push", "pr", "merge", "settings", "deployment", "issue_mutation", "release-cut", "release-publish", "release-rollback"];
+export type AuthzOperation = (typeof AUTHZ_OPERATIONS)[number];
+/**
+ * Human-origin kinds accepted as approval provenance.
+ * Agent-minted / self-asserted kinds are rejected by the gate.
+ */
+export declare const HUMAN_ORIGIN_KINDS: readonly ["operator-cli", "operator-session", "human-event"];
+export type HumanOriginKind = (typeof HUMAN_ORIGIN_KINDS)[number];
+/** Origin kinds that NEVER satisfy an implementation-approval gate. */
+export declare const REJECTED_ORIGIN_KINDS: readonly ["agent-lifecycle", "xbrief-status", "dispatch-envelope", "allocation-context", "self-asserted", "agent-authored"];
+export type RejectedOriginKind = (typeof REJECTED_ORIGIN_KINDS)[number];
+export interface GrantOrigin {
+    readonly kind: string;
+    readonly actor: string;
+    readonly mintedAt: string;
+    readonly mintedVia: string;
+    /** Optional external human event ref (issue comment URL, plan:approved id, …). */
+    readonly eventRef: string | null;
+}
+export interface GrantScope {
+    /** Immutable plan id or content hash string (structural; not crypto HMAC). */
+    readonly planRef: string | null;
+    readonly repo: string | null;
+    readonly branch: string | null;
+    readonly worktree: string | null;
+    /** Path globs for permitted file/product surfaces (incl. user-visible UI). */
+    readonly surfaces: readonly string[];
+    readonly operations: readonly AuthzOperation[];
+    readonly storyIds: readonly string[];
+    readonly issueIds: readonly number[];
+    /**
+     * Named fix cohort under an active UAT lease. Required when UAT is active
+     * for product mutations; approving one cohort does not clear UAT.
+     */
+    readonly cohortId: string | null;
+}
+export interface GrantSemantics {
+    readonly expiresAt: string | null;
+    readonly singleUse: boolean;
+    readonly usedAt: string | null;
+    readonly revokedAt: string | null;
+}
+export interface HumanOriginGrant {
+    readonly schemaVersion: 1;
+    readonly id: string;
+    readonly origin: GrantOrigin;
+    readonly scope: GrantScope;
+    readonly semantics: GrantSemantics;
+}
+export interface UatLease {
+    readonly active: boolean;
+    readonly campaignId: string;
+    readonly startedAt: string;
+    readonly startedBy: GrantOrigin;
+    readonly suspendedAt: string | null;
+    readonly note: string | null;
+}
+export interface AuthzState {
+    readonly schemaVersion: 1;
+    readonly uat: UatLease | null;
+    /** Optional pin of grant ids considered active (empty = all non-revoked on disk). */
+    readonly activeGrantIds: readonly string[];
+}
+export type AuthzDecisionCode = "authz-allow" | "authz-inactive" | "authz-uat-deny" | "authz-grant-missing" | "authz-grant-origin-reject" | "authz-grant-scope-deny" | "authz-grant-expired" | "authz-grant-revoked" | "authz-grant-single-use-spent";
+/** Structured codes for release-class closed-verb gates (#1095 Wave 4). */
+export type ClosedVerbDecisionCode = "closed-verb-allow" | "closed-verb-env-bypass" | "closed-verb-deny-missing" | "closed-verb-deny-origin" | "closed-verb-deny-scope" | "closed-verb-deny-expired" | "closed-verb-deny-revoked" | "closed-verb-deny-spent" | "closed-verb-unknown";
+export interface ClosedVerbDecision {
+    readonly allowed: boolean;
+    readonly code: ClosedVerbDecisionCode;
+    readonly reason: string;
+    readonly verb: string;
+    readonly target: string | null;
+    readonly humanApprovalRef: string | null;
+    readonly envBypassKey: string | null;
+    readonly skillPointer: string | null;
+}
+export interface AuthzDecision {
+    readonly allowed: boolean;
+    readonly code: AuthzDecisionCode;
+    readonly reason: string;
+    readonly humanApprovalRef: string | null;
+    readonly approvedScope: GrantScope | null;
+    readonly attemptedOp: AuthzOperation | "test" | "evidence" | "unknown";
+    readonly path: string | null;
+}
+export interface AuthzAuditRecord {
+    readonly schemaVersion: 1;
+    readonly ts: string;
+    readonly humanApprovalRef: string | null;
+    readonly approvedScope: GrantScope | null;
+    readonly attemptedOp: string;
+    readonly path: string | null;
+    readonly result: "allow" | "deny";
+    readonly code: AuthzDecisionCode;
+    readonly message: string;
+    readonly campaignId: string | null;
+}
+export declare const AUTHZ_SCHEMA_VERSION: 1;
+export declare const AUTHZ_DIR = ".deft/authz";
+export declare const AUTHZ_STATE_FILE = "state.json";
+export declare const AUTHZ_GRANTS_DIR = "grants";
+export declare const AUTHZ_AUDIT_FILE = "audit.jsonl";
+//# sourceMappingURL=types.d.ts.map

package/dist/authz/types.js

@@ -0,0 +1,41 @@
+/**
+ * Human-origin approval grants + UAT mutation lease (#2944 Wave 1 / #2948 L1–L2).
+ *
+ * Threat model (aligned agent, not malice): lifecycle/xBRIEF/dispatch tokens the
+ * agent authors must not independently satisfy implementation-approval gates.
+ * Local-file forgery by a credential-compromised agent remains #983-class OOS.
+ */
+/** Operation classes bound on a grant (Wave 1 structural binding + Wave 4 closed verbs). */
+export const AUTHZ_OPERATIONS = [
+    "edit",
+    "push",
+    "pr",
+    "merge",
+    "settings",
+    "deployment",
+    "issue_mutation",
+    /** Release-class closed verbs (#1095 Wave 4) — also satisfied by `deployment`. */
+    "release-cut",
+    "release-publish",
+    "release-rollback",
+];
+/**
+ * Human-origin kinds accepted as approval provenance.
+ * Agent-minted / self-asserted kinds are rejected by the gate.
+ */
+export const HUMAN_ORIGIN_KINDS = ["operator-cli", "operator-session", "human-event"];
+/** Origin kinds that NEVER satisfy an implementation-approval gate. */
+export const REJECTED_ORIGIN_KINDS = [
+    "agent-lifecycle",
+    "xbrief-status",
+    "dispatch-envelope",
+    "allocation-context",
+    "self-asserted",
+    "agent-authored",
+];
+export const AUTHZ_SCHEMA_VERSION = 1;
+export const AUTHZ_DIR = ".deft/authz";
+export const AUTHZ_STATE_FILE = "state.json";
+export const AUTHZ_GRANTS_DIR = "grants";
+export const AUTHZ_AUDIT_FILE = "audit.jsonl";
+//# sourceMappingURL=types.js.map

package/dist/authz/verb-classification.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Verb classification table loader + schema validation (#1095 Wave 4).
+ * SoT file: conventions/verb-classification.json (repo root).
+ */
+export declare const IRREVERSIBILITY_VALUES: readonly ["reversible-via-git-revert", "reversible-via-release-rollback", "destructive", "reversible"];
+export type Irreversibility = (typeof IRREVERSIBILITY_VALUES)[number];
+export interface VerbClassificationRow {
+    readonly closure_set: readonly string[];
+    readonly explicit_required: readonly string[];
+    readonly irreversibility: string;
+    readonly wildcard_allowed: boolean;
+    readonly recurring_allowed: boolean;
+    readonly default_expiry: string;
+    readonly skill: string;
+    readonly phase: string;
+    /** AuthzOperation names that satisfy this closed verb (Wave 1 grant ops). */
+    readonly authz_operations: readonly string[];
+    /** Ephemeral env bypass key, e.g. DEFT_ALLOW_RELEASE_PUBLISH. */
+    readonly env_bypass: string;
+}
+export interface VerbClassificationTable {
+    readonly schemaVersion: number;
+    readonly description?: string;
+    readonly verbs: Readonly<Record<string, VerbClassificationRow>>;
+}
+export declare class VerbClassificationError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Validate and normalise a raw JSON payload into a VerbClassificationTable.
+ * Throws VerbClassificationError on schema violations.
+ */
+export declare function parseVerbClassification(raw: unknown): VerbClassificationTable;
+/** Built-in Wave 4/5 rows used when the file is unavailable (tests / install). */
+export declare function builtinReleaseVerbClassification(): VerbClassificationTable;
+/**
+ * Resolve conventions/verb-classification.json relative to a project root, then
+ * walk up from this module for framework source layouts.
+ */
+export declare function resolveVerbClassificationPath(projectRoot?: string | null): string | null;
+export declare function loadVerbClassification(projectRoot?: string | null): VerbClassificationTable;
+export declare function getVerbRow(table: VerbClassificationTable, verb: string): VerbClassificationRow | null;
+//# sourceMappingURL=verb-classification.d.ts.map

package/dist/authz/verb-classification.js

@@ -0,0 +1,237 @@
+/**
+ * Verb classification table loader + schema validation (#1095 Wave 4).
+ * SoT file: conventions/verb-classification.json (repo root).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+export const IRREVERSIBILITY_VALUES = [
+    "reversible-via-git-revert",
+    "reversible-via-release-rollback",
+    "destructive",
+    "reversible",
+];
+export class VerbClassificationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "VerbClassificationError";
+        this.code = code;
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function asStringArray(raw, field) {
+    if (!Array.isArray(raw)) {
+        throw new VerbClassificationError("verb-class-schema", `${field} must be an array of strings`);
+    }
+    const out = [];
+    for (const item of raw) {
+        if (typeof item !== "string" || item.trim().length === 0) {
+            throw new VerbClassificationError("verb-class-schema", `${field} entries must be non-empty strings`);
+        }
+        out.push(item.trim());
+    }
+    return out;
+}
+function parseRow(name, raw) {
+    if (!isRecord(raw)) {
+        throw new VerbClassificationError("verb-class-schema", `verb '${name}' must be an object`);
+    }
+    const irreversibility = raw.irreversibility;
+    if (typeof irreversibility !== "string" || irreversibility.trim().length === 0) {
+        throw new VerbClassificationError("verb-class-schema", `verb '${name}' requires irreversibility string`);
+    }
+    if (typeof raw.wildcard_allowed !== "boolean") {
+        throw new VerbClassificationError("verb-class-schema", `verb '${name}' requires wildcard_allowed boolean`);
+    }
+    if (typeof raw.recurring_allowed !== "boolean") {
+        throw new VerbClassificationError("verb-class-schema", `verb '${name}' requires recurring_allowed boolean`);
+    }
+    if (typeof raw.default_expiry !== "string" || raw.default_expiry.trim().length === 0) {
+        throw new VerbClassificationError("verb-class-schema", `verb '${name}' requires default_expiry string`);
+    }
+    if (typeof raw.skill !== "string" || raw.skill.trim().length === 0) {
+        throw new VerbClassificationError("verb-class-schema", `verb '${name}' requires skill string`);
+    }
+    if (typeof raw.phase !== "string" || raw.phase.trim().length === 0) {
+        throw new VerbClassificationError("verb-class-schema", `verb '${name}' requires phase string`);
+    }
+    if (typeof raw.env_bypass !== "string" || !raw.env_bypass.startsWith("DEFT_ALLOW_")) {
+        throw new VerbClassificationError("verb-class-schema", `verb '${name}' requires env_bypass starting with DEFT_ALLOW_`);
+    }
+    const ops = asStringArray(raw.authz_operations, `${name}.authz_operations`);
+    if (ops.length === 0) {
+        throw new VerbClassificationError("verb-class-schema", `verb '${name}' authz_operations must be non-empty`);
+    }
+    if (raw.wildcard_allowed === true) {
+        throw new VerbClassificationError("verb-class-policy", `verb '${name}' must set wildcard_allowed=false for Wave 4 release-class closed verbs`);
+    }
+    return {
+        closure_set: asStringArray(raw.closure_set, `${name}.closure_set`),
+        explicit_required: asStringArray(raw.explicit_required, `${name}.explicit_required`),
+        irreversibility: irreversibility.trim(),
+        wildcard_allowed: false,
+        recurring_allowed: raw.recurring_allowed,
+        default_expiry: raw.default_expiry.trim(),
+        skill: raw.skill.trim(),
+        phase: raw.phase.trim(),
+        authz_operations: ops,
+        env_bypass: raw.env_bypass.trim(),
+    };
+}
+/**
+ * Validate and normalise a raw JSON payload into a VerbClassificationTable.
+ * Throws VerbClassificationError on schema violations.
+ */
+export function parseVerbClassification(raw) {
+    if (!isRecord(raw)) {
+        throw new VerbClassificationError("verb-class-schema", "root must be an object");
+    }
+    const schemaVersion = raw.schemaVersion;
+    if (typeof schemaVersion !== "number" || !Number.isInteger(schemaVersion) || schemaVersion < 1) {
+        throw new VerbClassificationError("verb-class-schema", "schemaVersion must be a positive integer");
+    }
+    if (!isRecord(raw.verbs)) {
+        throw new VerbClassificationError("verb-class-schema", "verbs must be an object");
+    }
+    const verbs = {};
+    for (const [name, row] of Object.entries(raw.verbs)) {
+        if (name.trim().length === 0) {
+            throw new VerbClassificationError("verb-class-schema", "verb name must be non-empty");
+        }
+        verbs[name.trim()] = parseRow(name.trim(), row);
+    }
+    if (Object.keys(verbs).length === 0) {
+        throw new VerbClassificationError("verb-class-schema", "verbs must include at least one row");
+    }
+    return {
+        schemaVersion,
+        description: typeof raw.description === "string" ? raw.description : undefined,
+        verbs,
+    };
+}
+/** Built-in Wave 4/5 rows used when the file is unavailable (tests / install). */
+export function builtinReleaseVerbClassification() {
+    return parseVerbClassification({
+        schemaVersion: 1,
+        description: "builtin release-class + finish-loop closed verbs (#1095 / #871)",
+        verbs: {
+            "release-cut": {
+                closure_set: [
+                    "changelog-promote",
+                    "roadmap-render",
+                    "tag-create",
+                    "tag-push",
+                    "gh-release-create-draft",
+                ],
+                explicit_required: ["release-publish", "release-rollback"],
+                irreversibility: "reversible-via-release-rollback",
+                wildcard_allowed: false,
+                recurring_allowed: false,
+                default_expiry: "4h",
+                skill: "content/skills/deft-directive-release/SKILL.md",
+                phase: "Phase 4",
+                authz_operations: ["release-cut", "deployment"],
+                env_bypass: "DEFT_ALLOW_RELEASE_CUT",
+            },
+            "release-publish": {
+                closure_set: [],
+                explicit_required: [],
+                irreversibility: "destructive",
+                wildcard_allowed: false,
+                recurring_allowed: false,
+                default_expiry: "1h",
+                skill: "content/skills/deft-directive-release/SKILL.md",
+                phase: "Phase 5",
+                authz_operations: ["release-publish", "deployment"],
+                env_bypass: "DEFT_ALLOW_RELEASE_PUBLISH",
+            },
+            "release-rollback": {
+                closure_set: [],
+                explicit_required: [],
+                irreversibility: "destructive",
+                wildcard_allowed: false,
+                recurring_allowed: false,
+                default_expiry: "1h",
+                skill: "content/skills/deft-directive-release/SKILL.md",
+                phase: "Phase 7",
+                authz_operations: ["release-rollback", "deployment"],
+                env_bypass: "DEFT_ALLOW_RELEASE_ROLLBACK",
+            },
+            "finish-loop": {
+                closure_set: [
+                    "edit",
+                    "push",
+                    "pr",
+                    "merge",
+                    "pr-watch",
+                    "pr-finish-loop",
+                    "directive-finish-loop",
+                ],
+                explicit_required: ["release-cut", "release-publish", "release-rollback"],
+                irreversibility: "reversible-via-git-revert",
+                wildcard_allowed: false,
+                recurring_allowed: true,
+                default_expiry: "8h",
+                skill: "content/contracts/finish-loop.md",
+                phase: "walk-away",
+                authz_operations: ["edit", "push", "pr", "merge"],
+                env_bypass: "DEFT_ALLOW_FINISH_LOOP",
+            },
+        },
+    });
+}
+/**
+ * Resolve conventions/verb-classification.json relative to a project root, then
+ * walk up from this module for framework source layouts.
+ */
+export function resolveVerbClassificationPath(projectRoot) {
+    const candidates = [];
+    if (projectRoot !== null && projectRoot !== undefined && projectRoot.trim().length > 0) {
+        candidates.push(resolve(projectRoot, "conventions", "verb-classification.json"));
+    }
+    // packages/core/src/authz → repo root: ../../../../conventions
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        candidates.push(resolve(here, "..", "..", "..", "..", "conventions", "verb-classification.json"));
+        candidates.push(resolve(here, "..", "..", "..", "conventions", "verb-classification.json"));
+    }
+    catch {
+        // ignore import.meta failures in non-ESM test shims
+    }
+    candidates.push(join(process.cwd(), "conventions", "verb-classification.json"));
+    for (const p of candidates) {
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+export function loadVerbClassification(projectRoot) {
+    const path = resolveVerbClassificationPath(projectRoot);
+    if (path === null) {
+        return builtinReleaseVerbClassification();
+    }
+    const text = readFileSync(path, "utf8");
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (err) {
+        throw new VerbClassificationError("verb-class-parse", `failed to parse ${path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return parseVerbClassification(raw);
+}
+export function getVerbRow(table, verb) {
+    const key = verb.trim().toLowerCase();
+    const direct = table.verbs[key];
+    if (direct !== undefined)
+        return direct;
+    for (const [name, row] of Object.entries(table.verbs)) {
+        if (name.toLowerCase() === key)
+            return row;
+    }
+    return null;
+}
+//# sourceMappingURL=verb-classification.js.map