crewly 1.8.4 → 1.8.5

package/dist/backend/backend/src/services/wiki/schema-loader.service.js

@@ -0,0 +1,183 @@
+/**
+ * SCHEMA.md loader + validator + frozen-path gate.
+ *
+ * Reads `<vault>/SCHEMA.md` (pure YAML inside a .md container), validates
+ * shape against `VaultSchema`, and exposes the frozen-path predicate used
+ * by `wiki-lint` to refuse restructure operations on OSS-pinned folders.
+ *
+ * Per v2.1 spec §2 (Hybrid folder architecture) — the `frozen: true` block
+ * is a HARD contract: any lint or ingest operation that targets a frozen
+ * path MUST fail closed.
+ *
+ * @module services/wiki/schema-loader.service
+ */
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import { parse as parseYAML } from 'yaml';
+/** Standard schema filename inside any vault root. */
+export const SCHEMA_FILENAME = 'SCHEMA.md';
+/**
+ * Loads + validates a vault's SCHEMA.md. Stateless — instantiate once
+ * per service or use the static helper.
+ */
+export class SchemaLoaderService {
+    /**
+     * Load and validate the SCHEMA.md inside a vault directory.
+     *
+     * @param vaultPath - Absolute path to the vault root (the directory
+     *   containing SCHEMA.md). Must be absolute.
+     * @returns Validated VaultSchema.
+     * @throws If vaultPath is not absolute, SCHEMA.md is missing, YAML
+     *   parsing fails, or the parsed object is shape-invalid.
+     */
+    async load(vaultPath) {
+        if (!path.isAbsolute(vaultPath)) {
+            throw new Error(`SchemaLoader: vaultPath must be absolute, got "${vaultPath}"`);
+        }
+        const schemaPath = path.join(vaultPath, SCHEMA_FILENAME);
+        let raw;
+        try {
+            raw = await fs.readFile(schemaPath, 'utf8');
+        }
+        catch (err) {
+            throw new Error(`SchemaLoader: SCHEMA.md not found at ${schemaPath} (${err.message})`);
+        }
+        let parsed;
+        try {
+            parsed = parseYAML(raw);
+        }
+        catch (err) {
+            throw new Error(`SchemaLoader: invalid YAML in ${schemaPath}: ${err.message}`);
+        }
+        return this.validate(parsed, schemaPath);
+    }
+    /**
+     * Determine whether a path inside a vault is frozen (OSS-pinned).
+     *
+     * Used by `wiki-lint` and `wiki-ingest` to refuse restructure / write
+     * operations. Comparison is by leading path segment — e.g. `sop/foo.md`
+     * is frozen if `sop/` is declared frozen.
+     *
+     * @param schema - The vault's parsed schema.
+     * @param relativePath - Path relative to vault root, e.g. `sop/team-1.md`.
+     * @returns true if the path lives under a frozen folder.
+     */
+    isFrozenPath(schema, relativePath) {
+        const normalized = relativePath.replace(/^[/\\]+/, '');
+        return schema.hardcoded.some((folder) => {
+            // Match either exact folder or anything beneath it.
+            const folderName = folder.path.replace(/[/\\]+$/, '');
+            return normalized === folderName || normalized.startsWith(`${folderName}/`);
+        });
+    }
+    /**
+     * Return every frozen folder path declared in a schema. Convenience for
+     * lint reports.
+     */
+    getFrozenPaths(schema) {
+        return schema.hardcoded.map((f) => f.path);
+    }
+    // ---------------------------------------------------------------------------
+    // Validation
+    // ---------------------------------------------------------------------------
+    validate(parsed, source) {
+        if (typeof parsed !== 'object' || parsed === null) {
+            throw new Error(`SchemaLoader: ${source} did not parse to an object`);
+        }
+        const p = parsed;
+        const vault_scope = this.requireScope(p.vault_scope, source);
+        const vault_id = this.requireString(p.vault_id, 'vault_id', source);
+        const hardcoded = this.requireHardcoded(p.hardcoded, source);
+        const llm_curated = this.requireLlmCurated(p.llm_curated, source);
+        const write_policy = this.requireWritePolicy(p.write_policy, source);
+        return { vault_scope, vault_id, hardcoded, llm_curated, write_policy };
+    }
+    requireScope(raw, source) {
+        if (raw !== 'team' && raw !== 'project' && raw !== 'global') {
+            throw new Error(`SchemaLoader: ${source} has invalid vault_scope "${raw}" — expected "team" | "project" | "global"`);
+        }
+        return raw;
+    }
+    requireString(raw, field, source) {
+        if (typeof raw !== 'string' || raw.length === 0) {
+            throw new Error(`SchemaLoader: ${source} missing or empty "${field}"`);
+        }
+        return raw;
+    }
+    requireHardcoded(raw, source) {
+        if (!Array.isArray(raw)) {
+            throw new Error(`SchemaLoader: ${source} "hardcoded" must be an array`);
+        }
+        return raw.map((entry, idx) => {
+            if (typeof entry !== 'object' || entry === null) {
+                throw new Error(`SchemaLoader: ${source} hardcoded[${idx}] is not an object`);
+            }
+            const e = entry;
+            const path = this.requireString(e.path, `hardcoded[${idx}].path`, source);
+            if (e.frozen !== true) {
+                throw new Error(`SchemaLoader: ${source} hardcoded[${idx}] must have frozen: true (got ${JSON.stringify(e.frozen)})`);
+            }
+            const description = this.requireString(e.description, `hardcoded[${idx}].description`, source);
+            const refs = this.requireStringArray(e.referenced_by, `hardcoded[${idx}].referenced_by`, source);
+            // Each ref must look like `<kind>:<name>` — validated lightly here so
+            // a malformed registry doesn't reach the resolver.
+            refs.forEach((ref, refIdx) => {
+                if (!/^(skill|service):.+$/.test(ref)) {
+                    throw new Error(`SchemaLoader: ${source} hardcoded[${idx}].referenced_by[${refIdx}] must match "skill:<name>" or "service:<name>" (got "${ref}")`);
+                }
+            });
+            return {
+                path,
+                frozen: true,
+                description,
+                referenced_by: refs,
+            };
+        });
+    }
+    requireLlmCurated(raw, source) {
+        if (!Array.isArray(raw)) {
+            throw new Error(`SchemaLoader: ${source} "llm_curated" must be an array`);
+        }
+        return raw.map((entry, idx) => {
+            if (typeof entry !== 'object' || entry === null) {
+                throw new Error(`SchemaLoader: ${source} llm_curated[${idx}] is not an object`);
+            }
+            const e = entry;
+            const path = this.requireString(e.path, `llm_curated[${idx}].path`, source);
+            if (e.frozen !== false) {
+                throw new Error(`SchemaLoader: ${source} llm_curated[${idx}] must have frozen: false (got ${JSON.stringify(e.frozen)})`);
+            }
+            const seed_subdirs = this.requireStringArray(e.seed_subdirs, `llm_curated[${idx}].seed_subdirs`, source);
+            return {
+                path,
+                frozen: false,
+                seed_subdirs,
+                llm_can_create_subdirs: Boolean(e.llm_can_create_subdirs),
+                lint_may_restructure: Boolean(e.lint_may_restructure),
+            };
+        });
+    }
+    requireWritePolicy(raw, source) {
+        if (typeof raw !== 'object' || raw === null) {
+            throw new Error(`SchemaLoader: ${source} "write_policy" must be an object`);
+        }
+        const w = raw;
+        return {
+            canonical: this.requireStringArray(w.canonical, 'write_policy.canonical', source),
+            proposed_only: this.requireStringArray(w.proposed_only, 'write_policy.proposed_only', source),
+            schema_writer: this.requireStringArray(w.schema_writer, 'write_policy.schema_writer', source),
+        };
+    }
+    requireStringArray(raw, field, source) {
+        if (!Array.isArray(raw)) {
+            throw new Error(`SchemaLoader: ${source} "${field}" must be an array`);
+        }
+        raw.forEach((item, idx) => {
+            if (typeof item !== 'string' || item.length === 0) {
+                throw new Error(`SchemaLoader: ${source} "${field}[${idx}]" must be a non-empty string`);
+            }
+        });
+        return raw;
+    }
+}
+//# sourceMappingURL=schema-loader.service.js.map

