akm-opencode 0.6.0 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # akm-opencode
 
-OpenCode plugin for the [AKM](https://github.com/itlackey/akm) CLI (v0.5.0+). Registers tools that let your AI agent **search**, **show**, and **manage** stash assets — skills, commands, agents, knowledge, memories, scripts, workflows, vaults, and wikis — plus **agentic hooks** that auto-load relevant assets into each turn, record feedback when assets are used, and harvest session memories so the stash improves with every session.
+OpenCode plugin for the [AKM](https://github.com/itlackey/akm) CLI (v0.7.0+). Registers tools that let your AI agent **search**, **show**, and **manage** stash assets — skills, commands, agents, knowledge, memories, lessons, scripts, workflows, vaults, and wikis — **operate the v0.7.0 proposal queue** and **distill lessons** through dedicated tools, plus **agentic hooks** that auto-load relevant assets into each turn, record feedback when assets are used (skipping proposed-quality drafts), and harvest session memories so the stash improves with every session.
 
 ## Installation
 
@@ -14,16 +14,16 @@ Add to your OpenCode config (`opencode.json`):
 
 ## Tools
 
-The plugin exposes a trimmed surface of **14 high-value tools**. Long-tail verbs (`add`, `save`, `import`, `clone`, `update`, `remove`, `list`-sources, `registry-search`, `index`-reindex, `config`, `upgrade`, ad-hoc `run`) are reachable via `akm_help` plus the raw `akm` CLI through the `bash` tool.
+The plugin exposes **19 high-value tools**. Long-tail verbs (`add`, `save`, `import`, `clone`, `update`, `remove`, `list`-sources, `registry-search`, `index`-reindex, `config`, `upgrade`, ad-hoc `run`, raw `agent`) are reachable via `akm_help` plus the raw `akm` CLI through the `bash` tool.
 
 | Tool | Description |
 |------|-------------|
-| `akm_search` | Search the local stash, the registry, or both. Type filter accepts `skill`, `command`, `agent`, `knowledge`, `memory`, `script`, `workflow`, `vault`, `wiki`, `any` |
+| `akm_search` | Search the local stash, the registry, or both. Type filter accepts `skill`, `command`, `agent`, `knowledge`, `lesson`, `memory`, `script`, `workflow`, `vault`, `wiki`, `any`; proposed hits can be included explicitly |
 | `akm_show` | Show a stash asset by its ref |
 | `akm_agent` | Dispatch a stash `agent:*` into OpenCode using the stash prompt and metadata |
 | `akm_cmd` | Execute a stash `command:*` template in OpenCode via SDK session prompting |
 | `akm_remember` | Record a memory in the default stash |
-| `akm_feedback` | Record positive or negative feedback for a stash asset (skipped automatically for `memory:` and `vault:` refs) |
+| `akm_feedback` | Record positive or negative feedback for a stash asset (skipped automatically for `memory:`, `vault:`, `lesson:`, and proposed-quality refs) |
 | `akm_curate` | Curate the stash for a task or topic and return ranked matches the agent can use |
 | `akm_evolve` | Dispatch the AKM curator subagent into a child session, capture the report as a memory, and seed the curator-context cache so it survives compaction |
 | `akm_parent_messages` | Summarize the parent OpenCode session so dispatched stash subagents can inherit upstream context |
@@ -31,6 +31,11 @@ The plugin exposes a trimmed surface of **14 high-value tools**. Long-tail verbs
 | `akm_vault` | Vault `list` / `show` (key names) / `create` / `set` / `unset` / `load` (opaque shell-eval text). **Values never surface** through `list`/`show`; `load` output is meant for `eval` and must not be displayed back |
 | `akm_wiki` | Manage wikis (`create`, `register`, `list`, `show`, `pages`, `search`, `stash`, `lint`, `ingest`, `remove`) |
 | `akm_workflow` | Drive workflow runs (`start`, `next`, `complete`, `status`, `list`, `create`, `template`, `resume`) |
+| `akm_proposal` | Operate the v0.7.0 proposal queue (`list` / `show` / `diff` / `accept` / `reject`). Always confirm with the user before `accept`/`reject` — those operations require explicit approval |
+| `akm_reflect` | Generate a reflection proposal via the configured agent CLI; output lands in the proposal queue only |
+| `akm_propose` | Generate a new-asset proposal via the configured agent CLI; the result is `quality:"proposed"` until accepted |
+| `akm_distill` | Distill an AKM ref (typically `memory:*` or `knowledge:*`) into a proposed `lesson` (gated by `llm.features.feedback_distillation`) |
+| `akm_setup` | Detect installed agent CLIs (`opencode`, `claude`, `codex`, `gemini`, `aider`) and persist `agent.default`. Required once per machine for `akm_reflect` / `akm_propose` |
 | `akm_help` | Discover the right `akm` CLI invocation for non-first-class verbs. Returns a curated quick-reference table plus live `akm <subcommand> --help` output |
 
 ## Compound-engineering hooks
@@ -43,8 +48,9 @@ fails silently when `akm` is not on PATH — the TUI is never affected.
 | --- | --- |
 | **`session.created`** (event hook) | Warms the stash index in the background, caches `akm hints` plus active workflow status, and runs a scoped `akm curate --run <sessionID>` so fresh sessions see relevant stash context before the first user message. |
 | **`chat.message`** | Runs `akm curate "<prompt>" --run <sessionID>` on each user message (prompts shorter than `AKM_CURATE_MIN_CHARS` are skipped). The top matches are stored for injection. Memory intents (prompts mentioning "remember" / "memory") are tracked in the session buffer. |
-| **`experimental.chat.system.transform`** | Appends cached hints, active workflow state, the last curator report, and the current prompt's curated context to the model's system prompt. Hints and workflow state are re-injected after transcript compaction. |
+| **`experimental.chat.system.transform`** | Appends cached hints, active workflow state, pending proposal summaries, the last curator report, and the current prompt's curated context to the model's system prompt. Hints and workflow state are re-injected after transcript compaction. |
 | **`tool.execute.before`** (`akm_*` tools) | Blocks destructive or sensitive operations until `confirm:true` is provided. |
+| **`permission.ask`** / **`command.execute.before`** | Detects risky raw `akm` CLI commands executed through shell/commands and denies them until the user explicitly approves the exact operation. |
 | **`tool.execute.after`** (`akm_*` tools) | Logs asset usage, accumulates refs into the session buffer, records `akm feedback <ref> --positive` / `--negative` asynchronously with per-call dedupe, checkpoints memories every `AKM_MEMORY_CHECKPOINT_EVERY` successful asset-touching tool calls, and scans child-agent free text for additional refs. |
 | **`experimental.session.compacting`** | Pushes hints, curated context, active workflows, and the last curator report into the compaction prompt so they survive transcript shrinking. |
 | **`shell.env`** | Exposes `AKM_STASH_DIR`, `AKM_PROJECT`, and `AKM_PLUGIN_VERSION` to shell tools so plain `akm` calls inherit the right context. |
@@ -66,6 +72,10 @@ fails silently when `akm` is not on PATH — the TUI is never affected.
 | `AKM_CURATOR_CONTEXT_MAX_CHARS` | `4000` | Max cached curator-report characters re-injected into system/compaction context; the full report is still persisted as memory. |
 | `AKM_MEMORY_CHECKPOINT_EVERY` | `8` | Number of successful asset-touching tool calls between mid-session checkpoint memories. |
 | `AKM_RETROSPECTIVE_FEEDBACK_PATTERN` | `\b(thanks|perfect|worked)\b` | Case-insensitive regex used for lightweight positive retrospective feedback on the most recent refs. |
+| `AKM_RETROSPECTIVE_NEGATIVE_PATTERN` | `\b(wrong|failed|broken|didn't work|did not work|bad)\b` | Case-insensitive regex used for negative retrospective feedback signals. |
+| `AKM_SCOPE_KEYS` | `user,agent,run,channel` | Comma-separated list of scope fields to attach on every `akm_remember`, `akm_curate`, and `akm_feedback` call. Remove a key to opt out of that dimension. |
+| `AKM_PENDING_PROPOSAL_TIMEOUT` | `2` | Seconds allowed for lightweight pending-proposal count checks during context injection. |
+| `AKM_PACKAGE_REF` | `akm-cli@latest` | Override the npm/bun package spec used for auto-install (e.g. pin to `akm-cli@0.7.0` in CI). |
 
 ### Curator agent
 
@@ -76,6 +86,27 @@ memories, parent-session context, live stash), produces a prioritized action
 list, and persists its latest report as `memory:akm-curator-YYYYMMDD-<sid>` so
 future curator runs can build on it.
 
+## AKM v1 workflows
+
+The plugin injects a concise AKM workflow instruction pack into context so agents:
+
+- search or curate before writing from scratch;
+- show an asset before relying on it;
+- record feedback after the result is known;
+- treat `lesson:*` as first-class durable assets;
+- treat proposed-quality assets as uncurated until accepted;
+- use `akm_help` to route `proposal`, `distill`, `reflect`, and `propose` CLI workflows;
+- require explicit user approval before proposal acceptance/rejection, push saves, source removal, CLI upgrades, update-all, or vault value access.
+
+The package also ships OpenCode command docs for common workflows:
+
+- `/akm-review-proposals`
+- `/akm-distill-lesson`
+- `/akm-reflect-on-failure`
+- `/akm-propose-asset`
+- `/akm-evolve-session`
+- `/akm-workflow-status`
+
 ### Registry discovery
 
 Search registries with `akm_search` using `source: "registry"` or `source: "both"`. Registry hits include `id`, `installRef`, and `action` fields. Use `installRef` when feeding a result into `akm add` (run via `akm_help` topic="add" or directly through bash); registry-specific IDs are not installable refs.
@@ -144,9 +175,11 @@ stash/
 ├── agents/     # markdown files
 ├── knowledge/  # markdown files
 ├── memories/   # markdown memory files (akm remember)
+├── lessons/    # first-class durable learnings (lesson:<name>) — produced by akm distill, accepted via akm_proposal accept
 ├── workflows/  # multi-step procedures (workflow:<name>)
 ├── vaults/     # .env secret stores (vault:<name>) — values never surface through structured output
-└── wikis/      # per-wiki directories <name>/{schema,index,log}.md + raw/ + pages
+├── wikis/      # per-wiki directories <name>/{schema,index,log}.md + raw/ + pages
+└── .akm/proposals/  # v0.7.0 proposal queue — drafts that never leak into search or commits
 ```
 
 ## Vaults

package/agent/akm-curator.md

@@ -20,7 +20,9 @@ Inputs you should inspect:
 Signals to act on:
 - Hot refs: assets repeatedly appearing in positive tool outcomes. Call akm_feedback <ref> positive --note "curator: consistently useful" to reinforce.
 - Cold refs: assets tied to failures or user complaints. Record akm_feedback <ref> negative --note "<excerpt>" and open the asset for review.
+- Lesson candidates: repeated memories or failures that should become a proposed lesson. Use akm_help topic="distill" before raw CLI distill commands.
 - Missing coverage: recurring user prompts with no matching asset. Draft a new skill, command, knowledge doc, wiki page, or workflow in the working stash and reindex via the akm CLI (see akm_help topic="reindex").
+- Pending proposals: list or diff them via akm_help topic="proposal" and recommend accept, reject, or revise. Never accept or reject without explicit user approval.
 - Duplicates / drift: near-identical descriptions or overlapping responsibilities. Propose a consolidation.
 - Stale memories: session summaries that never get recalled. Propose removal (see akm_help topic="remove") once distilled into a durable knowledge doc or wiki page.
 - Wiki hygiene: for each wiki returned by akm_wiki list, run akm_wiki lint <name> and report orphans, broken xrefs, uncited raws, and stale indexes as fix candidates.
@@ -42,9 +44,15 @@ Output shape: end every run with a markdown report that has these sections:
 ## Cold assets (investigate)
 - <ref> — failure signal — proposed fix
 
+## Lesson candidates
+- <theme> — evidence refs — distill or reflect command to run
+
 ## Coverage gaps
 - <theme> — proposed asset (type, name, one-line description)
 
+## Pending proposals
+- <proposal id> — summary — accept/reject/revise recommendation
+
 ## Duplicates / drift
 - <ref a> vs <ref b> — consolidation proposal
 

package/commands/akm-distill-lesson.md

@@ -0,0 +1,7 @@
+Distill repeated evidence into a proposed lesson.
+
+1. Search or curate for candidate refs.
+2. Show the strongest evidence refs.
+3. Call `akm_help` with `topic: "distill"`.
+4. Run `akm distill <ref>` only after the evidence is clear.
+5. Report the resulting proposal and remind the user that proposed assets are not curated until accepted.

package/commands/akm-evolve-session.md

@@ -0,0 +1,15 @@
+Run a full AKM session evolution review.
+
+End with these sections:
+
+## Hot assets
+## Cold assets
+## Lesson candidates
+## Coverage gaps
+## Pending proposals
+## Duplicates / drift
+## Wiki health
+## Workflow health
+## Housekeeping
+
+Use `akm_help` before long-tail raw CLI commands, and never accept or reject proposals or run risky AKM commands without explicit user approval.

package/commands/akm-propose-asset.md

@@ -0,0 +1,8 @@
+Create a proposed AKM asset for a coverage gap.
+
+1. Search or curate first.
+2. Confirm the gap is real.
+3. Call `akm_help` with `topic: "propose"`.
+4. Choose the smallest suitable asset type.
+5. Run `akm propose <type> <name> --task "..."`.
+6. Show proposal review commands and remind the user that proposed assets are not curated until accepted.

package/commands/akm-reflect-on-failure.md

@@ -0,0 +1,7 @@
+Reflect on an existing AKM asset after failure or drift.
+
+1. Identify the failure evidence and touched refs.
+2. Record negative feedback when justified.
+3. Call `akm_help` with `topic: "reflect"`.
+4. Run `akm reflect <ref> --task "..."`.
+5. List resulting pending proposals and do not accept or reject them without explicit user approval.

package/commands/akm-review-proposals.md

@@ -0,0 +1,7 @@
+Review pending AKM proposals safely.
+
+1. Call `akm_help` with `topic: "proposal"`.
+2. Run `akm proposal list --status pending --format json`.
+3. For relevant proposals, run `akm proposal show <id>` and `akm proposal diff <id>`.
+4. Summarize the likely accept, reject, or revise outcome.
+5. Do not run `akm proposal accept` or `akm proposal reject` unless the user explicitly approves the exact command.

package/commands/akm-workflow-status.md

@@ -0,0 +1,7 @@
+Inspect the current AKM workflow state safely.
+
+1. List active workflow runs.
+2. Show blocked or failed steps.
+3. Identify the next evidence needed.
+4. Recommend only safe next actions.
+5. Do not bypass review, approval, or verification requirements.

package/index.ts

@@ -5,7 +5,7 @@ import path from "node:path"
 import { fileURLToPath } from "node:url"
 
 let resolvedAkmCommand = "akm"
-const autoInstallPackageRef = "akm-cli@latest"
+const autoInstallPackageRef = process.env.AKM_PACKAGE_REF ?? "akm-cli@latest"
 const moduleDir = path.dirname(fileURLToPath(import.meta.url))
 const SEMVER_PATTERN = /\b\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?\b/
 
@@ -13,6 +13,7 @@ const AKM_AUTO_FEEDBACK = (process.env.AKM_AUTO_FEEDBACK ?? "1") !== "0"
 const AKM_AUTO_MEMORY = (process.env.AKM_AUTO_MEMORY ?? "1") !== "0"
 const AKM_AUTO_CURATE = (process.env.AKM_AUTO_CURATE ?? "1") !== "0"
 const AKM_AUTO_HINTS = (process.env.AKM_AUTO_HINTS ?? "1") !== "0"
+const AKM_PENDING_PROPOSAL_TIMEOUT_MS = Math.max(500, (Number(process.env.AKM_PENDING_PROPOSAL_TIMEOUT ?? "2") || 2) * 1_000)
 const AKM_CURATE_LIMIT = Math.max(1, Number(process.env.AKM_CURATE_LIMIT ?? "5") || 5)
 const AKM_CURATE_MIN_CHARS = Math.max(1, Number(process.env.AKM_CURATE_MIN_CHARS ?? "16") || 16)
 const AKM_CURATE_TIMEOUT_MS = Math.max(1_000, (Number(process.env.AKM_CURATE_TIMEOUT ?? "8") || 8) * 1_000)
@@ -21,6 +22,8 @@ const AKM_CURATOR_CONTEXT_MAX_CHARS = Math.max(500, Number(process.env.AKM_CURAT
 const SESSION_DATE_TAG_LENGTH = 8
 const CHECKPOINT_DATE_TAG_LENGTH = 15
 const AKM_RETROSPECTIVE_FEEDBACK_RE = createRetrospectiveFeedbackRegex()
+const AKM_RETROSPECTIVE_NEGATIVE_RE = createRetrospectiveNegativeRegex()
+const AKM_EXPLICIT_CORRECTION_RE = createExplicitCorrectionRegex()
 const PLUGIN_VERSION = readPackageVersion()
 
 // Per-session state that drives the compound-engineering loop.
@@ -46,12 +49,30 @@ type SessionBufferEntry = {
 const sessionBuffer = new Map<string, SessionBufferEntry[]>()
 const sessionFinalMemoryCaptured = new Set<string>()
 const sessionSuccessfulAssetTouchCount = new Map<string, number>()
+const pendingProposalSummaryCache = new Map<string, { count: number; expiresAt: number; unsupported?: boolean }>()
+const retrospectiveState = new Map<string, { recentRefs: string[]; lastNegativeSignalAt?: number }>()
 let cachedAkmStashDir: string | undefined
 
 // Asset-ref grammar matching the stash skill: [origin//]type:name.
 // We validate normalized tokens individually instead of running a global regex
 // over arbitrary tool output to keep extraction predictable and ReDoS-safe.
-const AKM_REF_PATTERN = /^(?:[A-Za-z0-9@._+/-]+\/\/)?(?:skill|command|agent|knowledge|memory|script|workflow|vault|wiki):[A-Za-z0-9._/\-]+$/
+const AKM_REF_PATTERN = /^(?:[A-Za-z0-9@._+/-]+\/\/)?(?:skill|command|agent|knowledge|memory|script|workflow|vault|wiki|lesson):[A-Za-z0-9._/\-]+$/
+const PROPOSED_QUALITY_WARNING = "Do not treat proposed assets as curated until accepted."
+const AKM_WORKFLOW_INSTRUCTION = [
+  "# AKM workflow (v0.7.0)",
+  "",
+  "Use AKM as a reusable knowledge and workflow stash.",
+  "",
+  "Before writing from scratch:",
+  "1. Use `akm_search` or `akm_curate`.",
+  "2. Use `akm_show <ref>` before relying on an asset.",
+  "3. Record `akm_feedback` after the result is known.",
+  "4. Use the dedicated v0.7.0 tools for the proposal flow: `akm_proposal` (list/show/diff/accept/reject), `akm_reflect`, `akm_propose`, and `akm_distill`. Fall back to `akm_help` for any verb without a dedicated tool.",
+  "5. Treat `lesson:*` as first-class durable learning assets — they are produced by `akm_distill <ref>` as proposals and accepted via `akm_proposal action=accept`.",
+  "6. Run `akm_setup` once on a fresh machine to detect installed agent CLIs and persist `agent.default`. Reflect/propose require it.",
+  `7. ${PROPOSED_QUALITY_WARNING}`,
+  "8. Never accept or reject proposals, push saves, remove sources, or access vault values without explicit user approval.",
+].join("\n")
 
 function readPackageVersion(): string {
   try {
@@ -72,6 +93,19 @@ function createRetrospectiveFeedbackRegex(): RegExp {
   }
 }
 
+function createRetrospectiveNegativeRegex(): RegExp {
+  const pattern = process.env.AKM_RETROSPECTIVE_NEGATIVE_PATTERN ?? "\\b(wrong|failed|broken|didn't work|did not work|bad)\\b"
+  try {
+    return new RegExp(pattern, "i")
+  } catch {
+    return /\b(wrong|failed|broken|didn't work|did not work|bad)\b/i
+  }
+}
+
+function createExplicitCorrectionRegex(): RegExp {
+  return /\b(this was wrong|that was wrong|you were wrong|incorrect|not correct)\b/i
+}
+
 const CURATOR_AGENT_PROMPT_FALLBACK = `You are the AKM curator — a compound-engineering agent that keeps the user's AKM stash improving every time the main agent finishes a task.
 
 Inputs you should inspect:
@@ -83,7 +117,9 @@ Inputs you should inspect:
 Signals to act on:
 - Hot refs: assets repeatedly appearing in positive tool outcomes. Call akm_feedback <ref> positive --note "curator: consistently useful" to reinforce.
 - Cold refs: assets tied to failures or user complaints. Record akm_feedback <ref> negative --note "<excerpt>" and open the asset for review.
+- Lesson candidates: repeated memories or failures that should become a proposed lesson. Use akm_help topic="distill" before raw CLI distill commands.
 - Missing coverage: recurring user prompts with no matching asset. Draft a new skill, command, knowledge doc, wiki page, or workflow in the working stash and reindex via the akm CLI (see akm_help topic="reindex").
+- Pending proposals: list or diff them via akm_help topic="proposal" and recommend accept, reject, or revise. Never accept or reject without explicit user approval.
 - Duplicates / drift: near-identical descriptions or overlapping responsibilities. Propose a consolidation.
 - Stale memories: session summaries that never get recalled. Propose removal (see akm_help topic="remove") once distilled into a durable knowledge doc or wiki page.
 - Wiki hygiene: for each wiki returned by akm_wiki list, run akm_wiki lint <name> and report orphans, broken xrefs, uncited raws, and stale indexes as fix candidates.
@@ -105,9 +141,15 @@ Output shape: end every run with a markdown report that has these sections:
 ## Cold assets (investigate)
 - <ref> — failure signal — proposed fix
 
+## Lesson candidates
+- <theme> — evidence refs — distill or reflect command to run
+
 ## Coverage gaps
 - <theme> — proposed asset (type, name, one-line description)
 
+## Pending proposals
+- <proposal id> — summary — accept/reject/revise recommendation
+
 ## Duplicates / drift
 - <ref a> vs <ref b> — consolidation proposal
 
@@ -265,6 +307,38 @@ function appendRunScopeArgs(args: string[], sessionID: string | undefined): stri
   return sessionID ? [...args, "--run", sessionID] : args
 }
 
+function getScopeFields(): Array<"user" | "agent" | "run" | "channel"> {
+  const configured = process.env.AKM_SCOPE_KEYS?.split(",").map((part) => part.trim()).filter(Boolean)
+  const values = configured && configured.length > 0 ? configured : ["user", "agent", "run", "channel"]
+  return values.filter((value): value is "user" | "agent" | "run" | "channel" =>
+    value === "user" || value === "agent" || value === "run" || value === "channel",
+  )
+}
+
+function buildScopedArgs(context: Record<string, unknown> | undefined): string[] {
+  if (!context) return []
+  const scopeFields = new Set(getScopeFields())
+  const args: string[] = []
+  const user = typeof context.userID === "string"
+    ? context.userID
+    : typeof context.user === "string"
+      ? context.user
+      : undefined
+  const agent = typeof context.agent === "string" ? context.agent : undefined
+  const run = typeof context.sessionID === "string" ? context.sessionID : typeof context.run === "string" ? context.run : undefined
+  const channel = typeof context.channel === "string"
+    ? context.channel
+    : typeof context.variant === "string"
+      ? context.variant
+      : undefined
+
+  if (scopeFields.has("user") && user) args.push("--user", user)
+  if (scopeFields.has("agent") && agent) args.push("--agent", agent)
+  if (scopeFields.has("run") && run) args.push("--run", run)
+  if (scopeFields.has("channel") && channel) args.push("--channel", channel)
+  return args
+}
+
 function runCurate(args: string[]): string | null {
   const result = runCliSyncRaw(args, AKM_CURATE_TIMEOUT_MS)
   if (!result.ok) return null
@@ -277,11 +351,10 @@ function runCurateForPrompt(text: string, sessionID?: string): string | null {
   return runCurate(
     appendRunScopeArgs(
       [
-        "--for-agent",
+        "--detail",
+        "agent",
         "--format",
         "text",
-        "--detail",
-        "summary",
         "-q",
         "curate",
         text,
@@ -297,11 +370,10 @@ function runCurateForSession(sessionID: string): string | null {
   return runCurate(
     appendRunScopeArgs(
       [
-        "--for-agent",
+        "--detail",
+        "agent",
         "--format",
         "text",
-        "--detail",
-        "summary",
         "-q",
         "curate",
         "--limit",
@@ -374,6 +446,17 @@ function formatCuratorReportContext(report: string): string {
   return `# AKM curator report\n${report}`
 }
 
+function formatPendingProposalContext(count: number): string {
+  const summaryLine = count === 1 ? "There is 1 pending AKM proposal." : `There are ${count} pending AKM proposals.`
+  return [
+    "# AKM pending proposals",
+    "",
+    summaryLine,
+    "Use `/akm-review-proposals` or `akm_help topic=proposal` to review them.",
+    PROPOSED_QUALITY_WARNING,
+  ].join("\n")
+}
+
 function summarizeCuratorReportForContext(report: string): string {
   if (report.length <= AKM_CURATOR_CONTEXT_MAX_CHARS) return report
   return `${report.slice(0, AKM_CURATOR_CONTEXT_MAX_CHARS).trimEnd()}\n\n[truncated for context]`
@@ -417,6 +500,139 @@ function warmIndexInBackground(): void {
   }
 }
 
+function safeJsonParse<T>(raw: string): T | undefined {
+  try {
+    return JSON.parse(raw) as T
+  } catch {
+    return undefined
+  }
+}
+
+function emitWorkflowTelemetry(client: LogCapableClient, level: LogLevel, eventType: string, extra: Record<string, unknown>) {
+  return writePluginLog(client, level, eventType, {
+    subsystem: "workflow-compliance",
+    eventType,
+    pluginVersion: PLUGIN_VERSION,
+    ...extra,
+  })
+}
+
+function noteRecentRefs(sessionID: string | undefined, refs: string[]) {
+  if (!sessionID || refs.length === 0) return
+  const state = retrospectiveState.get(sessionID) ?? { recentRefs: [] }
+  state.recentRefs = [...new Set([...state.recentRefs, ...refs])].slice(-8)
+  retrospectiveState.set(sessionID, state)
+}
+
+async function getPendingProposalCount(client: LogCapableClient, sessionID?: string): Promise<{ count: number; unsupported?: boolean }> {
+  const cacheKey = sessionID ?? "global"
+  const cached = pendingProposalSummaryCache.get(cacheKey)
+  if (cached && cached.expiresAt > Date.now()) return cached
+
+  const command = resolveAkmCommand()
+  if (typeof command !== "string") return { count: 0, unsupported: true }
+  try {
+    const stdout = execFileSync(command, ["proposal", "list", "--status", "pending", "--format", "json"], {
+      encoding: "utf8",
+      timeout: AKM_PENDING_PROPOSAL_TIMEOUT_MS,
+    })
+    const parsed = safeJsonParse<{ proposals?: unknown[]; hits?: unknown[] }>(stdout)
+    const count = Array.isArray(parsed?.proposals) ? parsed.proposals.length : Array.isArray(parsed?.hits) ? parsed.hits.length : 0
+    const result = { count, expiresAt: Date.now() + 60_000 }
+    pendingProposalSummaryCache.set(cacheKey, result)
+    return result
+  } catch (error: unknown) {
+    const message = formatCliError(error)
+    const unsupported = /unknown|unsupported|not found|invalid/i.test(message)
+    const result = { count: 0, unsupported, expiresAt: Date.now() + 60_000 }
+    pendingProposalSummaryCache.set(cacheKey, result)
+    return result
+  }
+}
+
+async function recordRetrospectiveFeedback(client: LogCapableClient, sessionID: string | undefined, text: string) {
+  if (!sessionID) return
+  const state = retrospectiveState.get(sessionID)
+  const recentRefs = state?.recentRefs ?? []
+  if (recentRefs.length === 0) return
+
+  const explicitCorrection = AKM_EXPLICIT_CORRECTION_RE.test(text)
+  const negative = explicitCorrection || AKM_RETROSPECTIVE_NEGATIVE_RE.test(text)
+  if (!negative) return
+
+  if (!explicitCorrection) {
+    const now = Date.now()
+    if (!state?.lastNegativeSignalAt || now - state.lastNegativeSignalAt > 2 * 60 * 1000) {
+      retrospectiveState.set(sessionID, { recentRefs, lastNegativeSignalAt: now })
+      return
+    }
+  }
+
+  const targetRef = recentRefs[recentRefs.length - 1]
+  const raw = await runCli(client, ["feedback", targetRef, "--negative", "--note", text.slice(0, 280)], {
+    toolName: "akm_feedback",
+    sessionID,
+  })
+  const parsed = safeJsonParse<{ ok?: boolean }>(raw)
+  if (parsed?.ok !== false) {
+    await emitWorkflowTelemetry(client, "info", "akm.feedback.recorded", {
+      sessionID,
+      toolName: "akm_feedback",
+      assetRef: targetRef,
+      outcome: "success",
+      reason: explicitCorrection ? "explicit correction" : "negative retrospective signal",
+    })
+  }
+  retrospectiveState.set(sessionID, { recentRefs })
+}
+
+type RiskyCommandAssessment = {
+  category: string
+  reason: string
+  approval: string
+}
+
+function assessRiskyAkmCommand(command: string): RiskyCommandAssessment | undefined {
+  const args = splitArguments(command)
+  const akmIndex = args.findIndex((arg) => arg === "akm" || arg.endsWith("/akm") || arg.endsWith("\\akm.exe"))
+  if (akmIndex === -1) return undefined
+  const tokens = args.slice(akmIndex + 1)
+  if (tokens[0] === "proposal" && tokens[1] === "accept") {
+    return { category: "proposal-accept", reason: "Proposal acceptance changes curated AKM content.", approval: "Ask the user to approve `akm proposal accept <id>`." }
+  }
+  if (tokens[0] === "proposal" && tokens[1] === "reject") {
+    return { category: "proposal-reject", reason: "Proposal rejection is a durable curation decision.", approval: "Ask the user to approve `akm proposal reject <id> --reason \"...\"`." }
+  }
+  if (tokens[0] === "save" && tokens.includes("--push")) {
+    return { category: "save-push", reason: "Pushing stash changes must be explicitly approved.", approval: "Ask the user to approve `akm save --push`." }
+  }
+  if (tokens[0] === "remove") {
+    return { category: "remove", reason: "Removing AKM sources is destructive.", approval: "Ask the user to approve the exact `akm remove ...` command." }
+  }
+  if (tokens[0] === "vault" && ["show", "load", "set", "unset"].includes(tokens[1] ?? "")) {
+    return { category: `vault-${tokens[1]}`, reason: "Vault access or mutation is sensitive.", approval: `Ask the user to approve the exact \`akm vault ${tokens[1]} ...\` command.` }
+  }
+  if (tokens[0] === "config" && tokens[1] === "set" && (tokens[2]?.startsWith("llm.features.") ?? false)) {
+    return { category: "config-llm-features", reason: "Changing AKM LLM feature flags alters autonomous behavior.", approval: "Ask the user to approve the exact `akm config set llm.features.* ...` command." }
+  }
+  if (tokens[0] === "update" && tokens.includes("--all")) {
+    return { category: "update-all", reason: "Updating all AKM kits changes many assets at once.", approval: "Ask the user to approve `akm update --all`." }
+  }
+  if (tokens[0] === "upgrade") {
+    return { category: "upgrade", reason: "Upgrading the AKM CLI changes the toolchain.", approval: "Ask the user to approve the exact `akm upgrade` command." }
+  }
+  return undefined
+}
+
+function blockedCommandMessage(command: string, assessment: RiskyCommandAssessment): string {
+  return [
+    `Blocked risky AKM command: ${command}`,
+    assessment.reason,
+    assessment.approval,
+    "Retry only after explicit user approval in this conversation.",
+  ].join("\n")
+}
+
 function queueFeedback(
   client: LogCapableClient,
   ref: string,
@@ -664,6 +880,8 @@ const AKM_HINTS_PREFIX = [
   "# AKM is available in this session",
   "",
   "You have an AKM stash on this machine. Before writing anything from scratch, call `akm_search` or `akm_curate` to see if the stash already covers it. Record `akm_feedback <ref> positive|negative` whenever an asset materially helps or misses, and use `akm_remember` to persist durable learnings so future sessions inherit them.",
+  "",
+  AKM_WORKFLOW_INSTRUCTION,
 ].join("\n")
 
 const AKM_CURATED_HEADER = "# AKM stash — assets relevant to this prompt"
@@ -715,6 +933,35 @@ type AkmHelpEntry = {
 }
 
 const AKM_HELP_QUICK_REFERENCE: readonly AkmHelpEntry[] = [
+  {
+    task: "Review pending proposals and decide whether to accept, reject, or revise them",
+    command: "akm proposal list --status pending --format json; akm proposal show <id>; akm proposal diff <id>",
+    notes: "Accept/reject requires explicit user approval.",
+    keywords: ["proposal", "review proposals", "pending proposals", "accept proposal", "reject proposal"],
+  },
+  {
+    task: "Distill repeated evidence into a proposed lesson",
+    command: "akm distill <ref>",
+    notes: "Distill creates a proposal; proposed assets are not curated until accepted.",
+    keywords: ["distill", "lesson", "proposed lesson"],
+  },
+  {
+    task: "Reflect on an existing asset after failure or drift",
+    command: "akm reflect <ref> --task \"...\"",
+    keywords: ["reflect", "drift", "failure"],
+  },
+  {
+    task: "Create a proposed asset for a coverage gap",
+    command: "akm propose <type> <name> --task \"...\"",
+    notes: PROPOSED_QUALITY_WARNING,
+    keywords: ["propose", "coverage gap", "proposed asset"],
+  },
+  {
+    task: "Search including proposed-quality assets",
+    command: "akm search <query> --include-proposed",
+    notes: PROPOSED_QUALITY_WARNING,
+    keywords: ["include-proposed", "proposed quality", "lesson"],
+  },
   {
     task: "Install a kit or register an external source (npm, GitHub, git, URL, local dir)",
     command: "akm add <package-ref> [--name <n>] [--type wiki] [--writable] [--trust] [--provider <p>] [--max-pages N] [--max-depth N]",
@@ -1064,6 +1311,7 @@ async function runCli(client: LogCapableClient, args: string[], meta: CliLogMeta
   }
 
   const fullArgs = args.includes("--format") ? [...args] : [...args, "--format", "json"]
+  const proposalId = args[0] === "proposal" && typeof args[2] === "string" ? args[2] : null
 
   try {
     const stdout = execFileSync(command, fullArgs, {
@@ -1081,6 +1329,59 @@ async function runCli(client: LogCapableClient, args: string[], meta: CliLogMeta
       stdout,
       stderr: "",
     })
+    const parsed = safeJsonParse<SearchResponse>(stdout)
+    const refs = args[0] === "search" || args[0] === "curate"
+      ? [...new Set([...(parsed?.hits?.flatMap((hit) => hit.ref ? [hit.ref] : []) ?? []), ...extractRefsFromText(stdout)])]
+      : extractRefsFromText(stdout)
+    noteRecentRefs(meta.sessionID, refs)
+    if (meta.toolName === "akm_search") {
+      await emitWorkflowTelemetry(client, "info", "akm.search.invoked", {
+        sessionID: meta.sessionID,
+        toolName: meta.toolName,
+        assetRef: refs[0] ?? null,
+        proposalId: null,
+        outcome: "success",
+        directory: meta.directory,
+      })
+    }
+    if (meta.toolName === "akm_curate") {
+      await emitWorkflowTelemetry(client, "info", "akm.curate.invoked", {
+        sessionID: meta.sessionID,
+        toolName: meta.toolName,
+        assetRef: refs[0] ?? null,
+        proposalId: null,
+        outcome: "success",
+        directory: meta.directory,
+      })
+    }
+    if (meta.toolName === "akm_show") {
+      await emitWorkflowTelemetry(client, "info", "akm.show.invoked", {
+        sessionID: meta.sessionID,
+        toolName: meta.toolName,
+        assetRef: args[1] ?? refs[0] ?? null,
+        proposalId,
+        outcome: "success",
+        directory: meta.directory,
+      })
+    }
+    if (args[0] === "proposal" && ["show", "diff"].includes(args[1] ?? "")) {
+      await emitWorkflowTelemetry(client, "info", "akm.proposal.reviewed", {
+        sessionID: meta.sessionID,
+        toolName: meta.toolName,
+        proposalId,
+        outcome: "requested",
+        directory: meta.directory,
+      })
+    }
+    if (args[0] === "proposal" && ["accept", "reject"].includes(args[1] ?? "")) {
+      await emitWorkflowTelemetry(client, "info", args[1] === "accept" ? "akm.proposal.accept.requested" : "akm.proposal.reject.requested", {
+        sessionID: meta.sessionID,
+        toolName: meta.toolName,
+        proposalId,
+        outcome: "requested",
+        directory: meta.directory,
+      })
+    }
     return stdout
   } catch (error: unknown) {
     const message = formatCliError(error)
@@ -1095,6 +1396,16 @@ async function runCli(client: LogCapableClient, args: string[], meta: CliLogMeta
       stdout: toLogString((error as { stdout?: unknown }).stdout) ?? "",
       stderr: toLogString((error as { stderr?: unknown }).stderr) ?? message,
     })
+    if (meta.toolName.startsWith("akm_")) {
+      await emitWorkflowTelemetry(client, "warn", `${meta.toolName}.failed`, {
+        sessionID: meta.sessionID,
+        toolName: meta.toolName,
+        proposalId,
+        outcome: "error",
+        reason: message,
+        directory: meta.directory,
+      })
+    }
     return JSON.stringify({ ok: false, error: message })
   }
 }
@@ -1104,6 +1415,7 @@ type AssetType =
   | "agent"
   | "command"
   | "knowledge"
+  | "lesson"
   | "memory"
   | "script"
   | "skill"
@@ -1115,6 +1427,7 @@ const ASSET_TYPES = [
   "agent",
   "command",
   "knowledge",
+  "lesson",
   "memory",
   "script",
   "skill",
@@ -1182,6 +1495,7 @@ type SearchHit = {
   action?: string
   editHint?: string
   curated?: boolean
+  quality?: string
 }
 
 type SearchResponse = {
@@ -1341,6 +1655,18 @@ function classifyToolFeedback(value: unknown): "positive" | "negative" | undefin
   return undefined
 }
 
+function withProposedWarnings(raw: string): string {
+  const parsed = safeJsonParse<SearchResponse>(raw)
+  if (!parsed) return raw
+  const hasProposed = parsed.hits?.some((hit) => hit.quality === "proposed") ?? false
+  if (!hasProposed) return raw
+  const warnings = parsed.warnings ?? []
+  return JSON.stringify({
+    ...parsed,
+    warnings: warnings.includes(PROPOSED_QUALITY_WARNING) ? warnings : [...warnings, PROPOSED_QUALITY_WARNING],
+  })
+}
+
 function truncateLogText(value: string, limit = 1_000): string {
   return value.length > limit ? `${value.slice(0, limit)}…` : value
 }
@@ -1583,6 +1909,7 @@ function createSearchArgs(input: {
   limit?: number
   source?: "local" | "stash" | "registry" | "both"
   defaultSource?: "local" | "stash" | "registry" | "both"
+  includeProposed?: boolean
 }): string[] {
   const args = ["search", input.query]
   if (input.type) args.push("--type", input.type)
@@ -1592,6 +1919,7 @@ function createSearchArgs(input: {
   } else if (input.defaultSource) {
     args.push("--source", normalizeSearchSource(input.defaultSource))
   }
+  if (input.includeProposed) args.push("--include-proposed")
   args.push("--detail", "normal")
   return args
 }
@@ -1656,6 +1984,10 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           if (!sessionWorkflow.has(sid)) {
             sessionWorkflow.set(sid, runWorkflowSummaryForSession() ?? "")
           }
+          const proposalSummary = await getPendingProposalCount(logClient, sid)
+          if (!proposalSummary.unsupported && proposalSummary.count > 0) {
+            markContextEpochDirty(sid)
+          }
         } else if (type === "session.compacted" || type === "session.idle" || type === "session.deleted") {
           if (!sid) return
           const captured = captureSessionMemory(sid, type)
@@ -1721,6 +2053,7 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           sessionHints.get(sid) ? `${AKM_HINTS_PREFIX}\n\n${sessionHints.get(sid)}` : "",
           sessionCurated.get(sid) ? `${AKM_CURATED_HEADER}\n${sessionCurated.get(sid)}${AKM_CURATED_TAIL}` : "",
           sessionWorkflow.get(sid) ? formatWorkflowContext(sessionWorkflow.get(sid)!) : "",
+          (await getPendingProposalCount(logClient, sid)).count > 0 && !(await getPendingProposalCount(logClient, sid)).unsupported ? formatPendingProposalContext((await getPendingProposalCount(logClient, sid)).count) : "",
           sessionCuratorReport.get(sid) ? formatCuratorReportContext(sessionCuratorReport.get(sid)!) : "",
         ]
         output.context.push(...applyContextBudget(blocks))
@@ -1745,6 +2078,7 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
             sessionHints.get(sid) ? `${AKM_HINTS_PREFIX}\n\n${sessionHints.get(sid)}` : "",
             sessionCurated.get(sid) ? `${AKM_CURATED_HEADER}\n${sessionCurated.get(sid)}${AKM_CURATED_TAIL}` : "",
             sessionWorkflow.get(sid) ? formatWorkflowContext(sessionWorkflow.get(sid)!) : "",
+            (await getPendingProposalCount(logClient, sid)).count > 0 && !(await getPendingProposalCount(logClient, sid)).unsupported ? formatPendingProposalContext((await getPendingProposalCount(logClient, sid)).count) : "",
             sessionCuratorReport.get(sid) ? formatCuratorReportContext(sessionCuratorReport.get(sid)!) : "",
           ]
           output.system.push(...applyContextBudget(blocks))
@@ -1784,6 +2118,53 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         // Never break tool execution from the pre-hook.
       }
     },
+    "permission.ask": async (input, output) => {
+      try {
+        const command = typeof input?.metadata?.command === "string"
+          ? input.metadata.command
+          : Array.isArray(input?.patterns)
+            ? input.patterns.join(" && ")
+            : ""
+        if (!command.includes("akm")) return
+        await emitWorkflowTelemetry(logClient, "info", "akm.raw_cli.invoked", {
+          sessionID: input.sessionID,
+          toolName: "bash",
+          outcome: "requested",
+          command,
+        })
+        const assessment = assessRiskyAkmCommand(command)
+        if (!assessment) return
+        output.status = "deny"
+        await emitWorkflowTelemetry(logClient, "warn", "akm.raw_cli.blocked", {
+          sessionID: input.sessionID,
+          toolName: "bash",
+          outcome: "blocked",
+          reason: assessment.reason,
+          command,
+          category: assessment.category,
+        })
+      } catch {
+        // Best-effort only.
+      }
+    },
+    "command.execute.before": async (input, output) => {
+      try {
+        const command = `${input.command ?? ""} ${input.arguments ?? ""}`.trim()
+        const assessment = assessRiskyAkmCommand(command)
+        if (!assessment) return
+        output.parts = [{ type: "text", text: blockedCommandMessage(command, assessment) }]
+        await emitWorkflowTelemetry(logClient, "warn", "akm.raw_cli.blocked", {
+          sessionID: input.sessionID,
+          toolName: String(input.command ?? "bash"),
+          outcome: "blocked",
+          reason: assessment.reason,
+          command,
+          category: assessment.category,
+        })
+      } catch {
+        // Best-effort only.
+      }
+    },
     "shell.env": async (_input, output) => {
       try {
         output.env.AKM_PROJECT = worktree
@@ -1839,6 +2220,7 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           }, dedupe)
         }
       }
+      await recordRetrospectiveFeedback(logClient, input.sessionID, text)
     },
     "tool.execute.after": async (input, output) => {
       if (!input.tool.startsWith("akm_")) return
@@ -1874,8 +2256,9 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
       // Auto-feedback + session buffering: record every asset ref the tool
       // touched so the stash ranking improves over time and so Stop/Compact
       // has material to flush into a session summary memory.
-      const refResult = extractToolRefs(input.tool, input.args as Record<string, unknown>, parsed)
-      if (refResult.refs.length > 0 && input.sessionID) {
+        const refResult = extractToolRefs(input.tool, input.args as Record<string, unknown>, parsed)
+        noteRecentRefs(input.sessionID, refResult.refs)
+        if (refResult.refs.length > 0 && input.sessionID) {
         for (const ref of refResult.refs) {
           addBufferEntry(input.sessionID, {
             kind: "tool-ref",
@@ -1942,9 +2325,15 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           .enum(["local", "stash", "registry", "both"])
           .optional()
           .describe("Search source. 'stash' searches local stash directories, 'registry' searches registries, and 'both' searches all sources. 'local' remains a backward-compatible alias for 'stash'."),
+        include_proposed: tool.schema.boolean().optional().describe("Include proposed-quality results. Proposed assets are not curated until accepted."),
       },
-      async execute({ query, type, limit, source }) {
-        return runCli(client as unknown as LogCapableClient, createSearchArgs({ query, type, limit, source }), { toolName: "akm_search" })
+      async execute({ query, type, limit, source, include_proposed }, context) {
+        const raw = await runCli(
+          client as unknown as LogCapableClient,
+          createSearchArgs({ query, type, limit, source, includeProposed: include_proposed }),
+          { toolName: "akm_search", sessionID: context.sessionID, directory: context.directory },
+        )
+        return withProposedWarnings(raw)
       },
     }),
     akm_show: tool({
@@ -1982,11 +2371,12 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         name: tool.schema.string().optional().describe("Optional memory name."),
         force: tool.schema.boolean().optional().describe("Overwrite an existing memory with the same name."),
       },
-      async execute({ content, name, force }) {
+      async execute({ content, name, force }, context) {
         const args = ["remember", content]
         if (name) args.push("--name", name)
         if (force) args.push("--force")
-        return runCli(client as unknown as LogCapableClient, args, { toolName: "akm_remember" })
+        args.push(...buildScopedArgs(context as unknown as Record<string, unknown>))
+        return runCli(client as unknown as LogCapableClient, args, { toolName: "akm_remember", sessionID: context.sessionID, directory: context.directory })
       },
     }),
     akm_feedback: tool({
@@ -1996,10 +2386,20 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         sentiment: tool.schema.enum(["positive", "negative"]).describe("Whether the feedback is positive or negative."),
         note: tool.schema.string().optional().describe("Optional note to attach to the feedback."),
       },
-      async execute({ ref, sentiment, note }) {
+      async execute({ ref, sentiment, note }, context) {
         const args = ["feedback", ref, sentiment === "positive" ? "--positive" : "--negative"]
         if (note) args.push("--note", note)
-        return runCli(client as unknown as LogCapableClient, args, { toolName: "akm_feedback" })
+        args.push(...buildScopedArgs(context as unknown as Record<string, unknown>))
+        const raw = await runCli(client as unknown as LogCapableClient, args, { toolName: "akm_feedback", sessionID: context.sessionID, directory: context.directory })
+        await emitWorkflowTelemetry(logClient, "info", "akm.feedback.recorded", {
+          sessionID: context.sessionID,
+          toolName: "akm_feedback",
+          assetRef: ref,
+          outcome: "success",
+          reason: sentiment,
+          directory: context.directory,
+        })
+        return raw
       },
     }),
     akm_curate: tool({
@@ -2009,10 +2409,11 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         limit: tool.schema.number().optional().describe("Maximum number of curated matches to return. Defaults to 6."),
         detail: tool.schema.enum(["summary", "normal", "full"]).optional().describe("Detail level for each match. Defaults to 'summary'."),
       },
-      async execute({ query, limit, detail }) {
+      async execute({ query, limit, detail }, context) {
         const args = ["curate", query, "--limit", String(limit ?? 6)]
         if (detail) args.push("--detail", detail)
-        return runCli(client as unknown as LogCapableClient, args, { toolName: "akm_curate" })
+        args.push(...buildScopedArgs(context as unknown as Record<string, unknown>))
+        return runCli(client as unknown as LogCapableClient, args, { toolName: "akm_curate", sessionID: context.sessionID, directory: context.directory })
       },
     }),
     akm_evolve: tool({
@@ -2555,6 +2956,89 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         }
       },
     }),
+    akm_proposal: tool({
+      description: "Operate the AKM v0.7.0 proposal queue — list/show/diff/accept/reject pending drafts. All proposal-producing commands (reflect, propose, distill, plus plugin-emitted proposals) write through this queue. Acceptance runs full validation before promoting; rejection archives the draft. Always confirm with the user before action='accept' or 'reject'.",
+      args: {
+        action: tool.schema.enum(["list", "show", "diff", "accept", "reject"]).describe("Proposal subcommand."),
+        id: tool.schema.string().optional().describe("Proposal id. Required for show/diff/accept/reject."),
+        status: tool.schema.enum(["pending", "accepted", "rejected"]).optional().describe("Filter for action='list'."),
+        reason: tool.schema.string().optional().describe("Required for action='reject'. Recorded with the archived proposal."),
+      },
+      async execute({ action, id, status, reason }) {
+        const logMeta = { toolName: "akm_proposal" }
+        switch (action) {
+          case "list": {
+            const args = ["proposal", "list"]
+            if (status) args.push("--status", status)
+            return runCli(client as unknown as LogCapableClient, args, logMeta)
+          }
+          case "show": {
+            if (!id) return JSON.stringify({ ok: false, error: "'id' is required for action='show'." })
+            return runCli(client as unknown as LogCapableClient, ["proposal", "show", id], logMeta)
+          }
+          case "diff": {
+            if (!id) return JSON.stringify({ ok: false, error: "'id' is required for action='diff'." })
+            return runCli(client as unknown as LogCapableClient, ["proposal", "diff", id], logMeta)
+          }
+          case "accept": {
+            if (!id) return JSON.stringify({ ok: false, error: "'id' is required for action='accept'. Confirm with the user before accepting." })
+            return runCli(client as unknown as LogCapableClient, ["proposal", "accept", id], logMeta)
+          }
+          case "reject": {
+            if (!id) return JSON.stringify({ ok: false, error: "'id' is required for action='reject'. Confirm with the user before rejecting." })
+            if (!reason || !reason.trim()) return JSON.stringify({ ok: false, error: "'reason' is required for action='reject'. Ask the user why the proposal is being rejected." })
+            return runCli(client as unknown as LogCapableClient, ["proposal", "reject", id, "--reason", reason], logMeta)
+          }
+        }
+      },
+    }),
+    akm_reflect: tool({
+      description: "Generate a reflection proposal for an AKM ref via the configured agent CLI. Output lands in the proposal queue only — never mutates live stash content. Requires `agent.default` to be set (run akm_setup first if missing).",
+      args: {
+        ref: tool.schema.string().optional().describe("[origin//]type:name ref to reflect on. Optional — when omitted the agent reflects on overall session signal."),
+        task: tool.schema.string().optional().describe("Free-form task description guiding the reflection."),
+      },
+      async execute({ ref, task }) {
+        const args = ["reflect"]
+        if (ref) args.push(ref)
+        if (task) args.push("--task", task)
+        return runCli(client as unknown as LogCapableClient, args, { toolName: "akm_reflect" })
+      },
+    }),
+    akm_propose: tool({
+      description: "Generate a new-asset proposal via the configured agent CLI. The asset is drafted as `quality:\"proposed\"` and lands in the proposal queue — never directly into curated content. Requires `agent.default` (run akm_setup first if missing).",
+      args: {
+        type: tool.schema.enum(["skill", "command", "agent", "knowledge", "lesson", "script", "workflow", "wiki"]).describe("Asset type for the new proposal."),
+        name: tool.schema.string().describe("Slug for the new asset (matches the standard ref grammar)."),
+        task: tool.schema.string().describe("Required. Describes what the asset should do."),
+      },
+      async execute({ type, name, task }) {
+        if (!task || !task.trim()) return JSON.stringify({ ok: false, error: "'task' is required for akm_propose." })
+        const args = ["propose", type, name, "--task", task]
+        return runCli(client as unknown as LogCapableClient, args, { toolName: "akm_propose" })
+      },
+    }),
+    akm_distill: tool({
+      description: "Distill an AKM ref into a proposed `lesson` using the bounded in-tree LLM. Gated by `llm.features.feedback_distillation` (default false); when the gate is off the call returns a fallback warning instead of a proposal. Lessons require `description` and `when_to_use` frontmatter and are stored under `lessons/<name>.md` after acceptance.",
+      args: {
+        ref: tool.schema.string().describe("[origin//]type:name ref to distill — most often memory:<name> or knowledge:<name>."),
+      },
+      async execute({ ref }) {
+        if (!ref || !ref.trim()) return JSON.stringify({ ok: false, error: "'ref' is required for akm_distill." })
+        return runCli(client as unknown as LogCapableClient, ["distill", ref], { toolName: "akm_distill" })
+      },
+    }),
+    akm_setup: tool({
+      description: "Detect installed agent CLIs (opencode, claude, codex, gemini, aider) and persist `agent.default`. Required once per machine before akm_reflect / akm_propose can shell out. Idempotent — pass force=true to re-run detection even when agent.default is already set.",
+      args: {
+        force: tool.schema.boolean().optional().describe("Re-run detection even when agent.default is already configured."),
+      },
+      async execute({ force }) {
+        const args = ["setup"]
+        if (force) args.push("--force")
+        return runCli(client as unknown as LogCapableClient, args, { toolName: "akm_setup" })
+      },
+    }),
     akm_help: tool({
       description: "Discover the right `akm` CLI command and args for tasks not covered by a first-class tool — e.g. save/push, import, clone, update, remove, list sources, registry search, reindex, config, CLI upgrade, run script. Returns a curated quick-reference plus live `akm --help` output. Pass `command` to drill into a specific subcommand.",
       args: {
@@ -2583,6 +3067,16 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           hints: topic ? lookupAkmHelpHint(topic) : [],
           quickReference: AKM_HELP_QUICK_REFERENCE,
           help: helpText,
+          workflowTopics: [
+            "proposal",
+            "distill",
+            "reflect",
+            "propose",
+            "lesson",
+            "include-proposed",
+            "llm-features",
+            "vault-safety",
+          ],
         })
       },
     }),

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "akm-opencode",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
-  "description": "OpenCode plugin for AKM - search, show, and manage extension assets via the akm CLI, including v0.5.0 vaults, wikis, and workflows, with agentic hooks that auto-load relevant stash assets, record feedback, and harvest session memories so the stash improves every session.",
+  "description": "OpenCode plugin for AKM v0.7.0 - search, show, and manage extension assets via the akm CLI, including vaults, wikis, workflows, the proposal queue, lesson assets, and reflect/propose/distill commands, with agentic hooks that auto-load relevant stash assets, record feedback, and harvest session memories so the stash improves every session.",
   "keywords": [
     "opencode",
     "opencode-ai",
@@ -26,6 +26,7 @@
   "files": [
     "index.ts",
     "agent/",
+    "commands/",
     "README.md"
   ],
   "main": "./index.ts",