From e90821331874c926eb5f95216dc2bb4bcbf4a115 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 7 Nov 2026 02:49:13 +0000 Subject: [PATCH] Record ownership and Go-native principles in architecture policy --- docs/adr/0001-command-dispatch-and-inputs.md | 2 +- .../adr/0002-public-facade-and-cli-backend.md | 2 +- docs/adr/0003-configuration-scopes.md | 2 +- docs/adr/0004-optional-integration-modules.md | 2 +- docs/adr/0005-application-alias-routing.md | 2 +- docs/adr/0006-invocation-reporting.md | 2 +- docs/adr/README.md | 39 +------- docs/policy/architecture.md | 96 +++++++++++++++---- docs/roadmap/promptkit-v0.19.0.md | 45 ++++----- 9 files changed, 106 insertions(+), 86 deletions(-) diff --git a/docs/adr/0001-command-dispatch-and-inputs.md b/docs/adr/0001-command-dispatch-and-inputs.md index f7d0632..4eb5987 100644 --- a/docs/adr/0001-command-dispatch-and-inputs.md +++ b/docs/adr/0001-command-dispatch-and-inputs.md @@ -2,7 +2,7 @@ ## Status -Accepted. Consolidated during the [alpha ADR cleanup](README.md#alpha-consolidation). +Accepted. ## Date diff --git a/docs/adr/0002-public-facade-and-cli-backend.md b/docs/adr/0002-public-facade-and-cli-backend.md index b733a09..5a19920 100644 --- a/docs/adr/0002-public-facade-and-cli-backend.md +++ b/docs/adr/0002-public-facade-and-cli-backend.md @@ -2,7 +2,7 @@ ## Status -Accepted. Consolidated during the [alpha ADR cleanup](README.md#alpha-consolidation). +Accepted. ## Date diff --git a/docs/adr/0003-configuration-scopes.md b/docs/adr/0003-configuration-scopes.md index 8a5fb3a..0ccd3ff 100644 --- a/docs/adr/0003-configuration-scopes.md +++ b/docs/adr/0003-configuration-scopes.md @@ -2,7 +2,7 @@ ## Status -Accepted. Consolidated during the [alpha ADR cleanup](README.md#alpha-consolidation). +Accepted. ## Date diff --git a/docs/adr/0004-optional-integration-modules.md b/docs/adr/0004-optional-integration-modules.md index f43747a..8d129ed 100644 --- a/docs/adr/0004-optional-integration-modules.md +++ b/docs/adr/0004-optional-integration-modules.md @@ -2,7 +2,7 @@ ## Status -Accepted. Consolidated during the [alpha ADR cleanup](README.md#alpha-consolidation). +Accepted. ## Date diff --git a/docs/adr/0005-application-alias-routing.md b/docs/adr/0005-application-alias-routing.md index bca2afe..0c97c0d 100644 --- a/docs/adr/0005-application-alias-routing.md +++ b/docs/adr/0005-application-alias-routing.md @@ -2,7 +2,7 @@ ## Status -Accepted. Renumbered during the [alpha ADR cleanup](README.md#alpha-consolidation). +Accepted. ## Date diff --git a/docs/adr/0006-invocation-reporting.md b/docs/adr/0006-invocation-reporting.md index 21f7e86..daec796 100644 --- a/docs/adr/0006-invocation-reporting.md +++ b/docs/adr/0006-invocation-reporting.md @@ -2,7 +2,7 @@ ## Status -Accepted. Consolidated during the [alpha ADR cleanup](README.md#alpha-consolidation). +Accepted. The structured-report formatting extension is accepted but not yet implemented; the [adoption roadmap](../roadmap/promptkit-v0.19.0.md#shared-core-report-output-prerequisite) tracks that work. diff --git a/docs/adr/README.md b/docs/adr/README.md index 783ffa8..e414dfe 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -2,8 +2,7 @@ These records explain major structural and ownership decisions. The [architecture policy](../policy/architecture.md) owns normative boundaries; -GoDoc and the [CLI reference](../cli.md) own implemented contracts. The -[roadmap](../roadmap/promptkit-v0.19.0.md) owns planned work and implementation status. +GoDoc and the [CLI reference](../cli.md) own implemented contracts. | ADR | Decision | | --- | --- | @@ -13,39 +12,3 @@ GoDoc and the [CLI reference](../cli.md) own implemented contracts. The | [0004](0004-optional-integration-modules.md) | Optional integration modules and upstream ownership | | [0005](0005-application-alias-routing.md) | Alias routing and canonical command ownership | | [0006](0006-invocation-reporting.md) | Invocation reporting, outcomes, and presentation ownership | - -## Alpha consolidation - -On 2026-11-07, the maintainer authorized a one-time exception to ADR immutability -while CommandKit was in alpha. Fourteen records were consolidated, revised, and -consecutively renumbered into the six above. The normal -[ADR policy](../policy/documentation.md#architecture-decision-records) continues -to apply after this cleanup. This exception does not authorize rewriting -published releases or changing implemented behavior through documentation alone. - -The [pre-consolidation records](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/76c00e32d05eb9f2f150f3554bd578192efe3a61/docs/adr) -remain available in Git history. Earlier references use that historical numbering. -The mapping below identifies where rationale or current contracts now belong; -it does not preserve removed records as parallel specifications. - -| Former record | Current owner | -| --- | --- | -| 0001 — Dispatch and inputs | ADR 0001 | -| 0002 — Cobra backend | ADR 0002 | -| 0003 — Public facade | ADR 0002; module boundaries in ADR 0004 | -| 0004 — Inspection surface | Capability rationale in ADR 0003; command inventory in the CLI reference | -| 0005 — Invocation outcomes | ADR 0006; numeric statuses and exact behavior in CLI/API contracts | -| 0006 — Command grammar | Shared parsing rationale in ADR 0001; grammar in the CLI reference | -| 0007 — Native YAML reports | Disclosure ownership in ADR 0004; presentation ownership in ADR 0006; current formats in the CLI reference | -| 0008 — Semantic comparison | Upstream ownership in ADR 0004; comparison reports and outcomes in CLI/API contracts | -| 0009 — Configuration scopes | ADR 0003 | -| 0010 — Optional modules | ADR 0004 | -| 0011 — Captured declarations | Structural decisions in ADR 0001; detailed mechanics in GoDoc | -| 0012 — Comparison pairs | Input/state separation in ADR 0001; provider lifetimes and selectors in CLI/API contracts | -| 0013 — Alias routing | ADR 0005 | -| 0014 — Invocation reporting | ADR 0006 | - -Current command and API contracts remain in force. Accepted changes to format -handling and independent comparison selections remain planned in the adoption -roadmap until implemented. Removing an ADR's detailed specification does not -silently remove those contracts or implement their planned replacements. diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 2e0ccd0..452932b 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -2,7 +2,7 @@ **Base Policy Version:** 1.3 -**Last Updated**: 2026-11-07 +**Last Updated**: 2026-11-06 **Upstream Source:** [architecture.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md) @@ -23,6 +23,22 @@ Exact exported contracts belong in Go declarations and GoDoc; implemented operator behavior belongs in the CLI reference. Do not describe planned packages or APIs as existing implementation. +## Ownership Boundaries + +Applications and integration handlers choose the operation and report content; +CommandKit core supplies the shared CLI mechanics. Integrated libraries retain +ownership of their domain behavior. These boundaries govern current and planned +capabilities; they do not imply that a planned API is implemented. + +| Area | CommandKit Owns | CommandKit Does Not Own | +| --- | --- | --- | +| **CLI output — core** | Format selection, serialization, template execution, and output delivery | Choosing report content or detail level; authoring application-specific text templates | +| **PromptKit/ConfigKit integrations** | Standard commands, flags, and report content that expose useful operator tasks through upstream public APIs | Helpers or convenience interfaces for application-internal use of upstream APIs | +| **CLI inputs** | CLI syntax, parsing, typed bindings, presence tracking, and usage diagnostics | Application business rules or upstream domain-validation semantics | +| **Upstream behavior** | Selecting and invoking supported capabilities, adapting their results, and preserving their meaning | Reimplementing upstream configuration resolution, prompt preparation, validation, or other domain algorithms | +| **Outcomes and errors — core** | Carrying and presenting selected outcomes; handling CommandKit's own parsing, rendering, and delivery failures | Deciding application recovery policy or terminating the process | +| **Application lifecycle** | Command dispatch and invocation reporting lifecycle | Application startup, engine construction, credential provisioning, signal handling, or long-lived application state | + ## Success Criteria Evaluate designs and adoption against both criteria: @@ -42,11 +58,29 @@ Replacing parsing and dispatch plumbing with equally repetitive registration or callback bookkeeping does not satisfy infrastructure reduction. Keep enough flexibility to express genuine application requirements within one command model. +## Go Types And Facilities + +CommandKit is a Go library for Go applications. Its APIs and implementation use +ordinary Go types, language features, and standard-library facilities. Their +documented semantics and representational limits are accepted design constraints. +CommandKit does not introduce substitute type systems or compatibility machinery +merely to circumvent those limits. + +Ordinary parsing, application-defined domain types, and necessary serialization +adapters remain appropriate. Preserve values that the selected Go types can +represent; accepting their limits does not justify accidental rounding or +truncation during conversion. Keep CLI boundary conversions small and focused, +without turning them into general-purpose type-conversion frameworks. + +Specific numeric parsing and report serialization contracts remain separate. +A CLI parser's selected numeric types do not establish a blanket restriction on +application-supplied values or silently redefine their serialization contracts. +GoDoc and CLI documentation own implemented behavior; roadmaps own pending work. + ## Command And Application Ownership [ADR 0001](../adr/0001-command-dispatch-and-inputs.md) records the selected dispatcher, captured declarations, installation boundary, and typed-input model. -The [ADR index](../adr/README.md) records the alpha consolidation and renumbering. CommandKit owns dispatch, common parsing, presence tracking, help, shared syntax diagnostics, and the handlers and CLI contracts of its standard families. @@ -67,7 +101,7 @@ Applications own their executable entry points, context creation, signals, stream selection, runtime construction, and final process exit. CommandKit returns invocation outcomes and must not terminate the process. Its common mechanics apply to custom commands without taking ownership of their domain -semantics or success-report formats. +semantics or report content. CommandKit's grammar applies to commands using its dispatcher and binding APIs. Its documentation recommends the same grammar and vocabulary for application-owned @@ -130,6 +164,21 @@ messages; callers choose the destinations. ownership model. Its accepted structured-report extension remains planned in the [adoption roadmap](../roadmap/promptkit-v0.19.0.md#shared-core-report-output-prerequisite). +For that shared report handoff, core owns format selection, serialization, +template execution, and delivery. Applications and integrations select logical +report content and detail level, and author any report-specific text templates. +Changing format must not implicitly change that content or detail level. +Representations and encoders are core implementation choices; commands should +not maintain parallel rendering pipelines or a separate report tree per format. + +Use ordinary Go report values and thin projections where upstream data needs +adaptation. Prefer standard serialization and template facilities to a new public +document model, tag convention, or template language. Shared rendering serves +both invocation reporting and direct writer use, while invocation delivery keeps +the existing visibility, outcome, and presentation-failure lifecycle. Exact +serialization conventions, format options, and API signatures belong in the +roadmap until implemented, then in their API and CLI contracts. + Applications decide how to respond to domain-specific errors. CommandKit may provide shared helpers for carrying, inspecting, and presenting errors while leaving those decisions with the application. Supplying an error cause alone @@ -139,9 +188,10 @@ handles its own errors, including routing, parsing, and presentation failures. Preserve application-defined domain classifications and supplied error identity. Report rendering and delivery failures separately from the command's explanation and cause, applying the [CLI reporting contract](../cli.md#presentation-failures). -Intentionally suppressed output is not a delivery failure. Present terminal failure explanations -after normal reporting finishes, avoid duplicate presentation through core's own -paths, and retain the explanation and any supplied cause in the returned outcome. +Intentionally suppressed output is not a delivery failure. Present terminal +failure explanations after normal reporting finishes, avoid duplicate presentation +through core's own paths, and retain the explanation and any supplied cause in +the returned outcome. Keep reporting state scoped to the invocation's presentation and returned outcome. Logging and message history remain application concerns. @@ -207,9 +257,11 @@ backend isolation principles in boundaries. The core owns command declarations, registration, bindings, dispatch, help/version, -shared syntax, diagnostics, and outcomes. Each integration owns its standard -handlers, provider contracts, reports, adapters, and integration-specific public -types. Dependencies point from integrations toward the core; an integration may +shared syntax, reporting mechanics, diagnostics, and outcomes. Each integration +owns its standard handlers, provider contracts, report content, adapters, and +integration-specific public types. Integrations expose operator-facing CLI tasks; +they do not provide convenience interfaces for application-internal upstream APIs. +Dependencies point from integrations toward the core; an integration may depend on another integration when its responsibility requires that relationship. Document those dependencies. Core public signatures, implementation imports, and module requirements remain independent of optional integration libraries, @@ -245,10 +297,10 @@ without exporting private assembly or backend structures. ## Backend And Library Integration [ADR 0002](../adr/0002-public-facade-and-cli-backend.md) selects Cobra with pflag -as the sole initial backend. Their types and operations stay inside an internal adapter that -translates CommandKit-owned definitions into backend machinery. Registry logic, -standard handlers, and shared internal representations remain independent of -backend-specific structures. +as the sole initial backend. Their types and operations stay inside an internal +adapter that translates CommandKit-owned definitions into backend machinery. +Registry logic, standard handlers, and shared internal representations remain +independent of backend-specific structures. Reuse backend routing and parsing mechanisms, adapting them to selected CommandKit semantics. Do not replicate Cobra's entire API through renamed @@ -256,9 +308,9 @@ wrappers. Introduce narrow internal interfaces where actual interactions justify them; a public backend selection or plugin framework is not part of the design. ConfigKit and PromptKit own configuration composition, provenance, inspection -semantics, secret classification, and native rendering. Applications provide -schemas, acquisition, domain resolution and validation, and construction of -inspection providers. CommandKit exposes those capabilities through supported +semantics, secret classification, and their native inspection representations. +Applications provide schemas, acquisition, domain resolution and validation, +and construction of inspection providers. CommandKit exposes those capabilities through supported upstream APIs. The public contract of the adopted library version governs their meaning and disclosure rules. When CommandKit adopts an upstream revision, changes to those semantics flow through its integration. Adaptation and @@ -282,6 +334,18 @@ Concrete integration needs guide provider representations under Use upstream safe inspection data to preserve owning-library meaning and disclosure rules under [ADR 0004](../adr/0004-optional-integration-modules.md). +Do not reconstruct inspection reports from mutable runtime configuration or source +files when the upstream inspection API supplies captured, safe evidence. Explicit +adaptation into ordinary report values must preserve the selected evidence and +report conversion failures rather than silently changing its meaning. + +CommandKit parses and forwards supplied CLI selections and overrides through the +declared acquisition boundary. Upstream libraries retain path validity, +resolution, precedence, conflict handling, and domain validation. Preserve their +errors instead of inventing a parallel override policy or retrying with altered +values. Application loading and application-owned overrides retain their own +responsibilities. + The [CLI reference](../cli.md#show-effective-configuration) owns current native report formats and operation-specific preparation and delivery timing. Semantic comparison exposes the adopted upstream comparison API and carries its evidence diff --git a/docs/roadmap/promptkit-v0.19.0.md b/docs/roadmap/promptkit-v0.19.0.md index a58db58..d268919 100644 --- a/docs/roadmap/promptkit-v0.19.0.md +++ b/docs/roadmap/promptkit-v0.19.0.md @@ -11,21 +11,12 @@ completion checklist identifies verification boundaries without redefining polic ## Ownership principles -Applications and integration handlers choose the operation and report content; -CommandKit core supplies the shared CLI mechanics. Integrated libraries retain -ownership of their domain behavior. - -| Area | CommandKit Owns | CommandKit Does Not Own | -| --- | --- | --- | -| **CLI output — core** | Format selection, serialization, template execution, and output delivery | Choosing report content or detail level; authoring application-specific text templates | -| **PromptKit/ConfigKit integrations** | Standard commands, flags, and report content that expose useful operator tasks through upstream public APIs | Helpers or convenience interfaces for application-internal use of upstream APIs | -| **CLI inputs** | CLI syntax, parsing, typed bindings, presence tracking, and usage diagnostics | Application business rules or upstream domain-validation semantics | -| **Upstream behavior** | Selecting and invoking supported capabilities, adapting their results, and preserving their meaning | Reimplementing upstream configuration resolution, prompt preparation, validation, or other domain algorithms | -| **Outcomes and errors — core** | Carrying and presenting selected outcomes; handling CommandKit's own parsing, rendering, and delivery failures | Deciding application recovery policy or terminating the process | -| **Application lifecycle** | Command dispatch and invocation reporting lifecycle | Application startup, engine construction, credential provisioning, signal handling, or long-lived application state | - -These agreed principles are recorded here for eventual incorporation into -[architecture.md](../policy/architecture.md). +The [architecture ownership table](../policy/architecture.md#ownership-boundaries) +and [Go types and facilities policy](../policy/architecture.md#go-types-and-facilities) +now own the agreed principles. Core supplies CLI mechanics and output formatting; +applications and integrations choose report content, and upstream libraries own +domain semantics. This roadmap owns the implementation work and its specific +input, serialization, and presentation contracts. ## Purpose and ownership @@ -406,9 +397,8 @@ When implementation lands, update the native-writer and mapping-order requirements. The aggregate presentation decision below also replaces separate-document framing. These presentation changes follow the ownership boundary in [ADR 0006](../adr/0006-invocation-reporting.md); they do -not require a separate successor ADR. The -[alpha consolidation](../adr/README.md#alpha-consolidation) retired the former -detailed report records without changing current behavior. +not require a separate successor ADR. Current display behavior remains in force +until the implementation and its canonical contracts change. This approach reduces new machinery by reusing standard serialization and centralizing the remaining conversion and rendering work. Exact internal @@ -642,6 +632,9 @@ or field order. ## Validation and completion checklist Select focused boundary tests under the [testing policy](../policy/testing.md). +The ownership and Go-native policy work is complete in +[architecture.md](../policy/architecture.md#ownership-boundaries). The checks below +cover implementation and its documentation, which remain pending. The checklist concerns core reporting and adapter/CLI behavior; it does not ask CommandKit to retest PromptKit rendering, schema, namespace, or ConfigKit resolution algorithms. @@ -737,11 +730,10 @@ rather than prescribing one test per line or exact cosmetic snapshots. thin projections, one shared rendering implementation, and focused tests. - [ ] Update CLI/API contracts, release notes, and examples with the implementation, including report framing, independent comparison selections, and validation - delivery timing. Incorporate the ownership principles into architecture.md and - replace obsolete native-YAML/document-order guidance in testing policy. The - consolidated ADRs own architectural rationale; these presentation and selector - changes need no separate successor records. Current documentation must match - the landed scope. + delivery timing. Keep contracts consistent with architecture policy and replace + obsolete native-YAML/document-order guidance in testing policy. The ADRs own + architectural rationale; these presentation and selector changes need no separate + successor records. Current documentation must match the landed scope. - [ ] Final independent-module and aligned-workspace suites pass with dependency identities recorded. Deferred features remain outside this adoption. @@ -844,9 +836,10 @@ value could be an integer: Keep this in one small, centralized internal helper dedicated to CLI JSON input. Use standard Go numeric parsing; no arbitrary-precision fallback, general-purpose number conversion package, public numeric conversion API, or extensible numeric -framework is selected. CommandKit is a Go library for Go applications and -deliberately accepts the precision and range of these Go types. It does not compensate for -their limits with alternate numeric representations. +framework is selected. This applies the +[Go types and facilities policy](../policy/architecture.md#go-types-and-facilities) +to these CLI inputs: accept the selected types' precision and range without +alternate numeric representations. **Required implementation comments:** document the syntax-based type selection, the `int64`/`uint64`/`float64` choices, accepted floating-point approximation,