@deftai/directive-core 0.55.0

package/dist/policy/capacity.d.ts

@@ -0,0 +1,45 @@
+export declare const DEFAULT_CAPACITY_UNIT = "vbrief-count";
+export declare const CAPACITY_UNIT_COST = "cost";
+export declare const CAPACITY_UNITS: Set<string>;
+export declare const DEFAULT_CAPACITY_WINDOW_DAYS = 30;
+export declare const DEFAULT_CAPACITY_ENFORCEMENT = "advise";
+export declare const CAPACITY_ENFORCEMENTS: Set<string>;
+export declare const DEFAULT_CAPACITY_MIN_SAMPLE_SIZE = 20;
+export declare const DEFAULT_EPIC_ESTIMATE = 3;
+export declare const DEFAULT_EPIC_STALENESS_DAYS = 30;
+export declare const CAPACITY_TARGET_SUM_TOLERANCE = 0.000001;
+export interface CapacityBucket {
+    readonly bucket_id: string;
+    readonly target: number;
+}
+export interface CapacityAllocation {
+    readonly unit: string;
+    readonly window_days: number;
+    readonly enforcement: string;
+    readonly min_sample_size: number;
+    readonly buckets: readonly CapacityBucket[];
+    readonly default_bucket: string;
+    readonly default_epic_estimate: number;
+    readonly epic_staleness_days: number;
+    readonly source: "typed" | "default" | "default-on-error";
+    readonly error: string | null;
+    readonly configured: boolean;
+}
+/** Validate a plan.policy.capacityAllocation payload. */
+export declare function validateCapacityAllocation(value: unknown): string[];
+/** Resolve plan.policy.capacityAllocation from PROJECT-DEFINITION. */
+export declare function resolveCapacityAllocation(projectRoot: string): CapacityAllocation;
+export interface BucketMatcher {
+    readonly bucket_id: string;
+    readonly labels: ReadonlySet<string>;
+}
+/** Return ordered matchers + default_bucket from PROJECT-DEFINITION raw match.labels. */
+export declare function loadBucketMatchers(projectRoot: string): {
+    matchers: BucketMatcher[];
+    default_bucket: string;
+};
+export declare const SOURCE_MATCH = "match";
+export declare const SOURCE_DEFAULT = "default";
+/** Return (bucket_id, source) for an issue's label set. */
+export declare function classifyBucket(issueLabels: ReadonlySet<string>, matchers: readonly BucketMatcher[], defaultBucket: string): [string, string];
+//# sourceMappingURL=capacity.d.ts.map

package/dist/policy/capacity.js

