@cleocode/core 2026.10.27 → 2026.11.1-canary.3

package/dist/docs/modernize/judge.d.ts

@@ -0,0 +1,85 @@
+/**
+ * System One judgments for `cleo docs modernize` (T14113).
+ *
+ * Two registered sites, asked only when a rule is unsure:
+ *
+ * - `docs.modernize.classify` — which kind is a doc whose folder, name and
+ *   headings did not settle it (rule confidence below the floor).
+ * - `docs.modernize.merge` — are two docs that share a slug one doc, when
+ *   their similarity sits in the middle band.
+ *
+ * Every ask goes through {@link askSiteDecision}: budgeted, audited to
+ * `decisions.jsonl` beside the rule answer, and never throwing. With no
+ * provider configured the site resolves to `off` and the rule answers with
+ * zero network; in `shadow` (the default) the provider is asked and recorded
+ * but the rule acts; only `on` with a confident, valid answer acts on it.
+ * Each call returns a {@link DocsModernizeJudgment} the plan row carries.
+ *
+ * @task T14113
+ * @epic T14106
+ */
+import type { DocsModernizeJudgment } from '@cleocode/contracts';
+import type { DecideOptions } from '../../decide/client.js';
+import type { DecisionSiteMode } from '../../decide/site.js';
+/** Wait budget per question, in ms. Modernize is a batch job, not a hot path. */
+export declare const MODERNIZE_DECISION_BUDGET_MS = 5000;
+/** Minimum confidence before `on` mode acts on a decided answer. */
+export declare const MODERNIZE_MIN_CONFIDENCE = 0.6;
+/** Effective modes for both sites, resolved once per run. */
+export interface ModernizeJudgeSettings {
+    /** Mode of `docs.modernize.classify`. */
+    readonly classifyMode: DecisionSiteMode;
+    /** Mode of `docs.modernize.merge`. */
+    readonly mergeMode: DecisionSiteMode;
+    /** Provider wiring forwarded to `decide()` (tests inject a provider here). */
+    readonly wiring?: DecideOptions;
+    /** Project root for config and the audit sink. */
+    readonly projectRoot: string;
+}
+/**
+ * Resolve both sites' modes. Unconfigured System One resolves to `off`.
+ *
+ * @param projectRoot - Project root for config lookup.
+ * @param wiring - Optional provider wiring.
+ * @param mode - Optional explicit mode for both sites.
+ * @returns The settings for one run.
+ */
+export declare function resolveModernizeJudgeSettings(projectRoot: string, wiring?: DecideOptions, mode?: DecisionSiteMode): Promise<ModernizeJudgeSettings>;
+/**
+ * Judge the kind of a doc the rules were unsure about.
+ *
+ * @param input - The doc, the rule's kind and confidence, and the offered kinds.
+ * @param settings - Run settings.
+ * @returns The judgment; `acted` is the kind the plan uses.
+ */
+export declare function judgeDocKind(input: {
+    readonly path: string;
+    readonly title: string;
+    readonly content: string;
+    readonly ruleKind: string;
+    readonly ruleConfidence: number;
+    readonly kinds: ReadonlyArray<{
+        readonly kind: string;
+        readonly description: string;
+    }>;
+}, settings: ModernizeJudgeSettings): Promise<DocsModernizeJudgment>;
+/**
+ * Judge whether two docs that share a slug are one doc.
+ *
+ * @param input - Both docs and their line similarity.
+ * @param settings - Run settings.
+ * @returns The judgment; `acted` is `merge` or `separate`.
+ */
+export declare function judgeDocMerge(input: {
+    readonly left: {
+        readonly path: string;
+        readonly content: string;
+    };
+    readonly right: {
+        readonly path: string;
+        readonly content: string;
+    };
+    readonly similarity: number;
+    readonly rule: 'merge' | 'separate';
+}, settings: ModernizeJudgeSettings): Promise<DocsModernizeJudgment>;
+//# sourceMappingURL=judge.d.ts.map