package/dist/backend/backend/src/services/wiki/schema-loader.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-loader.service.js","sourceRoot":"","sources":["../../../../../../backend/src/services/wiki/schema-loader.service.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/services/wiki/wiki-bookkeep-trigger.service.d.ts

@@ -0,0 +1,86 @@
+/**
+ * WikiBookkeepTriggerService — periodic vault scan that fires a
+ * notification to ORC when bookkeeping is due.
+ *
+ * Per Steve's 2026-05-22 design point #5: "还要时不时让 agent 针对自己的
+ * vault 进行 bookkeeping (可以根据存入的 md 数量来 trigger), 譬如过去
+ * N 天超过 X 个 md, 然后总结一下."
+ *
+ * Mechanism:
+ *   - every `intervalMs` (default 30 min) tick
+ *   - discover known vaults (project + team + global) by walking known
+ *     filesystem roots for SCHEMA.md
+ *   - call `WikiBookkeepService.generate` for each
+ *   - if `report.shouldFire`, invoke the caller-injected `fireFn` (in
+ *     production: enqueue a `[BOOKKEEP] vault=…` message to ORC)
+ *   - debounce per-vault so we don't spam — only refire after
+ *     `debounceMs` (default 6 h)
+ *
+ * The service intentionally does NOT do the consolidation itself — it
+ * notifies the agent, which then runs `wiki-bookkeep` + `wiki-ingest`
+ * (per the orchestrator system prompt rule).
+ *
+ * @module services/wiki/wiki-bookkeep-trigger.service
+ */
+import { WikiBookkeepService, WikiBookkeepReport } from './wiki-bookkeep.service.js';
+export type WikiBookkeepFireFn = (vaultPath: string, report: WikiBookkeepReport) => Promise<void> | void;
+export interface WikiBookkeepTriggerOptions {
+    /** Interval between scans, ms. Default 30 minutes. */
+    intervalMs?: number;
+    /** Minimum gap between fires for the same vault, ms. Default 6 hours. */
+    debounceMs?: number;
+    /** Caller-injected notifier. Production wires this to enqueue a message to ORC. */
+    fireFn: WikiBookkeepFireFn;
+    /** Optional override of the discovery roots (tests). */
+    discoverRoots?: () => Promise<string[]>;
+    /** Optional override of the bookkeep service (tests). */
+    bookkeepService?: WikiBookkeepService;
+}
+/**
+ * Discover absolute vault paths by walking the well-known Crewly roots:
+ *   - `<env CREWLY_PROJECT_VAULT_PATH>` (single explicit override)
+ *   - `<process.cwd>/.crewly/wiki` (current project vault)
+ *   - `~/.crewly/teams/<uuid>/wiki` (every team vault)
+ *   - `~/.crewly/global-wiki` (ORC cross-project vault, if present)
+ *
+ * A path is only included if `SCHEMA.md` exists inside it.
+ */
+export declare function discoverWikiVaults(): Promise<string[]>;
+/**
+ * Periodic vault-bookkeep trigger. Start at boot, stop at shutdown.
+ */
+export declare class WikiBookkeepTriggerService {
+    private static instance;
+    private readonly logger;
+    private readonly intervalMs;
+    private readonly debounceMs;
+    private readonly fireFn;
+    private readonly discoverRoots;
+    private readonly bookkeepService;
+    private timer;
+    /** vaultPath → last fired timestamp (ms). */
+    private readonly lastFiredAt;
+    /** Per-vault locks so two overlapping ticks don't double-fire. */
+    private inflight;
+    constructor(opts: WikiBookkeepTriggerOptions);
+    static getInstance(): WikiBookkeepTriggerService | null;
+    /** Wire the production singleton. Pass null to detach (tests / shutdown). */
+    static setInstance(next: WikiBookkeepTriggerService | null): void;
+    /** Begin scanning. Idempotent. */
+    start(): void;
+    /** Stop scanning. Safe to call multiple times. */
+    stop(): void;
+    /**
+     * Run one scan pass. Public for test + the manual
+     * `/api/wiki/bookkeep/trigger-now` endpoint.
+     */
+    tick(): Promise<{
+        scanned: string[];
+        fired: string[];
+        skippedByDebounce: string[];
+        quietVaults: string[];
+    }>;
+    /** Test affordance: clear the debounce ledger. */
+    _resetDebounceForTesting(): void;
+}
+//# sourceMappingURL=wiki-bookkeep-trigger.service.d.ts.map

