akm-cli 0.9.0-beta.41 → 0.9.0-beta.43

package/CHANGELOG.md

@@ -8,6 +8,69 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### 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

package/dist/assets/stash-skeleton/facts/conventions/assets/agent.md

@@ -1,22 +1,38 @@
 ---
 category: convention
-description: Starter SOFT authoring conventions for agent assets — edit to taste.
+description: Soft authoring conventions for agent assets using scoped role, tool, and maintenance rules.
 when_to_use: Surfaced to authoring agents when they write or revise an agent asset.
 ---
 
 <!--
   SOFT guidance only — advice, not a contract. Nothing here is enforced by the
-  proposal gate; the validator-rejecting HARD rules live in
-  src/core/authoring-rules.ts (#645) and remain the sole enforced source. Editing
-  or deleting this file cannot weaken the gate.
+  proposal gate; validator-rejecting HARD rules live in src/core/authoring-rules.ts
+  and remain the sole enforced source. Editing or deleting this file cannot weaken
+  the gate. Tune the guidance below to match how your stash wants this asset type
+  maintained.
 -->
 
 # Agent authoring conventions
 
-An agent is markdown whose frontmatter describes a reusable role.
+An agent asset defines a reusable role. Treat it like a disciplined maintainer, not a generic personality. Its job is to know its scope, read the right rulebooks, use the right tools, and leave the stash in better shape.
 
-- Frontmatter typically carries `name`, `description`, and optionally `tools` and
-  `model`. Write the `description` so a dispatcher knows exactly when to delegate.
-- The body is the system prompt: establish the role, its scope, and its boundaries.
-- Be explicit about what the agent should and should not do, and what it returns.
-- Prefer a focused single-responsibility persona over a broad do-everything agent.
+## Purpose
+
+Use an agent when a recurring task benefits from a specialized role, bounded responsibilities, and explicit tool behavior.
+
+## Authoring strategy
+
+- Write the description so a dispatcher knows exactly when to delegate to this agent.
+- Define the agent’s domain, authority, boundaries, and expected output.
+- Specify what the agent must read first: relevant stash standards, type conventions, reference docs, source files, or prior lessons.
+- State tool expectations plainly: what tools it may use, what it should avoid, and when it must ask for human review.
+- Give the agent maintenance duties when appropriate: update cross-references, append logs, preserve provenance, and surface contradictions.
+- Prefer a narrow role that does one thing reliably over a broad do-everything persona.
+- Include handoff behavior: what the agent should return when it cannot complete the task safely.
+
+## Maintenance strategy
+
+- Refine the agent when repeated sessions show the same delegation failure.
+- Add explicit negative guidance when the agent overreaches.
+- Keep role instructions stable and concise; move large background material into knowledge assets.
+- Use lessons to capture operational improvements, then promote stable ones into the agent when they become part of the role.

package/dist/assets/stash-skeleton/facts/conventions/assets/command.md

@@ -1,22 +1,38 @@
 ---
 category: convention
-description: Starter SOFT authoring conventions for command assets — edit to taste.
+description: Soft authoring conventions for command assets using repeatable LLM operation patterns.
 when_to_use: Surfaced to authoring agents when they write or revise a command asset.
 ---
 
 <!--
   SOFT guidance only — advice, not a contract. Nothing here is enforced by the
-  proposal gate; the validator-rejecting HARD rules live in
-  src/core/authoring-rules.ts (#645) and remain the sole enforced source. Editing
-  or deleting this file cannot weaken the gate.
+  proposal gate; validator-rejecting HARD rules live in src/core/authoring-rules.ts
+  and remain the sole enforced source. Editing or deleting this file cannot weaken
+  the gate. Tune the guidance below to match how your stash wants this asset type
+  maintained.
 -->
 
 # Command authoring conventions
 
-A command is a markdown prompt template the user invokes by name.
+A command is a reusable markdown prompt template invoked by name. Treat it like an operation in the stash: every vague instruction will compound into repeated vague output.
 
-- Optional frontmatter carries `name` and `description`; the body *is* the prompt.
-- Write the body as the instruction you want the model to follow when invoked.
-- State the task, the expected inputs, and the shape of the desired output up front.
-- Keep it tight and unambiguous — a command is run repeatedly, so vagueness compounds.
-- Use clear placeholders for any arguments the caller will supply.
+## Purpose
+
+Use a command when the user or agent needs to perform the same prompt-shaped task repeatedly with different arguments or context.
+
+## Authoring strategy
+
+- Put the task, inputs, constraints, and expected output shape near the top.
+- Make argument placeholders obvious and describe what each one should contain.
+- Tell the model what to inspect before acting, especially relevant stash assets, facts, standards, or reference docs.
+- State the decision boundary: what the command should do directly, what it should only propose, and what it should refuse or defer.
+- Include output requirements that are stable across runs.
+- Keep the prompt tight. A command should be easy to invoke and hard to misinterpret.
+- Avoid embedding one-time project details unless the command is intentionally project-specific.
+
+## Maintenance strategy
+
+- If users repeatedly clarify the same missing detail, add that detail to the command.
+- If command output regularly becomes useful durable knowledge, instruct the agent to file the result into the right asset type.
+- If the command starts handling multiple unrelated tasks, split it into smaller commands.
+- Preserve a clear invocation contract so future agents can call the command safely.

package/dist/assets/stash-skeleton/facts/conventions/assets/fact.md

@@ -1,24 +1,39 @@
 ---
 category: convention
-description: Starter SOFT authoring conventions for fact assets — edit to taste.
+description: Soft authoring conventions for fact assets using pinned-core and just-in-time context principles.
 when_to_use: Surfaced to authoring agents when they write or revise a fact asset.
 ---
 
 <!--
   SOFT guidance only — advice, not a contract. Nothing here is enforced by the
-  proposal gate; the validator-rejecting HARD rules live in
-  src/core/authoring-rules.ts (#645) and remain the sole enforced source. Editing
-  or deleting this file cannot weaken the gate.
+  proposal gate; validator-rejecting HARD rules live in src/core/authoring-rules.ts
+  and remain the sole enforced source. Editing or deleting this file cannot weaken
+  the gate. Tune the guidance below to match how your stash wants this asset type
+  maintained.
 -->
 
 # Fact authoring conventions
 
-A fact is durable stash-level context — personal, team, or project details,
-coding conventions, or stash-meta.
+A fact is durable stash-level context: personal, team, project, convention, or meta knowledge. Treat facts as the stash’s semantic layer — selectively loaded context that should guide future work without bloating every prompt.
 
-- Frontmatter should include a `description` and a `category`
-  (personal | team | project | convention | meta).
-- Set `pinned: true` only for the small always-injected core; most facts stay unpinned.
-- Keep each fact short, high-signal, and self-contained — it is durable context,
-  not an episodic note.
-- Write it as a standing declaration that stays true across sessions.
+## Purpose
+
+Use a fact for stable information that future agents should treat as true or normative: user preferences, project identity, team stack, architecture principles, naming conventions, tag vocabulary, or stash organization.
+
+## Authoring strategy
+
+- Write each fact as a standing declaration that can survive across sessions.
+- Keep it short, high-signal, and self-contained.
+- Choose the narrowest useful category: personal, team, project, convention, or meta.
+- Use `pinned: true` only for the small core that should be available constantly.
+- Leave most facts unpinned so they can be retrieved just-in-time.
+- Include scope and provenance when a fact is project-specific, inferred, or subject to change.
+- Separate facts from memories: memories preserve observations; facts state durable truth or durable policy.
+- Separate facts from knowledge: knowledge explains a topic; facts declare compact context.
+
+## Maintenance strategy
+
+- Revise or supersede facts when the durable truth changes.
+- Do not allow contradictory facts to remain equally active.
+- Promote repeated memories or lessons into facts only when they become stable context.
+- Keep convention and meta facts especially clear, because they steer future asset creation.

package/dist/assets/stash-skeleton/facts/conventions/assets/knowledge.md

@@ -1,22 +1,40 @@
 ---
 category: convention
-description: Starter SOFT authoring conventions for knowledge assets — edit to taste.
+description: Soft authoring conventions for knowledge assets as compiled, on-demand reference documents.
 when_to_use: Surfaced to authoring agents when they write or revise a knowledge asset.
 ---
 
 <!--
   SOFT guidance only — advice, not a contract. Nothing here is enforced by the
-  proposal gate; the validator-rejecting HARD rules live in
-  src/core/authoring-rules.ts (#645) and remain the sole enforced source. Editing
-  or deleting this file cannot weaken the gate.
+  proposal gate; validator-rejecting HARD rules live in src/core/authoring-rules.ts
+  and remain the sole enforced source. Editing or deleting this file cannot weaken
+  the gate. Tune the guidance below to match how your stash wants this asset type
+  maintained.
 -->
 
 # Knowledge authoring conventions
 
-A knowledge asset is a reference document meant to be read on demand.
+A knowledge asset is a compiled reference document meant to be read on demand. Treat it as the synthesized layer above raw material: not source files, not chat residue, but integrated, navigable understanding that saves future agents from rediscovering the same material.
 
-- Open with a top-level `# Title` that names the subject plainly.
-- Organise into concise, well-headed sections so a reader can jump to what they need.
-- Favour accuracy and clarity over completeness; link or cross-reference rather than
-  duplicating other assets.
-- Voice: explanatory and neutral, written to be re-read months later.
+## Purpose
+
+Use a knowledge asset for durable reference material, synthesized explanations, design notes, comparisons, and project context that is broader than a single memory but less procedural than a skill.
+
+## Authoring strategy
+
+- Open with a plain top-level title that names the subject.
+- Add a concise orientation paragraph: what this document covers and when it should be read.
+- For a long reference, add a table of contents near the top so the full scope is visible even on a partial read.
+- Organize by stable concepts, decisions, entities, or questions — roughly one page per concept.
+- Cross-reference related assets instead of duplicating them, so a navigable graph forms over time.
+- Preserve provenance where it matters: cite source files, raw notes, session logs, or issues by path/ref.
+- Call out contradictions, uncertainty, stale claims, and open questions explicitly.
+- Prefer accurate synthesis over exhaustive dumping. Raw material belongs elsewhere; this file is the compiled layer.
+- Use tables or checklists when they make retrieval and comparison easier.
+
+## Maintenance strategy
+
+- Update the existing page when new information changes the same topic; append a dated note rather than silently rewriting when provenance matters.
+- Create a new page when the concept deserves its own durable entry.
+- Add links both ways when a new relationship matters.
+- Periodically scan for orphaned, stale, or overlapping knowledge docs and consolidate them.

package/dist/assets/stash-skeleton/facts/conventions/assets/lesson.md

@@ -1,25 +1,43 @@
 ---
 category: convention
-description: Starter SOFT authoring conventions for lesson assets — edit to taste.
+description: Soft authoring conventions for lesson assets that capture compounding, hard-won judgment.
 when_to_use: Surfaced to authoring agents when they write or revise a lesson asset.
 ---
 
 <!--
   SOFT guidance only — advice, not a contract. Nothing here is enforced by the
-  proposal gate; the validator-rejecting HARD rules live in
-  src/core/authoring-rules.ts (#645) and remain the sole enforced source. Editing
-  or deleting this file cannot weaken the gate. Tune the guidance below to match
-  how your stash likes lessons written.
+  proposal gate; validator-rejecting HARD rules live in src/core/authoring-rules.ts
+  and remain the sole enforced source. Editing or deleting this file cannot weaken
+  the gate. Tune the guidance below to match how your stash wants this asset type
+  maintained.
 -->
 
 # Lesson authoring conventions
 
-A lesson captures durable, hard-won judgement about *when* to reach for something
-and *what goes wrong without it* — it is not a restatement of the source asset.
+A lesson captures durable, hard-won judgment that should compound across future agent sessions. Treat it as distilled judgment about how to act: it should preserve the extracted meaning of what real use revealed, not merely recount an incident or summarize another asset.
 
-- Lead with the trigger: when should a reader reach for this lesson?
-- Then the failure mode: what breaks, or what gets missed, without it?
-- Then the insight: what did real use reveal that the asset itself does not say?
-- Keep it to one to three short, concrete paragraphs. Prefer specifics over
-  general advice; a lesson earns its keep by being actionable in a real moment.
-- Voice: direct and practical, written for a future agent mid-task.
+## Purpose
+
+Use a lesson to record:
+
+- when to reach for a pattern, asset, or decision;
+- what tends to go wrong without it;
+- what evidence, feedback, or repeated experience made the lesson worth keeping;
+- how a future agent should act differently because this lesson exists.
+
+## Authoring strategy
+
+- Lead with the trigger: the concrete situation where this lesson should be loaded.
+- Follow with the failure mode: what mistake, omission, or confusion this prevents.
+- End with the reusable judgment: the practical rule a future agent can apply.
+- Keep the scope narrow. A lesson should teach one durable behavior.
+- Prefer observed evidence over generic advice. Mention the kind of signal that produced the lesson, such as rejected proposals, repeated lint findings, user feedback, or session outcomes.
+- Do not restate the source asset. Lessons are compiled judgment, not copied documentation.
+- Write for a future agent mid-task: direct, practical, and easy to apply.
+
+## Maintenance strategy
+
+- Update an existing lesson when new feedback sharpens the same judgment.
+- Create a new lesson only when the trigger or failure mode is meaningfully different.
+- Deprecate or revise stale lessons instead of allowing contradictory guidance to accumulate.
+- When a lesson becomes broadly normative, consider promoting the stable rule into a `fact:conventions/...` asset.

package/dist/assets/stash-skeleton/facts/conventions/assets/memory.md

@@ -1,21 +1,38 @@
 ---
 category: convention
-description: Starter SOFT authoring conventions for memory assets — edit to taste.
+description: Soft authoring conventions for memory assets using durable-context and provenance discipline.
 when_to_use: Surfaced to authoring agents when they write or revise a memory asset.
 ---
 
 <!--
   SOFT guidance only — advice, not a contract. Nothing here is enforced by the
-  proposal gate; the validator-rejecting HARD rules live in
-  src/core/authoring-rules.ts (#645) and remain the sole enforced source. Editing
-  or deleting this file cannot weaken the gate.
+  proposal gate; validator-rejecting HARD rules live in src/core/authoring-rules.ts
+  and remain the sole enforced source. Editing or deleting this file cannot weaken
+  the gate. Tune the guidance below to match how your stash wants this asset type
+  maintained.
 -->
 
 # Memory authoring conventions
 
-A memory is a short factual note the user wants persisted across sessions.
+A memory is a short, durable note that should survive beyond the current session. Treat it as a small compiled fact or decision, not a transcript fragment.
 
-- Frontmatter usually includes a `description` that states the fact in one line.
-- Keep the body brief and self-contained — one durable fact or decision per memory.
-- Write it so it still reads clearly with no surrounding conversation for context.
-- Prefer durable, reusable facts over episodic play-by-play of a single session.
+## Purpose
+
+Use a memory when a future agent would make a better decision by knowing a specific user preference, project decision, environmental fact, constraint, or observed outcome.
+
+## Authoring strategy
+
+- Record one durable fact, decision, or constraint per memory.
+- Write it so it stands alone without the original conversation.
+- Include enough context to prevent misapplication: subject, scope, and when it matters.
+- Prefer stable, reusable information over step-by-step session play-by-play.
+- Mark uncertainty or subjectivity clearly when the memory is not a settled fact.
+- Preserve source/provenance in frontmatter or body when the memory came from a session, log, user statement, or derived inference.
+- Avoid storing secrets, private tokens, or volatile temporary state as memory.
+
+## Maintenance strategy
+
+- Update or supersede memories when newer evidence changes the truth.
+- Consolidate repeated memories into a clearer fact or knowledge asset.
+- Convert broad, stable conventions into `fact` assets.
+- Archive memories that are no longer current rather than letting stale context keep influencing agents.

package/dist/assets/stash-skeleton/facts/conventions/assets/script.md

@@ -1,21 +1,43 @@
 ---
 category: convention
-description: Starter SOFT authoring conventions for script assets — edit to taste.
+description: Soft authoring conventions for script assets using agent-safe CLI helper principles.
 when_to_use: Surfaced to authoring agents when they write or revise a script asset.
 ---
 
 <!--
   SOFT guidance only — advice, not a contract. Nothing here is enforced by the
-  proposal gate; the validator-rejecting HARD rules live in
-  src/core/authoring-rules.ts (#645) and remain the sole enforced source. Editing
-  or deleting this file cannot weaken the gate.
+  proposal gate; validator-rejecting HARD rules live in src/core/authoring-rules.ts
+  and remain the sole enforced source. Editing or deleting this file cannot weaken
+  the gate. Tune the guidance below to match how your stash wants this asset type
+  maintained.
 -->
 
 # Script authoring conventions
 
-A script is an executable text file stored as-is and run on demand.
+A script is an executable helper that an agent or human can run on demand. Treat it like a small, deterministic tool that reduces manual bookkeeping and makes repeatable operations safer.
 
-- Start with a shebang appropriate to the interpreter (e.g. `#!/usr/bin/env bash`).
-- Follow it with a short usage comment: what the script does and how to invoke it.
-- Keep the script focused on one job; fail loudly and early on bad input.
-- Prefer readable, well-commented logic over cleverness — these get re-run by others.
+## Purpose
+
+Use a script when a task is mechanical, repeatable, and better handled by a deterministic program than by free-form agent edits.
+
+## Authoring strategy
+
+- Start with the appropriate interpreter line and a short usage comment.
+- State what the script does, expected inputs, outputs, side effects, and failure behavior.
+- Keep one script focused on one job.
+- Validate inputs before mutation.
+- Fail loudly and early on unsafe or ambiguous input.
+- Declare required dependencies and assumptions explicitly rather than assuming a tool is installed.
+- Justify any non-obvious constant (timeout, retry count, limit) in a comment so a future reader can adjust it safely.
+- Prefer idempotent behavior where practical.
+- Avoid hidden network calls, destructive defaults, or silent writes.
+- Never print secrets or sensitive values.
+- Write output that is easy for both humans and agents to parse.
+- Favor clear names, straightforward control flow, and comments at decision points.
+
+## Maintenance strategy
+
+- Add examples when agents or users repeatedly invoke the script incorrectly.
+- Keep dangerous actions behind explicit flags.
+- When a script becomes a core operation, add or update a workflow that explains when to run it.
+- If the script encodes a convention, also document that convention in a fact or knowledge asset.

package/dist/assets/stash-skeleton/facts/conventions/assets/skill.md

@@ -1,23 +1,40 @@
 ---
 category: convention
-description: Starter SOFT authoring conventions for skill assets — edit to taste.
+description: Soft authoring conventions for skill assets as reusable, just-in-time procedural rulebooks.
 when_to_use: Surfaced to authoring agents when they write or revise a skill asset.
 ---
 
 <!--
   SOFT guidance only — advice, not a contract. Nothing here is enforced by the
-  proposal gate; the validator-rejecting HARD rules live in
-  src/core/authoring-rules.ts (#645) and remain the sole enforced source. Editing
-  or deleting this file cannot weaken the gate.
+  proposal gate; validator-rejecting HARD rules live in src/core/authoring-rules.ts
+  and remain the sole enforced source. Editing or deleting this file cannot weaken
+  the gate. Tune the guidance below to match how your stash wants this asset type
+  maintained.
 -->
 
 # Skill authoring conventions
 
-A skill is a reusable, self-contained capability stored as `skills/<name>/SKILL.md`.
+A skill is a reusable, self-contained capability stored as `skills/<name>/SKILL.md`. Treat it like a compact operating manual that an agent can load just-in-time, follow without rediscovering the process, and improve when repeated use exposes gaps.
 
-- Frontmatter usually carries `name`, `description`, and `when_to_use`. Write the
-  `description` so a dispatcher can decide *from it alone* whether to load the skill.
-- Open the body with the goal in an imperative voice ("Generate…", "Review…").
-- Structure as: purpose, when to use, then the procedure or guidance as ordered
-  steps or short sections. Favour scannable headings over long prose.
-- Keep it focused on one capability; split unrelated concerns into separate skills.
+## Purpose
+
+Use a skill when the stash needs reusable procedural guidance for a recurring class of work. A good skill reduces repeated reasoning cost: future agents should not have to reconstruct the same method from raw context.
+
+## Authoring strategy
+
+- Make the dispatch signal clear. The description should let a dispatcher decide whether to load the skill without reading the whole body.
+- Open with the outcome the skill helps produce.
+- State when to use it, when not to use it, and what inputs the agent should gather before acting.
+- Structure the body as a rulebook: principles first, then procedure, then checks.
+- Use short sections and ordered steps where sequence matters.
+- Match the level of detail to how fragile the task is: open-ended work gets high-level heuristics and room to reason, while fragile or consistency-critical steps get exact, unambiguous instructions.
+- Keep the body lean and move bulky background into companion knowledge docs referenced one level deep, so the skill loads cheaply and stays scannable.
+- Include failure modes and verification steps. A skill should tell the agent how to know the work is complete.
+- Keep one skill focused on one capability. Split unrelated concerns into separate skills and cross-reference them.
+
+## Maintenance strategy
+
+- Update the skill when session logs, feedback, or rejected proposals reveal repeatable confusion.
+- Add companion knowledge docs when the skill needs background material that would bloat the main procedure.
+- Promote durable recurring corrections into the skill; leave one-off observations in memories or lessons.
+- Prefer small edits that preserve the skill’s operational shape over broad rewrites that erase tested guidance.

package/dist/assets/stash-skeleton/facts/conventions/assets/workflow.md

@@ -1,22 +1,43 @@
 ---
 category: convention
-description: Starter SOFT authoring conventions for workflow assets — edit to taste.
+description: Soft authoring conventions for workflow assets using explicit operations, logging, and lintable steps.
 when_to_use: Surfaced to authoring agents when they write or revise a workflow asset.
 ---
 
 <!--
   SOFT guidance only — advice, not a contract. Nothing here is enforced by the
-  proposal gate; the validator-rejecting HARD rules live in
-  src/core/authoring-rules.ts (#645) and remain the sole enforced source. Editing
-  or deleting this file cannot weaken the gate.
+  proposal gate; validator-rejecting HARD rules live in src/core/authoring-rules.ts
+  and remain the sole enforced source. Editing or deleting this file cannot weaken
+  the gate. Tune the guidance below to match how your stash wants this asset type
+  maintained.
 -->
 
 # Workflow authoring conventions
 
-A workflow describes a multi-step process an agent or human follows in order.
+A workflow describes an ordered process an agent or human can follow. Treat it as the operation layer of a maintained stash: clear steps, clear state, clear completion criteria, and enough bookkeeping to resume safely.
 
-- Open with a top-level `# <Title>` naming the workflow's outcome.
-- Lay out the steps as ordered `## Step N` sections, each with a clear action.
-- For each step, state what to do, what it depends on, and how to know it is done.
-- Keep steps atomic and resumable — a reader should be able to stop and pick up midway.
-- Note any branch points or preconditions explicitly rather than burying them in prose.
+## Purpose
+
+Use a workflow when the task requires multiple steps, branching decisions, repeated checks, or durable progress tracking.
+
+## Authoring strategy
+
+- Open with the outcome the workflow produces.
+- State prerequisites, required inputs, and tools before the steps.
+- Use ordered step sections when sequence matters.
+- For each step, specify:
+  - what to do;
+  - what evidence or input it depends on;
+  - what output it produces;
+  - how to know the step is done.
+- Make branch points explicit. Do not bury conditional behavior in prose.
+- Include validation, lint, or review steps near the end.
+- Include rollback or recovery notes when the workflow mutates files, state, repos, or external systems.
+- Keep steps atomic and resumable so an interrupted run can continue without guessing.
+
+## Maintenance strategy
+
+- Update the workflow when repeated execution reveals missing checks or unclear handoffs.
+- Add logging expectations when the workflow creates durable state.
+- Extract reusable sub-procedures into skills or scripts when the workflow grows too broad.
+- Record recurring mistakes as lessons, then fold stable corrections back into the workflow.

package/dist/commands/improve/improve.js

@@ -964,6 +964,63 @@ export async function akmImprove(options = {}) {
     // #576: clears the per-run LLM usage sink. Defaults to a no-op until the sink
     // is installed inside the try; the `finally` always calls it.
     let disposeLlmUsageSink = () => { };
+    // ── Crash-safe / incremental stash sync (#662) ──────────────────────────────
+    // The primary stash writes as a filesystem source DURING the run
+    // (write-source.ts case-3); those writes become a git commit only when this
+    // closure runs. Historically the only call site was a single BATCH commit at
+    // the very end of the happy path, so a run interrupted AFTER writing but
+    // BEFORE finishing — a mid-cycle crash, a budget abort, or an external
+    // SIGTERM/`process.exit` — left every write uncommitted until some LATER run
+    // happened to finish cleanly and swept the whole backlog up. We now call this
+    // from THREE places: between cycles (bank each completed cycle), at end-of-run
+    // (the converged commit), and from the catch path (commit what was written
+    // before the crash). That shrinks the worst-case loss from "the entire run" to
+    // "the in-flight cycle".
+    //
+    // Declared in the OUTER scope (not inside the try) so the catch block can reach
+    // it. Idempotent + NON-FATAL: `saveGitStash` short-circuits a clean working
+    // tree ("nothing to commit") and a thrown sync error is swallowed here, so a
+    // repeat call after a no-op cycle is cheap and a failed push never fails the
+    // run. Gated identically to the original end-of-run block (git-backed primary
+    // stash, sync not disabled). `eventsCtx` is captured by reference, so calls
+    // after the db-backed context is installed inside the try use the live handle.
+    const effectiveSync = { ...improveProfile.sync, ...options.sync };
+    const commitStashBatch = (messageContext) => {
+        if (!primaryStashDir || effectiveSync.enabled === false || !isGitBackedStash(primaryStashDir)) {
+            return undefined;
+        }
+        const saveGitStashFn = options.saveGitStashFn ?? saveGitStash;
+        const writableOverride = resolveWritableOverride(_earlyConfig);
+        const push = effectiveSync.push !== false;
+        const message = renderSyncCommitMessage(effectiveSync.message ?? "akm improve auto-sync", messageContext, Date.now());
+        try {
+            const syncResult = saveGitStashFn(undefined, message, writableOverride, { push, repoDir: primaryStashDir });
+            appendEvent({
+                eventType: "stash_synced",
+                metadata: {
+                    committed: syncResult.committed,
+                    pushed: syncResult.pushed,
+                    skipped: syncResult.skipped,
+                    reason: syncResult.reason ?? null,
+                },
+            }, eventsCtx);
+            return {
+                committed: syncResult.committed,
+                pushed: syncResult.pushed,
+                skipped: syncResult.skipped,
+                ...(syncResult.reason !== undefined ? { reason: syncResult.reason } : {}),
+            };
+        }
+        catch (syncErr) {
+            const reason = syncErr instanceof Error ? syncErr.message : String(syncErr);
+            warn(`improve: stash sync failed (non-fatal): ${reason}`);
+            appendEvent({
+                eventType: "stash_synced",
+                metadata: { committed: false, pushed: false, skipped: true, reason },
+            }, eventsCtx);
+            return { committed: false, pushed: false, skipped: true, reason };
+        }
+    };
     try {
         // H7 (#566): arm the budget watchdog. `armBudgetWatchdog` captures both the
         // budget timer and the hard-kill timer it schedules on exhaustion, returning
@@ -1053,6 +1110,16 @@ export async function akmImprove(options = {}) {
                     break;
                 }
             }
+            // #662 incremental sync: bank the PREVIOUS cycle's writes before starting a
+            // new one, so a crash/abort/timeout mid-run loses at most the in-flight
+            // cycle rather than the whole run. Guarded on `cycleIndex > 0`, so the
+            // common maxCycles:1 path never calls this — its single end-of-run commit
+            // below stays the only sync and the serialized envelope is byte-identical
+            // to pre-#662. `saveGitStash` no-ops a clean tree, so a cycle that wrote
+            // nothing costs only a `git status`.
+            if (cycleIndex > 0) {
+                commitStashBatch({ scope, plannedRefs, runId: options.runId });
+            }
             // Re-run ensureIndex + collectEligibleRefs + memory-cleanup recompute for
             // cycles 2+ (cycle 1 already ran them in the first try above). This makes
             // cycle N's gate-promoted proposals visible to this cycle's ref selection.
@@ -1309,57 +1376,18 @@ export async function akmImprove(options = {}) {
                 warningCount: allWarnings.length,
                 orphansPurged: orphansPurged ?? 0,
             }, eventsCtx);
-        // End-of-run BATCH auto-sync. Recognition is decoupled from the per-write
-        // path (see write-source.ts case-3): the primary stash writes as a
-        // filesystem source during the run, then is committed in one shot here via
-        // the same `saveGitStash` that `akm sync` calls. Gated on a non-dry-run, a
-        // git-backed primary stash (by `.git`, not by remote), and sync not
-        // disabled. A sync failure is NON-FATAL — it never fails a successful run
-        // (mirrors the contradiction-detection best-effort pattern).
-        const effectiveSync = { ...improveProfile.sync, ...options.sync };
-        if (!result.dryRun && primaryStashDir && effectiveSync.enabled !== false && isGitBackedStash(primaryStashDir)) {
-            const saveGitStashFn = options.saveGitStashFn ?? saveGitStash;
-            // Reuse the config resolved at the top of the run (`_earlyConfig`) instead
-            // of a second loadConfig(); the writable derivation is shared with
-            // `akm sync` via resolveWritableOverride().
-            const writableOverride = resolveWritableOverride(_earlyConfig);
-            const push = effectiveSync.push !== false;
-            // `sync.message` may contain `{token}` placeholders (timestamp/date/time/
-            // scope/refs/accepted) expanded against this run's results; the default
-            // template has no tokens so it renders verbatim.
-            const message = renderSyncCommitMessage(effectiveSync.message ?? "akm improve auto-sync", result, Date.now());
-            try {
-                // Pass primaryStashDir as the explicit commit target so the gate above
-                // (which validated primaryStashDir via isGitBackedStash) and the commit
-                // operate on the SAME directory — avoids divergence when a caller passes
-                // a non-default options.stashDir (FIX 9).
-                const syncResult = saveGitStashFn(undefined, message, writableOverride, { push, repoDir: primaryStashDir });
-                result.sync = {
-                    committed: syncResult.committed,
-                    pushed: syncResult.pushed,
-                    skipped: syncResult.skipped,
-                    ...(syncResult.reason !== undefined ? { reason: syncResult.reason } : {}),
-                };
-                appendEvent({
-                    eventType: "stash_synced",
-                    metadata: {
-                        committed: syncResult.committed,
-                        pushed: syncResult.pushed,
-                        skipped: syncResult.skipped,
-                        reason: syncResult.reason ?? null,
-                    },
-                }, eventsCtx);
-            }
-            catch (syncErr) {
-                const reason = syncErr instanceof Error ? syncErr.message : String(syncErr);
-                warn(`improve: end-of-run stash sync failed (non-fatal): ${reason}`);
-                result.sync = { committed: false, pushed: false, skipped: true, reason };
-                appendEvent({
-                    eventType: "stash_synced",
-                    metadata: { committed: false, pushed: false, skipped: true, reason },
-                }, eventsCtx);
-            }
-        }
+        // End-of-run BATCH auto-sync — the converged commit. Recognition is
+        // decoupled from the per-write path (see write-source.ts case-3): the primary
+        // stash writes as a filesystem source during the run, then is committed via
+        // the same `saveGitStash` that `akm sync` calls. The gating (git-backed
+        // primary stash, sync not disabled) and the NON-FATAL guarantee now live in
+        // `commitStashBatch` (#662); the inter-cycle and catch-path calls reuse it.
+        // dry-run already returned above, so this always runs on a completed live
+        // run. `result.sync` reflects this final commit (for a one-cycle run it is
+        // the only commit; for a multi-cycle run the earlier cycles were banked by
+        // the inter-cycle calls and this records the last batch). `result` carries
+        // the full `{accepted}`/`{refs}`/`{triage_*}` token data for the message.
+        result.sync = commitStashBatch(result);
         return result;
     }
     catch (err) {
@@ -1372,6 +1400,13 @@ export async function akmImprove(options = {}) {
                 durationMs: Date.now() - startMs,
             },
         }, eventsCtx);
+        // #662 crash/abort safety net: commit whatever this run already wrote to the
+        // primary stash BEFORE rethrowing, so an interrupted run (mid-cycle crash or
+        // a cooperative budget abort that surfaces as a throw) does not leave its
+        // writes uncommitted until a later clean run sweeps them up. Best-effort —
+        // `commitStashBatch` swallows its own errors and no-ops a clean tree, so this
+        // never masks or supersedes the original failure being rethrown below.
+        commitStashBatch({ scope, plannedRefs, runId: options.runId });
         throw err;
     }
     finally {
@@ -2471,6 +2506,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 +2533,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 +2549,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.0-beta.41",
+  "version": "0.9.0-beta.43",
   "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": [