akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/commands/improve/proposal-envelope.js

@@ -1,31 +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/.
-/**
- * `emitProposal` — the proposal-envelope facade (D10 / R7).
- *
- * Every improve verb that raises a proposal (revise = reflect, learn =
- * distill/promote/extract, consolidate = the merge/promote ops) routes it
- * through this single seam instead of calling {@link createProposal} directly.
- *
- * Since WI-6.2 the envelope carries `changes: FileChange[]` + `beforeHash`:
- * `createProposal` derives a single-entry change set (whose `after` IS
- * `payload.content`) and the mint-time before-state hash for every proposal
- * emitted through this seam — producers stay payload-shaped and get the
- * envelope for free. The facade remains a pass-through: it does NOT synthesise
- * `sourceRun` or mutate the input — each emit site owns its own
- * `source`/`sourceRun`/attribution.
- *
- * Pinned by `tests/commands/improve/proposal-envelope.test.ts`.
- */
-import { createProposal, } from "../proposal/repository.js";
-/**
- * Emit a proposal through the single improve envelope seam. Equivalent to
- * `createProposal(ctx.stashDir, input, ctx.proposalsCtx)`; returns either the
- * persisted {@link import("../proposal/repository.js").Proposal} or a
- * {@link import("../proposal/repository.js").CreateProposalSkipped} record when a
- * dedup/cooldown guard fires (detect with `isProposalSkipped`).
- */
-export function emitProposal(ctx, input) {
-    return createProposal(ctx.stashDir, input, ctx.proposalsCtx);
-}

package/dist/commands/improve/run-context.js

