akm-cli 0.9.18 → 0.9.19-alpha.1

package/dist/storage/repositories/improve-ledger-repository.js

@@ -38,6 +38,33 @@ export const LEDGER_REVISIT_CADENCE_DAYS = 7;
  * eligible again.
  */
 export const PAIR_PASS_LEDGER_SOURCE = "consolidate-pair";
+/**
+ * The consolidate promote pass's ledger source: one row per source memory,
+ * keyed by the memory (`memories/<name>`), not by the knowledge ref the
+ * promotion would create.
+ */
+export const CONSOLIDATE_LEDGER_SOURCE = "consolidate";
+/**
+ * Whether a decision on `(source, outcome)` leaves the ref's next attempt to
+ * its content instead of a clock (#998). An accepted or rejected consolidate
+ * promotion is a verdict on that memory's text; asking the model about the
+ * same text again can only reproduce the proposal (accepted used to be
+ * eligible at once, rejected after 7 days), so the memory waits for an edit.
+ * The clock stays for a row with no recorded hash — one decided before the
+ * hash was recorded — see {@link nextEligibleAt} and {@link isContentDrivenRow}.
+ */
+export function isContentDrivenDecision(source, outcome) {
+    return source === CONSOLIDATE_LEDGER_SOURCE && (outcome === "accepted" || outcome === "rejected");
+}
+/**
+ * Whether this row is held by its content hash: a decided consolidate
+ * promotion that recorded the body it was decided against. Such a row has no
+ * `next_eligible_at`; the caller compares `contentHash` with the asset's
+ * current body hash (the pair pass does the same in `selectInitiators`).
+ */
+export function isContentDrivenRow(row) {
+    return row.contentHash !== null && isContentDrivenDecision(row.source, row.outcome);
+}
 /**
  * Outcomes whose window a fresh signal on the asset (new feedback, a content
  * change) cannot lift. Every other window is a revisit cadence that a signal
@@ -73,12 +100,17 @@ function windowDays(source, outcome) {
 }
 /**
  * The single cadence function: when a `(source, outcome)` recorded at
- * `fromIso` becomes eligible again, or `null` for "immediately".
+ * `fromIso` becomes eligible again, or `null` for "immediately". A decision
+ * that {@link isContentDrivenDecision} holds by content, recorded together
+ * with the body hash it was decided against, starts no clock at all: `null`
+ * here means the hash is the whole test, not that the ref is free to retry.
  */
-export function nextEligibleAt(source, outcome, fromIso) {
+export function nextEligibleAt(source, outcome, fromIso, contentHash) {
     const from = Date.parse(fromIso);
     if (!Number.isFinite(from))
         return null;
+    if (contentHash && isContentDrivenDecision(source, outcome))
+        return null;
     const days = windowDays(source, outcome);
     return days === null ? null : new Date(from + days * MS_PER_DAY).toISOString();
 }
@@ -127,7 +159,7 @@ export function recordImproveLedger(db, input) {
         source: input.source,
         lastAttemptAt: input.at,
         outcome: input.outcome,
-        nextEligibleAt: nextEligibleAt(input.source, input.outcome, input.at),
+        nextEligibleAt: nextEligibleAt(input.source, input.outcome, input.at, input.contentHash),
         proposalId: input.proposalId ?? null,
         detail: trimDetail(input.detail),
         contentHash: input.contentHash ?? null,
@@ -150,14 +182,16 @@ export function recordImproveLedger(db, input) {
  * differ from the ledger key (a distill proposal for `lessons/x` is keyed by
  * its input `memories/x`) — and `last_attempt_at` is kept: the window starts
  * at the decision, the attempt happened when it happened. A proposal no row
- * knows (minted before the ledger existed) gets a row keyed by its own ref.
+ * knows (minted before the ledger existed, or whose row a later `judged_no_action`
+ * overwrote) gets a row keyed by `input.ref`.
  */
 export function recordImproveLedgerDecision(db, input) {
+    const hash = isContentDrivenDecision(input.source, input.outcome) ? input.contentHash : undefined;
     const changes = db
         .prepare(`UPDATE improve_ledger
-       SET outcome = ?, next_eligible_at = ?, detail = ?
+       SET outcome = ?, next_eligible_at = ?, detail = ?, content_hash = COALESCE(?, content_hash)
        WHERE stash_dir = ? AND proposal_id = ?`)
-        .run(input.outcome, nextEligibleAt(input.source, input.outcome, input.at), trimDetail(input.detail), input.stashDir, input.proposalId).changes;
+        .run(input.outcome, nextEligibleAt(input.source, input.outcome, input.at, hash), trimDetail(input.detail), hash ?? null, input.stashDir, input.proposalId).changes;
     if (Number(changes) > 0)
         return;
     recordImproveLedger(db, {
@@ -168,8 +202,33 @@ export function recordImproveLedgerDecision(db, input) {
         at: input.at,
         proposalId: input.proposalId,
         ...(input.detail !== undefined ? { detail: input.detail } : {}),
+        ...(hash !== undefined ? { contentHash: hash } : {}),
     });
 }
+/**
+ * A rejected proposal was reopened (`akm proposal reopen`): put the rows
+ * {@link recordImproveLedgerDecision} found by `proposal_id` back to what the
+ * mint wrote — `proposed`, on the revisit cadence from the reopen, and no
+ * `content_hash` (a mint records none) — so the rejection's hard window stops
+ * reporting (and blocking) a proposal that is pending again.
+ * `last_attempt_at` is kept, as a decision keeps it. A proposal with no such
+ * row (its mint wrote none, or a later attempt took the key over) changes
+ * nothing.
+ */
+export function reopenImproveLedgerDecision(db, input) {
+    db.prepare(`UPDATE improve_ledger
+     SET outcome = 'proposed', next_eligible_at = ?, detail = ?, content_hash = NULL
+     WHERE stash_dir = ? AND proposal_id = ?`).run(nextEligibleAt(input.source, "proposed", input.at), trimDetail(input.detail), input.stashDir, input.proposalId);
+}
+/**
+ * The same reopen for a proposal whose mint deliberately wrote no ledger row (a
+ * retire proposal — see `createRetireProposal`): the row its rejection created
+ * is dropped, returning the ledger to what the mint left. Found by
+ * `proposal_id`, like {@link recordImproveLedgerDecision}.
+ */
+export function forgetImproveLedgerDecision(db, stashDir, proposalId) {
+    db.prepare("DELETE FROM improve_ledger WHERE stash_dir = ? AND proposal_id = ?").run(stashDir, proposalId);
+}
 /**
  * Should-fix 6 (second review round): a read-only or dry-run open never
  * migrates, so it can land on a state.db from before migration 029 added

package/dist/storage/repositories/index-vec-repository.js

@@ -80,9 +80,11 @@ export function upsertEmbedding(db, entryId, embedding, model) {
  * (ties by id): an exact scan of the current model's rows. `distance` is
  * `sqrt(2 * (1 - cosine))`, the L2 distance between the unit-normalised
  * vectors. Rows of another width, left by a model that is no longer current,
- * never match.
+ * never match. With a `scope`, only that bundle's entries of that type are
+ * scanned: the `k` nearest of those, not the `k` nearest of everything filtered
+ * afterwards.
  */
-export function searchVec(db, query, k) {
+export function searchVec(db, query, k, scope) {
     const dim = query.length;
     const q = Float64Array.from(query);
     let queryNorm = 0;
@@ -92,11 +94,13 @@ export function searchVec(db, query, k) {
         return [];
     queryNorm = Math.sqrt(queryNorm);
     const current = modelPredicate(db, currentEmbeddingModel(db));
+    const scoped = scope ? " AND embeddings.id IN (SELECT id FROM entries WHERE type = ? AND bundle_id = ?)" : "";
+    const params = scope ? [...current.params, scope.type, scope.bundleId] : current.params;
     const ids = [];
     const similarities = [];
     const rows = db
-        .prepare(`SELECT id, embedding FROM embeddings WHERE ${current.sql}`)
-        .iterate(...current.params);
+        .prepare(`SELECT id, embedding FROM embeddings WHERE ${current.sql}${scoped}`)
+        .iterate(...params);
     for (const { id, embedding } of rows) {
         if (embedding.byteLength !== dim * 4)
             continue;
@@ -126,14 +130,15 @@ export function searchVec(db, query, k) {
 /**
  * The k nearest neighbours of an already-indexed entry, by its stored vector —
  * no re-embedding, no network. Returns [] when the entry has no stored
- * vector. The entry itself is typically returned with distance ~0; callers
- * filter it out by id.
+ * vector. Unscoped, the entry itself is typically returned with distance ~0;
+ * callers filter it out by id. A `scope` confines the neighbours to one
+ * bundle's entries of one type (see {@link searchVec}).
  */
-export function getNeighborsByEntryId(db, id, k) {
+export function getNeighborsByEntryId(db, id, k, scope) {
     const row = db.prepare("SELECT embedding FROM embeddings WHERE id = ?").get(id);
     if (!row || row.embedding.byteLength % 4 !== 0)
         return [];
-    return searchVec(db, new Float32Array(row.embedding.slice().buffer), k);
+    return searchVec(db, new Float32Array(row.embedding.slice().buffer), k, scope);
 }
 /**
  * Every entry that has no embedding row for `model` (any row when no model is

package/dist/storage/repositories/proposals-repository.js

@@ -106,6 +106,20 @@ const GATE_OUTCOMES = {
     staged: true,
     "auto-rejected": true,
 };
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** One undone rejection in `metadata_json.reviewHistory` (see `ProposalReviewHistoryEntry`): only the fields readers rely on are checked. */
+function isReviewHistoryEntry(value) {
+    if (!isRecord(value))
+        return false;
+    const { review, gateDecision, reopenedAt, reopenReason } = value;
+    return (typeof reopenedAt === "string" &&
+        (reopenReason === undefined || typeof reopenReason === "string") &&
+        (review === undefined ||
+            (isRecord(review) && typeof review.outcome === "string" && typeof review.decidedAt === "string")) &&
+        (gateDecision === undefined || isRecord(gateDecision)));
+}
 function validatePresentMetadata(meta) {
     const stringFields = ["sourceRun", "beforeHash", "beforeHashNormalized", "backupContent"];
     for (const field of stringFields) {
@@ -129,6 +143,12 @@ function validatePresentMetadata(meta) {
             invalidPresentField("review");
         }
     }
+    if (Object.hasOwn(meta, "reviewHistory")) {
+        const history = meta.reviewHistory;
+        if (!Array.isArray(history) || history.some((entry) => !isReviewHistoryEntry(entry))) {
+            invalidPresentField("reviewHistory");
+        }
+    }
     if (Object.hasOwn(meta, "gateDecision")) {
         const gate = meta.gateDecision;
         if (typeof gate !== "object" ||
@@ -270,6 +290,7 @@ export function proposalRowToProposal(row) {
         ...(typeof meta.beforeHash === "string" ? { beforeHash: meta.beforeHash } : {}),
         ...(typeof meta.beforeHashNormalized === "string" ? { beforeHashNormalized: meta.beforeHashNormalized } : {}),
         ...(meta.review !== undefined ? { review: meta.review } : {}),
+        ...(meta.reviewHistory !== undefined ? { reviewHistory: meta.reviewHistory } : {}),
         ...(typeof meta.confidence === "number" ? { confidence: meta.confidence } : {}),
         ...(meta.gateDecision !== undefined ? { gateDecision: meta.gateDecision } : {}),
         ...(typeof meta.backupContent === "string" ? { backupContent: meta.backupContent } : {}),
@@ -332,6 +353,8 @@ export function proposalToRowValues(proposal, stashDir) {
         metaObj.sourceRun = proposal.sourceRun;
     if (proposal.review !== undefined)
         metaObj.review = proposal.review;
+    if (proposal.reviewHistory !== undefined)
+        metaObj.reviewHistory = proposal.reviewHistory;
     if (proposal.confidence !== undefined)
         metaObj.confidence = proposal.confidence;
     if (proposal.gateDecision !== undefined)

package/dist/tasks/run/load-task.js

@@ -107,7 +107,11 @@ export async function loadPreparedTask(id, options) {
                 return { file: await resolveAssetPath(bundleDir, type, name), bundleRoot: bundleDir };
             }
             const resolutionConfig = requiresCommandConfig ? config : loadConfig();
-            const resolvedBundle = resolveWriteTarget(resolutionConfig, bundle, { requireWritable: false });
+            // `bundle` is the qualifier of an asset ref in the task, not a flag.
+            const resolvedBundle = resolveWriteTarget(resolutionConfig, bundle, {
+                requireWritable: false,
+                flag: "The asset ref's bundle",
+            });
             return {
                 file: await resolveAssetPath(resolvedBundle.source.path, type, name),
                 bundleRoot: resolvedBundle.source.path,

package/docs/migration/README.md

@@ -6,6 +6,7 @@ Upgrade guides and per-release migration notes.
 - [v0.9.2 release note](release-notes/0.9.2.md) -- Self-contained terminal upgrade summary shipped for `akm help migrate 0.9.2`
 - [v0.9.16 release note](release-notes/0.9.16.md) -- Source-bound scheduler grants, local execution authority, and split unsafe overrides
 - [v0.9.17 release note](release-notes/0.9.17.md) -- Consolidate's retire proposals and index layout 26, replacing the LLM entity graph with declared links, and `akm improve` scoped to what retrieval actually returns
+- [v0.9.19 release note](release-notes/0.9.19.md) -- `akm improve` scoped to the bundle it writes to (scheduled runs need one `--bundle` run per other bundle), `akm proposal reopen` and the retire-proposal diff, and fewer repeat consolidate promotions
 - [v0.8 -> current v0.9 migration guide](v0.8-to-v0.9.md) -- Package upgrade with fresh current config/state and explicit task conversion
 - [v0.7 -> v0.8 migration guide](v0.7-to-v0.8.md) -- Task schema and 0.8-era changes
 - [v0.5 -> v0.6 migration guide](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md) -- Terminology cut, registry schema v3, publisher changes

package/docs/migration/release-notes/0.9.19.md

@@ -0,0 +1,134 @@
+Migration notes for akm v0.9.19
+
+Nothing has to run after upgrading from 0.9.18: 0.9.19 adds no config keys,
+changes no index layout, adds no state.db migration and leaves scheduler rows
+alone. (0.9.18 asked nothing either. From 0.9.16 or earlier, also read the
+0.9.17 note: akm help migrate 0.9.17.) What changes is which bundle akm
+improve works on, how a rejected proposal is undone, what consolidation and
+distill queue for review, and what akm proposal diff shows for a retirement.
+
+akm improve now improves one bundle: the one it writes to, which is --bundle
+when you pass it, else defaultWriteTarget, else your working bundle
+(AKM_BUNDLE_DIR when set, otherwise defaultBundle). Through 0.9.18 a run also
+picked assets out of your other writable bundles, read each one from the
+bundle that owned it, and filed the proposal in its own write target, so an
+asset that lived elsewhere came back either as a new copy in the write target
+or as an edit of the write target's own copy made from the other bundle's
+text. That no longer happens, and a rewrite filed outside the bundle that
+owns its asset is now refused. If everything you improve lives in one bundle,
+nothing changes for you. If you improve more than one, this is the one action
+in the release: a scheduled akm improve, the shipped akm-improve tasks
+included, now covers only its write target, so add one akm improve --bundle
+run for each other bundle you want improved:
+
+akm task add improve-team --schedule "15 3 * * *" \
+  --command "akm improve --bundle team --skip-if-locked --require-engines"
+
+(The --bundle inside the command string is akm improve's own; the --bundle of
+akm task add itself picks which bundle stores the task.) akm improve skills/x
+for an asset that lives only in another bundle now fails with a not-found
+error whose hint names that bundle, and akm improve team//skills/x works.
+Proposals an older run already queued stay in the queue, so review them with
+akm proposal list: one that creates an asset you already have in another
+bundle, or overwrites this bundle's copy with the other's text, is one of
+those. akm improve --dry-run and --plan now preview the bundle a live run
+improves; with no --bundle or defaultWriteTarget, a dry run used to read
+defaultBundle while a live run started from AKM_BUNDLE_DIR.
+
+A rejection is no longer final. akm proposal reopen <id> [<id> ...] puts
+rejected proposals back to pending and keeps each rejection in the proposal's
+reviewHistory, which akm proposal show prints; a proposal_reopened event goes
+into akm log. Reopen refuses a proposal that is not rejected or whose target
+changed since it was created, by the same rule accept applies: an update needs
+its target unchanged, a create needs the target still absent, and a retire
+proposal needs its successor present and both documents unchanged. It also
+refuses a retire proposal while another pending retire proposal involves
+either of its documents. Given several ids it reopens all of them or none and
+lists every refusal. It takes full ids, since a prefix only matches pending
+proposals (an asset ref works too, for the newest proposal on it while none
+is pending, but never for a retire proposal). The age that retention expiry
+and --older-than see starts over at the reopen, so a scheduled sweep does not
+take a proposal you just put back.
+
+The case that matters most is consolidate's retire proposals. Through 0.9.18,
+akm proposal diff drew a retirement as the file replaced by one blank line,
+so a correct retirement could pass for data loss. One reviewer rejected all
+65 of a bundle's retire proposals that way, and each rejection also kept the
+pair pass from proposing that retirement again while both documents stayed
+unchanged. To take them back, check each rejection's reason (akm proposal
+list --status rejected --generator consolidate-pair --detail normal --format
+json shows it as review.reason) and reopen only those rejected over the diff,
+one id at a time so a refusal skips only that one (the pattern matches the
+reason given here; change it to yours):
+
+akm proposal list --status rejected --generator consolidate-pair \
+  --detail normal --format json \
+  | jq -r '.proposals[] | select(.review.reason // "" | test("blank line"))
+      | .id' \
+  | xargs -r -n 1 akm proposal reopen --reason "diff was misrendered"
+
+A proposal refused because another pending retire proposal involves the same
+document can be reopened once that one is decided. A pair whose documents
+changed after the rejection needs no recovery, because the old rejection only
+held while both were unchanged and the pair pass may judge it afresh. Reopened
+retire proposals wait for you like any other. drain never accepts a retire
+proposal, so read each with akm proposal diff and accept or reject it.
+
+akm proposal diff now draws a retirement as one. The text output has a retire
+header, the pair's verdict (label, reason, and continuity risk when the pair
+was flagged), a note that accept archives the file and revert restores it byte
+for byte, and then only the removed lines under a
++++ /dev/null (retired: archived; successor <ref>) line. In JSON, a retire
+proposal's diff result gains op ("delete"), retirement (retiredRef,
+successorRef, judgeLabel, judgeReason, cosine, and continuityRisk when flagged)
+and note; the diff result of every other proposal is unchanged. A script that
+matched the old "(update: ...)" header on a retire proposal should expect
+"(retire: ...)". akm proposal show --detail full no longer ends a retire
+proposal with an empty payload heading, and a reopened proposal's JSON gains
+reviewHistory.
+
+Consolidation queues fewer repeat promotions. Before it queues a memory as a
+knowledge proposal, it compares the memory with the 20 knowledge docs in its
+bundle nearest to it by stored vector, and skips it, with skip reason
+dedup_covered_by_knowledge, when one of them already holds at least half of
+the memory's distinct 5-word runs. That needs stored vectors: with semantic
+search off the check does nothing and only the exact slug and whole-body
+checks apply. A memory whose promotion was accepted or rejected is now offered
+again only when its body changes (frontmatter edits do not count); it used to
+come back at once after an accept and after 7 days after a rejection. A
+decision an older release recorded has no body hash to compare and keeps
+those old windows. Expect a shorter promotion queue, with the skipped
+memories showing up as skip reasons and warnings in the run's result; to have
+a memory considered again, edit its text.
+
+Three changes keep a tool failure recorded as feedback from becoming a lesson
+about the error or a TODO placeholder in a memory. Reflect's feedback caveat no
+longer offers a TODO: verify placeholder: when feedback asks for something the
+asset lacks, reflect is told to leave the section unchanged. TODO lines earlier
+runs already put in your assets stay until you remove them; grep -rniE
+"TODO:? *verify" over the bundle finds them. Distill's quality judge now also
+scores whether a lesson is about what its source is about, and a lesson judged
+off-subject is dropped as quality_rejected (a ledger row and a distill_invoked
+event, no proposal) instead of passing or waiting in the queue as
+review_needed; the judge also reads the same first 3000 characters of the
+source body, without frontmatter, that the generator saw. The shipped agent
+guidance changed with it: akm help agents now says to record feedback about an
+asset's content, that it helped or turned out wrong, stale or unhelpful, and
+not a failed akm command such as akm show erroring, and akm feedback --help
+says the same of --reason. If you pasted that guide into an AGENTS.md or a
+system prompt, regenerate the block: the old text told agents to record
+--negative "when it fails".
+
+Downgrading to 0.9.18 needs no data change, since no schema moved, but it
+brings some of this back. 0.9.18 does not know reviewHistory: a proposal
+reopened under 0.9.19 reads as an ordinary pending proposal, and 0.9.18 drops
+its history if it rewrites the row (accepting or rejecting it, say). It also
+counts a pending proposal's age from its creation, so a reopened proposal can
+be expired by the next akm improve run (retire proposals never expire) or
+swept by a scheduled accept, reject or drain with --older-than. It does not
+hold a promoted memory either: 0.9.19 records a decided promotion with the
+memory's body hash and no retry time, which 0.9.18 reads as eligible now, so
+those memories go back to consolidation on the next run, a rejected one
+sooner than the 7 days 0.9.18 would have waited. Its improve plans assets
+from every writable bundle again, and its akm proposal diff draws a
+retirement as a blank replacement again.

package/docs/migration/release-notes/README.md

@@ -7,6 +7,11 @@ live one level up in `docs/migration/`.
 
 ## Available notes
 
+- [0.9.19](0.9.19.md) — `akm improve` planning only the bundle it writes to
+  (a scheduled run needs one `--bundle` run per other bundle),
+  `akm proposal reopen` and the retire-proposal diff, consolidate's coverage
+  check and content-driven hold on decided promotions, distill's grounding
+  check, and what a downgrade to 0.9.18 undoes
 - [0.9.17](0.9.17.md) — consolidate's retire proposals and continuity check,
   promotions archiving their source memory, declared links replacing the LLM
   entity graph, index layout 26, scheduler rows carrying their own context,

package/docs/migration/v0.8-to-v0.9.md

@@ -140,7 +140,11 @@ paths (same-filesystem rename, or copy-then-delete across filesystems). A
 lock file is only ever deleted once the same staleness check `akm improve`
 itself uses says its holder is dead; a lock a live run still holds (or one
 this process cannot read) is left in place and reported instead. The whole
-step is idempotent — a second run reports nothing pending.
+step is idempotent — a second run reports nothing pending. 0.9.17-alpha.4
+removed that step: `akm migrate` no longer relocates these files, and one left
+at an old path is inert (nothing reads it). Two of the five writers no longer
+exist either — the improve ledger replaced `distill-rejected/`, and the
+write-only `eval-cases/` path was removed.
 `$STASH/.akm/memory-cleanup/` did not move; it is the one confirmed exception
 to the rule (see Storage locations, above).