akm-cli 0.9.26-alpha.2 → 0.9.27-alpha.1

package/CHANGELOG.md

@@ -6,6 +6,300 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.27-alpha.1] - 2026-10-06
+
+### Fixed
+
+- **A codex dispatch with an output schema no longer leaves a temp folder
+  behind.** Every build of the codex command for a request with a schema made a
+  new `akm-codex-schema-*` folder in the OS temp dir for `--output-schema` and
+  nothing ever removed it (the builder has no post-run hook, and the file is read
+  after it returns), so a machine whose `/tmp` is tmpfs held a folder in RAM per
+  dispatch until reboot. The schema is now written once to akm's cache dir, in a
+  file named by its hash: concurrent units dispatching the same schema share it,
+  a rewrite is an atomic rename of identical bytes, and the only residue is one
+  small file per distinct schema.
+- **An index that has been updated ranks like a fresh index of the same files,
+  and `akm index --full` no longer doubles the full-text totals.** `entries_fts`
+  is contentless, and FTS5 cannot take a deleted row out of a contentless
+  table's BM25 totals (its row count, and the token counts the average document
+  length comes from). Every replaced or removed row left them one row too high:
+  40 notes read 40, then 41 after one edit, then 81 after `--full`, and a delete
+  never lowered them, so scores drifted away from what a fresh index gives.
+  SQLite has no command that recomputes them (`delete` and `rebuild` are refused
+  on a contentless table), so a delete that removes a row now stamps
+  `index_meta.ftsTotalsStale` in its own transaction, whichever process made it,
+  and the next `akm index` rebuilds the table from `entries` before it finishes:
+  about a second at 25,000 entries, and only when rows have left the table. A
+  row the write-path index replaced after an accepted proposal is settled the
+  same way, and an index that has already drifted is corrected by the first run
+  that replaces or removes a row.
+- **`akm improve` runs against an API that rejects `chat_template_kwargs`,
+  OpenAI's among them.** Improve's reflect, consolidate and judge calls always
+  ask for thinking off, and the client sends that as
+  `chat_template_kwargs.enable_thinking` and a top-level `enable_thinking`. A
+  strict API answers 400 `Unknown parameter: 'chat_template_kwargs'`, the retry
+  without the response schema sent both fields again, and `akm improve judge`
+  reported `judge timeout/error — routed to review`. No engine setting could
+  stop it: the call sites override the engine's `enableThinking`, and
+  `extraParams` can only add fields. A 4xx that names either field is now
+  answered by one retry without both (which may in turn fall back without the
+  schema), and akm stops sending them to that endpoint and model for the rest
+  of the process, as it already does for `response_format`.
+- **A lesson the model wrote without a `when_to_use` is no longer thrown away
+  silently by `akm proposal extract`.** The extract schema left `when_to_use`
+  optional while the parser dropped a lesson without one (or with one under 15
+  characters) and said nothing, so a model that followed the schema could
+  write a sound lesson that akm discarded and the session reported no
+  candidates: on akm-eval's extract eval qwen3.8-27b kept 3 of 11 expected
+  insights against 9 for gpt-oss-120b. Every property of the schema is now
+  required, `when_to_use` and `rationale_if_empty` included, with an empty
+  string for none (a memory or knowledge candidate needs no trigger, a
+  non-empty answer no rationale), which is also what a strict structured-output
+  provider needs; the prompt's output contract says the same. Any candidate the
+  contract still refuses, for this reason or another, is named in its session's
+  `warnings` as `<type>:<name> dropped: <reason>`.
+- **Distill's response schemas are valid for a strict structured-output
+  provider.** The client sends a response schema `strict: true`, and OpenAI
+  refuses one whose objects leave a property out of `required`: `400 Invalid
+  schema for response_format 'akm_response': ... Missing 'tags'`. The lesson
+  schema left out `tags`, and the knowledge schema `tags` and `sources`, so
+  the first distill request on such a provider always failed. After a 4xx the
+  client retries once without the schema, but a gateway that answers the same
+  rejection with a 502 is not retried, and every distill call through it
+  failed; the workaround, `supportsJsonSchema: false`, loses the guidance that
+  keeps a model from leaving out `when_to_use`. Every property is now
+  required, and an empty array stands for none (distill already dropped an
+  empty `tags` or `sources`).
+- **`akm improve` no longer reflects on an asset whose file a proposal would not
+  write, so accepting a reflect proposal no longer adds a second file.** A
+  skill's `references/a.md` is indexed as `knowledge/skills/<name>/references/a`,
+  but a proposal writes the path derived from that ref,
+  `knowledge/skills/<name>/references/a.md`. Nothing is there, so the proposal
+  was a `create`, and accepting it wrote a copy beside the skill's own file;
+  later proposals then revised the copy while the skill's file drifted. Reflect
+  now refuses before it calls the model, naming the file and the path a
+  proposal would write, and the loop records it as a skip (`unsupported_type`,
+  `file_outside_layout` in the `reflect_completed` event). This is the rule
+  0.9.26 added to `akm feedback --replace`. An asset that another bundle owns is
+  still refused by `createProposal` (#1000).
+- **An index that 0.9.1 wrote no longer crashes akm.** Every `akm index` on it
+  exited 70 with `null is not an object (evaluating 'doc.xrefs')`, `akm migrate
+  apply` and `akm index --full` did not help, and `akm search` failed with
+  `null is not an object (evaluating 'item.entry.quality')`; the only way out
+  was moving `index.db` aside. That layout (20) keeps the transitional
+  `entry_key`, `dir_path`, `stash_dir`, `entry_json` and `entry_type` columns
+  that layout 21 removed, each NOT NULL, beside the current columns, and leaves
+  `document_json` NULL on every row. The table had every column akm checks for,
+  so it was taken for a current one: the links migration read the NULL
+  documents, and no insert could ever have succeeded (`NOT NULL constraint
+  failed: entries.entry_key`). akm now treats a table that still has a retired
+  column as older than layout 21, as the compat notes already said: the
+  writable opener recreates its entries-keyed tables (the LLM enrichment cache
+  is kept) and the next `akm index` re-walks every source, and a read rebuilds
+  inline. An index that a failed open already half-migrated (layout stamp still
+  20, `search_text` dropped, `asset_links` created) recovers the same way.
+- **Two files that claim one ref no longer trade places in the index, and `akm
+  index` says so.** A skill's `references/a.md` and a note at
+  `knowledge/skills/x/references/a.md` are both the ref
+  `knowledge/skills/x/references/a`, and the index holds one row for it. The
+  first file a run persisted held it, so a full build followed the filesystem's
+  listing order (one bundle indexed on tmpfs and on ext4 held different files),
+  and the first incremental run after a full build handed the row to the other
+  file, because it drains only the directory that lost: with no file touched,
+  the row, its search entry and the text its vector is embedded from changed,
+  and the vector was dropped and recomputed. When a smaller-path file was added
+  later and then deleted, the ref also left the index until `--full`, although
+  its other file was still on disk. The file with the smaller path (code-point
+  order, as `akm show`'s refusal lists them) now holds the ref however the
+  directories are drained and the walk is ordered, a directory that gives a ref
+  up is drained again so the ref passes back when its holder goes, and each
+  pair is reported in the `warnings` of `akm index`, naming the file indexed
+  and the one skipped.
+- **Consolidate's plan schema and the session summary schema are valid for a
+  strict structured-output provider, and a new response schema can no longer
+  skip the rule.** The client sends a response schema `strict: true`, and
+  OpenAI refuses one whose objects leave a property out of `required`. The
+  consolidate plan left out `description` and `confidence`, and the session
+  summary `tags`, so the first request of every plan and every summary to such
+  a provider was refused. The client then retries without the schema and
+  remembers that per connection (endpoint and model), not per schema, so one
+  invalid schema also switched the response schema off for every valid one
+  that followed on that connection. Every property of both is now required: an
+  empty `description` keeps the memory's own, a null `confidence` records none
+  and an empty `tags` array is no tags, which is how all three were already
+  read. A contract test runs every schema akm sends through the rule, so a
+  property added later without being required fails CI.
+
+## [0.9.26] - 2026-10-05
+
+The stable release of the 0.9.26 line: 0.9.26-alpha.1 and alpha.2, and the
+changes in this section. When upgrading from 0.9.25:
+
+- **Consolidate retires far fewer notes that hold something the kept note
+  lacks.** Its pair judge lists what each note alone holds and akm never
+  retires a note with anything listed; on 385 held-out pair proposals, 91% of
+  its retirements are safe, against 61% before. A duplicate that a second look
+  confirms is accepted by the triage drain (alpha.1).
+- **Negative feedback can carry the fix:** `akm feedback --negative --replace
+  "<exact text>" --with "<corrected>" --source "<evidence>"` (alpha.2), and
+  `--outdated` or `--superseded-by <ref>` to mark a note's history. Either
+  becomes one `feedback` proposal for review.
+- **Negative feedback is for wrong or stale content.** The hints and docs say
+  so; a note that did not fit the task records nothing. Each feedback event now
+  records the hash of the text it judged, and reflect marks feedback given on
+  an earlier version.
+- **Distill no longer accepts a lesson unattended.** A lesson that passes its
+  judge waits for review instead of the drain, and distill skips a memory
+  flagged wrong since its last edit, one whose only feedback is a positive
+  without a reason, and a lesson that already exists.
+- **Fixed:** a proposal no longer rewraps a note's frontmatter to add its
+  `type`, and accepting one stamps its provenance as lines of its own instead
+  of writing the frontmatter out again; a feedback fix for an asset outside the
+  bundle's layout is refused instead of queued at the wrong path.
+- **Removed:** `akm feedback --failure-mode` and `feedback.allowedFailureModes`
+  (an old config still loads, naming the key once).
+
+### Added
+
+- **`akm feedback --negative --superseded-by <ref>` and `--outdated` mark an
+  asset's history, in the same single `feedback` proposal as any `--replace`
+  edits.** `--superseded-by` (another asset replaces this one) sets
+  `beliefState: superseded` and adds the ref to `supersededBy`; akm resolves it
+  through the index first, and it must be indexed and not the asset itself, or
+  nothing is recorded. The rules are those of `akm remember --supersedes`: an
+  asset that already says so is left as it is, `contradicted` and `archived`
+  stay, and a scalar `supersededBy` becomes a list. `--outdated` (the asset
+  describes a past state and nothing replaces it) sets `beliefState:
+  deprecated`, unless the asset already says superseded, contradicted or
+  archived. Like every fix, both are for negative feedback and need `--reason`
+  and `--source`; they apply to markdown assets and are not used together. akm
+  edits only the `beliefState` and `supersededBy` lines of the text, so
+  comments, quoting, key order and line endings stay (it writes the frontmatter
+  out again only when a line edit cannot follow how a key is spelled), and `fix`
+  in the command's output and in the feedback event says what was set.
+
+### Changed
+
+- **Each feedback event records the text it judged, and reflect marks feedback
+  given on an earlier version of it.** `akm feedback` adds `contentHash`, the
+  sha256 of the asset's body without its frontmatter as it stood when the
+  feedback was given, to the event and its usage row, for positive and negative
+  feedback. It is left out for an env or secret file, whose bytes akm never
+  reads, and when the file cannot be read. When reflect gathers an asset's
+  recent feedback, a line whose `contentHash` differs from the asset's current
+  body ends with ` (given on an earlier version of the text)`, so the model
+  knows the text changed since. A line without a `contentHash` (all feedback
+  recorded before this change) or with a matching one reads as before, and the
+  rest of the prompt is unchanged.
+- **The shipped hints and docs say what negative feedback is for.** Record
+  `akm feedback --negative` only when an asset's content is wrong or stale, and
+  say what is wrong and what it should say. A note that simply did not fit the
+  task is not negative feedback: record nothing for it. Once the correct fact is
+  verified, attach the exact fix with `--replace`/`--with`/`--source`. Of the 195
+  negative reasons recorded in the last 30 days, 100 named no error in the note,
+  and 89 of those only said it did not fit the agent's task, which still lowered
+  the note's ranking and sent it to improve. The hints and the guides no longer
+  list "unhelpful" among the reasons to flag a note, and their example reasons
+  name a wrong fact instead of "wrong framework" or "incomplete-edge-cases". The
+  hints also say that an outdated note can be marked with `--outdated`, or
+  `--superseded-by <ref>` when another note replaces it.
+- **Distill skips a memory that was flagged wrong and not edited since.** A
+  memory with negative feedback in the last 30 days on the text it still has is
+  no source for a lesson, so the improve loop skips distill for it: a
+  `distill-skipped` action with the reason "flagged wrong since its last edit"
+  and an `improve_skipped` event (`distill_flagged_wrong`). The attempt goes in
+  the improve ledger as `unchanged`, so the memory waits for newer feedback, and
+  reflect still plans it. Feedback records the hash of the body it judged
+  (`contentHash`), so a write that leaves the body alone, such as an inference
+  stamp or an accepted frontmatter repair, does not lift the flag; changing the
+  body does. Feedback recorded without a hash keeps the earlier test: it flags
+  the memory while it is newer than the file's last write (its modification
+  time, as in the retrieval scope's new-material test), so any later write ends
+  it. An explicit `akm improve <ref>` still distills it.
+- **A distill proposal that passes the quality judge goes to review, not to the
+  drain.** The gate used to stamp a passing lesson (or knowledge promotion)
+  `staged`, and the triage drain accepted it on the next run with no one
+  looking. It is now minted `deferred` for a person: gate decision
+  `deferred`/`quality-gate` with the reason `distill-review`, carrying the
+  judge's per-criterion `scores` and `judgeReason`, so neither the drain nor its
+  judgment tier accepts it, and the improve ledger records `review_needed`. The
+  `distill_invoked` outcome is still `queued`. On 2026-10-05 the gate had
+  staged 12 lessons and 10 were bad (they restated the memory, claimed what it
+  does not say, or filed a dated status as a lesson); no judge score separated
+  them from the two good ones. A failed judgment behaves as before, and with
+  `processes.distill.qualityGate` off nothing is judged, so the proposal is
+  minted unstamped for the drain to decide.
+- **Distill skips a memory whose only recent feedback is positive and says
+  nothing.** A bare `akm feedback --positive` records that a note helped, which
+  gives the writer nothing to distil, so it restated the memory: 10 of the 11
+  lessons made from a memory with only that kind of feedback were rejected (the
+  11th was good). When every feedback event in the last 30 days that counts as a
+  signal is positive with no reason and no note, the improve loop skips distill
+  for the memory: a `distill-skipped` action with the reason "only positive
+  feedback, without a reason" and an `improve_skipped` event
+  (`distill_positive_without_reason`). The attempt goes in the improve ledger as
+  `unchanged`, so the memory waits for newer feedback. A reason, a note or a
+  negative signal anywhere in the window lets it through, and an explicit
+  `akm improve <ref>` still distills it. Record `--reason` with a positive
+  signal to say what helped.
+- **Distill no longer regenerates a lesson that already exists.** A lesson's ref
+  comes from its memory's name (`memories/deploy` gives
+  `lessons/memory-deploy-lesson`), so a second distill of the same memory
+  proposed the same ref, and accepting it replaced the lesson. All 5 such
+  overwrites recorded by the 2026-10-05 review were rejected. When the stash
+  the proposal is filed in already holds a file at the lesson ref, distill now
+  returns `skipped` with the reason `lesson_exists` (in the result and the
+  `distill_invoked` event) before any model call, mints no proposal and leaves
+  the memory untouched, and the improve loop records it in the ledger as
+  `unchanged`. A lesson of that name in another bundle does not count, since
+  the proposal would not replace it. To change a lesson, edit it.
+
+### Removed
+
+- **`akm feedback --failure-mode` and the `feedback.allowedFailureModes` config
+  key.** The flag labelled negative feedback `incorrect`, `outdated`,
+  `dangerous`, `incomplete` or `redundant`. None of the 195 negative feedback
+  events of the last 30 days set it, and nothing read it back. It now fails as an
+  unknown flag, and `akm feedback`'s output and the `improve_review_needed`
+  event no longer carry `failureMode`. A config that still sets
+  `feedback.allowedFailureModes` loads, names the key once as unknown, and
+  `akm migrate apply` drops it. Events recorded earlier keep their `failureMode`.
+
+### Fixed
+
+- **`akm feedback --replace` no longer queues a fix that accepting would turn
+  into a duplicate file.** A proposal writes the path computed from the ref's
+  type and name under the bundle's root, which is not where an asset indexed
+  outside that layout lives (a git bundle's `tasks/README.md` is
+  `knowledge/tasks/README`; a skill's `references/symptom-map.md` is
+  `knowledge/skills/<name>/references/symptom-map`). Accepting such a proposal
+  created a second file and left the real one unfixed. akm now refuses before
+  recording anything, naming the file and the path the proposal would write, and
+  says to edit the file directly. Plain negative feedback on these assets is
+  unaffected.
+- **A proposal no longer rewraps, reorders or strips a note's frontmatter to
+  add or correct its `type`.** When a proposal's content had no `type:` or a
+  different one, akm re-serialized the whole frontmatter block, so the reviewer
+  of a one-line correction also saw long values rewrapped, keys reordered and
+  YAML comments dropped. In practice 40 of 70 one-line correction proposals did
+  this. akm now adds a missing `type:` (and `updated:`) as a line before the
+  closing `---`, or replaces the existing `type:` line where it stands, and
+  leaves every other byte as written, line endings and body included. It
+  re-serializes only when it cannot do that safely, such as a `type` value that
+  spans several lines. The same write path serves `akm remember`, `akm import`
+  and `akm workflow create`, so a note akm writes without a `type` now carries
+  it, and `updated`, as its last frontmatter lines instead of its first.
+  Accepting a proposal also stamps its provenance (`generated`, `verified`,
+  `provenance`) as lines of its own, the last of the frontmatter, instead of
+  writing the whole frontmatter out again; a staging run found the old stamp
+  rewrapping 3 of 16 accepted edits. Accept still turns CRLF into LF, and still
+  writes the frontmatter out again when it carries bookkeeping keys such as
+  `inferenceProcessed` from the live note into a proposal that lacks them.
+- **`akm lint --fix` keeps a CRLF note's line endings** when it adds a missing
+  `updated:`. It used to rewrite the whole file to LF, so one added line showed
+  as every line changed.
+
 ## [0.9.26-alpha.2] - 2026-10-05
 
 ### Added

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

@@ -95,23 +95,29 @@ akm workflow create ship-release               # Create a workflow asset in the
 akm lint --type workflows                      # Parse and compile every .md/.yml workflow source; list every error
 akm workflow run workflows/ship-release        # Start or resume and execute the workflow
 akm feedback skills/code-review --positive     # Record that an asset helped (ranks it higher; no rewrite)
-akm feedback agents/reviewer --negative --reason "wrong framework" # Flag it: lowers its ranking; improve may repair its frontmatter
+akm feedback agents/reviewer --negative --reason "says to run jest; the suite runs on vitest" # Content wrong or stale: lowers its ranking; improve may repair its frontmatter
 akm feedback knowledge/opencode-server --negative --reason "the default port is 4096, not 8000" --replace "port 8000" --with "port 4096" --source "https://opencode.ai/docs/server/" # Queue an exact fix
 akm feedback memories/deployment-notes --positive # Works for memories too
 akm feedback env/prod --positive               # Records env feedback without surfacing values
 ```
 
-Use `akm feedback` whenever an asset's content materially helps, or proves wrong,
-stale or unhelpful, so future search ranking can learn from actual usage.
+Use `akm feedback --positive` when an asset's content materially helps, so
+future search ranking can learn from actual usage. Record negative feedback only
+when the asset's content is wrong or stale, and say what is wrong and what it
+should say.
 `akm feedback <ref> --negative --reason "<what is wrong and what should change>"`
 flags the asset: it ranks lower right away, and the next improve run may repair
-its description, title or `when_to_use` from your reason. Improve does not
-rewrite an asset's text: to correct a wrong fact there, attach the exact fix
-with `--replace "<exact current text>" --with "<corrected text>" --source "<URL,
-command or file>"`, which akm checks and queues as a proposal. `--positive` records that an asset helped (it raises its
-ranking) and does not trigger a rewrite; improve no longer rewrites assets from
-positive signals or on a proactive cadence. An akm command that fails says
-nothing about the asset; don't record it as feedback.
+its description, title or `when_to_use` from your reason. A note that simply did
+not fit your task is not negative feedback: record nothing for it. Improve does
+not rewrite an asset's text: once you have verified the correct fact, attach the
+exact fix with `--replace "<exact current text>" --with "<corrected text>"
+--source "<URL, command or file>"`, which akm checks and queues as a proposal.
+A note that is outdated can be marked with `--outdated`, or
+`--superseded-by <ref>` when another note replaces it.
+`--positive` records that an asset helped (it raises its ranking) and does not
+trigger a rewrite; improve no longer rewrites assets from positive signals or on
+a proactive cadence. An akm command that fails says nothing about the asset;
+don't record it as feedback.
 
 ## LLM Wiki bundles
 

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