@@ -1,123 +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/.
-/**
- * `RunContext` — the shared, run-scoped carrier for the three improve verbs
- * (revise = reflect, learn = extract/distill/inference, consolidate = the
- * memory-tier ops; D17). WI-7.5–7.8 decompose the improve god-functions into
- * named passes that thread a `RunContext` instead of long positional argument
- * lists.
- *
- * ## The D6 read-once seam
- *
- * `readAsset` is a memoizing file-read seam whose memo is **NEVER run-wide**
- * (D6 / top-risk #7: a run-wide memo would serve prep-time bytes after a mid-run
- * write). The guarantee is structural here, not merely conventional:
- *
- *   - The **base** context returned by {@link createRunContext} has NO active
- *     memo. `readAsset` on it always reads through to disk, so it can never go
- *     stale — the safe default.
- *   - {@link RunContext.withFreshAssetMemo} mints a sibling context that shares
- *     every run-scoped carrier but owns a FRESH, empty memo. Memoization is
- *     therefore opt-in per scope:
- *       * prep's stage-body passes share ONE memo, forked only AFTER the
- *         mutating pre-loop passes have written their ops to disk, then
- *         discarded at stage end;
- *       * reflect and distill each fork their own memo per verb invocation, so
- *         their reads still happen at invoke time (not prep time).
- *   - Within a memo scope, {@link RunContext.writeAsset} writes through to disk
- *     AND refreshes the memo, and {@link RunContext.noteAssetWrite} drops a memo
- *     entry for a path written out-of-band, so a subsequent `readAsset` of the
- *     same path returns POST-write bytes (e.g. the distill in-loop salience
- *     stamp at `distill.ts:816`).
- *
- * The contract is pinned by `tests/commands/improve/run-context.test.ts`.
- *
- * This module deliberately mints only the carrier + seam. Adoption at the verb
- * call sites lands in WI-7.5 (reflect/distill), WI-7.6 (preparation), and
- * WI-7.7 (akmImprove/extract). It does NOT change `EventsContext` shape and does
- * NOT thread a db handle into `ProposalsContext` (D14).
- */
-import fs from "node:fs";
-import path from "node:path";
-import { resolveStashDir } from "../../core/common.js";
-import { recordWrittenPath } from "../../core/write-provenance.js";
-/**
- * Build a `RunContext` over the given carriers with the supplied memo (or `null`
- * for the non-memoizing base context). Kept private so the only way to obtain a
- * memoizing context is {@link RunContext.withFreshAssetMemo}.
- */
-function buildRunContext(carriers, memo) {
-    const memoKey = (filePath) => path.resolve(filePath);
-    return {
-        stashDir: carriers.stashDir,
-        config: carriers.config,
-        eventsCtx: carriers.eventsCtx,
-        proposalsCtx: carriers.proposalsCtx,
-        chat: carriers.chat,
-        getLlmRunner: carriers.getLlmRunner,
-        sourceRun: carriers.sourceRun,
-        dryRun: carriers.dryRun,
-        signal: carriers.signal,
-        now: carriers.now,
-        readAsset(filePath) {
-            if (!memo)
-                return carriers.readFile(filePath);
-            const key = memoKey(filePath);
-            const cached = memo.get(key);
-            if (cached !== undefined)
-                return cached;
-            const bytes = carriers.readFile(filePath);
-            memo.set(key, bytes);
-            return bytes;
-        },
-        writeAsset(filePath, content) {
-            carriers.writeFile(filePath, content);
-            // #652: journal the write for the run's write-provenance set. Recorded
-            // here (not in the default `writeFile` carrier) so an injected IO seam is
-            // attributed identically to a real `fs` write.
-            recordWrittenPath(filePath);
-            memo?.set(memoKey(filePath), content);
-        },
-        noteAssetWrite(filePath) {
-            memo?.delete(memoKey(filePath));
-        },
-        withFreshAssetMemo() {
-            return buildRunContext(carriers, new Map());
-        },
-    };
-}
-/**
- * Create the base `RunContext` for an improve run. Its `readAsset` is
- * non-memoizing (always fresh); call {@link RunContext.withFreshAssetMemo} to
- * enter a memoized pass/invocation scope.
- */
-export function createRunContext(init) {
-    const carriers = {
-        stashDir: init.stashDir,
-        config: init.config,
-        eventsCtx: init.eventsCtx,
-        proposalsCtx: init.proposalsCtx,
-        chat: init.chat,
-        getLlmRunner: init.getLlmRunner ?? (() => null),
-        sourceRun: init.sourceRun,
-        dryRun: init.dryRun,
-        signal: init.signal,
-        now: init.now ?? Date.now,
-        readFile: init.io?.readFile ?? ((filePath) => fs.readFileSync(filePath, "utf8")),
-        writeFile: init.io?.writeFile ?? ((filePath, content) => fs.writeFileSync(filePath, content, "utf8")),
-    };
-    return buildRunContext(carriers, null);
-}
-/**
- * Resolve the run's stash directory at the improve builder boundary: the
- * explicit `options.stashDir` when the caller passed one, else the ambient
- * resolveStashDir() fallback. WI-9.10d: this is the SINGLE resolveStashDir
- * call site on the improve path — the verb entries call THIS instead of
- * resolveStashDir directly, so the ambient read lives only in the builder
- * module. (The CLI-wide resolveStashDir sweep for non-improve commands is a
- * deferred follow-on — see the chunk-9 ledger WI-9.10d entry.)
- */
-export function resolveRunStashDir(explicitStashDir) {
-    return explicitStashDir ?? resolveStashDir();
-}

package/dist/commands/improve/shared.js

@@ -1,31 +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/.
-/**
- * Small pure helpers shared across the improve command family. Extracted to
- * delete byte-identical duplication that previously lived inline in the
- * per-process passes (the whole-corpus synthesis pass removed in 0.9.0 and
- * the procedural-compilation pass removed in 0.9.0). Keep this file free of
- * I/O and of any improve-specific state — these are leaf utilities.
- */
-/**
- * Cap on how many prior rejected proposals for a ref are injected as
- * Reflexion-style verbal-RL context so the LLM avoids regenerating refusals.
- * Shared by both the revise (reflect) and learn (distill) verbs, which
- * previously declared this constant independently.
- */
-export const MAX_REJECTED_PROPOSALS = 3;
-/** Normalize an unknown thrown value to a human-readable message string. */
-export function errMessage(e) {
-    return e instanceof Error ? e.message : String(e);
-}
-/**
- * Slugify an asset ref for use in eval-case / rejection filenames: lowercase,
- * non-alphanumerics collapsed to `-`, capped at 60 characters.
- */
-export function refSlug(ref) {
-    return ref
-        .replace(/[^a-z0-9]/gi, "-")
-        .toLowerCase()
-        .slice(0, 60);
-}

package/dist/commands/improve/source-identity.js

