@deftai/directive-core 0.91.0 → 0.93.0

package/dist/scope/transition.js

@@ -8,6 +8,7 @@ import { atomicWriteBrief, formatBriefJson, readBriefForMutation } from "./brief
 import { stampCompletionMetadata } from "./capacity-stamp.js";
 import { LIFECYCLE_FOLDERS, MOVE_LABELS, STATUS_PRECONDITIONS, STAY_LABELS, TRANSITIONS, } from "./constants.js";
 import { detectLifecycleFolder, updateDecomposedChildBackReferences, updateDecomposedParentBackReferences, } from "./decomposed-refs.js";
+import { classifyStoredDeliveryDisposition, evaluateDeliveryGate, stampDeliveryProvenance, } from "./delivery-evidence.js";
 import { syncProjectDefinitionAfterScopeMove } from "./project-definition-sync.js";
 import { syncSpecificationAfterScopeMove } from "./specification-sync.js";
 import { utcNowIso } from "./vbrief-json.js";
@@ -48,7 +49,7 @@ function stampEnvelopeUpdated(data, nowIso) {
         }
     }
 }
-export function runTransition(action, filePath, now = new Date()) {
+export function runTransition(action, filePath, now = new Date(), options = {}) {
     if (!(action in TRANSITIONS)) {
         const valid = Object.keys(TRANSITIONS).sort().join(", ");
         return { ok: false, message: `Unknown action '${action}'. Valid actions: ${valid}` };
@@ -95,9 +96,15 @@ export function runTransition(action, filePath, now = new Date()) {
     const requiredStatus = STATUS_PRECONDITIONS[act];
     if (requiredStatus !== undefined) {
         if (currentStatus === targetStatus) {
+            // Surface legacy delivery disposition on already-completed briefs (#3041).
+            let dispositionSuffix = "";
+            if (act === "complete" && currentFolder === "completed") {
+                const disposition = classifyStoredDeliveryDisposition(planObj);
+                dispositionSuffix = ` (deliveryDisposition=${disposition})`;
+            }
             return {
                 ok: true,
-                message: `No-op: ${basename} is already ${targetStatus} in ${currentFolder}/`,
+                message: `No-op: ${basename} is already ${targetStatus} in ${currentFolder}/${dispositionSuffix}`,
             };
         }
         if (currentStatus !== requiredStatus) {
@@ -131,6 +138,25 @@ export function runTransition(action, filePath, now = new Date()) {
         }
     }
     const nowIso = utcNowIso(now);
+    // #3041: fail closed before mutating a code-bearing complete without delivery evidence.
+    if (act === "complete") {
+        const gate = evaluateDeliveryGate({
+            projectRoot,
+            plan: planObj,
+            nowIso,
+            evidence: options.deliveryEvidence,
+            nonDeliveryDisposition: options.nonDeliveryDisposition,
+            runGit: options.runGit,
+            verifier: options.verifier ?? "scope:complete",
+            assumeEvidenceValidated: options.assumeEvidenceValidated,
+        });
+        if (!gate.ok) {
+            return { ok: false, message: gate.message };
+        }
+        if (gate.provenance !== null) {
+            stampDeliveryProvenance(planObj, gate.provenance);
+        }
+    }
     planObj.status = targetStatus;
     planObj.updated = nowIso;
     // Keep the envelope clock aligned with plan.updated on every mutating transition (#2862).
@@ -153,7 +179,7 @@ export function runTransition(action, filePath, now = new Date()) {
         }
         // #2578: stamp terminal status at the destination path in the same write as
         // folder placement — never leave a non-terminal status under completed/.
-        const writeResult = atomicWriteBrief(destPath, data, vbriefRoot);
+        const writeResult = atomicWriteBrief(destPath, data, vbriefRoot, { projectRoot });
         if (!writeResult.ok) {
             return { ok: false, message: writeResult.message };
         }
@@ -193,7 +219,7 @@ export function runTransition(action, filePath, now = new Date()) {
             message: `${actionLabel} ${basename}: ${currentFolder}/ -> ${targetFolder}/ (status: ${targetStatus})`,
         };
     }
-    const writeResult = atomicWriteBrief(resolvedPath, data, vbriefRoot);
+    const writeResult = atomicWriteBrief(resolvedPath, data, vbriefRoot, { projectRoot });
     if (!writeResult.ok) {
         return { ok: false, message: writeResult.message };
     }

package/dist/session/ritual-sentinel.js

@@ -1,6 +1,7 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, } from "node:fs";
-import { join, relative, resolve } from "node:path";
+import { existsSync, readdirSync, readFileSync, renameSync, rmSync, statSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
 import { containedWrite } from "../fs/contained-write.js";
+import { assertWriteTargetSafe } from "../fs/projection-containment.js";
 import { hasArtifactSuffix, LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, } from "../layout/resolve.js";
 import { stableJson } from "./json.js";
 import { RITUAL_STATE_CONTRACT } from "./posture.js";
@@ -95,21 +96,29 @@ function validateSteps(raw, key) {
     }
     return [steps, null];
 }
-function atomicWriteJson(targetPath, payload, prefix) {
-    const dir = join(targetPath, "..");
-    mkdirSync(dir, { recursive: true });
-    const tmpBase = `${prefix}${process.pid}.json.tmp`;
+/**
+ * Contained atomic JSON write for ritual/sentinel state (#3042).
+ * Containment root is projectRoot (not dirname(target)) so a force-added `.deft`
+ * directory symlink fails closed before temp+rename.
+ */
+function atomicWriteJson(projectRoot, targetPath, payload, prefix) {
+    const root = resolve(projectRoot);
+    const abs = resolve(targetPath);
+    // Refuse leaf/parent symlinks on the final path before temp+rename publish.
+    assertWriteTargetSafe(root, abs);
+    const dir = dirname(abs);
+    const tmpBase = `${prefix}${process.pid}.${basename(abs)}.tmp`;
     const tmpName = join(dir, tmpBase);
     const text = `${stableJson(payload, 2)}\n`;
     try {
-        // #2980 wave D: ritual-state product write routes through containedWrite.
+        // #2980 wave D / #3042: product write routes through containedWrite under projectRoot.
         containedWrite({
-            root: resolve(dir),
-            target: tmpBase,
+            root,
+            target: tmpName,
             data: text,
             mode: "create",
         });
-        renameSync(tmpName, targetPath);
+        renameSync(tmpName, abs);
     }
     catch (err) {
         try {
@@ -191,7 +200,7 @@ export function readRitualState(projectRoot) {
 }
 export function writeRitualState(projectRoot, payload) {
     const stateFile = ritualStatePath(projectRoot);
-    atomicWriteJson(stateFile, payload, ".ritual-state.");
+    atomicWriteJson(projectRoot, stateFile, payload, ".ritual-state.");
     return stateFile;
 }
 /** Instant guaranteed to fail `evaluateLoadedState` age checks on any policy horizon. */
@@ -303,7 +312,7 @@ export function writeSentinel(projectRoot, input) {
             .replace(`${LEGACY_ARTIFACT_DIR}/active/`, `${MIGRATED_ARTIFACT_DIR}/active/`),
         lastBranch: input.lastBranch,
     };
-    atomicWriteJson(sentinelFile, payload, ".last-session.");
+    atomicWriteJson(projectRoot, sentinelFile, payload, ".last-session.");
     return sentinelFile;
 }
 function formatElapsed(deltaMs) {

package/dist/session/session-start-hook.d.ts

@@ -1,3 +1,4 @@
+import { detectDeftDirectiveDisable } from "../policy/deft-directive-disable.js";
 import { detectNoDeftDirective } from "../policy/no-deft-directive.js";
 import { writeSentinel } from "./ritual-sentinel.js";
 export interface SessionStartHookOptions {
@@ -7,6 +8,8 @@ export interface SessionStartHookOptions {
     readonly writeSentinelFn?: typeof writeSentinel;
     /** Test seam for #2926 opt-out detection. */
     readonly detectNoDeftDirectiveFn?: typeof detectNoDeftDirective;
+    /** Test seam for #3039 test kill-switch detection. */
+    readonly detectDeftDirectiveDisableFn?: typeof detectDeftDirectiveDisable;
 }
 /** Write ``.deft/last-session.json`` from current git state (#1269). */
 export declare function runSessionStartHookWrite(projectRoot: string, options?: SessionStartHookOptions): {

package/dist/session/session-start-hook.js

@@ -1,9 +1,30 @@
 import { resolveVersion } from "../doctor/paths.js";
+import { detectDeftDirectiveDisable, formatDeftDirectiveDisableMessage, isDeftDirectiveDisableActive, } from "../policy/deft-directive-disable.js";
 import { detectNoDeftDirective, NO_DEFT_DIRECTIVE_DISABLED_MESSAGE, NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE, } from "../policy/no-deft-directive.js";
 import { detectBranch } from "./git.js";
 import { detectLatestActiveVbrief, writeSentinel } from "./ritual-sentinel.js";
 /** Write ``.deft/last-session.json`` from current git state (#1269). */
 export function runSessionStartHookWrite(projectRoot, options = {}) {
+    const detectKill = options.detectDeftDirectiveDisableFn ?? detectDeftDirectiveDisable;
+    // #3039: local (untracked) kill-switch — skip ritual bookkeeping (deposit OK).
+    // Tracked flags do not short-circuit (enforcement stays on).
+    const kill = detectKill(projectRoot);
+    const killActive = options.detectDeftDirectiveDisableFn !== undefined
+        ? kill.active
+        : isDeftDirectiveDisableActive(projectRoot);
+    if (killActive) {
+        const detectOptOut = options.detectNoDeftDirectiveFn ?? detectNoDeftDirective;
+        const optOut = detectOptOut(projectRoot);
+        const message = formatDeftDirectiveDisableMessage({
+            permanentOptOutAlsoPresent: optOut.present,
+            trackedByGit: false,
+        });
+        return {
+            code: 0,
+            stdout: `${message}\n`,
+            stderr: "",
+        };
+    }
     const detectOptOut = options.detectNoDeftDirectiveFn ?? detectNoDeftDirective;
     // #2926: root opt-out wins — host SessionStart must not write ritual bookkeeping.
     const optOut = detectOptOut(projectRoot);

package/dist/session/session-start.js

@@ -3,6 +3,7 @@ import { runningInsideDeftRepo } from "../doctor/paths.js";
 import { emitSessionEvalReadback } from "../eval/readback.js";
 import { MIGRATE_COMPLETION_NUDGE, shouldEmitMigrateNudge } from "../init-deposit/migrate.js";
 import { detectEnvironmentContext, environmentContextToDict, formatEnvironmentContext, } from "../platform/shell-context.js";
+import { DEFT_DIRECTIVE_DISABLE_FLAG_NAME, DEFT_DIRECTIVE_DISABLE_STATUS, detectDeftDirectiveDisable, formatDeftDirectiveDisableMessage, isDeftDirectiveDisableActive, } from "../policy/deft-directive-disable.js";
 import { disclosureLine } from "../policy/disclosure.js";
 import { detectNoDeftDirective, NO_DEFT_DIRECTIVE_DISABLED_MESSAGE, NO_DEFT_DIRECTIVE_FLAG_NAME, NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE, NO_DEFT_DIRECTIVE_INCONSISTENT_POLICY, } from "../policy/no-deft-directive.js";
 import { humanMergeDisclosureLine, resolveHumanMergePolicy, } from "../policy/require-human-merge.js";
@@ -543,6 +544,36 @@ export function runSessionStart(projectRoot, options = {}) {
     const runGit = options.runGit ?? defaultGitRunner;
     const environment = (options.probeEnvironment ?? detectEnvironmentContext)();
     const ceremonyTier = options.ceremonyTier ?? COLD_CEREMONY_TIER;
+    // #3039: local (untracked) test kill-switch — skip ritual write; deposit may remain.
+    // Recovery requires delete + new session. Tracked flags do not short-circuit.
+    if (isDeftDirectiveDisableActive(projectRoot)) {
+        const killSwitch = detectDeftDirectiveDisable(projectRoot);
+        const optOutAlso = detectNoDeftDirective(projectRoot);
+        const message = formatDeftDirectiveDisableMessage({
+            permanentOptOutAlsoPresent: optOutAlso.present,
+            trackedByGit: false,
+        });
+        const lines = message.split("\n");
+        return {
+            code: 0,
+            payload: {
+                ready: false,
+                exit_code: 0,
+                disabled: true,
+                disabled_via: DEFT_DIRECTIVE_DISABLE_FLAG_NAME,
+                status: DEFT_DIRECTIVE_DISABLE_STATUS,
+                kill_switch: true,
+                inconsistent: false,
+                deposit_present: killSwitch.depositPresent,
+                tracked_by_git: false,
+                permanent_opt_out_also_present: optOutAlso.present,
+                posture,
+                environment: environmentContextToDict(environment),
+                message,
+            },
+            lines,
+        };
+    }
     // #2926: official root opt-out wins locally — skip Directive session ritual.
     // disabled = skip ritual (exit 0 clean / 1 inconsistent). ready stays false so
     // automation does not treat opt-out as "session fully initialized for work".

package/dist/slash/emitters.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Per-host native command/prompt emitters (#3053 / epic #55).
+ *
+ * Maps shared thin-wrapper IR from {@link generateThinWrappers} onto each
+ * supported host’s repo-relative path layout. Pure generate-to-path records;
+ * filesystem deposit is init-deposit `writeSlashCommandDeposit` (#3054).
+ *
+ * ## Host id → output directory / file pattern
+ *
+ * | Host id | Relative directory   | Filename pattern   |
+ * |---------|----------------------|--------------------|
+ * | claude  | `.claude/commands/`  | `{hyphen-stem}.md` |
+ * | cursor  | `.cursor/commands/`  | `{hyphen-stem}.md` |
+ * | grok    | `.grok/commands/`    | `{hyphen-stem}.md` |
+ * | codex   | `.codex/prompts/`    | `{hyphen-stem}.md` |
+ *
+ * All four use the shared thin-wrapper markdown template (L5). Adding a host is
+ * an additive layout entry + optional frontmatter reshape — not a new product
+ * name table (L2 lives in product-set / generator only).
+ *
+ * ⊗ Empty stub dirs for “enabled but no emitter” (L6).
+ * ⊗ Native legacy alias files (L3).
+ */
+import { type ThinWrapperIR } from "./generator.js";
+/**
+ * Hosts with a real slash/prompt emitter layout (aligned with hook host ids).
+ * Default enabled set for deposit (#3054) is this list when policy opts in.
+ */
+export declare const SLASH_EMITTER_HOSTS: readonly ["claude", "cursor", "grok", "codex"];
+export type SlashEmitterHostId = (typeof SLASH_EMITTER_HOSTS)[number];
+/** Repo-relative layout for one host’s native command/prompt files. */
+export interface HostCommandLayout {
+    readonly hostId: SlashEmitterHostId;
+    /**
+     * Repo-relative directory (posix, no trailing slash).
+     * Example: `.claude/commands`
+     */
+    readonly relativeDir: string;
+    /** Human-readable file pattern (always `{stem}.md` for v1). */
+    readonly filePattern: string;
+    /**
+     * Kind of native surface the host loads (documentation + deposit policy).
+     * Does not change file contents in v1 — all emit shared thin markdown.
+     */
+    readonly surfaceKind: "commands" | "prompts";
+}
+/**
+ * Documented host id → directory / file pattern mapping (issue #3053 AC).
+ * Frozen; additive registration only.
+ */
+export declare const HOST_COMMAND_LAYOUTS: Readonly<Record<SlashEmitterHostId, HostCommandLayout>>;
+/** One host-native file ready for deposit (#3054) or tests. */
+export interface HostEmittedFile {
+    readonly hostId: SlashEmitterHostId;
+    /** Canonical slash id from the product set. */
+    readonly logicalId: string;
+    /** Hyphen filename stem (L4). */
+    readonly filenameStem: string;
+    /** Basename including `.md`. */
+    readonly filename: string;
+    /** Repo-relative posix path, e.g. `.claude/commands/deft-continue.md`. */
+    readonly relativePath: string;
+    /** Thin-wrapper file contents (frontmatter + body). */
+    readonly contents: string;
+    readonly description: string;
+    readonly dispatchPath: string;
+}
+/** Type guard for {@link SlashEmitterHostId}. */
+export declare function isSlashEmitterHostId(value: string): value is SlashEmitterHostId;
+/** Stable list of hosts that have real emitters (no stubs). */
+export declare function listSlashEmitterHosts(): readonly SlashEmitterHostId[];
+/** Look up the documented layout for a host, or throw. */
+export declare function getHostCommandLayout(hostId: SlashEmitterHostId): HostCommandLayout;
+/**
+ * Build the repo-relative path for one IR entry under a host layout (L4 filenames).
+ */
+export declare function hostRelativePath(hostId: SlashEmitterHostId, filename: string): string;
+/**
+ * Emit host-native file records for one host from shared thin-wrapper IR.
+ *
+ * Does not redefine the L2 product table — defaults to {@link generateThinWrappers}.
+ * Contents stay thin (L5); paths use L4 hyphen names under the host layout.
+ */
+export declare function emitHostCommandFiles(hostId: SlashEmitterHostId, wrappers?: readonly ThinWrapperIR[]): readonly HostEmittedFile[];
+/**
+ * Emit for every host that has a real emitter (default: all of {@link SLASH_EMITTER_HOSTS}).
+ *
+ * Returns a map keyed by host id; each value has count === product set when using
+ * default IR.
+ */
+export declare function emitAllHostCommandFiles(hosts?: readonly SlashEmitterHostId[], wrappers?: readonly ThinWrapperIR[]): ReadonlyMap<SlashEmitterHostId, readonly HostEmittedFile[]>;
+/**
+ * Host-specific markdown reshape hook.
+ *
+ * v1: all hosts share the generator’s host-agnostic `fileMarkdown` (description +
+ * optional argument-hint + thin body). Future hosts may remap frontmatter keys
+ * here without touching the product name table.
+ */
+export declare function renderHostFileContents(_hostId: SlashEmitterHostId, wrapper: ThinWrapperIR): string;
+/** Assert emitted contents remain thin pointers (for tests and deposit validation). */
+export declare function assertThinHostEmission(files: readonly HostEmittedFile[]): void;
+//# sourceMappingURL=emitters.d.ts.map

package/dist/slash/emitters.js

@@ -0,0 +1,148 @@
+/**
+ * Per-host native command/prompt emitters (#3053 / epic #55).
+ *
+ * Maps shared thin-wrapper IR from {@link generateThinWrappers} onto each
+ * supported host’s repo-relative path layout. Pure generate-to-path records;
+ * filesystem deposit is init-deposit `writeSlashCommandDeposit` (#3054).
+ *
+ * ## Host id → output directory / file pattern
+ *
+ * | Host id | Relative directory   | Filename pattern   |
+ * |---------|----------------------|--------------------|
+ * | claude  | `.claude/commands/`  | `{hyphen-stem}.md` |
+ * | cursor  | `.cursor/commands/`  | `{hyphen-stem}.md` |
+ * | grok    | `.grok/commands/`    | `{hyphen-stem}.md` |
+ * | codex   | `.codex/prompts/`    | `{hyphen-stem}.md` |
+ *
+ * All four use the shared thin-wrapper markdown template (L5). Adding a host is
+ * an additive layout entry + optional frontmatter reshape — not a new product
+ * name table (L2 lives in product-set / generator only).
+ *
+ * ⊗ Empty stub dirs for “enabled but no emitter” (L6).
+ * ⊗ Native legacy alias files (L3).
+ */
+import { generateThinWrappers, isThinWrapperMarkdown } from "./generator.js";
+import { PRODUCT_COMMAND_COUNT } from "./product-set.js";
+/**
+ * Hosts with a real slash/prompt emitter layout (aligned with hook host ids).
+ * Default enabled set for deposit (#3054) is this list when policy opts in.
+ */
+export const SLASH_EMITTER_HOSTS = ["claude", "cursor", "grok", "codex"];
+/**
+ * Documented host id → directory / file pattern mapping (issue #3053 AC).
+ * Frozen; additive registration only.
+ */
+export const HOST_COMMAND_LAYOUTS = Object.freeze({
+    claude: Object.freeze({
+        hostId: "claude",
+        relativeDir: ".claude/commands",
+        filePattern: "{stem}.md",
+        surfaceKind: "commands",
+    }),
+    cursor: Object.freeze({
+        hostId: "cursor",
+        relativeDir: ".cursor/commands",
+        filePattern: "{stem}.md",
+        surfaceKind: "commands",
+    }),
+    grok: Object.freeze({
+        hostId: "grok",
+        relativeDir: ".grok/commands",
+        filePattern: "{stem}.md",
+        surfaceKind: "commands",
+    }),
+    codex: Object.freeze({
+        hostId: "codex",
+        relativeDir: ".codex/prompts",
+        filePattern: "{stem}.md",
+        surfaceKind: "prompts",
+    }),
+});
+/** Type guard for {@link SlashEmitterHostId}. */
+export function isSlashEmitterHostId(value) {
+    return SLASH_EMITTER_HOSTS.includes(value);
+}
+/** Stable list of hosts that have real emitters (no stubs). */
+export function listSlashEmitterHosts() {
+    return SLASH_EMITTER_HOSTS;
+}
+/** Look up the documented layout for a host, or throw. */
+export function getHostCommandLayout(hostId) {
+    const layout = HOST_COMMAND_LAYOUTS[hostId];
+    if (layout === undefined) {
+        throw new Error(`No slash emitter layout for host: ${hostId}`);
+    }
+    return layout;
+}
+/**
+ * Build the repo-relative path for one IR entry under a host layout (L4 filenames).
+ */
+export function hostRelativePath(hostId, filename) {
+    const layout = getHostCommandLayout(hostId);
+    // Defensive: refuse path separators in filename so deposit cannot escape relativeDir.
+    if (filename.includes("/") || filename.includes("\\") || filename.includes("..")) {
+        throw new Error(`Invalid command filename for host emit: ${filename}`);
+    }
+    return `${layout.relativeDir}/${filename}`;
+}
+/**
+ * Emit host-native file records for one host from shared thin-wrapper IR.
+ *
+ * Does not redefine the L2 product table — defaults to {@link generateThinWrappers}.
+ * Contents stay thin (L5); paths use L4 hyphen names under the host layout.
+ */
+export function emitHostCommandFiles(hostId, wrappers = generateThinWrappers()) {
+    if (!isSlashEmitterHostId(hostId)) {
+        throw new Error(`Unknown slash emitter host: ${String(hostId)}`);
+    }
+    // Snapshot layout once; additive hosts must register before emit.
+    getHostCommandLayout(hostId);
+    return wrappers.map((w) => {
+        const contents = renderHostFileContents(hostId, w);
+        return {
+            hostId,
+            logicalId: w.logicalId,
+            filenameStem: w.filenameStem,
+            filename: w.filename,
+            relativePath: hostRelativePath(hostId, w.filename),
+            contents,
+            description: w.description,
+            dispatchPath: w.dispatchPath,
+        };
+    });
+}
+/**
+ * Emit for every host that has a real emitter (default: all of {@link SLASH_EMITTER_HOSTS}).
+ *
+ * Returns a map keyed by host id; each value has count === product set when using
+ * default IR.
+ */
+export function emitAllHostCommandFiles(hosts = SLASH_EMITTER_HOSTS, wrappers = generateThinWrappers()) {
+    const out = new Map();
+    for (const hostId of hosts) {
+        out.set(hostId, emitHostCommandFiles(hostId, wrappers));
+    }
+    return out;
+}
+/**
+ * Host-specific markdown reshape hook.
+ *
+ * v1: all hosts share the generator’s host-agnostic `fileMarkdown` (description +
+ * optional argument-hint + thin body). Future hosts may remap frontmatter keys
+ * here without touching the product name table.
+ */
+export function renderHostFileContents(_hostId, wrapper) {
+    return wrapper.fileMarkdown;
+}
+/** Assert emitted contents remain thin pointers (for tests and deposit validation). */
+export function assertThinHostEmission(files) {
+    if (files.length !== PRODUCT_COMMAND_COUNT) {
+        throw new Error(`Expected ${PRODUCT_COMMAND_COUNT} host command files, got ${files.length}`);
+    }
+    for (const f of files) {
+        if (!isThinWrapperMarkdown(f.contents, f.dispatchPath)) {
+            throw new Error(`Non-thin emission for ${f.relativePath}`);
+        }
+    }
+}
+//# sourceMappingURL=emitters.js.map

package/dist/slash/generator.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Host-agnostic thin-wrapper generator for product slash commands (#3052 / epic #55).
+ *
+ * Emits IR + markdown templates that per-host emitters (#3053) format into native
+ * command/prompt/workflow files. Wrappers stay thin (L5): frontmatter description +
+ * short dispatch pointer — never inlined strategy/skill/commands.md bodies.
+ *
+ * ## Token / context budgets (from #55 token design rules)
+ *
+ * | When | Target |
+ * |---|---|
+ * | Idle (user never invokes `/deft…`) | ~0 from command files |
+ * | Catalog (`/` menu: name + description × N) | ≤ ~1k tok for the product set |
+ * | Single invoke | ~40–100 tok thin wrapper body |
+ * | After dispatch | cost of the target strategy/skill (unchanged) |
+ *
+ * Multi-host deposit does not multiply tokens in one session: each host reads only
+ * its own command directory. Real spend is the loaded artifact after invoke.
+ */
+import { logicalIdToFilename, logicalIdToFilenameStem, PRODUCT_COMMAND_COUNT, type ProductCommand } from "./product-set.js";
+/** Rough UTF-8 bytes-per-token estimate (aligned with agents-md-budget). */
+export declare const BYTES_PER_TOKEN_ESTIMATE = 4;
+/** L5: invoke wrapper body budget (≈100 tokens). */
+export declare const MAX_WRAPPER_BODY_TOKENS = 100;
+/** Per-command catalog description hard cap for tests (order-of-magnitude 20–50). */
+export declare const MAX_DESCRIPTION_TOKENS = 50;
+/** Full product-set description catalog budget (≤ ~1k tok). */
+export declare const MAX_CATALOG_TOKENS = 1000;
+/**
+ * Host-agnostic intermediate representation for one thin wrapper.
+ *
+ * Emitters consume this shape without re-listing product names.
+ */
+export interface ThinWrapperIR {
+    /** Canonical slash id, e.g. `/deft:directive:run:interview`. */
+    readonly logicalId: string;
+    /** Hyphen stem without extension. */
+    readonly filenameStem: string;
+    /** On-disk filename including `.md`. */
+    readonly filename: string;
+    /** Catalog description (host frontmatter `description`). */
+    readonly description: string;
+    readonly dispatchKind: ProductCommand["dispatchKind"];
+    /** Content-root-relative primary load path. */
+    readonly dispatchPath: string;
+    readonly argumentHint?: string;
+    /** Body markdown only (no frontmatter). */
+    readonly bodyMarkdown: string;
+    /** Full file: YAML frontmatter + body (host-agnostic template). */
+    readonly fileMarkdown: string;
+    /** Estimated body tokens (UTF-8 bytes / {@link BYTES_PER_TOKEN_ESTIMATE}). */
+    readonly estimatedBodyTokens: number;
+    /** Estimated description tokens. */
+    readonly estimatedDescriptionTokens: number;
+}
+/** Aggregate token budget report for the product set. */
+export interface TokenBudgetReport {
+    readonly commandCount: number;
+    readonly catalogTokens: number;
+    readonly maxBodyTokens: number;
+    readonly maxDescriptionTokens: number;
+    readonly withinBodyBudget: boolean;
+    readonly withinDescriptionBudget: boolean;
+    readonly withinCatalogBudget: boolean;
+    readonly ok: boolean;
+}
+/** Estimate tokens from a UTF-8 string (bytes / 4). */
+export declare function estimateTokens(text: string): number;
+/**
+ * Render the thin body only: short dispatch pointer, no inlined target content.
+ *
+ * Keeps invoke cost in the ~40–100 token band (L5).
+ */
+export declare function renderThinWrapperBody(command: ProductCommand): string;
+/**
+ * Render host-agnostic file markdown: description frontmatter + thin body.
+ *
+ * Per-host emitters may re-shape frontmatter keys; the body semantics stay shared.
+ */
+export declare function renderThinWrapperFile(command: ProductCommand): string;
+/** Build {@link ThinWrapperIR} for one product command. */
+export declare function generateThinWrapper(command: ProductCommand): ThinWrapperIR;
+/**
+ * Generate thin wrappers for the full L2 product set (stable order, count === 13).
+ *
+ * This is the primary API for #3053 emitters.
+ */
+export declare function generateThinWrappers(commands?: readonly ProductCommand[]): readonly ThinWrapperIR[];
+/** Measure catalog + per-wrapper body budgets for the generated set. */
+export declare function measureTokenBudget(wrappers?: readonly ThinWrapperIR[]): TokenBudgetReport;
+/**
+ * Structural check that a wrapper file looks like a thin pointer template.
+ * Used by unit tests and available to emitters for deposit validation.
+ */
+export declare function isThinWrapperMarkdown(fileMarkdown: string, dispatchPath: string): boolean;
+/** Re-export mapping helpers for emitter convenience without a second import path. */
+export { logicalIdToFilename, logicalIdToFilenameStem, PRODUCT_COMMAND_COUNT };
+//# sourceMappingURL=generator.d.ts.map