package/dist/backend/backend/src/services/wiki/wiki-bookkeep-trigger.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiki-bookkeep-trigger.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/wiki/wiki-bookkeep-trigger.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAOH,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAErF,MAAM,MAAM,kBAAkB,GAAG,CAC/B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,kBAAkB,KACvB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAE1B,MAAM,WAAW,0BAA0B;IACzC,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,MAAM,EAAE,kBAAkB,CAAC;IAC3B,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACxC,yDAAyD;IACzD,eAAe,CAAC,EAAE,mBAAmB,CAAC;CACvC;AAKD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CA4B5D;AAED;;GAEG;AACH,qBAAa,0BAA0B;IACrC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA2C;IAClE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA0B;IACxD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAsB;IACtD,OAAO,CAAC,KAAK,CAA+B;IAC5C,6CAA6C;IAC7C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,kEAAkE;IAClE,OAAO,CAAC,QAAQ,CAAqB;gBAEzB,IAAI,EAAE,0BAA0B;IAS5C,MAAM,CAAC,WAAW,IAAI,0BAA0B,GAAG,IAAI;IAIvD,6EAA6E;IAC7E,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,0BAA0B,GAAG,IAAI,GAAG,IAAI;IAKjE,kCAAkC;IAClC,KAAK,IAAI,IAAI;IAWb,kDAAkD;IAClD,IAAI,IAAI,IAAI;IAQZ;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC;QACpB,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,iBAAiB,EAAE,MAAM,EAAE,CAAC;QAC5B,WAAW,EAAE,MAAM,EAAE,CAAC;KACvB,CAAC;IAoDF,kDAAkD;IAClD,wBAAwB,IAAI,IAAI;CAGjC"}

