akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/assets/hints/cli-hints-short.md

@@ -1,6 +1,6 @@
 # akm CLI
 
-You have access to a searchable library of scripts, skills, commands, agents, knowledge documents, workflows, and memories via `akm`. Search your sources first before writing something from scratch.
+You have access to a searchable library of scripts, skills, commands, agents, knowledge documents, workflows, env files, secrets, lessons, and memories via `akm`. Search your sources first before writing something from scratch.
 
 ## Agent Task Loop
 
@@ -8,15 +8,15 @@ For any task, follow this loop:
 1. `akm curate "<task>"` — find the best matching asset
 2. `akm show <ref>` — read the schema (field names and structure)
 3. Edit the workspace file using schema field names + task-specific values from your README
-4. `akm feedback <ref> --positive` — record success
+4. `akm feedback <ref> --positive` — record success; use `--negative --reason "..."` when it fails
 
 For workflow tasks:
-1. `akm workflow next workflows/<name>` — get current step instructions
-2. Do the step work in your workspace
-3. `akm workflow complete <run-id> --step <step-id>` — mark done, get next step
+1. `akm show workflows/<name>` — inspect the procedure before executing it
+2. `akm workflow run workflows/<name> --param_name=value` — execute every step and verification gate
+3. `akm workflow status <run-id> --units` — inspect a stopped or failed run
 
 Workflow runs are scoped to your current project/worktree/directory. Ref-based
-commands like `workflow next workflows/<name>`, `workflow status workflows/<name>`,
+commands like `workflow run workflows/<name>`, `workflow status workflows/<name>`,
 and `workflow list` operate within the current scope only.
 
 ## Quick Reference
@@ -25,27 +25,27 @@ and `workflow list` operate within the current scope only.
 akm search "<query>"                          # Search all sources
 akm curate "<task>"                          # Curate the best matches for a task
 akm search "<query>" --type workflow          # Filter to workflow assets
-akm search "memory:projectA/"                 # List a typed subtree (ref-prefix query; trailing slash required)
-akm search "<query>" --source both            # Also search registries
+akm search "memories/projectA/"               # List a subtree (conceptId prefix; trailing slash required)
+akm search "<query>" --from all               # Also search registries
 akm show <ref>                                # View asset details
-akm workflow next <ref>                       # Start or resume a workflow
-akm remember "Deployment needs VPN access"    # Record a memory in your stash
-akm remember "note" --target my-stash         # Route write to a named writable stash source
+akm help <command>                            # Show a command's options and subcommands
+akm workflow run <ref>                        # Start or resume and execute a workflow
+akm remember "Deployment needs VPN access"    # Record a memory in your bundle
+akm remember "note" --bundle my-bundle         # Route write to a named writable bundle source
 akm remember "note" --xref knowledge/auth-flow # Cite provenance in frontmatter xrefs (repeatable)
 akm remember "fix" --supersedes memories/old-note # Write a correction AND demote the superseded asset
-akm import ./notes/release-checklist.md       # Import a knowledge doc into your stash
-akm import ./doc.md --target my-stash         # Route import to a named writable stash source
+akm import ./notes/release-checklist.md       # Import a knowledge doc into your bundle
+akm import ./doc.md --target my-bundle         # Route import to a named writable bundle source
 akm proposal diff skills/akm-dream            # Diff proposal by ref, UUID, or 8-char prefix
 akm proposal accept 7c115132                  # Accept by UUID prefix
 akm proposal reject skills/my-skill --reason "..."  # Reject by ref
 akm feedback <ref> --positive|--negative      # Record whether an asset helped
-akm add <ref>                                 # Add a source (npm, GitHub, git, local dir)
-akm clone <ref>                               # Copy an asset to the working stash (optional --dest arg to clone to specific location)
-akm mv memories/old-note new-note             # Rename an asset: inbound refs rewritten, ranking history preserved
-akm sync                                      # Commit (and push if writable remote) changes in the primary stash (--no-push to commit only)
+akm bundle add <ref>                                 # Add a source (npm, GitHub, git, local dir)
+akm clone <ref>                               # Copy an asset to the working bundle (optional --dest arg to clone to specific location)
+akm sync                                      # Commit (and push if writable remote) changes in the primary bundle (--no-push to commit only)
 akm improve --no-sync                         # Run improve without the end-of-run auto-commit
 akm improve --no-push                         # Auto-commit but skip push for this run
