@deftai/directive-runtime 0.129.7 → 0.129.8

package/vendor/directive-core/dist/policy/small-change-lane.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Small-change lane under the rapid ceremony dial (#6204).
+ *
+ * One fail-closed evaluator next to the ceremony dial policy. A thin brief
+ * (see `intake/thin-brief.ts`) stays in the lane only while:
+ *   - the ceremony dial depth is `rapid`;
+ *   - the bound holds: `maxProductionFiles` / `maxChangedLines` from
+ *     `plan.policy.ceremonyDial.smallChangeLane`, each field falling back to
+ *     the shipped default (SMALL_CHANGE_LANE_DEFAULT_*) when unset. An invalid
+ *     policy value or an unreadable PROJECT-DEFINITION refuses;
+ *   - the measured cumulative product diff against the lane-admit base holds
+ *     the bound;
+ *   - the public-surface determination is `none`. `unknown` refuses.
+ *
+ * The measurement is git, never the provisional dial estimators
+ * (`estimateProvisionalCeremonyInputs`, task-size hints). Those are not proof.
+ *
+ * The gates that can refuse (xbrief:preflight, verify:ac, scope:complete) call
+ * `evaluateSmallChangeLaneGate`, so the bound is rechecked at each one.
+ *
+ * Lane exit: once the bound is crossed, every retry on that scope refuses until
+ * the brief is converted to the full shape (`escalateThinBriefToFullShape`).
+ * That conversion is scope-local. It is not the #3319 dial-depth raise
+ * (`escalateCeremonyDial`), which does not clear this refusal.
+ */
+import { type CeremonyDepth } from "./ceremony-dial.js";
+/** Policy field for the lane bound, nested under the ceremony dial policy. */
+export declare const FIELD_SMALL_CHANGE_LANE = "plan.policy.ceremonyDial.smallChangeLane";
+/** Plan metadata key that records lane membership and the lane-admit base. */
+export declare const SMALL_CHANGE_LANE_MARKER_KEY = "x-directive/smallChangeLane";
+/** Schema id of the lane marker. */
+export declare const SMALL_CHANGE_LANE_SCHEMA = "deft.small-change-lane.v1";
+/** The one remediation for every lane refusal: lane exit to the full brief shape. */
+export declare const SMALL_CHANGE_LANE_REMEDIATION: string;
+/** Default production-file cap when the policy field is unset (operator choice, #6204). */
+export declare const SMALL_CHANGE_LANE_DEFAULT_MAX_PRODUCTION_FILES = 5;
+/** Default changed-line cap (added + deleted, tests included) when the policy field is unset. */
+export declare const SMALL_CHANGE_LANE_DEFAULT_MAX_CHANGED_LINES = 500;
+/** Lane bound. Policy overrides each field; unset fields use the shipped defaults. */
+export interface SmallChangeLaneBound {
+    readonly maxProductionFiles: number;
+    readonly maxChangedLines: number;
+}
+export type PublicSurfaceDetermination = "none" | "changed" | "unknown";
+/** Measured cumulative product diff against a named base. */
+export interface SmallChangeLaneMeasurement {
+    /** The comparison base (lane-admit base, or the delivered commit's parent). */
+    readonly base: string;
+    readonly source: "worktree" | "delivered";
+    readonly productionFiles: readonly string[];
+    readonly changedLines: number;
+    readonly publicSurface: PublicSurfaceDetermination;
+    readonly publicSurfaceReason: string;
+}
+export type SmallChangeLaneMeasureResult = {
+    readonly ok: true;
+    readonly measurement: SmallChangeLaneMeasurement;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export type SmallChangeLaneVerdictKind = "admitted" | "not-rapid" | "unconfigured" | "unmeasured" | "public-surface-unknown" | "public-surface-changed" | "bound-crossed";
+export interface SmallChangeLaneVerdict {
+    readonly ok: boolean;
+    readonly kind: SmallChangeLaneVerdictKind;
+    readonly reason: string;
+    readonly measurement: SmallChangeLaneMeasurement | null;
+}
+export interface EvaluateSmallChangeLaneInput {
+    readonly depth: CeremonyDepth;
+    readonly bound: SmallChangeLaneBound | null;
+    /** Why the bound is null (unset or invalid policy). */
+    readonly boundError?: string | null;
+    readonly measure: SmallChangeLaneMeasureResult;
+}
+/**
+ * Pure fail-closed evaluator. Admits only at depth `rapid`, with a valid
+ * bound (null means invalid policy), a successful measurement, public surface `none`, and counts at or
+ * under the bound. Every other input refuses.
+ */
+export declare function evaluateSmallChangeLane(input: EvaluateSmallChangeLaneInput): SmallChangeLaneVerdict;
+/** The shipped default bound, used for any field the policy leaves unset. */
+export declare const DEFAULT_SMALL_CHANGE_LANE_BOUND: SmallChangeLaneBound;
+/**
+ * Validate a `plan.policy.ceremonyDial.smallChangeLane` payload. Each field is
+ * optional; a present field must be a non-negative integer.
+ */
+export declare function validateSmallChangeLaneBound(value: unknown): string[];
+export interface ReadSmallChangeLaneBoundResult {
+    readonly bound: SmallChangeLaneBound | null;
+    readonly error: string | null;
+}
+/**
+ * Read the bound from a `plan.policy.ceremonyDial` block. Unset fields use the
+ * shipped defaults; an invalid value refuses (bound null).
+ */
+export declare function readSmallChangeLaneBound(ceremonyDialBlock: unknown): ReadSmallChangeLaneBoundResult;
+/** Read the bound from the project's PROJECT-DEFINITION policy. */
+export declare function readSmallChangeLaneBoundFromProject(projectRoot: string): ReadSmallChangeLaneBoundResult;
+export interface GitResult {
+    readonly status: number;
+    readonly stdout: string;
+}
+export type SmallChangeLaneGitRunner = (args: readonly string[], cwd: string) => GitResult;
+export declare const defaultSmallChangeLaneGitRunner: SmallChangeLaneGitRunner;
+/** Lifecycle paths are not product diff (briefs, changelog, framework state). */
+export declare function isLaneLifecyclePath(relPath: string): boolean;
+/** Test and fixture paths are product diff but not production files or public surface. */
+export declare function isLaneTestPath(relPath: string): boolean;
+/** Public-surface class of one production path, before reading its diff. */
+export declare function classifyPublicSurfacePath(relPath: string): "surface" | "code" | "doc" | "unknown";
+export interface MeasureSmallChangeLaneOptions {
+    readonly projectRoot: string;
+    /** Lane-admit base for the worktree measure. */
+    readonly admitBase: string;
+    /**
+     * Delivered commit (merge or squash commit). When set, measure that commit
+     * against its first parent instead of the worktree against the admit base.
+     */
+    readonly deliveredCommit?: string | null;
+    readonly runGit?: SmallChangeLaneGitRunner;
+}
+/**
+ * Measure the cumulative product diff. Worktree mode diffs the working tree
+ * (committed, staged, unstaged and untracked) against the lane-admit base.
+ * Delivered mode diffs the delivered commit against its first parent.
+ * Any git failure or binary file fails the measurement.
+ */
+export declare function measureSmallChangeLaneDiff(options: MeasureSmallChangeLaneOptions): SmallChangeLaneMeasureResult;
+/**
+ * admitted → in the lane, bound rechecked at each gate.
+ * crossed → the bound was crossed after admit; refused until lane exit,
+ *   even if the diff later shrinks.
+ * escalated → converted to the full shape; the existing gates govern.
+ */
+export type SmallChangeLaneState = "admitted" | "crossed" | "escalated";
+export interface SmallChangeLaneMarker {
+    readonly state: SmallChangeLaneState;
+    readonly admitBase: string;
+    /** Why the bound was crossed (state `crossed`). */
+    readonly crossedReason?: string;
+}
+export type ReadSmallChangeLaneMarkerResult = {
+    readonly present: false;
+} | {
+    readonly present: true;
+    readonly ok: true;
+    readonly marker: SmallChangeLaneMarker;
+} | {
+    readonly present: true;
+    readonly ok: false;
+    readonly reason: string;
+};
+/** Build the marker the thin-brief emitter writes. */
+export declare function buildSmallChangeLaneMarker(admitBase: string, state?: SmallChangeLaneState): Record<string, unknown>;
+/** Read lane membership from `plan.metadata`. */
+export declare function readSmallChangeLaneMarker(plan: unknown): ReadSmallChangeLaneMarkerResult;
+/**
+ * Persist a crossing on the brief file so later retries refuse even if the
+ * diff shrinks back under the bound. Returns false when the write fails.
+ */
+export declare function recordSmallChangeLaneCrossing(briefPath: string, reason: string, projectRoot?: string): boolean;
+/** Full brief representation: at least one narrative with text and at least one plan item. */
+export declare function isFullBriefShape(plan: unknown): boolean;
+export type SmallChangeLaneGateName = "scope:promote" | "scope:activate" | "xbrief:preflight" | "verify:ac" | "scope:complete";
+/** Test and caller overrides. Production gates pass only `deliveredCommit`. */
+export interface SmallChangeLaneGateOverrides {
+    readonly depth?: CeremonyDepth;
+    readonly bound?: SmallChangeLaneBound | null;
+    readonly deliveredCommit?: string | null;
+    readonly runGit?: SmallChangeLaneGitRunner;
+}
+export interface SmallChangeLaneGateOptions extends SmallChangeLaneGateOverrides {
+    readonly projectRoot: string;
+    readonly gate: SmallChangeLaneGateName;
+    /** Brief file; when set, a crossing is recorded on it (state `crossed`). */
+    readonly briefPath?: string | null;
+}
+export interface SmallChangeLaneGateResult {
+    /** False when the brief is not in the lane (no marker); the gate is a no-op. */
+    readonly applies: boolean;
+    readonly ok: boolean;
+    readonly message: string;
+    readonly verdict: SmallChangeLaneVerdict | null;
+}
+/**
+ * Recheck the lane at a gate that can refuse. No marker → not in the lane, no-op.
+ * Admitted marker → measure and evaluate; any refusal names the lane exit.
+ * Escalated marker → the scope left the lane; it passes here only once the
+ * brief has the full shape, and the existing gates then decide.
+ */
+export declare function evaluateSmallChangeLaneGate(plan: unknown, options: SmallChangeLaneGateOptions): SmallChangeLaneGateResult;
+//# sourceMappingURL=small-change-lane.d.ts.map

package/vendor/directive-core/dist/policy/small-change-lane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"small-change-lane.d.ts","sourceRoot":"","sources":["../../src/policy/small-change-lane.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAYH,OAAO,EAAE,KAAK,aAAa,EAAuB,MAAM,oBAAoB,CAAC;AAI7E,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,6CAA6C,CAAC;AAElF,8EAA8E;AAC9E,eAAO,MAAM,4BAA4B,gCAAgC,CAAC;AAE1E,oCAAoC;AACpC,eAAO,MAAM,wBAAwB,8BAA8B,CAAC;AAEpE,qFAAqF;AACrF,eAAO,MAAM,6BAA6B,QAM8C,CAAC;AAEzF,2FAA2F;AAC3F,eAAO,MAAM,8CAA8C,IAAI,CAAC;AAEhE,iGAAiG;AACjG,eAAO,MAAM,2CAA2C,MAAM,CAAC;AAE/D,sFAAsF;AACtF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,MAAM,0BAA0B,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;AAExE,6DAA6D;AAC7D,MAAM,WAAW,0BAA0B;IACzC,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,CAAC;IAC1C,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,0BAA0B,CAAC;IACnD,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACtC;AAED,MAAM,MAAM,4BAA4B,GACpC;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,0BAA0B,CAAA;CAAE,GACvE;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD,MAAM,MAAM,0BAA0B,GAClC,UAAU,GACV,WAAW,GACX,cAAc,GACd,YAAY,GACZ,wBAAwB,GACxB,wBAAwB,GACxB,eAAe,CAAC;AAEpB,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,0BAA0B,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,0BAA0B,GAAG,IAAI,CAAC;CACzD;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC5C,uDAAuD;IACvD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,4BAA4B,CAAC;CAChD;AAUD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,4BAA4B,GAClC,sBAAsB,CA8CxB;AAMD,6EAA6E;AAC7E,eAAO,MAAM,+BAA+B,EAAE,oBAG7C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAYrE;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,KAAK,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,iBAAiB,EAAE,OAAO,GACzB,8BAA8B,CAyBhC;AAED,mEAAmE;AACnE,wBAAgB,mCAAmC,CACjD,WAAW,EAAE,MAAM,GAClB,8BAA8B,CAWhC;AAMD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,wBAAwB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,KAAK,SAAS,CAAC;AAE3F,eAAO,MAAM,+BAA+B,EAAE,wBAQ7C,CAAC;AAEF,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAS5D;AAED,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAGvD;AAwBD,4EAA4E;AAC5E,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAWjG;AAsND,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,wBAAwB,CAAC;CAC5C;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,6BAA6B,GACrC,4BAA4B,CAyH9B;AAMD;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,CAAC;AAIxE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,+BAA+B,GACvC;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAA;CAAE,GACrF;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAQ5E,sDAAsD;AACtD,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE,oBAAiC,GACvC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzB;AAED,iDAAiD;AACjD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,OAAO,GAAG,+BAA+B,CAgCxF;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAgBT;AAED,8FAA8F;AAC9F,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CASvD;AAED,MAAM,MAAM,uBAAuB,GAC/B,eAAe,GACf,gBAAgB,GAChB,kBAAkB,GAClB,WAAW,GACX,gBAAgB,CAAC;AAErB,+EAA+E;AAC/E,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC7C,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,wBAAwB,CAAC;CAC5C;AAED,MAAM,WAAW,0BAA2B,SAAQ,4BAA4B;IAC9E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAQD,MAAM,WAAW,yBAAyB;IACxC,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;CACjD;AAeD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,0BAA0B,GAClC,yBAAyB,CAiF3B"}