@@ -0,0 +1,251 @@
+import { loadProjectDefinition } from "../policy/resolve.js";
+export const DEFAULT_CAPACITY_UNIT = "vbrief-count";
+export const CAPACITY_UNIT_COST = "cost";
+export const CAPACITY_UNITS = new Set([DEFAULT_CAPACITY_UNIT, CAPACITY_UNIT_COST]);
+export const DEFAULT_CAPACITY_WINDOW_DAYS = 30;
+export const DEFAULT_CAPACITY_ENFORCEMENT = "advise";
+export const CAPACITY_ENFORCEMENTS = new Set(["advise", "enforce"]);
+export const DEFAULT_CAPACITY_MIN_SAMPLE_SIZE = 20;
+export const DEFAULT_EPIC_ESTIMATE = 3;
+export const DEFAULT_EPIC_STALENESS_DAYS = 30;
+export const CAPACITY_TARGET_SUM_TOLERANCE = 1e-6;
+function isNumber(value) {
+    return typeof value === "number" && !Number.isNaN(value) && typeof value !== "boolean";
+}
+function isPositiveInt(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+function defaultCapacityAllocation(source, error = null) {
+    return {
+        unit: DEFAULT_CAPACITY_UNIT,
+        window_days: DEFAULT_CAPACITY_WINDOW_DAYS,
+        enforcement: DEFAULT_CAPACITY_ENFORCEMENT,
+        min_sample_size: DEFAULT_CAPACITY_MIN_SAMPLE_SIZE,
+        buckets: [],
+        default_bucket: "",
+        default_epic_estimate: DEFAULT_EPIC_ESTIMATE,
+        epic_staleness_days: DEFAULT_EPIC_STALENESS_DAYS,
+        source,
+        error,
+        configured: false,
+    };
+}
+function validateCapacityBuckets(value) {
+    const errors = [];
+    const buckets = value.buckets;
+    if (!Array.isArray(buckets) || buckets.length === 0) {
+        errors.push("plan.policy.capacityAllocation.buckets must be a non-empty array");
+        return errors;
+    }
+    const ids = [];
+    let total = 0;
+    for (let idx = 0; idx < buckets.length; idx += 1) {
+        const bucket = buckets[idx];
+        if (typeof bucket !== "object" || bucket === null || Array.isArray(bucket)) {
+            errors.push(`plan.policy.capacityAllocation.buckets[${idx}] must be an object`);
+            continue;
+        }
+        const rec = bucket;
+        const bucketId = rec.id;
+        if (typeof bucketId !== "string" || bucketId.trim().length === 0) {
+            errors.push(`plan.policy.capacityAllocation.buckets[${idx}].id must be a non-empty string`);
+        }
+        else {
+            ids.push(bucketId);
+        }
+        const target = rec.target;
+        if (!isNumber(target)) {
+            errors.push(`plan.policy.capacityAllocation.buckets[${idx}].target must be a number; got ${String(target)}`);
+        }
+        else if (Number(target) < 0 || Number(target) > 1) {
+            errors.push(`plan.policy.capacityAllocation.buckets[${idx}].target must be between 0.0 and 1.0; got ${String(target)}`);
+        }
+        else {
+            total += Number(target);
+        }
+    }
+    const duplicates = [...new Set(ids.filter((id, i) => ids.indexOf(id) !== i))].sort();
+    if (duplicates.length > 0) {
+        errors.push(`plan.policy.capacityAllocation.buckets ids must be unique; duplicates: ${JSON.stringify(duplicates)}`);
+    }
+    if (ids.length > 0 && Math.abs(total - 1.0) > CAPACITY_TARGET_SUM_TOLERANCE) {
+        errors.push(`plan.policy.capacityAllocation.buckets targets must sum to 1.0; got ${total.toFixed(6)}`);
+    }
+    const defaultBucket = value.defaultBucket;
+    if (defaultBucket !== undefined && defaultBucket !== null) {
+        if (typeof defaultBucket !== "string") {
+            errors.push("plan.policy.capacityAllocation.defaultBucket must be a string");
+        }
+        else if (!ids.includes(defaultBucket)) {
+            errors.push(`plan.policy.capacityAllocation.defaultBucket '${defaultBucket}' must match a declared bucket id`);
+        }
+    }
+    return errors;
+}
+/** Validate a plan.policy.capacityAllocation payload. */
+export function validateCapacityAllocation(value) {
+    if (value === null || value === undefined) {
+        return [];
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        return [
+            `plan.policy.capacityAllocation must be an object; got ${typeof value} (${String(value)})`,
+        ];
+    }
+    const rec = value;
+    const errors = [];
+    const unit = rec.unit ?? DEFAULT_CAPACITY_UNIT;
+    if (typeof unit !== "string" || !CAPACITY_UNITS.has(unit)) {
+        errors.push(`plan.policy.capacityAllocation.unit must be one of ${JSON.stringify([...CAPACITY_UNITS].sort())}; got ${String(unit)}`);
+    }
+    const enforcement = rec.enforcement ?? DEFAULT_CAPACITY_ENFORCEMENT;
+    if (typeof enforcement !== "string" || !CAPACITY_ENFORCEMENTS.has(enforcement)) {
+        errors.push(`plan.policy.capacityAllocation.enforcement must be one of ${JSON.stringify([...CAPACITY_ENFORCEMENTS].sort())}; got ${String(enforcement)}`);
+    }
+    if (!("window" in rec)) {
+        errors.push("plan.policy.capacityAllocation.window is required (trailing accounting window in days)");
+    }
+    else if (!isPositiveInt(rec.window)) {
+        errors.push(`plan.policy.capacityAllocation.window must be a positive integer (days); got ${String(rec.window)}`);
+    }
+    if ("minSampleSize" in rec) {
+        const mss = rec.minSampleSize;
+        if (typeof mss !== "number" || !Number.isInteger(mss) || mss < 0) {
+            errors.push(`plan.policy.capacityAllocation.minSampleSize must be a non-negative integer; got ${String(mss)}`);
+        }
+    }
+    if ("defaultEpicEstimate" in rec && !isPositiveInt(rec.defaultEpicEstimate)) {
+        errors.push(`plan.policy.capacityAllocation.defaultEpicEstimate must be a positive integer; got ${String(rec.defaultEpicEstimate)}`);
+    }
+    if ("epicStalenessDays" in rec && !isPositiveInt(rec.epicStalenessDays)) {
+        errors.push(`plan.policy.capacityAllocation.epicStalenessDays must be a positive integer; got ${String(rec.epicStalenessDays)}`);
+    }
+    errors.push(...validateCapacityBuckets(rec));
+    return errors;
+}
+function getPolicyBlock(data) {
+    const plan = data.plan;
+    if (typeof plan === "object" && plan !== null && !Array.isArray(plan)) {
+        const policy = plan.policy;
+        if (typeof policy === "object" && policy !== null && !Array.isArray(policy)) {
+            return policy;
+        }
+    }
+    return {};
+}
+/** Resolve plan.policy.capacityAllocation from PROJECT-DEFINITION. */
+export function resolveCapacityAllocation(projectRoot) {
+    const [data, err] = loadProjectDefinition(projectRoot);
+    if (data === null) {
+        return defaultCapacityAllocation("default", err);
+    }
+    const policyBlock = getPolicyBlock(data);
+    if (!("capacityAllocation" in policyBlock)) {
+        return defaultCapacityAllocation("default");
+    }
+    const raw = policyBlock.capacityAllocation;
+    const validationErrors = validateCapacityAllocation(raw);
+    if (validationErrors.length > 0 ||
+        typeof raw !== "object" ||
+        raw === null ||
+        Array.isArray(raw)) {
+        return defaultCapacityAllocation("default-on-error", validationErrors[0] ?? "capacityAllocation must be an object");
+    }
+    const rec = raw;
+    const bucketsRaw = rec.buckets;
+    const buckets = [];
+    if (Array.isArray(bucketsRaw)) {
+        for (const bucket of bucketsRaw) {
+            if (typeof bucket === "object" && bucket !== null && !Array.isArray(bucket)) {
+                const b = bucket;
+                if (typeof b.id === "string" && isNumber(b.target)) {
+                    buckets.push({ bucket_id: b.id, target: Number(b.target) });
+                }
+            }
+        }
+    }
+    const defaultBucket = typeof rec.defaultBucket === "string" ? rec.defaultBucket : "";
+    return {
+        unit: typeof rec.unit === "string" ? rec.unit : DEFAULT_CAPACITY_UNIT,
+        window_days: Number(rec.window),
+        enforcement: typeof rec.enforcement === "string" ? rec.enforcement : DEFAULT_CAPACITY_ENFORCEMENT,
+        min_sample_size: typeof rec.minSampleSize === "number" && Number.isInteger(rec.minSampleSize)
+            ? rec.minSampleSize
+            : DEFAULT_CAPACITY_MIN_SAMPLE_SIZE,
+        buckets,
+        default_bucket: defaultBucket,
+        default_epic_estimate: typeof rec.defaultEpicEstimate === "number" && Number.isInteger(rec.defaultEpicEstimate)
+            ? rec.defaultEpicEstimate
+            : DEFAULT_EPIC_ESTIMATE,
+        epic_staleness_days: typeof rec.epicStalenessDays === "number" && Number.isInteger(rec.epicStalenessDays)
+            ? rec.epicStalenessDays
+            : DEFAULT_EPIC_STALENESS_DAYS,
+        source: "typed",
+        error: null,
+        configured: buckets.length > 0,
+    };
+}
+/** Return ordered matchers + default_bucket from PROJECT-DEFINITION raw match.labels. */
+export function loadBucketMatchers(projectRoot) {
+    const [data] = loadProjectDefinition(projectRoot);
+    const matchers = [];
+    if (data === null) {
+        return { matchers, default_bucket: "" };
+    }
+    const policyBlock = getPolicyBlock(data);
+    const cap = policyBlock.capacityAllocation;
+    if (typeof cap !== "object" || cap === null || Array.isArray(cap)) {
+        return { matchers, default_bucket: "" };
+    }
+    const rec = cap;
+    const buckets = rec.buckets;
+    if (Array.isArray(buckets)) {
+        for (const bucket of buckets) {
+            if (typeof bucket !== "object" || bucket === null || Array.isArray(bucket)) {
+                continue;
+            }
+            const b = bucket;
+            const bucketId = b.id;
+            if (typeof bucketId !== "string" || bucketId.trim().length === 0) {
+                continue;
+            }
+            matchers.push({
+                bucket_id: bucketId.trim(),
+                labels: new Set(matchLabels(b.match)),
+            });
+        }
+    }
+    const defaultBucket = rec.defaultBucket;
+    return {
+        matchers,
+        default_bucket: typeof defaultBucket === "string" ? defaultBucket : "",
+    };
+}
+function matchLabels(match) {
+    if (typeof match !== "object" || match === null || Array.isArray(match)) {
+        return [];
+    }
+    const labels = match.labels;
+    if (typeof labels !== "object" || labels === null || Array.isArray(labels)) {
+        return [];
+    }
+    const anyOf = labels["any-of"];
+    if (!Array.isArray(anyOf)) {
+        return [];
+    }
+    return anyOf.filter((x) => typeof x === "string" && x.length > 0);
+}
+export const SOURCE_MATCH = "match";
+export const SOURCE_DEFAULT = "default";
+/** Return (bucket_id, source) for an issue's label set. */
+export function classifyBucket(issueLabels, matchers, defaultBucket) {
+    for (const matcher of matchers) {
+        for (const label of matcher.labels) {
+            if (issueLabels.has(label)) {
+                return [matcher.bucket_id, SOURCE_MATCH];
+            }
+        }
+    }
+    return [defaultBucket, SOURCE_DEFAULT];
+}
+//# sourceMappingURL=capacity.js.map

package/dist/policy/decisions.d.ts

@@ -0,0 +1,26 @@
+export declare const PENDING_DECISIONS_AUDIT_DIR_REL = "vbrief/.audit";
+export declare const PENDING_DECISIONS_LOG_NAME = "pending-human-decisions.jsonl";
+export declare const DECISION_STATUS_PENDING = "pending";
+export declare const DECISION_STATUS_RESOLVED = "resolved";
+export declare const DEFAULT_PENDING_DECISIONS_THRESHOLD = 5;
+export interface DecisionBacklog {
+    readonly pending_count: number;
+    readonly by_kind: Readonly<Record<string, number>>;
+    readonly resolved_in_window: number;
+    readonly override_count: number;
+    readonly p0_reversal_in_window: boolean;
+    readonly override_rate: number;
+}
+export declare function pendingDecisionsLogPath(projectRoot: string): string;
+/** Return every well-formed decision event in insertion order. */
+export declare function readDecisionEvents(projectRoot: string, logPath?: string): Record<string, unknown>[];
+export interface SummarizeDecisionBacklogOptions {
+    readonly now?: Date;
+    readonly window_days?: number;
+    readonly events?: readonly Record<string, unknown>[];
+}
+/** Summarise the pending-decisions log into a DecisionBacklog. */
+export declare function summarizeDecisionBacklog(projectRoot: string, options?: SummarizeDecisionBacklogOptions): DecisionBacklog;
+/** Return the Tier-1 backlog nudge string, or empty when at/under threshold. */
+export declare function pendingDecisionsNudgeLine(count: number, threshold?: number): string;
+//# sourceMappingURL=decisions.d.ts.map

package/dist/policy/decisions.js

@@ -0,0 +1,114 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+export const PENDING_DECISIONS_AUDIT_DIR_REL = "vbrief/.audit";
+export const PENDING_DECISIONS_LOG_NAME = "pending-human-decisions.jsonl";
+export const DECISION_STATUS_PENDING = "pending";
+export const DECISION_STATUS_RESOLVED = "resolved";
+export const DEFAULT_PENDING_DECISIONS_THRESHOLD = 5;
+export function pendingDecisionsLogPath(projectRoot) {
+    return join(resolve(projectRoot), PENDING_DECISIONS_AUDIT_DIR_REL, PENDING_DECISIONS_LOG_NAME);
+}
+function parseIsoTs(value) {
+    if (typeof value !== "string" || value.length === 0) {
+        return null;
+    }
+    const text = value.replace("Z", "+00:00");
+    const parsed = new Date(text);
+    if (Number.isNaN(parsed.getTime())) {
+        return null;
+    }
+    return parsed;
+}
+/** Return every well-formed decision event in insertion order. */
+export function readDecisionEvents(projectRoot, logPath) {
+    const path = logPath ?? pendingDecisionsLogPath(projectRoot);
+    if (!existsSync(path)) {
+        return [];
+    }
+    const out = [];
+    for (const raw of readFileSync(path, { encoding: "utf8" }).split("\n")) {
+        const stripped = raw.trim();
+        if (stripped.length === 0) {
+            continue;
+        }
+        try {
+            const obj = JSON.parse(stripped);
+            if (typeof obj === "object" && obj !== null && !Array.isArray(obj)) {
+                const rec = obj;
+                if (typeof rec.decision_id === "string") {
+                    out.push(rec);
+                }
+            }
+        }
+        catch {
+            // skip malformed lines
+        }
+    }
+    return out;
+}
+/** Summarise the pending-decisions log into a DecisionBacklog. */
+export function summarizeDecisionBacklog(projectRoot, options = {}) {
+    const records = options.events ?? readDecisionEvents(projectRoot);
+    const latest = new Map();
+    for (const event of records) {
+        const decisionId = event.decision_id;
+        if (typeof decisionId === "string" && decisionId.length > 0) {
+            latest.set(decisionId, event);
+        }
+    }
+    const byKind = {};
+    let pendingCount = 0;
+    for (const event of latest.values()) {
+        if (event.status === DECISION_STATUS_PENDING) {
+            pendingCount += 1;
+            const kind = typeof event.kind === "string" && event.kind.length > 0 ? event.kind : "unspecified";
+            byKind[kind] = (byKind[kind] ?? 0) + 1;
+        }
+    }
+    const nowDt = options.now ?? new Date();
+    let resolvedInWindow = 0;
+    let overrideCount = 0;
+    let p0Reversal = false;
+    const windowDays = options.window_days;
+    for (const event of latest.values()) {
+        if (event.status !== DECISION_STATUS_RESOLVED) {
+            continue;
+        }
+        if (windowDays !== undefined) {
+            const stamp = parseIsoTs(event.timestamp);
+            if (stamp === null) {
+                continue;
+            }
+            const ageDays = (nowDt.getTime() - stamp.getTime()) / (86400 * 1000);
+            if (ageDays < 0 || ageDays > windowDays) {
+                continue;
+            }
+        }
+        resolvedInWindow += 1;
+        if (event.override === true) {
+            overrideCount += 1;
+        }
+        if (event.p0_reversal === true) {
+            p0Reversal = true;
+        }
+    }
+    const overrideRate = resolvedInWindow > 0 ? overrideCount / resolvedInWindow : 0;
+    return {
+        pending_count: pendingCount,
+        by_kind: byKind,
+        resolved_in_window: resolvedInWindow,
+        override_count: overrideCount,
+        p0_reversal_in_window: p0Reversal,
+        override_rate: overrideRate,
+    };
+}
+/** Return the Tier-1 backlog nudge string, or empty when at/under threshold. */
+export function pendingDecisionsNudgeLine(count, threshold = DEFAULT_PENDING_DECISIONS_THRESHOLD) {
+    if (count <= threshold) {
+        return "";
+    }
+    return (`[TIER-1] pending human-clearance backlog: ${count} decision(s) ` +
+        `awaiting adjudication (> threshold ${threshold}). Tune wipCap to real ` +
+        "review throughput or clear the backlog before dispatching more work.");
+}
+//# sourceMappingURL=decisions.js.map

package/dist/policy/disclosure.d.ts

@@ -0,0 +1,4 @@
+import type { PolicyResult } from "./resolve.js";
+/** One-liner disclosure phrasing for AGENTS.md / setup interview echo. */
+export declare function disclosureLine(result: PolicyResult): string;
+//# sourceMappingURL=disclosure.d.ts.map

package/dist/policy/disclosure.js

@@ -0,0 +1,19 @@
+import { ENV_BYPASS } from "./resolve.js";
+/** One-liner disclosure phrasing for AGENTS.md / setup interview echo. */
+export function disclosureLine(result) {
+    if (result.allowDirectCommits) {
+        if (result.source === "env-bypass") {
+            return (`[deft policy] ${ENV_BYPASS} is set -- ` +
+                "branch-protection policy bypassed for this session.");
+        }
+        return ("[deft policy] Direct commits to the default branch are ENABLED " +
+            `(source: ${result.source}). Branch-protection policy is OFF.`);
+    }
+    if (result.error !== null) {
+        return ("[deft policy] Branch-protection policy is ON (fail-closed: " +
+            `${result.error}). Direct commits to the default branch are blocked.`);
+    }
+    return ("[deft policy] Branch-protection policy is ON. Direct commits to the " +
+        "default branch are blocked. Use a feature branch.");
+}
+//# sourceMappingURL=disclosure.js.map

package/dist/policy/index.d.ts

@@ -0,0 +1,43 @@
+export * from "./autonomy.js";
+export * from "./capacity.js";
+export * from "./decisions.js";
+export * from "./disclosure.js";
+export * from "./resolve.js";
+export * from "./wip.js";
+export declare const FIELD_ALLOW_DIRECT_COMMITS = "plan.policy.allowDirectCommitsToMaster";
+export declare const FIELD_WIP_CAP = "plan.policy.wipCap";
+export declare const FIELD_SESSION_RITUAL_STALENESS_HOURS = "plan.policy.sessionRitualStalenessHours";
+export declare const FIELD_TRIAGE_SCOPE = "plan.policy.triageScope";
+export declare const FIELD_TRIAGE_SCOPE_IGNORES = "plan.policy.triageScopeIgnores";
+export declare const FIELD_TRIAGE_RANKING_LABELS = "plan.policy.triageRankingLabels";
+export declare const FIELD_TRIAGE_AUTO_CLASSIFY = "plan.policy.triageAutoClassify";
+export declare const FIELD_TRIAGE_HOLD_MARKERS = "plan.policy.triageHoldMarkers";
+export declare const FIELD_SWARM_SUBAGENT_BACKEND = "plan.policy.swarmSubagentBackend";
+export declare const DEFAULT_SESSION_RITUAL_STALENESS_HOURS = 4;
+export declare const DEFAULT_TRIAGE_SCOPE_VALUE: readonly Record<string, unknown>[];
+export declare const DEFAULT_TRIAGE_SCOPE_IGNORES_VALUE: readonly unknown[];
+export declare const DEFAULT_TRIAGE_RANKING_LABELS_VALUE: readonly string[];
+export declare const DEFAULT_TRIAGE_AUTO_CLASSIFY_VALUE: readonly unknown[];
+export declare const KNOWN_SUBAGENT_BACKEND_IDS: Set<string>;
+export interface PolicyField {
+    readonly name: string;
+    readonly current: unknown;
+    readonly default: unknown;
+    readonly source: string;
+}
+/** Walk registered inspectors and return one row per field (#1148). */
+export declare function inspectAllPolicies(projectRoot: string): PolicyField[];
+/** Look up a single registered field by canonical dotted-path name. */
+export declare function inspectOnePolicy(name: string, projectRoot: string): PolicyField | null;
+/** Return canonical names of every registered typed-policy field. */
+export declare function registeredPolicyNames(): string[];
+export declare function fieldToDict(field: PolicyField): Record<string, unknown>;
+/** Render the JSON envelope {generated_at, fields: [...]}. */
+export declare function renderJson(fields: PolicyField[], now?: Date): string;
+/** Render the human-readable text format from the issue body. */
+export declare function renderText(fields: PolicyField[]): string;
+/** Python repr for a string (single-quoted). */
+export declare function pythonStringRepr(value: string): string;
+/** Python repr for a list of strings. */
+export declare function pythonListRepr(items: string[]): string;
+//# sourceMappingURL=index.d.ts.map