commandkit/docs/roadmap/implementation.md

Release tooling implementation plan

Status: Stage 1 complete; Stages 2–6 pending.

Follow the stages in integer order. This is one end-to-end sprint: intermediate stages may temporarily leave scripts, tests, and documentation inconsistent. Do not add compatibility scaffolding or repeat complete suites merely to make each intermediate stage independently releasable. Follow the local commit policy for completed, validated units; stage boundaries do not require commits.

The feature roadmap owns the target and selected choices. Read development guidance, the agent policy, testing policy, documentation policy, and the applicable release policy before implementation. Use codebase-memory tools for code discovery as instructed by AGENTS.md.

Baseline and fixed decisions

Planning baseline: 3d396b1a66bfafc509472cd74a3f8029def3d432. At that revision:

• go.mod registers ReleaseKit v0.8.0. The root module owns the selected tool version even when releasing an integration. Keep that dependency selection, all library module paths and versions, and Go minimums unchanged.
• Three JSON profiles select core, ckconfig, and ckprompt. Their only file selection is the explicit root shared-file list; hosted delivery is absent.
• scripts/release is a 49-line native-build launcher. The 506-line scripts/release_test.go and 399-line scripts/release_integration_test.go contain the test scaffolding being replaced.
• .releasekit/gitea-token is a maintainer-supplied ignored credential file. Its contents are not input to implementation or tests. Preserve the file and directory ignore rule. Do not add the credential to fixtures, logs, or commits.
• Both integrations declare core v0.2.0, while their current source requires newer APIs. Workspace-off Go 1.26.8 tests fail at baseline with missing commandkit.CompletionHint, Explanation, and other symbols. This is an existing release-readiness issue, not a reason to change dependency versions or weaken validation in this sprint. Stage 5 distinguishes this limitation from verification of the current source and selected file checks.

The former open decisions are resolved for this plan: select all four proposed generic file checks and use host-normalized registered-tool execution. Add the agreed forbidden token path and local page-only Gitea delivery. Keep ordinary source publication and hosted delivery separate. No binary delivery, CI job, library API change, dependency upgrade, or production publication is part of this sprint. No implementation-blocking design question remains.

Stage 1: Configure the three release profiles

Completed. All three profiles parse as JSON and select the planned checks and delivery destination; the credential directory remains ignored.

Edit releasekit.json, integrations/ckconfig/releasekit.json, and integrations/ckprompt/releasekit.json.

1. Preserve each profile's product, module_dir, remote, expected_push_url, and explicit validation.shared_files. The endpoint remains ssh://git@forge.maximumdirect.net:22222/base-layer/commandkit.git.
2. Add validation.go_format: true, validation.markdown: {}, and validation.module_distribution with workspace_files and local_replacements both true.
3. Add validation.forbidden_files containing only .releasekit/gitea-token. This is a literal repository-relative selection applying to the captured repository, including integration releases.
4. Add delivery with forge: "gitea", base_url: "https://forge.maximumdirect.net", owner: "base-layer", repository: "commandkit", and token_file: ".releasekit/gitea-token". Leave token_env omitted, preserving ReleaseKit's default environment override. Add no build targets or additional validators.
5. Retain /.releasekit/ in .gitignore; revise its comment from executable storage to local ReleaseKit credentials. Do not remove existing local files.

Check that all three files parse as JSON. Use the pinned configuration reference for field semantics. Root file checks stop at independent module boundaries; the forbidden-path check has its separately documented repository scope. Do not create custom validators, broader forbidden lists, or blanket exclusions.

Stage result: the intended checks and delivery destination are represented entirely by the existing upstream profile schema.

Stage 2: Centralize tool invocation and module routing

Create executable POSIX-shell scripts/releasekit as the shared entry point. Keep executable scripts/release as the existing publication convenience entry point. No shell library, module-map file, generated script, or JSON parser is needed in the launcher.

The shared entry point has these forms:

Invocation	Handling
./scripts/releasekit MODULE publish [ARGS...]	Select module defaults and invoke upstream publish.
./scripts/releasekit MODULE check [ARGS...]	Select module defaults and invoke upstream check.
./scripts/releasekit MODULE deliver [ARGS...]	Select module defaults and invoke upstream deliver.
./scripts/releasekit version [ARGS...]	Forward without module/profile inference.
./scripts/releasekit publication-attempts [ARGS...]	Forward without module/profile inference.
./scripts/releasekit reconcile [ARGS...]	Forward without module/profile inference.

ARGS are ordinary upstream arguments, including the version where required; forward them as separate quoted arguments, without shell evaluation. This wrapper covers the selected maintainer workflow; it does not reimplement the ReleaseKit parser. Let upstream validate versions, flags, records, and candidate state. Reject a missing selector/operation or unsupported wrapper form with usage on stderr and status 2 before running Go. Preserve meaningful argv boundaries; exact usage prose is not a compatibility target.

Implement the only selector mapping in scripts/releasekit:

Selector	Module directory	Profile	Product for profile-wiring tests
core	.	releasekit.json	CommandKit
ckconfig	integrations/ckconfig	integrations/ckconfig/releasekit.json	CommandKit ckconfig
ckprompt	integrations/ckprompt	integrations/ckprompt/releasekit.json	CommandKit ckprompt

Implementation details:

1. Resolve the repository root from the script location using quoted POSIX shell operations safe with spaces and inherited CDPATH; change there.
2. Set GOWORK=off and GOTOOLCHAIN=local before querying Go. Resolve native GOHOSTOS and GOHOSTARCH through the selected go, then export them as GOOS and GOARCH for tool execution. Do not inherit a cross-build target.
3. Read the effective flags with go env GOFLAGS. Append -mod=readonly to that string and export it as GOFLAGS, preserving the other effective flags. Appending gives read-only selection precedence over an inherited -mod setting. Do not parse or evaluate the string in the shell. Go 1.26.8 does not accept go tool -mod=readonly; do not use that unsupported form.
4. For module operations, prepend OPERATION --repo ROOT --config ABS_PROFILE. For publish only, also prepend --expected-module MODULE_DIR. Neither ordinary check nor deliver accepts that publication flag. Append the supplied upstream arguments unchanged; upstream owns its flag semantics.
5. For the three raw forms, forward the command and supplied arguments without adding profile, module, or publication flags. The working directory is the repository root. Relative record paths therefore resolve there; document absolute record paths in examples for clarity, without prohibiting relative ones. Recovery identity comes from the selected saved record.
6. Finish through exec go tool go.maximumdirect.net/releasekit/cmd/releasekit. Preserve the child's output streams and exit status. Do not create or build an executable in .releasekit/bin/, preflight Gitea, or chain delivery after publication.

Reduce scripts/release to checking its existing two-argument shape, then executing the sibling helper with MODULE publish VERSION. Delegate selector validation to that helper, avoiding a second mapping. Keep ./scripts/release MODULE VERSION usable from outside the repository.

Stage result: all selected operations share root-tool execution and one module mapping; publication and delivery remain explicitly separate commands.

Stage 3: Replace release-test scaffolding with focused wiring tests

Rewrite scripts/release_test.go around the actual scripts and a small fake Go executable at the subprocess boundary. Remove scripts/release_integration_test.go and helpers with no remaining users.

Use temporary directories, including a repository path with spaces and an outside invocation directory. Copy the scripts and actual profiles into the fixture. The fake Go needs only to answer the queried go env values and to record the tool invocation, selected environment values, and controlled output and status. Simple argument recording suffices: remove goCall, its bespoke record parser, native-build assertions, and tests of assertion helpers. Do not retain a fake build stage, fake publisher executable, Git repository fixture, tag inspector, suite marker, or release-note generator.

Cover these behaviors with compact cases:

