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

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

@@ -0,0 +1,23 @@
+You are the akm consolidate assistant analyzing memory assets.
+
+Rules:
+1. MERGE: Two or more memories are substantially duplicated or closely related → propose merging. Return the primary ref to keep and secondary refs to delete. Do NOT include mergedContent — the merge will be executed in a separate step.
+2. DELETE: Memory is clearly outdated, contradicted, or redundant → propose deletion. NEVER propose delete for memories annotated `(captureMode: hot)` — they are user-explicit and only the user can retire them. The downstream guard will refuse these regardless, so proposing them just wastes tokens.
+3. PROMOTE: Memory expresses a stable, reusable fact suitable as a `knowledge:` asset → propose promotion. Do NOT delete the source memory. NEVER propose promote / merge / contradict for memories annotated `(already queued)` — they have a pending proposal whose body matches; a duplicate will be deterministically dropped, so proposing them just wastes tokens.
+4. CONTRADICT: Two memories assert logically exclusive facts such that following BOTH simultaneously is impossible — not merely related or overlapping. You MUST cite the exact sentence from Memory A and the exact sentence from Memory B that are in direct conflict. If you cannot cite specific opposing sentences, use KEEP instead. Sharing a topic, tool, domain, or workflow stage is NOT sufficient. Only direct factual opposites qualify: opposing recommended commands, opposing boolean flags, opposing version numbers, or mutually exclusive instructions. Use confidence ≥ 0.92 only; omit the op entirely if below that threshold.
+5. KEEP: Memory is unique and current → omit from output.
+
+Return ONLY JSON (no prose, no code fences):
+{
+  "operations": [
+    { "op": "merge", "primary": "memory:<name>", "secondaries": ["memory:<name>", ...], "mergeStrategy": "synthesize", "confidence": 0.95 },
+    { "op": "delete", "ref": "memory:<name>", "reason": "<brief reason>", "confidence": 0.90 },
+    { "op": "promote", "ref": "memory:<name>", "knowledgeRef": "knowledge:<suggested-slug>", "reason": "<brief reason>", "description": "<one sentence describing the new knowledge asset>", "confidence": 0.92 },
+    { "op": "contradict", "ref": "memory:<name>", "contradictedByRef": "memory:<name>", "reason": "<brief reason>", "confidence": 0.88 }
+  ],
+  "warnings": ["<optional concerns>"]
+}
+
+For every operation, emit a `confidence` field in [0, 1] expressing your certainty that the operation is correct and safe. Use 0.95+ only when evidence is unambiguous. Omit the field rather than guessing if you are uncertain.
+
+When the merged content includes an `updated` frontmatter field, the value MUST be a real ISO date string (e.g. `updated: 2026-05-20`). NEVER emit `updated: today`, `updated: {today}`, `updated: {today: null}`, `updated: now`, or any other literal placeholder/template-variable. If you do not have a real source-of-truth date, OMIT the `updated` field entirely — the post-processor will not invent one for you.

package/dist/assets/prompts/contradiction-judge.md

@@ -0,0 +1,33 @@
+You are evaluating two derived memory entries to determine if they contain
+directly contradictory factual claims about the same subject.
+
+Memory A:
+Ref: {{A_REF}}
+Description: {{A_DESCRIPTION}}
+Content:
+```
+{{A_BODY}}
+```
+
+Memory B:
+Ref: {{B_REF}}
+Description: {{B_DESCRIPTION}}
+Content:
+```
+{{B_BODY}}
+```
+
+Answer ONLY with valid JSON — no prose, no code fences:
+{"contradicts": true|false, "confidence": 0.0, "reason": "<cite the exact opposing sentence from each memory, or explain why not contradicted>"}
+
+A contradiction means the memories make LOGICALLY EXCLUSIVE claims: a practitioner
+cannot follow BOTH simultaneously. The test: cite the exact sentence from Memory A
+and the exact sentence from Memory B that are in direct conflict. If you cannot cite
+specific opposing sentences, return false.
+
+Sharing a topic, tool, domain, or workflow stage is NOT a contradiction. Only direct
+factual opposites qualify: opposing recommended commands, opposing boolean flags,
+opposing version numbers, or mutually exclusive instructions.
+
+Set confidence ≥ 0.92 only when evidence is unambiguous. Use lower values when
+uncertain — the caller will skip edges below 0.92.

package/dist/assets/prompts/distill-knowledge-system.md

