akm-cli 0.9.19-alpha.2 → 0.9.19

package/CHANGELOG.md

@@ -6,161 +6,170 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
-## [0.9.19-alpha.2] - 2026-09-30
-
-### Changed
-
-- **Distill's grounding check vetoes only a score of 1; a 2 goes to a person.**
-  0.9.19-alpha.1 made a grounding score of 2 or less `quality_rejected`. A
-  calibration of the lesson judge on a local llama.cpp model (34 cases, 5
-  passes, 199 calls) scored all 4 off-subject lessons grounding 1 in nearly
-  every pass (one scored 2 in 4 of 5 full passes and 1 otherwise), and its only
-  false vetoes, 2 of 120 legitimate judgments, were one on-subject lesson that
-  adds advice beyond its source and scored 2. Temperature 0 did not make the
-  judge repeatable on that server either: scores moved by up to a point between
-  passes. A grounding score of 1 is therefore still `quality_rejected` (an
-  `improve_ledger` row and a `distill_invoked` event, no proposal, reason
-  `Off-subject for its source (grounding 1/5): …`), and a 2 is now
-  `review_needed`, a pending proposal for a person with the reason
-  `Borderline on grounding (2/5), routed to review: …`, even when the mean of
-  novelty and non-redundancy alone would pass it. A mean that alone rejects the
-  lesson stays `quality_rejected`, and a grounding score of 3 to 5 is
-  unchanged.
-
-## [0.9.19-alpha.1] - 2026-09-30
+## [0.9.19] - 2026-09-30
 
 ### Added
 
 - **`akm proposal reopen <id...> [--reason <text>]` (#997).** A rejection was
   final: nothing undid it, and a rejected `consolidate-pair` retire proposal
   also kept the pair pass from ever proposing that retirement again while both
-  documents were unchanged. Reopen moves rejected proposals back to `pending`,
-  keeping the rejection (and the gate verdict that came with it) in the
-  proposal's new `reviewHistory`, which `proposal show` prints; the verdict
-  itself is cleared so the drain sees the proposal as undecided, except a
-  `deferred` one (the quality gate's hand-off to a person), which stays. It is
-  refused unless the proposal is `rejected` and `accept` would not refuse it as
-  stale (an update's target unchanged; a create's target still absent; a retire
-  proposal's successor present and both documents' body hashes as recorded),
-  and a retire proposal is refused while another pending retire proposal
-  involves either of its documents. Several ids are all-or-nothing. The pair pass
-  follows the status: a reopened proposal is no longer a settled pair and,
-  pending, is not minted twice. Its `improve_ledger` row is reset (a retire
-  proposal's rejection row is dropped, any other goes back to `proposed`), the
-  age that retention expiry and `--older-than` (bulk accept/reject, `drain`)
-  see restarts at the reopen, so a scheduled sweep does not take a proposal a
-  person just put back, and a `proposal_reopened` event is appended.
-  `akm proposal reject`'s confirmation prompt no longer says a rejection
-  cannot be undone.
+  documents were unchanged. Reopen moves rejected proposals back to `pending`
+  (a proposal that retention expiry archived is a rejected one too), keeping
+  the rejection, and the gate verdict that came with it, in the proposal's new
+  `reviewHistory`, which `proposal show` prints. The verdict itself is cleared
+  so the drain sees the proposal as undecided, except a `deferred` one (the
+  quality gate's hand-off to a person), which stays. It takes a full id or an
+  asset ref (an id prefix only matches pending proposals) and is refused
+  unless the proposal is `rejected` and `accept` would not refuse it as stale: an update's target
+  unchanged, a create's target still absent, a retire proposal's successor
+  present and both documents' body hashes as recorded. A retire proposal is
+  also refused while another pending retire proposal involves either of its
+  documents. Several ids are all-or-nothing. The pair pass follows the status:
+  a reopened proposal is no longer a settled pair and, pending, is not minted
+  twice. Its `improve_ledger` row is reset (a retire proposal's rejection row
+  is dropped, any other goes back to `proposed`), the age that retention expiry
+  and `--older-than` (bulk accept/reject, `drain`) see restarts at the reopen,
+  so a scheduled sweep does not take a proposal a person just put back, and a
+  `proposal_reopened` event is appended. `akm proposal reject`'s confirmation
+  prompt no longer says a rejection cannot be undone.
 
-### Fixed
+### Changed
 
-- **A tool failure recorded with `akm feedback` no longer becomes a lesson
-  about the error or a `TODO` placeholder in a memory (#999).** Agents
-  recorded `akm show` failing on a memory with a `.derived.md` child (fixed in
-  0.9.17) as negative feedback, and distill and reflect read it as evidence
-  about the memory's content. On one bundle, 9 such events on 8 memories
-  produced 4 distill lessons about "duplicate physical owners" for memories on
-  unrelated subjects (one auto-accepted and live), and a reflect proposal,
-  also auto-accepted, that added a `TODO: verify physical owner` section to a
-  memory, on which a fifth lesson was then built. The shipped hints had told
-  agents to record `--negative` "when it fails"; they, and the help for
-  `akm feedback --reason`, now say a failed akm command is not feedback on the
-  asset. Reflect's feedback caveat no longer offers a `TODO: verify …`
-  placeholder: when feedback asks for information the asset lacks, it says
-  only to leave the section unchanged. The distill quality judge now also
-  scores **grounding**, whether the lesson is about what its source is about
-  (1–2 only for a different subject; a lesson that corrects its source from
-  feedback is not off-subject), and a grounding score of 2 or less is
-  `quality_rejected` (an `improve_ledger` row and a `distill_invoked` event, no
-  proposal) whatever the mean of novelty and non-redundancy is. Such a lesson
-  reads as novel and non-redundant, so it used to pass or, in the review band,
-  be minted as a pending `review_needed` proposal. The judge also reads the
-  same slice of the source the lesson was generated from (its body without
-  frontmatter, first 3000 characters) instead of the raw file's first 2000. A
-  lesson that contradicts its source still reaches a human through the
-  optional fidelity check (`processes.distill.fidelityCheck.enabled`, off by
-  default), and every other `review_needed` reason is unchanged. `TODO:`
-  lines already in a memory are not removed.
-- **Consolidation stops re-proposing memories that `knowledge/` already
-  covers (#998).** The promote pass copied a memory into a new `knowledge/`
-  proposal with no notion of what `knowledge/` already held: the model never
-  sees it, the mint-time checks only caught the same slug or a byte-identical
-  body, and an accepted promotion's memory was eligible again at once (a
-  rejected one after 7 days). On one bundle 88% of a run's proposals came from
-  memories promoted before, one of them 14 times, and 215 of 224 rejections
-  read "covered by an existing knowledge doc". Two changes, no new setting:
-  before queuing a promotion, consolidate now compares the memory with the 20
-  `knowledge/` docs in its bundle nearest to it by stored vector (the lookup
-  the pair pass uses) and skips it, with skip reason
-  `dedup_covered_by_knowledge`, when one of them holds at least half of the
-  memory's distinct 5-word shingles (measured against every knowledge doc,
-  that share was at least 0.5 for 122 of the 224 rejected proposals and for
-  none of the 103 accepted ones; a covering doc past the 20 nearest goes
-  unseen); and a memory whose promotion was accepted or rejected is offered
-  again only when its body changes, the same content-driven rule the pair pass
-  uses, instead of at once or after 7 days. A promotion decided by an older
-  release recorded no body hash and keeps its old windows. With no stored
-  vector (semantic search off) the coverage check does nothing.
-- **`akm improve` no longer files one bundle's assets into another (#1000).**
-  Candidate selection admitted assets from every writable bundle, but every
-  proposal is filed in the run's write target and reflect reads each asset
-  from the bundle that owns it. An asset owned by another bundle therefore
-  came back as a `create` fork in the write target, or as an `update` of the
-  write target's own copy built from the other bundle's copy. A run now plans
-  only the bundle it writes to (`--bundle`, else `defaultWriteTarget`, else
-  the working bundle), and a bare ref scope (`akm improve skills/x`) resolves
-  inside that bundle. Distill's memory-to-knowledge promotion likewise merges
-  only with a doc that already exists in the write target. As a second line of
-  defence, `createProposal` refuses a rewrite whose `itemRef` names an asset
-  owned by a different configured bundle than the queue's. **Narrowed
-  behaviour:** a run no longer picks up assets from your other writable
-  bundles (it used to read them and queue the result in its own write target),
-  so a scheduled `akm improve` now covers only its write target: add one
-  `akm improve --bundle <name>` run per other bundle you want improved.
+- **`akm improve` improves only the bundle it writes to (#1000).** Candidate
+  selection admitted assets from every writable bundle, but every proposal is
+  filed in the run's write target and reflect reads each asset from the bundle
+  that owns it. An asset owned by another bundle therefore came back as a
+  `create` fork in the write target, or as an `update` of the write target's
+  own copy built from the other bundle's copy. A run now plans only the bundle
+  it writes to (`--bundle`, else `defaultWriteTarget`, else the working bundle:
+  `AKM_BUNDLE_DIR` when set, otherwise `defaultBundle`), and a bare ref scope
+  (`akm improve skills/x`) resolves inside that bundle. Distill's
+  memory-to-knowledge promotion likewise merges only with a doc that already
+  exists in the write target. As a second line of defence, `createProposal`
+  refuses a rewrite whose `itemRef` names an asset owned by a different
+  configured bundle than the queue's. **Narrowed behaviour:** a run no longer
+  picks up assets from your other writable bundles (it used to read them and
+  queue the result in its own write target), so a scheduled `akm improve`, the
+  shipped improve task templates included, now covers only its write target:
+  add one `akm improve --bundle <name>` run per other bundle you want improved.
   `akm improve <ref>` for an asset that lives only in another bundle now fails
   with a not-found error whose hint names the remedy (`--bundle team`, or
   `akm improve team//skills/x`). Proposals the old behaviour already queued
   stay in the queue; review them with `akm proposal list`. `--bundle`'s help
   text now says it selects the bundle a run improves and writes to.
-- **`akm improve --dry-run`/`--plan` previews the bundle a live run improves.**
-  With no `--bundle` and no `defaultWriteTarget`, a live run starts from
-  `AKM_BUNDLE_DIR` before `defaultBundle`, but a dry run read `defaultBundle`
-  only, so the two could plan different bundles. The preview now resolves the
-  working bundle the same way.
+- **Consolidation stops re-proposing memories that `knowledge/` already covers
+  (#998).** The promote pass copied a memory into a new `knowledge/` proposal
+  with no notion of what `knowledge/` already held: the model never sees it,
+  the mint-time checks only caught the same slug or an identical body, and an
+  accepted promotion's memory was eligible again at once (a rejected one after
+  7 days). On one bundle 88% of a run's proposals came from memories promoted
+  before, one of them 14 times, and 215 of 224 rejections said the memory
+  duplicated, was covered by, or overlapped an existing knowledge doc. Two
+  changes, no new setting: before queuing a promotion, consolidate now compares
+  the memory with the 20 `knowledge/` docs in its bundle nearest to it by
+  stored vector (the lookup the pair pass uses) and skips it, with skip reason
+  `dedup_covered_by_knowledge` and a warning naming the covering doc, when one
+  of them holds at least half of the memory's distinct 5-word shingles
+  (measured against every knowledge doc, that share was at least 0.5 for 122 of
+  the 224 rejected proposals and for none of the 103 accepted ones; a covering
+  doc past the 20 nearest goes unseen); and a memory whose promotion was
+  accepted or rejected is offered again only when its body (not its
+  frontmatter) changes, the same content-driven rule the pair pass uses,
+  instead of at once or after 7 days. A promotion decided by an older release
+  recorded no body hash and keeps its old windows. With no stored vector
+  (semantic search off) the coverage check does nothing.
+- **Distill's quality judge also scores grounding: a 1 is vetoed, a 2 goes to
+  review (#999).** A lesson about a different subject than its source reads as
+  novel and non-redundant, so it used to pass or, in the review band, be minted
+  as a pending `review_needed` proposal. The judge, which gates
+  memory-to-knowledge promotions the same way, now also scores **grounding**,
+  whether the lesson is about what its source is about: 1 or 2 only for a
+  different subject, 3 for a lesson on the source's subject that goes beyond or
+  corrects it (distill folds feedback into the lesson, and the judge is not
+  shown that feedback), 4 or 5 when the source supports it. Grounding is left
+  out of the mean of novelty and non-redundancy. A grounding score of 1 is
+  `quality_rejected` whatever the mean is (an `improve_ledger` row and a
+  `distill_invoked` event, no proposal, reason
+  `Off-subject for its source (grounding 1/5): …`). A 2 is borderline and is
+  `review_needed`: a pending proposal for a person, with the reason
+  `Borderline on grounding (2/5), routed to review: …`, even when the mean
+  alone would pass it; a mean that alone rejects the lesson stays
+  `quality_rejected`. A 3 to 5 changes nothing. Only a 1 is a veto because the
+  judge is not repeatable enough to discard a 2 unseen: on a calibration on a
+  local llama.cpp model (34 cases, 5 passes), the only legitimate lesson it
+  scored 2 or lower (2 of 120 judgments) was an on-subject lesson that adds
+  advice beyond its source, and temperature 0 did not make the scores
+  repeatable there: they moved by up to a point between passes. The judge also
+  reads the same slice of the source the lesson was generated from (its body
+  without frontmatter, first 3000 characters) instead of the raw file's first
+  2000. A lesson that contradicts its source still reaches a human through the
+  optional fidelity check (`processes.distill.fidelityCheck.enabled`, off by
+  default), and every other `review_needed` reason is unchanged.
+
+### Fixed
+
 - **`akm proposal diff` shows a retire proposal as a retirement (#997).** It
   rendered the retired file as replaced by one blank line (`----`, a lone `+`,
   then every other line as a removal, under an `(update: <ref>)` header) and
   said nothing about the retirement, so one reviewer rejected all 65 of a
   bundle's `consolidate-pair` proposals as "would destroy content". The diff
-  now lists only the removed lines, under a `(retire: <retired> -> <successor>)`
-  header and `+++ /dev/null (retired: archived; successor <ref>)`, and its JSON
-  result gains `op: "delete"`, a `retirement` block under the keys `proposal
-  show` uses (`retiredRef`, `successorRef`, `judgeLabel`, `judgeReason`,
-  `cosine`, and `continuityRisk` when the pair was flagged, which the text
-  output prints as well) and a `note` that accepting archives the file under
-  `.akm/memory-cleanup/archive/` and `akm proposal revert` restores it
-  byte-exactly. The new fields are additive and appear on retire proposals
-  only. `akm proposal show --detail full` also stops ending a retire proposal
-  with a bare `payload:` heading over nothing.
+  now lists only the removed lines, under a
+  `(retire: <retired> -> <successor>)` header and
+  `+++ /dev/null (retired: archived; successor <ref>)`, and its JSON result
+  gains `op: "delete"`, a `retirement` block under the keys `proposal show`
+  uses (`retiredRef`, `successorRef`, `judgeLabel`, `judgeReason`, `cosine`,
+  and `continuityRisk` when the pair was flagged) and a `note` that accepting
+  archives the file under `.akm/memory-cleanup/archive/` and
+  `akm proposal revert` restores it byte-exactly; the text output prints the
+  same verdict and note above the removed lines. The new fields are additive
+  and appear on retire proposals only. `akm proposal show --detail full` also
+  stops ending a retire proposal with a bare `payload:` heading over nothing.
+  Rejections made over the old rendering can be taken back with
+  `akm proposal reopen`.
+- **A tool failure recorded with `akm feedback` no longer becomes a lesson
+  about the error or a `TODO` placeholder in a memory (#999).** Agents recorded
+  `akm show` failing on a memory with a `.derived.md` child (fixed in 0.9.17)
+  as negative feedback, and distill and reflect read it as evidence about the
+  memory's content. On one bundle, 9 such events on 8 memories produced 4
+  distill lessons about "duplicate physical owners" for memories on unrelated
+  subjects (one auto-accepted and live), and a reflect proposal, also
+  auto-accepted, that added a `TODO: verify physical owner` section to a
+  memory, on which a fifth lesson was then built. The shipped hints had told
+  agents to record `--negative` "when it fails"; they, and the help for
+  `akm feedback --reason`, now say a failed akm command is not feedback on the
+  asset (if you pasted `akm help agents` into an AGENTS.md or a system prompt,
+  regenerate it). Reflect's feedback caveat no longer offers a `TODO: verify …`
+  placeholder: when feedback asks for information the asset lacks, it says only
+  to leave the section unchanged. Distill's judge now also checks that a lesson
+  is about its source (see Changed). `TODO:` lines already in a memory are not
+  removed.
+- **`akm improve --dry-run`/`--plan` previews the bundle a live run improves.**
+  With no `--bundle` and no `defaultWriteTarget`, a live run starts from
+  `AKM_BUNDLE_DIR` before `defaultBundle`, but a dry run read `defaultBundle`
+  only, so the two could plan different bundles. The preview now resolves the
+  working bundle the same way.
 - **Errors name the flag the command takes, not the retired `--target`
   (`improve`, `remember`, `clone`, `task`, `proposal --queue`).** A `--bundle`
   that names no configured bundle, names a read-only one, or differs from a
-  bundle-qualified ref (`akm improve team//skills/x --bundle stash`) failed with
-  "--target must reference a source name", "or pass --target to a different
-  source" or "conflicts with --target". `akm improve`, `remember`, `clone` and
-  every `task` verb reject `--target` (renamed `--bundle` in 0.9), and
-  `proposal --queue` takes `--queue`, so each message sent the user to a flag
-  that does not work. They now name the flag the command takes, and the
+  bundle-qualified ref (`akm improve team//skills/x --bundle stash`) failed
+  with "--target must reference a source name", "or pass --target to a
+  different source" or "conflicts with --target". `akm improve`, `remember`,
+  `clone` and every `task` verb reject `--target` (renamed `--bundle` in 0.9),
+  and `proposal --queue` takes `--queue`, so each message sent the user to a
+  flag that does not work. They now name the flag the command takes, and the
   remedy in `akm remember --supersedes` says "re-run with --bundle" instead of
-  "--target". A bundle that came from a ref inside a task (`ghost//workflows/x`)
-  is described as such rather than blamed on a flag. The commands that really
-  take `--target` (`import`, `env`, `secret`, `proposal accept`) are unchanged.
-  Separately, the help for `akm improve --skip-if-locked` said a lock collision
-  without the flag exits 78. It exits 75 (`IMPROVE_LOCK_HELD`), as the CLI
-  reference says. The `--limit` help says "highest salience first" (it said
-  utility), and the `task add --command` help example uses
-  `--strategy reflect-distill` (the `frequent` strategy no longer exists).
+  "--target". A bundle that came from a ref inside a task
+  (`ghost//workflows/x`) is described as such rather than blamed on a flag. The
+  commands that really take `--target` (`import`, `env`, `secret`, and
+  `proposal accept`/`diff`/`revert`) are unchanged.
+- **Stale help and warning text corrected.** The help for
+  `akm improve --skip-if-locked` said a lock collision without the flag exits
+  78. It exits 75 (`IMPROVE_LOCK_HELD`), as the CLI reference says. The
+  `--limit` help says "highest salience first" (it said utility), the
+  `task add --command` help example uses `--strategy reflect-distill` (the
+  `frequent` strategy no longer exists), and improve's warning about missing
+  `show` events now speaks of the retrieval scope (it named a zero-feedback
+  fallback).
 
 ## [0.9.18] - 2026-09-29
 

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

@@ -101,6 +101,13 @@ 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.
 
+One consequence of those old windows: if you deleted the knowledge copies an
+older release promoted, to keep only the memories, those memories have
+neither a hold nor a copy for the coverage check to find, so the first 0.9.19
+run proposes each of them once more, word for word. Reject them (akm proposal
+reject <id> --yes --reason "..."): 0.9.19 records the rejection with the
+memory's body hash, and they stay held until their text changes.
+
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.19-alpha.2",
+  "version": "0.9.19",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [