akm-cli 0.9.29 → 0.9.31

package/docs/architecture/testing/manual-testing-checklist.md

@@ -0,0 +1,3420 @@
+# AKM Manual Testing Runbook
+
+This is the authoritative manual QA document for AKM `0.9.x`. Other testing
+documents describe automation and internals; this document owns manual test
+scope, setup, expected behavior, evidence, and release-facing gates.
+
+Last audited against the implementation: **2026-08-05** (`0.9.0-rc.15`).
+
+## Table of Contents
+
+- [1. Purpose and Use](#1-purpose-and-use)
+- [2. Safety and Prerequisites](#2-safety-and-prerequisites)
+- [3. Sandbox Setup](#3-sandbox-setup)
+- [4. Fixtures and Local Services](#4-fixtures-and-local-services)
+- [5. Fast Offline Pass](#5-fast-offline-pass)
+- [6. Startup, Setup, Help, and Config](#6-startup-setup-help-and-config)
+- [7. Index, Search, Curate, and Show](#7-index-search-curate-and-show)
+- [8. Output, Errors, and Exit Codes](#8-output-errors-and-exit-codes)
+- [9. Bundles, Adapters, Sources, and Registries](#9-bundles-adapters-sources-and-registries)
+- [10. Writes, Import, Clone, and Sync](#10-writes-import-clone-and-sync)
+- [11. Env and Secret](#11-env-and-secret)
+- [12. Lint](#12-lint)
+- [13. Feedback, Log, and Health](#13-feedback-log-and-health)
+- [14. Workflow](#14-workflow)
+- [15. Task](#15-task)
+- [16. Proposal Queue](#16-proposal-queue)
+- [17. Agent, LLM, and Improve](#17-agent-llm-and-improve)
+- [18. Semantic Search](#18-semantic-search)
+- [19. Migration, Durability, and Concurrency](#19-migration-durability-and-concurrency)
+- [20. Security and Adversarial Testing](#20-security-and-adversarial-testing)
+- [21. Package, Runtime, Platform, and Release](#21-package-runtime-platform-and-release)
+- [22. Evidence and Cleanup](#22-evidence-and-cleanup)
+- [23. Change-Based Test Selection](#23-change-based-test-selection)
+- [24. Known Constraints and Blocked Gates](#24-known-constraints-and-blocked-gates)
+
+---
+
+## 1. Purpose and Use
+
+### 1.1 Scope
+
+This runbook covers:
+
+- CLI startup, help, setup, config, output shaping, and error classification.
+- Indexing, ranking, search, curate, show, refs, fragments, and usage tracking.
+- Every built-in bundle adapter and every supported source provider.
+- Writes, target precedence, git publication, envs, secrets, and redaction.
+- Workflow, task, proposal, agent, LLM, and improve behavior.
+- Semantic search, migration, crash recovery, locking, and concurrent processes.
+- npm packages, standalone binaries, installers, self-upgrade, schedulers, and
+  release artifacts.
+- Security boundaries including SSRF, path traversal, symlinks, dangerous env
+  keys, malformed input, rollback, and partial publication.
+
+This is a catalog, not an instruction to run every gate for every change. Use
+[Change-Based Test Selection](#23-change-based-test-selection) to choose scope.
+
+### 1.2 Test tiers
+
+Every check carries one or more labels.
+
+| Label | Meaning | Typical time | Token/network cost |
+| --- | --- | ---: | --- |
+| **[CORE]** | Fast deterministic offline gate | 25-35 min | None |
+| **[LOCAL]** | Extended local filesystem/process gate | +45-75 min | None |
+| **[SERVICE]** | Controlled loopback fixture services | +15-25 min | None |
+| **[LIVE]** | Controlled public git/npm/HTTPS service | +15-30 min | Network only |
+| **[AI]** | Fake or bounded real agent/LLM checks | +15-30 min | Fake: none; real: bounded |
+| **[PLATFORM]** | Native OS/runtime/install checks | Per platform | Runner/VM time |
+| **[DESTRUCTIVE]** | Crash, migration, and recovery rehearsal | 1-3 hr | Disposable VM only |
+| **[RELEASE]** | Exact package and release-artifact acceptance | 1-3 hr | CI/VM/network |
+
+### 1.3 Result states
+
+Use these states exactly:
+
+| Status | Meaning |
+| --- | --- |
+| `PASS` | Behavior, exit code, output, and side effects match the stated expectation. |
+| `FAIL` | Any observable result differs. |
+| `BLOCKED` | A named prerequisite is unavailable. Record it. |
+| `N/A` | The target platform genuinely does not support the surface. |
+
+Do not turn an implementation defect into an expected result. Some adversarial
+gates below intentionally expose unresolved behavior. A release waiver must name
+the issue, impact, owner, and expiry.
+
+### 1.4 Evidence header
+
+Record this once per run:
+
+```text
+commit:
+package version:
+artifact digest (when applicable):
+OS / architecture:
+Bun / Node versions:
+CLI invocation path:
+sandbox path:
+tiers run:
+started / finished UTC:
+tester:
+```
+
+For every failure retain the command, exit code, stdout, stderr, relevant file
+or database diff, and whether a second identical run reproduced it. Never
+attach real credentials or unredacted env/secret payloads.
+
+---
+
+## 2. Safety and Prerequisites
+
+### 2.1 Non-negotiable safety rules
+
+- [ ] Use a disposable shell and preferably a disposable clean worktree.
+- [ ] Isolate `HOME`, all four `XDG_*_HOME` variables, all four `AKM_*_DIR`
+      variables, temp files, GitHub CLI config, Git config, npm config/cache,
+      and Hugging Face cache under one sandbox root.
+- [ ] Set `AKM_CONFIG_DIR`. It overrides `XDG_CONFIG_HOME`; omitting it can
+      overwrite a real config before path verification.
+- [ ] Clear inherited AKM debug/registry settings and provider, agent, GitHub,
+      LLM, and embedding credentials.
+- [ ] Set both `AKM_FORCE_SETUP_TMP_STASH=1` and
+      `AKM_FORCE_INIT_TMP_STASH=1`; setup and bundle-create use separate guards.
+- [ ] Use `dist/akm` for release-facing checks. Use `bun ./src/cli.ts` only when
+      intentionally validating source execution.
+- [ ] Never run `akm upgrade`, native scheduler mutation, migration failure
+      injection, or kill-point tests on the developer account or host install.
+- [ ] Never point `akm sync` at a real writable remote.
+- [ ] Never use production secrets as fixtures.
+- [ ] Do not use internal migration test-hook variables manually. Run the
+      shipped recovery suites or use a dedicated disposable recovery harness.
+- [ ] Guard recursive cleanup with the exact sandbox prefix.
+
+The sandbox isolates AKM state. `bun install` and `bun run build` still operate
+inside the checkout, so release QA should use a disposable worktree and start
+from a clean `git status`.
+
+### 2.2 Prerequisites
+
+**[CORE]** and **[LOCAL]** require Bash, Bun, Node.js 22+, Git, `jq`, standard
+POSIX filesystem tools, and the repository checkout.
+
+| Gate | Additional prerequisite |
+| --- | --- |
+| YAML parsing | Repository `yaml` dependency |
+| Git source/sync | Disposable remote or local no-push repository |
+| npm source | Disposable package/version or controlled registry |
+| Production website | Controlled public HTTPS hostname; loopback is blocked |
+| Local semantic model | Cold-download network, disk, isolated `HF_HOME` |
+| Docker | Docker/BuildKit and base-image network access |
+| Native scheduler | Disposable OS account or VM |
+| Release artifact | Exact candidate tarball/binaries/checksums and native runners |
+
+### 2.3 Automated baseline before manual release QA
+
+```sh
+git status --short
+bun install --frozen-lockfile
+bun run check
+bun run build
+test -x dist/akm
+test ! -e dist/tests
+```
+
+- [ ] **[RELEASE]** `bun run check` exits `0`.
+- [ ] **[RELEASE]** Build exits `0`; `dist/tests` does not exist.
+- [ ] **[RELEASE]** Recheck `git status --short`. Only understood generated
+      changes are present. Do not format/rewrite the release candidate during
+      acceptance.
+
+---
+
+## 3. Sandbox Setup
+
+### 3.1 Create the sandbox
+
+Run from the repository root. The shell function is deliberate; it is more
+reliable than an alias in copied scripts.
+
+```sh
+set -u
+umask 077
+
+export REPO="$(git rev-parse --show-toplevel)"
+export AKM_BIN="$REPO/dist/akm"
+export AKM_SANDBOX="$(mktemp -d /tmp/akm-sandbox.XXXXXX)"
+
+export HOME="$AKM_SANDBOX/home"
+export XDG_CONFIG_HOME="$AKM_SANDBOX/xdg-config"
+export XDG_CACHE_HOME="$AKM_SANDBOX/xdg-cache"
+export XDG_DATA_HOME="$AKM_SANDBOX/xdg-data"
+export XDG_STATE_HOME="$AKM_SANDBOX/xdg-state"
+export AKM_CONFIG_DIR="$AKM_SANDBOX/config"
+export AKM_CACHE_DIR="$AKM_SANDBOX/cache"
+export AKM_DATA_DIR="$AKM_SANDBOX/data"
+export AKM_STATE_DIR="$AKM_SANDBOX/state"
+export AKM_BUNDLE_DIR="$AKM_SANDBOX/bundle"
+export TMPDIR="$AKM_SANDBOX/tmp"
+export TMP="$TMPDIR"
+export TEMP="$TMPDIR"
+export HF_HOME="$AKM_SANDBOX/huggingface"
+export GH_CONFIG_DIR="$AKM_SANDBOX/gh"
+export GIT_CONFIG_GLOBAL="$AKM_SANDBOX/gitconfig"
+export GIT_CONFIG_NOSYSTEM=1
+export NPM_CONFIG_USERCONFIG="$AKM_SANDBOX/npmrc"
+export npm_config_cache="$AKM_SANDBOX/npm-cache"
+export AKM_FORCE_SETUP_TMP_STASH=1
+export AKM_FORCE_INIT_TMP_STASH=1
+
+unset AKM_VERBOSE AKM_DEBUG AKM_REGISTRY_URL AKM_NPM_REGISTRY
+unset AKM_LLM_API_KEY AKM_EMBED_API_KEY AKM_NO_AUTO_MIGRATE
+unset AKM_EMBED_DETERMINISTIC AKM_UPGRADE_SKIP_CHECKSUM
+unset GITHUB_TOKEN GH_TOKEN OPENAI_API_KEY ANTHROPIC_API_KEY
+unset OPENCODE_API_KEY X_BEARER_TOKEN X_RSS_TEMPLATE
+
+mkdir -p \
+  "$HOME" "$XDG_CONFIG_HOME" "$XDG_CACHE_HOME" "$XDG_DATA_HOME" \
+  "$XDG_STATE_HOME" "$AKM_CONFIG_DIR" "$AKM_CACHE_DIR" \
+  "$AKM_DATA_DIR" "$AKM_STATE_DIR" "$AKM_BUNDLE_DIR" "$TMPDIR" \
+  "$HF_HOME" "$GH_CONFIG_DIR" "$npm_config_cache"
+
+akm() { "$AKM_BIN" "$@"; }
+```
+
+For source-entrypoint testing only:
+
+```sh
+akm() { bun "$REPO/src/cli.ts" "$@"; }
+```
+
+### 3.2 Verify isolation before mutation
+
+`config path --all` is a read-only recovery surface and works before config
+exists.
+
+```sh
+akm config path --all --format json >"$AKM_SANDBOX/paths.json"
+jq -e --arg root "$AKM_SANDBOX/" \
+  'all(to_entries[]; (.value | tostring | startswith($root)))' \
+  "$AKM_SANDBOX/paths.json"
+```
+
+- [ ] **[CORE]** Every reported path starts with `$AKM_SANDBOX/`.
+- [ ] **[CORE]** `akm --version` matches `jq -r .version package.json`.
+- [ ] **[CORE]** No real provider/agent credential remains in `env`.
+
+Stop immediately if a path escapes the sandbox.
+
+### 3.3 Deterministic non-interactive setup
+
+Do not use `setup --yes` to seed ranking checks. It can perform host-dependent
+environment/agent detection. Avoid scaffolding so fixture counts remain exact.
+
+```sh
+akm setup \
+  --config '{"semanticSearchMode":"off","registries":[]}' \
+  --dir "$AKM_BUNDLE_DIR" \
+  --no-init \
+  --format json >"$AKM_SANDBOX/setup.json"
+
+jq -e --arg dir "$AKM_BUNDLE_DIR" \
+  '.written == true and .bundleDir == $dir' \
+  "$AKM_SANDBOX/setup.json"
+test ! -e "$AKM_BUNDLE_DIR/skills"
+```
+
+- [ ] **[CORE]** Setup exits `0`, writes only sandbox config, and does not
+      scaffold under `--no-init`.
+- [ ] **[CORE]** `config list` contains `configVersion: "0.9.0"`, `bundles`, and
+      `defaultBundle`; retired root keys are absent.
+
+### 3.4 Classified-error helper
+
+Use this only for thrown/classified failures. `--quiet` keeps stderr to one JSON
+envelope.
+
+```sh
+expect_error() {
+  expected_status="$1"
+  expected_code="$2"
+  shift 2
+
+  set +e
+  akm --quiet "$@" \
+    >"$AKM_SANDBOX/error.stdout" \
+    2>"$AKM_SANDBOX/error.stderr"
+  actual_status=$?
+  set -e
+
+  test "$actual_status" -eq "$expected_status"
+  test ! -s "$AKM_SANDBOX/error.stdout"
+  jq -e --arg code "$expected_code" \
+    '.ok == false and .code == $code and (.error | type == "string")' \
+    "$AKM_SANDBOX/error.stderr"
+}
+```
+
+Do not use this helper for health warnings/failures, lint findings,
+workflow/task/agent domain failures, or blocked migration plans. Those emit a
+normal result on stdout with a nonzero status.
+
+### 3.5 Byte snapshot helper
+
+```sh
+snapshot_tree() {
+  root="$1"
+  output="$2"
+  (
+    cd "$root"
+    find . -type f -print0 | LC_ALL=C sort -z | xargs -0 sha256sum
+  ) >"$output"
+}
+```
+
+On platforms without `sha256sum`, use the native SHA-256 utility and record it.
+For failed stateful commands, snapshot config, lockfile, bundle, cache, data,
+state, and event cursor, not only asset files.
+
+---
+
+## 4. Fixtures and Local Services
+
+### 4.1 Exact ranking baseline
+
+Copy fixture contents, including dotfiles, without setup scaffolding:
+
+```sh
+cp -R "$REPO/tests/fixtures/stashes/ranking-baseline/." "$AKM_BUNDLE_DIR/"
+
+for entry in agents commands knowledge skills MANIFEST.json; do
+  test -e "$AKM_BUNDLE_DIR/$entry"
+done
+test ! -e "$AKM_BUNDLE_DIR/scripts"
+
+akm index --full --format json >"$AKM_SANDBOX/index-baseline.json"
+jq -e '.totalEntries == 18 and .verification.ok == true' \
+  "$AKM_SANDBOX/index-baseline.json"
+
+akm info --format json | jq -e '
+  .indexStats.entryCount == 18 and
+  .indexStats.byType == {
+    "skill": 4,
+    "knowledge": 10,
+    "command": 2,
+    "agent": 2
+  }
+'
+```
+
+- [ ] **[CORE]** The fixture itself has exactly `agents`, `commands`,
+      `knowledge`, `skills`, and `MANIFEST.json` at its root.
+- [ ] **[CORE]** Full index reports exactly 18 entries and exact type counts.
+
+Stable refs:
+
+| Type | Ref |
+| --- | --- |
+| skill | `skills/k8s-deploy` |
+| skill | `skills/docker-homelab` |
+| knowledge | `knowledge/incident-response-runbook` |
+| agent | `agents/code-reviewer` |
+| command | `commands/release-manager` |
+
+### 4.2 Supplemental manual-QA bundle
+
+Copy this only after exact ranking assertions:
+
+```sh
+cp -R "$REPO/tests/fixtures/manual-qa/bundle/." "$AKM_BUNDLE_DIR/"
+akm index
+akm show knowledge/qa-guide | jq -e '.name == "qa-guide"'
+akm show workflows/typed-route | jq -e '.type == "workflow"'
+akm show tasks/manual-success | jq -e '.type == "task"'
+```
+
+It supplies `.meta`, typed/gated workflows, command tasks, and fake-agent input
+assets. It contains no credentials.
+
+### 4.3 Start controlled fixture services
+
+The service binds only to `127.0.0.1`, records route/model/count/presence
+metadata, and exposes chat, embedding, registry, and website routes.
+
+```sh
+export AKM_QA_SERVICE_META="$AKM_SANDBOX/service.json"
+export AKM_QA_SERVICE_LOG="$AKM_SANDBOX/service-requests.jsonl"
+export AKM_QA_SITE_VERSION="$AKM_SANDBOX/site-version.txt"
+printf 'v1\n' >"$AKM_QA_SITE_VERSION"
+
+bun "$REPO/tests/fixtures/manual-qa/fake-services.ts" \
+  "$AKM_QA_SERVICE_META" \
+  "$AKM_QA_SERVICE_LOG" \
+  "$AKM_QA_SITE_VERSION" \
+  >"$AKM_SANDBOX/service.stdout" \
+  2>"$AKM_SANDBOX/service.stderr" &
+export AKM_QA_SERVICE_PID=$!
+
+for _ in $(seq 1 100); do
+  test -s "$AKM_QA_SERVICE_META" && break
+  kill -0 "$AKM_QA_SERVICE_PID"
+  sleep 0.05
+done
+test -s "$AKM_QA_SERVICE_META"
+
+export AKM_QA_BASE_URL="$(jq -r .baseUrl "$AKM_QA_SERVICE_META")"
+export AKM_QA_CHAT_URL="$(jq -r .chat.ok "$AKM_QA_SERVICE_META")"
+export AKM_QA_PROPOSAL_URL="$(jq -r .chat.proposal "$AKM_QA_SERVICE_META")"
+export AKM_QA_EMBED_URL="$(jq -r .embeddings "$AKM_QA_SERVICE_META")"
+export AKM_QA_REGISTRY_URL="$(jq -r .registry "$AKM_QA_SERVICE_META")"
+export AKM_QA_WEBSITE_URL="$(jq -r .website "$AKM_QA_SERVICE_META")"
+```
+
+- [ ] **[SERVICE]** Metadata appears within five seconds and all endpoints are
+      loopback.
+- [ ] **[SERVICE]** Request logs contain no authorization or prompt values.
+
+Loopback website ingestion needs command-scoped `NODE_ENV=test` because
+production correctly blocks private hosts. That proves crawler protocol, not
+production SSRF behavior.
+
+### 4.4 Configure fake agent engines
+
+```sh
+export AKM_QA_BUN="$(command -v bun)"
+export AKM_QA_FAKE_AGENT="$REPO/tests/fixtures/manual-qa/fake-agent.ts"
+
+agent_engine_json() {
+  mode="$1"
+  shift
+  extra='[]'
+  if test "$#" -gt 0; then
+    extra="$(printf '%s\n' "$@" | jq -R . | jq -s .)"
+  fi
+  jq -nc \
+    --arg bin "$AKM_QA_BUN" \
+    --arg script "$AKM_QA_FAKE_AGENT" \
+    --arg mode "$mode" \
+    --argjson extra "$extra" \
+    '{kind:"agent",platform:"opencode",bin:$bin,args:([$script,$mode] + $extra)}'
+}
+
+akm config set engines.qa-agent "$(agent_engine_json success)" >/dev/null
+akm config set engines.qa-agent-fail "$(agent_engine_json fail)" >/dev/null
+akm config set engines.qa-agent-capture "$(agent_engine_json capture)" >/dev/null
+akm config set engines.qa-agent-secret "$(agent_engine_json echo-secret)" >/dev/null
+akm config set engines.qa-judge-pass "$(agent_engine_json judge-pass)" >/dev/null
+akm config set engines.qa-judge-reject "$(agent_engine_json judge-reject)" >/dev/null
+akm config set defaults.engine qa-agent >/dev/null
+akm config set workflow.judgeEngine qa-judge-pass >/dev/null
+
+export AKM_QA_SIGNAL_MARKER="$AKM_SANDBOX/fake-agent.signal"
+akm config set engines.qa-agent-sleep \
+  "$(agent_engine_json sleep 10000 "$AKM_QA_SIGNAL_MARKER")" >/dev/null
+akm config set engines.qa-agent-sleep.timeoutMs 100 >/dev/null
+```
+
+### 4.5 Configure fake LLM and embedding engines
+
+Run after starting fixture services:
+
+```sh
+export QA_LLM_KEY='manual-qa-not-a-real-secret'
+
+akm config set engines.qa-chat "$(jq -nc \
+  --arg endpoint "$AKM_QA_CHAT_URL" \
+  '{kind:"llm",endpoint:$endpoint,model:"qa-model",apiKey:"$QA_LLM_KEY",timeoutMs:1000}')" >/dev/null
+akm config set defaults.llmEngine qa-chat >/dev/null
+
+akm config set embedding "$(jq -nc \
+  --arg endpoint "$AKM_QA_EMBED_URL" \
+  '{provider:"openai",endpoint:$endpoint,model:"qa-embedding",dimension:4,batchSize:4}')" >/dev/null
+```
+
+### 4.6 Seed proposal cases
+
+```sh
+bun "$REPO/tests/fixtures/manual-qa/seed-proposals.ts" \
+  "$AKM_BUNDLE_DIR" >"$AKM_SANDBOX/proposals.json"
+akm index
+jq -e '.update.id and .newAsset.id and .emptyDiff.id and .defer.id' \
+  "$AKM_SANDBOX/proposals.json"
+```
+
+The seeder creates a fixed update, new asset, empty diff, and deferred candidate.
+It is destructive and must target only the sandbox.
+
+---
+
+## 5. Fast Offline Pass
+
+The fast gate uses no network, model download, provider token, agent process,
+scheduler, or migration. Run:
+
+| Order | Required coverage |
+| ---: | --- |
+| 1 | Sections 3.1-3.3: sandbox and deterministic setup |
+| 2 | Section 4.1: exact ranking baseline |
+| 3 | Section 6.1: version/root/help surface |
+| 4 | Sections 7.1-7.4: index/search/curate/show |
+| 5 | Sections 8.1-8.5: representative formats and errors |
+| 6 | Sections 10.1-10.3: local remember/import writes |
+| 7 | Sections 11.1-11.3: env/secret redaction |
+| 8 | Section 12.1: lint detect/fix/idempotence |
+| 9 | Section 13.1: feedback/log smoke |
+
+Success criteria:
+
+- [ ] Every **[CORE]** check passes.
+- [ ] A second index/read pass preserves exact fixture counts and ranking.
+- [ ] No secret fixture value appears in output, logs, reports, config, or events.
+- [ ] No file outside `$AKM_SANDBOX` changes after setup begins.
+
+---
+
+## 6. Startup, Setup, Help, and Config
+
+### 6.1 Version, root help, and command help
+
+```sh
+test "$(akm --version)" = "$(jq -r .version "$REPO/package.json")"
+akm --help >"$AKM_SANDBOX/root-help.txt"
+
+for command in \
+  setup index health info bundle upgrade search curate show workflow \
+  remember import sync clone registry migrate config feedback log agent \
+  lint improve proposal help hints completions env secret task; do
+  test "$(grep -Ec "^  ${command}[[:space:]]{2,}" "$AKM_SANDBOX/root-help.txt")" -eq 1
+```
+
+- [ ] **[CORE]** Version matches `package.json` exactly.
+- [ ] **[CORE]** Root help lists every command above exactly once and includes
+      `migrate`.
+- [ ] **[CORE]** Root help does not list retired top-level `init`, `add`, `list`,
+      `remove`, `update`, `wiki`, `mv`, `history`, `graph`, `lessons`, `extract`,
+      or `propose`.
+- [ ] **[CORE]** Bare `akm` and `akm help` print the sectioned overview without
+      reading or rewriting invalid config.
+- [ ] **[CORE]** `help agents`, `help agents --full`, `hints`, and
+      `hints --detail brief` are nonempty and have the expected relative detail.
+- [ ] **[LOCAL]** `help bundle|env|secret|workflow|task|proposal` agrees with the
+      corresponding `--help` command tree.
+- [ ] **[LOCAL]** Deep usage includes the full prefix, such as `akm task run`.
+- [ ] **[LOCAL]** Misspelled command/flag suggestions are concise and contain no
+      ANSI controls inside JSON.
+
+### 6.2 Non-interactive setup
+
+- [ ] **[LOCAL]** `setup --yes` in a second sandbox runs without prompts,
+      initializes a bundle, and is idempotent on the second run.
+- [ ] **[LOCAL]** JSON and YAML passed through `setup --from` normalize to
+      equivalent config.
+- [ ] **[LOCAL]** `--from ... --yes --dir ... --no-init` writes config but does
+      not scaffold.
+- [ ] **[LOCAL]** Passing both `--from` and `--config` exits `2` with
+      `INVALID_FLAG_VALUE` before write.
+- [ ] **[LOCAL]** Malformed JSON/YAML or invalid shape exits `78` with
+      `INVALID_CONFIG_FILE`, preserves prior config bytes, and prints no stack.
+- [ ] **[SERVICE]** `setup --probe` against the fixture `.chat.probe` endpoint
+      verifies connectivity before write and records no credential value.
+- [ ] **[LOCAL]** `setup --config '{}' --dir "$HOME" --no-init` rejects the
+      unsafe root. `--no-init` must not bypass target safety.
+- [ ] **[LOCAL]** Invalid embedding shape is a config error, not exit `70`.
+
+### 6.3 Interactive setup
+
+Use a real TTY in the sandbox.
+
+- [ ] **[LOCAL]** Setup explains semantic download, small-model setup, agent
+      engines, registries, sources, and task review.
+- [ ] **[LOCAL]** Cancel at each boundary; config/bundle stay byte-identical
+      unless final save was confirmed.
+- [ ] **[LOCAL]** Redirected stdin without a noninteractive flag exits `2` with
+      `NON_INTERACTIVE_REQUIRES_YES` instead of hanging.
+- [ ] **[AI]** Detected CLIs/model servers are suggestions only; selecting or
+      skipping persists exactly the reviewed choice.
+
+### 6.4 Config management
+
+```sh
+akm config list --format json | jq -e '.bundles and .defaultBundle'
+akm config get semanticSearchMode | jq -e '. == "off"'
+akm config set semanticSearchMode auto --silent >"$AKM_SANDBOX/silent.out"
+test ! -s "$AKM_SANDBOX/silent.out"
+akm config unset semanticSearchMode --silent >"$AKM_SANDBOX/silent.out"
+test ! -s "$AKM_SANDBOX/silent.out"
+```
+
+- [ ] **[CORE]** `list|get|set|unset` preserve unrelated keys and return JSON
+      values; use `jq -r` for string comparisons.
+- [ ] **[CORE]** `--silent` changes config with empty stdout; errors still emit.
+- [ ] **[LOCAL]** Objects deep-merge, arrays replace, and `unset` is deletion.
+- [ ] **[LOCAL]** Generic walker cannot set/unset `configVersion`.
+- [ ] **[LOCAL]** `defaultWriteTarget` rejects unknown/disabled bundles and can
+      be set/unset for a configured writable bundle.
+- [ ] **[LOCAL]** Retired config roots and defaults fail without rewrite.
+- [ ] **[LOCAL]** API key references accept `$VAR`/`${VAR}` only; config/list/info
+      never materialize values.
+- [ ] **[LOCAL]** Concurrent independent `config set` processes preserve both
+      changes or one fails cleanly; JSON stays valid and no temp file remains.
+- [ ] **[LOCAL]** `config path --all` honors output formatting. Bare
+      `config path` is a raw path primitive; if format/output are ignored it
+      must warn explicitly. Silent ignoring is a failure.
+
+### 6.5 Help migration notes
+
+- [ ] **[CORE]** `help migrate 0.6.0`, `v0.6.0-rc1`, and `latest` print bundled
+      guidance without config startup.
+- [ ] **[CORE]** Unknown version lists available notes gracefully.
+- [ ] **[CORE]** Missing version exits `2` with `MISSING_REQUIRED_ARGUMENT`.
+- [ ] **[LOCAL]** Global flags do not steal the version positional.
+
+### 6.6 Completions
+
+```sh
+akm completions --format yaml \
+  >"$AKM_SANDBOX/akm-completion.bash" \
+  2>"$AKM_SANDBOX/completion.stderr"
+bash -n "$AKM_SANDBOX/akm-completion.bash"
+grep -q "'--format' has no effect" "$AKM_SANDBOX/completion.stderr"
+```
+
+- [ ] **[CORE]** Generated Bash parses; warning stays on stderr.
+- [ ] **[LOCAL]** Dynamically source it and verify each group returns only real
+      subcommands. Registry completion is `add list remove`.
+- [ ] **[LOCAL]** Unsupported shell exits `2` with structured usage error.
+- [ ] **[LOCAL]** `--install` writes only in sandbox completion paths, emits no
+      script on stdout, and reports destination on stderr.
+
+### 6.7 Upgrade check
+
+`upgrade --check` is network-backed, not part of first-run/offline coverage.
+
+- [ ] **[LIVE]** With GitHub credentials cleared, check reports current/latest,
+      boolean availability, and install method without mutation.
+- [ ] **[LIVE]** Repeat with a disposable token and prove redaction.
+- [ ] **[LIVE]** Source/dist may report `installMethod: "unknown"`; do not count
+      that as standalone-upgrade success.
+
+---
+
+## 7. Index, Search, Curate, and Show
+
+### 7.1 Index
+
+```sh
+akm index --full --format json >"$AKM_SANDBOX/index-full.json"
+akm index --verbose --format json \
+  >"$AKM_SANDBOX/index-verbose.json" \
+  2>"$AKM_SANDBOX/index-verbose.stderr"
+jq -e . "$AKM_SANDBOX/index-verbose.json"
+test -s "$AKM_SANDBOX/index-verbose.stderr"
+```
+
+- [ ] **[CORE]** Full index reports 18 baseline entries, successful verification,
+      scanned directories, and timings.
+- [ ] **[CORE]** Immediate incremental index preserves count and skips unchanged
+      directories.
+- [ ] **[CORE]** Verbose progress is stderr-only; stdout remains valid JSON.
+- [ ] **[LOCAL]** Add, modify, rename, and delete one asset; new bytes appear and
+      removed bytes never remain discoverable.
+- [ ] **[LOCAL]** Malformed workflow warns/skips only that file.
+- [ ] **[LOCAL]** `--clean --dry-run` reports stale refs without deleting them;
+      normal clean removes them. Account for normal indexing discovering a
+      deletion before clean runs.
+- [ ] **[LOCAL]** `--dry-run` without `--clean` exits `2`.
+- [ ] **[LOCAL]** Removed `--enrich`/`--re-enrich` exit `2` with guidance.
+- [ ] **[LOCAL]** SIGINT/SIGTERM release locks, preserve prior valid index, and
+      allow the next index.
+- [ ] **[LOCAL]** Two simultaneous full indexes serialize or return typed lock
+      failure, never DB corruption/permanent lock.
+
+### 7.2 Search
+
+```sh
+akm search k8s-deploy \
+  --detail full --format json |
+  jq -e '
+    .hits[0].ref == "skills/k8s-deploy" and
+    .hits[0].type == "skill" and
+    .hits[0].score >= 0 and .hits[0].score <= 1
+  '
+
+json_count="$(akm search docker | jq '.hits | length')"
+jsonl_count="$(akm search docker --format jsonl | jq -s 'length')"
+test "$json_count" -gt 0
+test "$json_count" -eq "$jsonl_count"
+```
+
+- [ ] **[CORE]** Exact/phrase queries rank expected fixtures first.
+- [ ] **[CORE]** `--type skill` returns only skills. Unknown free-form type
+      returns zero hits, not usage failure.
+- [ ] **[CORE]** Empty search browses all 18 baseline entries deterministically.
+- [ ] **[CORE]** JSON and JSONL hit counts match.
+- [ ] **[CORE]** No-result search exits `0` with empty hits.
+- [ ] **[LOCAL]** Prefix queries (`knowledge/`, `memories/projectA/`,
+      `<bundle>//`) enforce exact boundaries; `projectAlpha/` does not leak.
+- [ ] **[LOCAL]** Named bundle/local/registry/all modes keep local `hits` and
+      `registryHits` separate.
+- [ ] **[LOCAL]** Repeated valid filters AND-join. Missing/malformed/unknown or
+      conflicting filters fail without broadening scope.
+- [ ] **[LOCAL]** Scoped memory appears only for matching filters; unscoped
+      assets disappear once filters are supplied.
+- [ ] **[LOCAL]** Belief current/historical/all partitions state correctly.
+- [ ] **[LOCAL]** Proposed quality and sessions are excluded by default and
+      included only through explicit flags.
+- [ ] **[LOCAL]** A successful read advances usage-event state in
+      `$AKM_DATA_DIR` only.
+- [ ] **[LOCAL]** Zero/negative/fractional/prefix numeric limits (`2x`), overflow,
+      and conflicting repeats are rejected. `parseInt` prefix acceptance fails.
+
+### 7.3 Curate
+
+```sh
+akm curate "docker homelab" --detail full --format json |
+  jq -e '.items[0].ref == "skills/docker-homelab" and (.summary | type == "string")'
+```
+
+- [ ] **[CORE]** Returns `{items,query,summary}` and actionable follow-ups.
+- [ ] **[CORE]** Empty query exits `2`, `MISSING_REQUIRED_ARGUMENT`.
+- [ ] **[LOCAL]** Type, limit, source, detail, agent shape, related refs, and
+      family collapse are correct.
+- [ ] **[LOCAL]** Invalid limits match search strictness.
+- [ ] **[SERVICE]** Registry-only items have install guidance and no local
+      path/editability.
+
+### 7.4 Show, fragments, scope, and meta
+
+```sh
+akm show skills/k8s-deploy --format json |
+  jq -e '
+    .type == "skill" and
+    .ref == "skills/k8s-deploy" and
+    (.path | startswith("/")) and
+    (.content | contains("Kubernetes Deployment"))
+  '
+
+akm show 'knowledge/incident-response-runbook#severity-levels' \
+  --format json |
+  jq -e '(.content | contains("SEV1")) and ((.content | contains("Escalation Path")) | not)'
+```
+
+- [ ] **[CORE]** Default/full/agent/summary retain canonical ref; human/agent
+      shapes expose path/editability as documented.
+- [ ] **[CORE]** Valid fragment returns only that section. Invalid fragment exits
+      `1`, `ASSET_NOT_FOUND`, and lists slugs.
+- [ ] **[CORE]** Missing asset exits `1` with structured stderr.
+- [ ] **[LOCAL]** `.md` suffix normalization preserves durable identity.
+- [ ] **[LOCAL]** Removed `toc`, `--scope`, and type-colon refs fail with useful
+      migration guidance.
+- [ ] **[LOCAL]** `show meta`, `meta:<name>`, and `<bundle>//meta` direct-read
+      `.meta`; those docs never appear in search.
+- [ ] **[LOCAL]** Qualified duplicates return selected bundle bytes; unqualified
+      follows default then installation precedence.
+- [ ] **[LOCAL]** Scope match resolves; mismatch returns not-found without leak.
+- [ ] **[LOCAL]** Read-only source reports `editable:false` plus edit hint;
+      writable local reports `true`.
+- [ ] **[LOCAL]** Show is local-index only and does not remote-fallback.
+
+---
+
+## 8. Output, Errors, and Exit Codes
+
+### 8.1 Exit and channel oracle
+
+| Outcome | Exit | Channel |
+| --- | ---: | --- |
+| Success | `0` | Normal payload on stdout |
+| Not found/general failure | `1` | Classified stderr or domain stdout result |
+| Usage/bad input | `2` | Structured JSON stderr |
+| Health warning | `4` | Health stdout result |
+| Unexpected throw | `70` | Structured internal stderr |
+| Config error | `78` | Structured JSON stderr |
+
+Domain-result exceptions:
+
+| Command | Nonzero behavior |
+| --- | --- |
+| `health` | Warn `4`, fail `1`; result stays on stdout |
+| `lint --fail-on-flagged` | Exit `1`; lint result stays on stdout |
+| `workflow run` | Failure/rejection/timeout emits workflow stdout result |
+| `agent` | Dispatch failure exits `1` with `agent-result` stdout |
+| `task run` | Blocked/failed `1`, command config failure `78`; child code in detail |
+| `migrate` | Child status preserved; progress can precede final formatted plan |
+| `env run` / `secret run` | Raw child streams and exact child status |
+
+### 8.2 Six formats
+
+```sh
+akm info --format json | jq -e .
+akm info --format jsonl | jq -e .
+akm info --format yaml | bun -e '
+  import { parse } from "yaml";
+  const value = parse(await Bun.stdin.text());
+  if (!value?.version) process.exit(1);
+'
+akm info --format text >"$AKM_SANDBOX/info.txt"
+akm info --format md >"$AKM_SANDBOX/info.md"
+akm info --format html >"$AKM_SANDBOX/info.html"
+grep -qi '<html' "$AKM_SANDBOX/info.html"
+```
+
+- [ ] **[CORE]** JSON/JSONL/YAML parse; text is plain; Markdown is not JSON;
+      HTML is self-contained.
+- [ ] **[LOCAL]** Repeat representative search/show/config/bundle/log/health/task/
+      proposal/workflow/setup/migrate commands in supported formats.
+- [ ] **[LOCAL]** Global flags work before/after command and with space/equals.
+- [ ] **[LOCAL]** Persisted output defaults apply only when CLI flags are absent.
+
+### 8.3 Shape, detail, and output destination
+
+- [ ] **[CORE]** Brief/normal/full increase detail without identity drift.
+- [ ] **[CORE]** Summary succeeds only on show; all other commands reject it
+      before side effects with exit `2`, `INVALID_SHAPE_VALUE`.
+- [ ] **[LOCAL]** Agent shape keeps action fields and strips non-action metadata.
+- [ ] **[LOCAL]** `show --format md --output <file>` writes file, empty stdout.
+- [ ] **[LOCAL]** Output replacement is atomic; unwritable/directory target does
+      not truncate existing content.
+- [ ] **[LOCAL]** JSONL stays on stdout and does not create `--output` file.
+- [ ] **[LOCAL]** Health report HTML data matches JSON report data.
+
+### 8.4 Format-exempt commands
+
+`completions`, `help`, `help migrate`, `env path`, `env run`, and `secret run`
+do not emit normal result envelopes.
+
+- [ ] **[CORE]** Passing format emits one stderr warning and preserves raw
+      payload/child streams.
+- [ ] **[LOCAL]** Child help/format flags after `--` reach child, not AKM parser.
+- [ ] **[LOCAL]** Interactive setup is terminal UI; scripted setup is formatted.
+
+### 8.5 Error gauntlet
+
+```sh
+expect_error 2 MISSING_REQUIRED_ARGUMENT curate ""
+expect_error 1 ASSET_NOT_FOUND show skills/does-not-exist
+expect_error 2 UNKNOWN_FLAG info --totally-bogus
+expect_error 2 INVALID_FORMAT_VALUE info --format xml
+expect_error 2 INVALID_DETAIL_VALUE info --detail maximum
+expect_error 2 INVALID_SHAPE_VALUE search docker --shape summary
+expect_error 2 MISSING_REQUIRED_ARGUMENT help migrate
+expect_error 2 INVALID_FLAG_VALUE completions --shell zsh
+```
+
+- [ ] **[CORE]** Classified throw leaves stdout empty and emits one stderr JSON
+      object with `ok:false`, `error`, `code`, optional hint.
+- [ ] **[CORE]** No ordinary failure prints stack, bare `Error:`, ANSI JSON, or
+      output-shape registration failure.
+- [ ] **[LOCAL]** Errors stay JSON under text/yaml/md/html/output flags; no error
+      output file is created.
+- [ ] **[LOCAL]** Test-harness unclassified throw exits `70`; `AKM_DEBUG=1` adds
+      stack only on stderr.
+- [ ] **[LOCAL]** Unknown commands/bare groups exit `2` with concise current hint.
+
+---
+
+## 9. Bundles, Adapters, Sources, and Registries
+
+### 9.1 Bundle create
+
+Use a second sandbox or disposable secondary paths.
+
+- [ ] **[LOCAL]** First create scaffolds canonical dirs/current config/default.
+- [ ] **[LOCAL]** `--dir <secondary>` backfills without changing existing
+      default; `--set-default` changes it explicitly.
+- [ ] **[LOCAL]** Repeat is idempotent and preserves files.
+- [ ] **[LOCAL]** `$HOME`, root, config, cache, data, and state roots are rejected
+      even if no scaffolding work would occur.
+- [ ] **[LOCAL]** Env/secrets paths have owner-only POSIX permissions.
+- [ ] **[LOCAL]** Temp authorization uses `AKM_FORCE_INIT_TMP_STASH`, not setup's
+      separate variable.
+
+### 9.2 Identity, precedence, and enabled state
+
+```sh
+mkdir -p "$AKM_SANDBOX/bundle-a" "$AKM_SANDBOX/bundle-b"
+akm bundle add "$AKM_SANDBOX/bundle-a" --name bundle-a
+akm bundle add "$AKM_SANDBOX/bundle-b" --name bundle-b
+akm remember "body A" --name shared --bundle bundle-a
+akm remember "body B" --name shared --bundle bundle-b
+akm show bundle-a//memories/shared | jq -e '.content | contains("body A")'
+akm show bundle-b//memories/shared | jq -e '.content | contains("body B")'
+```
+
+- [ ] **[LOCAL]** Qualified identity remains stable through index/search/show.
+- [ ] **[LOCAL]** Unqualified resolution follows default then installation
+      precedence, never random duplicate.
+- [ ] **[LOCAL]** Names obey slug rules; `team/sync-qa` is rejected.
+- [ ] **[LOCAL]** Kind filter accepts exact supported kinds; `local`/`managed`
+      groupings exit `2`.
+- [ ] **[LOCAL]** `bundle show` reports one descriptor/components/effective
+      writable state.
+- [ ] **[LOCAL]** `enabled:false` removes source from index/search/refresh/write
+      selection. Singular update/write must not bypass disabled state.
+
+### 9.3 Built-in adapter matrix
+
+| Adapter | Fixture |
+| --- | --- |
+| `website-snapshot` | `tests/fixtures/bundles/website-snapshot` |
+| `agent-skills` | `tests/fixtures/bundles/agent-skills` |
+| `claude` | `tests/fixtures/bundles/claude` |
+| `opencode` | `tests/fixtures/bundles/opencode` |
+| `dotenv` | `tests/fixtures/bundles/dotenv` |
+| `akm-workflow` | `tests/fixtures/bundles/akm-workflow` |
+| `akm-task` | `tests/fixtures/bundles/akm-task` |
+| `llm-wiki` | `tests/fixtures/bundles/llm-wiki` |
+| `akm` | `tests/fixtures/stashes/ranking-baseline` |
+| `okf` | `tests/fixtures/bundles/okf-sample-v2` |
+| `generic-files` | `tests/fixtures/bundles/generic-files` |
+
+For each adapter:
+
+- [ ] **[LOCAL]** Add copied fixture under unique name; run bundle show, full
+      index, search, representative show, and lint.
+- [ ] **[LOCAL]** Expected component wins precedence without double indexing.
+- [ ] **[LOCAL]** Placement/ref/type/rendering match format-family goldens.
+- [ ] **[LOCAL]** Intentional invalid files produce only named lint findings.
+- [ ] **[LOCAL]** Read-only adapter rejects write before mutation.
+
+### 9.4 LLM Wiki adapter
+
+```sh
+cp -R "$REPO/tests/fixtures/bundles/llm-wiki" "$AKM_SANDBOX/sample-wiki"
+akm bundle add "$AKM_SANDBOX/sample-wiki" --name sample-wiki
+akm bundle show sample-wiki --format json
+akm index --full
+akm show sample-wiki//pages/http-caching
+akm show sample-wiki//raw/2026-07-http-rfc
+akm lint --dir "$AKM_SANDBOX/sample-wiki"
+```
+
+- [ ] **[LOCAL]** Adapter is `llm-wiki`; pages use `pageKind`, raw is
+      `wiki-source`.
+- [ ] **[LOCAL]** `schema.md`, `index.md`, `log.md` are not indexed concepts.
+- [ ] **[LOCAL]** Intentional broken xref is reported.
+- [ ] **[LOCAL]** Removing schema or pages prevents recognition.
+- [ ] **[LOCAL]** No network/LLM request occurs.
+- [ ] **[LOCAL]** There is no `akm wiki`; agents write normal files.
+
+### 9.5 Filesystem source
+
+```sh
+mkdir -p "$AKM_SANDBOX/fs-source/knowledge"
+printf '%s\n' '# Filesystem Marker' '' 'qa-filesystem-source-marker' \
+  >"$AKM_SANDBOX/fs-source/knowledge/marker.md"
+akm bundle add "$AKM_SANDBOX/fs-source" --name fs-source
+akm bundle list --kind filesystem
+akm search qa-filesystem-source-marker --from fs-source
+```
+
+- [ ] **[LOCAL]** Add indexes in place with kind `filesystem`, writable true.
+- [ ] **[LOCAL]** Single update and update-all reconcile current files into the
+      index without provider hydration.
+- [ ] **[LOCAL]** Non-TTY remove requires `--yes`, removes ownership/index, and
+      leaves source files.
+- [ ] **[LOCAL]** Real path plus symlink alias does not create ambiguous owner or
+      duplicate durable refs.
+
+### 9.6 Git source
+
+Use a small disposable HTTPS/SSH repository. `file://` is rejected by design.
+
+- [ ] **[LIVE]** Inferred add clones/locks/configures/indexes read-only.
+- [ ] **[LIVE]** Branch/tag/ref pin resolves exact revision.
+- [ ] **[LIVE]** Change unique upstream marker, update by legal name, and prove
+      new bytes/revision. Exit zero alone is insufficient.
+- [ ] **[LIVE]** Force rematerializes complete content.
+- [ ] **[LIVE]** Declarative `--provider git` is config-only; first update
+      materializes and runs security audit.
+- [ ] **[LIVE]** Writable source pushes only under explicit policy; no-push never
+      contacts remote.
+- [ ] **[LIVE]** Plain `git+http` cannot bypass insecure transport gate.
+- [ ] **[LIVE]** Remove cleans AKM-owned config/lock/index/cache only.
+
+### 9.7 npm source
+
+Use a disposable package/version or controlled registry.
+
+- [ ] **[LIVE]** Inferred add materializes/locks/indexes read-only.
+- [ ] **[LIVE]** Scoped/unscoped refs, exact versions, dist-tags, malformed specs,
+      missing versions, auth, checksum/tar safety, and oversized archives behave
+      structurally.
+- [ ] **[LIVE]** Publish second unique marker/version; update proves new bytes.
+- [ ] **[LIVE]** Declarative provider is config-only; update makes managed.
+- [ ] **[LIVE]** `writable:true` is rejected.
+- [ ] **[LIVE]** Remove cleans all AKM-owned extraction roots only.
+
+### 9.8 Website source
+
+Production must reject loopback/private hosts:
+
+```sh
+expect_error 78 INVALID_CONFIG_FILE \
+  bundle add "$AKM_QA_WEBSITE_URL" --name private-site --allow-insecure-transport
+```
+
+Protocol-only fixture:
+
+```sh
+NODE_ENV=test akm bundle add "$AKM_QA_WEBSITE_URL" \
+  --name qa-site --allow-insecure-transport --max-pages 2 --max-depth 1
+NODE_ENV=test akm search qa-site --from qa-site
+```
+
+- [ ] **[SERVICE]** Production blocks private start/redirect hosts;
+      `--allow-insecure-transport` accepts transport risk only, not SSRF.
+- [ ] **[SERVICE]** Test-seam crawl respects page/depth/robots; request log proves
+      private path not fetched.
+- [ ] **[SERVICE]** Change site version to `v2`, named-update, and prove v2 bytes.
+      Stale-fallback success with v1 fails this gate.
+- [ ] **[SERVICE]** Failed first crawl leaves no config/cache/index/lock/success
+      event residue.
+- [ ] **[SERVICE]** Interrupted publication preserves previous complete snapshot.
+- [ ] **[SERVICE]** Update-all skips website; named update refreshes.
+- [ ] **[LIVE]** Repeat against controlled public HTTPS in production mode.
+- [ ] **[LIVE]** Specialized YouTube/Bluesky/X/feed fetchers use controlled data
+      or disposable credentials and retain safe fallback.
+
+### 9.9 Registry
+
+```sh
+expect_error 2 INVALID_FLAG_VALUE registry add "$AKM_QA_REGISTRY_URL" --name qa-registry
+akm registry add "$AKM_QA_REGISTRY_URL" --name qa-registry --allow-insecure-transport
+akm registry list | jq -e '.registries[] | select(.name == "qa-registry")'
+akm search kubernetes --from registry --detail full
+akm search kubernetes --from registry --assets --detail full
+akm registry remove qa-registry --yes
+```
+
+- [ ] **[SERVICE]** HTTP requires `--allow-insecure-transport` and warns.
+- [ ] **[SERVICE]** Duplicate URL is idempotent `added:false`; unknown remove is
+      exit `1`, `SOURCE_NOT_FOUND`.
+- [ ] **[SERVICE]** Registry hits remain `registryHits`, not local `hits`.
+- [ ] **[SERVICE]** Full hit exposes actionable `installRef`.
+- [ ] **[SERVICE]** `--assets` makes asset-level fixture result observable;
+      discarding provider asset hits is failure.
+- [ ] **[SERVICE]** Scores remain provider-local and may exceed one.
+- [ ] **[SERVICE]** Malformed/wrong schema/HTTP/timeout/stale/oversized response
+      does not poison other registries.
+- [ ] **[SERVICE]** Options require JSON object; malformed/non-object fails before
+      config mutation.
+- [ ] **[SERVICE]** Install uses `bundle add <installRef>`; no registry install
+      subcommand exists.
+
+### 9.10 Source failure atomicity and dangerous env
+
+```sh
+before_config="$(sha256sum "$AKM_CONFIG_DIR/config.json")"
+set +e
+akm bundle add "$REPO/tests/fixtures/manual-qa/dangerous-bundle" \
+  --name qa-dangerous </dev/null
+status=$?
+set -e
+test "$status" -eq 1
+test "$(sha256sum "$AKM_CONFIG_DIR/config.json")" = "$before_config"
+! akm bundle list --format json | jq -e '.sources[] | select(.name == "qa-dangerous")'
+```
+
+- [ ] **[LOCAL]** Inferred noninteractive add blocks raw dangerous env, rolls
+      back config/lock/cache/index, no success event/envelope.
+- [ ] **[LOCAL]** Allow-insecure permits reviewed fixture with warning.
+- [ ] **[LOCAL]** Non-`.env` file under env is ignored.
+- [ ] **[LOCAL]** Publisher lint suppression does not silently bypass untrusted
+      install safety; test suppression fixture separately.
+- [ ] **[LOCAL]** Declarative provider and later update receive equivalent audit.
+- [ ] **[LOCAL]** New dangerous key on update preserves previous complete source.
+- [ ] **[LOCAL]** A held WAL index reader observes only the prior generation
+      through a failed update; index/state main, WAL, and SHM inodes are not
+      replaced during compensation.
+- [ ] **[LOCAL]** Writable Git rejects physical-root/component symlink escapes,
+      a changed HEAD or dirty state at publication, and dangerous tracked,
+      untracked, ignored, filter-produced, or submodule materialization.
+- [ ] **[LOCAL]** Lock publication and rollback fence both exact raw bytes and
+      file mode; a concurrent chmod blocks publication without being reverted.
+- [ ] **[LOCAL]** A simulated durable index/state split is reported as
+      `index-state-generation`; after writers stop, `akm index --full` clears
+      the advisory and restores coherent searchable usage links.
+- [ ] **[LOCAL]** Corrupt/unreadable lock fails structurally; no managed/plain
+      reinterpretation or split state.
+- [ ] **[LOCAL]** Failed add/update/remove compare config, lock, cache, index,
+      source bytes, and event cursor, not only exit.
+
+---
+
+## 10. Writes, Import, Clone, and Sync
+
+### 10.1 Remember
+
+```sh
+akm remember "test memory body" --name test-memory
+akm show memories/test-memory | jq -e '.content | contains("test memory body")'
+expect_error 1 RESOURCE_ALREADY_EXISTS remember "duplicate" --name test-memory
+akm remember "replacement" --name test-memory --force
+printf 'stdin body\n' | akm remember --name from-stdin
+```
+
+- [ ] **[CORE]** Plain/stdin/force paths write one valid indexed memory and
+      preserve body bytes.
+- [ ] **[CORE]** Duplicate without force fails before mutation.
+- [ ] **[LOCAL]** Description/repeated tags/expiry/source/auto/nested path/xrefs
+      serialize once without nested frontmatter/duplicates.
+- [ ] **[LOCAL]** Scope-only memory is valid without tags and uses canonical
+      scope fields.
+- [ ] **[LOCAL]** Tag-bearing metadata with no resulting tag fails before write.
+- [ ] **[LOCAL]** Invalid absolute/traversal name/path, self/unresolved xref,
+      unknown bundle, retired target/stash flags fail before all side effects.
+- [ ] **[AI]** Enrich success/failure uses fake LLM and never silently writes
+      missing required metadata.
+
+### 10.2 Target precedence
+
+- [ ] **[LOCAL]** Explicit bundle wins over default write target, then default
+      bundle; no fallback to first writable source.
+- [ ] **[LOCAL]** Read-only/disabled/missing/unsupported targets reject before
+      write.
+- [ ] **[LOCAL]** Writable git target produces one complete boundary commit;
+      push requires writable + remote policy.
+- [ ] **[LOCAL]** Qualified source cannot redirect to conflicting target.
+
+### 10.3 Import
+
+```sh
+cat >"$AKM_SANDBOX/incoming.md" <<'EOF'
+---
+description: Imported manual QA document
+custom:
+  nested: preserved
+---
+# Imported Guide
+
+qa-import-marker
+EOF
+
+akm import "$AKM_SANDBOX/incoming.md" --name imported-guide
+akm import - --name imported-stdin <"$AKM_SANDBOX/incoming.md"
+```
+
+- [ ] **[CORE]** File/stdin import preserve custom frontmatter/body and produce
+      deterministic refs.
+- [ ] **[LOCAL]** Path/target/force/xref/supersession use same preflight/write
+      rules as remember.
+- [ ] **[LOCAL]** Malformed frontmatter fails losslessly; missing input/invalid
+      name leaves no partial file.
+- [ ] **[LOCAL]** Loopback URL production import exits `2` under SSRF policy;
+      no allow-insecure bypass exists.
+- [ ] **[LIVE]** Controlled public HTTPS import follows bounded redirects,
+      converts content, derives URL-path name, blocks private redirect.
+
+### 10.4 Supersession
+
+- [ ] **[LOCAL]** Correction xrefs old asset; old gains superseded state/by ref
+      while preserving unrelated metadata/body.
+- [ ] **[LOCAL]** Belief-current hides old; all can return both.
+- [ ] **[LOCAL]** Unresolved/self supersession changes neither file.
+- [ ] **[LOCAL]** Cross-bundle non-applicable demotion is reported explicitly.
+- [ ] **[DESTRUCTIVE]** Failure between correction and demotion has pinned
+      all-or-nothing behavior; undocumented half-correction fails.
+
+### 10.5 Clone
+
+- [ ] **[CORE]** Clone a skill and single file to unmanaged destination; skill
+      references copy recursively, source unchanged.
+- [ ] **[LOCAL]** Managed clone follows explicit/default/working target and
+      indexes immediately.
+- [ ] **[LOCAL]** Destination works without write target and conflicts with
+      bundle flag.
+- [ ] **[LOCAL]** Existing destination requires force; invalid rename/traversal/
+      missing source leaves no partial copy.
+- [ ] **[LIVE]** Clone from uninstalled controlled package caches but does not
+      register source.
+
+### 10.6 Sync
+
+```sh
+git -C "$AKM_BUNDLE_DIR" init
+git -C "$AKM_BUNDLE_DIR" config user.name 'AKM Manual QA'
+git -C "$AKM_BUNDLE_DIR" config user.email 'manual-qa@example.invalid'
+git -C "$AKM_BUNDLE_DIR" add .
+git -C "$AKM_BUNDLE_DIR" commit -m 'Manual QA baseline'
+
+akm remember "sync marker" --name sync-marker
+akm sync --no-push -m "Manual QA sync"
+git -C "$AKM_BUNDLE_DIR" show --stat --oneline -1
+```
+
+- [ ] **[LOCAL]** Non-git bundle returns structured skipped/no-op.
+- [ ] **[LOCAL]** Git commits sandbox changes/message and never pushes with
+      no-push.
+- [ ] **[LOCAL]** Named source uses legal slug such as `team-sync-qa`, not slash.
+- [ ] **[LOCAL]** Source literally named `json` remains selectable alongside
+      format flag.
+- [ ] **[LOCAL]** Whole-bundle staging policy is represented honestly; no claim
+      that unrelated dirty paths were excluded if they were committed.
+- [ ] **[LIVE]** Disposable writable remote pushes; read-only/no-remote commits
+      locally only; failed push retains complete local commit.
+
+### 10.7 Write concurrency, atomicity, and paths
+
+- [ ] **[LOCAL]** Two same-name remember creates: exactly one succeeds, one
+      already-exists; final is one complete payload.
+- [ ] **[LOCAL]** Repeat for import and content-bearing env create.
+- [ ] **[LOCAL]** Concurrent different-asset writes both survive/index.
+- [ ] **[LOCAL]** Read-only/unwritable/disk-full/path-is-directory failures leave
+      old bytes/index intact.
+- [ ] **[LOCAL]** Internal symlink resolves consistently; escaping symlink is
+      rejected and outside sentinel unchanged.
+- [ ] **[DESTRUCTIVE]** Kill replacement at publication boundaries; recovery is
+      old or new complete bytes, no temp/stale lock/truncation.
+
+---
+
+## 11. Env and Secret
+
+Use conspicuous dummy values only. AKM keeps env and secret values out of its
+structured results, but a child launched by `env run` or `secret run` owns its
+raw stdout/stderr and can print injected values.
+
+### 11.1 Create, list, path, and indexing
+
+```sh
+export QA_SECRET_VALUE='manual-qa-secret-not-a-credential'
+
+printf '%s\n' \
+  'QA_PUBLIC=manual-qa-public' \
+  'QA_SECOND=manual-qa-second' \
+  'QA_TOKEN=Bearer ${secret:qa-token}' \
+  >"$AKM_SANDBOX/qa-runtime.env"
+
+akm env create qa-runtime \
+  --from-file "$AKM_SANDBOX/qa-runtime.env" --format json \
+  >"$AKM_SANDBOX/env-create.json"
+printf '%s\n' "$QA_SECRET_VALUE" |
+  akm secret set secrets/qa-token --format json \
+    >"$AKM_SANDBOX/secret-set.json"
+
+akm env list --format json >"$AKM_SANDBOX/env-list.json"
+akm secret list --format json >"$AKM_SANDBOX/secret-list.json"
+akm index
+akm show env/qa-runtime --format json \
+  >"$AKM_SANDBOX/env-show.json"
+akm show secrets/qa-token --format json \
+  >"$AKM_SANDBOX/secret-show.json"
+
+jq -e 'any(.envs[]; .ref == "env/qa-runtime" and (.keys | index("QA_PUBLIC")))' \
+  "$AKM_SANDBOX/env-list.json"
+jq -e 'any(.secrets[]; .ref == "secrets/qa-token")' \
+  "$AKM_SANDBOX/secret-list.json"
+
+for capture in \
+  "$AKM_SANDBOX/env-create.json" \
+  "$AKM_SANDBOX/secret-set.json" \
+  "$AKM_SANDBOX/env-list.json" \
+  "$AKM_SANDBOX/secret-list.json" \
+  "$AKM_SANDBOX/env-show.json" \
+  "$AKM_SANDBOX/secret-show.json"; do
+  ! grep -F "$QA_SECRET_VALUE" "$capture"
+  ! grep -F 'manual-qa-public' "$capture"
+done
+```
+
+- [ ] **[CORE]** Env list exposes refs and key names only; secret list exposes
+      refs only. Values, comments, and absolute paths are absent.
+- [ ] **[CORE]** Env is searchable by key name, never value/comment. Secret is
+      searchable by filename only, never bytes.
+- [ ] **[CORE]** `env path env/qa-runtime` emits one absolute path on stdout and
+      a do-not-source warning on stderr; `--quiet` suppresses only the warning.
+- [ ] **[CORE]** Env/secret directories are `0700` and files are `0600` on
+      POSIX. Record the ACL equivalent on Windows.
+- [ ] **[CORE]** Empty env create is idempotent. Content-bearing create refuses
+      an existing destination with exit `2`, preserving old bytes.
+- [ ] **[LOCAL]** `--from-file` and `--from-stdin` conflict. Env stdin over 1 MiB,
+      secret stdin/file over 5 MiB, missing input, invalid path, and traversal
+      fail before publication.
+- [ ] **[LOCAL REGRESSION]** Secret `--from-env` obeys the same 5 MiB cap as
+      stdin/file. Current behavior must not be accepted if it bypasses the cap.
+- [ ] **[LOCAL]** `--sensitive` and sibling `.sensitive` markers remove an asset
+      from list/index/search/show while preserving direct run/path use.
+- [ ] **[LOCAL]** Mutations are not automatically reindexed; list reads disk
+      immediately, while search/show change only after `akm index`.
+
+### 11.2 Safe value use and raw child channels
+
+```sh
+export QA_INHERITED='manual-qa-inherited'
+
+akm env run env/qa-runtime \
+  --only QA_PUBLIC,QA_TOKEN --clean --inherit QA_INHERITED \
+  -- bun -e '
+    if (process.env.QA_PUBLIC !== "manual-qa-public") process.exit(11);
+    if (process.env.QA_TOKEN !== "Bearer manual-qa-secret-not-a-credential") process.exit(12);
+    if (process.env.QA_INHERITED !== "manual-qa-inherited") process.exit(13);
+    if (process.env.QA_SECOND !== undefined) process.exit(14);
+  '
+
+akm secret run secrets/qa-token QA_INJECTED --clean \
+  -- bun -e '
+    if (process.env.QA_INJECTED !== "manual-qa-secret-not-a-credential") process.exit(15);
+  '
+test -z "${QA_INJECTED+x}"
+
+set +e
+akm env run env/qa-runtime -- bun -e 'process.exit(7)'
+env_child_status=$?
+akm secret run secrets/qa-token QA_INJECTED -- bun -e 'process.exit(9)'
+secret_child_status=$?
+set -e
+test "$env_child_status" -eq 7
+test "$secret_child_status" -eq 9
+```
+
+- [ ] **[CORE]** Values enter only the child environment and never mutate the
+      invoking shell.
+- [ ] **[CORE]** `${secret:NAME}` resolves from the env asset's own bundle,
+      including embedded/multiple tokens. Missing secret fails before spawn.
+- [ ] **[CORE]** `--only` and `--except` are mutually exclusive; filtering occurs
+      before dangerous-key policy. Clean mode inherits only the documented
+      minimum plus explicit names.
+- [ ] **[CORE]** Child stdout/stderr pass through unchanged and exact numeric
+      child status is returned. Do not claim those raw streams are redacted.
+- [ ] **[LOCAL]** Missing command is usage exit `2`; missing executable is
+      `FILE_NOT_FOUND`, exit `1`; non-executable target is config exit `78`.
+- [ ] **[LOCAL]** Access events contain only env ref/key names or secret ref/
+      target variable. They contain no values and occur only after resolution.
+- [ ] **[LOCAL]** Timeout/signal behavior returns a nonzero signal-equivalent
+      result and leaves no child. A null child status must not become success.
+- [ ] **[LOCAL]** Format flags on `env path`, `env run`, and `secret run` warn on
+      stderr and leave the raw payload/child streams unchanged.
+
+### 11.3 Export, overwrite, targets, and removal
+
+```sh
+printf 'QA_LITERAL=$(touch %s)\n' "$AKM_SANDBOX/export-payload-ran" \
+  >"$AKM_SANDBOX/qa-export.env"
+akm env create qa-export --from-file "$AKM_SANDBOX/qa-export.env"
+akm env export env/qa-export --out "$AKM_SANDBOX/qa-export.sh" \
+  --format json >"$AKM_SANDBOX/env-export.json"
+
+test ! -e "$AKM_SANDBOX/export-payload-ran"
+sh -c '. "$1"' sh "$AKM_SANDBOX/qa-export.sh"
+test ! -e "$AKM_SANDBOX/export-payload-ran"
+
+printf 'replacement-without-trailing-newline' |
+  akm secret set secrets/qa-token
+akm env remove env/qa-export --yes
+```
+
+- [ ] **[CORE]** Export requires `--out`, prints no values, writes atomically at
+      `0600`, and single-quotes substitutions/backticks/dollars/quotes/globs.
+- [ ] **[CORE]** Export does not resolve `${secret:...}`. `env run` is the safe
+      default for secret substitution.
+- [ ] **[CORE]** Secret stdin strips one trailing newline; file input preserves
+      bytes exactly. Secret overwrite is atomic and serialized.
+- [ ] **[LOCAL]** Explicit target wins over `defaultWriteTarget`, then default
+      bundle. Read-only/disabled/unsupported targets fail before mutation.
+- [ ] **[LOCAL]** Writable Git target publishes one boundary commit unless the
+      files are intentionally ignored and stored as local-only overlays.
+- [ ] **[LOCAL]** Env remove needs confirmation, removes the env and marker, and
+      leaves unrelated assets unchanged.
+- [ ] **[LOCAL]** `secret path` and `secret remove` are removed and exit `2`.
+      Locate/delete a secret under the reviewed bundle root, then reindex.
+- [ ] **[LOCAL REGRESSION]** Duplicate env refs across bundles resolve to the
+      same file for path/run/export/remove. Read/write resolver disagreement is
+      a failure.
+
+### 11.4 Dangerous keys and redaction boundary
+
+- [ ] **[CORE]** Secret run rejects dangerous target variables such as `PATH`,
+      `LD_PRELOAD`, `NODE_OPTIONS`, and `GIT_CONFIG_*` before spawn/event.
+- [ ] **[LOCAL]** First-party env activation warns and proceeds; third-party
+      activation blocks exit `2`. Excluding all dangerous keys permits the safe
+      subset.
+- [ ] **[LOCAL]** `--allow-dangerous-env-keys` can authorize reviewed installation but
+      never authorizes later dangerous activation.
+- [ ] **[LOCAL REGRESSION]** Lint suppression cannot authorize untrusted install;
+      declarative first materialization and every update receive the same audit.
+- [ ] **[LOCAL REGRESSION]** Env export applies an equivalent dangerous-key
+      warning/gate before producing sourceable output.
+- [ ] **[LOCAL]** Search all captured AKM results, events, state/log databases,
+      reports, and config for the literal dummy value. Exclude deliberate child
+      passthrough evidence from the AKM-redaction claim.
+
+---
+
+## 12. Lint
+
+### 12.1 Detect, gate, fix, and repeat
+
+Create a disposable native-AKM lint root:
+
+```sh
+export QA_LINT_DIR="$AKM_SANDBOX/lint-bundle"
+mkdir -p "$QA_LINT_DIR/knowledge"
+cat >"$QA_LINT_DIR/knowledge/fixable.md" <<'EOF'
+---
+description: Manual QA: fixable colon
+---
+# Fixable
+EOF
+
+akm lint --dir "$QA_LINT_DIR" --format json \
+  >"$AKM_SANDBOX/lint-detect.json"
+jq -e '.ok == true and .summary.flagged >= 1' \
+  "$AKM_SANDBOX/lint-detect.json"
+
+set +e
+akm lint --dir "$QA_LINT_DIR" --fail-on-flagged --format json \
+  >"$AKM_SANDBOX/lint-gate.json" \
+  2>"$AKM_SANDBOX/lint-gate.stderr"
+lint_gate_status=$?
+set -e
+test "$lint_gate_status" -eq 1
+test ! -s "$AKM_SANDBOX/lint-gate.stderr"
+jq -e '.ok == true and .summary.flagged >= 1' \
+  "$AKM_SANDBOX/lint-gate.json"
+
+akm lint --dir "$QA_LINT_DIR" --fix --format json \
+  >"$AKM_SANDBOX/lint-fix.json"
+jq -e '.summary.fixed >= 1' "$AKM_SANDBOX/lint-fix.json"
+
+snapshot_tree "$QA_LINT_DIR" "$AKM_SANDBOX/lint-fixed.sha256"
+akm lint --dir "$QA_LINT_DIR" --auto-fix --format json \
+  >"$AKM_SANDBOX/lint-fix-second.json"
+jq -e '.summary.fixed == 0' "$AKM_SANDBOX/lint-fix-second.json"
+snapshot_tree "$QA_LINT_DIR" "$AKM_SANDBOX/lint-fixed-again.sha256"
+cmp "$AKM_SANDBOX/lint-fixed.sha256" \
+  "$AKM_SANDBOX/lint-fixed-again.sha256"
+```
+
+- [ ] **[CORE]** Plain lint exits `0` with `ok:true` even when findings exist.
+- [ ] **[CORE]** Fail-on-flagged exits `1` but retains the complete successful
+      lint result on stdout and leaves stderr empty.
+- [ ] **[CORE]** Fix applies only fixable findings, reports failed fixes as
+      flagged, and is byte-idempotent on the second run.
+- [ ] **[CORE]** Fix plus fail-on-flagged exits `1` only if findings remain.
+- [ ] **[CORE]** `--auto-fix` equals `--fix`; single-dash `-auto-fix` is an
+      unknown flag, exit `2`.
+- [ ] **[CORE]** Each finding has relative file, issue, detail, and tri-state
+      fixed status. No absolute bundle path or secret value appears.
+
+### 12.2 Native and adapter scopes
+
+```sh
+akm lint --dir "$AKM_BUNDLE_DIR" --type workflows --format json \
+  >"$AKM_SANDBOX/lint-workflows.json"
+akm lint --dir "$REPO/tests/fixtures/stashes/all-types" --format json \
+  >"$AKM_SANDBOX/lint-all-types.json"
+akm lint --dir "$REPO/tests/fixtures/bundles/llm-wiki" --format json \
+  >"$AKM_SANDBOX/lint-wiki.json"
+```
+
+- [ ] **[CORE]** Native sweep covers agents, commands, memories, skills,
+      workflows, lessons, tasks, knowledge, and facts, plus a separate dangerous
+      `.env` pass.
+- [ ] **[LOCAL]** Workflow Markdown compiles structurally; task `.yml` validates
+      version/schedule/enabled/target; missing `SKILL.md` is flagged.
+- [ ] **[LOCAL]** `--type` accepts exact plural native directories and genuinely
+      narrows structural and dangerous-env scanning.
+- [ ] **[LOCAL REGRESSION]** Singular/unknown type and missing/unreadable `--dir`
+      fail instead of returning a false-clean result.
+- [ ] **[LOCAL]** Non-AKM roots dispatch through the detected/configured adapter
+      `validate()` implementation and remain read-only even with `--fix`.
+- [ ] **[LOCAL]** LLM Wiki reports uncited raw, missing description, broken xref,
+      and broken source; dotenv reports dangerous keys without exposing values.
+- [ ] **[LOCAL REGRESSION]** `--type` is not silently ignored by non-AKM adapter
+      validation.
+- [ ] **[CORE]** Unsupported `--profile`, `--category`, `--severity`, and
+      `--bundle` flags fail exit `2`; do not invent selector semantics.
+
+### 12.3 Rules, suppressions, and mutation boundaries
+
+Core issue codes include `unquoted-colon`, `missing-updated`, `orphaned-stub`,
+`placeholder-stub`, `missing-name-or-type`, `missing-type`, `stale-path`,
+`missing-skill-md`, `invalid-task-yaml`, `missing-ref`,
+`dangerous-env-key`, `invalid-workflow-structure`, and `missing-category`.
+Adapters may add named diagnostics; unknown adapter codes map to
+`adapter-diagnostic` while preserving the original code in detail.
+
+- [ ] **[LOCAL]** Only unquoted description, missing updated, orphaned stub, and
+      placeholder stub fixes mutate; all structural/security findings remain
+      flagged.
+- [ ] **[LOCAL]** `lint_skip` scalar/list suppresses only supported base rules,
+      exactly and case-sensitively. It cannot suppress dangerous env or per-type
+      structure.
+- [ ] **[LOCAL]** `# akm-lint-ok: dangerous-env-key` suppresses only the next
+      matching dotenv assignment for lint display, never installation/runtime.
+- [ ] **[LOCAL REGRESSION]** Suppression also associates with `export KEY=...`;
+      malformed task YAML and `.yaml` spelling produce explicit findings rather
+      than disappearing.
+- [ ] **[LOCAL]** Fenced-code refs are ignored; body refs and refs/xrefs/
+      supersededBy/contradictedBy fields are checked across configured bundles.
+- [ ] **[LOCAL]** Lint appends no event, performs no reindex, and adapter
+      validation never writes.
+- [ ] **[LOCAL REGRESSION]** Native fix honors read-only/Git publication
+      boundaries and either behaves transactionally or reports partial mutation
+      explicitly. Silent direct edits/deletes are a failure.
+
+### 12.4 Advisory channel
+
+Non-fatal workflow compile advisories (a step with no `output:` schema, a
+reference to an undeclared param) travel in their own channel so a hint cannot
+fail a build.
+
+```sh
+akm lint --type workflows --format json > "$AKM_SANDBOX/lint-advisory.json"
+jq -e '.warnings | length > 0' "$AKM_SANDBOX/lint-advisory.json"
+jq -e '[.flagged[].issue] | index("workflow-warning") == null' "$AKM_SANDBOX/lint-advisory.json"
+akm lint --type workflows --fail-on-flagged; echo "exit=$?"
+```
+
+- [ ] **[CORE]** A compile advisory appears in `warnings` with issue code
+      `workflow-warning`, never in `flagged`, and `summary.warnings` counts it.
+- [ ] **[CORE]** `--fail-on-flagged` exits `0` for a bundle whose only findings
+      are advisories, and non-zero once a real error is present.
+- [ ] **[LOCAL]** Both lint paths agree: the akm sweep and a bundle linted
+      through its own adapter classify the same code the same way.
+- [ ] **[LOCAL]** A workflow file is parsed and compiled **once** per sweep, not
+      once per output channel — check with a large workflow and compare sweep
+      time against a bundle with the same file count and no workflows.
+
+### 12.5 Output parity and automated coverage
+
+- [ ] **[CORE]** JSON/JSONL/YAML/text/Markdown/HTML preserve the same finding
+      set and summary. Text renders flagged before fixed.
+- [ ] **[LOCAL]** Hard usage/config/internal failures use standard structured
+      stderr and do not emit a partial lint result.
+- [ ] **[LOCAL]** Run focused lint, adapter dispatch, workflow structure,
+      dangerous-key, and format-family golden suites after linter changes.
+
+---
+
+## 13. Feedback, Log, and Health
+
+### 13.1 Feedback taxonomy and ranking
+
+```sh
+akm feedback skills/k8s-deploy --positive --tag slice:manual --tag team:qa
+expect_error 2 MISSING_REQUIRED_ARGUMENT \
+  feedback skills/k8s-deploy --negative
+akm feedback skills/k8s-deploy --negative \
+  --reason "manual QA relevance check"
+```
+
+- [ ] **CORE** Positive and reasoned negative feedback return stable signal/reason fields.
+- [ ] **CORE** Negative feedback without a reason fails by default with `MISSING_REQUIRED_ARGUMENT`, exit `2`.
+- [ ] **LOCAL** Both signals, missing/nonexistent ref, malformed tag, and more than ten tags fail before durable mutation.
+- [ ] **LOCAL** `feedback.requireReason:false` produces the documented warning rather than the default hard failure.
+- [ ] **LOCAL** User feedback updates ranking immediately and reports `rankingUpdate.applied`; machine-origin signals do not impersonate user demand.
+- [ ] **LOCAL** Feedback survives full reindex and contains no credential fixture value.
+
+### 13.2 Durable log and cursors
+
+```sh
+akm log --type feedback --ref skills/k8s-deploy --detail full --format json \
+  > "$AKM_SANDBOX/feedback-log.json"
+event_id="$(jq -r '.events[-1].id' "$AKM_SANDBOX/feedback-log.json")"
+akm log --since "@offset:$event_id" --format json
+```
+
+- [ ] **CORE** Mutations produce numeric durable ids, normalized refs, type, timestamp, and structured non-secret metadata.
+- [ ] **LOCAL** Type/ref/run/since/limit/include-tags/exclude-tags filters compose correctly.
+- [ ] **LOCAL** `@offset:<id>` returns only later events across a fresh process and exposes a reusable next offset.
+- [ ] **LOCAL** Include-tags requires all requested tags; exclude removes any matching event.
+- [ ] **LOCAL** Retired `log list` and `log tail` fail with current `akm log` guidance.
+- [ ] **LOCAL** Full rebuild/source update/restart preserve events and monotonic cursors.
+- [ ] **LOCAL** Event metadata stores ids/status/counts, not workflow instructions, child output, prompts, env values, or credentials.
+
+### 13.3 Health pass, warn, and fail
+
+```sh
+set +e
+akm health --format json > "$AKM_SANDBOX/health.json"
+health_status=$?
+set -e
+
+jq -e --argjson status "$health_status" '
+  (.status == "pass" and $status == 0) or
+  (.status == "warn" and $status == 4) or
+  (.status == "fail" and $status == 1)
+' "$AKM_SANDBOX/health.json"
+```
+
+- [ ] **CORE** Health status and exit mapping agree; warn remains `ok:true`, hard failure is `ok:false`.
+- [ ] **LOCAL** Fresh data dir initializes `state.db`, validates schema/round-trip, and does not call initial absence corruption.
+- [ ] **LOCAL** Fake default agent provides deterministic healthy engine evidence.
+- [ ] **SERVICE** Semantic config `auto` plus blocked runtime produces nonfatal advisory/exit `4` when hard checks pass.
+- [ ] **LOCAL** A copied secondary state DB with a failed hard check returns health stdout result and exit `1`; never corrupt primary evidence DB.
+- [ ] **LOCAL** Active/stuck runs, task backing/fail rate, agent failure rate, improve/session metrics, and graph summary are accurate.
+- [ ] **LOCAL** Since accepts duration/date/ISO/epoch and rejects invalid/future values predictably.
+- [ ] **LOCAL** Up to four repeated windows work; explicit windows and window-compare are mutually exclusive.
+
+### 13.4 Health reports
+
+```sh
+akm health --report --format json > "$AKM_SANDBOX/health-report.json"
+akm health --report --format html --output "$AKM_SANDBOX/health-report.html"
+akm health --group-by run --format md > "$AKM_SANDBOX/health-runs.md"
+```
+
+- [ ] **LOCAL** JSON/Markdown/HTML contain the same per-run/trend/proposal/accept-rate data.
+- [ ] **LOCAL** Absolute since is not misparsed as implicit duration comparison.
+- [ ] **LOCAL** HTML is self-contained, safely escaped, and credential-free.
+- [ ] **LOCAL** Report read failure is not overwritten by stale status-derived exit.
+
+---
+
+## 14. Workflow
+
+### 14.1 Authoring and validation
+
+```sh
+akm workflow list --format json | jq -e '.runs == []'
+akm workflow create qa-template --print > "$AKM_SANDBOX/qa-template.md"
+test ! -e "$AKM_BUNDLE_DIR/workflows/qa-template.md"
+akm workflow create qa-created --from "$AKM_SANDBOX/qa-template.md"
+akm lint --type workflows --fail-on-flagged
+```
+
+- [ ] **CORE** Create-print emits raw valid Markdown and writes nothing.
+- [ ] **CORE** Create-from writes/indexes valid workflow with preamble and exact sections.
+- [ ] **LOCAL** Flat name plus safe path creates hierarchy; slash/traversal/duplicate step/missing section/unknown route/invalid params fail before write.
+- [ ] **LOCAL** Existing workflow requires force plus from/reset; force alone fails.
+- [ ] **LOCAL** Lint catches structure without rewriting valid prose.
+- [ ] **CORE** A schema keyword outside the enforced subset (`format`, `pattern`,
+      `$ref`, `const`, `uniqueItems`, `patternProperties`, …) in `output:` or
+      `params:` is a **line-anchored parse error naming the keyword**, not a
+      silently non-constraining schema. Confirm the same document fails
+      `workflow run`, `workflow show`, `workflow create`, and `akm lint`.
+- [ ] **LOCAL** `akm index` skips such a workflow with a scan warning rather
+      than indexing it — the quietest surface, so check it deliberately.
+- [ ] **LOCAL** `allOf`/`anyOf`/`oneOf`/`not` are accepted and **enforced** at
+      runtime; a bounded-evaluation overrun is reported as an error, never as a
+      truncated pass.
+- [ ] **LOCAL** A document-level `defaults.llm` combined with any step on an
+      agent engine fails at freeze, naming the step and the engine. Moving the
+      `llm:` block onto the LLM step's `unit:` is the documented remedy; `llm: {}`
+      is a no-op and `llm: null` is a parse error.
+
+### 14.2 Typed params and partial run without an engine call
+
+The `typed-route` fixture executes a route-only first step. `--max-steps 1`
+tests parameter parsing and durable run creation without agent/LLM dispatch.
+
+```sh
+akm workflow run workflows/typed-route \
+  --include_processes=true --count 2 \
+  --labels api --labels worker --max-steps 1 \
+  > "$AKM_SANDBOX/typed-run.json"
+
+export QA_RUN_ID="$(jq -r .run.id "$AKM_SANDBOX/typed-run.json")"
+jq -e '
+  .run.status == "active" and
+  .run.currentStepId == "finish" and
+  .run.params == {
+    "include_processes": true,
+    "count": 2,
+    "labels": ["api", "worker"]
+  }
+' "$AKM_SANDBOX/typed-run.json"
+```
+
+- [ ] **LOCAL** Boolean/integer/number/string/null/enum/object/repeated array/JSON array coerce to schema types.
+- [ ] **LOCAL** Unknown param, underscore-hyphen alias, invalid JSON/enum/range, missing required, duplicate scalar, flags before target, and retired params bag fail exit `2`.
+- [ ] **LOCAL** Params supplied to active run fail because creation-only.
+- [ ] **LOCAL** Invalid max-steps values fail; bounded partial exits `0`, remains active.
+- [ ] **LOCAL** `--max-steps` counts **finished spine steps**: a step's whole
+      bounded gate loop counts as one, and a route-skipped step consumes none.
+      It does not bound the dispatches inside a single step's gate loop — pair
+      it with `budget.max_units` when that is what you need capped.
+
+### 14.3 Status, list, abandon, resume, and scope
+
+```sh
+akm workflow status "$QA_RUN_ID"
+akm workflow status workflows/typed-route
+akm workflow list --active --ref workflows/typed-route
+akm workflow status "$QA_RUN_ID" --units
+akm workflow abandon "$QA_RUN_ID"
+akm workflow resume "$QA_RUN_ID"
+```
+
+- [ ] **LOCAL** Direct id status works from another dir; ref status/list remain current-scope only.
+- [ ] **LOCAL** Units adds diagnostics without state change.
+- [ ] **LOCAL** Abandon marks failed/removes active; resume reopens failed/blocked, never completed.
+- [ ] **LOCAL** Run by ref while active resumes it; direct id continues exact run.
+- [ ] **LOCAL** Source edit after start does not change frozen plan; new run sees edit.
+
+### 14.4 Deterministic execution and gates
+
+Configure fake engines from section 4.4, then continue the active run:
+
+```sh
+akm workflow run "$QA_RUN_ID" --max-steps 1 \
+  > "$AKM_SANDBOX/typed-finished.json"
+jq -e '.run.status == "completed"' "$AKM_SANDBOX/typed-finished.json"
+```
+
+Create separate copies of `gated-agent` for pass/reject/malformed judges so each
+run freezes its own judge selection.
+
+- [ ] **AI** Pass verdict completes.
+- [ ] **AI** Reject verdict returns missing/feedback evidence and nonzero domain result.
+- [ ] **AI** Malformed verdict, agent/HTTP failure, missing judge, and timeout fail closed.
+- [ ] **AI** Max loops bounds retries and prior gate feedback enters next unit.
+- [ ] **AI** Gate journal distinguishes running/error/pass/reject and survives resume.
+- [ ] **AI** Config changes after start do not replace frozen execution/judge engine/model/timeout.
+
+### 14.5 Exec (shell) units
+
+An exec unit spawns a command instead of dispatching to an engine, so run this
+whole subsection with **no engine configured** — that is the first assertion,
+not a setup shortcut. Author the fixtures first:
+
+```sh
+cat > "$AKM_BUNDLE_DIR/workflows/exec-basic.md" <<'EOF'
+---
+type: workflow
+description: Exec unit smoke
+steps:
+  - id: emit
+    unit:
+      exec:
+        command: ["printf", "hello\n\n"]
+---
+
+# Exec Basic
+
+## emit
+
+Print a greeting. Stdout is the promoted artifact; this prose never reaches the
+command.
+EOF
+
+cat > "$AKM_BUNDLE_DIR/workflows/exec-json.md" <<'EOF'
+---
+type: workflow
+description: Exec unit with a typed artifact
+steps:
+  - id: emit
+    unit:
+      exec:
+        command: ["echo", '{"verdict":"pass"}']
+      output: { type: object, required: [verdict], properties: { verdict: { type: string } } }
+---
+
+# Exec JSON
+
+## emit
+
+Emit exactly one JSON value.
+EOF
+
+akm index
+akm lint --type workflows --fail-on-flagged
+akm workflow run workflows/exec-basic --format json > "$AKM_SANDBOX/exec-basic.json"
+jq -e '.run.status == "completed"' "$AKM_SANDBOX/exec-basic.json"
+akm workflow status "$(jq -r .run.id "$AKM_SANDBOX/exec-basic.json")" --units
+```
+
+Authoring and dispatch:
+
+- [ ] **CORE** A workflow of only exec steps freezes and completes with **no
+      engine configured at all**; the run spends no tokens.
+- [ ] **CORE** Without `output:`, the artifact is stdout with trailing newlines
+      stripped (`hello`, not `hello\n\n`); empty stdout is *no output*.
+- [ ] **CORE** With `output:`, stdout must be exactly one JSON value — leading
+      and trailing whitespace tolerated, any other trailing text fails the unit
+      — and the value is validated against the schema.
+- [ ] **CORE** `engine`, `model`, or `llm` alongside `exec:` fails at parse,
+      naming the conflict.
+- [ ] **LOCAL** `command` is argv, never a shell string: an argument containing
+      `;`, `|`, `&&`, `$(…)`, backticks, `>`, or `*` reaches the child as those
+      literal bytes. `["bash", "-lc", "…"]` is the supported way to get a shell.
+- [ ] **LOCAL** Argv bounds hold: 1–64 entries, each non-empty and at most 4096
+      bytes; violations fail at parse and at frozen-plan decode.
+- [ ] **LOCAL** A step body is still required and is **not** passed to the
+      command.
+- [ ] **LOCAL** stderr is a diagnostic channel only — it never becomes the
+      artifact, and a passing command that writes to stderr still succeeds.
+
+Failure taxonomy — each reason, and whether `retry.on` may name it:
+
+- [ ] **CORE** Non-zero exit is `non_zero_exit` and, under the default
+      `on_error: fail`, fails the step and the run (this is what makes a `test`
+      step a gate). `on_error: continue` records it in evidence instead.
+- [ ] **LOCAL** Wall-clock expiry is `timeout`; run cancellation is `aborted`; a
+      missing binary or unusable working directory is `spawn_failed`. All three
+      are retryable via `retry.on`.
+- [ ] **LOCAL** `exec_output_limit`, `exec_context_too_large`, `exec_cwd_escape`
+      and `exec_capture_incomplete` are **rejected** in a `retry.on` list —
+      each is deterministic, an authoring problem, or work that already ran.
+- [ ] **LOCAL** On timeout or cancellation the child's whole **process group**
+      takes the SIGTERM→SIGKILL ladder; no orphaned grandchildren survive.
+
+Capture and retention:
+
+- [ ] **LOCAL** Past the 8 MiB per-stream retention cap akm keeps draining the
+      pipe, so the command never blocks: with no `output:` schema the unit
+      **succeeds** with the artifact marked truncated; with a schema it fails
+      `exec_output_limit`.
+- [ ] **LOCAL** A command that backgrounds a descendant inheriting **stderr**
+      (`sh -c 'daemon 2>&1 & echo ok'` shapes) and exits 0 **succeeds** with its
+      complete stdout artifact, and warns that the stderr tail may be missing.
+      Only an incomplete **stdout** capture fails the unit.
+- [ ] **LOCAL** That same unit settles promptly after its leader exits — it does
+      **not** sit until its declared timeout expires.
+- [ ] **LOCAL** `timeout: none` is genuinely unbounded: a command that runs well
+      past an hour still completes and promotes its artifact.
+
+Environment scope and context:
+
+- [ ] **LOCAL** The child gets the default allowlist only: credentials and cloud
+      or CI variables present in akm's own environment are **absent** unless
+      named. `pass_env:` widens it by name; exact named `env:` bindings provide
+      fixed or secret values.
+- [ ] **CORE** A new durable-v4-family (`irVersion: 5`) start containing
+      `inherit_env: true` is rejected before dispatch and directs the author to
+      named env bindings. A pre-`irVersion`-5 stored plan is also rejected and
+      directs the user to start a new run.
+- [ ] **LOCAL** `env:` bindings inject resolved values, and the `AKM_*` context
+      is applied *after* them, so a binding cannot shadow it.
+- [ ] **LOCAL** `AKM_RUN_ID`, `AKM_STEP_ID`, `AKM_UNIT_ID`, `AKM_PARAMS`,
+      `AKM_INPUTS`, and (in a `map`) `AKM_ITEM` / `AKM_ITEM_INDEX` reach the
+      command with the documented shapes.
+- [ ] **LOCAL** An oversized `AKM_*` context fails `exec_context_too_large`
+      **before** the spawn, naming the variable, rather than surfacing a raw
+      `E2BIG`.
+
+`cwd` and isolation:
+
+- [ ] **LOCAL** `cwd` is relative and contained: absolute paths, drive letters,
+      `~`, and `..` **segments** are rejected by the parser *and* the
+      frozen-plan decoder, and containment is re-checked against the resolved
+      base (symlinks included) immediately before the spawn.
+- [ ] **LOCAL** A directory whose *name* merely begins with dots (`..data`) is a
+      legal contained `cwd` and must **not** fail `exec_cwd_escape`.
+- [ ] **LOCAL** Under `isolation: worktree` each unit gets a fresh detached
+      worktree; a clean one is gone once the step resolves, a dirty one is
+      retained and its path logged.
+- [ ] **LOCAL** When a dirty leftover is moved aside and the worktree then fails
+      to mint, the failure still reports **where the preserved work went**.
+- [ ] **DESTRUCTIVE** The stale-worktree sweep removes abandoned trees after
+      seven days but leaves a tree that is still in use by a live run.
+
+Gates, retry, and reuse:
+
+- [ ] **LOCAL** A `### gate` rubric on an exec step **evaluates** — a rejection
+      still fails the step — but never loops: the command runs exactly **once**
+      regardless of `gate.max_loops`, because a frozen argv cannot answer
+      feedback. Verify with a command that appends to a file.
+- [ ] **LOCAL** A declared `retry:` re-runs the command only for reasons it
+      names; a schema miss is never re-prompted (re-running could deploy twice).
+- [ ] **LOCAL** A completed exec unit is reused on resume, never re-executed —
+      confirm with a command whose side effect is observable.
+- [ ] **LOCAL** `map` fan-out over exec units respects the frozen concurrency
+      width, and each unit sees its own `AKM_ITEM`.
+
+### 14.6 Failure, interruption, concurrency, and events
+
+- [ ] **LOCAL** Execution nonzero returns workflow stdout result, exit `1`.
+- [ ] **LOCAL** Whole-run timeout leaves current step resumable and records evidence.
+- [ ] **LOCAL** A run that **completes** after its `--timeout` deadline landed is
+      reported as completed, not as timed out.
+- [ ] **LOCAL** SIGINT/SIGTERM map to `130`/`143`, release claims, leave recoverable run.
+- [ ] **LOCAL** Concurrent same-ref/scope starts create one active run; second driver loses lease safely.
+- [ ] **LOCAL** Map fan-out respects workflow and frozen engine concurrency caps.
+- [ ] **LOCAL** Log by run correlates start/unit/gate/step/finish only.
+- [ ] **DESTRUCTIVE** Kill before unit, after unit, after judge; resume reclaims only unfinished work, no duplicate unit.
+- [ ] **DESTRUCTIVE** Run focused lease/crash/contention/publication suites.
+
+### 14.7 Step artifacts, bounds, and evidence
+
+A step's promoted artifact is bounded for *persistence* only. The distinction
+between what the running invocation sees and what the row keeps is the point.
+
+- [ ] **LOCAL** A step promoting an artifact larger than the 1 MiB persistence
+      cap still hands the **complete** value to the next step of the same run —
+      both a whole-value `inputs:` reference and a path reference into it.
+- [ ] **LOCAL** The persisted row for that step carries a truncation marker, and
+      **resuming** into the truncated artifact fails loudly, naming truncation
+      as the cause rather than reporting a missing property.
+- [ ] **LOCAL** Over-cap evidence sacrifices the byte-largest values first, and
+      the persisted row is never left over cap.
+
+### 14.8 Retired surfaces and fallback
+
+- [ ] **CORE** Start/next/complete/brief/report fail `UNKNOWN_COMMAND` with run/status guidance.
+- [ ] **LOCAL** No template/validate/watch; replacements are create-print/lint/log.
+- [ ] **AI** No defaults engine plus actual opencode binary enables announced SDK fallback; SDK package alone does not.
+- [ ] **AI** Binary absent fails `78`, names both remedies; no arbitrary first-engine fallback.
+- [ ] **LOCAL** Secret-shaped param names warn because params persist; use dummy values only.
+
+---
+
+## 15. Task
+
+### 15.1 Surface and schema
+
+The current group has only `add`, `run`, `history`, `sync`, and `doctor`.
+Inspection uses generic search/show. Enable/disable is YAML edit plus sync;
+removal is file deletion plus sync.
+
+- [ ] **CORE** Task help shows those five; bare task exits `2`; doctor is diagnostic.
+- [ ] **CORE** Search `tasks/` and show `tasks/manual-success` expose fixtures.
+- [ ] **LOCAL** Task list/show/remove/enable/disable and plural top-level tasks fail with guidance.
+- [ ] **LOCAL** Version `2` and schedule are required; enabled default correct; exactly one target.
+- [ ] **LOCAL** Command arrays preserve argv. String commands whitespace-split without shell quote semantics.
+- [ ] **LOCAL** Old Markdown task is not indexed; YAML is canonical; legacy same-id blocks add unless force.
+
+### 15.2 Doctor and manual execution without scheduler mutation
+
+```sh
+akm task doctor --format json > "$AKM_SANDBOX/task-doctor.json"
+akm task run manual-success --format json > "$AKM_SANDBOX/task-success.json"
+
+set +e
+akm task run manual-failure --format json > "$AKM_SANDBOX/task-failure.json"
+task_failure_status=$?
+set -e
+
+test "$task_failure_status" -eq 1
+jq -e '.result.detail.exitCode == 7' "$AKM_SANDBOX/task-failure.json"
+akm task history --id manual-failure --limit 1
+```
+
+- [ ] **CORE** Doctor reports backend/executable/log dir/schedule subset without scheduler mutation.
+- [ ] **CORE** Manual run executes disabled success task; scheduled marker skips disabled task.
+- [ ] **LOCAL** Failure is stdout result/CLI `1`, with child `7` retained in detail/history.
+- [ ] **LOCAL** Command child `78` maps CLI `78`; other failed status maps `1`.
+- [ ] **LOCAL** Missing/malformed task, invalid id, prompt/workflow failure, timeout, and signal record bounded history.
+- [ ] **LOCAL** Flat log and logs DB agree and redact credentials.
+- [ ] **LOCAL** A **workflow** task that declares no `timeoutMs:` gets the
+      6-hour unattended default: the log records `timed_out=true` with the
+      applied `timeout_ms`, the attempt is `failed` so the scheduler sees a
+      non-zero exit, and the aborted run is left **resumable** with the error
+      naming `akm workflow resume <id>`.
+- [ ] **LOCAL** `timeoutMs: null` opts a workflow task out entirely and arms no
+      timer; an explicit number overrides the default.
+- [ ] **LOCAL** A workflow task whose run **completes** as the deadline lands is
+      recorded `completed` with no timeout error and no resume hint.
+
+### 15.3 Scheduler binding and native lifecycle
+
+- [ ] **LOCAL** Source/dist scheduler write without rebind rejects ineligible executable before task/scheduler mutation.
+- [ ] **LOCAL** Explicit rebind records reviewed invocation and warns not release-eligible.
+- [ ] **PLATFORM** Use installed npm/standalone candidate in disposable account.
+- [ ] **PLATFORM** Add a disabled command/prompt/workflow; confirm no native entry exists; use `akm task enable` and inspect the native entry; edit schedule/target + sync; execute; inspect history/log; use `akm task disable` and confirm removal; delete YAML + sync remains converged.
+- [ ] **PLATFORM** Existing binding remains unless rebind; upgrade behavior is explicit.
+
+| Platform | Evidence |
+| --- | --- |
+| Linux cron | Before/after crontab, generated line, execution log, history, removal |
+| macOS launchd | Plist, launchctl state, execution log, history, unload/removal |
+| Windows schtasks | XML, scheduler query, execution result, history, deletion |
+
+```sh
+AKM_NATIVE_SCHEDULER_TESTS=1 bun test tests/integration/native-scheduler.test.ts
+```
+
+- [ ] **PLATFORM** Native test actually runs rather than skips and all changes are removed from the disposable account.
+
+---
+
+## 16. Proposal Queue
+
+### 16.1 Seed, list, show, diff, and resolution
+
+Run the deterministic seeder from section 4.6.
+
+```sh
+update_id="$(jq -r .update.id "$AKM_SANDBOX/proposals.json")"
+new_id="$(jq -r .newAsset.id "$AKM_SANDBOX/proposals.json")"
+
+akm proposal list --status pending --format json
+akm proposal show "$update_id" --format json
+akm proposal show 11111111 --format json
+akm proposal show memories/qa-proposal-update --format json
+akm proposal diff "$update_id" --format text
+```
+
+- [ ] **LOCAL** List filters queue/status/ref/type without mutation; bare proposal is a usage error.
+- [ ] **LOCAL** Pending proposal resolves by full UUID, unique prefix, and canonical asset ref.
+- [ ] **LOCAL** Ambiguous prefix `33333333` fails with an ambiguity error and candidate guidance.
+- [ ] **LOCAL** Missing proposal is `PROPOSAL_NOT_FOUND`, exit `1`.
+- [ ] **LOCAL** Show includes payload, provenance, target, validation, status, and no credential values.
+- [ ] **LOCAL** Diff distinguishes create/update/empty diff and renders all supported formats.
+- [ ] **LOCAL** Queue/target selectors that conflict with recorded target fail before mutation.
+
+### 16.2 Accept and revert exact bytes
+
+```sh
+cp "$AKM_BUNDLE_DIR/memories/qa-proposal-update.md" \
+  "$AKM_SANDBOX/qa-proposal-update.before"
+
+akm proposal accept "$update_id" --format json
+grep -q 'qa-proposal-after' "$AKM_BUNDLE_DIR/memories/qa-proposal-update.md"
+
+akm proposal revert "$update_id" --format json
+cmp "$AKM_SANDBOX/qa-proposal-update.before" \
+  "$AKM_BUNDLE_DIR/memories/qa-proposal-update.md"
+```
+
+- [ ] **LOCAL** Accept validates/publishes/indexes one proposal and archives it accepted with backup metadata.
+- [ ] **LOCAL** Update revert accepts full archived UUID or asset ref, restores exact prior bytes, reindexes, and marks reverted.
+- [ ] **LOCAL** Archived UUID prefixes are not supported by revert; use full UUID.
+- [ ] **LOCAL** Accepting new asset succeeds, but reverting it fails with usage exit `2` because no prior-content backup exists.
+- [ ] **LOCAL** Reverting pending/rejected/reverted/missing proposal has the correct usage/not-found classification and changes no bytes.
+- [ ] **LOCAL** Stale before-hash, read-only/disabled target, lint blocker, adapter precommit failure, git commit/push failure, and publication interruption preserve coherent queue/asset state.
+
+### 16.3 Reject and bulk dry-runs
+
+```sh
+akm proposal reject "$new_id" --reason "manual QA" --yes
+akm proposal accept --generator reflect --dry-run --format json
+akm proposal reject --generator distill \
+  --reason "manual QA dry-run" --dry-run --format json
+```
+
+- [ ] **LOCAL** Single reject requires nonempty reason and `--yes` in non-TTY mode; it archives one row and preserves payload/audit.
+- [ ] **LOCAL** Bulk dry-run needs no prompt, reports matching proposals, and leaves statuses/assets unchanged.
+- [ ] **LOCAL** Max-diff-lines and older-than strictly validate integers/ranges and select exact rows.
+- [ ] **LOCAL** Dry-run does not create backups, commits, or asset/index mutations.
+
+### 16.4 Drain and observability
+
+```sh
+before_event_id="$(akm log --format json | jq -r '.events[-1].id // 0')"
+akm proposal drain --dry-run --format json \
+  > "$AKM_SANDBOX/drain-dry-run.json"
+after_event_id="$(akm log --format json | jq -r '.events[-1].id // 0')"
+```
+
+- [ ] **LOCAL** Without a judgment tier, drain accepts only proposals a quality judge passed (a `staged` gate decision whose content hash still matches), rejects empty diffs, and defers everything else; it never accepts an unjudged proposal by itself.
+- [ ] **LOCAL** Dry-run leaves assets/statuses unchanged but appends the documented `triage_drained` observability event. It is not globally side-effect-free.
+- [ ] **LOCAL** Max accepts, older-than, queue mode versus `--promote`, and hard cap buckets are exact.
+- [ ] **AI** Judgment-enabled drain uses selected frozen engine and fails closed on malformed/failed judgment.
+- [ ] **LOCAL** Noninteractive promotion without `--yes` fails before writes.
+
+### 16.5 Proposal generation and crash recovery
+
+- [ ] **AI** `proposal new` with the fake/controlled agent either queues one valid proposal with provenance or returns a structured engine failure; use one tiny asset/task.
+- [ ] **AI** `proposal extract --type <harness>` and `--auto` use disposable session fixtures, bounded since/limit, and never ingest real session secrets.
+- [ ] **LOCAL** Generated proposal source/sourceRun/model/target attribution is complete and queryable.
+- [ ] **DESTRUCTIVE** Kill accept/reject/revert at each durable transaction phase; retry converges with one archive status and old/new complete bytes.
+- [ ] **LOCAL** Run `tests/integration/proposal-durable-recovery.test.ts`, proposal storage/target-binding suites, and proposal stuck-repair before release changes to queue transactions.
+
+---
+
+## 17. Agent, LLM, and Improve
+
+### 17.1 Fake agent success, failure, capture, timeout, and redaction
+
+Configure fake engines from section 4.4.
+
+```sh
+akm agent agents/qa-reviewer \
+  --engine qa-agent --prompt "Return the fixture marker" --format json \
+  > "$AKM_SANDBOX/agent-success.json"
+jq -e '.ok == true and .shape == "agent-result" and (.stdout | contains("qa-agent-success"))' \
+  "$AKM_SANDBOX/agent-success.json"
+
+akm agent --engine qa-agent-capture \
+  --prompt "capture prompt" --cwd "$AKM_SANDBOX" --format json \
+  > "$AKM_SANDBOX/agent-capture.json"
+
+set +e
+akm agent --engine qa-agent-fail --prompt "fail" --format json \
+  > "$AKM_SANDBOX/agent-failure.json"
+agent_failure_status=$?
+set -e
+test "$agent_failure_status" -eq 1
+jq -e '.ok == false and .exitCode == 7' "$AKM_SANDBOX/agent-failure.json"
+```
+
+- [ ] **AI** Agent asset contributes system prompt/model/tool policy; CLI model override wins.
+- [ ] **AI** Prompt, prompt-stdin, cwd, and interactive no-prompt paths are each covered; stored commands and workflows use their canonical commands.
+- [ ] **AI** Capture proves exact argv/prompt/cwd and credential-presence boolean without logging credential value.
+- [ ] **AI** Nonzero child returns `agent-result` on stdout, CLI exit `1`, child code/reason/stderr retained and redacted.
+- [ ] **AI** Missing executable is a bounded spawn failure; timeout kills process group and writes the fake signal marker with no orphan.
+- [ ] **AI** `OPENCODE_API_KEY=manual-qa-credential-value` plus echo-secret mode produces no literal value in AKM result, stderr, event, or logs.
+- [ ] **AI REGRESSION** Prompt-stdin remains mutually exclusive with `--prompt`; removed aliases such as agent `--command` are absent from help.
+- [ ] **AI** Named LLM engine is rejected where agent-only dispatch is required; invalid platform/kind fails before spawn.
+- [ ] **AI** Default-engine fallback is announced exactly once when used and never rescues an explicitly invalid named engine.
+
+### 17.2 Fake OpenAI-compatible service
+
+Start/configure sections 4.3 and 4.5.
+
+```sh
+: >"$AKM_QA_SERVICE_LOG"
+
+akm remember "Observed manual QA on 2026-08-05" \
+  --name qa-enriched --tag manual-qa-seed --enrich --format json \
+  > "$AKM_SANDBOX/enriched.json"
+
+grep -q 'manual-qa' "$AKM_BUNDLE_DIR/memories/qa-enriched.md"
+
+akm config set engines.qa-chat.endpoint "$AKM_QA_PROPOSAL_URL" --silent
+akm proposal new lesson qa-llm-proposal \
+  --task "Create the controlled manual QA lesson" \
+  --engine qa-chat --format json >"$AKM_SANDBOX/llm-proposal-default.json"
+jq -e '.ok == true and (.ref | endswith("//lessons/qa-llm-proposal"))' \
+  "$AKM_SANDBOX/llm-proposal-default.json"
+
+akm config set engines.qa-chat.maxTokens 32 --silent
+akm proposal new lesson qa-llm-proposal \
+  --task "Repeat the controlled manual QA lesson with an engine cap" \
+  --engine qa-chat --format json >"$AKM_SANDBOX/llm-proposal-capped.json"
+akm config unset engines.qa-chat.maxTokens --silent
+akm config set engines.qa-chat.endpoint "$AKM_QA_CHAT_URL" --silent
+
+jq -s -e '
+  ([.[] | select(.pathname == "/ok/chat/completions")]) as $enrich |
+  ([.[] | select(.pathname == "/proposal/chat/completions")]) as $proposal |
+  ($enrich | length) == 1 and
+  $enrich[0].authorizationPresent == true and
+  $enrich[0].maxTokensPresent == true and
+  ($proposal | length) == 2 and
+  all($proposal[]; .authorizationPresent == true) and
+  $proposal[0].maxTokensPresent == false and
+  $proposal[1].maxTokensPresent == true and
+  $enrich[0].responseFormatPresent == false and
+  all($proposal[]; .responseFormatPresent == true)
+' \
+  "$AKM_QA_SERVICE_LOG"
+```
+
+- [ ] **AI** The seed tag forces the structured remember path; valid response enriches tags/description/date with one bounded request.
+- [ ] **AI REGRESSION** `remember --enrich` without another structured argument must still dispatch enrichment. A zero-request raw write is a failure.
+- [ ] **AI** HTTP 500, invalid envelope, malformed content, connection refused, and slow endpoint produce typed/fail-soft behavior with no stack/hang/partial write.
+- [ ] **AI** Timeout honors engine `timeoutMs`; no removed feature-gate timeout is used.
+- [ ] **AI** Explicit symbolic credential is required and authoritative; missing value fails config/dispatch without trying another secret.
+- [ ] **AI** Echo-auth 500 response cannot leak the Authorization value into error, log, event, or persisted run result.
+- [ ] **AI** Remember's enrichment call sends its intentional caller cap; default proposal chat omits `max_tokens`; configured engine `maxTokens` sends it.
+- [ ] **AI** Local endpoint work defaults to one concurrent request on indexing paths; remote defaults remain bounded.
+- [ ] **AI** Probe route exercises capability setup using tiny fixed responses only.
+
+Run the standalone enrichment regression separately. It currently fails because
+the command takes the raw-write path and makes no request:
+
+```sh
+before_requests="$(wc -l <"$AKM_QA_SERVICE_LOG")"
+akm remember "Standalone enrichment dispatch oracle" \
+  --name qa-enrich-only --enrich --format json \
+  >"$AKM_SANDBOX/enrich-only.json"
+after_requests="$(wc -l <"$AKM_QA_SERVICE_LOG")"
+
+test "$after_requests" -eq "$((before_requests + 1))"
+grep -q 'manual-qa' "$AKM_BUNDLE_DIR/memories/qa-enrich-only.md"
+```
+
+### 17.3 Improve dry-run invariants
+
+Dry-run still preflights enabled model-backed processes, so configure the fake
+LLM first. It must not call the model or mutate any durable surface.
+
+```sh
+snapshot_tree "$AKM_SANDBOX" "$AKM_SANDBOX/before-improve.sha256"
+before_requests="$(wc -l < "$AKM_QA_SERVICE_LOG")"
+
+akm improve skills/k8s-deploy \
+  --strategy quick --limit 1 --dry-run --no-sync --no-push \
+  --format json > "$AKM_SANDBOX/improve-dry-run.json"
+
+after_requests="$(wc -l < "$AKM_QA_SERVICE_LOG")"
+test "$before_requests" -eq "$after_requests"
+jq -e '
+  .schemaVersion == 2 and
+  .shape == "improve" and
+  .dryRun == true and
+  .strategy == "quick"
+' "$AKM_SANDBOX/improve-dry-run.json"
+```
+
+Do not compare the snapshot file against itself. Produce before/after manifests
+outside the hashed tree or exclude those evidence files, then compare config,
+bundle, data, state, and cache independently.
+
+- [ ] **AI** Dry-run emits schema-v2 improve result, performs zero model requests, creates no proposal/event/run/lock/log/asset/config/index/git change.
+- [ ] **AI** Scope by type/ref, task guidance, bundle validation, limit, strategy, require-feedback-signal, and format shaping are represented in plan.
+- [ ] **AI** Retired `--target`, `canary`, and removed auto-accept behavior produce current errors/warnings without poisoned scope.
+- [ ] **AI** Unknown strategy/engine/incompatible process fails during preflight before logging/locks/mutation.
+
+### 17.4 Bounded live improve and lock behavior
+
+Use a controlled test-capable model, one asset, and explicit no-sync/no-push:
+
+```sh
+akm improve skills/k8s-deploy \
+  --task "tighten the description" \
+  --strategy quick --limit 1 --no-sync --no-push --json-to-stdout
+```
+
+- [ ] **AI** Successful live run persists exactly one `improve_runs` row, emits expected process/proposal events, and queues reviewable changes with provenance.
+- [ ] **AI** Default live mode emits progress on stderr and no stdout; json-to-stdout returns the same persisted result.
+- [ ] **AI** Lock contention without skip is a transient error, exit `75` (`IMPROVE_LOCK_HELD`); `--skip-if-locked` exits `0`, reports `skipped.reason:"lock-held"`, and emits no `improve_invoked`.
+- [ ] **AI** Stale lock is reclaimed with an observable recovery event; active lock is never stolen.
+- [ ] **AI** Timeout/SIGINT/SIGTERM/SIGHUP persist one terminated run with redacted reason and release locks/children.
+- [ ] **AI** Default/quick/thorough/reflect-distill/consolidate/catchup/proactive-maintenance strategies enable exactly documented processes. Autonomy-gated mutations remain off without explicit experimental opt-in.
+- [ ] **AI** No sync/push occurs under explicit flags; git publication is tested separately only against disposable remote.
+- [ ] **AI** Credential/prompt/session values are absent from improve result, state DB, proposal provenance, health report, event stream, and logs.
+
+---
+
+## 18. Semantic Search
+
+Semantic intent (`off`/`auto`) and runtime readiness are separate. Use a fresh
+data/cache/state tier for each case because vectors, fingerprints, and blocked
+status are durable.
+
+### 18.1 Isolated semantic tiers and state oracle
+
+```sh
+export AKM_QA_BASE_DATA_DIR="$AKM_DATA_DIR"
+export AKM_QA_BASE_CACHE_DIR="$AKM_CACHE_DIR"
+export AKM_QA_BASE_STATE_DIR="$AKM_STATE_DIR"
+
+use_semantic_tier() {
+  tier="$1"
+  export AKM_DATA_DIR="$AKM_SANDBOX/semantic/$tier/data"
+  export AKM_CACHE_DIR="$AKM_SANDBOX/semantic/$tier/cache"
+  export AKM_STATE_DIR="$AKM_SANDBOX/semantic/$tier/state"
+  mkdir -p "$AKM_DATA_DIR" "$AKM_CACHE_DIR" "$AKM_STATE_DIR"
+}
+
+restore_semantic_dirs() {
+  export AKM_DATA_DIR="$AKM_QA_BASE_DATA_DIR"
+  export AKM_CACHE_DIR="$AKM_QA_BASE_CACHE_DIR"
+  export AKM_STATE_DIR="$AKM_QA_BASE_STATE_DIR"
+}
+```
+
+| Effective state | Meaning | Search behavior |
+| --- | --- | --- |
+| `disabled` | Mode is `off` | FTS only, no embedding request |
+| `pending` | Enabled but not verified/current fingerprint changed | FTS fallback with advisory |
+| `ready-js` | Complete vectors (scanned by cosine similarity in JavaScript) | Hybrid/vector search |
+| `blocked` | Recent embedding failure | FTS fallback until retry/expiry |
+
+- [ ] **[CORE]** With mode off, full index reports disabled, stores zero
+      embeddings, and search remains exact FTS with no model/network request.
+- [ ] **[LOCAL]** Info, index verification, health advisory, and search event
+      agree on effective state. Config intent remains `auto` after transient
+      failure.
+- [ ] **[LOCAL]** A blocked status expires to pending after its documented TTL;
+      a fingerprint change also returns to pending without deleting keyword data.
+
+### 18.2 Deterministic model-free path
+
+`AKM_EMBED_DETERMINISTIC=1` is a test-only stable hash embedder, not a production
+model or relevance-quality claim.
+
+```sh
+use_semantic_tier deterministic
+akm config unset embedding --silent
+akm config set semanticSearchMode auto --silent
+export AKM_EMBED_DETERMINISTIC=1
+
+akm index --full --format json \
+  >"$AKM_SANDBOX/semantic-deterministic-index.json"
+jq -e '
+  .verification.ok == true and
+  .verification.semanticStatus == "ready-js" and
+  .verification.embeddingCount == .verification.entryCount
+' "$AKM_SANDBOX/semantic-deterministic-index.json"
+
+akm search "deploy docker compose in a homelab" \
+  --detail full --format json \
+  >"$AKM_SANDBOX/semantic-deterministic-search.json"
+akm log --type search --limit 1 --detail full --format json \
+  >"$AKM_SANDBOX/semantic-deterministic-log.json"
+jq -e '.events[-1].metadata.mode == "semantic"' \
+  "$AKM_SANDBOX/semantic-deterministic-log.json"
+
+unset AKM_EMBED_DETERMINISTIC
+```
+
+- [ ] **[LOCAL]** Index/search make no network or model request.
+- [ ] **[LOCAL]** Every embeddable entry has one vector; repeated full index
+      yields stable vectors and relevant result set.
+- [ ] **[LOCAL]** Full-detail hit explains hybrid/semantic matching and durable
+      search telemetry records actual semantic mode. Timing alone is not proof.
+
+### 18.3 Controlled remote embedding service
+
+Start section 4.3 first. The fixture proves transport, batching, persistence,
+readiness, and activation, not natural-language relevance.
+
+```sh
+use_semantic_tier fake-remote
+unset AKM_EMBED_DETERMINISTIC AKM_EMBED_API_KEY
+: >"$AKM_QA_SERVICE_LOG"
+
+akm config set embedding "$(jq -nc \
+  --arg endpoint "$AKM_QA_EMBED_URL" \
+  '{provider:"openai",endpoint:$endpoint,model:"qa-embedding",dimension:4,batchSize:4}')" \
+  --silent
+akm config set semanticSearchMode auto --silent
+
+akm index --full --format json >"$AKM_SANDBOX/semantic-remote-index.json"
+jq -e '
+  .verification.ok == true and
+  .verification.embeddingProvider == "remote" and
+  .verification.embeddingCount == .verification.entryCount and
+  .verification.semanticStatus == "ready-js"
+' "$AKM_SANDBOX/semantic-remote-index.json"
+
+akm search deploy --detail full --format json \
+  >"$AKM_SANDBOX/semantic-remote-search.json"
+jq -s -e '
+  [.[] | select(.pathname == "/v1/embeddings")] as $requests |
+  ($requests | length) > 0 and
+  all($requests[];
+    .model == "qa-embedding" and
+    .authorizationPresent == false and
+    .inputCount >= 1 and .inputCount <= 4)
+' "$AKM_QA_SERVICE_LOG"
+```
+
+- [ ] **[SERVICE]** Batch/model/auth metadata is exact; request log contains no
+      input text or credential value.
+- [ ] **[SERVICE]** Query creates one additional embedding request and records
+      semantic execution.
+- [ ] **[SERVICE]** Wrong envelope, wrong vector count/dimension, HTTP failure,
+      slow response, cancellation, and connection refusal are bounded and do not
+      invalidate the FTS index.
+- [ ] **[SERVICE]** Changing `embedding.dimension` invalidates old vectors and
+      an ordinary index regenerates them. Changing indexed text regenerates
+      exactly that asset's vector.
+- [ ] **[SERVICE]** Changing `embedding.model` to a string that still resolves
+      to a compatible model (same dimension, near-identical vectors on
+      re-embedding a sample) is verified and KEPT — no purge, the stored
+      vectors survive, and `akm index --format json` reports the same
+      `embeddingCount` as before. `akm index --reembed` bypasses this check
+      and forces a purge + rebuild regardless.
+- [ ] **[SERVICE REGRESSION]** A provider-returned vector dimension mismatch is
+      rejected rather than stored as ready.
+
+### 18.4 Blocked indexing and query-time fallback
+
+```sh
+use_semantic_tier blocked
+akm config set embedding "$(jq -nc \
+  --arg endpoint "$AKM_QA_BASE_URL/error/embeddings" \
+  '{provider:"openai",endpoint:$endpoint,model:"qa-failing",dimension:4,batchSize:4}')" \
+  --silent
+akm config set semanticSearchMode auto --silent
+
+set +e
+akm index --full --format json \
+  >"$AKM_SANDBOX/semantic-blocked-index.json" \
+  2>"$AKM_SANDBOX/semantic-blocked-index.stderr"
+blocked_index_status=$?
+set -e
+
+test "$blocked_index_status" -eq 0
+jq -e '
+  .verification.ok == false and
+  .verification.semanticStatus == "blocked"
+' "$AKM_SANDBOX/semantic-blocked-index.json"
+
+akm search deploy --detail full --format json \
+  >"$AKM_SANDBOX/semantic-blocked-search.json"
+jq -e '(.hits | length) > 0 and (.warnings | length) > 0' \
+  "$AKM_SANDBOX/semantic-blocked-search.json"
+```
+
+- [ ] **[SERVICE]** Index exits `0` because keyword indexing succeeded, but
+      semantic verification is explicitly false/blocked and warns.
+- [ ] **[SERVICE]** Search exits `0`, returns FTS hits, and records keyword mode.
+- [ ] **[SERVICE]** If hard health checks pass, blocked semantic readiness is a
+      health warning on stdout with exit `4`, not a hard failure.
+- [ ] **[SERVICE REGRESSION]** Query-time provider failure updates durable
+      readiness and structured warnings, not stderr only while status stays ready.
+- [ ] **[LOCAL REGRESSION]** Targeted writes that skip embeddings cannot leave a
+      misleading complete/ready count; next index converges deterministically.
+
+### 18.5 Real local and bounded live gates
+
+```sh
+use_semantic_tier local-model
+unset AKM_EMBED_DETERMINISTIC AKM_EMBED_API_KEY
+akm config unset embedding --silent
+akm config set semanticSearchMode auto --silent
+akm index --full --verbose --format json \
+  >"$AKM_SANDBOX/semantic-local-index.json"
+```
+
+- [ ] **[AI]** Package install loads the default local model, keeps all model
+      files under isolated `HF_HOME`, reaches ready, and passes a paraphrase
+      query through an actual CLI subprocess.
+- [ ] **[AI]** Record cold download and warm offline reuse separately. A model
+      download failure blocks semantic only and leaves FTS usable.
+- [ ] **[AI]** Optional remote provider uses a non-production symbolic key,
+      exact model/dimension, batch at most four, bounded spend, and redaction.
+- [ ] **[PLATFORM]** Standalone release binary cannot load the externalized local
+      transformer dependency; use remote embeddings or mark local gate `N/A`.
+
+Automated real-model gate:
+
+```sh
+AKM_SEMANTIC_TESTS=1 \
+  bun test --timeout=120000 tests/integration/semantic-search-e2e.test.ts
+```
+
+Restore the primary tier after semantic checks:
+
+```sh
+restore_semantic_dirs
+unset AKM_EMBED_DETERMINISTIC
+akm config set semanticSearchMode off --silent
+akm config unset embedding --silent
+```
+
+---
+
+## 19. Migration, Durability, and Concurrency
+
+### 19.1 Task migration boundary
+
+`akm migrate` has exactly one responsibility: explicit task migration, run as
+two generations in one pass — task-v2 to task-v3 source conversion, then
+task-v3 to task source v4 conversion against the resulting files. It never
+rewrites config or databases.
+
+| Operation | Classification |
+| --- | --- |
+| `akm migrate status` | Read-only task inventory, both generations |
+| `akm migrate apply --dry-run` | Read-only validated conversion plan, both generations |
+| `akm migrate apply` | Per-file backup plus atomic task-source replacement, both generations |
+
+- [ ] **[LOCAL]** Status and dry-run report the same generation for each pass
+      and change no source, config, database, lock, scheduler, event, or usage
+      row.
+- [ ] **[LOCAL]** Apply validates complete v3 bytes before replacement,
+      preserves mode, and creates the backup immediately before the write; the
+      v3-to-v4 generation then runs the same way against the resulting files.
+- [ ] **[LOCAL]** A changed generation, ambiguous argv array, unwritable source,
+      invalid YAML, or unsafe shell translation is blocked with original bytes
+      intact.
+- [ ] **[LOCAL]** Normal run/sync/doctor rejects task v2 and task v3 and never
+      invokes the migrator as a side effect.
+
+### 19.2 Automatic current database upgrades
+
+Managed `state.db` opens validate the exact migration-ledger prefix and apply
+known pending additive migrations automatically. Unknown or reordered ledger
+entries fail closed. There is no external storage migration command.
+
+- [ ] **[LOCAL]** A fresh database applies the complete current registry.
+- [ ] **[LOCAL]** A database with an exact older prefix advances on open without
+      dropping or rewriting durable rows.
+- [ ] **[LOCAL]** A newer/unknown or inconsistent ledger is rejected before a
+      write.
+- [ ] **[LOCAL]** Concurrent first opens serialize each migration exactly once.
+- [ ] **[LOCAL]** `index.db` remains regenerable; `state.db` is never deleted as
+      a generic recovery step.
+
+### 19.3 Package upgrade boundary
+
+`akm upgrade` updates executable code only. A 0.8 installation moves its old
+config/state aside, creates current config/state, and selectively brings
+authored assets forward. The explicit task migrator can then convert task-v2
+sources through to task source v4. No current runtime loads old
+config/storage layouts.
+
+- [ ] **[LIVE DISPOSABLE]** `akm upgrade --check` is nonmutating and the chosen
+      npm/Bun/pnpm or standalone path installs the expected version.
+- [ ] **[LIVE DISPOSABLE]** A standalone replacement verifies its checksum and
+      preflights the staged binary before atomic replacement.
+- [ ] **[LIVE DISPOSABLE]** Old and current data sets stay separate; rollback
+      restores executable code together with its matching archived data.
+
+### 19.4 Concurrent writers and readers
+
+```sh
+akm config set semanticSearchMode off --silent
+
+set +e
+akm index --full --format json \
+  >"$AKM_SANDBOX/index-race-1.json" 2>"$AKM_SANDBOX/index-race-1.stderr" &
+index_pid_1=$!
+akm index --full --format json \
+  >"$AKM_SANDBOX/index-race-2.json" 2>"$AKM_SANDBOX/index-race-2.stderr" &
+index_pid_2=$!
+wait "$index_pid_1"; index_status_1=$?
+wait "$index_pid_2"; index_status_2=$?
+set -e
+
+test "$index_status_1" -eq 0
+test "$index_status_2" -eq 0
+! grep -qi 'database is locked' "$AKM_SANDBOX"/index-race-*.stderr
+test ! -e "$AKM_DATA_DIR/index.db.write.lock"
+
+akm config set search.graphBoost.directBoostPerEntity 0.11 --silent &
+config_pid_1=$!
+akm config set search.graphBoost.directBoostCap 1.25 --silent &
+config_pid_2=$!
+wait "$config_pid_1"
+wait "$config_pid_2"
+jq -e '
+  .search.graphBoost.directBoostPerEntity == 0.11 and
+  .search.graphBoost.directBoostCap == 1.25
+' "$AKM_CONFIG_DIR/config.json"
+```
+
+- [ ] **[LOCAL]** Index contender waits/serializes; both complete, verification
+      passes, no SQLite lock error or stale writer lease remains.
+- [ ] **[LOCAL]** Concurrent independent config writes both survive or one fails
+      cleanly after the bounded lock wait; config remains complete JSON.
+- [ ] **[LOCAL]** Same-name create races produce one asset/one already-exists;
+      different names both survive. Repeat for remember/import/env/secret.
+- [ ] **[LOCAL]** Reader during full index sees old or finalized new generation,
+      never an empty/intermediate FTS generation.
+- [ ] **[LOCAL REGRESSION]** A live writer is never reclaimed solely because a
+      wall-clock stale threshold elapsed.
+- [ ] **[DESTRUCTIVE]** Sync cannot commit an intermediate multi-file write;
+      source update/website/npm refresh are old-or-new complete after kill.
+
+### 19.5 Database and artifact recovery matrix
+
+| Artifact | Recovery rule |
+| --- | --- |
+| `config.json` | Corruption exits `78`; preserve bytes and restore manually from verified backup |
+| `akm.lock` | Preserve corrupt bytes; mutation fails before config/cache/index changes |
+| `index.db` | Regenerable after evidence capture: remove/quarantine, then full index |
+| `state.db` | Non-regenerable; never delete as repair; restore verified backup |
+| transaction journal | Stop writers, retain evidence, use domain recovery |
+| Git source cache | Staged swap for read-only sources; writable checkout policy is explicit |
+| npm/website cache | Must preserve prior complete generation or report a known failing gate |
+
+- [ ] **[LOCAL]** WAL is default; explicit DELETE/TRUNCATE works; detected network
+      filesystems fall back safely; managed connections use bounded busy timeout.
+- [ ] **[LOCAL]** State writes use immediate transactions and nested same-
+      connection calls join the outer transaction.
+- [ ] **[LOCAL]** Atomic write failure yields complete old or new bytes. A parent
+      directory fsync failure after rename may report failure with new bytes;
+      record that ambiguity rather than claiming rollback.
+- [ ] **[LOCAL]** Full rebuild preserves state/events/proposals/workflow history;
+      only derived index data is disposable.
+
+### 19.6 Focused automated gates
+
+```sh
+bun test --timeout=120000 \
+  tests/integration/migrate-format.test.ts \
+  tests/migrate/task-v2-to-v3-files.test.ts \
+  tests/tasks/migrate-v2-to-v3.test.ts \
+  tests/integration/config-recovery-concurrency.test.ts \
+  tests/integration/file-lock.test.ts \
+  tests/integration/index-writer-lock.test.ts \
+  tests/integration/index-writer-lock-crossproc.test.ts \
+  tests/integration/proposal-durable-recovery.test.ts
+```
+
+---
+
+## 20. Security and Adversarial Testing
+
+Security gates are fail-closed. A green regression suite proves only represented
+cases; it does not waive an uncovered boundary. Never turn a known vulnerability
+into expected behavior. Hostile archives, DNS/rebinding, kill points, and native
+process tests run only in a bounded disposable container or VM.
+
+### 20.1 Failure and evidence oracle
+
+- [ ] Use only dummy credentials, controlled loopback services, local archives,
+      and outside-sandbox sentinels. Never contact metadata services, a LAN host,
+      production registry, or private infrastructure.
+- [ ] Rejected usage normally exits `2`, invalid configuration `78`, dangerous
+      install `1`, and health warning `4`. Exit `70`, signal death, resource
+      exhaustion, partial publication, or silent success is a failure.
+- [ ] For stateful rejection compare config, lock, cache, index, source bytes,
+      databases, event cursor, process/listener set, stdout, and stderr.
+- [ ] Capture terminal-control fixtures to files and inspect bytes through a
+      non-rendering program. Never print them directly to a terminal.
+- [ ] Security `FAIL` or `BLOCKED` blocks release unless the release record has a
+      named issue, impact, owner, mitigation, approver, and expiry.
+
+### 20.2 Filesystem containment and links
+
+```sh
+outside="$AKM_SANDBOX/outside-sentinel"
+mkdir -p "$outside"
+printf 'outside-must-not-change\n' >"$outside/sentinel"
+ln -s "$outside" "$AKM_BUNDLE_DIR/memories/qa-link"
+
+set +e
+akm remember 'must not escape' --name escaped --path qa-link \
+  >"$AKM_SANDBOX/link-write.stdout" \
+  2>"$AKM_SANDBOX/link-write.stderr"
+link_status=$?
+set -e
+
+test "$link_status" -eq 2
+test ! -e "$outside/escaped.md"
+test "$(cat "$outside/sentinel")" = outside-must-not-change
+rm "$AKM_BUNDLE_DIR/memories/qa-link"
+```
+
+- [ ] **[LOCAL]** Remember/import/env/secret/workflow/task/proposal writes reject
+      absolute, parent, mixed-separator, NUL, drive/device, and descendant-
+      symlink escapes before mutation.
+- [ ] **[LOCAL]** Manual and Git-backed walkers skip escaping file/directory
+      symlinks, including tracked and untracked Git links. Outside marker never
+      enters search/show/snippets/embeddings/model prompts/index DB.
+- [ ] **[LOCAL]** Internal links follow one documented containment rule; hardlink,
+      FIFO/device, unreadable, disappearing, and rename-race cases stay bounded.
+- [ ] **[LOCAL REGRESSION]** Direct write primitives and Git-listed asset reads
+      enforce the same realpath boundary. Any outside read/write blocks release.
+- [ ] **[LOCAL]** Archive extraction rejects absolute/traversing names, unsafe
+      strip results, escaping symlink/hardlink targets, duplicate/type-conflict
+      members, devices/FIFOs/sockets, and unsupported types before publication.
+
+### 20.3 SSRF, redirects, DNS, and network budgets
+
+Section 9.8's `NODE_ENV=test` crawl is a protocol seam only. Prove an ordinary
+installed CLI cannot activate that seam merely through ambient environment:
+
+```sh
+before_requests="$(wc -l <"$AKM_QA_SERVICE_LOG")"
+set +e
+NODE_ENV=test akm bundle add "$AKM_QA_WEBSITE_URL" \
+  --name qa-ambient-bypass --allow-insecure-transport \
+  >"$AKM_SANDBOX/ambient-bypass.stdout" \
+  2>"$AKM_SANDBOX/ambient-bypass.stderr" </dev/null
+ambient_status=$?
+set -e
+
+installed="$(akm bundle list --format json |
+  jq '[.sources[]? | select(.name == "qa-ambient-bypass")] | length')"
+if test "$installed" -ne 0; then
+  akm bundle remove qa-ambient-bypass --yes >/dev/null 2>&1 || true
+fi
+
+test "$ambient_status" -eq 78
+test "$installed" -eq 0
+test "$(wc -l <"$AKM_QA_SERVICE_LOG")" -eq "$before_requests"
+```
+
+- [ ] **[SERVICE REGRESSION]** Ambient `NODE_ENV=test`/`BUN_TEST=1` cannot bypass
+      production private-host policy. Current failure requires a fix, not PASS.
+- [ ] **[SERVICE]** Reject loopback/private/link-local/metadata/CGNAT/multicast/
+      reserved/documentation IPv4, IPv6, mapped IPv6, NAT64, 6to4, userinfo, and
+      non-HTTP schemes.
+- [ ] **[SERVICE]** Mixed public/private, empty, and failed DNS results fail
+      closed. Validate and constrain every redirect hop, not only the first URL.
+- [ ] **[DESTRUCTIVE]** Rebinding fixture proves the connection uses the approved
+      address or equivalent enforcement; a second unpinned DNS lookup fails.
+- [ ] **[SERVICE]** Strip auth/cookie/proxy-auth on cross-origin redirect and
+      bound redirects, DNS, headers/body, bytes, rate-limit wait, and total time.
+- [ ] **[SERVICE REGRESSION]** Equivalent egress policy covers website pages/
+      robots/feeds, response-derived media URLs, URL health checks, registries,
+      npm metadata/tarballs, setup recommendations, and self-update downloads.
+- [ ] Request logs prove no forbidden destination was contacted; error text alone
+      is not evidence.
+
+### 20.4 Registry, package, Git, and archive trust
+
+- [ ] **[LOCAL]** Git source/ref rejects option-shaped refs, control chars,
+      `ext::`, `fd::`, `file:`, unknown/insecure schemes, and revision mismatch.
+      Subprocesses use argv, bounded time, and noninteractive auth.
+- [ ] **[SERVICE]** npm honors strong SRI before SHA-1, requires integrity,
+      validates every redirect host, and executes no package lifecycle script
+      while materializing a bundle.
+- [ ] **[DESTRUCTIVE]** Archive budgets cover compressed/expanded bytes, member
+      count, per-member size, depth, compression ratio, listing/extraction time,
+      and partial staging cleanup.
+- [ ] **[SERVICE]** Registry response size/count/depth/string limits apply to
+      static and skills providers before parse/cache/render. Malformed/control-
+      character data cannot poison another registry.
+- [ ] **[SERVICE REGRESSION]** Registry list/config/info/search never expose
+      literal option credentials or credential-bearing URLs; install guidance is
+      inert and safely quoted.
+- [ ] **[SERVICE]** Setup binds an official recommendation ID to its expected
+      authenticated install ref; an arbitrary configured registry cannot replace
+      that ref under the same display ID.
+- [ ] **[LOCAL REGRESSION]** Failed add/update/remove restores prior config,
+      lock, cache, root, index, and event cursor, including re-add of an existing
+      source. No success event precedes security audit.
+
+### 20.5 Dangerous env, secrets, output, and permissions
+
+```sh
+before_event="$(akm log --format json | jq -r '.events[-1].id // 0')"
+set +e
+akm bundle add \
+  "$REPO/tests/fixtures/manual-qa/suppressed-dangerous-bundle" \
+  --name qa-suppressed-dangerous \
+  >"$AKM_SANDBOX/suppressed.stdout" \
+  2>"$AKM_SANDBOX/suppressed.stderr" </dev/null
+suppressed_status=$?
+set -e
+
+test "$suppressed_status" -eq 1
+test "$(akm log --format json | jq -r '.events[-1].id // 0')" = "$before_event"
+! akm bundle list --format json |
+  jq -e '.sources[]? | select(.name == "qa-suppressed-dangerous")'
+```
+
+- [ ] **[LOCAL REGRESSION]** Publisher lint suppression cannot suppress
+      untrusted install security; scan read errors fail closed; inferred,
+      declarative, normal update, and force update use the same pre-publication
+      audit.
+- [ ] **[LOCAL]** Runtime blocks source-origin `LD_PRELOAD`, `DYLD_*`, `PATH`,
+      `NODE_OPTIONS`, `BASH_FUNC_*`, and `GIT_CONFIG_*`; first-party use warns.
+- [ ] **[LOCAL]** Exact dummy values and credential-shaped URL/userinfo/query/
+      fragment variants are absent from AKM stdout/stderr, errors, events,
+      task logs, databases, reports, proposals, workflows, backups, and config.
+- [ ] **[LOCAL]** JSON/YAML stay parseable; text/Markdown visibly encode terminal
+      controls; HTML escapes attacker fields. Inspect captured bytes only.
+- [ ] **[LOCAL]** Env/secret directories and files akm creates are `0700`/`0600`
+      even under umask 022, as are config backups and scheduler invocation
+      files. The data directory, the databases and their sidecars, and per-run
+      task logs take the process umask: akm neither sets nor reports on those.
+- [ ] **[PLATFORM]** Windows ACL evidence replaces POSIX mode checks and is marked
+      N/A only when genuinely unsupported.
+
+### 20.6 Execution, agents, model output, and listeners
+
+- [ ] **[LOCAL]** Command arrays preserve exact argv for whitespace, quotes,
+      semicolons, substitutions, newlines, percent signs, and platform meta-
+      characters. No shell appears unless explicitly selected by contract.
+- [ ] **[PLATFORM]** Cron/launchd/schtasks serialization round-trips argv without
+      shell/XML injection; timeout/cancel removes process tree and scheduler entry.
+- [ ] **[AI]** Empty, fenced, think-block, malformed, nested, oversized, and
+      schema-invalid model output fails closed within bounded attempts/bytes.
+- [ ] **[AI]** Asset text containing fake verdict JSON, rubric overrides, tool
+      instructions, and exfiltration requests cannot make a rejecting fake judge
+      pass or publish a proposal.
+- [ ] **[AI REGRESSION]** Every AKM-managed listener has an unpredictable
+      per-process credential. Unauthenticated local requests get `401`, the AKM
+      client authenticates, and the credential is never durable.
+- [ ] **[AI REGRESSION]** The OpenCode SDK fallback listener is not considered
+      safe merely because it binds loopback or chooses a random port.
+- [ ] **[LOCAL]** Active-bundle custom wiki fetchers are trusted executable code;
+      installation alone cannot import one, and activation requires an explicit
+      reviewed trust decision.
+
+### 20.7 Malformed input and resource exhaustion
+
+- [ ] **[LOCAL]** Reject `__proto__`, `constructor`, and `prototype` at every
+      config/import merge depth; ordinary object prototypes remain unchanged.
+- [ ] **[LOCAL]** Wrong top-level types, duplicate keys, invalid UTF-8/NUL,
+      extreme numbers, oversized strings/arrays/nesting, truncated JSON/YAML,
+      and YAML alias expansion terminate within bounded memory/time.
+- [ ] **[LOCAL]** Workflow source/step/param/fan-out/plan/depth limits fail before
+      durable run creation or engine dispatch.
+- [ ] **[LOCAL]** Malformed input emits no stack, spawns no child, makes no model
+      or public request, writes no partial state, and never exits `70`.
+- [ ] Fuzz/property failures retain the seed as a deterministic fixture.
+
+### 20.8 Focused security suite and disposition
+
+```sh
+bun test --timeout=120000 \
+  tests/redaction.test.ts \
+  tests/registry-resolve.test.ts \
+  tests/opencode-sdk-runner.test.ts \
+  tests/integration/website-ssrf.test.ts \
+  tests/integration/tar-utils-scan.test.ts \
+  tests/integration/walker.test.ts \
+  tests/integration/vault-dangerous-key-install-gate.test.ts \
+  tests/integration/vault-dangerous-key-lint.test.ts \
+  tests/integration/env-run-dangerous-key-block.test.ts \
+  tests/integration/config-sanitize-secrets.test.ts \
+  tests/integration/self-update.test.ts
+```
+
+Current known failing gates must be fixed or explicitly waived with expiry:
+
+| Boundary | Required disposition |
+| --- | --- |
+| Ambient test-mode SSRF bypass and secondary URL sinks | `FAIL` until guarded |
+| Git/direct-write symlink escape | `FAIL` until contained |
+| Archive expanded-resource/type/link budgets | `FAIL` until bounded |
+| Registry option/control-data rendering | `FAIL` until redacted |
+| Registry URL credential persistence and rendering | `PASS` — #811 passed independent review after seven hardening cycles |
+| Suppressible/add-only dangerous-key audit and event ordering | `FAIL` until pre-publication |
+| Source lifecycle rollback across config/lock/root/index/events | `FAIL` until atomic/recoverable |
+| OpenCode local-listener authentication/documentation | `FAIL` until authenticated |
+| Exact-value command-target task-log redaction | `PASS` — fixed in 0.9.1 (#755) |
+| Package-manager upgrade exact-version verification | `PASS` — fixed 2026-08-06 (`self-update.ts`) |
+
+---
+
+## 21. Package, Runtime, Platform, and Release
+
+Release acceptance runs against the exact candidate commit and bytes. A local
+source build, packed npm artifact, standalone binary, installer, and published
+release are different subjects and require separate evidence.
+
+### 21.1 Supported matrix and build boundaries
+
+| Surface | Current support/constraint |
+| --- | --- |
+| npm package | Node `>=22` bootstrap; Bun `>=1.0` preferred, Node fallback supported |
+| Node fallback | Test Node 22 and 24; requires built dist and usable SQLite dependency |
+| Standalone | Linux x64/arm64 glibc, macOS x64/arm64, Windows x64 |
+| Unsupported standalone | Alpine/musl, 32-bit, native Windows ARM64 |
+| POSIX installer | Linux/macOS x64/arm64; `AKM_INSTALL_DIR` override |
+| Windows installer | PowerShell 5.1+, x64 binary; ARM64 uses x64 emulation |
+| Scheduler | Linux crontab, macOS LaunchAgent, Windows Task Scheduler |
+
+```sh
+bun install --frozen-lockfile
+bun run check
+bun run build
+
+test -x dist/akm
+test -x dist/akm-migrate
+test -f dist/cli.js
+test -f dist/cli-node.mjs
+test -f dist/scripts/akm-migrate.js
+test -f dist/scripts/akm-migrate-node.js
+test ! -e dist/tests
+
+node dist/akm --version
+node dist/cli-node.mjs --version
+bun dist/cli.js --version
+```
+
+- [ ] **[RELEASE]** Build emits `src/**` only plus deliberately copied runtime
+      assets and migration entries; no test/general helper tree leaks into dist.
+- [ ] **[RELEASE]** Package bins are exactly `dist/akm` and `dist/akm-migrate`,
+      both Node-shebang launchers with Bun preference and Node fallback.
+- [ ] **[RELEASE]** Relative ESM imports are Node-compatible and all module-local
+      text/YAML/XML assets needed at runtime are present.
+- [ ] **[RELEASE]** Build may regenerate schema but leaves no unexplained tracked
+      diff. Release acceptance uses verify-only lint, not formatting mutation.
+
+### 21.2 npm pack, isolated install, and runtime parity
+
+```sh
+bun run test:package
+bun test --timeout=120000 \
+  tests/package-install.test.ts \
+  tests/integration/package-install.test.ts \
+  tests/integration/package-launcher.test.ts \
+  tests/integration/npm-bin-contract.test.ts
+
+bun run build
+# Install the exact spec package.json declares — never a range of your own.
+# better-sqlite3 compiles from source whenever there is no prebuilt binary for
+# the running Node's ABI, and a from-source build against Node 24.19+ headers
+# aborts at teardown (#790). CI does the same read-back. Remove it first:
+# `npm install pkg@version` is a no-op when that version is already installed
+# and will NOT rebuild the binding for the Node you are about to test with.
+rm -rf node_modules/better-sqlite3
+npm install --no-save \
+  "better-sqlite3@$(node -p "require('./package.json').optionalDependencies['better-sqlite3']")"
+AKM_SMOKE_NODE=node bun run test:node-smoke
+AKM_SMOKE_NODE=node bun run test:node-compat
+```
+
+- [ ] **[RELEASE]** Test-package packs and installs under a temporary prefix,
+      verifies package/version/bin ownership, runs both launchers, and cleans up.
+- [ ] **[PLATFORM]** Repeat Node smoke/compat on Node 22 and 24. Every gated test
+      runs rather than skips; no Bun global leaks into the forced Node path.
+- [ ] **[PLATFORM]** Missing/failed/pre-1.0 Bun probe falls back to Node; current
+      Bun is selected. Paths with spaces and Windows `%*` preserve argv.
+- [ ] **[PLATFORM]** Node 20 package install fails at preinstall with the Node 22
+      diagnostic and leaves no usable bins.
+- [ ] **[RELEASE]** Packed payload contains required dist/docs/schemas and omits
+      source, tests, repository scripts, `.git`, `.akm`, and `node_modules`.
+- [ ] **[RELEASE]** Packed README equals `.github/README.npm.md`. Run lifecycle
+      staging only in a disposable worktree because it overwrites `README.md`.
+
+`bun run build:install` replaces the configured machine-global installation and
+is never an ordinary manual QA command.
+
+### 21.3 Docker and standalone artifacts
+
+```sh
+./tests/docker/run-docker-tests.sh
+
+# Focused alternatives:
+./tests/docker/run-docker-tests.sh ubuntu-binary
+./tests/docker/run-docker-tests.sh --bun-only
+./tests/docker/run-docker-tests.sh --binary-only
+
+# Test wrapper; without the variable the file skips:
+AKM_DOCKER_TESTS=1 bun test tests/integration/docker-install.test.ts
+```
+
+- [ ] **[PLATFORM]** Four Bun-linked source variants pass: Ubuntu, Debian,
+      Alpine, Fedora. Three local linux-x64 binary variants pass: Ubuntu,
+      Debian, Fedora. Summary is seven passes, zero failures/skips.
+- [ ] **[PLATFORM]** Matrix proves CLI startup, bundle create, index/search/show/
+      info/list, and incremental indexing. It does not prove npm pack, published
+      artifact, installer, self-upgrade, ARM, macOS, or Windows.
+- [ ] **[RELEASE]** Cross-compile five exact standalone names; run each on native
+      OS/architecture and verify the embedded version and supported command surface.
+- [ ] **[RELEASE]** `checksums.txt` covers exactly five binaries and both
+      installers. The npm tarball is compared separately because it is generated
+      later.
+
+### 21.4 Installers and self-upgrade
+
+Use release-attached installers, not raw `main`, and pin a concrete tag:
+
+```sh
+VERSION="$(jq -r .version package.json)"
+TAG="v$VERSION"
+INSTALL_ROOT="$(mktemp -d)"
+
+curl -fsSL \
+  "https://github.com/itlackey/akm/releases/download/$TAG/install.sh" \
+  -o "$INSTALL_ROOT/install.sh"
+AKM_INSTALL_DIR="$INSTALL_ROOT/bin" bash "$INSTALL_ROOT/install.sh" "$TAG"
+"$INSTALL_ROOT/bin/akm" --version
+```
+
+- [ ] **[LIVE PLATFORM]** Correct OS/arch asset downloads; exact checksum entry
+      verifies before replacement; unsupported arch/tool/permission/mismatch
+      fails closed.
+- [ ] **[PLATFORM]** Windows installer uses isolated `AKM_INSTALL_DIR`, verifies
+      SHA-256, records/reverses PATH mutation, and runs x64 candidate.
+- [ ] **[RELEASE]** Installers support `AKM_INSTALL_DIR`; do not document a
+      nonexistent `--prefix` option.
+
+Real self-upgrade runs only in a disposable VM/container from a compatible
+older 0.9 release:
+
+```sh
+unset AKM_UPGRADE_SKIP_CHECKSUM
+akm --version
+akm migrate status
+akm upgrade --check --format json
+akm upgrade --format json
+akm --version
+akm migrate status
+akm info
+```
+
+- [ ] **[LIVE DESTRUCTIVE]** Check is nonmutating. npm/Bun/pnpm global installs
+      invoke their package manager; standalone streams bounded bytes, verifies
+      checksum, preflights the staged binary, and atomically replaces it.
+- [ ] **[LIVE DESTRUCTIVE]** Failure retains explicit recoverable old/new
+      artifacts. Integrity bypass variable is never set for acceptance.
+- [ ] **[LIVE]** A 0.8 package can be replaced, but its config/state are not
+      runtime inputs: archive them, initialize current paths, then explicitly
+      migrate retained task-v2 sources.
+- [ ] **[LIVE]** RC/`next` cannot be validated through latest-stable discovery;
+      record post-publication stable self-upgrade as blocked until discoverable.
+
+### 21.5 Native scheduler acceptance
+
+Use an installed npm or standalone candidate and a disposable OS account. Do
+not hide an ineligible checkout behind `--rebind` in release acceptance.
+
+- [ ] **[PLATFORM]** Doctor reports eligible `npm`/`standalone` binding with
+      absolute candidate paths and no credentials in the row.
+- [ ] **[PLATFORM]** Add disabled task, inspect native definition, enable/edit +
+      sync, trigger, verify candidate version/history/log, delete YAML + sync,
+      and prove native removal.
+- [ ] **[PLATFORM]** Preserve unrelated crontab/plist/schtasks entries and exact
+      argv quoting. Context descriptor is content-addressed and mode `0600` on
+      POSIX.
+- [ ] **[PLATFORM]** Linux standalone gate runs with its required candidate bin,
+      version, and architecture variables.
+- [ ] **[PLATFORM]** macOS/Windows native test runs only on disposable GitHub
+      Actions with `CI=true`, `GITHUB_ACTIONS=true`, compiled native artifact,
+      real runner home, unique task ID, gate dirs, version, and architecture.
+- [ ] **[PLATFORM]** Windows Node variant also provides packed `akm.cmd`, exact
+      `node.exe`, path-with-spaces gate, and unique node task ID.
+
+A bare `AKM_NATIVE_SCHEDULER_TESTS=1 bun test ...` is insufficient and must not
+be recorded as PASS when the test skipped.
+
+### 21.6 Exact release gate and publication
+
+```sh
+bun run release:check
+
+# Partial local gate only:
+./tests/release-check.sh --skip-docker
+```
+
+- [ ] **[RELEASE]** Full script runs workflow syntax/contract, verify-only lint,
+      typecheck, build/bin/migration checks, package acceptance, setup/install
+      regression, explicit legacy-task migration, Linux standalone scheduler,
+      unit, integration, then Docker.
+- [ ] **[RELEASE]** Every gated file reports executed tests. Skip-docker is
+      partial unless a separate exact-commit matrix transcript exists.
+- [ ] **[RELEASE]** Cut the changelog BEFORE triggering the workflow: bump
+      `package.json` `version`, rename `## [Unreleased]` to
+      `## [<version>] - <YYYY-MM-DD>`, and leave a fresh empty `## [Unreleased]`
+      above it. This is functional, not cosmetic —
+      `src/commands/sources/migration-help.ts:84` resolves release notes by
+      skipping the `Unreleased` heading, so shipping an un-renamed section makes
+      the released binary's `akm help migrate latest` report the PREVIOUS
+      release's notes. Enforced by `tests/integration/workflow-release.test.ts`
+      ("the changelog is cut…"), which `tests/release-check.sh` runs as
+      `run_step "Workflow Release Contract"` — so a missed cut fails the release
+      gate rather than depending on this checklist being read.
+- [ ] **[RELEASE]** Official workflow input version equals committed package
+      version and targets the tested SHA. Stable uses npm `latest`; prerelease
+      uses `next` and GitHub prerelease.
+- [ ] **[RELEASE]** After publication, download every asset, verify checksums,
+      compare GitHub/npm tarballs, install under fresh Node 22/24, and run native
+      binaries/installers on supported targets.
+- [ ] **[RELEASE]** npm version is immutable. Existing GitHub assets may be
+      clobbered by rerun, so rerun only identical commit/bytes and compare hashes.
+
+---
+
+## 22. Evidence and Cleanup
+
+### 22.1 Required evidence
+
+Retain outside `/tmp/akm-*` because test cleanup can remove old matching paths:
+
+- [ ] Commit SHA, package version, candidate/artifact digests, OS/architecture,
+      Bun/Node/npm versions, exact launcher path, UTC window, tester, tiers.
+- [ ] Exact command, exit status, stdout, and stderr as separate files. Preserve
+      `PIPESTATUS[0]` when using `tee`.
+- [ ] Before/after worktree status and config/lock/bundle/cache/data/state/event
+      manifests for stateful failures.
+- [ ] Test totals and skip list. An opt-in suite that skipped is `BLOCKED`, never
+      `PASS`.
+- [ ] Pack manifest, isolated install/bin ownership, Node matrix, Docker summary,
+      native scheduler before/after, self-upgrade transcript, release/run URLs,
+      npm metadata, release inventory, and checksum transcript where applicable.
+- [ ] Every failure's reproduction result and retained rollback/stage/rescue path.
+- [ ] Every waiver's issue, impact, owner, mitigation, approver, and expiry.
+- [ ] No real token, npmrc, GitHub auth file, raw environment dump, prompt, or
+      unredacted secret-bearing state enters evidence.
+
+### 22.2 Cleanup procedure
+
+```sh
+if test -n "${AKM_QA_SERVICE_PID:-}"; then
+  kill "$AKM_QA_SERVICE_PID" 2>/dev/null || true
+  wait "$AKM_QA_SERVICE_PID" 2>/dev/null || true
+fi
+```
+
+- [ ] Delete test task YAML, sync, and inspect native scheduler to prove no AKM
+      test marker/plist/task remains.
+- [ ] Remove isolated npm prefixes, installer directories, migration clones,
+      writable remotes, containers, and VMs.
+- [ ] Remove only the seven exact `akm-test-*` Docker image tags; never broad-
+      prune a shared Docker host.
+- [ ] Archive failure shard logs/evidence before deleting announced temp roots.
+- [ ] Remove `tests/docker/.build` only by exact path after verifying it belongs
+      to this checkout.
+- [ ] Copy evidence out, then guard sandbox deletion:
+
+```sh
+case "$AKM_SANDBOX" in
+  /tmp/akm-sandbox.*) rm -rf -- "$AKM_SANDBOX" ;;
+  *) printf 'Refusing unsafe cleanup: %s\n' "$AKM_SANDBOX" >&2; false ;;
+esac
+```
+
+- [ ] Compare final worktree/status to baseline. Explain every remaining change;
+      do not use broad Git restore on a shared or dirty worktree.
+
+---
+
+## 23. Change-Based Test Selection
+
+Every production change gets focused tests during iteration and `bun run check`
+before merge. `check:changed` is a fixed fast contract battery, not diff-aware
+and not a substitute for the full check.
+
+| Changed area | Required escalation beyond focused tests |
+| --- | --- |
+| CLI dispatcher/output/command CLI | check:changed, envelope/output suites, sections 6 and 8, full check |
+| Config/paths/setup/schema | setup/install regression, first-run package path, sections 3 and 6, full check |
+| Refs/adapters/index/search/show | contract/ranking/index suites, sections 4 and 7; semantic if vectors/status changed |
+| Sources/registry/write-source | provider/write/publication suites, controlled service; LIVE git/npm/HTTPS when lifecycle changed |
+| Storage/migration/transactions | crash/concurrency/property/published-upgrade gates, section 19, destructive rehearsal for cutover changes |
+| Workflow | workflow unit/integration, gate fake agents, slow expansion, crash/contention when scheduler changed |
+| Workflow exec units / subprocess capture | section 14.5 end to end on an engine-less install, plus the worktree isolation and stale-sweep gates; any capture, timeout, or process-group change also runs the agent spawn suites, which share that subprocess layer |
+| Workflow child environment / allowlist | section 14.5 environment gates plus section 11; a change to the shared floor is native Windows, not Linux emulation |
+| Task/scheduler | task suites, Linux standalone; native macOS/Windows for backend/quoting/binding; published upgrade for schema changes |
+| Env/secret/security path/archive/network | env/secret plus traversal/SSRF/archive/redaction/dangerous-key suites, section 20 |
+| Agent/LLM/improve/proposal | family suites and fake-service AI pass; live bounded provider only for changed external dispatch |
+| Package/runtime/build dependencies | build/package/bin, Node 22/24, Bun launcher, standalone, Docker, release check |
+| Installers/self-update/standalone | installer/update suites, exact checksum/artifact tests, native install/upgrade, full release gate |
+| Workflows/release-check/Docker | workflow syntax/contract, actual Docker matrix, complete artifact inventory |
+| Test preload/helpers/runners | lint isolation, both sharded targets, multiple shard counts, leaked temp/log review |
+| Documentation only | doc-example lint and named contract tests; local evidence required because normal CI may skip docs-only changes |
+
+Minimum selection rules:
+
+- [ ] Changes to providers, refs, search/show, config, or output also run
+      `tests/contracts/` and read architecture guidance before acceptance.
+- [ ] Contract/security/migration/release changes run the full relevant section,
+      not one happy-path command.
+- [ ] A platform-specific change cannot be passed solely on Linux emulation.
+- [ ] A documentation-only change that alters commands runs those examples in a
+      sandbox even if code tests are unaffected.
+
+---
+
+## 24. Known Constraints and Blocked Gates
+
+These are current constraints, not historical expected failures. Re-audit this
+section before each release and remove an item when its implementation/gate is
+fixed.
+
+### 24.1 Supported constraints
+
+1. npm bootstrap requires Node `>=22`; Bun does not remove that requirement.
+2. No Alpine/musl standalone, native Windows ARM64, 32-bit, or non-listed target.
+3. Standalone binaries cannot load the externalized local transformer model.
+4. macOS/Windows schedules are per-user interactive; schedule grammar is narrower
+   than Linux cron and Windows expansion is bounded.
+5. Docker, semantic E2E, Node compatibility, native scheduler, published upgrade,
+   standalone scheduler, real-agent/model, and slow property gates are opt-in.
+6. Current normal CI is Ubuntu-centric and does not itself run Docker, real
+   embeddings, native macOS/Windows schedulers, or release binaries.
+7. The release workflow runs `tests/release-check.sh --skip-docker`
+   (build/publication follow it) but not Docker, the slow gate, or the Node
+   matrix — those stay separate, opt-in local/CI gates.
+8. Docker source variants use `bun link`; binary variants use a locally compiled
+   linux-x64 artifact. They do not prove npm/published bytes.
+9. Self-upgrade discovery follows latest stable/npm `@latest`, so an unpublished
+   or prerelease candidate cannot complete that happy path.
+10. 0.8-to-0.9 self-upgrade is deliberately blocked; use explicit migration.
+
+### 24.2 Open release-blocking regression gates
+
+Triaged 2026-08-06 for the 0.9.0 release: every sub-item was assessed against
+the actual test/lint/code evidence (an item counts as covered only when a test
+*asserts* the property, not merely exercises the path). itlackey reviewed the
+triage the same day and directed per-row outcomes: three rows resolved
+outright, four targeted fixes landed (registry stale fallback, upgrade
+version verification, lint fail-closed, plus the full Semantic row), and the
+remaining gaps carry approved waivers with the expiries recorded below.
+
+- [x] **Test harness:** curation cannot leave a schema-less shared `index.db`
+      that makes later proposal acceptance tests fail by file order.
+      **Resolved 2026-08-06.** Root cause: `openExistingDatabase` created the
+      missing file on open (no schema), so `curate`'s fire-and-forget usage
+      telemetry planted a broken `index.db` that later proposal acceptance saw
+      as existing-but-corrupt. It now refuses to create (`create: false` down
+      to the driver) and a missing index throws with an `akm index` remedy.
+      Regression pins: `tests/storage/open-existing-database-no-create.test.ts`
+      (order-independent distillation of the two-file repro: telemetry no-op →
+      write-path fail-open) and the original pair passing in one process
+      (`tests/curate-logic.test.ts` + `tests/commands/proposal/adapter-precommit-check.test.ts`).
+- [x] **Agent/LLM:** standalone `remember --enrich` dispatches enrichment instead
+      of silently taking the raw-write path.
+      **Resolved 2026-08-06.** The feared bug was real: `hasStructuredArgs`
+      (`src/commands/read/remember-cli.ts`) omitted `args.enrich`, so a bare
+      `--enrich` took the zero-flag hot path and never attempted enrichment.
+      Fixed (routes like `--auto`; fail-soft unchanged) and the standalone test
+      in `tests/integration/remember-frontmatter.test.ts` now asserts the
+      enrichment branch ran (warning surfaced), which it previously did not.
+- [x] **Semantic:** vector dimension validation, truthful ready-vec, JS fallback
+      after fast-path failure, runtime failure status, targeted-write readiness,
+      and cancellation propagation.
+      **Resolved 2026-08-06** (fix-now directed by itlackey at 0.9.0 triage):
+  - Truthful ready-vec: `verifyIndexState` now reports `ready-vec` only when
+    the vec fast path is actually serving (`isVecAvailable` AND
+    `isVecFastPathReady`); a degraded run reports `ready-js` with an
+    `akm index --full` hint. Pinned by
+    `tests/integration/index-verification-truth.test.ts` (forces real vec
+    insert failures via a width-mismatched mock endpoint; verified to fail
+    against the old logic).
+  - Dimension validation: `embedding.dimension` is bounded to the vec-table
+    guard's 1–4096 in the config schema (fails at `config set` with a clear
+    message instead of crashing `akm index`); the DB-layer guard itself is
+    pinned in `tests/integration/db.test.ts`.
+  - Runtime failure status: a real provider failure (HTTP 500) driven through
+    `akmIndex()` to `semanticStatus: "blocked"` is now pinned in
+    `index-verification-truth.test.ts`.
+  - Cancellation propagation: pre-aborted and mid-run-aborted signals
+    rejecting `akmIndex()` are pinned in the same file.
+  - JS fallback after fast-path failure: already covered
+    (`tests/integration/db.test.ts`, `tests/integration/vector-search.test.ts`).
+  - Targeted-write readiness: first-class writes use the same embedding
+    materializer as full indexing for the entry IDs they changed. A healthy
+    provider makes the write vector-fresh before return; provider failure keeps
+    the authored file and FTS row while publishing canonical blocked status.
+    Pinned in `tests/integration/indexer/index-written-assets.test.ts`.
+- [x] **Durability:** atomic reader-visible index generations, live-lock age,
+      full source lifecycle rollback, safe website/npm refresh, strict lockfile,
+      registry stale fallback, and sync/write serialization.
+      **Closed for 0.9.1** — the last open item (#758) landed; see the
+      per-item history below.
+  - Covered: strict lockfile (`tests/integration/lockfile.test.ts` corrupt-
+    lockfile fail-closed + CAS cases).
+  - **Fixed 2026-08-06** (fix-now directed at 0.9.0 triage): registry stale
+    fallback — a failed registry fetch now serves the cached index even past
+    its TTL, with a warning, instead of hard-failing
+    (`src/storage/repositories/registry-cache.ts`; pinned by
+    `tests/integration/registry-stale-fallback.test.ts`).
+  - **Fixed for 0.9.1** ([#757](https://github.com/itlackey/akm/issues/757),
+    [#759](https://github.com/itlackey/akm/issues/759)): four of the five
+    partial/open items landed.
+    - Live-lock age — a lock whose holder PID is genuinely ALIVE but whose
+      mtime has aged past the threshold is now pinned in both directions, at
+      the production thresholds, for the index-writer lease and the improve
+      run lock (`tests/integration/index-writer-lock.test.ts`,
+      `tests/integration/commands/improve/improve-lock-invariants.test.ts`).
+      Each positive test fails when `probeLock`'s age branch is disabled; each
+      negative control fails when it is made unconditional.
+    - Atomic index generations — a second reader connection opened from inside
+      `insertTransaction` now proves it observes the complete previous
+      generation, never zero or partial rows
+      (`tests/integration/indexer/reindex-generation-atomicity.test.ts`).
+    - Sync serialization — `createExactPathCommit`'s own CAS is raced by a real
+      concurrent commit landing inside the `update-ref` window, mirroring the
+      `write-source.ts` pattern
+      (`tests/integration/sync-exact-commit-cas.test.ts`).
+    - Safe website refresh — this one was a REAL BUG, not just missing
+      coverage: the refresh deleted the whole mirror and then wrote pages in
+      place, so an interrupted run left a partial mirror that a later
+      non-forced run would serve (the freshness marker is only rewritten on
+      success, so the stale marker still looked fresh). Fixed with
+      staging-dir-then-rename plus an age-gated sweep of abandoned staging
+      dirs (`src/sources/snapshot-fetchers/website-ingest.ts`; pinned by
+      `tests/integration/website-refresh-interruption.test.ts`, all four cases
+      of which fail against the old in-place write). Residual, documented in
+      code: publication is two renames, so a kill in that one-syscall window
+      leaves the mirror absent — `requireStashDir` callers refresh immediately,
+      others recover on the next expiry or `--force`.
+  - **Closed for 0.9.1** ([#758](https://github.com/itlackey/akm/issues/758)):
+    full source lifecycle rollback — the waiver's named verification test now
+    exists as `tests/integration/vault-dangerous-key-blocked-install-rollback.test.ts`.
+    It drives the real `akm bundle add` CLI end-to-end against a materialized
+    copy of `tests/fixtures/manual-qa/dangerous-bundle/` (whose
+    `env/runtime.env` carries `NODE_OPTIONS`), non-TTY and without
+    `--allow-dangerous-env-keys`, and asserts every lifecycle surface after the block:
+    **byte-level** parity of `config.json` and `akm.lock`, no surviving content
+    root, and no orphaned index row. Three workspace states are covered —
+    pristine, pre-existing operator config, and a bundle already installed —
+    the last of which pins the other direction too: a rollback that reverts
+    the FIRST bundle's records is as wrong as one that leaves the refused
+    bundle's behind.
+    Rollback was found already correct in every case constructible here; the
+    test's value is as a pin, so it was mutation-verified against five separate
+    breaks (skip the rollback; drop `removeLockEntry`; delete every bundle
+    instead of the target; leave the content root; skip the post-rollback
+    reindex) and fails on each.
+  - Residue accepted by design, asserted explicitly rather than left implicit:
+    (a) on a pristine workspace the attempt still SCAFFOLDS `config.json` and
+    `akm.lock` — the config/lock writers create their file on first mutation —
+    so the test pins that the created `config.json` deep-equals `DEFAULT_CONFIG`
+    with no `bundles` key and that `akm.lock` is the empty array, rather than
+    asserting absence; (b) the events stream keeps the `add` event for the
+    refused ref, because it is an append-only audit log of ATTEMPTS and an
+    operator investigating a blocked install needs it on record.
+- [ ] **Security:** Git/direct-write symlink containment, authenticated OpenCode
+      listener, registry credential/control-data redaction, archive expansion
+      budgets, universal redirect/SSRF policy, and unsuppressible update audit.
+  - Partial: symlink containment (walker escape cases tested; not exercised
+    through a real git-repo walk), registry control-data redaction
+    (response-shape limits tested), redirect/SSRF policy (website fetcher has
+    the policy; registry fetch does not apply the same private-IP guard).
+    Registry URL credential handling is implemented under #811. Strict
+    configured-value rejection and conservative diagnostic redaction passed
+    independent review after seven hardening cycles; the final focused corpus
+    covers 102 cases with 36,895 assertions.
+  - Open: authenticated OpenCode listener (localhost listener carries no
+    per-process credential), archive expansion budgets (download size capped;
+    expansion ratio/member budgets untested).
+  - Closed in #765: the unsuppressible update audit stages and re-verifies every
+    refreshed bundle before publication; keep the rejection, approval, and
+    rollback cases above in the release matrix.
+  - Tracking: [#763](https://github.com/itlackey/akm/issues/763) (listener credential),
+    [#764](https://github.com/itlackey/akm/issues/764) (archive expansion budgets),
+    [#766](https://github.com/itlackey/akm/issues/766) (git symlink containment),
+    [#767](https://github.com/itlackey/akm/issues/767) (registry SSRF),
+    [#811](https://github.com/itlackey/akm/issues/811) (registry URL credentials,
+    completed for 0.9.2).
+  - issue: local-attack-surface and hostile-upstream hardening gaps, all
+    pre-existing (none regressed in 0.9.0). impact: requires a local
+    co-resident attacker, a malicious registry/source, or a compromised
+    upstream to exploit. owner: itlackey. verification test: the checklist's
+    own §23 items (lines cited in the per-item notes). temporary mitigation:
+    sources/registries are operator-chosen; dangerous-env audit runs at
+    install; opencode listener binds loopback only. waiver approver:
+    itlackey — approved 2026-08-06 (0.9.0 release triage). waiver expiry:
+    0.10.0 (hardening series).
+- [x] **Secrets/permissions:** exact-value task-log redaction; managed-file
+      permission coverage (rejected — see below). **Row closed in 0.9.1:** both
+      halves are resolved — the redaction gap is fixed, and permission
+      management is a rejected concept rather than outstanding work. No waiver
+      remains on this row.
+  - Covered: exact-value redaction for prompt-target and workflow-target task
+    logs (`tests/integration/tasks-runner.test.ts` "redacts echoed agent
+    credentials before task logs are persisted", webhook-URL case).
+  - **REJECTED, not fixed** ([#756](https://github.com/itlackey/akm/issues/756),
+    reverted in [#791](https://github.com/itlackey/akm/issues/791)). akm briefly
+    chmodded the databases, their `-wal`/`-shm` sidecars, and the containing
+    data directory to owner-only on every `openManagedDatabase`, and wrote task
+    logs `0600` into a `0700` directory. That is no longer the intended
+    behavior and should not be re-attempted: enforcing a mode on a directory the
+    operator owns — on the most-traveled path in the CLI, including read-only
+    opens — silently converted legacy `0755` data dirs and broke installs
+    sharing `$XDG_DATA_HOME` across uids, which worked in 0.9.0.
+    **Decision: akm does not manage permissions on the data directory, the
+    databases, or task logs.** Those take the process umask; protecting the
+    data directory is the operator's call and umask/`chmod` is their lever.
+    This is scoped, not blanket — akm still creates `env`/`secret` assets,
+    config backups and scheduler invocation files at `0600`/`0700` at creation
+    time, which is a different act from re-permissioning a directory the
+    operator already owned. Nothing survives from that work:
+    the health advisory that reported on those modes is gone too — akm does not
+    nag about permissions it does not set.
+  - **Fixed** ([#755](https://github.com/itlackey/akm/issues/755), 0.9.1).
+    Exact-value redaction now runs in `persistRunLog`, the one sink all three
+    target kinds funnel through, so the command arm is covered alongside the
+    other two. Secret values come from three places, and the distinction matters:
+    config-declared credentials and a task's own `redact:` names are redacted at
+    any length, while values merely *inferred* from a variable's name must clear
+    an 8-character floor. Applying the naive rule the issue proposed — treat
+    every non-allowlisted value in the inherited environment as secret —
+    classified 127 of 132 variables as credentials, 25 of them one character
+    long, and rewrote `3 tests passed` into `[REDACTED] tests passed`. Pinned by
+    `tests/tasks/log-redaction.test.ts` and the `runTask — command target` cases
+    in `tests/integration/tasks-runner.test.ts`, including an over-redaction
+    guard that fails if ordinary build output is ever mangled.
+- [ ] **Package/release:** exact package-manager upgrade version verification,
+      native installer/scheduler coverage, action/dependency provenance hardening,
+      and post-publication artifact parity.
+  - **Fixed 2026-08-06** (fix-now directed at 0.9.0 triage): upgrade version
+    verification — after a package-manager install "succeeds", `akm upgrade`
+    now re-reads `akm --version` from PATH; a confirmed mismatch (lagging
+    `@latest` dist-tag) reports `upgraded: false` with the exact-version pin
+    remedy and skips `migrate apply` (which would have run against the old
+    binary). Fail-open only when verification itself is unavailable.
+    (`src/commands/sources/self-update.ts`; pinned in
+    `tests/integration/self-update.test.ts`.)
+  - **Fixed** ([#771](https://github.com/itlackey/akm/issues/771), 0.9.1):
+    publication is gated on the real release-acceptance script.
+    `.github/workflows/release.yml` runs `./tests/release-check.sh
+    --skip-docker` before version-verify/build/publish, so the npm bin shim,
+    the migration bundle under both the Bun and Node entry points, and the
+    packed-artifact install are all checked by CI instead of depending on the
+    operator remembering `bun run release:check` locally.
+  - **Fixed** ([#768](https://github.com/itlackey/akm/issues/768)): every
+    third-party `uses:` in `.github/workflows/*.yml` is now pinned to a full
+    commit SHA (with the tag preserved as a trailing comment) instead of a
+    mutable tag.
+  - Partial ([#770](https://github.com/itlackey/akm/issues/770)): native
+    scheduler macOS/Windows coverage is no longer unreachable —
+    `.github/workflows/gated-ci.yml`'s `native-scheduler` job now runs
+    `tests/integration/native-scheduler.test.ts` with
+    `AKM_NATIVE_SCHEDULER_TESTS=1` on real `macos-15`/`windows-2022` runners
+    (path-gated on PRs, full on the weekly schedule and release-candidate
+    tags). `install.ps1` still has no execution harness — its PATH-mutation
+    step (`[Environment]::SetEnvironmentVariable(..., "User")`) throws off
+    Windows, so a fake-harness approach like `install-script.test.ts` cannot
+    deterministically drive it outside a real Windows runner — but
+    `tests/integration/install-ps1-syntax.test.ts` now statically parses it
+    with PowerShell's own parser (runs on any host with `pwsh`, including
+    GitHub's `ubuntu-latest`), catching syntax regressions though not
+    semantic ones.
+  - Open: post-publish artifact parity (nothing compares npm tarball to
+    release assets).
+  - Tracking: [#769](https://github.com/itlackey/akm/issues/769) (post-publish artifact parity),
+    [#770](https://github.com/itlackey/akm/issues/770) (install.ps1 execution harness, if ever pursued on a real Windows runner).
+  - issue: release-infrastructure hardening. impact: a clobbered release
+    asset ships silently; tag-hijack of a third-party action could
+    compromise the release job. owner: itlackey. verification test: per-item
+    notes (workflow-lint for SHA pins; post-publish parity job). temporary
+    mitigation: releases are operator-triggered (`workflow_dispatch`) with a
+    human watching; `release:check` covers the Linux artifact end-to-end
+    when run. waiver approver: itlackey — approved 2026-08-06 (0.9.0 release
+    triage). waiver expiry: 0.10.0.
+- [ ] **Lint:** invalid type/dir fail-closed behavior, adapter type scoping,
+      malformed task coverage, and transactional/publication-aware fixing.
+  - **Fixed 2026-08-06** (fix-now directed at 0.9.0 triage): invalid
+    `--type`/`--dir` fail closed — a nonexistent `--dir` and an unknown
+    `--type` on an akm bundle (the singular/plural typo) are now usage
+    errors instead of a false-clean `ok:true, flagged:0`
+    (`src/commands/lint/index.ts`; pinned by
+    `tests/integration/lint-fail-closed.test.ts`).
+  - **Fixed for 0.9.1** (waiver discharged): all three tracked rows landed.
+    - [#760](https://github.com/itlackey/akm/issues/760) malformed task YAML —
+      the parse failure is now its own `invalid-task-yaml` finding instead of
+      collapsing onto `{}` (which every task rule short-circuits on), and a
+      `tasks/*.yaml` near miss is collected and flagged for the extension
+      rather than skipped by the walk. Fixed on all three task-lint surfaces
+      (the CLI sweep, the `akm` adapter's `validate`, and `akm-task`) from one
+      shared parse in `src/tasks/schema.ts`; pinned by
+      `tests/integration/lint-task-yaml.test.ts`.
+    - [#761](https://github.com/itlackey/akm/issues/761) `--fix` safety —
+      `--fix` against a bundle configured `writable: false` is now a usage
+      error raised before any file is touched, and a per-file fix-write
+      failure is reported in-band as `fixed: "failed"` (plus a `lint-failed`
+      finding if the per-file dispatch throws) instead of aborting the sweep
+      with an uncaught error that hid the fixes already on disk. Pinned by
+      `tests/integration/lint-fix-safety.test.ts`.
+    - [#762](https://github.com/itlackey/akm/issues/762) adapter type scoping —
+      a `--type` passed to a non-akm bundle now emits a warning naming the
+      flag and the adapter; findings are unchanged (validation was already a
+      superset). Pinned in `tests/integration/lint-adapter-dispatch.test.ts`.
+  - Also closed alongside these: [#774](https://github.com/itlackey/akm/issues/774)
+    — `missing-skill-md` is reachable again for `agent-skills` (a real
+    directory pass over `ValidateContext.list`, replacing the dangling
+    `{@link directorySkillDiagnostics}` reference), and opencode's singular
+    `skill/` alias is checked identically to `skills/`. Pinned by
+    `tests/integration/lint-missing-skill-md.test.ts`.
+
+For each unchecked row record:
+
+```text
+issue:
+impact:
+owner:
+verification test:
+temporary mitigation:
+waiver approver:
+waiver expiry:
+```
+
+The stale-consolidation CLI recovery surface was removed in 0.9.1; its two
+obsolete skipped improve-memory integration cases were deleted during the 0.9.2
+cleanup ([#794](https://github.com/itlackey/akm/issues/794)).
+Stale transaction journals remain covered through the `stale-txn-journals`
+health check. Do not carry historical failures into this list unless they remain
+reproducible against the exact candidate.