@@ -8,7 +8,7 @@ For any task, follow this loop:
 1. `akm curate "<task>"` — find the best matching asset
 2. `akm show <ref>` — read the schema (field names and structure)
 3. Edit the workspace file using schema field names + task-specific values from your README
-4. `akm feedback <ref> --positive` — record that the asset helped (it raises its ranking and does not trigger a rewrite); when its content was wrong, stale or unhelpful, `akm feedback <ref> --negative --reason "<what is wrong and what should change>"` flags it: the next improve run may repair its description, title or `when_to_use` from your reason, but not its text. To correct a wrong fact in the text, add the exact fix: `--replace "<exact current text>" --with "<corrected text>" --source "<URL, command or file>"`. A failed akm command (e.g. `akm show` erroring) is not feedback on the asset — don't record it.
+4. `akm feedback <ref> --positive` — record that the asset helped (it raises its ranking and does not trigger a rewrite). Record negative feedback only when the asset's content is wrong or stale, and say what is wrong and what it should say. `akm feedback <ref> --negative --reason "<what is wrong and what should change>"` flags it: the next improve run may repair its description, title or `when_to_use` from your reason, but not its text. A note that simply did not fit your task is not negative feedback: record nothing for it. Once you have verified the correct fact, add the exact fix: `--replace "<exact current text>" --with "<corrected text>" --source "<URL, command or file>"`. A note that is outdated can be marked with `--outdated`, or `--superseded-by <ref>` when another note replaces it. A failed akm command (e.g. `akm show` erroring) is not feedback on the asset — don't record it.
 
 For workflow tasks:
 1. `akm show workflows/<name>` — inspect the procedure before executing it
