akm-cli 0.9.25-alpha.2 → 0.9.25-alpha.4

package/CHANGELOG.md

@@ -6,6 +6,108 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.25-alpha.4] - 2026-10-04
+
+### Changed
+
+- **The reflect quality judge's rubric is written for the frontmatter-only
+  revisions reflect makes, and says what drove each one.** A revision answering
+  negative feedback (any `[negative]` line) is judged only on the fields it
+  changes, since it cannot change the body and need not resolve feedback about
+  it. A field change is justified when the field is missing or broken, claims
+  more than the body covers, or, for a note the feedback calls stale, needs to
+  name the version or date the body records. A maintenance revision needs a
+  missing or broken field, and rewording a sound one is churn. New values are
+  checked as claims against the body. On 113 frontmatter-only proposals
+  reviewed by Claude Opus, the production model passed 78 of the 95 good ones
+  and 3 of the 18 bad ones, against 53 and 7 under the previous rubric, which
+  was tuned on body rewrites. The agent judge's tool paragraph drops its
+  feedback-points check, which contradicted that rule.
+
+## [0.9.25-alpha.3] - 2026-10-04
+
+### Added
+
+- **akm learns from Codex sessions.** `akm proposal extract --type codex` reads
+  the rollout files Codex writes under `$CODEX_HOME/sessions` (`~/.codex/sessions`
+  by default), as it reads Claude Code's and opencode's session files. `--auto`
+  and `akm improve`'s session extraction include Codex on a machine that has
+  them, and a session is extracted once, as for the other harnesses. The model
+  sees what the person and Codex said and the tool calls and results between
+  them, without Codex's own instructions or injected context (AGENTS.md, the
+  environment, an invoked skill). The reader lists a person's sessions,
+  `codex exec` runs included. It leaves out the rollouts Codex writes for
+  subagents and its other internal agents, which are not sessions of their own, and
+  unlike a Claude Code subagent transcript it does not fold them into their
+  parent.
+
+### Changed
+
+- **Reflect changes only an asset's `description`, `when_to_use` and title;
+  akm keeps the body byte for byte.** On 396 labelled reflect edits, those that
+  fixed a frontmatter defect and left the body alone were good 24 times in 26;
+  those that also rewrote the body were bad 175 times in 224. The reply is now
+  `confidence` and a `frontmatterPatch` of `description`, `when_to_use` and
+  `title` (each a non-empty single-line string, or `null` for no change), plus
+  `ref` when no target was given, and no body: the JSON Schema, both output
+  contracts and the repair prompt say so, and the framed reply for an endpoint
+  that rejects JSON Schema has no content markers. akm applies the patch to the
+  asset it read by rewriting only the changed keys' frontmatter lines, so every
+  other line, including a list beside a description the YAML parser cannot read,
+  stays as it was; a source whose closing `---` is fused onto a value gets no
+  proposal. A non-null `title` becomes a
+  `# <title>` heading and one blank line at the top of the body, only when the
+  body has no level-1 heading; otherwise it is ignored. A patch that changes
+  nothing, whether every field is `null` or equal to the source's, creates no
+  proposal (`no_change`); an asset that requires a `description` and has none
+  still gets one derived from its own text, as before (#636).
+- **Reflect may answer "nothing to change."** Its prompt forbade it: "your
+  proposal must correct or add something the source lacks", "must meaningfully
+  differ" from a rejected proposal, "do not return the same content
+  unchanged", and "you MUST generate" a `when_to_use`. On the same edits, those
+  that fixed no defect were bad 86 times in 93, and those driven by negative
+  feedback 50 times in 53; most of that feedback says the asset did not help
+  with an unrelated task. One goal sentence now covers every asset type: check
+  the three fields against the body and the feedback, and return `null` for
+  each that needs no fix. The feedback caveat says that feedback about a task
+  the asset never claims to cover needs no change, and with no feedback the
+  prompt says to fix only a missing or broken field. A rejected proposal is not
+  to be proposed again, and the engine returns `null` when no other change is
+  justified.
+- **Reflect's prompt names the frontmatter problems akm can see** (a
+  description split by a stray period or carrying an escaped quote, no
+  `when_to_use`, no title) and asks for a repair that keeps the description's
+  wording, names, numbers and paths rather than a rewrite. Without the list the
+  model fixed 51 of 122 broken descriptions and 93 of 193 missing titles; with
+  it, 120 and 189. When the feedback calls a note stale or historical, a new
+  `when_to_use` names the version or date the body records, or stays as it is.
+  On an 80-case sample of the labelled set, Claude Opus reviewers judged 64 of
+  the new reflect's 78 proposals good; the old reflect's edits in the set are
+  good 81 times in 396.
+- **`akm proposal accept` warns about an echoed "Avoid These Patterns"
+  section instead of refusing.** Reflect keeps a body as it is, so a proposal
+  for an asset that already carries the section (a leftover of the run-only
+  prompt text) would never be accepted, and the person accepting cannot edit
+  the proposal.
+
+### Removed
+
+- **Everything reflect needed to rewrite a body.** The prompt's "Content
+  preservation rules" and the size bounds computed for them; the related
+  distilled lessons section and the companion-doc
+  (`knowledge/skills/<skill>/references/<topic>`) option, with the gathering
+  behind them and the `derived_from_reflect` marker it read; the size guard and
+  the truncation-marker check on reflect's output, and their review reasons
+  `reflect-size-ratio` and `reflect-truncation-leak`; the stripping of an
+  appended frontmatter block and of an echoed "Avoid These Patterns" section
+  from a body; and the restore of identity fields, which a patch cannot name.
+  The accept-time size advisory and truncation-marker block stay.
+- **The `body-edit` review reason.** A reflect revision no longer changes the
+  body, so one the judge passed is stamped `staged` and the triage drain
+  accepts it, as before 0.9.24; with `processes.reflect.qualityGate` off it is
+  minted unstamped for the drain to decide. A proposal already deferred as
+  `body-edit` stays deferred.
+
 ## [0.9.25-alpha.2] - 2026-10-03
 
 ### Added

