akm-cli 0.9.6 → 0.9.7

package/CHANGELOG.md

@@ -4,6 +4,196 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.9.7] - 2026-08-31
+
+### Added
+
+- **`akm curate --pack <tokens>` (#746).** Packs the ranked stash hits' full
+  content into a single token-budgeted blob instead of returning refs the
+  caller has to follow up on with N separate `akm show` calls. Content is
+  resolved through the same path `akm show` uses, so a `ref#fragment` hit
+  packs just that section. Drops whole assets from the tail of the ranked
+  list first; only a single highest-rank hit that alone exceeds the budget
+  is truncated. Registry hits are never packed — that separation stays
+  opt-in and there is no flag to override it. Named `--pack` rather than
+  `--budget` because the workflow asset schema already uses `budget` for
+  run-cost caps.
+
+- **`llms.txt`-aware website ingestion (#749).** `akm bundle add` against an
+  origin root now probes `<origin>/llms.txt` first and, when present, uses
+  that author-curated link list as the crawl frontier instead of discovering
+  links by parsing HTML. Each linked page still flows through the same
+  robots-compliant, host-guarded, content-extracting fetch as before, so
+  ingested pages stay individually addressable. Off-origin manifest entries
+  are dropped. The probe is restricted to origin-root URLs, so adding a
+  specific page still fetches that page. Sites without the file fall through
+  to the existing crawler unchanged. `llms-full.txt` is deliberately not
+  read: its `## <path>` separators are ambiguous against real page content.
+
+### Changed
+
+- **The improve-strategy presets were reviewed as a set (#878).** The
+  investigation first believed `thorough` silently ran without validation;
+  that was wrong — every strategy deep-merges onto `default` before
+  resolving, so the old asset behaved correctly. What was real: `thorough`
+  was the only preset of ten relying on that invisible inheritance instead
+  of an explicit process matrix, and its triage used `applyMode: "queue"`
+  while its description promised to "drain the backlog" — queue mode never
+  promotes, so nothing drained. `catchup` had the same inertness:
+  `maxAcceptsPerRun: 100` under queue mode, a key the promote loop never
+  reads.
+
+  Both now use the same judged-promotion pattern as `reflect-distill` and
+  `proactive-maintenance`: `applyMode: "promote"`, `judgment: true`, a
+  per-run accept cap (`thorough` 25, `catchup` 100), and `maxDiffLines:
+  200`. The autonomy gate demotes promote back to queue unless
+  `experimental.improveAutonomy` is enabled, so by default both still
+  review-only; with autonomy on, they actually drain. `thorough` now
+  carries default's full explicit matrix, and a regression test pins
+  "everything default enables, thorough enables identically, plus triage."
+
+### Fixed
+
+- **Pruning a memory no longer leaves dangling belief edges (#884).**
+  `analyzeMemoryCleanup` archives a pruned memory rather than deleting it —
+  the file moves under `.akm/memory-cleanup/archive/` beside a `cleanup.md`
+  audit record naming its `ref` and `originalPath`. Ref resolution only ever
+  looked at the memory's original location, so once #882 made
+  `contradictedBy`/`supersededBy` validatable, every memory pointing at a
+  pruned one began reporting `missing-ref`. `refExistsInAnyStash` now resolves
+  the archive tombstone, so a belief edge to an archived memory is satisfied
+  instead of dangling. Existence only: `resolveRefPathInStash` still ignores
+  the archive, because it returns a path callers mutate (`--supersedes`
+  demotion) and an archived file must never be written to. The contradiction
+  an edge records is preserved rather than erased, which a bare edge-scrub
+  would have destroyed.
+
+  A ref whose target has neither a file nor a tombstone was removed by
+  something other than prune — a hand `git rm`, or a pre-fix release — and is
+  genuinely dangling. Clearing those deletes user assertions, so it is opt-in
+  behind `akm lint --prune-dangling-edges` and is deliberately NOT folded into
+  `--fix`: every other auto-fix repairs a malformed file, whereas this one
+  edits well-formed files to drop a claim about the belief graph. The repair
+  is scoped to the `supersededBy`/`contradictedBy` channels — a stale `xrefs`
+  entry is an ordinary broken link that the author may want to re-target, not
+  delete — and preserves comments, key order, and surviving list entries. It
+  clears the same `writable: false` gate `--fix` does.
+
+  Known limitation: if a memory's only edge on a channel is dropped, a
+  `beliefState:` naming that channel is left without a supporting edge.
+  Choosing a demotion target is a belief-semantics decision this fix does not
+  make. No occurrences existed in the stash that surfaced #884.
+
+- **A corrupt `index.db` now rebuilds instead of failing the command
+  (#865).** `src/core/state-db.ts` documented that "a corrupt index is
+  recovered by deleting it and re-running `akm index`" — that recovery was
+  never implemented. Real on-disk corruption surfaced a raw `SQLITE_CORRUPT`
+  and exited 70, and the existing inline-reindex fallback could not help
+  because it reopened the same corrupt file. `openIndexDatabase` now detects
+  corruption, removes the file and its `-wal`/`-shm` sidecars, and retries
+  the open once. Scoped to `index.db`, which is fully regenerable from the
+  stash; `state.db` is never touched.
+
+- **`akm task sync` accepts an immutable package-local install (#868).** An
+  image-baked akm pinned at a path outside the npm global root was refused
+  outright, and `--rebind` then warned on every sync that the pinned binary
+  was "mutable, unproven" — the opposite of true, training operators to
+  ignore a recurring warning. The npm-global check was only ever a proxy for
+  "this binary won't change out from under the scheduler"; that property is
+  now tested directly, so a launcher this process cannot write to (a
+  read-only mount) is eligible without `--rebind` and without the warning.
+  Writable `npx`/project-`node_modules` installs remain ineligible, which is
+  the case the original check existed for. No new config knob.
+
+- **`TASK_SCHEMA_VERSION_UNSUPPORTED` names the actual blocker (#869).** For
+  a v2/v3 file the message is only reached after the read-time shim has
+  already tried and failed to convert it — meaning a human decision is
+  required — yet it pointed at `akm migrate apply`, which would report the
+  identical block for that same file. The blocked `reason`/`detail` were
+  already computed and then discarded; they are now surfaced, so the error
+  names the specific reason (e.g.
+  `shell-command-resolution-changes-v2-literal-argv-semantics`) and says a
+  decision is needed rather than sending the operator to a command that
+  cannot help.
+
+  Also verified as already fixed and left alone: cross-bundle scoping (a
+  blocked file in one bundle does not prevent conversion in another —
+  resolved by #866) and `env`-prefixed command conversion (resolved by
+  #867).
+
+- **`akm task sync` no longer dead-ends on pre-0.9.2 crontab rows (#881).**
+  Rows written by v0.9.0/v0.9.1 carry no `--scheduler-context` marker, so
+  `extractCronInvocation` could not parse them. Sync therefore saw the task
+  as absent, tried to install it, and collided with the row that was still
+  physically present — permanently blocking sync for every task on any
+  install upgrading past v0.9.2. Such a row is now recognized and
+  reconciled. The fallback fires only when the marker is entirely absent
+  and only inside akm's own `# akm:task … BEGIN/END` sentinels, so a row
+  carrying the marker that fails to parse for any other reason is never
+  reinterpreted, and no ownership or cardinality assertion changed.
+
+- **`akm lint` validates `type:slug` xrefs instead of silently skipping
+  them (#882).** `typeNameFromConceptId` returns `undefined` for the colon
+  grammar, so `classifyConceptRef` treated those refs as "not a local ref"
+  and dropped them before validation — roughly half the xref channel on a
+  real corpus. Zero `missing-ref` findings read as "every reference is
+  healthy" when half had never been examined. akm still writes this
+  grammar today (`memory-contradiction-detect.ts` emits `contradictedBy:`
+  as `memory:<name>`), so it is a live channel, not legacy residue; it is
+  now accepted as a fallback in lint only, leaving the parser and write
+  paths on the single conceptId grammar.
+
+- **Refs to derived memories resolve (#882).** `assetPathCandidatesForName`
+  only ever offered `<name>.md`, so any ref to a memory stored as
+  `<name>.derived.md` failed to resolve — affecting the conceptId grammar
+  equally, and invisible until the above fix made these refs validatable.
+  `.derived` is a provenance marker on the same identity, not part of the
+  name, so `<name>.derived.md` is now a secondary candidate with plain
+  `<name>.md` still taking precedence when both exist. Fixed at the
+  resolution primitive, so write-time `--xref`/`--supersedes` validation
+  benefits as well.
+
+### Removed
+
+- **The `frequent` and `memory-focus` improve strategies.** Zero recorded
+  invocations, and both were mid-points of other presets (`frequent` ≈
+  `reflect-distill` without distill or triage; `memory-focus` a subset of
+  `frequent`). The shipped hourly task template now uses `reflect-distill`
+  — matching what real deployments had already switched to by hand. Any
+  removed combination remains expressible via `improve.strategies` in
+  config. One caveat: a user-config strategy *named* `frequent` or
+  `memory-focus` previously merged over the built-in of the same name; it
+  now merges over `default` only, so a partial override that relied on the
+  built-in's values will resolve differently and should be made explicit.
+
+### Testing
+
+- **The previous-release corpus covers more than task sources (#880).**
+  Added fixtures for the synthesized `AKM_BUNDLE_DIR` duplicate-`stash`
+  bundle shape that caused #870, the retired 0.8 `stashDir`/`sources[]`/
+  `installed[]` config keys, and a downstream consumer's `config.json` plus
+  four task-source-v4 files. The 0.8 fixture deliberately asserts the
+  opposite of the others: those keys are hard-rejected by design, so it
+  guards that the rejection stays loud and actionable rather than silently
+  loading. Every fixture was proven to catch a regression by breaking the
+  guarantee, observing the failure, and reverting.
+
+- Pinned current handling of truncated LLM responses (`finishReason:
+  "length"`) as a regression test (#865). No distinct classification or
+  retry was added: the underlying truncation was already resolved by
+  `reasoningEffort`, and threading the finish reason through four layers to
+  earn one diagnostic label was not justified.
+
+### Not shipped
+
+- **Orphan-asset detection for `akm health` (#750)** was implemented and
+  then backed out after measurement. Against a live 23,859-entry index it
+  flagged 16,609 of 16,615 in-scope assets (99.96%) and took 135 s. The
+  corpus is not densely cross-linked — 1,591 distinct xref tokens exist in
+  total — so the check has no signal to give. The broken-ref half of #750
+  had already shipped previously. Moved to Backlog; see #882 for the
+  resolver defect the investigation exposed.
+
 ## [0.9.6] - 2026-08-31
 
 The deletion release: **net −2,100 lines**, almost all of it machinery that

package/dist/assets/hints/cli-hints-full.md

@@ -245,8 +245,8 @@ akm improve --no-push                         # commit but skip push for this ru
 akm improve --sync                            # force sync even on strategies that disable it
 ```
 
-Strategy sync defaults: `catchup`, `consolidate`, `default`, `frequent`,
-`graph-refresh`, `memory-focus`, `quick`, and `thorough` auto-commit + push;
+Strategy sync defaults: `catchup`, `consolidate`, `default`,
+`graph-refresh`, `quick`, and `thorough` auto-commit + push;
 `proactive-maintenance` and `reflect-distill` skip sync entirely. Override
 with `--sync` / `--no-sync` flags.
 
@@ -355,7 +355,7 @@ scheduler (cron / launchd / schtasks). The file is the source of truth:
 file plus one `sync` is a complete workflow.
 
 ```sh
-akm task add nightly-improve --schedule "@daily" --command "akm improve --strategy frequent"
+akm task add nightly-improve --schedule "@daily" --command "akm improve --strategy default"
 akm task add briefing --schedule "0 9 * * *" --prompt "Draft the morning briefing"  # Inline command task
 akm task sync                                  # Reconcile task files with the OS scheduler
 akm task sync --rebind                         # Also re-pin the scheduler's akm binary/spelling

package/dist/assets/improve-strategies/catchup.json

@@ -1,15 +1,44 @@
 {
-  "description": "Manual catch-up — consolidation + triage drain with no interval minimum.",
+  "description": "Manual catch-up \u2014 consolidation plus a judged triage drain (up to 100 accepts) with no interval minimum. Auto-accepts only when improve autonomy is enabled; otherwise proposals queue for review.",
   "processes": {
-    "reflect": { "enabled": false },
-    "distill": { "enabled": false },
-    "consolidate": { "enabled": true, "allowedTypes": ["memory"], "maxChunkSize": 50, "minPoolSize": 0 },
-    "memoryInference": { "enabled": false },
-    "graphExtraction": { "enabled": false },
-    "extract": { "enabled": false },
-    "triage": { "enabled": true, "applyMode": "queue", "policy": "personal-stash", "maxAcceptsPerRun": 100 },
-    "validation": { "enabled": false },
-    "proactiveMaintenance": { "enabled": false }
+    "reflect": {
+      "enabled": false
+    },
+    "distill": {
+      "enabled": false
+    },
+    "consolidate": {
+      "enabled": true,
+      "allowedTypes": ["memory"],
+      "maxChunkSize": 50,
+      "minPoolSize": 0
+    },
+    "memoryInference": {
+      "enabled": false
+    },
+    "graphExtraction": {
+      "enabled": false
+    },
+    "extract": {
+      "enabled": false
+    },
+    "triage": {
+      "enabled": true,
+      "applyMode": "promote",
+      "policy": "personal-stash",
+      "maxAcceptsPerRun": 100,
+      "judgment": true,
+      "maxDiffLines": 200
+    },
+    "validation": {
+      "enabled": false
+    },
+    "proactiveMaintenance": {
+      "enabled": false
+    }
   },
-  "sync": { "enabled": true, "push": true }
+  "sync": {
+    "enabled": true,
+    "push": true
+  }
 }

package/dist/assets/improve-strategies/thorough.json

@@ -1,15 +1,53 @@
 {
-  "description": "Like default, plus the triage process (drains the pending-proposal backlog).",
+  "description": "Everything default runs, plus a judged triage drain of the pending-proposal backlog (up to 25 accepts per run). Auto-accepts only when improve autonomy is enabled; otherwise proposals queue for review. Identical tuning to default; improve-stage extract and proactive maintenance stay off.",
   "processes": {
     "reflect": {
       "enabled": true,
+      "limit": 25,
       "allowedTypes": ["agent", "command", "knowledge", "lesson", "memory", "skill", "workflow"]
     },
-    "distill": { "enabled": true, "allowedTypes": ["memory"] },
-    "consolidate": { "enabled": true, "allowedTypes": ["memory"] },
-    "memoryInference": { "enabled": true },
-    "graphExtraction": { "enabled": true },
-    "triage": { "enabled": true, "applyMode": "queue" }
+    "distill": {
+      "enabled": true,
+      "allowedTypes": ["memory"],
+      "requirePlannedRefs": true
+    },
+    "consolidate": {
+      "enabled": true,
+      "allowedTypes": ["memory"],
+      "minPoolSize": 500
+    },
+    "memoryInference": {
+      "enabled": true
+    },
+    "graphExtraction": {
+      "enabled": true
+    },
+    "extract": {
+      "enabled": false,
+      "triage": {
+        "enabled": true,
+        "minScore": 2
+      }
+    },
+    "validation": {
+      "enabled": true
+    },
+    "proactiveMaintenance": {
+      "enabled": false,
+      "dueDays": 30,
+      "maxPerRun": 15
+    },
+    "triage": {
+      "enabled": true,
+      "applyMode": "promote",
+      "policy": "personal-stash",
+      "maxAcceptsPerRun": 25,
+      "maxDiffLines": 200,
+      "judgment": true
+    }
   },
-  "sync": { "enabled": true, "push": true }
+  "sync": {
+    "enabled": true,
+    "push": true
+  }
 }

package/dist/assets/tasks/improve/akm-improve-frequent.yml

@@ -1,4 +1,4 @@
 version: 4
-run: akm improve --strategy frequent --skip-if-locked
-description: Frequent inference pass (hourly at :40; improve-stage extract off)
+run: akm improve --strategy reflect-distill --skip-if-locked
+description: Frequent learning pass (hourly at :40) — reflect, distill, memory inference, judged triage
 schedule: "40 * * * *"

package/dist/commands/agent/contribute-cli.js

@@ -139,6 +139,16 @@ export const lintCommand = defineCommand({
             description: "Exit non-zero when summary.flagged > 0 (CI-friendly). Default: exit 0 regardless of findings.",
             default: false,
         },
+        // #884: NOT folded into `--fix`. Every other auto-fix repairs a structural
+        // defect in the file it edits; this one DELETES an assertion the user (or
+        // the improve pipeline) made about the belief graph, and it does so in
+        // files that are themselves perfectly well-formed. That is a data decision,
+        // so it stays opt-in behind its own flag even when `--fix` is present.
+        "prune-dangling-edges": {
+            type: "boolean",
+            description: "Opt-in repair: drop supersededBy/contradictedBy entries whose target has neither a file nor a prune tombstone. Modifies memories — review the plain `akm lint` report first.",
+            default: false,
+        },
         type: {
             type: "string",
             description: "Only lint assets of this type (e.g. workflows, tasks, memories). akm bundles only — every other adapter validates the whole bundle and warns that the flag had no effect.",
@@ -151,6 +161,7 @@ export const lintCommand = defineCommand({
                 fix: args.fix === true || getHyphenatedBoolean(args, "auto-fix"),
                 dir: getStringArg(args, "dir"),
                 typeFilter: getStringArg(args, "type"),
+                pruneDanglingEdges: getHyphenatedBoolean(args, "prune-dangling-edges"),
             });
             output("lint", result);
             if (args["fail-on-flagged"] && result.summary.flagged > 0) {

package/dist/commands/improve/improve-cli.js

@@ -114,7 +114,7 @@ export const improveCommand = defineCommand({
         },
         strategy: {
             type: "string",
-            description: "Named improve strategy from improve.strategies or built-in strategies (catchup, consolidate, default, frequent, graph-refresh, memory-focus, proactive-maintenance, quick, reflect-distill, thorough). Controls which sub-processes run and which asset types are processed.",
+            description: "Named improve strategy from improve.strategies or built-in strategies (catchup, consolidate, default, graph-refresh, proactive-maintenance, quick, reflect-distill, thorough). Controls which sub-processes run and which asset types are processed.",
         },
         sync: {
             type: "boolean",

package/dist/commands/improve/improve-strategies.js

@@ -4,9 +4,7 @@
 import catchup from "../../assets/improve-strategies/catchup.json" with { type: "json" };
 import consolidate from "../../assets/improve-strategies/consolidate.json" with { type: "json" };
 import defaultStrategy from "../../assets/improve-strategies/default.json" with { type: "json" };
-import frequent from "../../assets/improve-strategies/frequent.json" with { type: "json" };
 import graphRefresh from "../../assets/improve-strategies/graph-refresh.json" with { type: "json" };
-import memoryFocus from "../../assets/improve-strategies/memory-focus.json" with { type: "json" };
 import proactiveMaintenance from "../../assets/improve-strategies/proactive-maintenance.json" with { type: "json" };
 import quick from "../../assets/improve-strategies/quick.json" with { type: "json" };
 import reflectDistill from "../../assets/improve-strategies/reflect-distill.json" with { type: "json" };
@@ -45,9 +43,7 @@ const BUILTIN_STRATEGIES = {
     default: defaultStrategy,
     quick,
     thorough,
-    "memory-focus": memoryFocus,
     "graph-refresh": graphRefresh,
-    frequent,
     consolidate,
     catchup,
     "reflect-distill": reflectDistill,

package/dist/commands/improve/memory/memory-improve.js

@@ -5,6 +5,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { assembleAsset } from "../../../core/asset/asset-serialize.js";
 import { mutateFrontmatter, parseFrontmatter } from "../../../core/asset/frontmatter.js";
+import { MEMORY_ARCHIVE_REL } from "../../../core/asset/memory-archive.js";
 import { conceptIdFromTypeName } from "../../../core/asset/resolve-ref.js";
 import { asNonEmptyString, groupBy, stringArray } from "../../../core/common.js";
 import { DERIVED_SUFFIX } from "../../../core/recognition-util.js";
@@ -553,7 +554,7 @@ function priorBeliefStateForArchive(candidate) {
 }
 function createArchiveDir(stashDir, ref, archivedAt) {
     const baseName = `${archivedAt.replace(/[:.]/g, "-")}-${sanitizeRef(ref)}`;
-    const root = path.join(stashDir, ".akm", "memory-cleanup", "archive");
+    const root = path.join(stashDir, MEMORY_ARCHIVE_REL);
     fs.mkdirSync(root, { recursive: true });
     let attempt = 0;
     while (true) {

package/dist/commands/improve/preparation.js

@@ -760,7 +760,7 @@ async function runPreparationPrelude(args) {
     };
 }
 export async function runImprovePreparationStage(args) {
-    const { scope, options, plannedRefs, primaryStashDir, eventsCtx, initialCleanupWarnings, improveProfile, resolvedPlan, planOnly = options.dryRun === true, } = args;
+    const { scope, options, primaryStashDir, eventsCtx, initialCleanupWarnings, improveProfile, resolvedPlan, planOnly = options.dryRun === true, } = args;
     const actions = [];
     const cleanupWarnings = initialCleanupWarnings ? [...initialCleanupWarnings] : [];
     const { memoryIndexHealth, consolidationPass, extractPlan, extractResults, appliedCleanup, postCleanupRefs, cleanupGate, validationFailures, validationFailureRefs, schemaRepairs, } = await runPreparationPrelude({ ...args, planOnly, actions, cleanupWarnings });

package/dist/commands/improve/reflect.js

@@ -790,7 +790,7 @@ function parseDirectReflectOutput(raw, mode, targetRef) {
 export async function runReflectViaLlm(opts) {
     const start = Date.now();
     let repairAttempts = 0;
-    const connection = opts.runner.connection;
+    const _connection = opts.runner.connection;
     const messages = [{ role: "user", content: opts.prompt ?? "" }];
     const configuredTimeout = Object.hasOwn(opts, "timeoutMs")
         ? (opts.timeoutMs ?? null)