akm-cli 0.9.0-rc.4 → 0.9.0-rc.6

package/dist/assets/wiki/index-template.md

@@ -1,12 +0,0 @@
----
-description: Catalog of pages in the {{WIKI_NAME}} wiki. Regenerated by `akm index`.
-wikiRole: index
----
-
-# {{WIKI_NAME}} — index
-
-_This file is regenerated on every `akm index` run. Manual edits are
-preserved until the next regeneration, then replaced._
-
-_(no pages yet — create one with your editor, or ingest a source with `akm
-wiki stash {{WIKI_NAME}} <path>`.)_

package/dist/assets/wiki/ingest-workflow-template.md

@@ -1,83 +0,0 @@
-# Ingest workflow for wiki:{{WIKI_NAME}}
-
-Wiki location: {{WIKI_DIR}}
-Schema: {{SCHEMA_PATH}}
-
-Follow these steps. akm commands handle the invariants; use your native
-Read/Write/Edit tools for page edits.
-
-This workflow is for ingesting sources that are ALREADY present under
-`{{WIKI_DIR}}/raw/`. Do not ask the user for a source unless the raw queue is
-empty and the caller explicitly asked for interactive ingest.
-
-1. **Read the schema.** Open `{{SCHEMA_PATH}}`. It defines the voice, page
-   kinds, contradiction policy, and any wiki-specific conventions. Do not
-   skip this step even on familiar wikis — the schema may have changed.
-
-2. **Discover the pending raw queue.**
-   ```sh
-   akm wiki lint {{WIKI_NAME}}
-   ```
-   Focus on `uncited-raw` findings: those raw files exist under `raw/` but are
-   not yet cited by any authored page. Treat each `uncited-raw` finding as a
-   pending ingest item, and sort the queue **oldest raw file first** (by
-   filename/mtime). Processing oldest-first keeps backlog age bounded even
-   when the queue is larger than one run can finish. If there are no
-   `uncited-raw` findings, exit cleanly after a final `akm index` +
-   `akm wiki lint {{WIKI_NAME}}` verification.
-
-   Do not read or classify the whole backlog upfront. Work the queue as a
-   bounded loop, one raw file at a time: fully finish a raw (read → decide →
-   edit → log entry, steps 3-7 below) before looking at the next one. If you
-   run low on time partway through a large backlog, stop after finishing your
-   current raw — do not start a new one you can't complete. This is expected
-   and fine: whatever you already merged is committed to the pages and
-   `log.md`, so the next scheduled run picks up where you left off instead of
-   redoing this run's work.
-
-3. **For the current raw file, read the source and find related pages.**
-   Open the raw file directly from `{{WIKI_DIR}}/raw/`.
-
-   If the file does not read as text (binary content, garbled bytes, e.g. a
-   raw PDF byte-dump that was never text-extracted), do not attempt deep
-   forensic recovery (no web searches, no `strings`-style dumps). Append a
-   one-line `log.md` entry noting it as skipped/unprocessable with a short
-   reason, then move on to the next raw in the queue.
-
-   Otherwise, search for related pages:
-   ```sh
-   akm wiki search {{WIKI_NAME}} "<key terms from the raw source>"
-   ```
-   Read the top hits with `akm show wiki:{{WIKI_NAME}}/pages/<page>`. Use
-   `akm show wiki:{{WIKI_NAME}}/pages/<page> toc` for large pages.
-
-4. **Decide for each candidate.** For each related page:
-   - **Append**: add a section or paragraph under the relevant heading.
-     Include the raw source in the page's `sources:` frontmatter list.
-   - **Contradict**: note the tension explicitly; don't silently overwrite.
-     Follow the schema's contradiction policy.
-   - **Skip**: source doesn't add to this page — move on.
-
-5. **Create new pages for concepts/entities the source introduces**, under
-   `{{WIKI_DIR}}/pages/` (never at the wiki root — only `schema.md`,
-   `index.md`, and `log.md` belong there). Each new page must have
-   frontmatter with `description`, `pageKind`, `xrefs`, and `sources`.
-   Cross-reference with related pages both directions.
-
-6. **Update xrefs both ways.** If page A now xrefs page B, page B must xref
-   page A. `akm wiki lint {{WIKI_NAME}}` will flag violations.
-
-7. **Append to `log.md`.** One entry per processed raw source (ingested or
-   skipped-as-unprocessable): date, raw slug, one-line summary, refs to
-   created/edited pages. Newest at the top.
-
-8. **Regenerate the index + verify.**
-   ```sh
-   akm index
-   akm wiki lint {{WIKI_NAME}}
-   ```
-   Resolve any lint findings before calling the ingest done.
-
-That's it. `akm` never calls an LLM — reasoning is your job; it just owns
-the invariants (raw immutability, ref validation, index regeneration,
-structural lint).

package/dist/assets/wiki/log-template.md

