Complete the performance audit and update documentation

docs/roadmap/implementation.md

@@ -1,6 +1,6 @@
 # Performance implementation plan
 
-Status: implementation in progress; Stages 1–8 are complete, Stages 9–11 have not started.
+Status: complete; Stages 1–11 are complete.
 
 Date: 2026-10-09.
 
@@ -876,7 +876,7 @@ are observations, not thresholds.
 
 ## Stage 11: audit the completed target and reconcile documentation
 
-**Status:** not started. **Prerequisite:** Stages 1–10.
+**Status:** complete. **Prerequisite:** Stages 1–10.
 
 **Files:** this plan, `performance.md`,
 [internal overview](../internal/overview.md), developer/README navigation,
@@ -925,4 +925,103 @@ implemented with relevant behavioral and efficiency evidence; maintained docs
 identify their current owners. No performance guarantee or additional release
 gate has been introduced.
 
-**Evidence:** pending.
+**Evidence:** Audited PF-01–PF-06 against the current implementation and
+behavioral coverage. PF-01 selects the PromptKit renderer before serialization;
+PF-02 indexes backend commands to declarations and uses parent links for the
+selected path; PF-03 caches immutable bridge metadata per `App` and uses one
+mutable adapter session per `Execute`, including help and usage; PF-04 scans
+only YAML framing lines but retains complete framed bytes; PF-05 validates and
+clones pending registrations before atomically installing them; PF-06 prepares
+owned ordered scope metadata, lookup, and discovery data at registration. The
+existing focused tests cover refresh after registration, parser/help/usage
+session reuse, YAML boundaries/directives, registration rollback, prepared
+scope ownership, selector collisions, and callback timing. OD-1 and OD-2 remain
+as selected: backend state is fresh per invocation, and YAML output retains a
+full framed buffer.
+
+The default sprint suite passed on source revision `62b4a48` with
+`GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none GOSUMDB=off go test
+-mod=readonly -count=1 ./...`. Packages `commandkit`, `internal/cobra`, and
+`scripts` passed; both examples compiled. `go list` and `go doc -all .` confirmed
+that Cobra/pflag remain confined to `internal/cobra`, the adapter does not
+import the root package, and the root exported declarations retain their
+existing signatures. Review of the sprint Go diff found no changed or added
+root exported declarations.
+
+Final representative measurements used Go 1.26.8, linux/amd64, Linux
+6.17.0-41-generic, Intel Core i5-7260U CPU @ 2.20 GHz, source revision
+`62b4a48`, and the unchanged fixtures from earlier stages. The five-sample
+command passed:
+`GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none GOSUMDB=off go test
+-mod=readonly -run '^$' -bench '^BenchmarkPerformance' -benchmem
+-benchtime=200ms -count=5 . ./internal/cobra`. Raw output is in
+`/tmp/commandkit-performance-final.txt`. Dispatch, prepared-scope, and scope
+registration benchmarks were then repeated with the same five-sample settings.
+Shortly after the measurements, the host load average was 3.62 on four logical
+CPUs; historical stage measurements did not record load. Cross-run timing
+comparisons are therefore inconclusive, while bytes and allocation counts
+remained stable.
+
+- **PF-01:** For 128 prompt inputs, final text measured 159,091–172,388 ns/op,
+  126,782–126,787 B/op, and 1,143 allocations; YAML measured 1,240,053–1,534,668
+  ns/op, 1,262,298–1,262,330 B/op, and 5,079 allocations. Stage 2 recorded
+  145,524–145,531 B and 1,171 allocations for text and 1,393,508–1,393,568 B
+  and 6,039–6,040 allocations for YAML. Four-input YAML is now 69,677–69,678 B
+  and 480 allocations versus 74,730–74,733 B and 557 at baseline. Selected
+  rendering reduces report work and allocations; profile-text timings remain
+  noisy.
+- **PF-02:** Final adapter Parse measured 242,960–242,969 B/op and 1,706
+  allocations for the shallow/wide fixture, and 119,560 B/op and 827
+  allocations for the deep fixture. Stage 4's isolated change reduced deep
+  Parse by 384 B and one allocation; later session work adds a small wrapper
+  cost. Tree construction remains in these Parse measurements; selected-path
+  lookup is recorded separately in Stage 4.
+- **PF-03:** Final repeated success measured 53,796–61,372 ns/op,
+  29,580–29,581 B/op, and 269 allocations. Local and explicit help used
+  41.4–41.9 KB and 509/516 allocations; parser and handler usage used about
+  30 KB and 292/284 allocations. Stage 9 measured 38,671–44,179 ns/op for
+  repeated success and about 41.4–41.9 KB with the same help allocation counts.
+  A focused repeat remained slower in time while allocation results stayed
+  stable. The host load noted above and the absence of a prior load record
+  prevent attributing this timing difference to the source change. Cold
+  construction plus first execution measured 84,000–93,954 ns/op and
+  38,418–38,419 B for a small app, and 616,203–678,200 ns/op and about 305 KB
+  for a wide app. The cached neutral tree still requires construction once per
+  metadata generation, and mutable backend trees are still built per invocation.
+- **PF-04:** Direct 4 KiB framing measured 1,193–1,256 ns/op, 4,864 B/op, and
+  one allocation; direct 1 MiB framing measured 188,617–561,502 ns/op,
+  1,056,768–1,056,770 B/op, and one allocation. The 1 MiB aggregate writer
+  measured 1,624,170–1,806,960 ns/op, about 4.245 MB, and 185 allocations,
+  versus the Stage 2 baseline of about 8.695 MB and 215–216 allocations. The
+  full framed copy remains part of the selected OD-2 behavior.
+- **PF-05:** Final 128-entry individual registration measured 101,116–118,013
+  ns/op, 29,420–29,421 B/op, and 293 allocations, compared with the Stage 1
+  baseline of 414,618–492,261 ns/op, about 405 KB, and 784 allocations. A
+  128-entry batch measured 104,559–118,844 ns/op, about 35,992 B/op, and 296
+  allocations, retaining the documented extra pending-index and map-growth
+  cost compared with the smaller Stage 1 batch allocation. The focused run
+  confirms this remains an allocation/timing tradeoff, not a correctness issue.
+- **PF-06:** Final two-scope discovery, named selection, and aggregate
+  validation measured 33,003–34,199, 38,275–45,600, and 44,677–65,937 ns/op,
+  respectively; allocation counts were 195, 207, and 208. At 32 scopes,
+  discovery used 199 allocations, named selection 207, and aggregate validation
+  240. The focused repeat also remained slower than Stage 10 measurements while
+  retaining the same allocation counts. Compared with Stage 2,
+  retained metadata reduces two-scope discovery from 21,161 B/223 allocations
+  to 18,559–18,560 B/195, and 32-scope aggregate validation from 29,781–29,782
+  B/269 to 22,705–22,706 B/240. The prepared suite retains ordered scopes,
+  lookup, and discovery data; registration cost grows accordingly.
+
+The runbook remains the owner of release operations, the ReleaseKit roadmap
+owns adoption status, and this performance roadmap and record own PF-01–PF-06.
+Updated the internal overview, README, and contributor navigation; replaced
+obsolete ReleaseKit-plan links in the releasekit, initial, and remediation
+records with the completed historical adoption record or current owner. Local
+Markdown links and fragments passed checks across all eight affected documents,
+and `git diff --check` passed. The Stage 1–10 implementation commits are
+`aed4c59`, `a431540`, `628dc78`, `ae656d8`, `3f8841f`, `5816dd3`, `3ad3559`,
+`a852301`, `a7960e5`, and `62b4a48`; the final audit is recorded in this commit.
+
+Remaining costs are full backend tree construction for each invocation and a
+full framed YAML buffer for delivery. No public performance guarantee or new
+release gate was added.