@@ -1,28 +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/.
-// ── Durable improve-state keys ───────────────────────────────────────────────
-//
-// Every improve ref uses the current grammar (a short conceptId), and the durable
-// state key is the resolved index entry's `item_ref` when the planner supplied
-// one, else the conceptId `ref` itself (`preparation.ts`
-// `salienceWriteKey`/`outcomeWriteKey` = `itemRef ?? ref`).
-/**
- * The durable improve-state key for a ref with no resolved `item_ref` — the
- * conceptId `ref` itself.
- */
-export function durableImproveRef(ref) {
-    return ref;
-}
-/** Return the conceptId portion of a durable improve-state key. */
-export function bareImproveRef(ref) {
-    const boundary = ref.indexOf("//");
-    return boundary >= 0 ? ref.slice(boundary + 2) : ref;
-}
-/**
- * The single durable improve-state key used by both readers and writers.
- * Indexed entries use item_ref; direct or provenance-free refs use conceptId.
- */
-export function improveStateReadRefs(ref, itemRef) {
-    return [itemRef ?? ref];
-}

package/dist/commands/improve/triage.js

@@ -1,96 +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/.
-/**
- * Default minimum total score a session must reach to PASS the gate. Tuned
- * conservatively: a single real narrative-lesson session, or a procedurally
- * dense session, clears it — but pure read-only Q&A does not. Config-overridable
- * via `processes.extract.triage.minScore`.
- */
-export const DEFAULT_TRIAGE_MIN_SCORE = 2;
-// Decision / outcome / error narrative markers. Case-insensitive, word-bounded.
-const MARKER_RE = /\b(error|failed|fix(?:ed)?|root cause|turns out|because|decided|instead|gotcha|workaround|regress(?:ed)?|broke|TIL)\b/i;
-// Edit / commit / file-write markers in tool event text.
-const EDIT_COMMIT_RE = /\b(Edit|Write|MultiEdit|git commit|diff)\b/i;
-// A substantive turn is an assistant or tool turn whose text is non-trivial.
-const SUBSTANTIVE_MIN_CHARS = 40;
-/**
- * Pure heuristic scorer. Operates only on `data.events`. Each sub-signal is
- * normalized to a small bounded contribution; `score` is their sum and
- * `pass = score >= minScore`.
- *
- * Sub-signals:
- *   - markers: presence of decision/outcome/error keywords across event text
- *     (capped, narrative-lesson signal).
- *   - toolDensity: bounded contribution from tool-use events.
- *   - editCommit: bounded contribution from edit/write/commit events.
- *   - substantiveRatio: scaled fraction of non-trivial assistant+tool turns,
- *     filtering pure short Q&A.
- *
- * toolDensity + editCommit alone can clear DEFAULT_TRIAGE_MIN_SCORE so
- * high-action / no-narrative sessions are KEPT.
- */
-export function scoreSessionTriage(data, minScore) {
-    const events = data.events;
-    const total = events.length;
-    // (a) markers — count word-bounded marker hits across all event text, capped.
-    let markerHits = 0;
-    for (const e of events) {
-        if (MARKER_RE.test(e.text))
-            markerHits += 1;
-    }
-    // Each marker-bearing event contributes 1 point, capped at 2 (a single real
-    // narrative session clears the bar on markers alone).
-    const markers = Math.min(markerHits, 2);
-    // (b) toolDensity — bounded contribution from tool-use events.
-    let toolEvents = 0;
-    for (const e of events) {
-        if (e.role === "tool")
-            toolEvents += 1;
-    }
-    // 0.25 per tool event, capped at 1.5.
-    const toolDensity = Math.min(toolEvents * 0.25, 1.5);
-    // (c) editCommit — bounded contribution from edit/write/commit markers on
-    // events (filePath present, or text matching the edit/commit regex).
-    let editCommitEvents = 0;
-    for (const e of events) {
-        if (e.filePath || EDIT_COMMIT_RE.test(e.text))
-            editCommitEvents += 1;
-    }
-    // 0.25 per edit/commit event, capped at 1.5. Together with toolDensity a
-    // procedurally dense session reaches well above the default threshold.
-    const editCommit = Math.min(editCommitEvents * 0.25, 1.5);
-    // (d) substantiveRatio — scaled fraction of non-trivial assistant+tool turns.
-    let substantive = 0;
-    for (const e of events) {
-        if ((e.role === "assistant" || e.role === "tool") && e.text.length >= SUBSTANTIVE_MIN_CHARS) {
-            substantive += 1;
-        }
-    }
-    const ratio = total > 0 ? substantive / total : 0;
-    // Scale to a bounded [0,1] contribution.
-    const substantiveRatio = Math.min(ratio, 1);
-    const subscores = { markers, toolDensity, editCommit, substantiveRatio };
-    const score = markers + toolDensity + editCommit + substantiveRatio;
-    // Base gate: score must clear the floor.
-    const pass = score >= minScore;
-    return {
-        pass,
-        score,
-        subscores,
-        ...(pass ? {} : { reason: "low_signal" }),
-    };
-}
-/**
- * Resolve the effective triage config from the extract process config. Mirrors
- * the minContentChars resolution style in akmExtract.
- *
- * Default-off: `enabled` is FALSE unless `triage.enabled === true`. `minScore`
- * defaults to {@link DEFAULT_TRIAGE_MIN_SCORE}.
- */
-export function resolveTriageConfig(extractProcess) {
-    const triage = extractProcess?.triage;
-    const enabled = triage?.enabled === true;
-    const minScore = typeof triage?.minScore === "number" ? triage.minScore : DEFAULT_TRIAGE_MIN_SCORE;
-    return { enabled, minScore };
-}

