akm-cli 0.10.261012-beta → 0.10.261014-beta

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

@@ -1,135 +0,0 @@
-# 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.