-akm registry search "<query>"                 # Search all registries
+akm search "<query>" --from registry          # Search all registries (registry search was folded into search)
 ```
 
 ## Primary Asset Types
@@ -56,13 +56,76 @@ akm registry search "<query>"                 # Search all registries
 | skill | Instructions to follow (read the full content) |
 | command | A prompt template with placeholders to fill in |
 | agent | A system prompt with model and tool hints |
-| knowledge | A reference doc (use `toc` or `section "..."` to navigate) |
+| knowledge | A reference doc (append `#<heading-slug>` to the ref to read one section) |
 | workflow | Parsed steps plus workflow-specific execution commands |
 | memory | Recalled context (read the content for background information) |
-| env | A `.env` file of related CONFIGURATION (many vars; sensitive or not — all protected); key names only. Inject with `akm env run <ref> -- <cmd>` (the agent-safe path — values stay on disk). |
-| secret | A single sensitive value for AUTHENTICATION (token, key, cert); name only. Use `akm secret path` / `akm secret run`. |
+| env | A `.env` file of configuration an app loads together (many vars; sensitive or not — all protected); key names only. Inject with `akm env run <ref> -- <cmd>` (the agent-safe path — values stay on disk). |
+| secret | A single sensitive value for AUTHENTICATION (token, key, cert); name only. Inject with `akm secret run <ref> <VAR> -- <cmd>`. |
+| lesson | A distilled feedback lesson: `content` plus `action` (rendered from the `when_to_use` frontmatter). Read both before applying a related skill. Generated by the improve pipeline and promoted through the proposal queue. |
 
 When an asset meaningfully helps or fails, record that with `akm feedback` so
 future search ranking can learn from real usage.
 
-Run `akm -h` for the full command reference.
+## Error Shapes and Exit Codes
+
+Every command returns JSON by default. On failure, the shape is always
+emitted on **stderr** (stdout is normally left empty):
+
+```json
+{"ok": false, "error": "<message>", "code": "<optional machine-readable code>", "hint": "<optional remediation hint>"}
+```
+
+Exit codes:
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | Not found or command-reported failure |
+| 2 | Usage / bad input |
+| 4 | Health warning (`akm health` only) |
+| 70 | Internal / unclassified error |
+| 78 | Configuration error |
+
+Check `ok === false` or a non-zero exit code to detect failure. The `hint`
+field, when present, describes a corrective action. `search`/`curate`
+success results also carry an additive `tip` field (a plain-text suggestion)
+when the result set is empty.
+
+`env run`, `secret run`, and `migrate` preserve the spawned process's exact
+status. `task run` preserves configuration failures as exit 78; other failed
+task results and failed `agent` dispatches map to exit 1 while retaining the
+child status in their result envelope.
+
+`akm lint` is the exception: it exits **0 on every successful run regardless
+of findings**. Read `summary.flagged` to detect issues, or pass
+`--fail-on-flagged` to opt into "exit 1 when findings exist":
+
+```sh
+akm lint | jq '.summary.flagged'              # always exit 0; read the count
+akm lint --fail-on-flagged && deploy          # exit 1 if any flagged issues
+```
+
+## Proposals & improvement (0.8.0+)
+
+`akm` ships a proposal queue so reflective edits, new asset drafts, and
+feedback-distilled lessons land out-of-band before they touch the live
+bundle. None of these commands mutate bundle content directly — they always
+go through `akm proposal accept`.
+
+```sh
+akm improve <ref>                              # Produce an improvement proposal for an existing asset
+akm improve <ref> --task "tighten the description"
+akm proposal new <type> <name> --task "..."    # Draft a new asset proposal from a description
+akm proposal new lesson docker-cleanup --task "consolidate cleanup feedback"
+akm proposal list                              # List pending proposals
+akm proposal list --status pending|accepted|rejected|reverted
+akm proposal show <id>                          # Render the proposal body
+akm proposal diff <ref-or-id>                   # Diff by ref, UUID, or 8-char prefix
+akm proposal accept 7c115132                    # Accept by UUID prefix
+akm proposal reject skills/my-skill --reason "not ready" # Reject by asset ref
+akm search "<query>" --include-proposed        # Surface proposal-queue entries in search
+```
+
+Run `akm help <command>` for that command's options and subcommands. Run
+`akm --help` for the command overview or `akm hints --detail full` for the
+complete agent guide.