@@ -1,8 +0,0 @@
----
-description: Append-only log for the {{WIKI_NAME}} wiki. Newest entries at the top.
-wikiRole: log
----
-
-# {{WIKI_NAME}} — log
-
-_Each entry: ISO date, operation, brief summary._

package/dist/assets/wiki/schema-template.md

@@ -1,61 +0,0 @@
----
-description: Rules that govern this wiki. Read before ingesting, searching, or editing pages.
-wikiRole: schema
----
-
-# {{WIKI_NAME}} wiki schema
-
-This wiki follows the three-layer pattern:
-
-- `raw/` — immutable ingested sources (never edit)
-- `pages/<page>.md` and `pages/<topic>/<page>.md` — agent-authored pages
-- `schema.md` (this file), `index.md`, `log.md` — wiki-level metadata
-
-## Page frontmatter
-
-Every page should carry frontmatter so akm can index and link it:
-
-```yaml
----
-description: one-sentence summary used in search and lint
-pageKind: entity | concept | question | note | <your-custom-kind>
-xrefs:
-  - wiki:{{WIKI_NAME}}/pages/other-page
-sources:
-  - raw/<slug>.md
----
-```
-
-`pageKind` accepts any non-empty string. Add new categories freely; they
-will surface in `index.md` as new sections after the next `akm index` run.
-
-## Three operations
-
-### Ingest
-
-1. Copy the new source into `raw/` with `akm wiki stash {{WIKI_NAME}} <path>`.
-2. Find related pages: `akm wiki search {{WIKI_NAME}} "<terms>"`.
-3. For each related page: append a section, note a contradiction, or create a
-   new page under `pages/`. Update xrefs on both sides.
-4. Cite the raw source in each touched page's `sources:` frontmatter.
-5. Append one entry to `log.md` describing what was assimilated.
-
-### Query
-
-1. `akm wiki search {{WIKI_NAME}} "<question>"` — find candidate pages.
-2. `akm show wiki:{{WIKI_NAME}}/pages/<page>` — read the top hits.
-3. Compose the answer from the wiki; cite raw sources only when the wiki
-   points at them.
-
-### Lint
-
-1. `akm wiki lint {{WIKI_NAME}}` — deterministic structural checks.
-2. Resolve each finding: link orphans, fix broken xrefs, add descriptions,
-   cite uncited raws, refresh the index.
-
-## Hard rules
-
-- `raw/` is immutable. Never edit ingested sources.
-- Cross-references must point at pages that actually exist.
-- Prefer appending to an existing page over duplicating one.
-- Cite the raw source id (e.g. `raw/2026-04-foo.md`) when copying claims.

package/dist/commands/improve/calibration.js