package/dist/backend/backend/src/services/wiki/wiki-bookkeep-trigger.service.js

@@ -0,0 +1,187 @@
+/**
+ * WikiBookkeepTriggerService — periodic vault scan that fires a
+ * notification to ORC when bookkeeping is due.
+ *
+ * Per Steve's 2026-05-22 design point #5: "还要时不时让 agent 针对自己的
+ * vault 进行 bookkeeping (可以根据存入的 md 数量来 trigger), 譬如过去
+ * N 天超过 X 个 md, 然后总结一下."
+ *
+ * Mechanism:
+ *   - every `intervalMs` (default 30 min) tick
+ *   - discover known vaults (project + team + global) by walking known
+ *     filesystem roots for SCHEMA.md
+ *   - call `WikiBookkeepService.generate` for each
+ *   - if `report.shouldFire`, invoke the caller-injected `fireFn` (in
+ *     production: enqueue a `[BOOKKEEP] vault=…` message to ORC)
+ *   - debounce per-vault so we don't spam — only refire after
+ *     `debounceMs` (default 6 h)
+ *
+ * The service intentionally does NOT do the consolidation itself — it
+ * notifies the agent, which then runs `wiki-bookkeep` + `wiki-ingest`
+ * (per the orchestrator system prompt rule).
+ *
+ * @module services/wiki/wiki-bookkeep-trigger.service
+ */
+import * as path from 'path';
+import * as os from 'os';
+import * as fs from 'fs/promises';
+import { existsSync } from 'fs';
+import { LoggerService } from '../core/logger.service.js';
+import { WikiBookkeepService } from './wiki-bookkeep.service.js';
+const DEFAULT_INTERVAL_MS = 30 * 60 * 1000;
+const DEFAULT_DEBOUNCE_MS = 6 * 3600 * 1000;
+/**
+ * Discover absolute vault paths by walking the well-known Crewly roots:
+ *   - `<env CREWLY_PROJECT_VAULT_PATH>` (single explicit override)
+ *   - `<process.cwd>/.crewly/wiki` (current project vault)
+ *   - `~/.crewly/teams/<uuid>/wiki` (every team vault)
+ *   - `~/.crewly/global-wiki` (ORC cross-project vault, if present)
+ *
+ * A path is only included if `SCHEMA.md` exists inside it.
+ */
+export async function discoverWikiVaults() {
+    const found = new Set();
+    const candidates = [];
+    const fromEnv = process.env['CREWLY_PROJECT_VAULT_PATH'];
+    if (fromEnv && path.isAbsolute(fromEnv))
+        candidates.push(fromEnv);
+    candidates.push(path.join(process.cwd(), '.crewly/wiki'));
+    candidates.push(path.join(os.homedir(), '.crewly/global-wiki'));
+    const teamsRoot = path.join(os.homedir(), '.crewly/teams');
+    if (existsSync(teamsRoot)) {
+        try {
+            const entries = await fs.readdir(teamsRoot, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                candidates.push(path.join(teamsRoot, entry.name, 'wiki'));
+            }
+        }
+        catch {
+            // ignore — partial discovery is fine
+        }
+    }
+    for (const candidate of candidates) {
+        if (existsSync(path.join(candidate, 'SCHEMA.md'))) {
+            found.add(candidate);
+        }
+    }
+    return [...found].sort();
+}
+/**
+ * Periodic vault-bookkeep trigger. Start at boot, stop at shutdown.
+ */
+export class WikiBookkeepTriggerService {
+    static instance = null;
+    logger;
+    intervalMs;
+    debounceMs;
+    fireFn;
+    discoverRoots;
+    bookkeepService;
+    timer = null;
+    /** vaultPath → last fired timestamp (ms). */
+    lastFiredAt = new Map();
+    /** Per-vault locks so two overlapping ticks don't double-fire. */
+    inflight = new Set();
+    constructor(opts) {
+        this.logger = LoggerService.getInstance().createComponentLogger('WikiBookkeepTrigger');
+        this.intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
+        this.debounceMs = opts.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+        this.fireFn = opts.fireFn;
+        this.discoverRoots = opts.discoverRoots ?? discoverWikiVaults;
+        this.bookkeepService = opts.bookkeepService ?? WikiBookkeepService.getInstance();
+    }
+    static getInstance() {
+        return this.instance;
+    }
+    /** Wire the production singleton. Pass null to detach (tests / shutdown). */
+    static setInstance(next) {
+        if (this.instance && this.instance !== next)
+            this.instance.stop();
+        this.instance = next;
+    }
+    /** Begin scanning. Idempotent. */
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => void this.tick(), this.intervalMs);
+        // Don't keep the event loop alive just for bookkeeping.
+        this.timer.unref?.();
+        this.logger.info('WikiBookkeepTrigger started', {
+            intervalMs: this.intervalMs,
+            debounceMs: this.debounceMs,
+        });
+    }
+    /** Stop scanning. Safe to call multiple times. */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+            this.logger.info('WikiBookkeepTrigger stopped');
+        }
+    }
+    /**
+     * Run one scan pass. Public for test + the manual
+     * `/api/wiki/bookkeep/trigger-now` endpoint.
+     */
+    async tick() {
+        const vaults = await this.discoverRoots();
+        const result = {
+            scanned: [...vaults],
+            fired: [],
+            skippedByDebounce: [],
+            quietVaults: [],
+        };
+        for (const v of vaults) {
+            if (this.inflight.has(v))
+                continue;
+            this.inflight.add(v);
+            try {
+                const outcome = await this.bookkeepService.generate({ vaultPath: v });
+                if (!outcome.ok) {
+                    this.logger.warn('WikiBookkeepTrigger: bookkeep failed for vault', {
+                        vault: v,
+                        reason: outcome.reason,
+                    });
+                    continue;
+                }
+                if (!outcome.report.shouldFire) {
+                    result.quietVaults.push(v);
+                    continue;
+                }
+                const last = this.lastFiredAt.get(v) ?? 0;
+                if (Date.now() - last < this.debounceMs) {
+                    result.skippedByDebounce.push(v);
+                    continue;
+                }
+                this.lastFiredAt.set(v, Date.now());
+                try {
+                    await this.fireFn(v, outcome.report);
+                    result.fired.push(v);
+                    this.logger.info('WikiBookkeepTrigger fired', {
+                        vault: v,
+                        recentMd: outcome.report.recentMdCount,
+                        threshold: outcome.report.threshold,
+                        duplicates: outcome.report.duplicateCandidates.length,
+                    });
+                }
+                catch (err) {
+                    this.logger.warn('WikiBookkeepTrigger: fireFn threw (swallowed)', {
+                        vault: v,
+                        error: err.message,
+                    });
+                }
+            }
+            finally {
+                this.inflight.delete(v);
+            }
+        }
+        return result;
+    }
+    /** Test affordance: clear the debounce ledger. */
+    _resetDebounceForTesting() {
+        this.lastFiredAt.clear();
+    }
+}
+//# sourceMappingURL=wiki-bookkeep-trigger.service.js.map