@@ -40,7 +40,7 @@ akm proposal diff skills/akm-dream            # Diff proposal by ref, UUID, or 8
 akm proposal accept 7c115132                  # Accept by UUID prefix
 akm proposal reject skills/my-skill --reason "..."  # Reject by ref
 akm feedback <ref> --positive                 # Record that an asset helped (ranks it higher; no rewrite)
-akm feedback <ref> --negative --reason "..."  # Flag it: lowers its ranking; improve may repair its frontmatter
+akm feedback <ref> --negative --reason "..."  # Content wrong or stale: lowers its ranking; improve may repair its frontmatter
 akm feedback <ref> --negative --reason "..." --replace "<exact text>" --with "<fix>" --source "<url|cmd|file>"  # Queue an exact fix of its text
 akm bundle add <ref>                                 # Add a source (npm, GitHub, git, local dir)
 akm clone <ref>                               # Copy an asset to the working bundle (optional --dest arg to clone to specific location)
@@ -65,9 +65,9 @@ akm search "<query>" --from registry          # Search all registries (registry
 | secret | A single sensitive value for AUTHENTICATION (token, key, cert); name only. Inject with `akm secret run <ref> <VAR> -- <cmd>`. |
 | lesson | A distilled feedback lesson: `content` plus `action` (rendered from the `when_to_use` frontmatter). Read both before applying a related skill. Generated by the improve pipeline and promoted through the proposal queue. |
 
