@winspan/claude-forge 8.54.4 → 9.12.0

package/dist/skills/distill/index.d.ts

@@ -0,0 +1,223 @@
+/**
+ * src/skills/distill/index.ts — R-A simplified orchestrator (spec 1851).
+ *
+ * Pre-R-A this drove `cf skills distill <init|run|review|refresh>` and held
+ * the sample-approve gate state machine. R-A:
+ *   - Removes the CLI entry points (CLI is deleted upstream).
+ *   - Removes the scoring phase (it-universal-scorer.ts is deleted; the
+ *     R-B skill-distiller agent will score + distill in one LLM call).
+ *   - Removes the review/sample-approve gate (`phase: 'review_required'`).
+ *   - Keeps the `distillRun` function as the single Web-UI entrypoint so
+ *     `distill-manager.ts` continues to work; it now calls the stub
+ *     `distillGroup` (R-A) which returns memory-only results.
+ */
+import { type Upstream, type FetchResult } from './upstream-fetcher.js';
+import { type DistillResult } from './distiller.js';
+export declare const DEFAULT_STATE_PATH: string;
+/**
+ * Per-run state. R-A simplification (spec 1851 §2.5):
+ *   - phase reduced to { idle | running | done | error } (no scoring /
+ *     distilling / review_required intermediate states).
+ *   - `pending` removed (no gate that needs a resume queue).
+ *   - `rejected` reserved for R-B anchor-lint failures.
+ *   - `pocChunkSize` removed (no sample-approve gate).
+ *
+ * NOTE: a few field names are kept (`completed`, `skipped`, `upstreamCommits`,
+ * `cacheRoot`, `updatedAt`) for backwards compatibility with the on-disk JSON
+ * left behind by older daemons. Old `phase` values are normalised to 'done'
+ * on read in `normaliseLegacyState`.
+ */
+export interface DistillState {
+    phase: 'idle' | 'running' | 'done' | 'error';
+    cacheRoot: string;
+    upstreamCommits: Record<string, string>;
+    completed: string[];
+    skipped: string[];
+    /** R-B will populate this when anchor-lint rejects an agent output. */
+    rejected: string[];
+    lastRunAt: string;
+    updatedAt: string;
+    /**
+     * Back-compat field: pre-R-A state files (e.g. `skills-distill-state.json`
+     * still on disk in `~/.claude-forge/`) carry `pending: []`. We read it for
+     * tolerant deserialisation but never write to it from `distillRun`; always
+     * `[]` in R-A. Do not key new behaviour off this — remove only after we are
+     * confident no live state file still includes it.
+     */
+    pending?: string[];
+}
+/**
+ * Read state file. Returns null if missing or unparsable. Pre-R-A schemas are
+ * auto-normalised so existing on-disk state survives the daemon upgrade.
+ */
+export declare function readState(statePath?: string): Promise<DistillState | null>;
+export declare function writeState(state: DistillState, statePath?: string): Promise<void>;
+export declare function clearState(statePath?: string): Promise<void>;
+export interface InitOptions {
+    cacheRoot?: string;
+    noticePath?: string;
+    catalogPath?: string;
+    upstreams?: ReadonlyArray<Upstream>;
+    statePath?: string;
+    /** Skip actual git network calls (used by tests). */
+    skipFetch?: boolean;
+    /** Synthetic fetch results (test injection) */
+    syntheticResults?: FetchResult[];
+}
+export interface InitResult {
+    fetchResults: FetchResult[];
+    noticeWritten: boolean;
+    catalogWritten: boolean;
+}
+/**
+ * Initialize the distillation workspace: clone upstreams to cache, seed
+ * NOTICE + catalog stub, persist initial state. Idempotent. Web /init route
+ * still calls this (status-only path; no CLI).
+ */
+export declare function distillInit(opts?: InitOptions): Promise<InitResult>;
+/**
+ * RunOptions — R-A trimmed. Removed (vs pre-R-A):
+ *   - `scoreAiProvider` / `distillAiProvider` (no LLM in stub; R-B uses
+ *     `child_process.spawn` not provider objects)
+ *   - `scoreThreshold` (no scoring step)
+ *   - `useAgent` (Phase B env toggle deleted)
+ *   - `continue` (no sample-approve gate)
+ */
+export interface RunOptions {
+    cacheRoot?: string;
+    outputDir?: string;
+    noticePath?: string;
+    statePath?: string;
+    /** Regenerate everything (clears state). */
+    regenerateAll?: boolean;
+    /** Skip a topic id. */
+    skip?: string[];
+    /** Cap total topics processed (PoC scope). Default 5. */
+    topicCap?: number;
+    /** Override upstream list. */
+    upstreams?: ReadonlyArray<Upstream>;
+    /** Inject candidate file list for tests (bypasses listUpstreamSkills). */
+    candidatePaths?: string[];
+    /**
+     * R-B: per-skill stream-json event callback (distill-manager bridges these
+     * to SSE for the Web UI progress card).
+     */
+    onProgress?: (event: {
+        type: string;
+        charCount?: number;
+        raw?: unknown;
+        topicId?: string;
+    }) => void;
+    /**
+     * R-B: user-initiated cancel (distill-manager.cancel() flips this).
+     * Aborts the in-flight claude CLI child process; outer loop checks between
+     * skills and short-circuits.
+     */
+    cancelSignal?: AbortSignal;
+    /** R-B: per-skill timeout (default 600s). */
+    timeoutMs?: number;
+    /**
+     * Spec 0930: when non-empty, ignore `topicCap` and only distill the listed
+     * canonical topic ids. A warning is logged for any requested id that has
+     * no matching candidate. Pairs with `force: true` to re-distill files
+     * that are already in `state.completed`.
+     */
+    topicIds?: string[];
+    /**
+     * Spec 0930: when true, bypass `state.completed` so a topic already
+     * recorded as completed (incl. legacy stub-fallback fossils and accidental
+     * empty-body files) can be re-distilled. Does NOT clear other state fields
+     * and does NOT mutate state on read.
+     */
+    force?: boolean;
+    /**
+     * Spec 1641 (force-outputid follow-up): when non-empty, the orchestrator
+     * maps each requested outputId to the specific group member whose
+     * `inferOutputId({members:[m], topicId:g.topicId})` matches, and calls
+     * `distillGroup` with `forcedOutputId` + `forcedMember` so the write
+     * target is exactly `<outputDir>/<outputId>.md` — not the topic-canonical
+     * primary. Pairs with `force: true` to bypass `state.completed`.
+     *
+     * Precedence vs `topicIds` (Q2 decision): when both are set, `outputIds`
+     * WINS. The orchestrator logs an info-level note and ignores `topicIds`.
+     * Each requested outputId with no matching candidate is `logger.warn`'d
+     * and skipped; the run continues with the remaining outputIds.
+     *
+     * Two outputIds resolving to the same topic group spawn the agent twice
+     * (Q4 decision: no coalescing — one outputId = one CLI spawn = one file).
+     */
+    outputIds?: string[];
+}
+export interface RunResult {
+    /** All distilled outputs in this invocation (R-A: stub results, no files). */
+    distilled: DistillResult[];
+    /**
+     * @deprecated R-A removed the sample-approve gate; always false. Field is
+     * preserved so distill-manager / SSE consumers stay schema-stable until R-C.
+     */
+    pausedAtGate: boolean;
+    /** Updated state */
+    state: DistillState;
+    /** Message for user-facing UI (rendered by distill-manager event stream) */
+    message: string;
+}
+/**
+ * R-A distillRun: enumerate candidates → group by topic → stub-distill each.
+ * No scoring (R-B agent scores in-line). No retry / gate. Returns memory-only
+ * `DistillResult[]` so the Web UI can render the run completing without
+ * writing anything to `src/skills/distilled/`.
+ */
+export declare function distillRun(opts?: RunOptions): Promise<RunResult>;
+export interface ReviewSummary {
+    /** Output dir scan: id -> path */
+    distilledFiles: Array<{
+        id: string;
+        path: string;
+        itScore: number;
+        realDistillation: boolean;
+    }>;
+    /** Pending topics waiting for user OK (R-A: always empty). */
+    pending: string[];
+    /** Last state snapshot */
+    state: DistillState | null;
+}
+/**
+ * Lists distilled files + scores + whether each is a real vs stub
+ * distillation. UI surface unchanged from pre-R-A; results come from the
+ * existing `src/skills/distilled/*.md` files (not touched in R-A).
+ */
+export declare function distillReview(opts?: {
+    outputDir?: string;
+    statePath?: string;
+}): Promise<ReviewSummary>;
+/**
+ * Describes a distilled file that is "broken" — either a pre-R-A
+ * stub-fallback fossil or a near-empty body (Bug B). Returned by
+ * `listStubTopics()` so the Web UI and `/redistill-stubs` route can
+ * derive topic ids to force-redistill.
+ */
+export interface StubDescriptor {
+    /** Bare file name (e.g. `distilled-creator.md`) */
+    file: string;
+    /** Filename without `.md` (e.g. `distilled-creator`) */
+    outputId: string;
+    /** Canonical topic id used for grouping (e.g. `meta-skill`) */
+    topicId: string;
+    /** Why this file was flagged. */
+    reason: 'stub-fallback' | 'empty-body' | 'missing-distilled-by';
+    /** Value of `distilled_by` frontmatter or null when missing. */
+    distilledBy: string | null;
+    /** Length of body markdown (post-frontmatter). */
+    bodyChars: number;
+}
+/**
+ * Scan a distilled-skills output directory and return descriptors for any
+ * file that is a `stub-fallback` fossil OR has a body shorter than the
+ * minimum chars threshold. Spec 0930 §5.2.
+ */
+export declare function listStubTopics(opts?: {
+    outputDir?: string;
+}): Promise<StubDescriptor[]>;
+/** Placeholder — refresh is same as init+run; semantics same as pre-R-A. */
+export declare function distillRefresh(opts?: RunOptions): Promise<RunResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/skills/distill/index.d.ts.map

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