package/dist/backend/backend/src/services/wiki/wiki-bookkeep-trigger.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiki-bookkeep-trigger.service.js","sourceRoot":"","sources":["../../../../../../backend/src/services/wiki/wiki-bookkeep-trigger.service.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/services/wiki/wiki-bookkeep.service.d.ts

@@ -0,0 +1,116 @@
+/**
+ * WikiBookkeepService — vault health metrics + consolidation signals.
+ *
+ * Per Steve's 2026-05-22 design point #5: "还要时不时让 agent 针对自己的
+ * vault 进行 bookkeeping (可以根据存入的 md 数量来 trigger), 譬如过去 N
+ * 天超过 X 个 md, 然后总结一下."
+ *
+ * This service produces the report the bookkeeping agent reads:
+ *   - md count per top-level llm-curated subfolder
+ *   - new mds in the last N days
+ *   - filename clusters (likely-duplicates by Jaccard of token sets)
+ *   - queue stats (so the agent sees pending items too)
+ *
+ * The agent uses this report (+ its LLM) to decide:
+ *   - which pages to consolidate / dedupe (calls wiki-ingest with a new
+ *     consolidated body + deletes the originals via a separate skill —
+ *     deletion is OUT of scope for Phase 1; surface as proposals).
+ *   - which topics deserve a summary "rollup" page.
+ *
+ * The service does NOT delete or rewrite anything. It reports.
+ *
+ * @module services/wiki/wiki-bookkeep.service
+ */
+import { SchemaLoaderService } from './schema-loader.service.js';
+import { WikiQueueService } from './wiki-queue.service.js';
+export interface WikiBookkeepInput {
+    /** Absolute vault path. */
+    vaultPath: string;
+    /** Window for "recent activity" stats. Default 7 days. */
+    windowDays?: number;
+    /** Md-count threshold used by `shouldFire` (default 10). */
+    threshold?: number;
+}
+export interface WikiPageRef {
+    path: string;
+    bytes: number;
+    modifiedAt: string;
+}
+export interface WikiDuplicateCluster {
+    /** Shared base — the longest filename prefix across the cluster. */
+    basis: string;
+    /** Member pages (relative paths). */
+    pages: string[];
+}
+export interface WikiBookkeepReport {
+    vault: {
+        scope: string;
+        id: string;
+        path: string;
+    };
+    generatedAt: string;
+    windowDays: number;
+    threshold: number;
+    /** Did we cross the threshold for "trigger a consolidation pass"? */
+    shouldFire: boolean;
+    /** Total md files under the vault (recursive). */
+    totalMdCount: number;
+    /** Newly created/touched mds within `windowDays`. */
+    recentMdCount: number;
+    /** Per-folder counts under llm-curated/<x>/. */
+    countsByFolder: Record<string, number>;
+    /** Likely-duplicate clusters by filename Jaccard. */
+    duplicateCandidates: WikiDuplicateCluster[];
+    /** Mds that haven't been touched in 90 days — stale candidates. */
+    staleCount: number;
+    /** Queue snapshot for this vault. */
+    queue: {
+        pending: number;
+        claimed: number;
+        processed: number;
+        skipped: number;
+        total: number;
+    };
+    /** Recommendations the agent's LLM should act on. */
+    recommendations: string[];
+}
+export type WikiBookkeepOutcome = {
+    ok: true;
+    report: WikiBookkeepReport;
+} | {
+    ok: false;
+    reason: 'invalid_input' | 'schema_missing' | 'vault_missing';
+    message: string;
+};
+/**
+ * Vault health + bookkeeping report generator. Stateless; uses the
+ * schema loader + queue services it composes.
+ */
+export declare class WikiBookkeepService {
+    private static instance;
+    private readonly logger;
+    private readonly schemaLoader;
+    private readonly queue;
+    constructor(schemaLoader?: SchemaLoaderService, queue?: WikiQueueService);
+    static getInstance(): WikiBookkeepService;
+    /** Test-only reset. */
+    static _resetForTesting(): void;
+    /**
+     * Build the bookkeeping report. Caller (skill / cron / agent) decides
+     * whether to act on `shouldFire`. The service never writes; it reports.
+     */
+    generate(input: WikiBookkeepInput): Promise<WikiBookkeepOutcome>;
+    private collectPages;
+    /**
+     * Find filename clusters by Jaccard over name tokens.
+     * Two pages with ≥ 0.6 overlap on their non-trivial filename tokens
+     * are flagged as potential duplicates. Token = anything ≥ 3 chars
+     * after splitting on `[-_./]`, lowercased, minus date prefix.
+     */
+    private findDuplicateClusters;
+    private tokenizeFilename;
+    private jaccard;
+    private longestCommonPrefix;
+    private buildRecommendations;
+}
+//# sourceMappingURL=wiki-bookkeep.service.d.ts.map

package/dist/backend/backend/src/services/wiki/wiki-bookkeep.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiki-bookkeep.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/wiki/wiki-bookkeep.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAMH,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAM3D,MAAM,WAAW,iBAAiB;IAChC,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,UAAU,EAAE,OAAO,CAAC;IACpB,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,aAAa,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,qDAAqD;IACrD,mBAAmB,EAAE,oBAAoB,EAAE,CAAC;IAC5C,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,KAAK,EAAE;QACL,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IACF,qDAAqD;IACrD,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,GACxC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,eAAe,GAAG,gBAAgB,GAAG,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjG;;;GAGG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAoC;IAC3D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;IACnD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;gBAGvC,YAAY,CAAC,EAAE,mBAAmB,EAClC,KAAK,CAAC,EAAE,gBAAgB;IAO1B,MAAM,CAAC,WAAW,IAAI,mBAAmB;IAKzC,uBAAuB;IACvB,MAAM,CAAC,gBAAgB,IAAI,IAAI;IAI/B;;;OAGG;IACG,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC;YAwGxD,YAAY;IA2C1B;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IA6B7B,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,OAAO;IAQf,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,oBAAoB;CA8C7B"}