package/dist/assets/improve-strategies/default.json

@@ -1,5 +1,5 @@
 {
-  "description": "Standard improve pass — reflect, distill, consolidate, memory inference, graph extraction, and validation; improve-stage extract and proactive maintenance off.",
+  "description": "Standard improve pass — reflect, distill, advisory consolidation, graph extraction, and validation. Memory inference is listed below but only runs when experimental.improveAutonomy is set; improve-stage extract and proactive maintenance off.",
   "processes": {
     "reflect": {
       "enabled": true,

package/dist/assets/improve-strategies/reflect-distill.json

@@ -5,7 +5,7 @@
       "enabled": true,
       "allowedTypes": ["agent", "command", "knowledge", "lesson", "memory", "skill", "workflow"]
     },
-    "distill": { "enabled": true, "allowedTypes": ["memory"] },
+    "distill": { "enabled": true, "allowedTypes": ["memory"], "requirePlannedRefs": false },
     "consolidate": { "enabled": false },
     "memoryInference": { "enabled": true },
     "graphExtraction": { "enabled": false },

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

@@ -1,5 +1,4 @@
-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.
+Compress the memory below into one derived memory. Output ONLY a JSON object with exactly these fields: title, description, tags, searchHints, and content.
+Rules: title must be specific and short; description must be one sentence; tags must contain 3-8 specific tags; searchHints must contain 3-6 useful retrieval phrases; content must be a plain string with 2-3 sentences. Avoid vague generalizations, preserve key facts (names/versions/paths/config keys verbatim), and merge related points. Never return field descriptions or placeholder values.
 
 Memory:

package/dist/assets/stash-skeleton/README.md

@@ -1,7 +1,7 @@
 # AKM Stash
 
 This is an **AKM stash** — a structured knowledge repository that stores reusable
-assets for you and your AI agents. AKM (Agent Knowledge Management) indexes, ranks,
+assets for you and your AI agents. AKM (Agent Knowledge Manager) indexes, ranks,
 and surfaces these assets at the right moment during coding sessions, improving
 consistency and reducing repeated context-setting.
 
@@ -68,9 +68,10 @@ akm show knowledge/<name>
 akm show memories/<name>
 akm show commands/<name>
 
-# List available assets by type
-akm list --type skill
-akm list --type knowledge
+# Browse available assets by type (a trailing slash lists the subtree)
+akm search "skills/"
+akm search "knowledge/"
+akm search "<query>" --type skill
 ```
 
 ### Recording feedback and new knowledge
@@ -100,4 +101,4 @@ akm proposal accept <id>
 
 ---
 
-*Created by `akm init`. See `akm --help` for full command reference.*
+*Created by `akm bundle create`. See `akm --help` for full command reference.*

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

@@ -1,7 +1,9 @@
 ---
+type: fact
 category: convention
 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.
+updated: 2026-07-28
 ---
 
 <!--

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

@@ -1,7 +1,9 @@
 ---
+type: fact
 category: convention
 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.
+updated: 2026-07-28
 ---
 
 <!--

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

@@ -1,7 +1,9 @@
 ---
+type: fact
 category: convention
 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.
+updated: 2026-07-28
 ---
 
 <!--

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

@@ -1,7 +1,9 @@
 ---
+type: fact
 category: convention
 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.
+updated: 2026-07-28
 ---
 
 <!--

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

@@ -1,7 +1,9 @@
 ---
+type: fact
 category: convention
 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.
+updated: 2026-07-28
 ---
 
 <!--

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

@@ -1,7 +1,9 @@
 ---
+type: fact
 category: convention
 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.
+updated: 2026-07-28
 ---
 
 <!--

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

@@ -1,7 +1,9 @@
 ---
+type: fact
 category: convention
 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.
+updated: 2026-07-28
 ---
 
 <!--

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

@@ -1,7 +1,9 @@
 ---
+type: fact
 category: convention
 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.
+updated: 2026-07-28
 ---
 
 <!--

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

@@ -1,7 +1,9 @@
 ---
+type: fact
 category: convention
 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.
+updated: 2026-07-28
 ---
 
 <!--

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

@@ -1,7 +1,9 @@
 ---
+type: fact
 category: convention
 description: How to cross-link assets so retrieval compounds — a provenance xref when derived, sparse real associative xrefs, corrections as new assets, and canonical entity naming.
 when_to_use: Surfaced to authoring agents when they create or revise any asset that derives from, corrects, or relates to another asset.
+updated: 2026-07-28
 ---
 
 <!--

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

@@ -1,7 +1,9 @@
 ---
+type: fact
 category: convention
 description: The closed vocabulary of domain prefixes for reuse-born assets (knowledge/skill/fact/script), plus canonical entity spellings. Edit this to match your stash.
 when_to_use: Surfaced to authoring agents alongside the other convention facts; consult it when picking a domain prefix for a knowledge, skill, fact, or script asset.
+updated: 2026-07-28
 ---
 
 <!--

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

@@ -1,7 +1,9 @@
 ---
+type: fact
 category: convention
 description: Where to place an asset in the stash — the one path partition axis, chosen by asset type, so refs stay stable and slug search (akm search "<slug>" --type <type>) co-locates related assets.
 when_to_use: Surfaced to authoring agents when they create or move any asset and must decide its subdirectory/name.
+updated: 2026-07-28
 ---
 
 <!--
@@ -99,19 +101,28 @@ cross-project reuse.
 
 ## Renames and evolution
 
-- **A ref is chosen once. Default to not renaming.** A manual rename dangles
+- **A ref is chosen once. Default to not renaming.** A rename dangles
   inbound xrefs silently at write time — nothing catches the breakage until
   the next `akm lint` run flags the dead frontmatter refs (`missing-ref`) —
-  while the dead ref string keeps scoring in FTS, and a manually renamed file
+  while the dead ref string keeps scoring in FTS, and a renamed file
   is a new index entry, so the asset's accumulated usage-ranking history
   resets.
-- If a rename is truly unavoidable, prefer `akm mv <ref> <new-name>`
-  (Experimental): it moves the file, rewrites inbound references across the
-  writable stash in the same pass, and keeps the asset's usage-ranking
-  history. Citing files in read-only sources are reported for manual
-  follow-up. On an older CLI without `akm mv`, treat the rename as an
-  xref-fixing operation: grep the stash for the old ref string and fix every
-  inbound reference in the same pass.
+- **A rename is delete plus create, and you do it by hand.** There is no
+  `akm mv` — moving the file strands every inbound ref and gives the
+  destination a fresh identity. If a rename is truly unavoidable:
+
+  ```sh
+  mv memories/old-note.md memories/new-note.md
+  # update any intentional refs (fully qualified: bundle//memories/old-note)
+  akm index
+  akm lint          # confirms nothing dangles
+  ```
+
+  A memory's `.derived.md` twin must move with its base. Citing files in
+  read-only sources cannot be fixed at all — another reason not to rename. The
+  asset's accumulated usage-ranking history resets unless you carry it over
+  with `bun scripts/rekey-asset-ref.ts <old-ref> <new-ref>` (a maintainer
+  script, run from a source clone after the move and before `akm index`).
 - When a project-scoped note turns out to be domain-general, **append, don't
   promote**: write a new `knowledge/<domain>/…` asset that xrefs the originating
   memory. Never rename the memory up a rung — that breaks its ref. The atomic

package/dist/assets/tasks/core/extract.yml

@@ -1,5 +1,5 @@
 version: 2
 schedule: "*/30 * * * *"
-command: akm extract --auto
+command: akm proposal extract --auto
 enabled: true
 description: Opt-in all-harness session extraction every 30 min

package/dist/assets/tasks/core/version-check.yml

@@ -1,5 +1,5 @@
 version: 2
 schedule: "0 9 * * 1"
-command: akm info --check-version
+command: akm upgrade --check
 enabled: true
 description: Weekly check for new akm releases

package/dist/assets/tasks/improve/akm-graph-refresh-weekly.yml

@@ -0,0 +1,5 @@
+version: 2
+schedule: "10 3 * * 0"
+command: akm improve --strategy graph-refresh --skip-if-locked
+enabled: true
+description: Full-corpus graph rebuild (weekly Sunday 3:10am)

package/dist/assets/tasks/improve/akm-improve-catchup.yml

@@ -0,0 +1,8 @@
+version: 2
+schedule: "0 4 * * *"
+command: akm improve --strategy catchup --skip-if-locked
+# Manual-recovery task: ships disabled (the retired registerDefaultTasks
+# marked it enableMode: "manual"). `akm task run` works while disabled;
+# opting into the schedule is `enabled: true` + `akm task sync`.
+enabled: false
+description: Manual recovery — consolidation + triage drain (run on demand via `akm task run akm-improve-catchup`)

package/dist/assets/tasks/improve/akm-improve-consolidate.yml

@@ -0,0 +1,5 @@
+version: 2
+schedule: "20 */4 * * *"
+command: akm improve --strategy consolidate --skip-if-locked
+enabled: true
+description: Consolidation-only pass (every 4h at :20)

package/dist/assets/tasks/improve/akm-improve-frequent.yml

@@ -0,0 +1,5 @@
+version: 2
+schedule: "40 * * * *"
+command: akm improve --strategy frequent --skip-if-locked
+enabled: true
+description: Frequent inference pass (hourly at :40; improve-stage extract off)

package/dist/assets/tasks/improve/akm-improve-nightly.yml

@@ -0,0 +1,5 @@
+version: 2
+schedule: "15 2 * * *"
+command: akm improve --strategy thorough --skip-if-locked
+enabled: true
+description: Full nightly quality sweep (daily 2:15am; suggested for server installs)

package/dist/assets/templates/html/health.html

@@ -390,7 +390,7 @@
       <div class="table-wrap">
       <table>
         <thead>
-          <tr><th>Started</th><th>Task</th><th>Strategy</th><th>Legacy Profile</th><th>Wall</th><th>Promoted</th><th>Merged</th><th>Contradicted</th><th>MI Written</th><th>Entities</th><th>Lint Fixed</th><th>Status</th></tr>
+          <tr><th>Started</th><th>Task</th><th>Strategy</th><th>Wall</th><th>Promoted</th><th>Merged</th><th>Contradicted</th><th>MI Written</th><th>Entities</th><th>Lint Fixed</th><th>Status</th></tr>
         </thead>
         <tbody id="lastRunsTable"></tbody>
       </table>
@@ -683,7 +683,6 @@ tbody.innerHTML = '';
   const dur = r.wallTimeMs ? (r.wallTimeMs / 60000).toFixed(1) + 'm' : '—';
   const task = r.taskId || 'manual';
   const strategy = r.strategy || '—';
-  const legacyProfile = r.legacyProfile || '—';
   const badge = r.ok
     ? '<span class="badge-pill badge-pass" style="padding:2px 8px;font-size:11px;"><span class="dot dot-pass" style="width:6px;height:6px;"></span>&nbsp;ok</span>'
     : '<span class="badge-pill badge-fail" style="padding:2px 8px;font-size:11px;"><span class="dot dot-fail" style="width:6px;height:6px;"></span>&nbsp;failed</span>';
@@ -691,7 +690,6 @@ tbody.innerHTML = '';
     <td style="font-family:monospace;font-size:12px;">${ts}</td>
     <td><code>${task}</code></td>
     <td><code>${strategy}</code></td>
-    <td><code>${legacyProfile}</code></td>
     <td>${dur}</td>
     <td style="color:var(--accent);font-weight:600;">${r.promoted || 0}</td>
     <td>${r.merged || 0}</td>

package/dist/assets/workflows/workflow-template.md

@@ -1,24 +1,41 @@
 ---
-description: Describe what this workflow accomplishes
-tags:
-  - example
+type: workflow
+description: One-sentence summary of what this workflow accomplishes.
+updated: 2026-01-01
+tags: [example]
 params:
-  example_param: Explain this parameter
+  example_param: { type: string, description: Explain this parameter }
+steps:
+  - id: first-step
+  - id: second-step
+    inputs: [steps.first-step.output]
 ---
 
-# Workflow: {{TITLE}}
+# {{TITLE}}
 
-## Step: {{FIRST_STEP_TITLE}}
-Step ID: {{FIRST_STEP_ID}}
+Free preamble prose describing what this workflow does. It is indexed for
+search and shown in `akm show`, but it is never dispatched to a step.
 
-### Instructions
-Describe what to do in this step.
+## first-step
 
-### Completion Criteria
-- Confirm the first step is complete
+Describe what to do in this step. Refer to run parameters in plain
+language — for example, "read the value given by the `example_param`
+parameter" — never as a template expression like `{{ example_param }}`.
 
-## Step: Second Step
-Step ID: second-step
+## second-step
 
-### Instructions
-Describe what happens next.
+Describe what happens next, using the first step's artifact — attached to
+this unit as context because this step declares
+`inputs: [steps.first-step.output]` above — referred to in prose as "the
+first step's attached artifact."
+
+### gate
+
+A `### gate` sub-heading is the step's completion rubric: the judge
+receives this whole section byte-exact. Omit the heading or leave its text
+empty to skip validation. A non-empty rubric requires
+`workflow.judgeEngine`; verifier failures and malformed verdicts reject the
+gate rather than silently skipping it.
+
+- Confirm the step accomplished what it set out to do.
+- Confirm nothing required was silently skipped.

package/dist/cli/invocation.js

@@ -7,11 +7,10 @@
  * Before this module, ~46 `process.argv` read sites were scattered across
  * `src/**` (32 outside `src/cli.ts`), each re-scanning the raw argv array for
  * repeated flags (`parseAllFlagValues`), `--`-passthrough tails (`env run`,
- * `secret run`), or first-occurrence flag values (`parseFlagValue`) — plus a
- * startup MUTATION of the global `process.argv` at `cli.ts:644`. This module
- * normalizes argv into one typed {@link ParsedInvocation} object, minted ONCE
- * by `src/cli.ts` right after its `normalizeShowArgv` rewrite, so every
- * downstream reader shares one parse instead of re-scanning the raw array.
+ * `secret run`), or first-occurrence flag values (`parseFlagValue`). This
+ * module normalizes argv into one typed {@link ParsedInvocation} object,
+ * minted ONCE by `src/cli.ts` at startup, so every downstream reader shares
+ * one parse instead of re-scanning the raw array.
  *
  * Deliberately import-free: this module must never join an import cycle
  * (cycle ratchet, plan §10.7 / chunk-9 D.3), so it depends on nothing but
@@ -20,11 +19,15 @@
  * of the same algorithms `output/context.ts`'s `parseFlagValue`/
  * `hasBooleanFlag` and (the now-retired) `cli/shared.ts` `parseAllFlagValues`
  * used, kept byte-identical so every converted call site is behavior-
- * preserving.
+ * preserving — with ONE deliberate exception (R-033a): `getAllFlagValuesFrom`
+ * now stops at a literal `--` separator instead of scanning past it, fixing a
+ * bug where a repeatable flag's value placed after `--` (meant to end flag
+ * parsing) was still read as a real flag occurrence. See that function's
+ * docstring.
  *
  * Singleton + fallback semantics (the design decision this module encodes):