package/dist/docs/modernize/judge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"judge.d.ts","sourceRoot":"","sources":["../../../src/docs/modernize/judge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAGV,qBAAqB,EAEtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,KAAK,EAAwB,gBAAgB,EAAgB,MAAM,sBAAsB,CAAC;AAMjG,iFAAiF;AACjF,eAAO,MAAM,4BAA4B,OAAQ,CAAC;AAElD,oEAAoE;AACpE,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAW5C,6DAA6D;AAC7D,MAAM,WAAW,sBAAsB;IACrC,yCAAyC;IACzC,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;IACxC,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC;IACrC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,kDAAkD;IAClD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAsB,6BAA6B,CACjD,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,aAAa,EACtB,IAAI,CAAC,EAAE,gBAAgB,GACtB,OAAO,CAAC,sBAAsB,CAAC,CAiBjC;AAwED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE;IACL,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxF,EACD,QAAQ,EAAE,sBAAsB,GAC/B,OAAO,CAAC,qBAAqB,CAAC,CAyBhC;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE;IACL,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACpE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAAC;CACrC,EACD,QAAQ,EAAE,sBAAsB,GAC/B,OAAO,CAAC,qBAAqB,CAAC,CAgChC"}

package/dist/docs/modernize/judge.js

@@ -0,0 +1,186 @@
+/**
+ * System One judgments for `cleo docs modernize` (T14113).
+ *
+ * Two registered sites, asked only when a rule is unsure:
+ *
+ * - `docs.modernize.classify` — which kind is a doc whose folder, name and
+ *   headings did not settle it (rule confidence below the floor).
+ * - `docs.modernize.merge` — are two docs that share a slug one doc, when
+ *   their similarity sits in the middle band.
+ *
+ * Every ask goes through {@link askSiteDecision}: budgeted, audited to
+ * `decisions.jsonl` beside the rule answer, and never throwing. With no
+ * provider configured the site resolves to `off` and the rule answers with
+ * zero network; in `shadow` (the default) the provider is asked and recorded
+ * but the rule acts; only `on` with a confident, valid answer acts on it.
+ * Each call returns a {@link DocsModernizeJudgment} the plan row carries.
+ *
+ * @task T14113
+ * @epic T14106
+ */
+import { DOC_MODERNIZE_CLASSIFY_SITE, DOC_MODERNIZE_MERGE_SITE, } from '../../decide/sites/registry.js';
+/** Wait budget per question, in ms. Modernize is a batch job, not a hot path. */
+export const MODERNIZE_DECISION_BUDGET_MS = 5_000;
+/** Minimum confidence before `on` mode acts on a decided answer. */
+export const MODERNIZE_MIN_CONFIDENCE = 0.6;
+/** Characters of body sent per doc. */
+const EXCERPT_MAX_CHARS = 1_500;
+/** Characters of a path or title sent. */
+const LABEL_MAX_CHARS = 200;
+/** The merge question's options. */
+const MERGE_OPTIONS = ['merge', 'separate'];
+/**
+ * Resolve both sites' modes. Unconfigured System One resolves to `off`.
+ *
+ * @param projectRoot - Project root for config lookup.
+ * @param wiring - Optional provider wiring.
+ * @param mode - Optional explicit mode for both sites.
+ * @returns The settings for one run.
+ */
+export async function resolveModernizeJudgeSettings(projectRoot, wiring, mode) {
+    const { resolveDecisionSiteSettings } = await import('../../decide/site.js');
+    const [classify, merge] = await Promise.all([
+        resolveDecisionSiteSettings({
+            modeKey: DOC_MODERNIZE_CLASSIFY_SITE.modeKey,
+            mode,
+            wiring,
+            projectRoot,
+        }),
+        resolveDecisionSiteSettings({
+            modeKey: DOC_MODERNIZE_MERGE_SITE.modeKey,
+            mode,
+            wiring,
+            projectRoot,
+        }),
+    ]);
+    return { classifyMode: classify.mode, mergeMode: merge.mode, wiring, projectRoot };
+}
+/** A one-hot choice answer standing for the rule. */
+function ruleAnswer(options, value, confidence) {
+    return {
+        type: 'choice',
+        value,
+        probabilities: Object.fromEntries(options.map((o) => [o, o === value ? 1 : 0])),
+        confidence,
+    };
+}
+/**
+ * Ask one choice question and fold the outcome into a judgment. `ask` calls
+ * `askSiteDecision` with the registered site id (gate 35 reads it there).
+ */
+async function judgeChoice(input) {
+    const base = {
+        question: input.question,
+        site: input.siteId,
+        mode: input.mode,
+        ruleAnswer: input.rule,
+    };
+    const fallback = {
+        ...base,
+        decidedAnswer: null,
+        decidedConfidence: null,
+        source: 'fallback',
+        acted: input.rule,
+    };
+    if (input.mode === 'off')
+        return fallback;
+    const name = input.question;
+    const decision = await input.ask({
+        budgetMs: MODERNIZE_DECISION_BUDGET_MS,
+        minConfidence: MODERNIZE_MIN_CONFIDENCE,
+        mode: input.mode,
+        heuristicVerdict: input.rule,
+        buildRequest: input.buildRequest,
+        heuristicAnswers: { [name]: ruleAnswer(input.options, input.rule, input.ruleConfidence) },
+        isValid: (answers) => {
+            const a = answers[name];
+            return a?.type === 'choice' && typeof a.value === 'string' && input.options.includes(a.value);
+        },
+        agree: (answers) => answers[name]?.value === input.rule,
+        wiring: input.settings.wiring,
+        projectRoot: input.settings.projectRoot,
+    });
+    const answer = decision?.answers[name];
+    if (!decision || answer?.type !== 'choice')
+        return fallback;
+    const acts = input.mode === 'on' && decision.confident;
+    return {
+        ...base,
+        decidedAnswer: answer.value,
+        decidedConfidence: answer.confidence,
+        source: decision.source,
+        acted: acts ? answer.value : input.rule,
+    };
+}
+/**
+ * Judge the kind of a doc the rules were unsure about.
+ *
+ * @param input - The doc, the rule's kind and confidence, and the offered kinds.
+ * @param settings - Run settings.
+ * @returns The judgment; `acted` is the kind the plan uses.
+ */
+export async function judgeDocKind(input, settings) {
+    const { askSiteDecision, redactThenClip } = await import('../../decide/site.js');
+    return judgeChoice({
+        ask: (common) => askSiteDecision({ siteId: DOC_MODERNIZE_CLASSIFY_SITE.id, ...common }),
+        question: 'classify',
+        siteId: DOC_MODERNIZE_CLASSIFY_SITE.id,
+        mode: settings.classifyMode,
+        options: input.kinds.map((k) => k.kind),
+        rule: input.ruleKind,
+        ruleConfidence: input.ruleConfidence,
+        settings,
+        buildRequest: (redact) => ({
+            state: {
+                path: redactThenClip(input.path, LABEL_MAX_CHARS, redact),
+                title: redactThenClip(input.title, LABEL_MAX_CHARS, redact),
+                excerpt: redactThenClip(input.content, EXCERPT_MAX_CHARS, redact),
+            },
+            questions: {
+                classify: {
+                    type: 'choice',
+                    criteria: Object.fromEntries(input.kinds.map((k) => [k.kind, k.description])),
+                },
+            },
+        }),
+    });
+}
+/**
+ * Judge whether two docs that share a slug are one doc.
+ *
+ * @param input - Both docs and their line similarity.
+ * @param settings - Run settings.
+ * @returns The judgment; `acted` is `merge` or `separate`.
+ */
+export async function judgeDocMerge(input, settings) {
+    const { askSiteDecision, redactThenClip } = await import('../../decide/site.js');
+    return judgeChoice({
+        ask: (common) => askSiteDecision({ siteId: DOC_MODERNIZE_MERGE_SITE.id, ...common }),
+        question: 'merge',
+        siteId: DOC_MODERNIZE_MERGE_SITE.id,
+        mode: settings.mergeMode,
+        options: MERGE_OPTIONS,
+        rule: input.rule,
+        ruleConfidence: 0.5,
+        settings,
+        buildRequest: (redact) => ({
+            state: {
+                firstPath: redactThenClip(input.left.path, LABEL_MAX_CHARS, redact),
+                firstExcerpt: redactThenClip(input.left.content, EXCERPT_MAX_CHARS, redact),
+                secondPath: redactThenClip(input.right.path, LABEL_MAX_CHARS, redact),
+                secondExcerpt: redactThenClip(input.right.content, EXCERPT_MAX_CHARS, redact),
+                lineSimilarity: Math.round(input.similarity * 100) / 100,
+            },
+            questions: {
+                merge: {
+                    type: 'choice',
+                    criteria: {
+                        merge: 'Both documents cover the same subject; one is an older, partial or alternate version of the other and they should become one document.',
+                        separate: 'The documents cover different subjects that happen to share a name; both should stay as separate documents.',
+                    },
+                },
+            },
+        }),
+    });
+}
+//# sourceMappingURL=judge.js.map

