Record ownership and Go-native principles in architecture policy

This commit is contained in:
2026-11-07 02:49:13 +00:00
parent 5d90d59996
commit e908213318
9 changed files with 106 additions and 86 deletions

View File

@@ -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,