• Check the selector table against the copied profiles' module/product and the selected destination, forbidden token path, shared files, and validation selections. This checks CommandKit's choices, not upstream parsing semantics.
• Exercise each selector with publish, check, and deliver. Verify absolute repository/profile arguments, publication-only --expected-module, and unchanged forwarding of supplied upstream arguments.
• Exercise the legacy publication entry point and raw recovery/version forms. Verify recovery receives the explicit record/options without inferred module identity or a profile argument.
• Use foreign target values, workspace/toolchain overrides, and effective GOFLAGS containing an unrelated flag and -mod=mod. The recorded tool environment must select the host, disable workspace discovery, use the local toolchain, preserve the unrelated flag, and give read-only mode precedence. Assert effective settings rather than an incidental count/order of queries.
• Exercise statuses 0, 1, 2, and 3 on a representative operation, stdout/stderr forwarding, and a nonzero legacy-publication result. Do not multiply all module/operation combinations by all exit statuses.
• Exercise malformed wrapper invocations and confirm no Go command ran. Leave invalid semantic-version and upstream-flag classification to ReleaseKit.

Use no credential file, authenticated request, or external service. Keep existing domain package and maintained-consumer tests unchanged. Run the focused scripts suite during development as needed; Stage 5 owns final complete validation.

Stage result: local tests protect CommandKit routing and invocation behavior; upstream tests own publication, credential handling, and hosted reconciliation.

Stage 4: Align current documentation with the implemented workflow

Update docs/release.md, the CommandKit-specific scope in docs/policy/release.md, and release-tooling guidance in docs/development.md. Keep adopted general policy text and provenance intact. Change current owners with the implementation; the feature roadmap supplies the design rationale.

Document these concrete invocation examples, using placeholders rather than selecting a new release version:

• Publish: ./scripts/release core vX.Y.Z, with corresponding integration selectors. Keep the existing core-then-ckconfig-then-ckprompt order.
• Diagnose: ./scripts/releasekit core check vX.Y.Z; optional, never a required step before publication repeats validation.
• Deliver: ./scripts/releasekit core deliver vX.Y.Z, or either integration selector with its own semantic version. The profile derives the full tag.
• Discover/reconcile: ./scripts/releasekit publication-attempts and ./scripts/releasekit reconcile --record /absolute/path/to/attempt.json.
• Inspect the tool: ./scripts/releasekit version.

Include the clean tagged-checkout prerequisite for delivery, later retries from the original tagged source, the page-only body and module-specific full tags, environment-token precedence over the repository-relative token file, and retention of the ignored credential directory. Explain that successful source publication completes the source release, while hosted delivery has a separate outcome and URL. Credentials and Gitea availability do not gate publication. Refer to upstream delivery and recovery contracts rather than duplicating an HTTP implementation or a second status model.

Remove native executable-storage commands and the retired COMMANDKIT_RELEASE_INTEGRATION exercise instructions. Explain that selected upstream file checks inspect committed inputs, cover modules independently, and do not replace domain review. Document future licensing footer URLs using https://forge.maximumdirect.net/base-layer/commandkit/src/tag/FULL_TAG/ plus the correct repository-relative module file path. Keep existing published notes and tags unchanged; add no speculative release note or historical backfill. No CI workflow, provider call, runtime API, or attribution update is required.

Search affected documentation for stale .releasekit/bin/ and retired test references. Keep the credential-path references. Where baseline documentation mentions a deleted source file, use its inline path and baseline revision instead of leaving a broken local hyperlink. Keep stage tracking in this plan, not in the feature roadmap.

Stage result: the maintainer runbook describes the actual wrapper commands, selected checks, separate outcomes, and recovery without obsolete scaffolding.

Stage 5: Verify the final source and record validation boundaries

Use Go 1.26.8 on PATH, GOTOOLCHAIN=local, and prepared dependency caches. Reuse checks for unchanged final content instead of repeating them for each stage. Preserve the existing ignored go.work (currently declaring Go 1.26.10); use an external temporary Go 1.26.8 workspace when testing current source.

Perform the following one-time migration checks; add no persistent validation script or new recurring publication gate:

1. Check shell syntax and executable modes for both scripts, parse the profiles, review documentation links/fragments, and run git diff --check. Verify only the intended files changed and the token remains ignored and untracked.
2. Exercise the real helper's version with foreign GOOS/GOARCH, an inherited workspace, and an unrelated effective Go flag. Confirm ReleaseKit v0.8.0 runs natively without changing module files. In a disposable module copy, remove required tool checksum metadata and use inherited -mod=mod; confirm the helper fails instead of repairing metadata. Do not alter the real sum files.
3. Review and stage only the intended sprint changes, including new files, for verification. Obtain the staged tree with git write-tree and archive that tree into a disposable directory; do not archive HEAD and accidentally test the old implementation. Initialize and commit that snapshot in a new local Git repository on main, with no copied tag refs or publication remote. This verifies intended content before committing it in CommandKit. Do not include ignored files, unrelated staged work, or real credentials. Existing notes can label these local-only diagnostics: core v0.3.0, integrations v0.1.0. No tag is created or reused in an authoritative repository.
4. Build the pinned ReleaseKit executable once into temporary storage, using the selected root module and read-only metadata. Run ordinary upstream check on the snapshot's core profile with workspace discovery off. This runs the root suite, including the new scripts tests, and all selected file checks. Temporary native storage here is diagnostic setup, not launcher code.
5. For the integrations, create an external temporary workspace containing all three snapshot modules. ReleaseKit v0.8.0 intentionally forces GOWORK=off for its child suites, so exporting a workspace or alternate module-file flag on the outer command cannot redirect those suites. For this diagnostic only, put a temporary go shim on the executable's PATH: forward all invocations to the absolute real Go binary, but for go test set GOWORK to that temporary workspace before executing the real command. Do not skip tests or alter their remaining arguments. Run upstream check for both integration profiles. Real package suites then exercise current source; upstream file checks still inspect unchanged committed inputs, including ordinary go.mod files. This procedure was verified during planning and needs no committed helper.
6. Record workspace-backed integration results separately from independent release-readiness evidence. The baseline standalone failures listed above must remain visible. If needed, compare workspace-off tests with baseline to distinguish new failures. Do not claim the shimmed diagnostic proves that published dependencies are aligned, and do not add the shim to ordinary check, publish, or the default test suite. Dependency/version alignment and preparation of real integration candidates remain separate release work.

Planning evidence: the four generic file checks passed for the baseline core; all five selected file checks passed for both baseline integration snapshots using their real workspace-backed suites. The corresponding workspace-off integration suites failed with the known missing-core-symbol errors. Repeat the relevant diagnostics for the final sprint content, not merely the baseline. Investigate new failures without turning the baseline limitation into a false green result or disabling an agreed validator.

Do not invoke publish, deliver, or ci-deliver against a real destination for verification. Configuration and forwarding are the local responsibility; ReleaseKit owns authenticated preflight, hosted writes, and content matching.

Stage result: the changed infrastructure, real current-source suites, and selected committed-file checks are verified, with independent integration release-readiness limits accurately reported.

Stage 6: Review, document completion, and commit

Review the complete diff against the feature roadmap. Confirm that all three profiles have the selected options and destination; one shared launcher owns module routing; the old publication exercise and unused helpers are gone; domain tests remain; documentation uses the new invocation and separate outcomes; and /.releasekit/ still protects the local token directory.

Record stages completed and final validation results in this document, including the dependency-version limitation. Do not retire these roadmap documents during this sprint: retain the target and completion evidence for review, then apply the normal roadmap lifecycle during later release preparation. No new release version or source/hosted publication is required to finish this implementation.

Follow the local commit policy, review staged changes, and commit the intended implementation units with short plain-English messages. Report the commit IDs, remaining work, and verification limits. Preserve unrelated changes and private files; do not force a clean worktree by deleting or including them. With only the planned sprint changes present, the resulting tracked worktree should be clean. Intermediate failures do not justify leaving the final selected scope partially implemented.

Stage result: a reviewable, committed implementation of the selected target with accurate validation evidence and no production publication.