@deftai/directive-core 0.98.1 → 0.99.0

package/dist/platform/host-content-surface.js

@@ -0,0 +1,214 @@
+/**
+ * Host content-surface class + managed-section drift (#3162).
+ *
+ * Directive file gates and #830/#2508 pins assume filesystem-visible work product
+ * and a host that does not rewrite constitution mid-run. REPL-first and
+ * self-mutating hosts break those assumptions. This module classifies the host
+ * surface (capability pointer #1461/#1357) and reports managed AGENTS section
+ * drift without inventing a full pin product.
+ *
+ * Never blocks session-start — advisory only.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { agentsRefreshPlan, extractManagedSection, parseManagedSectionAttrs, stripManagedSectionAttrs, } from "./agents-md.js";
+/** Host content-surface classes for gate / pin honesty (#3162). */
+export const HOST_CONTENT_SURFACE_CLASSES = [
+    "file-first",
+    "repl-first",
+    "self-mutating",
+    "unknown",
+];
+/** Env key for explicit class override (capability descriptor pointer). */
+export const ENV_HOST_CONTENT_SURFACE = "DEFT_HOST_CONTENT_SURFACE";
+/** Env opt-in: host holds executable work product before files exist. */
+export const ENV_HOST_REPL_FIRST = "DEFT_HOST_REPL_FIRST";
+/** Env opt-in: host refine/kernel may CRUD skills/prompts mid-run. */
+export const ENV_HOST_SELF_MUTATE = "DEFT_HOST_SELF_MUTATE";
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+function envTruthy(value) {
+    return TRUTHY.has((value ?? "").trim().toLowerCase());
+}
+function normalizeClassToken(raw) {
+    const token = raw.trim().toLowerCase().replace(/_/g, "-");
+    if (HOST_CONTENT_SURFACE_CLASSES.includes(token)) {
+        return token;
+    }
+    // Accept aliases used in host docs.
+    if (token === "file" || token === "filesystem" || token === "fs-first")
+        return "file-first";
+    if (token === "repl" || token === "kernel-first")
+        return "repl-first";
+    if (token === "self-edit" || token === "self-editing" || token === "continual-harness") {
+        return "self-mutating";
+    }
+    return null;
+}
+/**
+ * Classify host content surface from explicit env / capability signals (#1461/#1357 pointer).
+ * Defaults to file-first (historical Directive assumption) when no signal is set.
+ */
+export function classifyHostContentSurface(environ = process.env) {
+    const signals = [];
+    const explicit = (environ[ENV_HOST_CONTENT_SURFACE] ?? "").trim();
+    if (explicit) {
+        signals.push(ENV_HOST_CONTENT_SURFACE);
+        const parsed = normalizeClassToken(explicit);
+        if (parsed !== null) {
+            return {
+                contentClass: parsed,
+                source: `env:${ENV_HOST_CONTENT_SURFACE}`,
+                signals,
+            };
+        }
+        return {
+            contentClass: "unknown",
+            source: `env:${ENV_HOST_CONTENT_SURFACE}:unrecognized`,
+            signals,
+        };
+    }
+    const selfMutate = envTruthy(environ[ENV_HOST_SELF_MUTATE]);
+    const replFirst = envTruthy(environ[ENV_HOST_REPL_FIRST]);
+    if (selfMutate)
+        signals.push(ENV_HOST_SELF_MUTATE);
+    if (replFirst)
+        signals.push(ENV_HOST_REPL_FIRST);
+    // Self-mutating supersedes REPL-first when both are set (broader honesty surface).
+    if (selfMutate) {
+        return {
+            contentClass: "self-mutating",
+            source: `env:${ENV_HOST_SELF_MUTATE}`,
+            signals,
+        };
+    }
+    if (replFirst) {
+        return {
+            contentClass: "repl-first",
+            source: `env:${ENV_HOST_REPL_FIRST}`,
+            signals,
+        };
+    }
+    return {
+        contentClass: "file-first",
+        source: "assumed",
+        signals,
+    };
+}
+function hashBody(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex").slice(0, 12);
+}
+function mapPlanState(raw) {
+    if (typeof raw !== "string")
+        return "unknown";
+    switch (raw) {
+        case "current":
+        case "stale":
+        case "missing":
+        case "absent":
+        case "unreadable":
+        case "template-missing":
+        case "template-malformed":
+            return raw;
+        default:
+            return "unknown";
+    }
+}
+/**
+ * Probe managed AGENTS.md section drift (tamper-evident boundary, not full #830 pins).
+ * Uses agents:refresh plan state + embedded marker sha + body hash.
+ */
+export function probeManagedSectionDrift(projectRoot, seams = {}) {
+    const agentsPath = join(projectRoot, "AGENTS.md");
+    const plan = agentsRefreshPlan(projectRoot, seams.agentsMdSeams ?? {});
+    const state = mapPlanState(plan.state);
+    let embeddedSha = null;
+    let bodyHash = null;
+    const readAgents = seams.agentsMdSeams?.readAgents ??
+        ((path) => {
+            try {
+                if (!existsSync(path))
+                    return null;
+                return readFileSync(path, "utf8");
+            }
+            catch {
+                return null;
+            }
+        });
+    try {
+        const text = readAgents(agentsPath);
+        if (text !== null) {
+            const extracted = extractManagedSection(text);
+            if (extracted !== null) {
+                const attrs = parseManagedSectionAttrs(extracted);
+                embeddedSha = attrs?.sha ?? null;
+                bodyHash = hashBody(stripManagedSectionAttrs(extracted));
+            }
+        }
+    }
+    catch {
+        // body hash is best-effort
+    }
+    return {
+        state,
+        embeddedSha,
+        bodyHash,
+        path: typeof plan.path === "string" ? plan.path : agentsPath,
+    };
+}
+/** Full host-surface report for session-start payload + lines. */
+export function probeHostContentSurface(projectRoot, seams = {}) {
+    const environ = seams.environ ?? process.env;
+    const classified = classifyHostContentSurface(environ);
+    const managedSection = probeManagedSectionDrift(projectRoot, seams);
+    return {
+        contentClass: classified.contentClass,
+        classSource: classified.source,
+        signals: classified.signals,
+        managedSection,
+        runtimeMode: seams.runtimeMode ?? null,
+    };
+}
+export function hostContentSurfaceToDict(report) {
+    return {
+        content_class: report.contentClass,
+        class_source: report.classSource,
+        signals: [...report.signals],
+        runtime_mode: report.runtimeMode,
+        managed_section: {
+            state: report.managedSection.state,
+            embedded_sha: report.managedSection.embeddedSha,
+            body_hash: report.managedSection.bodyHash,
+            path: report.managedSection.path,
+        },
+    };
+}
+/**
+ * Format operator-facing host-surface lines (#3162).
+ * Always emits one summary line; adds honesty note for non-file-first or drift.
+ */
+export function formatHostContentSurfaceLines(report) {
+    const managed = report.managedSection.state;
+    const summary = `[deft host-surface] class=${report.contentClass} source=${report.classSource} ` +
+        `managed=${managed}` +
+        (report.managedSection.embeddedSha ? ` sha=${report.managedSection.embeddedSha}` : "") +
+        (report.managedSection.bodyHash ? ` body=${report.managedSection.bodyHash}` : "");
+    const lines = [summary];
+    if (report.contentClass === "repl-first" || report.contentClass === "self-mutating") {
+        lines.push("[deft host-surface] honesty: file gates and agent-only pins do not see host-kernel " +
+            "or mid-run host refine work product — see content/docs/host-surface-assumptions.md (#3162)");
+    }
+    if (managed === "stale" || managed === "missing" || managed === "absent") {
+        lines.push("[deft host-surface] managed AGENTS section drift — run `deft agents:refresh` " +
+            "(or `task agents:refresh`) so pins/managed constitution match the deposit");
+    }
+    return lines;
+}
+/**
+ * Probe + format; fail-open for session-start (never throws to callers that wrap).
+ */
+export function maybeFormatHostContentSurfaceLines(projectRoot, seams = {}) {
+    const report = probeHostContentSurface(projectRoot, seams);
+    return { report, lines: formatHostContentSurfaceLines(report) };
+}
+//# sourceMappingURL=host-content-surface.js.map