@@ -1,161 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-// ---------------------------------------------------------------------------
-// Reliability computation
-// ---------------------------------------------------------------------------
-/** Number of fixed-width reliability buckets over [0, 1]. */
-export const CALIBRATION_BUCKET_COUNT = 10;
-function roundRate(value) {
-    return Number(value.toFixed(4));
-}
-/**
- * Assign a confidence in [0, 1] to one of {@link CALIBRATION_BUCKET_COUNT}
- * fixed-width buckets. The final bucket is closed on the right so confidence
- * === 1 lands in the top bucket rather than overflowing.
- */
-function bucketIndex(confidence) {
-    const clamped = Math.min(1, Math.max(0, confidence));
-    const idx = Math.floor(clamped * CALIBRATION_BUCKET_COUNT);
-    return Math.min(CALIBRATION_BUCKET_COUNT - 1, idx);
-}
-/**
- * Compute a deterministic calibration summary from a list of acted-on gate
- * decisions. Pure: identical input always yields identical output, with no
- * dependency on wall-clock time or randomness.
- */
-export function summarizeCalibration(samples) {
-    const buckets = [];
-    const bucketCounts = new Array(CALIBRATION_BUCKET_COUNT).fill(0);
-    const bucketAccepted = new Array(CALIBRATION_BUCKET_COUNT).fill(0);
-    const bucketConfSum = new Array(CALIBRATION_BUCKET_COUNT).fill(0);
-    let accepted = 0;
-    let confSum = 0;
-    for (const sample of samples) {
-        const idx = bucketIndex(sample.confidence);
-        bucketCounts[idx] = (bucketCounts[idx] ?? 0) + 1;
-        bucketConfSum[idx] = (bucketConfSum[idx] ?? 0) + sample.confidence;
-        confSum += sample.confidence;
-        if (sample.outcome === "auto-accepted") {
-            accepted += 1;
-            bucketAccepted[idx] = (bucketAccepted[idx] ?? 0) + 1;
-        }
-    }
-    const total = samples.length;
-    const width = 1 / CALIBRATION_BUCKET_COUNT;
-    for (let i = 0; i < CALIBRATION_BUCKET_COUNT; i += 1) {
-        const count = bucketCounts[i] ?? 0;
-        const acc = bucketAccepted[i] ?? 0;
-        buckets.push({
-            lower: roundRate(i * width),
-            upper: roundRate((i + 1) * width),
-            count,
-            accepted: acc,
-            acceptRate: count > 0 ? roundRate(acc / count) : 0,
-            meanConfidence: count > 0 ? roundRate((bucketConfSum[i] ?? 0) / count) : 0,
-        });
-    }
-    const overallAcceptRate = total > 0 ? roundRate(accepted / total) : 0;
-    const meanConfidence = total > 0 ? roundRate(confSum / total) : 0;
-    return {
-        samples: total,
-        accepted,
-        rejected: total - accepted,
-        overallAcceptRate,
-        meanConfidence,
-        calibrationGap: total > 0 ? roundRate(meanConfidence - overallAcceptRate) : 0,
-        buckets,
-    };
-}
-/**
- * Project a list of `gateDecision` records (read from the proposal store) into
- * the acted-on calibration samples within an optional `[since, until)` window.
- *
- * Only `auto-accepted` / `auto-rejected` decisions with a finite confidence in
- * [0, 1] contribute. `deferred` decisions and decisions missing a confidence
- * are excluded (no realized accept/reject signal). The window filter uses each
- * decision's `decidedAt` timestamp; decisions with an unparseable timestamp are
- * kept only when no window is supplied.
- *
- * Exploration-budget promotions (`reason === "exploration-budget"`) are EXCLUDED:
- * they are accepted regardless of confidence, so they carry no reliability signal
- * about the gate threshold. Counting them would inflate the apparent accept-rate
- * and bias the auto-tuner downward — they are exempt from auto-tune by design
- * (WS-4 exploration budget).
- */
-export function gateDecisionsToSamples(decisions, window) {
-    const sinceMs = window?.since ? new Date(window.since).getTime() : undefined;
-    const untilMs = window?.until ? new Date(window.until).getTime() : undefined;
-    const samples = [];
-    for (const decision of decisions) {
-        if (!decision)
-            continue;
-        if (decision.outcome !== "auto-accepted" && decision.outcome !== "auto-rejected")
-            continue;
-        if (decision.reason === "exploration-budget")
-            continue;
-        const confidence = decision.confidence;
-        if (typeof confidence !== "number" || !Number.isFinite(confidence) || confidence < 0 || confidence > 1)
-            continue;
-        if (sinceMs !== undefined || untilMs !== undefined) {
-            const ts = new Date(decision.decidedAt).getTime();
-            if (!Number.isFinite(ts))
-                continue;
-            if (sinceMs !== undefined && ts < sinceMs)
-                continue;
-            if (untilMs !== undefined && ts >= untilMs)
-                continue;
-        }
-        samples.push({ confidence, outcome: decision.outcome });
-    }
-    return samples;
-}
-/**
- * Compute a bounded, opt-in threshold adjustment from a calibration summary.
- * PURE and deterministic — does not mutate config or read the clock. The
- * caller is responsible for persisting `newThreshold` and logging the result.
- *
- * Algorithm (deliberately simple and bounded):
- *   - When `autoTune` is false → no-op (`disabled`).
- *   - When samples < `minSamples` → no-op (`insufficient-samples`).
- *   - Otherwise nudge by at most `maxStep` toward `targetAcceptRate`, then
- *     clamp into `[minThreshold, maxThreshold]`. The step size scales with the
- *     gap from target but is capped, so a single run can never make a large
- *     swing.
- */
-export function computeThresholdAutoTune(currentThreshold, summary, config) {
-    const previousThreshold = Math.round(currentThreshold);
-    const noop = (reason) => ({
-        adjusted: false,
-        previousThreshold,
-        newThreshold: previousThreshold,
-        delta: 0,
-        reason,
-    });
-    if (!config.autoTune)
-        return noop("disabled");
-    if (summary.samples < config.minSamples)
-        return noop("insufficient-samples");
-    const gap = config.targetAcceptRate - summary.overallAcceptRate;
-    // A small dead-band so tiny noise doesn't churn the threshold every run.
-    const DEAD_BAND = 0.01;
-    if (Math.abs(gap) <= DEAD_BAND)
-        return noop("within-target");
-    // gap > 0 ⇒ realized below target ⇒ raise threshold (be stricter).
-    // gap < 0 ⇒ realized above target ⇒ lower threshold (be more permissive).
-    const direction = gap > 0 ? 1 : -1;
-    // Scale the step with the gap magnitude (in points) but cap at maxStep.
-    const desiredMagnitude = Math.min(config.maxStep, Math.max(1, Math.round(Math.abs(gap) * 100)));
-    const proposed = previousThreshold + direction * desiredMagnitude;
-    const clamped = Math.min(config.maxThreshold, Math.max(config.minThreshold, proposed));
-    const delta = clamped - previousThreshold;
-    if (delta === 0)
-        return noop("clamped-at-bound");
-    return {
-        adjusted: true,
-        previousThreshold,
-        newThreshold: clamped,
-        delta,
-        reason: direction > 0 ? "below-target-raise" : "above-target-lower",
-    };
-}