docs/roadmap/initial.md

@@ -593,8 +593,10 @@ implementation of additional library families. None is needed to prove the
 initial selected feature target. Application-owned commands remain extensible.
 
 Consumer migrations and source publication were kept outside the initial
-library target. Current ReleaseKit adoption is tracked in the
-[adoption roadmap](releasekit.md) and its [implementation plan](implementation.md).
+library target. ReleaseKit adoption status is tracked in the
+[adoption roadmap](releasekit.md); current release operations are in the
+[maintainer procedure](../release.md). Its completed implementation record is
+available at the [historical adoption revision](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/c0c03285f7beac3e96f1708b655c1eb2add35e79/docs/roadmap/implementation.md).
 The initial implementation targeted a usable module with maintained examples;
 it did not create placeholder publisher commands or a binary build matrix.
 

docs/roadmap/performance.md

@@ -1,6 +1,6 @@
 # Computational efficiency roadmap
 
-Status: ready for implementation; OD-1 and OD-2 resolved; implementation has not begun.
+Status: implemented; PF-01–PF-06 and selected approaches OD-1/OD-2 are complete.
 
 Date: 2026-10-09.
 
@@ -12,8 +12,8 @@ benefits, and use measurements to decide whether more complex optimizations are
 worth maintaining.
 
 This document owns the target state, priorities, and selected implementation
-scope. The [implementation plan](implementation.md) owns ordered stages,
-measurement fixtures, validation, and execution evidence. The
+scope. The completed [implementation record](implementation.md) owns ordered
+stages, measurement fixtures, validation, and execution evidence. The
 [architecture policy](../policy/architecture.md), accepted
 [ADRs](../adr/), [Go declarations](../../app.go), and
 [CLI reference](../cli.md) continue to govern behavior. Follow the

