akm docs

akm 0.9.0 — open-items register

Close-out record for the three-phase 0.9.0 release-review cleanup program (commits 28e4b55..HEAD on the release-review branch).

What this document is. A consolidated list of what the program closed and what it deliberately did not. It replaces an earlier 825-line per-item essay that had grown into a parallel bug tracker; the underlying detail still lives in the source registers it was scanned from — 0.9.0-docs-code-drift-register.md, 0.9.0-public-api-issue-backlog.md, and 0.9.0-release-surface-review.md — which remain the authoritative per-item records.

Confidence. The deferred items below came from register scanners that tree-checked each claim by reading code and running the CLI from source. They were not adversarially re-verified by a second agent. Registers in this repo have been found wrong about the tree more than twenty times during this program; treat every row as a lead to confirm, not a fact. Anything actually acted on was re-verified against the tree first, and several rows were dropped at that point because the premise turned out to be false.

Closed during close-out

Item Change Commit
R-045 / Q-18 / X-RULING-11 (owner ruling 11) instruction registered as a stash-resident asset type: placement spec with an instructions/ stash dir, matcher row, and a compile-time placementTypes() ⊆ KnownType assertion b4df01f, 316d47e
R-039 / X-RULING-9 (owner ruling 9) semanticSearchMode defaults to "off" so a bare or headless install never silently downloads the ~130 MB embedding model; the interactive wizard still pre-selects it on, with the download warning moved ahead of the prompt f04932f
R-027 (D-49 class) akm secret path and akm secret remove removed outright — they resolved a ref through different stash-selection logic, so a lookup and a deletion could name different files 686b51c
node-smoke(24) CI failure withEnv gained an optional deadline so a hung fn() can no longer leak env overrides into the rest of the run 47cad80
Ruling 12, R-053, NEW-A The four unlanded ruling-12 breaking changes: canonical bare-group behavior across all eleven groups (which is R-053), the save→sync event rename, and the dead installedKitCount / graphPath envelope fields. Also fixed NEW-A — RESPONSE_CONTRACT_JSON was teaching agents the retired <type>:<name> ref grammar that Q-08 now rejects 47559b0

Each ruling-12 item carries a CHANGELOG migration note under Breaking.

Deferred past 0.9.0

Nothing below blocks the release. Each row is one lead; the source registers carry the evidence.

Three rows were dropped rather than deferred, because re-verification refuted their premise: Q-17 (runtime-boundary-design.md was ruled retired, but the file is deliberately kept with an implementation-note banner), D-03 (the mv tier entry carries a claim already disproved), and E6 (setup schedules). They are recorded here only so a future scan of the source registers does not resurrect them as new.

Open owner decisions

Item Question
R-038 akm extract is documented without a privacy / LLM-transmission disclosure — does it need one?
R-036 Scheduled akm improve entries sit outside the experimental.improveAutonomy gate
NEW-E citty silently accepts unknown flags; no decision yet on whether to reject them
E5 Same-run promotion gap: no triage.postPass, no akm improve --drain
C7 akm add --allow-insecure authorizes two unrelated risks through one flag
G2 --source carries two different axes; the --from stash|registry|both rename was never made
G4 claude-code vs claude as the canonical harness id
R-010, R-011, R-016, R-042, R-044, R-059 Six earlier deliberate deferrals, confirmed still untouched

Behavior defects

Item Defect
A1 akm search --no-project-context is a no-op and its documented env-var fallback does not exist
A2 The blocked semantic-search warning does not distinguish "not configured" from a real fault
B1 The generic --format text fallback (≈37 commands) was never implemented
B3 config path, config validate, and env path write raw stdout and ignore --format
B4 hints is missing from FORMAT_EXEMPT_COMMANDS, so it ignores --format silently
R-009 akm search rejects the empty query its own help advertises
R-013 akm add --provider npm silently creates a filesystem bundle
R-014 akm add --provider text output prints Installed undefined
R-015 akm update --all silently skips non-lock-backed sources with no report
R-018 akm curate --type bypasses the curation algorithm
R-019 akm curate hard-caps registry results at 2 regardless of --limit
R-020 akm show drops the canonical ref from its payload
R-021 --detail brief as a flag and as a config default produce different payloads
R-055 Reads that write (utility-score updates) are undisclosed and have no opt-out
R-057 akm info omits stashDir / defaultBundle / per-type counts and bypasses --quiet
R-058 akm update deletes without confirmation while akm remove prompts
R-067 Three process.exit() sites remain despite a commit claiming otherwise
D-38 akm log list --limit is documented but silently ignored
C4 akm config enable|disable is a hardcoded skills.sh alias, listed Stable
C6 upgrade --skip-checksum ships and is tab-completable; STABILITY.md documents the inverse
C9 Four of six env-var hygiene actions were never performed
R-064 #3, D-16 Two items whose premise needs a live run to settle

Dead code and internal drift

Item Defect
R-063 #2/#3/#5/#6/#8/#9/#11 Confirmed-dead symbols, including curate's now-unreachable colon-grammar helpers
R-064 #1/#2/#4/#5 IndexOptions.reEnrich, IndexResponse.graphQuality, a void-ed durationMs, a dead updatable read
R-065 #1/#2/#4/#5, R-068 #1/#6 Comments and TODO(R2) markers that describe implemented features as unimplemented, or name the wrong store
R-066 #1 Two near-identical secret-directory walkers coexist
B5 Vestigial distill registrations
NEW-B The ref-grammar lint gate cannot see src/**/*.ts. NEW-A (RESPONSE_CONTRACT_JSON teaching agents the retired <type>:<name> grammar) was fixed in 47559b0, but the blind spot that let it survive a zero-tolerance sweep is still there
NEW-C, NEW-D Docblocks asserting premises the tree contradicts (citty behavior; "adapters barrel is test-only")
C8 Two tracker-ID references survive a 4-of-6 scrub
X-AKM-TEST-CLAIM STABILITY.md claims AKM_TEST_* is compiled out of release builds; no build step does that

Documentation drift

Roughly fifty rows, nearly all in docs/reference/cli.md, configuration.md, registry.md, architecture.md, and the migration guides: undocumented flags and subcommands, stale counts, dead anchors, and examples that exit non-zero. Tracked as D-04, D-06 through D-15, D-17 through D-29, D-31, D-33, D-34, D-36, D-39, D-40, D-44, D-45, D-49 through D-57, D-62, D-63, Q-01, Q-06, Q-09 through Q-16, Q-19, R-005, R-048, C2, H3, X-CLI-MD-WORKFLOW, and Part5-2 through Part5-4 in the source registers.

Two of these are worth pulling forward because they teach agents something false rather than merely being incomplete:

Not scanned

0.9.0-decisions.md and 38 "major" findings from the Phase-3 documentation review (X-PHASE3-MAJORS) were never worked through item by item. The Phase-3 blockers were fixed; its majors were not individually verified.

tests/TESTS_REVIEW.md was also in this list. It has since been scanned: all 67 of its findings were dispositioned against the tree on 2026-08-12 (issue #773) — 49 fixed, 14 still open, 4 superseded by decision — and the document was replaced with that disposition record. The still-open items are grouped into six themed clusters there.