package/dist/commands/proposal/drain-policies.js

@@ -1,151 +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/.
-/**
- * Built-in deterministic triage policy presets (Proposal-Queue Triage, §3.1).
- *
- * These are the *only* "rule schema" we ship. Custom needs are served by the
- * single `--policy <path>` escape hatch, which zod-validates an external policy
- * file — not by a config-embedded rule engine (see §9, rejected alternatives).
- *
- * | preset           | accepts                                                   | rejects     | leaves pending                                     |
- * |------------------|-----------------------------------------------------------|-------------|----------------------------------------------------|
- * | `personal-stash` | extract (real content); reflect ≤80 lines; consolidate    | empty diffs | consolidate mid-band, distill dups, contradictions |
- * | `conservative`   | small extract + consolidate only                          | empty diffs | everything else                                    |
- * | `manual`         | nothing                                                   | empty diffs | everything else                                    |
- */
-import fs from "node:fs";
-import { z } from "zod";
-import { UsageError } from "../../core/errors.js";
-import { warnOnce } from "../../core/warn.js";
-import { PROPOSAL_SOURCES } from "./repository.js";
-// Valid `generator` values for a drain rule are exactly the canonical proposal
-// `source` values (see {@link PROPOSAL_SOURCES} in src/commands/proposal/repository.ts). The
-// engine matches rules via `policy.accept.find(r => r.generator === proposal.source)`,
-// so a generator that is not a real source can never match — it would be a
-// silent permanent no-op. Validate against the closed set to surface typos.
-const GeneratorSchema = z.enum(PROPOSAL_SOURCES, {
-    errorMap: () => ({
-        message: `must be one of the known proposal sources: ${PROPOSAL_SOURCES.join(", ")}`,
-    }),
-});
-// ---------------------------------------------------------------------------
-// Built-in presets
-// ---------------------------------------------------------------------------
-/**
- * `personal-stash` encodes the deterministic core of today's hand-rolled
- * rubric (the editable `contradicted` memory). It is shipped as a preset, never
- * hardcoded policy: edit a copy via `--policy <path>` to tune it.
- */
-export const PERSONAL_STASH = {
-    name: "personal-stash",
-    accept: [
-        // Extract proposals carry freshly-pulled real content — accept when present,
-        // but cap the diff for parity with reflect(80)/consolidate(200): an
-        // arbitrarily large extract should not auto-promote with zero LLM calls.
-        { generator: "extract", minContentLines: 1, maxDiffLines: 200 },
-        // Reflect refinements: accept small ones; larger refinements defer to review.
-        { generator: "reflect", maxDiffLines: 80 },
-        // Consolidate within the diff band; mid-band lands in `defer` below.
-        { generator: "consolidate", maxDiffLines: 200 },
-    ],
-    rejectEmpty: true,
-    // Mid-band consolidate, distill duplicates, and contradiction escalations are
-    // the irreducibly-semantic tail — deferred to the (Phase 3) judgment tier.
-    defer: ["consolidate", "distill"],
-};
-/** `conservative` accepts only small, low-risk extract + consolidate proposals. */
-export const CONSERVATIVE = {
-    name: "conservative",
-    accept: [
-        { generator: "extract", maxDiffLines: 80, minContentLines: 1 },
-        { generator: "consolidate", maxDiffLines: 80 },
-    ],
-    rejectEmpty: true,
-    defer: [],
-};
-/** `manual` accepts nothing; it only clears empty diffs. */
-export const MANUAL = {
-    name: "manual",
-    accept: [],
-    rejectEmpty: true,
-    defer: [],
-};
-const BUILTIN_POLICIES = {
-    "personal-stash": PERSONAL_STASH,
-    conservative: CONSERVATIVE,
-    manual: MANUAL,
-};
-/** Names of the built-in presets, for help text and validation messages. */
-export const BUILTIN_POLICY_NAMES = Object.keys(BUILTIN_POLICIES);
-// ---------------------------------------------------------------------------
-// Custom policy file schema (`--policy <path>`)
-// ---------------------------------------------------------------------------
-const DrainAcceptRuleSchema = z
-    .object({
-    generator: GeneratorSchema,
-    maxDiffLines: z.number().int().positive().optional(),
-    minContentLines: z.number().int().nonnegative().optional(),
-    requireType: z.string().optional(),
-})
-    .passthrough();
-const DrainPolicySchema = z
-    .object({
-    name: z.string().min(1),
-    accept: z.array(DrainAcceptRuleSchema),
-    rejectEmpty: z.boolean(),
-    defer: z.array(GeneratorSchema),
-})
-    .passthrough();
-function warnIgnoredPolicyKeys(filePath, label, raw, knownKeys) {
-    if (!raw || typeof raw !== "object" || Array.isArray(raw))
-        return;
-    const extra = Object.keys(raw).filter((key) => !knownKeys.includes(key));
-    if (extra.length === 0)
-        return;
-    warnOnce(`drain-policy-ignored-keys:${filePath}:${label}:${extra.join(",")}`, `[proposal] Policy file "${filePath}" has ${label} field(s) akm does not recognize and ignores: ${extra.join(", ")}. Check for a typo, or the file may be written for a newer akm version.`);
-}
-const DRAIN_POLICY_KNOWN_KEYS = Object.keys(DrainPolicySchema.shape);
-const DRAIN_ACCEPT_RULE_KNOWN_KEYS = Object.keys(DrainAcceptRuleSchema.shape);
-/**
- * Resolve a `--policy <preset|path>` argument into a {@link DrainPolicy}.
- *
- *   - A bare preset name (`personal-stash` / `conservative` / `manual`) returns
- *     the matching built-in.
- *   - Anything else is treated as a filesystem path to a JSON policy file, which
- *     is read and zod-validated.
- *
- * Throws a {@link UsageError} on an unknown preset, a missing file, or a file
- * that fails schema validation.
- */
-export function resolveDrainPolicy(arg) {
-    const value = (arg ?? "personal-stash").trim();
-    const builtin = BUILTIN_POLICIES[value];
-    if (builtin)
-        return builtin;
-    // Treat as a path to a custom policy file.
-    if (!fs.existsSync(value)) {
-        throw new UsageError(`Unknown policy "${value}". Use a built-in preset (${BUILTIN_POLICY_NAMES.join(", ")}) or a path to a policy file.`, "INVALID_FLAG_VALUE");
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(fs.readFileSync(value, "utf8"));
-    }
-    catch (err) {
-        throw new UsageError(`Could not parse policy file "${value}": ${err instanceof Error ? err.message : String(err)}`, "INVALID_FLAG_VALUE");
-    }
-    const validated = DrainPolicySchema.safeParse(parsed);
-    if (!validated.success) {
-        throw new UsageError(`Invalid policy file "${value}": ${validated.error.issues.map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`).join("; ")}`, "INVALID_FLAG_VALUE");
-    }
-    warnIgnoredPolicyKeys(value, "top-level", parsed, DRAIN_POLICY_KNOWN_KEYS);
-    if (parsed &&
-        typeof parsed === "object" &&
-        !Array.isArray(parsed) &&
-        Array.isArray(parsed.accept)) {
-        parsed.accept.forEach((rule, index) => {
-            warnIgnoredPolicyKeys(value, `accept[${index}]`, rule, DRAIN_ACCEPT_RULE_KNOWN_KEYS);
-        });
-    }
-    return validated.data;
-}