@winspan/claude-forge 8.54.4 → 9.2.0

package/dist/core/storage/workflow-recommendations.js

@@ -0,0 +1,274 @@
+/**
+ * WorkflowRecommendationsOperations — workflow_recommendations 表读写 (v9.x Phase 5)
+ *
+ * Phase 5 fact table for UserPromptSubmitHandler step 5 (workflow recommender).
+ * Writes are issued by `WorkflowRecommender` on every prompt where a workflow
+ * rule matches. The Phase 5 feature flag `workflow_recommender.enabled`
+ * (default OFF) gates whether the recommender even runs — when the flag is
+ * OFF no rows are written and no PreToolUse mismatch denies happen.
+ *
+ * outcome state machine (see schema.sql):
+ *   pending ──spawn matching──▶ accepted
+ *           ──spawn w/ bypass──▶ bypassed
+ *           ──user "skip"────▶ rejected
+ *           ──Stop hook fires──▶ ignored
+ *
+ * 设计要点（仿 tool-intercepts.ts 模式）：
+ *   - 所有 timestamp 字段 ISO 8601 字符串（同 events 表）
+ *   - matched_keywords 通过 JSON.stringify(string[]) 序列化；为 null 表示
+ *     fallback rule（如 bmad-default 没有显式 keyword 匹配）
+ *   - `since` 用 ISO 字符串比较（SQLite 文本时间戳天然支持 lexicographic order）
+ *   - update 操作冪等；同一 id 重复 mark 不抛错（最后一次 outcome 生效）
+ */
+import { decodeToolInput } from './codec/tool-input-codec.js';
+export class WorkflowRecommendationsOperations {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /** Insert a new row; returns the assigned id. outcome defaults to 'pending'. */
+    writeRecommendation(record) {
+        const matched = record.matched_keywords && record.matched_keywords.length > 0
+            ? JSON.stringify(record.matched_keywords)
+            : null;
+        const result = this.db
+            .prepare(`INSERT INTO workflow_recommendations (
+           session_id, timestamp, rule_id, matched_keywords,
+           recommended_workflow, recommended_agent_type, reason,
+           outcome, source
+         ) VALUES (
+           @session_id, @timestamp, @rule_id, @matched_keywords,
+           @recommended_workflow, @recommended_agent_type, @reason,
+           @outcome, @source
+         )`)
+            .run({
+            session_id: record.session_id,
+            timestamp: record.timestamp,
+            rule_id: record.rule_id,
+            matched_keywords: matched,
+            recommended_workflow: record.recommended_workflow,
+            recommended_agent_type: record.recommended_agent_type,
+            reason: record.reason ?? null,
+            outcome: record.outcome ?? 'pending',
+            source: record.source ?? 'workflow_classifier',
+        });
+        return Number(result.lastInsertRowid);
+    }
+    /**
+     * Filter rows. Results are ordered by `timestamp DESC` so callers wanting
+     * "the most recent pending" can take `[0]`.
+     */
+    queryRecommendations(filter = {}) {
+        const conditions = [];
+        const params = [];
+        if (filter.session_id) {
+            conditions.push('session_id = ?');
+            params.push(filter.session_id);
+        }
+        if (filter.outcome) {
+            conditions.push('outcome = ?');
+            params.push(filter.outcome);
+        }
+        if (filter.rule_id) {
+            conditions.push('rule_id = ?');
+            params.push(filter.rule_id);
+        }
+        if (filter.source) {
+            conditions.push('source = ?');
+            params.push(filter.source);
+        }
+        if (filter.since) {
+            conditions.push('timestamp >= ?');
+            params.push(filter.since);
+        }
+        const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+        const limit = filter.limit ?? 100;
+        params.push(limit);
+        const sql = `SELECT * FROM workflow_recommendations ${where} ORDER BY timestamp DESC LIMIT ?`;
+        return this.db.prepare(sql).all(...params);
+    }
+    /**
+     * Mark a single recommendation row's outcome. `outcome_at` is stamped with
+     * the current ISO timestamp; callers MAY override via the optional arg.
+     */
+    updateOutcome(id, outcome, outcome_at) {
+        const ts = outcome_at ?? new Date().toISOString();
+        this.db
+            .prepare(`UPDATE workflow_recommendations
+         SET outcome = ?, outcome_at = ?
+         WHERE id = ?`)
+            .run(outcome, ts, id);
+    }
+    /**
+     * Bulk-mark every still-pending row for a session as 'ignored'. Used by
+     * StopHandler at session end so dashboards don't carry forever-pending rows.
+     * Returns the number of rows updated.
+     */
+    markPendingIgnoredBySession(session_id, outcome_at) {
+        const ts = outcome_at ?? new Date().toISOString();
+        const result = this.db
+            .prepare(`UPDATE workflow_recommendations
+         SET outcome = 'ignored', outcome_at = ?
+         WHERE session_id = ? AND outcome = 'pending'`)
+            .run(ts, session_id);
+        return Number(result.changes);
+    }
+    /**
+     * Bulk-mark every still-pending row for a session as 'rejected'. Used by
+     * UserPromptHandler when the user prompt contains explicit override
+     * keywords ("skip workflow" / "不要 harness" / etc.).
+     */
+    markPendingRejectedBySession(session_id, outcome_at) {
+        const ts = outcome_at ?? new Date().toISOString();
+        const result = this.db
+            .prepare(`UPDATE workflow_recommendations
+         SET outcome = 'rejected', outcome_at = ?
+         WHERE session_id = ? AND outcome = 'pending'`)
+            .run(ts, session_id);
+        return Number(result.changes);
+    }
+    /**
+     * Phase 2d pipeline-view batch helper. Pulls every workflow_recommendations
+     * row for the given session IDs in a single `IN (?,?,...)` query, ordered
+     * ASC by timestamp so the rollup layer can scan forward.
+     */
+    queryBySessions(sessionIds) {
+        if (sessionIds.length === 0)
+            return [];
+        const placeholders = sessionIds.map(() => '?').join(',');
+        const sql = `SELECT * FROM workflow_recommendations
+                 WHERE session_id IN (${placeholders})
+                 ORDER BY timestamp ASC`;
+        return this.db.prepare(sql).all(...sessionIds);
+    }
+    /** Convenience: how many rows for this session (any outcome). */
+    countBySession(session_id) {
+        const row = this.db
+            .prepare(`SELECT COUNT(*) AS c FROM workflow_recommendations WHERE session_id = ?`)
+            .get(session_id);
+        return row.c;
+    }
+    /**
+     * Kanban-board projection (v9.x post-Phase 5).
+     *
+     * Returns one row per recommendation with the joined session outcome,
+     * the first user_prompt for that session, the most recent Task spawn's
+     * subagent_type, plus a comma-list of KB page names that were injected
+     * for the same session. The web layer buckets these into 4 lanes
+     * (prompted / recommended / spawned / done).
+     *
+     * Pure-SQL join — keeps the per-row cost flat instead of N round-trips
+     * from the route layer. `windowDays` is clamped by the caller; `project`
+     * is an exact match (NULL-safe via "x OR 1=1" pattern when omitted).
+     */
+    queryAgentBoardCards(opts) {
+        const limit = Math.min(Math.max(opts.limit ?? 80, 1), 500);
+        const sinceMs = Date.now() - opts.windowDays * 86400_000;
+        const since = new Date(sinceMs).toISOString();
+        const params = [since];
+        let projectFilter = '';
+        if (opts.projectPath) {
+            projectFilter = 'AND s.project_path = ?';
+            params.push(opts.projectPath);
+        }
+        params.push(limit);
+        // Top-level SQL: every column EXCEPT spawn_subagent_type (which used a
+        // correlated `json_extract(e.tool_input, ...)` sub-SELECT incompatible
+        // with the gzip codec). We populate spawn_subagent_type in JS via a
+        // single batched fetch of candidate PostToolUse Task/Agent events for
+        // every (session, rec_timestamp) pair, then pick the earliest per rec.
+        const sql = `
+      SELECT
+        wf.id              AS rec_id,
+        wf.session_id      AS session_id,
+        wf.timestamp       AS timestamp,
+        wf.recommended_agent_type AS recommended_agent_type,
+        wf.recommended_workflow   AS recommended_workflow,
+        wf.outcome         AS rec_outcome,
+        wf.outcome_at      AS outcome_at,
+        wf.reason          AS reason,
+        wf.rule_id         AS rule_id,
+        wf.matched_keywords AS matched_keywords,
+        s.first_prompt     AS first_prompt,
+        s.start_time       AS session_start,
+        COALESCE(s.end_time, s.last_event_time, s.start_time) AS session_end,
+        s.outcome          AS session_outcome,
+        s.project_path     AS project_path,
+        (SELECT GROUP_CONCAT(inj.metadata_json, '||')
+           FROM injections inj
+          WHERE inj.session_id = wf.session_id
+            AND inj.source_handler = 'UserPromptSubmitHandler:kb') AS kb_meta_concat
+      FROM workflow_recommendations wf
+      LEFT JOIN sessions s ON s.session_id = wf.session_id
+      WHERE wf.timestamp >= ?
+        ${projectFilter}
+      ORDER BY wf.timestamp DESC
+      LIMIT ?
+    `;
+        const baseRows = this.db.prepare(sql).all(...params);
+        if (baseRows.length === 0)
+            return baseRows;
+        // ── spawn_subagent_type via codec (JS-side) ────────────────────────
+        //
+        // Strategy: pull every PostToolUse Task/Agent event (with raw tool_input)
+        // for the candidate sessions within the recommendation window, then for
+        // each recommendation row find the earliest event whose timestamp >= rec
+        // timestamp and decode its tool_input.subagent_type. Single SELECT + JS
+        // walk; avoids N correlated queries.
+        const sessionIdSet = new Set(baseRows.map(r => r.session_id));
+        const sessionIds = Array.from(sessionIdSet);
+        const sessionPh = sessionIds.map(() => '?').join(',');
+        const spawnEvents = this.db.prepare(`
+      SELECT session_id, timestamp, tool_input FROM events
+       WHERE session_id IN (${sessionPh})
+         AND hook_type = 'PostToolUse'
+         AND tool_name IN ('Task', 'Agent')
+         AND tool_input IS NOT NULL
+       ORDER BY session_id, timestamp ASC
+    `).all(...sessionIds);
+        // Bucket by session for the per-rec earliest-after lookup.
+        const eventsBySession = new Map();
+        for (const ev of spawnEvents) {
+            let list = eventsBySession.get(ev.session_id);
+            if (!list) {
+                list = [];
+                eventsBySession.set(ev.session_id, list);
+            }
+            list.push(ev);
+        }
+        for (const rec of baseRows) {
+            const events = eventsBySession.get(rec.session_id);
+            if (!events || events.length === 0) {
+                rec.spawn_subagent_type = null;
+                continue;
+            }
+            // events are pre-sorted ASC by timestamp; find the first one >= rec.timestamp
+            let chosen = null;
+            for (const ev of events) {
+                if (ev.timestamp >= rec.timestamp) {
+                    chosen = ev;
+                    break;
+                }
+            }
+            if (!chosen) {
+                rec.spawn_subagent_type = null;
+                continue;
+            }
+            try {
+                const decoded = decodeToolInput(chosen.tool_input);
+                if (decoded && typeof decoded === 'object' && !Array.isArray(decoded)) {
+                    const v = decoded.subagent_type;
+                    rec.spawn_subagent_type = typeof v === 'string' ? v : null;
+                }
+                else {
+                    rec.spawn_subagent_type = null;
+                }
+            }
+            catch {
+                rec.spawn_subagent_type = null;
+            }
+        }
+        return baseRows;
+    }
+}
+//# sourceMappingURL=workflow-recommendations.js.map

