@deftai/directive-core 0.98.1 → 0.100.0

package/dist/policy/ceremony-dial.d.ts

@@ -0,0 +1,289 @@
+/**
+ * Ceremony dial (#3214 / #3263): ritual depth = f(task size × model tier × project shape).
+ *
+ * Selection policy over existing pieces — not a new subsystem.
+ * Composes:
+ *   - strategies/rapid.md (light / rapid path)
+ *   - #3014 minimal consumer AGENTS profile (research pointer; not yet a shipped deposit)
+ *   - effort estimate (#1581), model routing (#1976/#818), host capability (#1461)
+ *
+ * Two-stage dial (#3214 design note / #1581 ordering) with tier-conditional cold-start (#3263):
+ *   cold-start / incomplete size → **tier-conditional**:
+ *     frontier (or unknown tier) → rapid; mid/low → standard (not rapid)
+ *   escalate when evidence arrives (provisional M/L size, full matrix)
+ * Full matrix: S × frontier → rapid; non-project → minimal; else scales up.
+ * Override always available via plan.policy.ceremonyDial.override; audited on write.
+ *
+ * Audit path (#3263): session:start records depth + provisional reasons on
+ * `.deft/ritual-state.json` under `ceremony_dial` — use `readCeremonyDialAudit`.
+ */
+/** Canonical dotted policy field name. */
+export declare const FIELD_CEREMONY_DIAL = "plan.policy.ceremonyDial";
+/** Short alias for `policy:show --field=ceremonyDial`. */
+export declare const FIELD_CEREMONY_DIAL_CLI_ALIAS = "ceremonyDial";
+/** Depth ladder: less ceremony → more ceremony. */
+export declare const CEREMONY_DEPTHS: readonly ["minimal", "rapid", "standard", "elevated"];
+export type CeremonyDepth = (typeof CEREMONY_DEPTHS)[number];
+/** Task size band (aligns with swarm size / effort estimate vocabulary). */
+export declare const CEREMONY_TASK_SIZES: readonly ["S", "M", "L", "XL"];
+export type CeremonyTaskSize = (typeof CEREMONY_TASK_SIZES)[number];
+/**
+ * Model capability tier for dial selection.
+ * `frontier` = strongest class; `mid` benefits from structure; `low` needs more ceremony.
+ */
+export declare const CEREMONY_MODEL_TIERS: readonly ["frontier", "mid", "low"];
+export type CeremonyModelTier = (typeof CEREMONY_MODEL_TIERS)[number];
+/** Whether the session is project-shaped (Directive repo/work) or ad-hoc non-project. */
+export declare const CEREMONY_PROJECT_SHAPES: readonly ["project", "non-project"];
+export type CeremonyProjectShape = (typeof CEREMONY_PROJECT_SHAPES)[number];
+/** Pointers for composition (not loaded as a subsystem — discovery only). */
+export declare const CEREMONY_RAPID_STRATEGY_POINTER = "content/strategies/rapid.md";
+export declare const CEREMONY_MINIMAL_AGENTS_PROFILE_POINTER = "docs/analysis/2026-07-31-minimal-consumer-agents-profile-research.md (#3014)";
+export interface CeremonyDialConfig {
+    /** When false, selection always returns standard (full ceremony). Default true. */
+    readonly enabled?: boolean;
+    /**
+     * Force a depth regardless of inputs. Always wins when set.
+     * Use null/omit for matrix selection.
+     */
+    readonly override?: CeremonyDepth | null;
+}
+export interface CeremonyDialInputs {
+    readonly taskSize?: CeremonyTaskSize | null;
+    readonly modelTier?: CeremonyModelTier | null;
+    readonly projectShape?: CeremonyProjectShape | null;
+}
+export interface CeremonyDialProfile {
+    readonly depth: CeremonyDepth;
+    /**
+     * Ritual steps auto-deferred at this depth (merged into session:start deferrals).
+     * Matches QUICK_STEPS / GATED_STEPS names in session-start.
+     */
+    readonly autoDeferSteps: readonly string[];
+    /** Skip fat cold-path work (verify tools, triage welcome, release probe, tickler). */
+    readonly skipFatPath: boolean;
+    /** How much lifecycle / history write budget this depth intends. */
+    readonly lifecycleWrites: "minimal" | "light" | "full";
+    /**
+     * Literal acceptance-command verification is always required (#3267 / #3156).
+     * Ceremony dial never skips capture+verbatim run — including rapid/minimal.
+     */
+    readonly literalAcceptanceRequired: true;
+    readonly label: string;
+}
+export type CeremonyDialSource = "override" | "matrix" | "default" | "disabled" | "typed" | "default-on-error";
+export interface CeremonyDialComposition {
+    /** Set when depth is rapid (light path). */
+    readonly rapidStrategy: string | null;
+    /** Set when depth is minimal (non-project / #3014 direction). */
+    readonly minimalAgentsProfile: string | null;
+}
+export interface CeremonyDialSelection {
+    readonly depth: CeremonyDepth;
+    readonly source: CeremonyDialSource;
+    readonly inputs: {
+        readonly taskSize: CeremonyTaskSize | null;
+        readonly modelTier: CeremonyModelTier | null;
+        readonly projectShape: CeremonyProjectShape | null;
+    };
+    readonly profile: CeremonyDialProfile;
+    readonly composition: CeremonyDialComposition;
+    readonly config: CeremonyDialConfig;
+    readonly error: string | null;
+}
+export declare function ceremonyDialProfile(depth: CeremonyDepth): CeremonyDialProfile;
+/** Validate a typed `plan.policy.ceremonyDial` payload. */
+export declare function validateCeremonyDial(value: unknown): string[];
+/**
+ * Normalize free-form size tokens (swarm size vocabulary) into dial bands.
+ * Accepts S|M|L|XL and small|medium|large|extra-large (case-insensitive).
+ */
+export declare function normalizeCeremonyTaskSize(raw: unknown): CeremonyTaskSize | null;
+/**
+ * Normalize model tier tokens. Frontier covers high/strong; mid covers medium;
+ * low covers weak/economy.
+ */
+export declare function normalizeCeremonyModelTier(raw: unknown): CeremonyModelTier | null;
+export declare function normalizeCeremonyProjectShape(raw: unknown): CeremonyProjectShape | null;
+/**
+ * Tier-conditional cold-start depth when task size is incomplete (#3263).
+ *
+ * Mid/low models benefit from structure on hard tasks and should not cold-start
+ * at rapid (start-light / escalate-too-late signature). Frontier recovers from a
+ * light start. Unknown tier stays rapid (optimistic cold default; pass
+ * `--model-tier` / `DEFT_CEREMONY_MODEL_TIER` to unlock the mid/low floor).
+ *
+ * Escalate-on-evidence still applies when size later arrives (full matrix).
+ */
+export declare function selectCeremonyColdStartDepth(modelTier: CeremonyModelTier | null | undefined): CeremonyDepth;
+/**
+ * Two-stage / partial-evidence selection when size or tier is missing
+ * (#3214 design note / #3263 tier-conditional cold-start).
+ *
+ * Cold incomplete size is tier-conditional (#3263): mid/low → standard, frontier
+ * or unknown → rapid. When size is known without tier, escalate on substantial
+ * size (apps-bank safety). Does not invent plan-item effort (#1581 post-planning only).
+ */
+export declare function selectCeremonyDepthFromPartialEvidence(inputs: {
+    readonly taskSize: CeremonyTaskSize | null;
+    readonly modelTier: CeremonyModelTier | null;
+}): CeremonyDepth;
+/**
+ * Pure default matrix (#3214 acceptance + #3263 tier-conditional cold-start):
+ * - non-project → minimal (#3014 direction)
+ * - S × frontier → rapid (strategies/rapid.md)
+ * - S × mid → standard (mid-tier gains from structure)
+ * - S × low → elevated
+ * - M × low → elevated; M otherwise → standard
+ * - L/XL → elevated (except L × frontier stays standard)
+ * - Incomplete size → tier-conditional cold-start (#3263): mid/low → standard; frontier/unknown → rapid
+ * - Size known, tier missing → escalate on M/L (partial evidence)
+ */
+export declare function selectCeremonyDepthFromMatrix(inputs: CeremonyDialInputs): CeremonyDepth;
+export interface SelectCeremonyDepthOptions {
+    readonly config?: CeremonyDialConfig;
+    readonly inputs?: CeremonyDialInputs;
+}
+/**
+ * Deterministic depth selection (pure; no IO).
+ *
+ * Precedence: disabled → standard; override → forced depth; else matrix on inputs;
+ * empty inputs → **rapid** (unknown-tier cold default; #3263 mid/low need modelTier set).
+ */
+export declare function selectCeremonyDepth(options?: SelectCeremonyDepthOptions): CeremonyDialSelection;
+export interface ResolveCeremonyDialOptions {
+    readonly inputs?: CeremonyDialInputs;
+    /** Explicit config bypasses PROJECT-DEFINITION load (tests). */
+    readonly config?: CeremonyDialConfig;
+}
+/**
+ * Resolve ceremony dial from PROJECT-DEFINITION policy + session inputs (#3214).
+ */
+export declare function resolveCeremonyDial(projectRoot: string, options?: ResolveCeremonyDialOptions): CeremonyDialSelection;
+/** Human-readable status line for session:start / policy:show. */
+export declare function formatCeremonyDialStatusLine(selection: CeremonyDialSelection): string;
+/** JSON-serializable dial snapshot for ritual-state / session payload. */
+export declare function ceremonyDialToDict(selection: CeremonyDialSelection): Record<string, unknown>;
+export interface CeremonyDialPolicyField {
+    readonly name: typeof FIELD_CEREMONY_DIAL;
+    readonly current: CeremonyDialConfig & {
+        selectedDepth?: CeremonyDepth;
+    };
+    readonly default: CeremonyDialConfig;
+    readonly source: string;
+}
+/** Inspector row for `task policy:show --field=ceremonyDial`. */
+export declare function inspectCeremonyDial(data: Record<string, unknown> | null, projectRoot?: string): CeremonyDialPolicyField;
+export interface SetCeremonyDialOptions {
+    readonly enabled?: boolean;
+    readonly override?: CeremonyDepth | null;
+    readonly actor?: string;
+    readonly note?: string;
+    readonly confirm?: boolean;
+}
+export interface SetCeremonyDialResult {
+    readonly exitCode: 0 | 1 | 2;
+    readonly stdout: string;
+    readonly changed: boolean;
+}
+/**
+ * Persist plan.policy.ceremonyDial (override + enabled) with audit trail (#3214).
+ * Requires --confirm for override writes (capability-cost style disclosure).
+ */
+export declare function setCeremonyDial(projectRoot: string, options: SetCeremonyDialOptions): SetCeremonyDialResult;
+/**
+ * Merge dial auto-defer steps into an existing deferrals map without clobbering
+ * operator-supplied reasons.
+ */
+export declare function mergeCeremonyDialDeferrals(existing: Readonly<Record<string, string>>, selection: CeremonyDialSelection): Record<string, string>;
+/** Env keys for headless dial inputs (no operator confirmation). */
+export declare const ENV_CEREMONY_TASK_SIZE = "DEFT_CEREMONY_TASK_SIZE";
+export declare const ENV_CEREMONY_MODEL_TIER = "DEFT_CEREMONY_MODEL_TIER";
+export declare const ENV_CEREMONY_PROJECT_SHAPE = "DEFT_CEREMONY_PROJECT_SHAPE";
+/** Optional host model hint used when DEFT_CEREMONY_MODEL_TIER is unset. */
+export declare const ENV_CEREMONY_MODEL_HINT = "DEFT_MODEL";
+export interface ProvisionalCeremonyEstimateHints {
+    /** Free-text task / prompt (optional; headless may omit). */
+    readonly promptText?: string | null;
+    /** Closed-verb or action verb token when known. */
+    readonly verb?: string | null;
+    /** Paths in scope (files or dirs); used for file-count / multi-area signals. */
+    readonly filePaths?: readonly string[] | null;
+    /** Explicit file count when paths are not enumerated. */
+    readonly fileCount?: number | null;
+    /** Process env for headless size/tier/shape overrides. */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Project root for deposit-based project-shape detection. */
+    readonly projectRoot?: string | null;
+}
+export interface ProvisionalCeremonyEstimate {
+    readonly taskSize: CeremonyTaskSize | null;
+    readonly modelTier: CeremonyModelTier | null;
+    readonly projectShape: CeremonyProjectShape | null;
+    /** Why each filled field was chosen (headless diagnostics). */
+    readonly reasons: readonly string[];
+}
+/**
+ * Detect project shape from deposit layout (headless, no prompts).
+ * Returns `project` when vanilla deposit markers exist; **null** when unknown
+ * (two-stage cold default stays rapid — do not invent non-project without evidence).
+ * Explicit `non-project` comes from CLI/env only.
+ */
+export declare function detectCeremonyProjectShape(projectRoot: string): CeremonyProjectShape | null;
+/**
+ * Headless-safe provisional S/M/L (+ optional tier/shape) **before** ritual.
+ * No operator confirmation. Plan-item effort (#1581) later confirms/corrects.
+ *
+ * Signals (max-wins for size): env → verb class → file-scope count → prompt shape.
+ * Project shape: env, else deposit detection when projectRoot is set.
+ */
+export declare function estimateProvisionalCeremonyInputs(hints?: ProvisionalCeremonyEstimateHints): ProvisionalCeremonyEstimate;
+/**
+ * Merge explicit dial inputs over provisional estimates. Explicit non-null wins.
+ * Used by session:start so vanilla deposit gets provisional fill without policy opt-in.
+ */
+export declare function mergeCeremonyDialInputsWithProvisional(explicit: CeremonyDialInputs | undefined, provisional: ProvisionalCeremonyEstimate): CeremonyDialInputs;
+/**
+ * Resolve dial inputs for session:start: explicit CLI/options first, then
+ * headless provisional classifier (env / verb / files / prompt / deposit).
+ * ⊗ Does not read plan-item effort (#1581) — that lands post-planning only.
+ */
+export declare function resolveSessionCeremonyDialInputs(projectRoot: string, explicit?: CeremonyDialInputs, options?: Omit<ProvisionalCeremonyEstimateHints, "projectRoot">): {
+    readonly inputs: CeremonyDialInputs;
+    readonly provisional: ProvisionalCeremonyEstimate;
+};
+export interface CeremonyDialAuditProvisional {
+    readonly taskSize: CeremonyTaskSize | null;
+    readonly modelTier: CeremonyModelTier | null;
+    readonly projectShape: CeremonyProjectShape | null;
+    readonly reasons: readonly string[];
+}
+/**
+ * Snapshot of dial selection recorded on `.deft/ritual-state.json` at session:start.
+ * Operators audit failed-task depth / provisional reasons without re-running ritual.
+ */
+export interface CeremonyDialAuditSnapshot {
+    readonly path: string;
+    readonly depth: CeremonyDepth | null;
+    readonly source: string | null;
+    readonly inputs: {
+        readonly taskSize: CeremonyTaskSize | null;
+        readonly modelTier: CeremonyModelTier | null;
+        readonly projectShape: CeremonyProjectShape | null;
+    } | null;
+    readonly provisional: CeremonyDialAuditProvisional | null;
+    readonly raw: Record<string, unknown> | null;
+    readonly error: string | null;
+}
+/**
+ * Read ceremony dial depth + provisional reasons from ritual-state (#3263 audit path).
+ * session:start already writes `ceremony_dial` (incl. provisional) — this is the
+ * operator/read path so failed runs can confirm start-light vs escalate timing.
+ *
+ * Returns `error` when ritual-state is missing/unreadable or lacks `ceremony_dial`;
+ * does not throw.
+ */
+export declare function readCeremonyDialAudit(projectRoot: string): CeremonyDialAuditSnapshot;
+/** One-line operator summary for audit tooling / failed-task forensics (#3263). */
+export declare function formatCeremonyDialAuditLine(audit: CeremonyDialAuditSnapshot): string;
+//# sourceMappingURL=ceremony-dial.d.ts.map