package/dist/docs/modernize/judge.js.map

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

package/dist/docs/modernize/plan.d.ts

@@ -0,0 +1,77 @@
+/**
+ * `cleo docs modernize <path> --dry-run` — propose, per file, a kind, a
+ * stable slug and a disposition (T14113).
+ *
+ * Steps:
+ *
+ * 1. Scan `.md` / `.txt` files under the root (the `docs import` scanner),
+ *    skipping build, generated and image folders.
+ * 2. Classify each file by rules (front matter, folder, filename, headings);
+ *    a rule below {@link MODERNIZE_CLASSIFY_FLOOR} is judged by System One
+ *    (`docs.modernize.classify`).
+ * 3. Derive the stable slug: no task, session or date tokens.
+ * 4. Group files by slug. Byte-identical members are deleted in favour of the
+ *    survivor; other members merge when their line similarity is high, stay
+ *    apart (with a numbered slug) when it is low, and are judged by System
+ *    One (`docs.modernize.merge`) in between.
+ * 5. Survivors keep or move to `<kind folder>/<slug><ext>`.
+ *
+ * Read-only: nothing is written except the decision-audit line each System
+ * One question gets. The plan is the input to `applyDocsModernize`.
+ *
+ * @task T14113
+ * @epic T14106
+ */
+import type { DocKindMetadata, DocsModernizeOverrides, DocsModernizePlan } from '@cleocode/contracts';
+import type { DecideOptions } from '../../decide/client.js';
+import type { DecisionSiteMode } from '../../decide/site.js';
+/** Folders modernize never descends into, beyond the scanner's defaults. */
+export declare const MODERNIZE_EXCLUDE_DIRS: ReadonlySet<string>;
+/** File extensions modernize reads. */
+export declare const MODERNIZE_EXTENSIONS: readonly string[];
+/** Options for {@link planDocsModernize}. */
+export interface PlanDocsModernizeOptions {
+    /** Absolute directory to modernize. */
+    readonly root: string;
+    /** Project root (kind registry, config, decision audit). */
+    readonly projectRoot: string;
+    /** Extra folder names to skip. */
+    readonly exclude?: readonly string[];
+    /** Explicit System One mode for both sites (tests; default from config). */
+    readonly mode?: DecisionSiteMode;
+    /** Provider wiring forwarded to `decide()` (tests). */
+    readonly decide?: DecideOptions;
+    /** Clock override (tests). */
+    readonly now?: () => Date;
+    /** Reviewer decisions keyed by path; they win over rules and System One. */
+    readonly overrides?: DocsModernizeOverrides;
+    /** Use this kind for every file instead of classifying (bulk ingest). */
+    readonly kind?: string;
+    /** Ingest every file into the store and leave the folder untouched. */
+    readonly storeOnly?: boolean;
+    /** Repository root for the `refs` scan (default: the project root). */
+    readonly repoRoot?: string;
+}
+/**
+ * Task and decision ids an old path names (`T1234`, `D11180`), upper-cased,
+ * in order of appearance.
+ *
+ * @param relPath - Path relative to the root.
+ * @returns Unique ids.
+ */
+export declare function ownerIdsFromPath(relPath: string): string[];
+/** The folder, relative to the root, that a kind's docs live in. */
+export declare function kindFolder(kind: string, kinds: readonly DocKindMetadata[]): string;
+/**
+ * Plan a modernize run over `options.root`.
+ *
+ * @param options - Root, project root and System One overrides.
+ * @returns The plan: one row per scanned file, sorted by path.
+ */
+export declare function planDocsModernize(options: PlanDocsModernizeOptions): Promise<DocsModernizePlan>;
+/** Raised when an override names a path the scan did not find. */
+export declare class DocsModernizeOverrideError extends Error {
+    /** Stable code for the envelope. */
+    readonly code = "E_MODERNIZE_OVERRIDE";
+}
+//# sourceMappingURL=plan.d.ts.map

package/dist/docs/modernize/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../src/docs/modernize/plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,KAAK,EACV,eAAe,EAKf,sBAAsB,EACtB,iBAAiB,EAElB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAmB7D,4EAA4E;AAC5E,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAKrD,CAAC;AAEH,uCAAuC;AACvC,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAAoB,CAAC;AAEvE,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kCAAkC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACjC,uDAAuD;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,8BAA8B;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC;IAC5C,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAQD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAM1D;AAgED,oEAAoE;AACpE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,eAAe,EAAE,GAAG,MAAM,CAIlF;AA2FD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,iBAAiB,CAAC,CAqM5B;AA8ID,kEAAkE;AAClE,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,oCAAoC;IACpC,QAAQ,CAAC,IAAI,0BAA0B;CACxC"}