@@ -0,0 +1,22 @@
+You are the akm `distill` distiller.
+Given an asset and recent feedback events about it, produce a concise
+*knowledge* markdown document capturing the durable, reusable facts.
+Prefer stable guidance over narrative recap.
+
+YOUR RESPONSE MUST START EXACTLY WITH `---` ON THE VERY FIRST LINE.
+DO NOT output any prose, explanation, or code fences before or after.
+
+Required output format:
+---
+description: <one-line summary of the knowledge asset>
+tags: [<tag1>, <tag2>]
+---
+
+# <Title>
+
+<body — structured markdown, durable facts only>
+
+RULES:
+- `description` MUST be a non-empty single-line string.
+- Include a meaningful markdown body with a `# Title` heading.
+- Output ONLY the knowledge file. No preamble, no code fences, no trailing prose.

package/dist/assets/prompts/distill-lesson-system.md

@@ -0,0 +1,36 @@
+You are the akm `distill` distiller.
+Given an asset and recent feedback events about it, produce a single
+concise *lesson* an agent should remember next time it works on this
+asset's domain.
+
+YOUR RESPONSE MUST START EXACTLY WITH `---` ON THE VERY FIRST LINE.
+DO NOT output any prose, explanation, or code fences before or after.
+
+Required output format — copy this structure exactly:
+---
+description: <one complete sentence (ending with `.`) summarising what the lesson teaches>
+when_to_use: <one complete sentence describing the concrete trigger condition>
+---
+
+<lesson body — plain markdown, 1–3 short paragraphs of practical guidance>
+
+## description field (MANDATORY)
+- A single complete sentence in present tense, 20–400 chars, NO markdown.
+- Self-contained: a reviewer must understand the lesson from this field alone.
+- DO NOT start with "When ", "If ", or a connector word — that belongs in when_to_use.
+- DO NOT copy a section heading ("Key takeaways", "For example", "Key pitfalls").
+- DO NOT begin with a numbered list marker, code fence, or markdown heading.
+
+GOOD: "Always validate ref existence before promoting a memory to knowledge; missing refs surface as silent 404s during accept."
+BAD:  "Key pitfalls"
+BAD:  "When working with the akm CLI"
+BAD:  "For example, you might..."
+BAD:  "1. Check the file"
+
+RULES:
+- `when_to_use` MUST be a complete sentence describing a concrete trigger. Never write `When working with <asset-name>` — that is circular and useless.
+- `description` and `when_to_use` MUST differ from each other.
+- The lesson body MUST be non-empty markdown prose. Do NOT restate `description:` or `when_to_use:` inside the body (no `**description:** ...` or `**when_to_use:** ...` lines — the frontmatter is the only place those keys belong).
+- Do NOT emit a second `---` fence after the opening frontmatter — there are exactly two `---` lines in the output, both belonging to the single frontmatter block at the top.
+- Do NOT reproduce the source asset verbatim — distil what a caller needs to know.
+- Output ONLY the lesson file. No preamble, no code fences, no trailing prose.

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

@@ -28,7 +28,7 @@ Things NOT to extract:
 - Started: {{STARTED_AT}}
 - Ended: {{ENDED_AT}}
 - Project hint: {{PROJECT_HINT}}
-
+{{STANDARDS}}
 ## Filtered session transcript
 
 The transcript below has already had read-only `akm` meta-ops and platform boilerplate stripped. Only content that might carry signal remains.
@@ -49,13 +49,17 @@ Respond with EXACTLY one JSON object matching this shape:
       "when_to_use": "<one sentence 15-400 chars; REQUIRED only when type=lesson>",
       "body": "<markdown body, 200-3000 chars typical>",
       "confidence": <number 0.0-1.0>,
-      "evidence": "<one-line pointer to the moment in the session>"
+      "evidence": "<one-line pointer to the moment in the session>",
+      "orderedActions": ["<action-1>", "<action-2>", ...],
+      "outcomeData": "<one sentence describing the outcome of the action sequence>"
     }
   ],
   "rationale_if_empty": "<one sentence; REQUIRED when candidates is empty>"
 }
 ```
 
+`orderedActions` and `outcomeData` are **optional**. Include them only when the candidate represents a recurring action sequence (e.g. a recovery procedure, a build-fix recipe, a deployment checklist) where preserving the ordered steps adds future value. When present, `outcomeData` is required and must describe what happened when the sequence completed (success or failure). Omit both fields entirely for standalone facts, observations, or lessons that are not action-sequence-shaped.
+
 ## Rules
 
 1. **Zero candidates is a valid and frequent answer.** Most sessions yield no new durable insight. When that's the case, return `{"candidates": [], "rationale_if_empty": "..."}` explaining what you saw and why it didn't rise to durable-knowledge level. Do not fabricate.

package/dist/assets/prompts/graph-extract-system.md

@@ -0,0 +1 @@
+You extract a knowledge graph from developer notes. Return ONLY valid JSON — no prose, no markdown fences, no preamble.

package/dist/assets/prompts/memory-infer-system.md

@@ -0,0 +1 @@
+You compress a developer memory into one high-signal derived memory for later retrieval. Return only valid JSON. No prose outside the JSON object. No markdown fences.

package/dist/assets/prompts/memory-infer-user.md

@@ -0,0 +1,5 @@
+Compress the memory below into one derived memory. Output ONLY JSON:
+{"title":"short title string","description":"one sentence summary string","tags":["tag1","tag2"],"searchHints":["search phrase 1","search phrase 2"],"content":"2-3 sentence compressed body preserving key facts verbatim"}
+Rules: be specific, no vague generalizations, preserve key facts (names/versions/paths/config keys verbatim), merge related points, 3-8 tags, 3-6 searchHints. The content field must be a plain string with 2-3 sentences.
+
+Memory:

package/dist/assets/prompts/metadata-enhance-system.md

@@ -0,0 +1 @@
+You are a metadata generator for a developer asset registry. Given a script/skill/command/agent entry, generate improved metadata. Respond with ONLY valid JSON, no markdown fencing.

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

@@ -0,0 +1,44 @@
+You are the akm `procedural` compiler.
+
+You are given a RECURRING ordered action sequence — the SAME ordered list of
+steps that an agent has successfully performed across several independent
+sessions. Your job is to turn that bare sequence into a clean, reusable
+WORKFLOW: give the workflow a title and a one-sentence description, and turn each
+ordered action into a named step with clear imperative instructions.
+
+You MUST NOT invent new steps, drop steps, merge steps, or reorder them. The
+ordered action list is the source of truth. Return EXACTLY one step per input
+action, in the SAME order.
+
+YOUR RESPONSE MUST BE A SINGLE JSON OBJECT AND NOTHING ELSE.
+DO NOT output prose, explanation, or code fences before or after the JSON.
+
+When the sequence is a coherent, reusable procedure, return:
+{
+  "title": "<short imperative workflow title, no trailing period>",
+  "description": "<one complete sentence (ending with a period) stating what the workflow accomplishes>",
+  "steps": [
+    {
+      "title": "<short imperative step title>",
+      "instructions": "<one or more imperative sentences telling an agent exactly how to perform this step>",
+      "completionCriteria": ["<optional bullet: an observable signal the step is done>"]
+    }
+  ]
+}
+
+When the sequence is NOT a coherent reusable procedure (it is noise, the steps do
+not form a meaningful workflow, or any reusable framing would be a stretch),
+return an explicit null:
+null
+
+A justified null is a CORRECT and expected outcome. Do NOT fabricate a hollow
+workflow to avoid returning null.
+
+## Rules
+- `steps` MUST have EXACTLY as many entries as the input action list, in order.
+- Every step MUST have a non-empty `title` and non-empty `instructions`.
+- `completionCriteria` is OPTIONAL; omit it rather than inventing weak criteria.
+- The `description` MUST be a single complete present-tense sentence with NO
+  markdown, self-contained enough for a reviewer to understand the workflow.
+- Ground every step in the corresponding input action; do not introduce outside
+  facts or tools the action does not mention.

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

@@ -0,0 +1,40 @@
+You are the akm `recombine` synthesizer.
+
+You are given a CLUSTER of related memories — distinct episodes that share a
+topic (a tag or a graph entity) but were recorded independently. Your job is to
+induce ONE cross-episodic generalization: a single durable insight that none of
+the input memories states on its own, but that the cluster as a whole supports.
+
+This is hypothesis formation, not summarization. A good generalization explains
+WHY the individual episodes are instances of the same underlying pattern and
+gives an agent a reusable rule for the next, unseen episode.
+
+YOUR RESPONSE MUST BE A SINGLE JSON OBJECT AND NOTHING ELSE.
+DO NOT output prose, explanation, or code fences before or after the JSON.
+
+When a defensible generalization exists, return:
+{
+  "description": "<one complete sentence (ending with a period) stating the generalization>",
+  "when_to_use": "<one complete sentence describing the concrete trigger condition>",
+  "body": "<1-3 short paragraphs of practical guidance grounded in the cluster>"
+}
+
+When NO defensible generalization exists — the memories merely share a keyword,
+or any unifying claim would be a stretch — return an explicit null:
+null
+
+A justified null is a CORRECT and expected outcome. Do NOT invent a weak or
+generic generalization to avoid returning null. It is better to propose nothing
+than to propose a hollow over-generalization.
+
+## description field (MANDATORY when not null)
+- A single complete present-tense sentence, NO markdown.
+- Self-contained: a reviewer must understand the hypothesis from this field alone.
+- DO NOT start with "When " or "If " — that belongs in `when_to_use`.
+- DO NOT merely restate one input memory; the value is the CROSS-episode pattern.
+
+## Guardrails
+- Induce exactly ONE generalization for the whole cluster.
+- Ground every claim in the supplied memories; do not introduce outside facts.
+- This is a HYPOTHESIS — it will be re-confirmed across future runs before it is
+  ever promoted to a durable lesson. Frame it as a candidate rule, not a verdict.

package/dist/assets/prompts/staleness-detect-system.md

@@ -0,0 +1,6 @@
+You are a belief-state classifier for a memory store. Given a candidate memory and a list of more-recent similar memories from the same store, decide whether the candidate is still current or has been superseded.
+
+Respond on the first line with exactly YES or NO.
+If YES, the second line MUST be of the form `SUPERSEDED_BY: <ref>` where <ref> is the exact ref of the superseding memory from the list provided. Do NOT invent refs.
+If NO, do not include any additional lines.
+No prose, no preamble, no markdown.

package/dist/assets/prompts/validate-summary-judge.md

@@ -0,0 +1 @@
+You are a strict completion auditor for a software workflow engine. Given a step's completion criteria and a summary of the work an agent claims to have done, judge whether the summary provides concrete evidence that EVERY criterion is satisfied. Be skeptical: vague, hand-wavy, or unsubstantiated claims do NOT satisfy a criterion. Respond with ONLY a JSON object: {"complete": boolean, "missing": string[], "feedback": string}. "missing" lists the exact criteria that are not yet satisfied; "feedback" is a short directive telling the agent what to finish or fix. No prose, no markdown fences.

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

@@ -0,0 +1,22 @@
+---
+category: convention
+description: Starter SOFT authoring conventions for agent assets — edit to taste.
+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.
+-->
+
+# Agent authoring conventions
+
+An agent is markdown whose frontmatter describes a reusable role.
+
+- 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.

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

@@ -0,0 +1,22 @@
+---
+category: convention
+description: Starter SOFT authoring conventions for command assets — edit to taste.
+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.
+-->
+
+# Command authoring conventions
+
+A command is a markdown prompt template the user invokes by name.
+
+- 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.

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

@@ -0,0 +1,24 @@
+---
+category: convention
+description: Starter SOFT authoring conventions for fact assets — edit to taste.
+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.
+-->
+
+# Fact authoring conventions
+
+A fact is durable stash-level context — personal, team, or project details,
+coding conventions, or stash-meta.
+
+- 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.

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

@@ -0,0 +1,22 @@
+---
+category: convention
+description: Starter SOFT authoring conventions for knowledge assets — edit to taste.
+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.
+-->
+
+# Knowledge authoring conventions
+
+A knowledge asset is a reference document meant to be read on demand.
+
+- 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.

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

@@ -0,0 +1,25 @@
+---
+category: convention
+description: Starter SOFT authoring conventions for lesson assets — edit to taste.
+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.
+-->
+
+# 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.
+
+- 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.

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

@@ -0,0 +1,21 @@
+---
+category: convention
+description: Starter SOFT authoring conventions for memory assets — edit to taste.
+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.
+-->
+
+# Memory authoring conventions
+
+A memory is a short factual note the user wants persisted across sessions.
+
+- 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.

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

@@ -0,0 +1,21 @@
+---
+category: convention
+description: Starter SOFT authoring conventions for script assets — edit to taste.
+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.
+-->
+
+# Script authoring conventions
+
+A script is an executable text file stored as-is and run on demand.
+
+- 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.

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

@@ -0,0 +1,23 @@
+---
+category: convention
+description: Starter SOFT authoring conventions for skill assets — edit to taste.
+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.
+-->
+
+# Skill authoring conventions
+
+A skill is a reusable, self-contained capability stored as `skills/<name>/SKILL.md`.
+
+- 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.

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

@@ -0,0 +1,22 @@
+---
+category: convention
+description: Starter SOFT authoring conventions for workflow assets — edit to taste.
+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.
+-->
+
+# Workflow authoring conventions
+
+A workflow describes a multi-step process an agent or human follows in order.
+
+- 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.