docs/roadmap/releasekit.md

@@ -8,11 +8,10 @@ Date: 2026-10-08.
 
 This roadmap defines the target state for adopting ReleaseKit as CommandKit's
 maintainer release tooling and the gaps from its reviewed baseline. The
-[implementation plan](implementation.md) owns ordered execution steps,
-stage-specific checks, and implementation evidence. This document does not
-authorize publication. The completed implementation and its evidence are
-recorded in the
-[final adoption audit](implementation.md#stage-6-audit-and-record-adoption-completion).
+[maintainer release procedure](../release.md) owns current operations. This
+document does not authorize publication. The completed implementation and its
+evidence are recorded in the
+[historical adoption record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/c0c03285f7beac3e96f1708b655c1eb2add35e79/docs/roadmap/implementation.md).
 
 The [release policy](../policy/release.md),
 [architecture policy](../policy/architecture.md), and
@@ -157,8 +156,9 @@ manual approval gate, or custom note checker.
 The implemented release policy identifies the selected integration while
 preserving substantive rules and provenance. README and developer navigation
 point to the implemented runbook and describe release-tooling status accurately.
-Current procedures belong in the runbook; this roadmap owns the target, and the
-implementation plan owns execution and evidence.
+Current procedures belong in the runbook; this roadmap owns the target and
+adoption status. The completed execution evidence remains in the historical
+adoption record.
 
 ### Licensing and incorporated material
 
@@ -176,7 +176,8 @@ integration, with links to upstream guidance where practical.
 ## Adoption coverage
 
 These IDs identify the target capabilities and remaining baseline gaps.
-Ordered assignments and checks belong in the implementation plan.
+The completed assignments and checks are preserved in the historical adoption
+record linked above.
 
 | ID | Capability gap | Target result |
 | --- | --- | --- |
@@ -185,7 +186,7 @@ Ordered assignments and checks belong in the implementation plan.
 | RK-03 | Publication launcher | One repository publication command builds the module-selected CLI without changing candidate metadata and preserves its outcomes; bootstrap output is ignored. |
 | RK-04 | Runbook and navigation | Maintainers have one canonical procedure for preparation, publication, and recovery; current documents describe available tooling accurately. |
 | RK-05 | Licensing treatment | Incorporated material receives policy-conforming attribution and texts without blanket tooling requirements. |
-| RK-06 | Integration confidence | The launcher/profile work together and adoption respects existing library boundaries; completion evidence and remaining release preparation are recorded in the implementation plan. |
+| RK-06 | Integration confidence | The launcher/profile work together and adoption respects existing library boundaries; completion evidence and remaining release preparation are recorded in the completed adoption record. |
 
 ## Acceptance criteria
 
@@ -206,8 +207,8 @@ Successful adoption has focused evidence for these integration results:
   affected documentation, notices, paths, and intended release links agree with
   the implemented integration.
 
-The implementation plan selects proportionate checks and reuses existing
-evidence where sufficient. Adoption checks are not automatically permanent
+The completed adoption record documents proportionate checks and reused
+evidence. Adoption checks are not automatically permanent
 release gates. Diagnostic `check` remains optional; the actual release publisher
 validates its final candidate once.
 
@@ -221,7 +222,7 @@ note or publish a tag merely to complete tooling adoption.
 ## Adoption completion
 
 RK-01 through RK-06 were implemented and reviewed on 2026-10-08. The
-[implementation plan's final audit](implementation.md#stage-6-audit-and-record-adoption-completion)
+[historical adoption record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/c0c03285f7beac3e96f1708b655c1eb2add35e79/docs/roadmap/implementation.md)
 records validation results and the local commit for each completed stage. No
 CommandKit release note or tag was created; preparing and publishing the first
 real release remains separate authorized work under the runbook.

docs/roadmap/remediation.md

@@ -8,7 +8,8 @@ Date: 2026-10-08.
 
 Reviewed CommandKit at `c0c03285f7beac3e96f1708b655c1eb2add35e79`, covering the
 six adoption commits from `ada2021` through `c0c0328` against the
-[ReleaseKit target](releasekit.md), [implementation plan](implementation.md),
+[ReleaseKit target](releasekit.md), the completed
+[implementation record at the reviewed revision](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/c0c03285f7beac3e96f1708b655c1eb2add35e79/docs/roadmap/implementation.md),
 and applicable policies. The previously completed documentation reconciliation
 record remains available in
 [Git history](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/c0c03285f7beac3e96f1708b655c1eb2add35e79/docs/roadmap/remediation.md).