diff --git a/README.md b/README.md index fad14d3..d1acbc5 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,8 @@ The [consumer guide](docs/consumers/guide.md) links to two maintained examples: - [Consumer guide](docs/consumers/guide.md) - [Internal package overview](docs/internal/overview.md) - [Maintainer release procedure](docs/release.md) +- [Computational efficiency roadmap](docs/roadmap/performance.md) +- [Performance implementation record](docs/roadmap/implementation.md) - [Architecture policy](docs/policy/architecture.md) - [Policy provenance](docs/policy/meta.md) @@ -30,7 +32,7 @@ The [consumer guide](docs/consumers/guide.md) links to two maintained examples: - [Initial delivery and deferred capabilities](docs/roadmap/initial.md) - [Completed initial implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/3871d837489b9955998b362587a52b47282dc021/docs/roadmap/implementation.md) - [ReleaseKit adoption roadmap](docs/roadmap/releasekit.md) -- [Release tooling implementation plan](docs/roadmap/implementation.md) +- [Completed ReleaseKit implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/c0c03285f7beac3e96f1708b655c1eb2add35e79/docs/roadmap/implementation.md) - [Historical CLI planning](docs/roadmap/01-cli-plan.md) - [Completed dispatcher planning](docs/roadmap/02-dispatch.md) - [Completed backend planning](docs/roadmap/03-backend.md) diff --git a/docs/development.md b/docs/development.md index f15f626..cf3624f 100644 --- a/docs/development.md +++ b/docs/development.md @@ -54,7 +54,8 @@ canonical documentation owners. | Public facade or adapter boundaries | [Internal overview](internal/overview.md), [ADR 0003](adr/0003-public-facade.md), and the architecture policy | | Deferred capabilities and delivery scope | [Initial feature target](roadmap/initial.md#deferred-capability-targets) and [explicit deferrals](roadmap/initial.md#explicit-deferrals) | | Initial planning history | [CLI](roadmap/01-cli-plan.md), [dispatcher](roadmap/02-dispatch.md), [backend](roadmap/03-backend.md), [facade](roadmap/04-facade.md), and [completed initial implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/3871d837489b9955998b362587a52b47282dc021/docs/roadmap/implementation.md) | -| Release tooling | [Maintainer release procedure](release.md), [ReleaseKit adoption roadmap](roadmap/releasekit.md), and [release tooling implementation plan](roadmap/implementation.md) | +| Release tooling | [Maintainer release procedure](release.md) and [ReleaseKit adoption roadmap](roadmap/releasekit.md) | +| Performance work | [Computational efficiency roadmap](roadmap/performance.md) and [performance implementation record](roadmap/implementation.md) | | Licensing or incorporated material | [Project grant](../COPYRIGHT), [license texts](../LICENSE), and [attribution](oss/attribution.md) | | Policy provenance | [Policy provenance](policy/meta.md) | @@ -62,10 +63,14 @@ Read all applicable rows for cross-cutting work. Go declarations and GoDoc own current exported contracts; the CLI reference owns operator behavior. The initial numbered roadmaps are completed planning records. The [ReleaseKit adoption roadmap](roadmap/releasekit.md) and its -[implementation plan](roadmap/implementation.md) track current maintainer -tooling work. Retained illustrations and historical staged instructions are not -current API references or assignments to restart implementation. Future -capabilities remain explicitly identified in their feature roadmaps. +[completed implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/c0c03285f7beac3e96f1708b655c1eb2add35e79/docs/roadmap/implementation.md) +record the adoption status; the +[maintainer release procedure](release.md) owns current operations. The +[performance roadmap](roadmap/performance.md) and its implementation record +own the efficiency target and evidence. Retained illustrations and historical +staged instructions are not current API references or assignments to restart +implementation. Future capabilities remain explicitly identified in their +feature roadmaps. ## Documentation validation diff --git a/docs/internal/overview.md b/docs/internal/overview.md index e682120..dfcbed2 100644 --- a/docs/internal/overview.md +++ b/docs/internal/overview.md @@ -13,20 +13,30 @@ provider adapters. Configuration reports adapt ConfigKit's public records and writers. PromptKit scope and definition handlers use PromptKit's public inspection methods and map their results to CommandKit-owned reports. -The root lowers registered command metadata into the internal adapter's neutral -bridge. The adapter returns raw parsed values and neutral syntax-failure data; -the root prepares typed input, invokes application/standard handlers, and -coordinates outcomes and diagnostic delivery. Application callbacks and their -supported error identity are handled in the root through its typed contracts. -Context and streams are passed to the adapter for its parsing and help operations. +The root lazily caches one immutable neutral bridge tree per `App`, invalidating +it after successful nonempty registration. For each `Execute`, it prepares one +adapter session and reuses that session for parsing, help, and usage. If a +callback registers commands during execution, metadata-dependent presentation +refreshes without repeating input callbacks. The root still prepares typed +input, invokes application/standard handlers, and coordinates outcomes and +diagnostic delivery. Application callbacks and their supported error identity +are handled in the root through its typed contracts. + +Configuration registration owns and normalizes its declarations, then prepares +ordered scopes, name lookup, installed operations, and a discovery DTO. Command +handlers reuse that private metadata; each invocation still creates its context +and invokes acquisition only for selected scopes. ## `internal/cobra` This package owns the Cobra-specific command tree, argument/flag parsing, -and help rendering. It translates neutral command metadata and parsed values -into a bridge result consumed by the root package. It does not import `commandkit` -and does not own registry policy, public command declarations, provider loading, -or standard inspection report rendering. +and help rendering. A session owns one mutable backend tree for an invocation; +parsing and presentation reuse it. Backend commands map directly to neutral +declarations, and Cobra parent links reconstruct only the selected command path. +The adapter returns raw parsed values and neutral syntax-failure data consumed +by the root package. It does not import `commandkit` and does not own registry +policy, public command declarations, provider loading, or standard inspection +report rendering. ## External implementation boundaries diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 1b512ec..1ff45a9 100644 --- a/docs/roadmap/implementation.md +++ b/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. diff --git a/docs/roadmap/initial.md b/docs/roadmap/initial.md index 94d5f2c..4c1280a 100644 --- a/docs/roadmap/initial.md +++ b/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. diff --git a/docs/roadmap/performance.md b/docs/roadmap/performance.md index 1c47fc1..1d9ba1f 100644 --- a/docs/roadmap/performance.md +++ b/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 diff --git a/docs/roadmap/releasekit.md b/docs/roadmap/releasekit.md index f933185..5959448 100644 --- a/docs/roadmap/releasekit.md +++ b/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. diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index 39622cd..d6d1238 100644 --- a/docs/roadmap/remediation.md +++ b/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).