package/dist/core/storage/workflow-recommendations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-recommendations.js","sourceRoot":"","sources":["../../../src/core/storage/workflow-recommendations.ts"],"names":[],"mappings":"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"}

package/dist/core/types.d.ts

@@ -93,13 +93,113 @@ export declare function isUserPromptSubmit(e: ForgeEvent): e is UserPromptSubmit
 export declare function isNotification(e: ForgeEvent): e is NotificationEvent & ForgeEvent;
 export declare function isStop(e: ForgeEvent): e is StopEvent & ForgeEvent;
 /**
- * Hook execution result
+ * Closed enum of agent identifiers the IntentEngine is allowed to suggest.
+ *
+ * - The first 8 names map 1:1 to `.claude/agents/<name>.md` files shipped in
+ *   the repo. Adding a new agent requires updating BOTH this enum AND the
+ *   `.claude/agents/` directory; the startup check enforces the sync.
+ * - `'Explore'` and `'general-purpose'` are Claude Code built-ins — they have
+ *   no `.md` file but are valid `subagent_type` values.
+ * - `'none'` covers workflow_type ∈ {'meta', 'explore'} where no agent should
+ *   be spawned (main thread handles the prompt directly).
+ */
+export type SuggestedAgent = 'coder' | 'planner' | 'decision-maker' | 'refactor-specialist' | 'harness-hotfix' | 'harness-debug-full' | 'hybrid-feature-with-safety' | 'doc-reviewer' | 'verify-agent' | 'Explore' | 'general-purpose' | 'none';
+/** All agent names that MUST have a corresponding `.claude/agents/*.md` file. */
+export declare const REQUIRED_AGENT_FILES: readonly SuggestedAgent[];
+/** Coarse workflow buckets returned by the IntentEngine. */
+export type WorkflowType = 'bmad' | 'harness-hotfix' | 'harness-debug' | 'refactor' | 'hybrid' | 'explore' | 'meta';
+/**
+ * Fallback layer that produced an IntentClassification. `L1` means the LLM
+ * main path succeeded; `L2`-`L6` denote progressive degradation. Persisted
+ * in `injections.source_handler` as `UserPromptSubmitHandler:intent_fallback:L{N}`
+ * (or `UserPromptSubmitHandler:intent` for L1) so dashboards can chart the
+ * health of the LLM path vs. fallback usage.
+ */
+export type FallbackLayer = 'L1' | 'L2' | 'L3' | 'L4' | 'L5' | 'L6';
+export interface IntentClassification {
+    /** ≤80 char summary in the prompt's primary language. */
+    intent_summary: string;
+    workflow_type: WorkflowType;
+    /** 0..1; lower values trigger fallback voting (see spec §3.4.1). */
+    confidence: number;
+    suggested_agent: SuggestedAgent;
+    /** ≤200 char human-readable reasoning, surfaced in the dashboard. */
+    reasoning: string;
+    /** Tokens extracted from the prompt; threaded into the KB query. */
+    keywords: string[];
+    /** Which layer produced this result. Always set by IntentEngine. */
+    layer: FallbackLayer;
+    /** Optional structured diagnostics for the dashboard. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result returned by `SpecApproval.verify()` — the UserPromptHandler maps each
+ * outcome to a different systemMessage. `'ok'` is the only happy path; all
+ * others surface a hint and let downstream pipeline steps run normally.
+ */
+export type SpecApprovalOutcome = 'ok' | 'not_found' | 'expired' | 'already_approved' | 'wrong_session';
+export interface SpecApprovalResult {
+    outcome: SpecApprovalOutcome;
+    /**
+     * C1 (spec 0854): normalised SpecLikeRow carried from the decisions
+     * kind='spec' row. Exposes the field names (spec_path/token/intent_json/
+     * status) the formatters key off.
+     */
+    row?: SpecApprovalRowLike;
+}
+/**
+ * The subset of fields the approval formatter + spec-gate consume from an
+ * approval row. decisions' SpecLikeRow satisfies this (C1). Declared here (not
+ * importing SpecLikeRow from storage) to keep core/types.ts free of
+ * storage-layer imports.
+ */
+export interface SpecApprovalRowLike {
+    spec_path: string;
+    token: string;
+    intent_json: string;
+    status: string;
+    approved_at?: string | null;
+}
+/**
+ * Claude Code hook-specific output sub-types.
+ *
+ * Spec 1944 (decision-hint chain fix, 2026-05-28): UserPromptSubmit hooks must
+ * write injection text under `hookSpecificOutput.additionalContext` for the
+ * main thread to see it — the top-level `systemMessage` is silently dropped by
+ * Claude Code on the UserPromptSubmit path. PreToolUse keeps its own sub-type
+ * with `permissionDecision` + `permissionDecisionReason`.
+ *
+ * See https://docs.claude.com/en/docs/claude-code/hooks
+ */
+export interface UserPromptSubmitHookOutput {
+    hookEventName: 'UserPromptSubmit';
+    additionalContext: string;
+}
+export interface PreToolUseHookOutput {
+    hookEventName: 'PreToolUse';
+    permissionDecision: 'allow' | 'deny' | 'ask' | 'defer';
+    permissionDecisionReason?: string;
+}
+/**
+ * Hook execution result.
+ *
+ * Spec 1944: `hookSpecificOutput` carries the protocol-compliant payload.
+ * Existing top-level `systemMessage` / `additionalContext` are retained for
+ * backward compat and for PreToolUse paths that still use them; new
+ * UserPromptSubmit injections SHOULD double-fill `hookSpecificOutput` (R7
+ * mitigation) so older Claude Code releases still see the text via the
+ * legacy field while compliant releases pick up the new shape.
  */
 export interface HookResult {
     allow: boolean;
     reason?: string;
+    /**
+     * @deprecated UserPromptSubmit path: silently dropped by Claude Code; use
+     * `hookSpecificOutput.additionalContext` instead. PreToolUse still honors it.
+     */
     systemMessage?: string;
     additionalContext?: string;
+    hookSpecificOutput?: UserPromptSubmitHookOutput | PreToolUseHookOutput;
 }
 /**
  * Security configuration
@@ -112,14 +212,19 @@ export interface SecurityConfig {
 }
 /**
  * Configuration structure
+ *
+ * D R-D (2026-05-29, spec 0902 / decision f5a5b030): the legacy `ai.*` group
+ * + `skill_matching.api_key` field were removed from this interface. All AI
+ * flows (CLAUDE.md generation, Knowledge build, Patch preview, Skill
+ * distillation, IntentEngine) now shell out to the local `claude` CLI
+ * subprocess (sub-spec A/B/C R-B + D R-A/R-B), which uses the user's Claude
+ * Code OAuth keychain — daemon does not hold an `ANTHROPIC_API_KEY` any more.
+ *
+ * `ConfigManager.get()` silently ignores any `ai:` / `skill_matching:` block
+ * left in `~/.claude-forge/config.yaml`; daemon startup still emits a
+ * deprecation warn pointing users to delete them.
  */
 export interface ForgeConfig {
-    ai: {
-        api_key: string;
-        model: string;
-        base_url?: string;
-        provider: string;
-    };
     storage: {
         path: string;
         max_size_mb: number;
@@ -128,16 +233,6 @@ export interface ForgeConfig {
         enabled: boolean;
         port: number;
     };
-    /**
-     * @deprecated Use `ai.api_key` instead. This field is kept for backward
-     * compatibility with config.yaml files generated by older `cf init` runs;
-     * daemon currently falls back to it when `ai.api_key` is empty. Will be
-     * removed in a future major release.
-     */
-    skill_matching?: {
-        /** @deprecated Use top-level `ai.api_key`. */
-        api_key?: string;
-    };
     security?: SecurityConfig;
 }
 export {};

package/dist/core/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"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"}

package/dist/core/types.js

@@ -22,4 +22,16 @@ export function isNotification(e) {
 export function isStop(e) {
     return e.hook_type === 'Stop';
 }
+/** All agent names that MUST have a corresponding `.claude/agents/*.md` file. */
+export const REQUIRED_AGENT_FILES = [
+    'coder',
+    'planner',
+    'decision-maker',
+    'refactor-specialist',
+    'harness-hotfix',
+    'harness-debug-full',
+    'hybrid-feature-with-safety',
+    'doc-reviewer',
+    'verify-agent',
+];
 //# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AA4GA,4EAA4E;AAC5E,6EAA6E;AAC7E,qEAAqE;AACrE,4DAA4D;AAE5D,MAAM,UAAU,YAAY,CAAC,CAAa;IACxC,OAAO,CAAC,CAAC,SAAS,KAAK,YAAY;WAC9B,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ;WAC/B,CAAC,CAAC,UAAU,KAAK,SAAS,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,CAAa;IACzC,OAAO,CAAC,CAAC,SAAS,KAAK,aAAa;WAC/B,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ;WAC/B,CAAC,CAAC,UAAU,KAAK,SAAS;WAC1B,CAAC,CAAC,WAAW,KAAK,SAAS,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,CAAa;IAC9C,OAAO,CAAC,CAAC,SAAS,KAAK,kBAAkB,IAAI,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ,CAAC;AACjF,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,CAAa;IAC1C,OAAO,CAAC,CAAC,SAAS,KAAK,cAAc,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,CAAa;IAClC,OAAO,CAAC,CAAC,SAAS,KAAK,MAAM,CAAC;AAChC,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AA4GA,4EAA4E;AAC5E,6EAA6E;AAC7E,qEAAqE;AACrE,4DAA4D;AAE5D,MAAM,UAAU,YAAY,CAAC,CAAa;IACxC,OAAO,CAAC,CAAC,SAAS,KAAK,YAAY;WAC9B,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ;WAC/B,CAAC,CAAC,UAAU,KAAK,SAAS,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,CAAa;IACzC,OAAO,CAAC,CAAC,SAAS,KAAK,aAAa;WAC/B,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ;WAC/B,CAAC,CAAC,UAAU,KAAK,SAAS;WAC1B,CAAC,CAAC,WAAW,KAAK,SAAS,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,CAAa;IAC9C,OAAO,CAAC,CAAC,SAAS,KAAK,kBAAkB,IAAI,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ,CAAC;AACjF,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,CAAa;IAC1C,OAAO,CAAC,CAAC,SAAS,KAAK,cAAc,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,CAAa;IAClC,OAAO,CAAC,CAAC,SAAS,KAAK,MAAM,CAAC;AAChC,CAAC;AAiCD,iFAAiF;AACjF,MAAM,CAAC,MAAM,oBAAoB,GAA8B;IAC7D,OAAO;IACP,SAAS;IACT,gBAAgB;IAChB,qBAAqB;IACrB,gBAAgB;IAChB,oBAAoB;IACpB,4BAA4B;IAC5B,cAAc;IACd,cAAc;CACN,CAAC"}

package/dist/core/utils/backup.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Timestamped backup-directory utility.
+ *
+ * Several apply-style flows need to materialise a timestamped backup
+ * directory before overwriting files in place:
+ *   • `src/knowledge/builder.ts` (applyPages) — .forge-knowledge/
+ *
+ * Shared shape:
+ *   1. Compute a timestamp slug from `new Date()`.
+ *   2. Resolve the path `baseDir/<slug>` — if it already exists, append
+ *      `-2`, `-3`, ... until an unused name is found.
+ *   3. `mkdir -p` the resolved path.
+ *   4. Return the path so the caller can copy whatever files it wants into
+ *      it (the actual copy logic stays at the call site because the two
+ *      consumers have different file-selection rules).
+ *
+ * Step 2 is optional via `conflictSuffix: 'never'` for call sites whose
+ * current behavior was "no collision handling, just mkdir -p" — preserves
+ * pre-refactor byte-identical output.
+ */
+/**
+ * Default timestamp slug formatter: local-time `YYYYMMDD-HHMM`.
+ *
+ * Local (not UTC) by design — matches the post-revert decision in commit
+ * 640d271a so backup directory names line up with the developer's wall clock.
+ */
+export declare function defaultTimestampSlug(now?: Date): string;
+export interface CreateTimestampedBackupOptions {
+    /** Directory under which the timestamped backup dir is created. */
+    baseDir: string;
+    /**
+     * How to produce the slug string. Default: {@link defaultTimestampSlug}.
+     * Pass a custom function to mirror legacy formats (e.g. ISO-replace in
+     * knowledge/builder.ts before unification).
+     */
+    tsFormatter?: () => string;
+    /**
+     * Collision handling:
+     *   • `'suffix'` (default) — if `baseDir/<slug>` exists, try
+     *     `baseDir/<slug>-2`, `-3`, ... until an unused name is found.
+     *   • `'never'` — skip the collision probe; just mkdir -p the bare slug
+     *     path. Use this when the caller's pre-refactor behavior was to
+     *     merge into an existing directory of the same timestamp (e.g.
+     *     `knowledge/builder.ts` historical behavior).
+     */
+    conflictSuffix?: 'suffix' | 'never';
+    /**
+     * If false, only the path/slug is computed — no `mkdir` is performed.
+     * Defaults to `true`. Set false when the caller wants to defer directory
+     * creation until it actually has something to copy (matches
+     * `knowledge/builder.ts:applyPages` historical "lazy mkdir" behavior).
+     *
+     * Note: when `mkdir: false` and `conflictSuffix: 'suffix'`, the collision
+     * probe still runs against the filesystem so the returned slug still
+     * dodges existing directories.
+     */
+    mkdir?: boolean;
+}
+export interface CreateTimestampedBackupResult {
+    /** Absolute (or caller-relative) path of the newly created backup directory. */
+    path: string;
+    /** The slug actually used (after any `-2/-3` suffix resolution). */
+    slug: string;
+}
+/**
+ * Resolve + create a timestamped backup directory under `baseDir`.
+ *
+ * The caller copies whatever files it wants into `result.path` afterwards.
+ * Returns the resolved path and final slug. Throws on `fs.mkdir` failure
+ * (does NOT swallow filesystem errors).
+ */
+export declare function createTimestampedBackup(options: CreateTimestampedBackupOptions): Promise<CreateTimestampedBackupResult>;
+/**
+ * Synchronous counterpart of {@link createTimestampedBackup} for call sites
+ * that must remain non-async (e.g. `knowledge/builder.ts:applyPages`).
+ *
+ * Behavior is identical to the async version, just uses `existsSync` +
+ * `mkdirSync` instead of `fs.access` / `fs.mkdir`.
+ */
+export declare function createTimestampedBackupSync(options: CreateTimestampedBackupOptions): CreateTimestampedBackupResult;
+//# sourceMappingURL=backup.d.ts.map

package/dist/core/utils/backup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.d.ts","sourceRoot":"","sources":["../../../src/core/utils/backup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,IAAiB,GAAG,MAAM,CAOnE;AAED,MAAM,WAAW,8BAA8B;IAC7C,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,MAAM,CAAC;IAC3B;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IACpC;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,6BAA6B;IAC5C,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,6BAA6B,CAAC,CA6BxC;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,8BAA8B,GACtC,6BAA6B,CAqB/B"}