akm-cli 0.9.0-beta.40 → 0.9.0-beta.42

package/CHANGELOG.md

@@ -6,6 +6,89 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Fixed
+
+- **improve/recombine: cap-aware decay — the `maxClustersPerRun` cap no longer
+  traps recurring hypotheses below `confirmThreshold` (#658).** Recombine is a
+  two-pass design: a cluster must be re-induced on `confirmThreshold` (=2) runs
+  before its `type:hypothesis` proposal promotes to an auto-accepted
+  `type:lesson`. But only the top-`maxClustersPerRun` (=5) clusters are
+  processed per run, and `decayUnseenRecombineHypotheses` hard-reset the
+  confirmation streak of every hypothesis not processed that run. A cluster that
+  genuinely re-forms every run but is displaced out of the top-5 (slots are tied
+  on member-count and broken by an arbitrary alphabetical tiebreak) had its
+  streak zeroed — it could never win two consecutive slots, so its proposal sat
+  pending forever (6 such proposals were stuck in one production stash).
+  `decayUnseenRecombineHypotheses` is now **cap-aware**: `recombine.ts` passes
+  the FULL pre-cap cluster set, and a hypothesis is spared from reset when its
+  cluster still Jaccard-matches a present cluster (same signature, overlap ≥ 0.7
+  — the same rule used for re-induction). Only hypotheses with no matching
+  current cluster (the corpus stopped supporting them) decay. This does **not**
+  lower the recurrence bar: the confirmation count is still advanced only by
+  genuine re-induction in the processed slice (`recordRecombineInduction`);
+  sparing merely avoids an artificial reset, so a genuinely non-recurring
+  hypothesis still decays to 0 and never confirms (no new bland-hypothesis churn,
+  cf. #632/#633). No schema change. The cap now lives in a new `capClusters`
+  helper split out of `buildRelatednessClusters` so the full ranked set stays
+  available for the decay sweep.
+- **`improve` reflect no longer emits proposals doomed to fail the
+  `invalid-description` gate when the source asset has no frontmatter
+  `description` (#636).** Reflect echoed the source frontmatter, so for assets
+  that carry other keys but no `description` (notably scraped docs:
+  `source`/`title`/`scraped`) the proposal inherited the missing/empty
+  description and the promote-time validator (`isValidDescription`, 20–400
+  chars) rejected it — observed as ~14/16 rejects in one triage pass, blocking
+  the whole scraped-doc/knowledge cluster from reflect improvement. The fix is
+  **generation-time only**: (1) `buildReflectPrompt` now injects an explicit
+  "synthesize a `description`" instruction whenever the source lacks a non-empty
+  `description` and the asset type requires one (per `authoring-rules.ts`
+  `DESCRIPTION_TYPES`), telling the model it MUST author a valid 20–400-char
+  plain-prose description from the asset's `title:`/first `# Heading`/opening
+  body; and (2) a deterministic reflect-side belt-and-suspenders in
+  `sanitizeReflectPayload` — if a source that already had frontmatter still ends
+  up with a missing/empty description after generation, reflect derives one
+  deterministically from `title:`/first heading (validated against
+  `isValidDescription`, never free-form invention) **before** the proposal is
+  created. The validator, `authoring-rules.ts` bounds, `repairProposalContent`,
+  and the drain are unchanged — nothing in the validator/promote path fabricates
+  content to pass itself.
+- **The high-salience improve admission lane (#608) now requires a
+  content-derived encoding score, not the per-type weight stub (#655,
+  #608/#644 follow-up).** The lane previously admitted any zero-feedback ref
+  whose `asset_salience.encoding_salience >= salienceThreshold` (default 0.75).
+  But for assets distill has not content-scored, `encoding_salience` is just the
+  per-type WEIGHT STUB (skill/agent 0.9, command/workflow 0.8, lesson 0.75), so
+  "high-salience" degenerated into "is a skill/agent/command/lesson" — which
+  selected the type-stub `lore-writer` agent on every run (prod: 1 content-scored
+  / 37 type-stub / 1826 NULL-legacy rows). The gate now also requires
+  `isContentEncodingRow(row, parseAssetRef(ref).type)` (the #644 provenance
+  helper), so only genuinely content-scored assets qualify. This preserves
+  #608's intent — distilled assets, the lane's real targets, keep their real
+  content score and still qualify — while cutting the type-stub waste; type-stub
+  rows must earn retrieval/feedback signal via the other lanes. NULL-legacy rows
+  follow `isContentEncodingRow`'s differs-from-stub heuristic. An aggregated log
+  line now reports how many refs the lane admitted so lane composition is
+  observable. The threshold, type-weight table, 10% cap, and `isContentEncodingRow`
+  are unchanged.
+
+- **Auto-sync no longer refuses to commit akm's own changes when unrelated
+  non-akm files are present in the stash working tree.** When a stash root is
+  shared with a project repo, stray files written into the stash root (e.g. a
+  `tasks.bak-…` backup dir or report artifacts like `data.js`,
+  `akm-health-report.html`, `reports/`) previously tripped the #476 safety
+  guard, which threw `refusing to push: … has uncommitted non-akm changes` on
+  **every** `akm improve` end-of-run auto-sync, `akm sync`, and `akm push`. In
+  one production incident this silently blocked all commits for ~1.5 days while
+  akm kept accepting proposals it never persisted. `saveGitStash` now **scopes
+  what it stages** instead of refusing: (1) an explicit modified-file list when
+  the caller passes `opts.paths`, else (2) the akm-managed pathspecs
+  (`TYPE_DIRS` values + `.akm`) that exist on disk — which by construction never
+  stages non-akm WIP, preserving the #476 protection without an all-or-nothing
+  refusal — and only as a last resort (3) `git add -A` when no managed pathspec
+  can be resolved. If nothing akm-managed is staged the run returns
+  `nothing to commit` (no empty commit, no throw). Unrelated non-akm files are
+  left untouched and uncommitted.
+
 ### Changed
 
 - **BEHAVIOR CHANGE — `akm init --dir <path>` no longer silently repoints your

package/dist/commands/improve/improve.js

@@ -2471,6 +2471,18 @@ async function runImprovePreparationStage(args) {
     // noFeedbackCandidates), burning LLM calls and churning the asset. This
     // mirrors the P0-A high-retrieval gate's `!lastReflectProposalTs.has(r.ref)`
     // guard above so all "rescue" lanes share the same once-per-asset semantics.
+    //
+    // Content-provenance gate (#644 follow-up): the row must ALSO carry a genuine
+    // content-derived encoding score (`isContentEncodingRow`). Otherwise the lane
+    // admits the per-type WEIGHT STUB (skill/agent 0.9, command/workflow 0.8,
+    // lesson 0.75 from DEFAULT_TYPE_ENCODING_WEIGHTS) for every distill-unscored
+    // asset — i.e. "high-salience" degenerates into "is a skill/agent/command/
+    // lesson", which selected the lore-writer type-stub agent on every run. Only
+    // content-scored assets earn the high-salience rescue; type-stub rows must
+    // earn retrieval/feedback signal via the other lanes. This PRESERVES #608's
+    // intent — distilled assets (the lane's real targets) keep their real content
+    // score and still qualify — while cutting the type-stub waste. See §5 F1 of
+    // docs/design/improve-salience-working-reference.md and #608/#644.
     const highSalienceRefs = [];
     const salienceCfg = (options.config ?? loadConfig()).improve?.salience;
     const salienceThreshold = salienceCfg?.salienceThreshold ?? 0.75;
@@ -2486,7 +2498,10 @@ async function runImprovePreparationStage(args) {
                 if (highSalienceRefs.length >= highSalienceCap)
                     break;
                 const row = getAssetSalience(dbForHighSalience, r.ref);
-                if (row && row.encoding_salience >= salienceThreshold && !lastReflectProposalTs.has(r.ref)) {
+                if (row &&
+                    isContentEncodingRow(row, parseAssetRef(r.ref).type) &&
+                    row.encoding_salience >= salienceThreshold &&
+                    !lastReflectProposalTs.has(r.ref)) {
                     highSalienceRefs.push(r);
                 }
             }
@@ -2499,6 +2514,10 @@ async function runImprovePreparationStage(args) {
             if (dbForHighSalience)
                 dbForHighSalience.close();
         }
+        if (highSalienceRefs.length > 0) {
+            info(`[improve] high-salience lane admitted ${highSalienceRefs.length} content-scored ref(s) ` +
+                `(threshold=${salienceThreshold}, requires content-derived encoding_source)`);
+        }
     }
     // Record an in-memory skip action for every zero-feedback ref that the
     // partition loop deferred to P0-A but P0-A then declined (retrievalCount below

package/dist/commands/improve/recombine.js

@@ -144,8 +144,11 @@ export function isJunkTag(tag) {
  *   - `"both"`  — union of the tag and entity grouping keys.
  *
  * A cluster is a signal whose member set is >= `minClusterSize`. Overlapping
- * clusters are de-duplicated by member-set identity, and the result is capped
- * to `maxClustersPerRun` by member-count descending.
+ * clusters are de-duplicated by member-set identity, and the result is RANKED
+ * by member-count descending (deterministic alphabetical tiebreak). The
+ * `maxClustersPerRun` cap is NOT applied here — call {@link capClusters} on the
+ * result for the processed slice; the full ranked list is retained so the
+ * cap-aware decay sweep can tell cap-displacement from corpus absence (#658).
  */
 export function buildRelatednessClusters(entries, opts) {
     // Only consolidation-eligible memories participate (exclude `.derived`).
@@ -213,9 +216,24 @@ export function buildRelatednessClusters(entries, opts) {
         seenMemberKeys.add(memberKey);
         return true;
     });
-    // Cap to maxClustersPerRun, largest clusters first (deterministic tiebreak).
+    // Rank largest-first (deterministic alphabetical tiebreak). The cap is applied
+    // by the caller via {@link capClusters}, NOT here, so the FULL formed set
+    // (every cluster that genuinely re-forms this run) stays available for the
+    // cap-aware decay sweep — a cluster displaced by the cap must not be confused
+    // with a cluster that vanished from the corpus (#658).
     clusters.sort((a, b) => b.members.length - a.members.length || a.signature.localeCompare(b.signature));
-    return clusters.slice(0, Math.max(0, opts.maxClustersPerRun));
+    return clusters;
+}
+/**
+ * #658 — apply the `maxClustersPerRun` cap to a largest-first ranked cluster
+ * list. Split out from {@link buildRelatednessClusters} so callers retain the
+ * full pre-cap set: the clusters BELOW the cap still re-formed this run and must
+ * spare their hypotheses from decay (cap-displacement is a SCHEDULING miss, not
+ * a substance miss). Callers that only need the processed slice call this; the
+ * full ranked list feeds {@link decayUnseenRecombineHypotheses}.
+ */
+export function capClusters(ranked, maxClustersPerRun) {
+    return ranked.slice(0, Math.max(0, maxClustersPerRun));
 }
 // ── Prompt + ref derivation ───────────────────────────────────────────────────
 /** Read a memory body (frontmatter stripped) for the cluster prompt. */
@@ -380,14 +398,18 @@ export async function akmRecombine(opts) {
         if (db)
             closeDatabase(db);
     }
-    const clusters = buildRelatednessClusters(entries, {
+    // #658 — `rankedClusters` is the FULL set that re-formed this run (ranked,
+    // pre-cap); `clusters` is the processed top-`maxClustersPerRun` slice. The
+    // decay sweep below uses the full set so a cap-displaced (but present)
+    // cluster spares its hypothesis from reset.
+    const rankedClusters = buildRelatednessClusters(entries, {
         minClusterSize,
-        maxClustersPerRun,
         relatednessSource,
         ...(entityByEntryId ? { entityByEntryId } : {}),
         ...(opts.maxClusterSize != null ? { maxClusterSize: opts.maxClusterSize } : {}),
         ...(opts.excludeTags ? { excludeTags: opts.excludeTags } : {}),
     });
+    const clusters = capClusters(rankedClusters, maxClustersPerRun);
     let clustersFormed = 0;
     let proposalsEmitted = 0;
     let lessonsPromoted = 0;
@@ -570,8 +592,22 @@ export async function akmRecombine(opts) {
         }
         // #625 — decay hypotheses NOT re-induced this run (reset their consecutive
         // streak) so confirmation is per-consecutive-run and conservative (AC4).
+        // #658 — but a hypothesis whose cluster genuinely re-formed this run and was
+        // merely cap-displaced (outside the top-`maxClustersPerRun` slice) must NOT
+        // be decayed — that is a scheduling miss, not a substance miss. We pass
+        // EVERY cluster that formed this run (the full pre-cap `rankedClusters`) as
+        // `presentClusters`; decay spares any row that Jaccard-matches a present
+        // cluster under the SAME overlap rule used for re-induction. Only rows with
+        // no matching current cluster (the corpus stopped supporting them) decay.
         if (stateDb) {
-            const decayedCount = decayUnseenRecombineHypotheses(stateDb, sourceRun, [...seenThisRun]);
+            const presentClusters = rankedClusters.map((c) => ({
+                signature: c.signature,
+                memberKey: recombineMemberKey(c),
+            }));
+            const decayedCount = decayUnseenRecombineHypotheses(stateDb, sourceRun, [...seenThisRun], {
+                presentClusters,
+                minOverlap: DEFAULT_RECOMBINE_OVERLAP,
+            });
             if (decayedCount > 0) {
                 appendEvent({
                     eventType: "recombine_invoked",

package/dist/commands/improve/reflect.js

@@ -29,6 +29,7 @@ import { parseAssetRef } from "../../core/asset/asset-ref.js";
 import { assembleAssetFromString, serializeFrontmatter } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { stripMarkdownFences } from "../../core/asset/markdown.js";
+import { DESCRIPTION_MAX_CHARS, requiresDescription } from "../../core/authoring-rules.js";
 import { resolveStashDir } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
@@ -44,7 +45,7 @@ import { runOpencodeSdk } from "../../integrations/harnesses/opencode-sdk/index.
 import { chatCompletion } from "../../llm/client.js";
 import { isLlmFeatureEnabled } from "../../llm/feature-gate.js";
 import { baseFailureFields, enoentHintMessage, isEnoentFailure, loadAgentConfigFromDisk, resolveAgentProfile, } from "../agent/agent-support.js";
-import { checkReflectSize } from "../proposal/validators/proposal-quality-validators.js";
+import { checkReflectSize, isValidDescription } from "../proposal/validators/proposal-quality-validators.js";
 import { createProposal, isProposalSkipped, listProposals, } from "../proposal/validators/proposals.js";
 import { deriveLessonRef, runLessonQualityJudge } from "./distill.js";
 import { classifyReflectChange } from "./reflect-noise.js";
@@ -403,6 +404,82 @@ function stripAppendedFrontmatter(body) {
         return body;
     return body.slice(0, body.indexOf(match[0])).replace(/\s+$/, "");
 }
+/**
+ * #636 — deterministically derive a valid `description` from an asset's existing
+ * metadata when one is missing. Sources, in priority order: the `title:`
+ * frontmatter field, the first `# Heading` in the (proposed or source) body, and
+ * the first sentence of the opening body paragraph. The candidate is normalized
+ * (whitespace collapsed, trailing punctuation/markdown stripped, clamped to the
+ * description max) and only returned if it PASSES `isValidDescription` — so this
+ * never produces a heading-fragment, truncated, or otherwise gate-failing value.
+ * Returns `undefined` when nothing usable can be derived (caller leaves the
+ * proposal as-is rather than fabricating prose).
+ *
+ * This is intentionally deterministic and lives in the reflect proposal-build
+ * path — it does NOT touch the validators or the promote-time repair.
+ */
+function deriveDescriptionFromAsset(title, proposedBody, sourceBody, targetRef) {
+    // Each candidate is tagged with its kind. A title or `# Heading` is a bare
+    // fragment ("Paged.js — Named Page") that reads poorly as a description even
+    // when it is long enough to pass the length gate, so for those we prefer the
+    // padded sentence form. A prose sentence is already a sentence, so it is used
+    // as-is (padding it would double-wrap an already-complete sentence).
+    const candidates = [];
+    // 1. title: frontmatter
+    if (typeof title === "string" && title.trim())
+        candidates.push({ text: title.trim(), kind: "fragment" });
+    // 2. first `# Heading` (proposed body first, then source body)
+    for (const body of [proposedBody, sourceBody]) {
+        const headingMatch = body.match(/^#{1,6}\s+(.+?)\s*$/m);
+        if (headingMatch?.[1])
+            candidates.push({ text: headingMatch[1].trim(), kind: "fragment" });
+    }
+    // 3. first sentence of the opening prose paragraph (skip headings, fences,
+    //    list markers, blockquotes — those are not prose).
+    for (const body of [proposedBody, sourceBody]) {
+        const firstSentence = firstProseSentence(body);
+        if (firstSentence)
+            candidates.push({ text: firstSentence, kind: "prose" });
+    }
+    for (const { text, kind } of candidates) {
+        const normalized = normalizeDescriptionCandidate(text);
+        if (!normalized)
+            continue;
+        // For a title/heading fragment, try the padded sentence form FIRST so the
+        // result reads as a sentence rather than a bare fragment — a short but valid
+        // title like "Paged.js — Named Page" (21 chars) would otherwise be returned
+        // verbatim. Fall back to the bare form only if the padded form fails the
+        // gate. A prose candidate is already a sentence, so it is used as-is.
+        const variants = kind === "fragment" ? [`Reference notes on ${normalized}.`, normalized] : [normalized];
+        for (const v of variants) {
+            const clamped = v.length > DESCRIPTION_MAX_CHARS ? v.slice(0, DESCRIPTION_MAX_CHARS).trimEnd() : v;
+            if (isValidDescription(clamped, targetRef, { skipRefTailCheck: true }).ok)
+                return clamped;
+        }
+    }
+    return undefined;
+}
+/** Extract the first prose sentence from a markdown body, or `""` if none. */
+function firstProseSentence(body) {
+    for (const rawLine of body.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        if (/^(#{1,6}\s|```|~~~|[-*+]\s|\d+\.\s|>|\||<!--)/.test(line))
+            continue;
+        const sentenceMatch = line.match(/^(.+?[.!?])(\s|$)/);
+        return (sentenceMatch?.[1] ?? line).trim();
+    }
+    return "";
+}
+/** Normalize a description candidate: strip markdown markers, collapse space. */
+function normalizeDescriptionCandidate(raw) {
+    return raw
+        .replace(/`/g, "")
+        .replace(/^[#>*\-\s]+/, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
 /**
  * Reflect post-processor — enforces the safety rails described at the top of
  * this file:
@@ -428,7 +505,7 @@ function stripAppendedFrontmatter(body) {
  * from `payload.frontmatter` so identity fields can be enforced. Size guard
  * is skipped because there is no source to compare against.
  */
-function sanitizeReflectPayload(payload, sourceContent, targetRef) {
+export function sanitizeReflectPayload(payload, sourceContent, targetRef) {
     const warnings = [];
     const { fmText: sourceFmText, body: sourceBody } = sourceContent
         ? splitFrontmatter(sourceContent)
@@ -470,6 +547,34 @@ function sanitizeReflectPayload(payload, sourceContent, targetRef) {
         }
     }
     const cleanedBody = stripAppendedFrontmatter(rawLlmBody.replace(/^\s+/, ""));
+    // #636 — deterministic description fallback (reflect-side belt-and-suspenders).
+    // If the type requires a `description` and the merged frontmatter is still
+    // MISSING one (source had none AND the model didn't author one), derive a
+    // description DETERMINISTICALLY from the existing `title:` frontmatter or the
+    // first `# Heading` / opening body sentence — never free-form invention. This
+    // runs in the reflect proposal-build path, BEFORE the proposal is created, so
+    // the validator/promote path is left untouched (no gate fabricates content).
+    //
+    // Scope is the issue's target: a source asset that ALREADY carries frontmatter
+    // (e.g. scraped docs: `source`/`title`/`scraped`) but has a MISSING/empty
+    // `description`. We deliberately do NOT fire when:
+    //   - the source has no frontmatter block at all (injecting one would be a
+    //     structural change and would defeat the #580 no-op/cosmetic noise gate
+    //     for a pure body echo), or
+    //   - a present-but-otherwise-invalid description exists (too short, a heading
+    //     fragment) — overwriting authored content is out of scope; the prompt
+    //     instruction handles improving it instead.
+    const refType = targetRef.includes(":") ? (targetRef.split(":")[0] ?? "") : "";
+    const mergedDesc = mergedFm.description;
+    const descIsMissing = typeof mergedDesc !== "string" || mergedDesc.trim().length === 0;
+    const sourceHadFrontmatter = sourceFmText !== null && Object.keys(sourceFm).length > 0;
+    if (refType && requiresDescription(refType) && descIsMissing && sourceHadFrontmatter) {
+        const derived = deriveDescriptionFromAsset(mergedFm.title, cleanedBody, sourceBody, targetRef);
+        if (derived) {
+            mergedFm.description = derived;
+            warnings.push("Synthesized a deterministic `description` from title/heading (#636) — source and proposal lacked one.");
+        }
+    }
     // Size guard — only when source body is meaningfully large. The pure
     // predicate lives in `core/proposal-quality-validators` so the same check
     // also runs inside `runProposalValidators` on `proposal accept`.

package/dist/core/authoring-rules.js

@@ -70,6 +70,15 @@ const WHEN_TO_USE_TYPES = new Set(["lesson"]);
  * Inject this VERBATIM into every improve/authoring prompt that creates or edits
  * an asset of `type`, so the agent is told exactly what the gate will reject.
  */
+/**
+ * Whether an asset of `type` carries a `description` that the validator
+ * (`isValidDescription` / `validateProposalFrontmatter`) treats as required.
+ * Reflect uses this to decide when a description-synthesis instruction (and the
+ * deterministic reflect-side fallback) must fire for a description-less source.
+ */
+export function requiresDescription(type) {
+    return DESCRIPTION_TYPES.has(type);
+}
 export function authoringRulesForType(type) {
     const rules = [...FRONTMATTER_BODY_RULES];
     if (DESCRIPTION_TYPES.has(type))

package/dist/core/state-db.js

@@ -1708,6 +1708,35 @@ export function getRecombineHypothesis(db, hypothesisRef) {
 export function markRecombineHypothesisPromoted(db, hypothesisRef, promotedAt) {
     db.prepare("UPDATE recombine_hypotheses SET promoted_at = ?, consecutive_count = 0 WHERE hypothesis_ref = ?").run(promotedAt, hypothesisRef);
 }
+/**
+ * #658 — does any current-run cluster match this hypothesis row under the SAME
+ * signature + Jaccard-overlap rule used for re-induction? A match means the
+ * cluster genuinely re-formed this run (it was merely cap-displaced out of the
+ * processed top-`maxClustersPerRun` slice), so its streak must NOT be reset.
+ */
+function hypothesisMatchesAnyPresentCluster(row, presentClusters, minOverlap) {
+    const rowMembers = row.member_key.split("|").filter((m) => m.length > 0);
+    if (rowMembers.length === 0)
+        return false;
+    const rowSet = new Set(rowMembers);
+    for (const cluster of presentClusters) {
+        if (cluster.signature !== row.signature)
+            continue;
+        const clusterMembers = cluster.memberKey.split("|").filter((m) => m.length > 0);
+        if (clusterMembers.length === 0)
+            continue;
+        let intersection = 0;
+        for (const m of clusterMembers) {
+            if (rowSet.has(m))
+                intersection += 1;
+        }
+        const union = rowSet.size + clusterMembers.length - intersection;
+        const overlap = union === 0 ? 0 : intersection / union;
+        if (overlap >= minOverlap)
+            return true;
+    }
+    return false;
+}
 /**
  * Decay-to-zero every NON-promoted hypothesis NOT re-induced in the current run.
  *
@@ -1718,9 +1747,50 @@ export function markRecombineHypothesisPromoted(db, hypothesisRef, promotedAt) {
  *
  * Only rows whose `hypothesis_ref` is NOT in `seenRefs` AND whose `last_run` is
  * NOT the current run are decayed. Already-promoted rows are left alone.
+ *
+ * #658 — CAP-AWARE decay. The recombine pass only re-inducts (and thus marks
+ * `seen`) the top-`maxClustersPerRun` clusters, but a cluster genuinely
+ * re-forms every run even when it is displaced below that cap. Resetting such a
+ * row treats a SCHEDULING miss as a SUBSTANCE miss and traps the hypothesis
+ * below `confirmThreshold` forever. When `opts.presentClusters` is supplied, a
+ * row is SPARED from decay if it Jaccard-matches any present cluster (same
+ * signature, overlap >= `opts.minOverlap`) — i.e. its cluster re-formed this run
+ * but was cap-displaced. This does NOT advance the streak (only re-induction in
+ * the processed slice does that, via {@link recordRecombineInduction}), so the
+ * recurrence bar for promotion is unchanged; it only stops the cap from
+ * manufacturing artificial misses. Omitting `presentClusters` preserves the
+ * pre-#658 hard-reset-after-one-miss behaviour exactly.
+ *
  * Returns the number of rows reset.
  */
-export function decayUnseenRecombineHypotheses(db, currentRun, seenRefs) {
+export function decayUnseenRecombineHypotheses(db, currentRun, seenRefs, opts) {
+    // #658 — when cap-aware sparing is requested, fold the cap-displaced rows into
+    // the "seen" exclusion set: the underlying reset SQL already protects every
+    // ref it is given, so sparing == treating a spared row exactly like a seen
+    // row for this sweep (its count is left untouched, never advanced).
+    let effectiveSeen = seenRefs;
+    if (opts && opts.presentClusters.length > 0) {
+        const candidates = db
+            .prepare("SELECT hypothesis_ref, signature, member_key FROM recombine_hypotheses WHERE promoted_at IS NULL AND (last_run IS NULL OR last_run != ?) AND consecutive_count != 0")
+            .all(currentRun);
+        const seenSet = new Set(seenRefs);
+        for (const row of candidates) {
+            if (seenSet.has(row.hypothesis_ref))
+                continue;
+            if (hypothesisMatchesAnyPresentCluster(row, opts.presentClusters, opts.minOverlap)) {
+                seenSet.add(row.hypothesis_ref);
+            }
+        }
+        effectiveSeen = [...seenSet];
+    }
+    return decayUnseenRecombineHypothesesInner(db, currentRun, effectiveSeen);
+}
+/**
+ * The raw reset sweep shared by the cap-aware wrapper above. Resets every
+ * non-promoted row from a prior run whose ref is NOT in `seenRefs`. Kept private
+ * so the param-ceiling chunking logic lives in one place.
+ */
+function decayUnseenRecombineHypothesesInner(db, currentRun, seenRefs) {
     // Reset every eligible row, then exclude the seen refs in chunks to respect
     // the ~999 SQLite param ceiling. With no seen refs we reset all non-promoted
     // rows from prior runs in a single statement.
@@ -1732,9 +1802,16 @@ export function decayUnseenRecombineHypotheses(db, currentRun, seenRefs) {
     }
     // A single NOT IN keeps the exclusion atomic (a chunked NOT IN would let a ref
     // excluded by one chunk still be reset by another chunk's statement). The
-    // recombine pass caps re-induced clusters at `maxClustersPerRun` (a handful),
-    // so `seenRefs` is far under SQLite's ~999 param ceiling in practice; we cap
-    // defensively and fall back to resetting all when somehow exceeded.
+    // recombine pass caps RE-INDUCED clusters at `maxClustersPerRun` (a handful) —
+    // but with #658 cap-aware sparing the caller folds every cap-displaced
+    // (present-but-unprocessed) hypothesis into `effectiveSeen` too, so on a large
+    // stash `seenRefs` here can carry MANY spared refs, not just the handful that
+    // were processed. We cap defensively at ~900 (under SQLite's ~999 param
+    // ceiling): if `effectiveSeen` somehow exceeds it we fall back to resetting all
+    // eligible rows — which re-introduces the cap-displacement trap for THAT run
+    // (spared rows get decayed because the NOT IN protection is dropped). That is a
+    // rare, bounded degradation; a stash with >900 simultaneously-spared
+    // hypotheses is far beyond current scale.
     if (seenRefs.length > 900) {
         const res = db
             .prepare("UPDATE recombine_hypotheses SET consecutive_count = 0 WHERE promoted_at IS NULL AND (last_run IS NULL OR last_run != ?) AND consecutive_count != 0")

package/dist/integrations/agent/prompts.js

@@ -26,7 +26,7 @@
  * during validation. We carry it through if the agent supplies it.
  */
 import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
-import { authoringRulesForType } from "../../core/authoring-rules.js";
+import { authoringRulesForType, DESCRIPTION_MAX_CHARS, DESCRIPTION_MIN_CHARS, requiresDescription, } from "../../core/authoring-rules.js";
 import { parseEmbeddedJsonResponse, stripCodeFences, stripThinkBlocks } from "../../core/parse.js";
 /**
  * Per-asset-type frontmatter / authoring hints surfaced in the prompt so
@@ -111,6 +111,30 @@ export function extractDraftConfidence(stdout) {
         return undefined;
     return value;
 }
+/**
+ * Whether the source asset content has a non-empty `description:` key in its
+ * YAML frontmatter. Used by {@link buildReflectPrompt} (#636) to decide whether
+ * to inject the synthesize-a-description instruction. Uses an inline regex to
+ * avoid pulling the full YAML parser into the prompt module (mirrors the
+ * existing inline frontmatter handling here).
+ */
+function sourceHasNonEmptyDescription(assetContent) {
+    if (!assetContent)
+        return false;
+    const fmMatch = assetContent.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    if (!fmMatch)
+        return false;
+    const fmBlock = fmMatch[1] ?? "";
+    // Match a top-level `description:` line and capture its inline value.
+    const descMatch = fmBlock.match(/^description\s*:\s*(.*)$/m);
+    if (!descMatch)
+        return false;
+    const value = (descMatch[1] ?? "")
+        .trim()
+        .replace(/^['"]|['"]$/g, "")
+        .trim();
+    return value.length > 0;
+}
 /**
  * Build the prompt for `akm reflect [ref]`. Asks the agent to review an
  * existing asset (plus any negative feedback / lint findings) and propose
@@ -167,6 +191,23 @@ export function buildReflectPrompt(input) {
         if (authoringRules) {
             sections.push(authoringRules);
         }
+        // #636 — synthesize-a-description instruction. Many source assets (notably
+        // scraped docs: `source`/`title`/`scraped`) carry frontmatter but NO
+        // `description`. Reflect echoes the source frontmatter, so the proposal
+        // inherits the missing description and the promote-time validator
+        // (isValidDescription, 20–400 chars) rejects it. The fix is at GENERATION
+        // time: when the source lacks a non-empty `description` and the type
+        // requires one, tell the model — unmissably — that it MUST author a valid
+        // `description`. (The validator/promote path is NOT changed: it must never
+        // fabricate content to pass itself.)
+        if (resolvedType && requiresDescription(resolvedType) && !sourceHasNonEmptyDescription(input.assetContent)) {
+            sections.push([
+                "REQUIRED — synthesize a `description` (the source asset has none):",
+                `- The source frontmatter does NOT include a non-empty \`description\`, but a ${resolvedType} asset REQUIRES one or the proposal will be rejected at promote time.`,
+                `- You MUST author a valid \`description\` in the proposal frontmatter: ${DESCRIPTION_MIN_CHARS}–${DESCRIPTION_MAX_CHARS} characters of plain-prose sentence summarizing what this asset is about.`,
+                '- Synthesize it from the asset\'s `title:` frontmatter, its first `# Heading`, or the opening body sentence. Do NOT copy a bare heading fragment (e.g. "Overview", "Named Page", "Key Insight") and do NOT emit a truncated phrase that ends on `:`/`;`/`,` or a hanging connector word.',
+            ].join("\n"));
+        }
     }
     if (input.assetContent?.trim()) {
         // Cap at 12 000 chars to stay well under OS ARG_MAX when the prompt is

package/dist/scripts/migrate-storage.js

@@ -9520,7 +9520,46 @@ function getRecombineHypothesis(db, hypothesisRef) {
 function markRecombineHypothesisPromoted(db, hypothesisRef, promotedAt) {
   db.prepare("UPDATE recombine_hypotheses SET promoted_at = ?, consecutive_count = 0 WHERE hypothesis_ref = ?").run(promotedAt, hypothesisRef);
 }
-function decayUnseenRecombineHypotheses(db, currentRun, seenRefs) {
+function hypothesisMatchesAnyPresentCluster(row, presentClusters, minOverlap) {
+  const rowMembers = row.member_key.split("|").filter((m) => m.length > 0);
+  if (rowMembers.length === 0)
+    return false;
+  const rowSet = new Set(rowMembers);
+  for (const cluster of presentClusters) {
+    if (cluster.signature !== row.signature)
+      continue;
+    const clusterMembers = cluster.memberKey.split("|").filter((m) => m.length > 0);
+    if (clusterMembers.length === 0)
+      continue;
+    let intersection = 0;
+    for (const m of clusterMembers) {
+      if (rowSet.has(m))
+        intersection += 1;
+    }
+    const union = rowSet.size + clusterMembers.length - intersection;
+    const overlap = union === 0 ? 0 : intersection / union;
+    if (overlap >= minOverlap)
+      return true;
+  }
+  return false;
+}
+function decayUnseenRecombineHypotheses(db, currentRun, seenRefs, opts) {
+  let effectiveSeen = seenRefs;
+  if (opts && opts.presentClusters.length > 0) {
+    const candidates = db.prepare("SELECT hypothesis_ref, signature, member_key FROM recombine_hypotheses WHERE promoted_at IS NULL AND (last_run IS NULL OR last_run != ?) AND consecutive_count != 0").all(currentRun);
+    const seenSet = new Set(seenRefs);
+    for (const row of candidates) {
+      if (seenSet.has(row.hypothesis_ref))
+        continue;
+      if (hypothesisMatchesAnyPresentCluster(row, opts.presentClusters, opts.minOverlap)) {
+        seenSet.add(row.hypothesis_ref);
+      }
+    }
+    effectiveSeen = [...seenSet];
+  }
+  return decayUnseenRecombineHypothesesInner(db, currentRun, effectiveSeen);
+}
+function decayUnseenRecombineHypothesesInner(db, currentRun, seenRefs) {
   if (seenRefs.length === 0) {
     const res2 = db.prepare("UPDATE recombine_hypotheses SET consecutive_count = 0 WHERE promoted_at IS NULL AND (last_run IS NULL OR last_run != ?) AND consecutive_count != 0").run(currentRun);
     return Number(res2.changes);

package/dist/sources/providers/git.js

@@ -479,28 +479,32 @@ export function saveGitStash(name, message, writableOverride, options) {
     if (!statusResult.stdout.trim()) {
         return { committed: false, pushed: false, skipped: false, output: "nothing to commit, working tree clean" };
     }
-    // Safety check (#476): when the stash dir is shared with a non-akm project
-    // (stash root == project repo root), `git add -A` would stage every dirty
-    // file in the user's working tree and push their unrelated WIP to the
-    // stash's remote. Refuse if any dirty path is outside the known akm-
-    // managed subtrees (TYPE_DIRS + `.akm/` state).
-    const nonAkmDirty = collectNonAkmDirtyPaths(statusResult.stdout);
-    if (nonAkmDirty.length > 0) {
-        const sample = nonAkmDirty.slice(0, 10);
-        const more = nonAkmDirty.length > sample.length ? `\n  ...and ${nonAkmDirty.length - sample.length} more` : "";
-        throw new Error(`refusing to push: stash repo at ${repoDir} has uncommitted non-akm changes:\n` +
-            sample.map((p) => `  ${p}`).join("\n") +
-            more +
-            `\nCommit or stash these manually before running an akm push. ` +
-            `Akm-managed paths are: ${Object.values(TYPE_DIRS).join(", ")}, .akm/`);
-    }
-    // Stage and commit — supply fallback identity so fresh environments without
+    // Scoped staging (#476 + the auto-sync incident): NEVER refuse akm's commit
+    // because unrelated non-akm files exist in the working tree. When the stash
+    // dir is shared with a non-akm project (stash root == project repo root), a
+    // blunt `git add -A` would sweep the user's unrelated WIP into the stash's
+    // remote. We avoid that by SCOPING what we stage, not by refusing the commit.
+    //
+    // Precedence:
+    //   1. Explicit modified-file list (`options.paths`) — stage exactly those.
+    //   2. Managed pathspecs (TYPE_DIRS values + `.akm`) that exist on disk —
+    //      stages everything akm owns and, by construction, never stages non-akm
+    //      WIP. This preserves the #476 protection WITHOUT refusing.
+    //   3. Last-resort `git add -A` — ONLY when neither an explicit list nor any
+    //      managed pathspec can be resolved. This is the maintainer-approved
+    //      "or all files if we cannot determine the exact file list" fallback and
+    //      is the one (rare) path that could include unrelated non-akm files.
+    if (!stageScopedChanges(repoDir, options?.paths)) {
+        throw new Error(`git add failed while staging akm changes in ${repoDir}`);
+    }
+    // Nothing actually staged → don't create an empty commit. This happens when
+    // only non-akm files were dirty (precedence 2 staged nothing).
+    const stagedResult = runGit(["-C", repoDir, "diff", "--cached", "--quiet"]);
+    if (stagedResult.status === 0) {
+        return { committed: false, pushed: false, skipped: false, output: "nothing to commit" };
+    }
+    // Commit — supply fallback identity so fresh environments without
     // user.name/user.email configured can always commit to the default stash.
-    // `add -A` is safe here because nonAkmDirty was just verified empty.
-    const addResult = runGit(["-C", repoDir, "add", "-A"]);
-    if (addResult.status !== 0) {
-        throw new Error(`git add failed: ${addResult.stderr?.trim() || "unknown error"}`);
-    }
     const commitResult = runGit([
         "-C",
         repoDir,
@@ -535,6 +539,51 @@ export function saveGitStash(name, message, writableOverride, options) {
         output: (commitResult.stdout + pushResult.stdout).trim() || "changes committed and pushed",
     };
 }
+/**
+ * Stage akm's changes in `repoDir` using the scoped-staging precedence
+ * documented at the call site (#476). Returns `false` only when a `git add`
+ * subprocess fails; returns `true` otherwise (including when nothing matched —
+ * the caller then detects "nothing staged" via `git diff --cached --quiet`).
+ *
+ * @param paths Optional explicit repo-relative paths akm wrote this run. When
+ *   provided and non-empty, exactly those are staged (chunked to stay under
+ *   argv length limits). Otherwise we fall back to the managed pathspecs, and
+ *   finally to `git add -A` only if no managed pathspec exists on disk.
+ */
+function stageScopedChanges(repoDir, paths) {
+    // Precedence 1: explicit modified-file list.
+    const explicit = (paths ?? []).filter((p) => typeof p === "string" && p.length > 0);
+    if (explicit.length > 0) {
+        return addPathspecsChunked(repoDir, explicit);
+    }
+    // Precedence 2: managed pathspecs that exist on disk (TYPE_DIRS + `.akm`).
+    const managed = [...Object.values(TYPE_DIRS), ".akm"].filter((dir) => fs.existsSync(path.join(repoDir, dir)));
+    if (managed.length > 0) {
+        return addPathspecsChunked(repoDir, managed);
+    }
+    // Precedence 3 (last resort): nothing akm-managed resolved on disk. Stage
+    // everything. This is the ONLY branch that can include unrelated non-akm
+    // files — it is the explicit, maintainer-approved "or all files if we cannot
+    // determine the exact file list" fallback and should be rare/never in
+    // practice (a git-backed stash always has at least one managed subtree once
+    // akm has written to it).
+    const addAll = runGit(["-C", repoDir, "add", "-A"]);
+    return addAll.status === 0;
+}
+/**
+ * Run `git add -- <pathspec>...` in chunks so a very large path list never
+ * exceeds the OS argv-length limit. Each chunk must succeed.
+ */
+function addPathspecsChunked(repoDir, pathspecs) {
+    const CHUNK = 500;
+    for (let i = 0; i < pathspecs.length; i += CHUNK) {
+        const chunk = pathspecs.slice(i, i + CHUNK);
+        const result = runGit(["-C", repoDir, "add", "--", ...chunk]);
+        if (result.status !== 0)
+            return false;
+    }
+    return true;
+}
 function findGitStashByTarget(stashes, target) {
     return stashes.find((stash) => matchesGitStashTarget(stash, target));
 }
@@ -620,45 +669,6 @@ export function classifyCloneFailure(url, stderr, spawnError) {
     const detail = raw || spawnMsg || "unknown error";
     return `Failed to clone ${url}: ${detail}`;
 }
-// ── Stash-safety helpers (#476) ──────────────────────────────────────────────
-/**
- * Inspect `git status --porcelain` output and return every dirty path that is
- * NOT inside an akm-managed subtree. Used by `runUpstreamPush` to refuse
- * pushing unrelated WIP when a writable stash shares its root with a project
- * repo.
- *
- * Porcelain v1 format: `XY <path>` or `XY <orig> -> <new>` for renames. We
- * key off the post-rename path (or the only path) — that is the working-tree
- * file at risk of being staged by `git add -A`.
- */
-function collectNonAkmDirtyPaths(porcelainOutput) {
-    const akmDirs = new Set(Object.values(TYPE_DIRS));
-    const result = [];
-    for (const rawLine of porcelainOutput.split("\n")) {
-        const line = rawLine.replace(/\r$/, "");
-        if (line.length === 0)
-            continue;
-        // Skip the 2-char status code + 1 space.
-        let p = line.length > 3 ? line.slice(3) : "";
-        // Renames / copies: `from -> to`. Stage decision applies to `to`.
-        const arrow = p.lastIndexOf(" -> ");
-        if (arrow !== -1) {
-            p = p.slice(arrow + 4);
-        }
-        // Strip surrounding quotes for paths with special chars.
-        if (p.startsWith('"') && p.endsWith('"') && p.length >= 2) {
-            p = p.slice(1, -1);
-        }
-        if (!p)
-            continue;
-        const segments = p.split("/");
-        const top = segments[0];
-        if (top === ".akm" || akmDirs.has(top))
-            continue;
-        result.push(p);
-    }
-    return result;
-}
 // ── Exports ─────────────────────────────────────────────────────────────────
-export { collectNonAkmDirtyPaths, ensureGitMirror, GitSourceProvider, getCachePaths, parseGitRepoUrl };
+export { ensureGitMirror, GitSourceProvider, getCachePaths, parseGitRepoUrl };
 // resolveWritableOverride is exported at its declaration above.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.0-beta.40",
+  "version": "0.9.0-beta.42",
   "type": "module",
   "description": "akm (Agent Knowledge Management) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [