akm-cli 0.9.31 → 0.10.261002-beta

package/docs/architecture/adapters.md

@@ -101,23 +101,21 @@ interface BundleAdapter {
   // reading authored bytes or walking the bundle.
   readCandidates?(c: BundleComponent, conceptId: string): Array<{ path: string; conceptId: string }>;
 
-  // OPTIONAL — placement / discovery.
-  placeNew?(c: BundleComponent, conceptId: string): string;   // where a new item would live
+  // OPTIONAL — discovery.
   directoryList?(c: BundleComponent): string[];               // owned dirs; feeds git exact-path staging
   looksLikeRoot?(root: string): boolean;                      // install-time probe
 }
 ```
 
 `recognize` and `validate` are required on every adapter; `index`,
-`affectedItems`, `readCandidates`, `placeNew`, `directoryList`, and
+`affectedItems`, `readCandidates`, `directoryList`, and
 `looksLikeRoot` are optional capability methods. An adapter overriding `index()` must keep
 `recognize()` coherent with it (conformance: `index()` == fold of
 `recognize()` over the core walk) or declare component-level
 incrementality.
 
-`readCandidates` is intentionally distinct from both `extensions` and
-`placeNew`: extensions are non-exhaustive walk hints, while placement is a
-write-normalization policy. Read candidates preserve canonical directory
+`readCandidates` is intentionally distinct from `extensions`: extensions are
+non-exhaustive walk hints. Read candidates preserve canonical directory
 manifests (for example `skills/<name>/SKILL.md`) so lookup, index-backed show, and workflow runtime share one
 physical-owner decision. Each candidate carries its canonical concept identity,
 so a byte-denying ownership probe never has to infer identity from the query.
@@ -145,30 +143,21 @@ concern.
 
 ---
 
-## `placeNew()` wiring status
+## Placement
 
-The interface declares `placeNew()` as an optional capability method, and 9
-of the 11 built-in adapters already implement it — all but `okf` and
-`website-snapshot` (`claude` and `opencode` inherit theirs from the shared
-tool-dir factory). **Nothing in the write path calls it yet**: AKM-native
-writes still resolve through AKM's own flat type→directory placement table
-(`src/core/asset/asset-placement.ts`'s `PLACEMENT_SPECS`), not through the
-owning adapter's `placeNew()`.
-
-Placement for every existing bundle is already correct today — this is a
-deliberately sequenced routing change, not unfinished behavior. It's
-scoped out of 0.9.0 by
-[D12](../architecture/specs/0.9.0-decisions.md#d12--bundleadapterplacenew-stays-unwired-until-010)
-and deferred to 0.10; nothing user-visible changes in 0.10 for this alone.
-See [STABILITY.md](../../STABILITY.md) ("On the horizon") for the
-up-to-date status if this changes.
+Adapters do not place new items. AKM-native writes resolve through AKM's own
+flat type→directory placement table (`src/core/asset/asset-placement.ts`'s
+`PLACEMENT_SPECS`), which is correct for akm-layout bundles — the only bundles
+the write commands touch in practice. A per-adapter `placeNew()` existed
+through 0.9 but nothing called it, and it was removed in 0.10. Supporting
+writable bundles in another layout would need it back: see
+[#1163](https://github.com/itlackey/akm/issues/1163).
 
 ---
 
 ## Write allowlists
 
-`placeNew()` wiring is a separate question from **which bundles AKM-native
-write commands are allowed to touch at all** — that's decided today by a
+Which bundles AKM-native write commands are allowed to touch at all is decided by a
 small allowlist check, `assertAkmAssetWrite` (`src/core/write-source.ts`),
 run before any write command touches the filesystem. It compares the target
 bundle's detected (or configured) adapter id against an allowlist and throws
@@ -181,12 +170,10 @@ The default allowlist is `["akm"]`. Two command families widen it explicitly:
 | `akm env create` / `env remove` / `secret set` | `dotenv` |
 | `akm workflow create` | `akm-workflow` |
 
-Every other adapter — including every adapter that already implements
-`placeNew()` (`agent-skills`, `claude`, `opencode`, `akm-task`,
-`generic-files`) — is rejected by every AKM-native write command in 0.9.0.
+Every other adapter (`agent-skills`, `claude`, `opencode`, `akm-task`,
+`generic-files`, and so on) is rejected by every AKM-native write command.
 `akm task add` in particular uses the *default* allowlist (`akm` only), so a
-standalone `akm-task` bundle is read-only through AKM-native write commands
-even though `akm-task`'s own `placeNew()` is implemented.
+standalone `akm-task` bundle is read-only through AKM-native write commands.
 
 Reading, searching, and `akm lint` are unaffected by this allowlist — only
 creating, editing, or deleting through AKM's own commands is restricted.
@@ -197,8 +184,7 @@ This allowlist boundary is also where AKM's [execution
 boundary](../guides/concepts.md) principle shows up on the write side: AKM
 retrieves and validates every supported format, but it only lets its own
 write commands mutate a narrow, explicitly-declared set of targets — it
-does not widen write access to a format just because that format's adapter
-happens to expose a `placeNew()` implementation.
+does not widen write access to a format just because it can read it.
 
 ---
 

package/docs/architecture/architecture.md

@@ -260,8 +260,7 @@ schema (`src/core/config/schema/sources-bundles.ts`).
 refresh.
 
 Write-target resolution (`resolveWriteTarget`) follows: an explicit
-destination flag (`--bundle` on `remember`/`clone`/`improve`, `--target` on
-`import`/env/secret mutations) -> `config.defaultWriteTarget` -> working
+destination flag (`--bundle`) -> `config.defaultWriteTarget` -> working
 bundle (`defaultBundle`) -> `ConfigError`. The resolved target keeps the
 optional configured selector separate from the stable `source.name`: APIs
 that must re-resolve a destination use the selector, while durable refs and
@@ -299,8 +298,8 @@ whose proposal queue is read or adjudicated; it does not override the proposal's
 write destination. Qualified proposals and unqualified proposals created in a
 configured secondary queue record the destination source name and materialized
 root. Diff, accept, and revert use that binding by default and reject an explicit
-`--target` that resolves elsewhere. An unbound short proposal requires either
-an explicit `--target` or an authenticated `--queue` context; it does not
+`--bundle` that resolves elsewhere. An unbound short proposal requires either
+an explicit `--bundle` or an authenticated `--queue` context; it does not
 inherit a default write target.
 
 ---
@@ -442,7 +441,7 @@ An explicit missing or incompatible engine is an error and never falls
 through to another configured engine.
 
 Task-v3 execution and durable workflow-v4 dispatch use this runtime boundary.
-Markdown and GitHub-shaped YAML compile through source IR v1; new starts freeze
+Markdown workflows compile through source IR v1; new starts freeze
 v4-family `irVersion: 5`. A stored plan that decodes runs whatever release
 froze it; one that does not is marked abandoned and `akm workflow run <ref>`
 starts afresh. Only a plan a newer akm froze is refused, naming the upgrade.

package/docs/architecture/improvement.md

@@ -32,15 +32,16 @@ everything else routes through `akm proposal accept`.
 
 ## Components
 
-- **Utility policy** (`src/indexer/feedback/utility-policy.ts`) — pure
-  domain math that turns accumulated feedback counts into a new utility
-  score. No database access; unit-testable in isolation.
+- **Utility recompute** (`recomputeUtilityScores`, `src/indexer/indexer.ts`) —
+  the one place utility is computed from `usage_events`; `akm index` runs it
+  for every entry and `akm feedback` for the entry it touched.
 - **Strategies** (`src/commands/improve/improve-strategies.ts`,
   `src/assets/improve-strategies/*.json`) — named presets that decide which
   improve processes run and with what engine/model/limits.
 - **Autonomy gate** (`src/commands/improve/autonomy-gate.ts`) — downgrades
-  the handful of processes that would otherwise mutate assets without review,
-  unless `experimental.improveAutonomy` is explicitly set.
+  the handful of processes that would otherwise mutate assets without review
+  (memory inference, memory cleanup, and a judged triage promote), unless
+  `experimental.improveAutonomy` is explicitly set.
 - **Reflect / distill / consolidate subprocesses** — the improve pipeline's
   proposal generators, invoked per asset (reflect, distill) or across the
   whole memory corpus (consolidate). See
@@ -49,7 +50,7 @@ everything else routes through `akm proposal accept`.
 - **Proposal queue** (`state.db`) — written by `createProposal` (reflect,
   distill, consolidate's promote operations, and the other proposal producers)
   and by `createRetireProposal` (the pair pass's retire proposals).
-- **Auto-sync** — the end-of-run commit/push step for git-backed bundles.
+- **Auto-sync** — the pre-run sync and the end-of-run commit/push step for git-backed bundles.
 - **Session extraction** (`akm proposal extract`) — a separate entry point
   that mines coding-agent session transcripts for durable insights and queues
   them the same way.
@@ -62,13 +63,16 @@ everything else routes through `akm proposal accept`.
    `--negative --reason "<what is wrong and what should change>"` flags the
    asset: the next improve run may repair its frontmatter from the reason.
    `--replace`/`--with`/`--source` attach an exact fix of its text once the
-   agent has verified the correct fact, which akm checks at once and queues as
-   a `feedback` proposal.
+   agent has verified the correct fact, which akm checks and applies at once
+   through a `feedback` proposal it accepts on the spot (no review).
    `--positive` records that the asset helped (it raises its ranking) and does
    not trigger a rewrite.
-2. The feedback event is appended to `state.db`, and the asset's utility
-   score is updated immediately via the bounded-step formula (below) — no
-   reindex required.
+2. The feedback event is appended to `state.db`. `akm search` and `akm curate`
+   count a user's recorded positives and negatives per asset and scale the
+   fused score by them (logarithmic in each count, the same for every asset),
+   so ranking moves at once with no reindex. The asset's utility score, which
+   improve and metrics read, is recomputed immediately by the same formula
+   `akm index` uses (below).
 3. `akm improve` selects assets from the one bundle it writes to. A rewrite
    (reflect) is planned only for an asset with negative feedback in the last
    30 days that is newer than the stage's last attempt, or for an explicit ref;
@@ -80,10 +84,11 @@ everything else routes through `akm proposal accept`.
    reason or note, which gives the writer nothing to distil (10 of the 11
    lessons made from such memories were rejected). Unless
    `--require-feedback-signal` is set, the
-   fallback lanes (high salience, and proactive maintenance where the strategy
-   enables it) pick what the retrieval scope below admits, for scoring only:
-   they plan nothing, so improve does not rewrite assets on a proactive
-   cadence. It ranks the selected assets by salience, applies the limit, then
+   proactive-maintenance lane (where the strategy enables it, as `default`
+   does) adds the stable assets due for a revisit that the retrieval scope below
+   admits, and plans them with the feedback-bearing ones. At most `maxPerRun`
+   (15) assets are picked per run, an asset is due only if not reflected or
+   distilled for `dueDays` (30), and reflect's `limit` (25) bounds the run. It ranks the selected assets by salience, applies the limit, then
    runs whichever processes the selected strategy enables against each one (see
    [Improve Workflow](internals/improve-workflow.md#ledger-pre-filter-signal-delta)).
 4. Reflect and distill each emit at most one proposal per asset per run;
@@ -119,36 +124,39 @@ everything else routes through `akm proposal accept`.
    retires, go in the same commit. A commit that fails warns and the accept
    stands.
 8. For a git-backed bundle, `akm improve`'s end-of-run auto-sync commits the
-   rest of the run's changes as a single batch and pushes (see below).
+   rest of the run's changes as a single batch and pushes (see below). The run
+   began with the same sync, so it started from what other hosts had pushed.
+
 
 ## Current decisions
 
 ### Utility scoring
 
-Utility moves by the MemRL bounded-step EMA formula (arXiv:2601.03192),
-implemented in `computeNextUtility` (`src/indexer/feedback/utility-policy.ts`):
+Utility has one formula and one implementation, `recomputeUtilityScores`
+(`src/indexer/indexer.ts`), counting only user-attributed (`source='user'`)
+events:
 
 ```text
-reward   = weighted average of positive (1.0) and negative (0.0) feedback in the batch
-nextUtil = clamp(currentUtil + FEEDBACK_LR * (reward - currentUtil), 0, 1)
+rate     = max(selectRate, max(0, positives - negatives) / (positives + negatives))
+nextUtil = prevUtil * 0.7^days + rate * (1 - 0.7^days)
 ```
 
-`FEEDBACK_LR` is `0.1`, so a single feedback batch moves utility by at most
-0.1 in either direction regardless of how lopsided the batch is — `reward` is
-a proportion of the counts, not their magnitude. When a previously
-high-utility asset (utility ≥ 0.5) crosses back below 0.5, the update is
-flagged as a review-threshold crossing so callers can escalate it. Decay is
-time-proportional rather than tied to index frequency, and usage history
-(and the utility it drives) is preserved across schema resets and full index
-rebuilds — see [Architecture: Utility Scoring](architecture.md#utility-scoring)
+`akm index` runs it for every entry. `akm feedback` runs the same function for
+the one entry it touched, so the value it stores is the one the next index
+would compute at that moment (a one-entry call skips the usage-event purge
+and leaves the recompute watermark alone). `days` is the time since the last
+full recompute, at least 1, so decay is time-proportional rather than tied to
+index frequency. When a previously high-utility asset (utility >= 0.5) falls
+below 0.5 after feedback, an `improve_review_needed` event is emitted. Usage
+history (and the utility it drives) is preserved across schema resets and full
+index rebuilds - see [Architecture: Utility Scoring](architecture.md#utility-scoring)
 for the storage-level summary.
 
 ### Strategy inheritance
 
 Improve presets live under `improve.strategies` (config) and the built-in
-set: `default`, `quick`, `thorough`, `consolidate`, `catchup`,
-`reflect-distill`, and `proactive-maintenance`
-(`src/assets/improve-strategies/*.json`). Selection
+set: `default` and `consolidate` (`src/assets/improve-strategies/*.json`). The removed `quick`, `thorough`,
+`catchup`, `reflect-distill` and `proactive-maintenance` still work as user-defined strategies. Selection
 order is `--strategy`, then `defaults.improveStrategy`, then `default`.
 
 Resolution is a two-step deep merge (`resolveImproveStrategy`): a named
@@ -157,16 +165,16 @@ any user-defined override for that same name (under `improve.strategies` in
 config) is merged on top. So a strategy — built-in or user-defined — that
 omits a field, or an entire process block, inherits it from `default`; an
 explicit `enabled: true`/`false` in the more specific layer always wins. This
-is why, for example, `proactiveMaintenance` stays off in `default` and
-`reflect-distill`, but a preset that doesn't mention it at all still inherits
-that "off" rather than defaulting to on.
+is why, for example, `proactiveMaintenance` is on in `default` and off in
+`consolidate`, and a preset that doesn't mention it at all inherits the
+`default` value. A user-defined strategy named `proactive-maintenance` (the name
+of the retired built-in) resolves the same way, merged onto `default`.
 
 ### Retrieval scope
 
 Improve reworks only what gets read (#986). Fresh feedback and an explicit ref
 scope (`akm improve skills/x`) are usage evidence of their own. Every other
-pick — the proactive-maintenance and high-salience lanes (which only score what
-they pick), and the memories consolidation judges — must be in the retrieval
+pick — the proactive-maintenance lane, and the memories consolidation judges — must be in the retrieval
 scope (`src/commands/improve/retrieval-scope.ts`):
 
 - **Retrieved:** a user-attributed `search`, `curate` or `show` returned the
@@ -207,7 +215,13 @@ Content passes only when **every** criterion scores 4 or more (a lesson's
 grounding is judged apart, see
 [distill](internals/improve-workflow.md#distill-akmdistill)); a mean of 3.5
 passed it before. A verdict that does not pass is a review when its mean is 2.5
-or more and a rejection below that. The rubric and the rule were chosen on 90
+or more and a rejection below that. Reflect narrows that band: a revision whose
+mean is 3.5 or more is queued for a person (reason `judge-uncertain`, with the
+`scores` and `judgeReason`) and records no rejection window, and a lower mean is
+refused. On 113 reviewed frontmatter-only proposals (lab 27B Q2, the shipped
+judge) the non-passing ones at 3.5 or more were 17 good and 9 bad, the rest 1
+good and 2 bad; on 396 labelled body rewrites a mean below 3.5 was good 6 times
+in 291 (the constant and its sources are in `src/commands/improve/reflect.ts`). The rubric and the rule were chosen on 90
 labelled real rewrites, where judging on the mean let rewrites that only
 reworded a correct asset through.
 
@@ -217,7 +231,10 @@ both stay on the proposal when the drain accepts it, so a later audit can read
 why it passed (`akm proposal show --format json`). A distill pass is not staged:
 the lesson or promotion is minted `deferred` for a person (reason
 `distill-review`, same gate) with the same `scores` and `judgeReason`, and the
-triage drain and its judgment tier leave it alone. On 2026-10-05 the gate had
+triage drain and its judgment tier leave it alone. A lesson that repeats an existing
+lesson may instead be proposed as an update of that lesson (reason
+`distill-update`, same gate), with only what the memory adds; the drain leaves
+it for a person too. 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), and no score separated them
 from the two good ones. Reflect revises only an asset's
@@ -225,34 +242,34 @@ from the two good ones. Reflect revises only an asset's
 those that fixed a frontmatter defect and left the body alone were good 24
 times in 26, and those that also rewrote the body were bad 175 times in 224.
 
-### Retrieval regression gate
-
-Reflect refuses a revision of an existing asset that grades lower on the
-asset's own retrieval queries (#722, `src/commands/improve/retrieval-gate.ts`).
-After the quality judge passes, up to five distinct user `search`/`curate`
-queries that returned the asset (envelopes, the stash README line and inputs
-over 2,000 characters dropped) are each graded 0–3 against the old and the new
-content with the retrieval eval's prompt, `retrieval-relevance-judge.md`, and
-its document shape: type, ref, name, description and the first 1,500 body
-characters. A lower mean for the new content is a `quality_rejected` refusal
-with the reflect rejection window. A grade that cannot be obtained refuses the
-rewrite, as the quality judge fails closed. An asset with no such queries is
-not graded.
-
-The gate exists because it was measured first. Of 60 accepted reflect rewrites
-(since 2026-07-01, stratified by lane) judged this way, 14 graded lower (23%,
-95% CI 14–35%) and 12 higher. Grading the same content twice flipped 11 of 174
-query grades, which puts 3 of 60 rewrites in the "lower" bucket by noise
-alone. The threshold for building it was fixed before judging: a lower bound of
-at least 10%.
+### Judgment tier: promotions only
+
+The triage drain's judgment tier (`processes.triage.judgment`, off in every
+built-in strategy) may accept only a consolidate promotion, a memory proposed as
+a new knowledge note. A retirement or a reflect revision it would
+accept is left for a person (`judgment-not-promotion`); it may still reject.
+Measured on the nightly eval with `experimental.improveAutonomy` (#1132, #1094),
+judging every kind solved 0.49 (gpt-5.6-terra) and 0.53 (qwen3.8-27b) of the
+items, harmed 14 and 11, and changed 18 and 21 notes outside the planted set.
+Judging promotions alone: precision 0.87, recall 0.78 and 4.8% of bad promotions
+accepted on qwen3.8-27b; precision 1.0, recall 0.17 on gpt-5.6-terra.
+
+### Proactive-lane proposals wait for a person
+
+A proposal planned by the proactive-maintenance lane (`eligibilitySource:
+"proactive"`, an asset with no feedback behind it) is never accepted by the
+drain, whether a deterministic gate (a staged quality-judge pass), the judgment
+tier or an accept staged by an earlier drain would take it. It is left for a
+person with reason `proactive-needs-review`, and the judgment tier does not see
+it. An empty diff is still rejected. Proposals driven by feedback (`signal-delta`,
+`scope`) follow the one rule unchanged (#1147).
 
 ### Retirement continuity
 
 Before the consolidate pair pass mints a `retire` proposal (rule R3,
 `src/commands/improve/consolidate/continuity-check.ts`), it replays up to five
 of the retired asset's own past `search`/`curate` queries
-(`loadRetrievalQueries`, the same cleaned set `../retrieval-gate.ts` replays
-for the retrieval regression gate — boilerplate, harness/tool envelopes,
+(`loadRetrievalQueries`, `../retrieval-queries.ts` — boilerplate, harness/tool envelopes,
 pastes and near-duplicates dropped before replay, S3a) through akm's own
 search, in-process — the ranking a user actually gets, no LLM. For every
 query where the retired asset ranked in the top 10, the successor must too
@@ -297,8 +314,7 @@ but nothing assigns or emits it any more.
 ### Dry-run planning boundary
 
 Dry and live improve runs call the same selectors for signal-delta eligibility,
-the fallback lanes (proactive maintenance and high salience, which score and
-plan nothing), the retrieval scope, salience ranking, disk presence, and the
+the proactive-maintenance lane, the retrieval scope, salience ranking, disk presence, and the
 final cap, and resolve the bundle they plan the same way: `--bundle`, else
 `defaultWriteTarget`, else the working bundle (`AKM_BUNDLE_DIR`, else
 `defaultBundle`). Each invocation reports a best-effort observation assembled
@@ -337,13 +353,20 @@ equals `effective`. When the run is unbounded, `totalCeiling` is omitted.
 candidates, validation, and proactive-maintenance selection are proposal-only
 and never write assets directly regardless of this gate.
 Three specific lanes *would* mutate assets without review and are downgraded
-unless `experimental.improveAutonomy` is explicitly set to `true`:
+unless `experimental.improveAutonomy` is explicitly set to `true` (the triage
+lane only when its judgment tier is on; see below):
 
 | Lane | What it does when enabled | With autonomy off |
 | --- | --- | --- |
 | `memoryInference` | Writes `.derived.md` children and rewrites parent frontmatter | disabled |
 | memory cleanup | Belief-state frontmatter rewrites, archive moves | analyzed but not applied |
-| `triage` `applyMode: "promote"` | Auto-accepts queued proposals into the bundle | downgraded to `queue` — triage still runs, it just does not auto-accept |
+| `triage` `applyMode: "promote"` **with judgment on** | The judgment tier auto-accepts consolidate promotions into the bundle | downgraded to `queue` — triage still runs, it just does not auto-accept |
+
+A deterministic-only `promote` (triage with judgment off) is not gated (#1143):
+the `default` strategy drains the queue through the deterministic gates, up to
+`maxAcceptsPerRun` (200) per run, with no opt-in. The nightly eval's baseline is
+exactly this path (`proposal drain --promote` without judgment): 0.91 (terra) and
+0.89 (qwen) of items solved, 0 to 1 harmed.
 
 Every downgrade is reported, not silent: it warns on stderr, appends an
 `improve_skipped` event with `reason: "autonomy_gated"`, and is counted in
@@ -358,18 +381,34 @@ explicit promote surface independent of this gate.
 
 ### Auto-sync
 
-For git-backed bundles (detected by a `.git` directory), `akm improve`
-automatically commits its changes as a single batch at the end of the run —
-the same operation as `akm sync` — and pushes if the bundle is writable, per
-the active strategy's `sync` setting. The `reflect-distill` and
-`proactive-maintenance` strategies skip sync entirely, so an interrupted run
-does not leave an uncommitted backlog. `--no-sync` disables sync for a single
-run; `--no-push` commits without pushing. Strategy sync behavior is
-configured via the `sync` block under `improve.strategies.<name>`.
-
-The sync always commits the paths it is given. A branch it cannot push (no
-upstream branch, or behind or diverged from its upstream) only skips the push,
-and the result says why: `sync.reason` reads `not pushed: ...`. A branch that is
+For git-backed bundles (detected by a `.git` directory), `akm improve` syncs
+twice: once **before** the run and once at the end. Both are the same operation
+as `akm sync` — fetch and merge the upstream, commit, and push if the bundle is
+writable, per the active strategy's `sync` setting. A user-defined strategy can
+turn sync off, so an interrupted run does not leave an uncommitted backlog.
+`--no-sync` disables both for a single run; `--no-push` commits without pushing.
+Strategy sync behavior is configured via the `sync` block under
+`improve.strategies.<name>`.
+
+The pre-run sync runs right after the run takes its lock and before the index
+and plan stages, so they see what another host pushed. It stages what `akm sync`
+stages (the managed paths, or the content subdirectory of a repo whose content
+lives in one), which means pending hand edits there are committed (and pushed)
+before the run starts, not mistaken for the run's own writes. It never aborts
+the run: a merge that conflicts (aborted, local commit kept), a failed fetch, or
+any other error is a warning, and the run continues on the local state. The
+outcome is `preRunSync` on the result (same shape as `sync`) and a `stash_synced`
+event with `phase: "pre-run"`. A dry run does not sync. Scheduled `core/improve`
+and `akm-improve-consolidate` runs go through the same `akm improve` entry, so
+they get it too.
+
+The sync always commits the paths it is given. It then fetches the remote and
+brings the upstream in (a fast-forward when it can, otherwise git's default
+merge) before it pushes, so a second host that pushed first does not stop the
+push. A branch it cannot push (no upstream branch, a failed fetch, or a merge
+that conflicts, which is aborted with the local commit kept) only skips the push,
+and the result says why: `sync.reason` reads `not pushed: ...`. A push the remote
+refuses after the commit landed still reports `sync.committed: true`. A branch that is
 ahead of its upstream, as it is after the accept commits above, is pushed with
 the sync commit. A clean tree that is ahead is not pushed: the sync pushes what
 it commits.

package/docs/architecture/internals/improve-workflow.md

@@ -13,7 +13,7 @@
 | `--limit` | `number` | Cap the number of assets processed, taken from the salience ranking, highest first (refs routed to distill only come last). |
 | `--timeout-ms` | `number` | Wall-clock budget for the entire run. Default: 7 200 000 ms (2 hours). |
 | `--skip-if-locked` | `boolean` | If another improve owns the whole-run lock, return an exit-0 no-op result before triage, indexing, events, or sync. Without the flag, contention is a transient error (`IMPROVE_LOCK_HELD`, exit 75). |
-| `--require-feedback-signal` | `boolean` | Turn the fallback lanes (high salience, proactive maintenance) off for the run: they only select and score assets, and a rewrite needs negative feedback. |
+| `--require-feedback-signal` | `boolean` | Turn the proactive-maintenance lane off for the run, so only assets with recent feedback are planned. |
 
 Injected function seams (`reflectFn`, `distillFn`, `ensureIndexFn`, `reindexFn`) replace production defaults in tests.
 
@@ -49,7 +49,7 @@ flowchart TD
     P -- yes --> P1[Log failures; refs that still fail\nare excluded from selection]
     P -- no --> L[Signal delta\nreflect: negative feedback, distill: any signal,\nnewer than the last ledger attempt\nand no hard ledger window]
     P1 --> L
-    L --> L2[Fallback lanes\nproactive maintenance, high salience:\nonly retrieved or new material,\nscored and never planned]
+    L --> L2[Proactive maintenance lane:\nonly retrieved or new material,\nmaxPerRun picks, due after dueDays]
     L2 --> M[scoreSalience\nsalience vector per ref: encoding, outcome, retrieval\nutility scores from SQLite seed the outcome term]
     M --> N[Sort by salience rank DESC, no-op dampened\ndrop refs missing on disk\napply --limit if set]
     N --> Q
@@ -100,7 +100,7 @@ flowchart TD
             DISTILL_G -- no --> DISTILL_J{quality gate judge:\nreusable, non-redundancy, grounding}
             DISTILL_J -- pass --> DISTILL_H[createProposal lessons/slug-lesson\nor knowledge/slug\nsource: distill, gate decision deferred\nappendEvent: outcome=queued]
             DISTILL_J -- mean in the review band --> DISTILL_REVIEW[createProposal, gate decision deferred\nappendEvent: outcome=review_needed]
-            DISTILL_J -- any criterion 2 or below, or the mean too low --> DISTILL_REJECT[improve_ledger row, no proposal\nappendEvent: outcome=quality_rejected]
+            DISTILL_J -- any criterion 2 or below, or the mean too low --> DISTILL_REJECT[improve_ledger row, no proposal\nappendEvent: outcome=quality_rejected\nunless a repeated lesson gets an update proposal, step 10]
             DISTILL_PROMOTE --> DISTILL_RETURN
             DISTILL_SKIP --> DISTILL_RETURN
             DISTILL_EXISTS --> DISTILL_RETURN
@@ -150,7 +150,7 @@ flowchart TD
             PAIR_INIT --> PAIR_CAND[Candidates: k=5 nearest by stored vector,\nsame bundle + memory tier, cosine >= T_pair]
             PAIR_CAND --> PAIR_JUDGE[One LLM call per pair:\nconsolidate-pair.md, 6-label schema]
             PAIR_JUDGE --> PAIR_OUT{judge label}
-            PAIR_OUT -- duplicate / subsumed / supersedes --> PAIR_GUARDS[Guards: hot capture, derived parent,\nrejected-pair match, same-run chain]
+            PAIR_OUT -- duplicate / subsumed / supersedes --> PAIR_GUARDS[Guards: derived parent,\nrejected-pair match, same-run chain]
             PAIR_GUARDS --> PAIR_CONTINUITY[Continuity check R3:\nreplay retired asset's own queries,\nflag continuityRisk, never block]
             PAIR_CONTINUITY --> PAIR_PROPOSE[emitProposal: retire,\nsource: consolidate-pair]
             PAIR_OUT -- overlap / unrelated / contradicts --> PAIR_NOACTION[judged_no_action\nno 7-day timer — content change only]
@@ -209,9 +209,8 @@ Reflect changes only an asset's `description`, `when_to_use` and title. The engi
    contract instead.
 6. Validate the reply with `parseSchemaReflectOutput` (`parseFramedReflectOutput` for the framed contract), which strips `<think>` blocks and code fences, then requires exactly the contract's fields: `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. A reply that fails gets one repair turn, shared across self-refine passes: the conversation so far, and a request to reformat the reply in the contract (`reflect-output-repair.md`). A reply still invalid fails with `parse_error` and queues nothing. A failed agent or SDK dispatch is reported as it ran, with its exit code and stderr.
 7. Apply the patch (`applyReflectPatch`) to the source asset: its frontmatter with the non-null `description` and `when_to_use` set, and its body unchanged. 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 source that requires a `description` and has none gets one derived from its own text when the patch gave none (#636). A patch that changes nothing (every field `null`, or equal to the source's, and no `description` to derive) is the `no_change` outcome (`reflect_skipped_noop`), as is a source with no content to patch; a result that differs only cosmetically is `reflect_skipped_cosmetic`. Neither creates a proposal.
-8. Quality gate (`processes.reflect.qualityGate`, on unless disabled): one judge call scores the revision against the source on **need**, **preservation** and **quality** ([Quality judge](../improvement.md#quality-judge)), and passes it only when every criterion scores 4 or more. A score that does not pass is refused (`quality_rejected`, no proposal). A judge that times out, errors or replies unparseably gives no verdict, and the proposal is deferred for review (`judge-error`, gate `quality-gate`). Before the judge, with the gate on or off, reflect refuses (`quality_rejected`, no proposal, no judge call; the rule is the event's `reflectDefect`) a revision that adds placeholder text (`placeholder_added`: "please confirm", "to be confirmed"; not `TODO`, `TBD` or `FIXME`), talks about its own edit (`meta_commentary_added`: "the feedback says", "this revision") or copies frontmatter into its body (`frontmatter_copied_into_body`: `sources:` or `updated:` lines outside code, a `sources` value). Each rule counts only what the revision adds to its source (`findReflectDefect`), and its wording is a list that `processes.reflect.defectFilter` replaces or, when empty, turns off ([Configuration](../../reference/configuration.md#strategies)).
-9. Retrieval regression gate, after a pass on an existing asset: a revision that grades lower on the asset's own retrieval queries is refused ([Retrieval regression gate](../improvement.md#retrieval-regression-gate)).
-10. Write the proposal (`mintProposal`). A pass the judge passed is stamped `staged`, and the triage drain accepts it; with the gate off the proposal is minted unstamped for the drain to decide. One made with no judge configured (`no-judge-configured`) is deferred for review (gate `reflect`), and so is one whose judge gave no verdict (`judge-error`). The drain leaves every deferral for a person.
+8. Quality gate (`processes.reflect.qualityGate`, on unless disabled): one judge call scores the revision against the source on **need**, **preservation** and **quality** ([Quality judge](../improvement.md#quality-judge)), and passes it only when every criterion scores 4 or more. A score that does not pass is refused (`quality_rejected`, no proposal) unless its mean is 3.5 or more: that is uncertain, not bad, and the proposal is deferred for a person (`judge-uncertain`, gate `quality-gate`, with the criterion `scores` and the judge's reason) and records no rejection window. A judge that times out, errors or replies unparseably gives no verdict, and the proposal is deferred for review too (`judge-error`, gate `quality-gate`). Before the judge, with the gate on or off, reflect refuses (`quality_rejected`, no proposal, no judge call; the rule is the event's `reflectDefect`) a revision that adds placeholder text (`placeholder_added`: "please confirm", "to be confirmed"; not `TODO`, `TBD` or `FIXME`), talks about its own edit (`meta_commentary_added`: "the feedback says", "this revision") or copies frontmatter into its body (`frontmatter_copied_into_body`: `sources:` or `updated:` lines outside code, a `sources` value). Each rule counts only what the revision adds to its source (`findReflectDefect`), and its wording is a list that `processes.reflect.defectFilter` replaces or, when empty, turns off ([Configuration](../../reference/configuration.md#strategies)).
+9. Write the proposal (`mintProposal`). A pass the judge passed is stamped `staged`, and the triage drain accepts it; with the gate off the proposal is minted unstamped for the drain to decide. One made with no judge configured (`no-judge-configured`) is deferred for review (gate `reflect`), and so is one whose judge gave no verdict (`judge-error`) and one in the judge's uncertain band (`judge-uncertain`). `akm proposal list` shows the reason; the drain leaves every deferral for a person.
 
 **What it writes:** one durable proposal row in `state.db`. It never writes asset files directly.
 
@@ -245,10 +244,17 @@ Reflect changes only an asset's `description`, `when_to_use` and title. The engi
    - **Grounding** asks whether every cause, step, number, rule and limit in the lesson is stated by the source or its feedback; 4–5 when each is, 3 when one stretches what the source says, 1–2 when any is in neither, when the lesson drops a limit the source states, or when it is about another subject. It is not part of the mean.
    - A criterion at 2 or below is `quality_rejected` whatever the mean is (the reason names the criterion: `grounding 2/5: …`). Otherwise the lesson passes when reusable and non-redundancy both score 4 or more, and a mean of those two of 2.5 or more is `review_needed`. A pass is also queued for a person (step 9), so the rejection is the only thing that keeps a lesson from a reviewer: on 2026-10-05 the old rubric (novelty, non-redundancy, and a grounding that scored 3 for a lesson that "goes beyond the source") passed 10 of the 17 bad lessons, because a lesson that adds to its memory scored as novel. The old novelty question was also the reason the judge rejected a faithful lesson of a lesson-worthy memory. A distill with no source to read (an unindexed ref distilled "from feedback signal alone") gives the judge an empty source, so its lesson is expected to be rejected.
    - `quality_rejected` writes an `improve_ledger` row for the input (30-day distill rejection window) and a `distill_invoked` event carrying `score`, the per-criterion `criteria` and the `reason`. It mints no proposal.
-   - `review_needed` mints a pending proposal stamped `deferred` / `quality-gate` for a human; the triage drain leaves it alone. It is the outcome for a non-passing mean of 2.5 or more when no criterion is at 2 or below, a judge that times out or returns something unparseable or incomplete, the optional fidelity check's contradiction (`processes.distill.fidelityCheck.enabled`, off by default; a lesson that contradicts its source reaches a human this way, not through grounding), and a heuristic lesson-quality finding (for example an invalid `description`), which is found before the judge is called.
+   - `review_needed` mints a pending proposal stamped `deferred` / `quality-gate` for a human; the triage drain leaves it alone. It is the outcome for a non-passing mean of 2.5 or more when no criterion is at 2 or below, a judge that times out, returns something unparseable or incomplete, or is missing when the lesson or promotion is judged, and a heuristic lesson-quality finding (for example an invalid `description`), which is found before the judge is called.
 9. Create proposal: `createProposal(stash, { ref: lessonRef, source: "distill", payload })` through `mintProposal`. A pass is minted `deferred` (gate `quality-gate`, reason `distill-review`) with the judge's per-criterion `scores` and `judgeReason`, for a person: the triage drain and its judgment tier leave it alone, and the improve ledger records `review_needed`. It is never `staged`. 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 promotion to knowledge that passes is deferred the same way. With `processes.distill.qualityGate` off nothing was judged, so the proposal is minted unstamped for the drain to decide.
 10. Emit `distill_invoked` event with `outcome: "queued"`.
 
+**Updating a lesson the memory repeats (#1090):** when the lesson repeats one the library holds, distill extends that lesson instead of only dropping the duplicate. It happens in two places, both with the quality gate on: the judge scored the writer's lesson 2 or below on non-redundancy (step 8), or the writer answered `NONE` (step 5). Either way the update is tried for the related lessons (among the top 3 nearby assets, as for the judge, in the bundle the proposal is filed in) that the writer's `reason`, or the judge's, names by ref or name, or for the only related lesson when it names none. One lesson among several that merely sit near the memory costs no call. A second call shows the writer the memory, its feedback and the candidate lessons' bodies, and asks it to pick the lesson that already states the memory's rule, list in `new_facts` each cause, step, number, limit or consequence the memory states and the lesson lacks (the memory's own incident retold is not one), and return that lesson's whole body with a line added for each; it answers `decision: "none"` when no listed lesson states the rule, when `new_facts` is empty (an update with none is not proposed), or when the memory contradicts a line. Then:
+
+- Every existing body line must still be there (compared by words, in any case and spacing). A body that drops or rewords one is not proposed.
+- The extended lesson (existing frontmatter and the whole new body) is judged as one lesson, in one call, by step 8's judge with an edit variant of its rubric: **reusable** and **grounding** read the whole lesson (a line is grounded when the memory, its feedback or the lesson being extended states it), and **non-redundancy** is asked of each added line against the lesson being extended: 1–2 when it only says again what the lesson says (its rule or cause in other words, or the same rule on an example from the memory), 4–5 when it states a fact the lesson lacks, however specific. The lesson being extended is shown to the judge as such, not as an asset the new lesson might repeat. Judging the added lines alone as a new lesson failed `reusable` for a lone fact, and no update passed. A body that adds no line is not proposed; anything short of a judge pass is not proposed.
+- The update is a pending proposal on the existing lesson's ref (`source: distill`), the lesson's frontmatter unchanged except that the memory is added to `xrefs`. Its `beforeHash` is the lesson's as read, so accepting it after the lesson changed is refused as stale. It is minted `deferred` (gate `quality-gate`, reason `distill-update`) with the judge's `scores` and `judgeReason`, so the triage drain and its judgment tier leave it for a person. The result and the `distill_invoked` event are `queued` with `proposalRef` set to the lesson and `updatesExisting: true`.
+- When nothing is proposed, the outcome is what it was before: `quality_rejected` with the judge's reason after a duplicate lesson, `skipped` / `nothing_reusable` after `NONE`.
+
 **Lesson-ref derivation rule:** `lessons/<type>-<name>-lesson` where `<type>-<name>` is derived from the input ref with origin stripped and non-alphanumeric characters replaced by `-`. Example: `skills/deploy` → `lessons/skill-deploy-lesson`. A lesson already at that ref is never overwritten (see step 4).
 
 **What it writes:** one durable proposal row in `state.db`. Never writes asset files directly.
@@ -378,8 +384,8 @@ duplicate, subsumed and superseding retirement, review-gated.
    body characters.
 4. **Outcome:** `duplicate`, `subsumed` and `supersedes` mint one `retire`
    proposal (source `consolidate-pair`, its own generator — see below) for
-   the side that does not survive — never a `captureMode: hot` memory, never
-   a `.derived` memory whose parent still exists, never across bundles,
+   the side that does not survive — never a
+   `.derived` memory whose parent still exists, never across bundles,
    never when either side already has a pending retire proposal (as the
    retired ref or its successor), and never retiring or reusing as a
    successor an asset already spent earlier in the SAME run (the durable
@@ -478,8 +484,8 @@ proposal.
 
 Before the pair pass mints a `retire` proposal, it replays up to five of the
 retired asset's own past `search`/`curate` queries
-(`loadRetrievalQueries`, `src/commands/improve/retrieval-gate.ts` — the same
-cleaned set the retrieval regression gate replays: `usableRetrievalQueries`
+(`loadRetrievalQueries`, `src/commands/improve/retrieval-queries.ts`:
+`usableRetrievalQueries`
 drops stash-README boilerplate and harness/tool envelopes
 (`nonTaskInput`), pastes over 2,000 characters, and queries that are
 duplicates once whitespace is collapsed, S3a) through akm's own search,
@@ -610,7 +616,7 @@ Two proposals can share the same `ref`; their UUID primary keys prevent collisio
 
 ## Scope restrictions
 
-`akm improve` reads and writes one bundle, its write target: `--bundle`, else `defaultWriteTarget`, else the working bundle. The candidate set is that bundle's assets and nothing else, because every proposal is filed in the write target. An asset that another writable bundle owns is never planned: reflect would read it from its own bundle and the proposal would land in this one, either forking the asset as a `create` or overwriting this bundle's copy with content taken from the other's (#1000). A bare ref scope (`akm improve skills/x`) resolves inside the write target only, and distill's memory-to-knowledge promotion merges only with a doc that already exists there. To improve another writable bundle, select it with `--bundle team` or a bundle-qualified scope such as `team//skills/code-review`; a scheduled run therefore covers only its write target, and each other bundle needs its own scheduled `akm improve --bundle <name>` run. A dry run (`--dry-run`, `--plan`) resolves the bundle the way a live run does, with the working bundle starting from `AKM_BUNDLE_DIR` before `defaultBundle`, so it previews the bundle a live run improves. As a second line of defence, `createProposal` refuses a proposal whose `itemRef` names an asset owned by a different configured bundle than the queue's.
+`akm improve` reads and writes one bundle, its write target: `--bundle`, else `defaultWriteTarget`, else the working bundle. The candidate set is that bundle's assets and nothing else, because every proposal is filed in the write target. An asset that another writable bundle owns is never planned: reflect would read it from its own bundle and the proposal would land in this one, either forking the asset as a `create` or overwriting this bundle's copy with content taken from the other's (#1000). A bare ref scope (`akm improve skills/x`) resolves inside the write target only, and distill's memory-to-knowledge promotion merges only with a doc that already exists there. To improve another writable bundle, select it with `--bundle team` or a bundle-qualified scope such as `team//skills/code-review`; a scheduled run therefore covers only its write target, and each other bundle needs its own scheduled `akm improve --bundle <name>` run. A dry run (`--dry-run`) resolves the bundle the way a live run does, with the working bundle starting from `AKM_BUNDLE_DIR` before `defaultBundle`, so it previews the bundle a live run improves. As a second line of defence, `createProposal` refuses a proposal whose `itemRef` names an asset owned by a different configured bundle than the queue's.
 
 `akm improve` and `akm lint` only operate on writable bundle sources (sources with `writable: true`). Read-only sources (git, npm, website) are excluded from the candidate set before any other filtering; a read-only write target plans nothing.
 
@@ -622,12 +628,12 @@ Every stage reads the improve ledger (`improve_ledger` in `state.db`, one row pe
 
 - A ref that passes reflect is planned for the loop. If it does not pass distill, distill is skipped for it (a `distill-skipped` action and an `improve_skipped` event with reason `distill_no_new_signal`).
 - A ref that passes only distill, and is a distill candidate, is planned distill-only.
-- A ref with no in-window feedback and no reflect window is left to the fallback lanes (proactive maintenance and high salience), which pick only what retrieval returned or new material (see [Retrieval scope](../improvement.md#retrieval-scope)). The lanes only select and score: a ref they pick is not planned for reflect or distill, so improve does not rewrite assets on a proactive cadence.
-- Every ref the loop does not take is counted in the plan's `signal` gate (or its `retrieval` gate, when the fallback lanes could not pick it for lack of usage evidence) and reported once, in aggregate, as an `improve_skipped` event (`no_new_signal`, `not_retrieved`).
+- A ref with no in-window feedback and no reflect window is left to the proactive-maintenance lane, which picks only what retrieval returned or new material (see [Retrieval scope](../improvement.md#retrieval-scope)) and plans its picks with the feedback-bearing refs. The cap against a proposal flood: `maxPerRun` (15) picks per run, an asset due only after `dueDays` (30) without a reflect or distill, and reflect's `limit` (25).
+- Every ref the loop does not take is counted in the plan's `signal` gate (or its `retrieval` gate, when the proactive lane could not pick it for lack of usage evidence) and reported once, in aggregate, as an `improve_skipped` event (`no_new_signal`, `not_retrieved`).
 - A memory flagged wrong is not distilled: when a negative feedback in the 30-day window recorded the hash of the body it judged (`contentHash`, the `body` hash of `content-hash.ts`) and the file's body still has it, the loop skips distill for it (a `distill-skipped` action and an `improve_skipped` event with reason `distill_flagged_wrong`) and records the attempt in the ledger as `unchanged`, so the ref waits for newer feedback. Reflect still plans it. A write that leaves the body alone (an inference stamp, a 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, whose modification time is the edit signal, as for the retrieval scope's new material.
 - A memory whose only feedback in the 30-day window is positive without a reason or note (`hasOnlyBarePositiveFeedback` in `preparation.ts`) is not distilled either: the loop skips distill for it (a `distill-skipped` action with the reason "only positive feedback, without a reason" and an `improve_skipped` event with reason `distill_positive_without_reason`) and records the attempt in the ledger as `unchanged`, so it waits for newer feedback. A bare `--positive` only records that a note helped, which gives the writer nothing to distil: 10 of the 11 lessons made from such a memory were rejected on 2026-10-05, and the 11th was good. A reason, a note or a negative signal among the feedback, or an explicit ref scope, lets it through.
 - A memory whose frontmatter says `beliefState: deprecated` or `superseded` (`isDeprecatedOrSuperseded` in `preparation.ts`) is not distilled either: the loop skips distill for it (a `distill-skipped` action with the reason "marked deprecated or superseded" and an `improve_skipped` event with reason `distill_deprecated_or_superseded`) and records the attempt in the ledger as `unchanged`. An explicit `--scope` ref still runs. `contradicted` is not skipped: it marks an open conflict, not a retired note.
-- The loop's refs are ranked by salience (`scoreSalience` in `preparation.ts`, which also scores the fallback lanes' picks and computes each vector with `computeSalience` from `salience.ts`): encoding, outcome, and retrieval frequency and recency, discounted for file size, with a ref that was repeatedly skipped as a no-op ranked lower. Refs missing on disk are dropped, and `--limit` cuts the list: reflect-path refs first, then distill-only refs.
+- The loop's refs are ranked by salience (`scoreSalience` in `preparation.ts`, which also scores the lane's picks and computes each vector with `computeSalience` from `salience.ts`): encoding, outcome, and retrieval frequency and recency, discounted for file size, with a ref that was repeatedly skipped as a no-op ranked lower. Refs missing on disk are dropped, and `--limit` cuts the list: reflect-path refs first, then distill-only refs.
 
 An explicit ref scope bypasses every gate. Consolidation, extract and schema repair read their own ledger sources in their own stages.
 

package/docs/architecture/internals/indexing.md

@@ -429,7 +429,7 @@ so a layout change is applied in place rather than by discarding the index.
 Durable workflow, task, proposal, event, and usage state in `state.db` is
 never touched by these paths.
 
-Workflow `.md` and `.yml` adapters compile directly to source IR version 1.
+The workflow `.md` adapter compiles directly to source IR version 1.
 The index stores only the ordinary normalized `entries` row and searchable
 metadata derived from that IR. It does not cache a second workflow AST or an
 executable plan. Starting a run recompiles the authored source once and freezes