-When an asset's content meaningfully helps, or proves wrong, stale or unhelpful,
-record that with `akm feedback` so future search ranking can learn from real
-usage. Only negative feedback with a specific reason gets the asset reviewed and
+When an asset's content meaningfully helps, or proves wrong or stale, record
+that with `akm feedback` so future search ranking can learn from real usage.
+Only negative feedback with a specific reason gets the asset reviewed and
 fixed: improve no longer rewrites assets from positive signals or on a
 proactive cadence. An akm command that fails says nothing about the asset;
 don't record it as feedback.

package/dist/assets/prompts/consolidate-system.md

@@ -7,10 +7,10 @@ Rules:
 Return ONLY JSON (no prose, no code fences):
 {
   "operations": [
-    { "op": "promote", "ref": "memories/<name>", "knowledgeRef": "knowledge/<suggested-slug>", "reason": "<brief reason>", "description": "<one sentence describing the new knowledge asset>", "confidence": 0.92 }
+    { "op": "promote", "ref": "memories/<name>", "knowledgeRef": "knowledge/<suggested-slug>", "reason": "<brief reason>", "description": "<one sentence describing the new knowledge asset, or an empty string to keep the memory's own>", "confidence": 0.92 }
   ]
 }
 
-For every operation, emit a `confidence` field in [0, 1] expressing your certainty that the operation is correct and safe. Use 0.95+ only when evidence is unambiguous. Omit the field rather than guessing if you are uncertain.
+For every operation, emit a `confidence` field in [0, 1] expressing your certainty that the operation is correct and safe. Use 0.95+ only when evidence is unambiguous. Use `null` rather than guessing if you are uncertain.
 
 When the merged content includes an `updated` frontmatter field, the value MUST be a real ISO date string (e.g. `updated: 2026-05-20`). NEVER emit `updated: today`, `updated: {today}`, `updated: {today: null}`, `updated: now`, or any other literal placeholder/template-variable. If you do not have a real source-of-truth date, OMIT the `updated` field entirely — the post-processor will not invent one for you.