- *  - `setParsedInvocation(argv)` is called exactly once, by `src/cli.ts`,
- *    immediately after `process.argv = normalizeShowArgv(process.argv)`. It
+ *  - `setParsedInvocation(argv)` is called exactly once, by `src/cli.ts`, in
+ *    its startup block before any command handler can run. It
  *    snapshots that argv into an immutable {@link ParsedInvocation} that
  *    every subsequent `getParsedInvocation()` call returns unchanged for the
  *    rest of the process lifetime — "normalize argv exactly once at entry".
@@ -58,8 +61,7 @@
  *    search-cli, stash-cli, cli.ts) is unaffected.
  *  - `findCittyTopLevelCommand`/`findCittyTopLevelCommandIndex` (moved from
  *    `cli/parse-args.ts`, which had zero internal imports for this cluster) —
- *    re-exported from `cli/parse-args.ts` for `tests/tasks-embedded.test.ts`
- *    and `commands/read/show.ts`.
+ *    re-exported from `cli/parse-args.ts` for `tests/tasks-embedded.test.ts`.
  *  - `resolveHelpMigrateVersionArg` (moved from `cli.ts`, where it was
  *    private) — the `akm help migrate <version>` positional/flag
  *    disambiguation guard.
@@ -69,6 +71,8 @@
 function getFlagValueFrom(argv, flag) {
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
+        if (arg === "--")
+            break;
         if (arg === flag)
             return argv[i + 1];
         if (arg.startsWith(`${flag}=`))
@@ -77,12 +81,32 @@ function getFlagValueFrom(argv, flag) {
     return undefined;
 }
 function hasFlagIn(argv, flag) {
-    return argv.some((arg) => arg === flag || arg === `${flag}=true`);
+    for (const arg of argv) {
+        if (arg === "--")
+            return false;
+        if (arg === flag || arg === `${flag}=true`)
+            return true;
+    }
+    return false;
 }
+/**
+ * Collect every `--flag value` / `--flag=value` occurrence, stopping at a
+ * literal `--` separator (R-033a). `--` conventionally ends flag parsing —
+ * everything after it is positional/passthrough, never a flag akm should
+ * interpret. Before this fix, a token like `--tag leaked:yes` placed AFTER
+ * `--` (e.g. `akm feedback <ref> --positive -- --tag leaked:yes`) was still
+ * picked up as a real `--tag` value, letting argv content past the boundary
+ * leak into structured output. This is a deliberate BEHAVIOR CHANGE from the
+ * pre-WI-9.9 per-site implementation this module otherwise keeps
+ * byte-identical (see the module docstring) — every caller of
+ * `parseAllFlagValues`/`getAllFlagValues` inherits the fix for free.
+ */
 function getAllFlagValuesFrom(argv, flag) {
     const values = [];
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
+        if (arg === "--")
+            break;
         if (arg === flag && i + 1 < argv.length) {
             values.push(argv[i + 1]);
             // BUG-M4: skip the value index so `--tag --tag` (literal `--tag` value)
@@ -122,8 +146,8 @@ function createParsedInvocation(argv) {
 let _invocation;
 /**
  * Mint the process-wide {@link ParsedInvocation} singleton. Called exactly
- * once, by `src/cli.ts`, right after `normalizeShowArgv` — "normalize argv
- * exactly once at entry" (plan §10.7).
+ * once, by `src/cli.ts`, at startup — "normalize argv exactly once at entry"
+ * (plan §10.7).
  */
 export function setParsedInvocation(argv) {
     _invocation = createParsedInvocation(argv);
@@ -157,10 +181,11 @@ export function _resetParsedInvocationForTests() {
 export function parseAllFlagValues(flag) {
     return getParsedInvocation().getAllFlagValues(flag);
 }
-function cittyComparableName(name) {
+/** citty compares `foo-bar` and `fooBar` as the same arg name. */
+export function cittyComparableName(name) {
     return name.replace(/[-_]+([a-zA-Z0-9])/g, (_match, char) => char.toUpperCase());
 }
-function toAliasArray(alias) {
+export function toAliasArray(alias) {
     if (Array.isArray(alias))
         return alias;
     return typeof alias === "string" ? [alias] : [];