akm-cli 0.9.30 → 0.9.32

package/docs/architecture/specs/0.9.0-open-items-register.md

@@ -0,0 +1,135 @@
+# 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-docs-code-drift-register.md),
+[`0.9.0-public-api-issue-backlog.md`](0.9.0-public-api-issue-backlog.md), and
+[`0.9.0-release-surface-review.md`](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:
+
+- `D-49` — `docs/guides/claude-code-vs-akm-workflows.md` Parts B–E describe the
+  pre-engine world ("akm does not execute workflow steps", "strictly
+  sequential", "no workers"). All of it was overtaken by `workflow run`'s native
+  executor, the fan-out scheduler, worktree isolation, and YAML v2 programs. A
+  rewrite must also state that the engine is gated behind
+  `experimental.workflowEngine` and refuses with exit 78 until it is set.
+- `X-CLI-MD-WORKFLOW` — the same gate is missing from
+  `docs/reference/cli.md`'s workflow section, whose subcommand table also omits
+  five shipped verbs.
+
+### 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.