docs: retire plans/perfect-shape.md — roadmap complete

[thymikee]

What

Retires the last plan file, plans/perfect-shape.md. The plans/ directory is now empty and removed.

The perfect-shape roadmap — the two-registry thesis (CommandDescriptor + PlatformPlugin), the typed-result spine, the folder DAG + import-direction layering lint, agent-cost, and the Apple apple + appleOs platform model with a non-breaking ios/macos leaf wire — is substantively complete and merged to main. plans/phase3-platform-plugin-progress.md was already retired (#982); this removes the final plan file, per the roadmap's own §5 retirement note ("plans/ deleted incrementally, perfect-shape.md last").

Delivered (all merged)

• Phase 1 — CommandDescriptor spine; daemon-registry / capability / batch / dispatch all derive from src/core/command-descriptor/registry.ts (dispatch switch → total map).
• Phase 2 a/b — typed per-command results + TypedError.
• Phase 3 — PlatformPlugin registry + Apple consolidation: internal PLATFORMS = ['apple', …] with an appleOs discriminant, PUBLIC_PLATFORMS = ['ios', 'macos', …] non-breaking leaf output, shared engine under src/platforms/apple/core/, per-OS leaves under src/platforms/apple/os/<os>/.
• Phase 4 — agent-cost (cost block, MCP outputSchema, leveled ResponseView).
• Phase 5 — folder DAG capstone: import-direction lint scripts/layering/check.ts.

Durable decision records

The ADRs are the durable records and the retirement targets:

• ADR-0008 — Command Descriptor Registry
• ADR-0009 — Apple Platform Consolidation (AppleOS leaf axis)

Current-state terms now live in CONTEXT.md, which gains an "Architecture (perfect-shape refactor, completed 2026-07)" section describing the delivered end-state (two registries, typed spine, Apple apple/appleOs model + non-breaking wire, folder DAG + layering lint, agent-cost) with pointers to ADR-0008/0009.

Deferred / next-minor (now recorded in CONTEXT.md so they aren't lost)

1. Phase 2c — narrow the ~15 remaining Record-typed client methods in src/client/client-types.ts to their existing typed contracts (semver-relevant public-API narrowing; not yet done).
2. b.3 recording/providers facets — the two risky PlatformPlugin daemon facets (providers, recording) stay on their daemon branch as source of truth (Phase 3 b.3: platform-neutral daemon facets (providers/recording/appLog/perf) on PlatformPlugin #974 closed).
3. Strict DAG back-edge inversion — the lint enforces the achievable subset; the full zero-back-edge DAG (e.g. commands → cli/client) is not done.
4. Legacy alias drops — ~175 LOC of legacy aliases/barrels, gated to the next major.

References repointed

Every remaining perfect-shape.md/§ reference was repointed to ADR-0008/0009 or CONTEXT.md — ADRs 0003/0008/0009, .github/workflows/ci.yml, scripts/layering/check.ts, and the platform-plugin/Apple source comments (src/core/capabilities.ts, src/core/platform-plugin/{plugin,apple-os-capabilities}.ts, src/platforms/apple/plugin.ts, src/platforms/apple/os/tvos/remote.ts, src/core/__tests__/capability-plugin-routing-parity.test.ts). No dangling references remain (git grep perfect-shape.md is clean).

Verification

Docs/comment-only. tsc -p tsconfig.json --noEmit, oxlint --deny-warnings, oxfmt --check, and the layering DAG check (scripts/layering/check.ts) all pass.

The perfect-shape roadmap is complete; this retires the last plan file.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.5 MB	1.5 MB	0 B
JS gzip	477.9 kB	477.9 kB	0 B
npm tarball	578.7 kB	578.7 kB	0 B
npm unpacked	2.0 MB	2.0 MB	0 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	27.1 ms	26.7 ms	-0.4 ms
CLI --help	47.3 ms	47.1 ms	-0.2 ms

Top changed chunks: no changes in the largest emitted chunks.

[thymikee]

Review finding:

The PR removes plans/perfect-shape.md, but a few comments still cite bare roadmap section numbers with no surviving target:

• scripts/layering/check.ts still says §5.5 sdk = re-export barrels only.
• src/core/interactors/register-builtins.ts still says equivalent in spirit to the §5.1 sketch.
• src/platforms/apple/plugin.ts still says kept device-shaped here (§7).

Because the plan file is deleted, those section references are now dangling. Please repoint them to ADR-0008/ADR-0009/CONTEXT.md wording, or inline the rationale without section numbers, before retiring the roadmap.

[thymikee]

Addressed + rebased onto main (now includes #1004). Removed the three dangling section-number citations now that plans/perfect-shape.md is gone — the rationale was already inlined at each site, so:

• src/platforms/apple/plugin.ts: (§7) → do-not-flatten; see docs/adr/0009.
• src/core/interactors/register-builtins.ts: the §5.1 … sketch → an … sketch (the sketch itself is inlined right there).
• scripts/layering/check.ts: dropped (§5.5 …), kept the inline "re-export barrels only" description.

Grep confirms no surviving §/perfect-shape references except ADR-0009's narrative pointer to CONTEXT.md (valid). Verified: tsc, oxlint, oxfmt, layering guard, fallow all green.

[thymikee]

Review follow-up: the dangling roadmap section references are fixed in head 2d77c2d. I verified git grep for plans/perfect-shape.md, perfect-shape.md, and § now returns no hits, while the surviving perfect-shape narrative is anchored in CONTEXT.md/ADR references.

Checks are green (21/21). This docs/comment-only retirement looks ready for human maintainer judgment.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-02 05:19 UTC