package/dist/assets/prompts/extract-session.md

@@ -48,13 +48,13 @@ Respond with EXACTLY one JSON object matching this shape:
       "type": "memory" | "lesson" | "knowledge",
       "name": "<kebab-case name, e.g. jwt-token; optionally under one kebab-case scope, e.g. auth/jwt-token>",
       "description": "<one sentence 20-400 chars>",
-      "when_to_use": "<one sentence 15-400 chars; REQUIRED only when type=lesson>",
+      "when_to_use": "<one sentence 15-400 chars for a lesson; an empty string for a memory or knowledge candidate>",
       "body": "<markdown body, 200-3000 chars typical>",
       "confidence": <number 0.0-1.0>,
       "evidence": "<one-line pointer to the moment in the session>"
     }
   ],
-  "rationale_if_empty": "<one sentence; REQUIRED when candidates is empty>"
+  "rationale_if_empty": "<one sentence when candidates is empty; an empty string otherwise>"
 }
 ```
 

package/dist/assets/stash-skeleton/README.md

@@ -80,11 +80,12 @@ akm search "<query>" --type skill
 # Mark an asset as helpful (raises its ranking; does not trigger a rewrite)
 akm feedback <ref> --positive
 
-# Flag an asset: it ranks lower, and the next improve run may repair its
-# description, title or when_to_use from your reason
+# Flag an asset whose content is wrong or stale: it ranks lower, and the next
+# improve run may repair its description, title or when_to_use from your reason.
+# A note that simply did not fit your task gets no negative feedback.
 akm feedback <ref> --negative --reason "<what is wrong and what should change>"
 
-# Correct a wrong fact in an asset's text: the exact fix is checked and queued for review
+# Once you have verified the correct fact, attach the exact fix: it is checked and queued for review
 akm feedback <ref> --negative --reason "<what is wrong>" --replace "<exact current text>" --with "<corrected text>" --source "<URL, command or file>"
 
 # Capture a durable lesson or memory from the current session