package/dist/assets/prompts/reflect-feedback-framing.md

@@ -1 +1 @@
-Feedback describes what a reader found missing or wrong. It is a signal to investigate, not a fact to insert. Do not add claims, numbers, dates, paths, ports, or incidents that are not already present in the asset content. If feedback asks for information the asset lacks, leave the section unchanged.
+Feedback describes what a reader found missing or wrong, often that the asset did not help with a task it was retrieved for. It is a signal, not a fact to insert. Change a field only when it is missing or broken, or when it claims more than the body covers, and then only to describe what the body covers. Feedback about a task the asset never claims to cover, or asking for information the asset lacks, needs no change. When the feedback says the asset is stale, outdated, superseded or historical, a `when_to_use` names the version or date the body records ("When working with the 0.1.0 client"), or stays as it is.

package/dist/assets/prompts/reflect-llm-framed-contract.md

@@ -1,13 +1,6 @@
 Respond with exactly this plain-text frame, with no prose or code fence around it:
 
 {{REF_LINE}}AKM_REFLECT_CONFIDENCE: <number from 0 to 1>
-AKM_REFLECT_FRONTMATTER_PATCH: {"description": null, "when_to_use": null}
-AKM_REFLECT_CONTENT_BEGIN
-<complete improved markdown body>
-AKM_REFLECT_CONTENT_END
+AKM_REFLECT_FRONTMATTER_PATCH: {"description": null, "when_to_use": null, "title": null}
 
-The first begin marker and final end marker delimit the body; marker lines between them are literal content. Put the complete markdown body between those outer markers. Quotes, Markdown fences, and backslashes inside the body are literal content; do not JSON-escape them. Emit the body only, without YAML frontmatter, because AKM preserves and merges the source frontmatter itself.
-
-The frontmatter patch must be a one-line JSON object with exactly `description` and `when_to_use`. Keep a field `null` when it should not change. Supply a non-empty string only when adding or correcting that field; AKM merges those values through its existing sanitizer.
-
-Never include the truncation marker (the literal text `{{TRUNCATION_MARKER}}`) or any other text from outside the fenced asset content shown to you, anywhere in the body.
+The frontmatter patch must be a one-line JSON object with exactly `description`, `when_to_use` and `title`. Keep a field `null` when it should not change; otherwise give a non-empty single-line string. `title` is the text of a level-1 heading, without the leading `#`; AKM adds it only when the body has none. AKM applies the patch to the source asset and keeps the body itself.

package/dist/assets/prompts/reflect-llm-schema-contract.md

@@ -1,5 +1,3 @@
 Respond only through the provider's native JSON schema. {{FIELD_RULE}}
 
-`content` must contain the complete improved markdown body only, without YAML frontmatter. `frontmatterPatch` must contain exactly `description` and `when_to_use`; set either field to `null` when it should not change, or to a non-empty string when adding or correcting it. AKM merges that narrow patch with the source frontmatter and preserves target identity itself. `confidence` is your honest self-rated quality confidence from 0 to 1. Do not add prose or Markdown fences around the JSON response.
-
-Never include the truncation marker (the literal text `{{TRUNCATION_MARKER}}`) or any other text from outside the quoted asset content shown to you, anywhere in `content`.
+`frontmatterPatch` must contain exactly `description`, `when_to_use` and `title`; set a field to `null` when it should not change, or to a non-empty single-line string. `title` is the text of a level-1 heading, without the leading `#`; AKM adds it only when the body has none. AKM applies the patch to the source asset, keeps the body itself, and preserves target identity. `confidence` is your honest self-rated quality confidence from 0 to 1. Do not add prose or Markdown fences around the JSON response.

package/dist/assets/prompts/reflect-output-repair.md

@@ -1,3 +1,3 @@
-Your previous response could not be extracted using the required output contract. Reformat that response exactly once using the contract below. Preserve its proposed markdown verbatim: do not revise, summarize, or add content. Return only the repaired envelope.
+Your previous response could not be extracted using the required output contract. Reformat that response exactly once using the contract below. Keep its proposed values as they are: do not revise or add to them. Return only the repaired envelope.
 
 {{OUTPUT_CONTRACT}}

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

@@ -10,6 +10,7 @@
  *   akm proposal extract --type claude --session-id <id>
  *   akm proposal extract --type claude --since 24h
  *   akm proposal extract --type opencode --since 7d --dry-run
+ *   akm proposal extract --type codex --since 24h
  *   akm proposal extract --auto                 # iterate all available harnesses
  *   akm proposal extract --type claude --location /custom/path --session-id <id>
  *
@@ -25,12 +26,12 @@ import { akmExtract, resolveStandaloneExtractPlan } from "./extract.js";
 export const extractCommand = defineJsonCommand({
     meta: {
         name: "extract",
-        description: "Extract durable insights from native session files (claude, opencode) and queue them as proposals.",
+        description: "Extract durable insights from native session files (claude, codex, opencode) and queue them as proposals.",
     },
     args: {
         type: {
             type: "string",
-            description: "Harness name (claude, opencode). Required unless --auto.",
+            description: "Harness name (claude, codex, opencode). Required unless --auto.",
         },
         "session-id": {
             type: "string",

package/dist/commands/improve/extract.js

@@ -2,7 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * `akm extract` — read native session logs (claude, opencode) through the
+ * `akm extract` — read native session logs (claude, codex, opencode) through the
  * session-log harnesses, pre-filter the noise, and ask the model for
  * memory/lesson/knowledge candidates the agent did not already save. Each
  * candidate is queued as a proposal (`source: "extract"`), never written.