Record ReleaseKit adoption review findings
This commit is contained in:
@@ -1,271 +1,124 @@
|
||||
# Documentation reconciliation work
|
||||
# ReleaseKit adoption review findings
|
||||
|
||||
Status: all twelve documentation remediation units complete.
|
||||
Status: two remediation items pending; implementation not changed by this review.
|
||||
|
||||
Date: 2026-10-07.
|
||||
Date: 2026-10-08.
|
||||
|
||||
## Purpose and authority
|
||||
## Review scope and authority
|
||||
|
||||
This checklist replaces the completed code-remediation record with the
|
||||
documentation update work agreed after the documentation audit. Use the current
|
||||
implementation, accepted ADRs, and [architecture policy](../policy/architecture.md)
|
||||
to reconcile stale status statements and superseded plans. The
|
||||
[documentation policy](../policy/documentation.md) assigns canonical owners.
|
||||
Reviewed CommandKit at `c0c03285f7beac3e96f1708b655c1eb2add35e79`, covering the
|
||||
six adoption commits from `ada2021` through `c0c0328` against the
|
||||
[ReleaseKit target](releasekit.md), [implementation plan](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).
|
||||
|
||||
Retain completed plans as clearly labeled historical records, preserve genuine
|
||||
deferrals, and direct implemented contracts to their current owners. Exact Go
|
||||
contracts belong in declarations and GoDoc; operator contracts belong in the
|
||||
[CLI reference](../cli.md); package inventory belongs in the
|
||||
[internal overview](../internal/overview.md). Roadmaps retain planning history,
|
||||
implementation status, and future work. Historical proposals must not read as
|
||||
current requirements.
|
||||
The target adoption is present: a released Go tool selection, minimal source-only
|
||||
profile, native launcher, fast subprocess tests, opt-in local publication
|
||||
exercise, and implemented runbook/navigation. The commits do not change
|
||||
production Go source or public declarations. Package dependency inspection found
|
||||
no ReleaseKit, Goldmark, or `golang.org/x/mod` runtime dependency in the root
|
||||
library or internal Cobra adapter. `scripts` contains external test files only.
|
||||
|
||||
Check each item when its documentation changes and review are complete.
|
||||
The remaining findings concern test maintainability and ambiguous normative
|
||||
wording. Neither establishes a missing production feature or a demonstrated
|
||||
publication failure. Fix them within the existing target; do not add release
|
||||
gates, new public contracts, or additional publisher machinery.
|
||||
|
||||
## D-01: reconcile the CLI proposal
|
||||
## R-01: avoid making bootstrap command details test contracts
|
||||
|
||||
Owner: [01-cli-plan.md](01-cli-plan.md).
|
||||
**Priority:** low. **Category:** code quality and unintended test constraints.
|
||||
|
||||
- [x] Replace the status claiming that no commands are implemented. Identify
|
||||
implemented operations, superseded proposals, and deferred features.
|
||||
- [x] Reconcile configuration scope defaults: every implemented configuration
|
||||
operation defaults to `app`; aggregate validation/display requires explicit
|
||||
`--scope all`. Retire the recommendation and rationale for validation defaulting
|
||||
to `all`.
|
||||
- [x] Replace singleton-repetition rejection with the selected last-occurrence
|
||||
rule, including conversion of every supplied occurrence. Remove repetition
|
||||
from the list of usage failures and label the old alternative as superseded.
|
||||
- [x] Replace obsolete `--prompt-version` examples and descriptions with the
|
||||
implemented `--version` spelling.
|
||||
- [x] Retire the upstream redaction prerequisite for rich profile reports.
|
||||
Record that effective `ExtraParams` is included using the current public
|
||||
PromptKit API, without introducing additional redaction requirements.
|
||||
- [x] Remove CommandKit mandates for application root paths, rejection of empty
|
||||
config values, overlay interpretation, and propagation from one application
|
||||
root into PromptKit. Values and presence reach application callbacks; those
|
||||
callbacks own their interpretation and acquisition paths.
|
||||
- [x] Reconcile aggregate validation output: completed scope records may already
|
||||
have been written when a later acquisition or output fails. Retire the claim
|
||||
that failure always produces no success report.
|
||||
- [x] Reconcile native display syntax: `config show --format yaml` is accepted.
|
||||
Link to the current framing contract rather than maintaining another report
|
||||
reference.
|
||||
- [x] Retire the proposed scope inventory fields for descriptions/default
|
||||
indicators and the proposed source-table presentation as current expectations.
|
||||
Link to implemented scope/source report shapes in the CLI reference.
|
||||
- [x] Remove the claim that root `app --version` is supported. Reconcile identity
|
||||
presentation with the implemented version command, optional text revision, and
|
||||
explicit YAML fields.
|
||||
- [x] Distinguish a missing definition ID operand from an explicitly blank ID:
|
||||
missing is usage failure; blank values reach the owning inspection API and
|
||||
produce operational results.
|
||||
- [x] Remove promises of automatic shared dependency reuse or mandatory
|
||||
acquisition coordination. Describe application-composed loading and optional
|
||||
invocation-local caching as consumer integration patterns.
|
||||
- [x] Keep diff and PromptKit catalogs explicitly deferred. Retire completed
|
||||
dispatch/report implementation tasks and the obsolete profile-report upstream
|
||||
dependency. Keep consumer migrations separate from library implementation.
|
||||
- [x] Label superseded alternatives and dated sibling-checkout evidence clearly.
|
||||
Replace duplicated current contracts with concise summaries and canonical links.
|
||||
**Location:** [scripts/release_test.go](../../scripts/release_test.go),
|
||||
`TestReleaseLauncherDelegatesPublication`, `assertNativeBootstrap`
|
||||
(lines 222–260), and `fakeGo` (lines 363–397).
|
||||
|
||||
**Completion:** Retired completed CLI work and reconciled obsolete choices;
|
||||
current contracts link to their owners and future work remains explicit.
|
||||
The assertion compares the entire build argument vector, including flag order
|
||||
and the absolute spelling of the output path. It also requires the two exact
|
||||
`env GOHOSTOS` and `env GOHOSTARCH` query forms. The executable double supplies
|
||||
only the first requested environment value, so a combined query would fail even
|
||||
if the launcher parsed both host values correctly.
|
||||
|
||||
## D-02: reconcile dispatcher planning
|
||||
The publication assertion similarly compares a complete argument vector,
|
||||
requiring `--repo` to precede `--config` even though the upstream CLI accepts
|
||||
either order before the version operand.
|
||||
|
||||
Owner: [02-dispatch.md](02-dispatch.md).
|
||||
For example, reordering build flags, using a relative output path resolved from
|
||||
the already verified repository root, or combining host queries can preserve
|
||||
the selected behavior while failing these tests. The target requires native
|
||||
bootstrap from the module-selected package, readonly metadata, the selected
|
||||
toolchain/workspace settings, and the intended executable destination. It does
|
||||
not make these equivalent command spellings permanent contracts.
|
||||
|
||||
- [x] Remove the pending status and claims that the registry, typed inputs,
|
||||
constructors, binding/group APIs, handler signatures, and outcomes are absent
|
||||
or unresolved.
|
||||
- [x] Retire completed API design, implementation sequence, and evidence tasks.
|
||||
Clearly label retained illustrations as historical; the public `Supplied`
|
||||
type is now implemented.
|
||||
- [x] Link current API usage to Go declarations/GoDoc and the
|
||||
[consumer guide](../consumers/guide.md), and current mechanics to the internal
|
||||
overview. Preserve application migration work as separate future work.
|
||||
The [testing policy](../policy/testing.md#test-behavior-not-implementation) and
|
||||
[agent policy](../policy/agents.md#implementation-discipline) call for protecting
|
||||
those selected behaviors without elevating implementation details.
|
||||
|
||||
**Completion:** Replaced pending dispatcher work with a completed planning
|
||||
record and links to implemented API, consumer, and internal owners.
|
||||
Required work:
|
||||
|
||||
## D-03: reconcile backend planning
|
||||
- [ ] Assert the required build settings, selected package, and resolved output
|
||||
destination without requiring one incidental flag ordering or path spelling.
|
||||
- [ ] Make host-query fixture handling and assertions reflect the requested
|
||||
host values rather than requiring separate subprocess query forms. Keep the
|
||||
fixture small; a complete Go command emulator is unnecessary.
|
||||
- [ ] Check the publication command, option values, version operand, and
|
||||
argument boundaries without fixing the order of independent options. Retain
|
||||
the upstream requirement that options precede the version.
|
||||
- [ ] Preserve checks for wrong native target, missing readonly mode, incorrect
|
||||
package/output, workspace or toolchain mistakes, failed bootstrap, and
|
||||
publication status/stream propagation.
|
||||
|
||||
Owner: [03-backend.md](03-backend.md).
|
||||
Completion evidence: focused launcher checks still detect the selected failures
|
||||
and accept an equivalent bootstrap form. This is a test correction, not a
|
||||
requirement to refactor the working launcher or add a release-time check.
|
||||
|
||||
- [x] Remove claims that the module dependencies, adapter, and invocation behavior
|
||||
are unimplemented. Link dependency facts to [go.mod](../../go.mod) and notices to
|
||||
[attribution](../oss/attribution.md).
|
||||
- [x] Remove the unresolved singleton-rejection discussion and reconcile it with
|
||||
accepted repetition semantics.
|
||||
- [x] Retire completed version-selection, translation, parsing/help, integration,
|
||||
and evidence tasks. Link current behavior to its owners; retain backend
|
||||
replacement and consumer adoption only as future work where applicable.
|
||||
## R-02: clarify optional diagnostic validation in the runbook
|
||||
|
||||
**Completion:** Recorded the implemented backend, retired completed adaptation
|
||||
tasks, and replaced singleton-rejection proposals with canonical references.
|
||||
**Priority:** low. **Category:** potentially strengthened prohibition.
|
||||
|
||||
## D-04: reconcile facade planning
|
||||
**Location:** [docs/release.md](../release.md), lines 76–77.
|
||||
|
||||
Owner: [04-facade.md](04-facade.md).
|
||||
The instruction “Do not require a separate `check` before `publish` or repeat
|
||||
the same suite” combines the intended rule against mandatory duplicate
|
||||
validation with wording that can be read as prohibiting an operator from
|
||||
voluntarily rerunning diagnostics.
|
||||
|
||||
- [x] Remove the pending status and claims that public declarations,
|
||||
implementation packages, the adapter, and dependency versions do not exist.
|
||||
- [x] Retire the illustrative `internal/engine` and `internal/command` layout as
|
||||
an active implementation target. Link to the actual root and internal adapter
|
||||
inventory without creating another maintained package reference.
|
||||
- [x] Retire completed API/boundary design and documentation tasks. Preserve
|
||||
legitimate future backend replacement considerations.
|
||||
- [x] Keep old automated boundary-checker suggestions clearly historical or
|
||||
optional; do not turn them into a new implementation requirement.
|
||||
The [release policy](../policy/release.md#candidate-validation) permits a
|
||||
validation-only diagnostic command and says it must not be a required
|
||||
prerequisite before publication repeats the checks. Avoiding automatic duplicate
|
||||
validation does not establish a blanket prohibition on optional diagnostic runs.
|
||||
The launcher correctly delegates once; this finding concerns the runbook's
|
||||
description, not its executable behavior.
|
||||
|
||||
**Completion:** Recorded facade completion, retired illustrative extra
|
||||
packages, and preserved backend replacement and proportionate-check
|
||||
considerations.
|
||||
Required work:
|
||||
|
||||
## D-05: close the preparation checklist
|
||||
- [ ] Say explicitly that `check` is optional for diagnosis and is not a
|
||||
required step before `publish`.
|
||||
- [ ] Scope the duplicate-validation instruction to the automated publication
|
||||
workflow and configured additional checks. Preserve operator discretion to
|
||||
investigate or rerun a check.
|
||||
- [ ] Retain the single publication command and its own final-candidate suite;
|
||||
do not add a required preliminary check or an extra confirmation.
|
||||
|
||||
Owner: [initial-plan.md](initial-plan.md).
|
||||
Completion evidence: document review confirms the runbook distinguishes an
|
||||
optional diagnostic action from a release requirement and agrees with the
|
||||
existing policy. No implementation change is needed for this item.
|
||||
|
||||
- [x] Mark roadmap preparation and implementation-plan handoff complete.
|
||||
- [x] Remove claims that exact declarations still await specification and that
|
||||
the staged plan is the next deliverable. Link to the completed plan and current
|
||||
API owners.
|
||||
- [x] Check the completed final handoff item and label the preparation process
|
||||
and recommended outline as historical planning material.
|
||||
## Review evidence and limits
|
||||
|
||||
**Completion:** Closed the planning handoff, checked its final item, and
|
||||
labeled the retained process and outline as historical.
|
||||
- Read the adoption diffs, launcher/profile, new test functions and fixtures,
|
||||
runbook, policy edits, historical navigation changes, and completion records.
|
||||
- Inspected package dependencies with offline module access and confirmed the
|
||||
production boundary and tests-only `scripts` package. Verified the committed
|
||||
launcher mode and ignored local executable storage.
|
||||
- Reviewed what the tests actually assert, including the local fixture's exact
|
||||
tag-object comparison, candidate commit, one suite marker, clean worktree, and
|
||||
endpoint-mismatch preflight behavior. The completion record reports earlier
|
||||
successful default and opt-in runs; this review did not rerun those tests or
|
||||
attempt publication.
|
||||
- No other adoption gap, newly imposed release gate, public API expansion, or
|
||||
runtime publication-code defect was identified in the reviewed changes.
|
||||
|
||||
## D-06: clarify completed feature and implementation records
|
||||
|
||||
Owners: [initial.md](initial.md) and the
|
||||
[completed initial implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/3871d837489b9955998b362587a52b47282dc021/docs/roadmap/implementation.md).
|
||||
|
||||
- [x] Replace ownership statements written in future tense in the feature roadmap with
|
||||
links to the existing GoDoc and CLI reference. Clearly identify detailed
|
||||
specifications as the completed design baseline.
|
||||
- [x] Label the implementation plan as a completed execution record and explain
|
||||
that subsequent fixes were committed after its original completion.
|
||||
- [x] Reconcile the statement that definition commands have no `--scope` flag:
|
||||
they have no built-in configuration-scope selection, but application-declared
|
||||
context selectors may use that name when it does not collide.
|
||||
- [x] Preserve the explicitly labeled “At planning time” baseline as historical
|
||||
context. Keep diff/catalog and other genuine deferrals visible; completed
|
||||
design records must not become competing current API/CLI references.
|
||||
|
||||
**Completion:** Labeled feature specifications and staged instructions as
|
||||
completed history, linked current owners, and recorded later code fixes and
|
||||
selector-name behavior.
|
||||
|
||||
## D-07: correct the current CLI reference
|
||||
|
||||
Owner: [cli.md](../cli.md).
|
||||
|
||||
- [x] Correct aggregate YAML framing prose: scope comments can precede an inline
|
||||
document-start marker; they are not always after the marker. Preserve the
|
||||
native content and one YAML document per scope.
|
||||
- [x] Qualify engine acquisition/construction wording. Standard handlers invoke
|
||||
registered inspection callbacks; the bundled helper acquires an engine through
|
||||
the application loader. Direct callbacks retain their own implementation and
|
||||
lifecycle rather than guaranteeing fresh engine construction.
|
||||
- [x] Describe the absence of execution/provider/credential operations as the
|
||||
behavior of CommandKit's inspection path, preserving application callback
|
||||
ownership of its effects.
|
||||
- [x] Correct cancellation attribution: cancellation can be detected at
|
||||
CommandKit's standard-handler boundaries as well as returned by PromptKit.
|
||||
Preserve supported error identity and operational classification.
|
||||
|
||||
**Completion:** Corrected native marker/comment placement, qualified callback
|
||||
and engine lifecycle claims, and reconciled cancellation attribution.
|
||||
|
||||
## D-08: remove stale policy status statements
|
||||
|
||||
Owners: [testing.md](../policy/testing.md) and [oss.md](../policy/oss.md).
|
||||
|
||||
- [x] Remove the testing policy's claim that there is currently no Go suite.
|
||||
Keep concrete validation commands in the developer guide.
|
||||
- [x] Remove the OSS policy's claim that Cobra/pflag are not incorporated and
|
||||
that their notices still await introduction. Link to existing attribution;
|
||||
keep version inventories out of the policy.
|
||||
- [x] Preserve policy rules and upstream provenance while correcting local
|
||||
implementation status. This work does not add testing or licensing gates.
|
||||
|
||||
**Completion:** Removed stale Go-suite and dependency-status claims while
|
||||
preserving policy rules, adopted versions, and upstream provenance.
|
||||
|
||||
## D-09: correct the internal bridge description
|
||||
|
||||
Owner: [internal/overview.md](../internal/overview.md).
|
||||
|
||||
- [x] Correct the claim that application callbacks cross the adapter bridge.
|
||||
Handler callbacks and typed invocation coordination remain in the root;
|
||||
the adapter exchanges neutral metadata and parse results.
|
||||
- [x] Keep inventory/mechanics here and normative responsibility boundaries in
|
||||
the architecture policy.
|
||||
|
||||
**Completion:** Corrected neutral metadata/results flow and root callback
|
||||
ownership; distinguished adapter help rendering from standard inspection
|
||||
reports.
|
||||
|
||||
## D-10: reconcile navigation and reading guidance
|
||||
|
||||
Owners: [development.md](../development.md) and [README.md](../../README.md).
|
||||
|
||||
- [x] Route current implementation work to GoDoc, consumer guidance, CLI
|
||||
reference, internal overview, and applicable ADRs/policies.
|
||||
- [x] Label the older numbered roadmaps as completed/historical planning rather
|
||||
than the active source of unresolved implementation decisions.
|
||||
- [x] Update README roadmap labels/navigation to match the reconciled statuses.
|
||||
Keep genuine future-work navigation discoverable without duplicating contracts.
|
||||
|
||||
**Completion:** Routed current work to canonical contracts and mechanics,
|
||||
labeled completed planning records, and exposed genuine deferrals separately.
|
||||
|
||||
## D-11: remove temporary references from durable ADRs
|
||||
|
||||
Owners:
|
||||
[ADR 0004](../adr/0004-standard-inspection-surface.md),
|
||||
[ADR 0006](../adr/0006-command-grammar.md),
|
||||
[ADR 0007](../adr/0007-native-yaml-reports.md),
|
||||
[ADR 0008](../adr/0008-semantic-configuration-diff.md), and
|
||||
[ADR 0009](../adr/0009-configuration-scopes.md).
|
||||
|
||||
- [x] Remove references to documents under `docs/roadmap` from these permanent
|
||||
records, using durable references where appropriate.
|
||||
- [x] Preserve accepted decision content and historical context. Link maintenance
|
||||
must not change architectural decisions or manufacture new requirements.
|
||||
- [x] Confirm that no ADR retains a temporary-roadmap reference after the edits.
|
||||
|
||||
**Completion:** Removed all temporary-roadmap links from ADRs through editorial
|
||||
reference updates; accepted statuses, dates, and architectural choices remain
|
||||
unchanged.
|
||||
|
||||
## D-12: review the reconciled documentation
|
||||
|
||||
- [x] Review every changed document against its canonical owner and current code.
|
||||
Verify command spellings, defaults, outcomes, ownership, and report descriptions
|
||||
affected by the corrections.
|
||||
- [x] Check local links and heading targets, including links affected by retiring
|
||||
sections. The audit found no unresolved local prose links or heading targets;
|
||||
preserve that result.
|
||||
- [x] Check diffs for whitespace, stale references, and claims that delivered
|
||||
components are absent or superseded choices remain active requirements.
|
||||
Historical baselines and explicitly labeled rejected alternatives remain valid.
|
||||
- [x] Confirm that deferred features are still identified accurately and that
|
||||
reconciliation introduces no new APIs, commands, guarantees, or consumer policy.
|
||||
- [x] Record completion here and commit completed documentation units under the
|
||||
local commit policy. Use document review for this prose work; do not add tests
|
||||
or validation machinery solely to reconcile documentation.
|
||||
|
||||
**Completion:** Reviewed all changed documentation against current code and
|
||||
owners; local links, headings, whitespace, deferrals, and preserved ADR/policy
|
||||
scope checked.
|
||||
|
||||
## Final reconciliation evidence
|
||||
|
||||
All D-01 through D-12 items are complete. The completed records distinguish
|
||||
historical planning from implemented contracts and genuine future work. Review
|
||||
confirmed that only Markdown documents changed, accepted ADR metadata and
|
||||
architectural choices were preserved, and policy source/version provenance was
|
||||
retained. Local prose links and heading targets resolve; diff whitespace checks
|
||||
passed. No Go tests were added or run for this documentation-only work.
|
||||
Leave source publication, hosted delivery, binary assets, and other explicitly
|
||||
deferred capabilities outside this remediation work. Update item status only
|
||||
after the relevant correction and evidence are complete.
|
||||
|
||||
Reference in New Issue
Block a user