package/dist/platform/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./agents-consumer-header.js";
 export * from "./agents-md.js";
 export * from "./constants.js";
+export * from "./host-content-surface.js";
 export * from "./ip-risk.js";
 export * from "./linear-scan.js";
 export * from "./platform-capabilities.js";

package/dist/platform/index.js

@@ -1,6 +1,7 @@
 export * from "./agents-consumer-header.js";
 export * from "./agents-md.js";
 export * from "./constants.js";
+export * from "./host-content-surface.js";
 export * from "./ip-risk.js";
 export * from "./linear-scan.js";
 export * from "./platform-capabilities.js";

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

@@ -0,0 +1,233 @@
+/**
+ * Ceremony dial (#3214): 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):
+ *   cold-start / incomplete inputs → **rapid** (start light; no plan-item deadlock)
+ *   escalate when evidence arrives (provisional M/L, mid/low tier, full matrix)
+ * Full matrix: S × frontier → rapid; non-project → minimal; else scales up.
+ * Override always available via plan.policy.ceremonyDial.override; audited on write.
+ */
+/** 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";
+    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;
+/**
+ * Two-stage / partial-evidence selection when size or tier is missing (#3214 design note).
+ *
+ * Start light (rapid) on cold incomplete inputs; escalate when partial evidence already
+ * implies heavier ceremony (apps-bank safety: hard/substantial work must not stay rapid).
+ * 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 + two-stage design note):
+ * - 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 → two-stage partial evidence (default rapid; escalate on M/L or mid/low)
+ */
+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** (two-stage cold default; escalate when evidence arrives).
+ */
+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;
+};
+//# sourceMappingURL=ceremony-dial.d.ts.map