diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 0b5828c..86db1ce 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,53 +1,70 @@ -# Validation model implementation plan +# ReleaseKit v0.2.0 implementation plan -Status: Foundation complete; individual v0.2.0 validation capabilities and -their settings remain future work. +Status: Agreed stages for the remaining v0.2.0 work. -This plan implements the enabling work in [model.md](model.md), guided by -[ADR 0003](../adr/0003-declarative-validation.md). It is written for a Luna -coding agent executing one stage per prompt, in numerical order. The -[v0.2.0 roadmap](v0.2.0.md) owns the scope and defaults of the individual -capabilities. Their checker implementations, module-selected CI tooling, and -the publication endpoint expectation are subsequent feature work. +This plan replaces the completed foundation sequence. It implements the target +state in [v0.2.0.md](v0.2.0.md), using the shared design in [model.md](model.md), +[ADR 0003](../adr/0003-declarative-validation.md), and +[ADR 0004](../adr/0004-module-selected-tooling.md). A Luna coding agent should +execute one numbered stage per prompt, in order. -The foundation provides shared execution, diagnostics, committed-file access, -and a concrete design for equivalent Go and profile declarations. Completion -of this plan establishes that foundation; completion of the individual -validation features makes their selections operational. +## Current baseline and completion scope -## Instructions for each stage +At `3974a46`, the foundation and all six [remediation findings](remediation.md) +are complete. `Check` and `Publish` share candidate-request conversion and validation. +`internal/validation` runs the default offline suite and owns diagnostics and +candidate-tree access. Committed-file readers are offline; destination resolution +handles symlinks, parent traversal, cancellation, and absolute in-checkout paths. +The root error types and CLI presentation preserve findings and cause context. +`buildinfo` retains its independent runtime dependency graph. -- Start with [development.md](../development.md), the - [agent policy](../policy/agents.md), and the policies applicable to the stage. - Inspect the worktree and reuse relevant validation already available. -- Use the codebase graph to locate current symbols. The paths below identify - the inspected baseline and may change during implementation. -- Implement the stage's focused outcome with its behavioral coverage and - applicable documentation. Commit completed units according to the agent - policy and report the resulting commit and remaining work. -- Continue through the sequence using local fixtures and automated checks. - Consumer migrations, hosted actions, intermediate releases, and human review - are outside these stages. Architecture review and next-step decisions follow - the completed implementation. -- Keep internal collaboration proportionate: ordinary structs, functions, and - explicit conversions. Preserve the root and `buildinfo` facade boundaries. - Current API contracts and selected user decisions determine compatibility. +The public validation specification and its JSON settings remain unimplemented. +The consumer CI template still selects an independent tool version. This sequence +completes every remaining release-roadmap capability and Audita's CI migration. +It ends with local verification and committed changes. Architecture review, +hosted deployment, release tagging, and decisions about further testing follow +this implementation. -## Design to carry through the stages +| Release-roadmap item | Implementation stages | +| --- | --- | +| 1. Shared validation API/profile model | 1–3, 5–11, 15 | +| 2. Module-selected CI tool and Audita migration | 12–14 | +| 3. One suite with race selection | 1 | +| 4. Separate full vet | 2 | +| 5. Package compilation | 3 | +| 6. Expected publication endpoint | 4 | +| 7. Go formatting | 5 | +| 8. Markdown links and optional boundary | 9–11 | +| 9. Independent distribution rules | 6–7 | +| 10. Individual file size | 8 | -### API rollout +## Instructions for every stage -Complete the shared refactor, diagnostics, candidate readers, and conversion -boundaries in this plan first. Introduce each public validation setting with -its functioning capability. The first capability introduces `ValidationSpec` -and the request/profile field; subsequent capabilities add their supported -selections. Go and profile behavior remain equivalent, and each feature owns -its behavioral coverage. The model's full target is reached as the capability -implementations land. +- Start with [development.md](../development.md) and applicable policies. Locate + current symbols with the codebase graph and inspect the worktree. The named + paths below describe the current baseline. +- Introduce each public and profile setting with its working capability, as + agreed. Update its GoDoc, configuration reference, consumer guidance, and + relevant CLI/internal documentation in that same stage. +- Use ordinary internal structs/functions and explicit facade conversions. + Keep product assertions in `AdditionalChecks` and profile `checks`. +- Select tests for the stage's actual risks under the + [testing policy](../policy/testing.md). Use local Git repositories, Go + packages, controlled command doubles, and HTTP fixtures. Default tests remain + offline and independent of real credentials or sibling checkouts. +- Prepare newly selected development dependencies before offline validation. + Apply the [OSS policy](../policy/oss.md) when adding dependencies or adapting + third-party material, including any required attribution and license texts. +- Verify the focused outcome, stage its relevant changes, review the diff, and + create a nonempty commit with a short plain English message. Preserve unrelated + work and continue to the next stage. These stages require local work and + automated checks; consumer changes in Stage 14 are committed in that repository. -### Validation declarations +## Design carried through the stages -The intended complete facade shape is: +### Public and profile declarations + +The completed specification is facade-owned: ```go type ValidationSpec struct { @@ -79,493 +96,422 @@ type FileSizeValidationSpec struct { } ``` -`ReleaseRequest.Validation` holds a `ValidationSpec` value. `Target` is the -existing facade-owned operating-system/architecture pair. The corresponding -profile keys are `validation.go.race`, `validation.go.full_vet`, -`validation.go.compile_targets`, `validation.go_format`, -`validation.markdown.enforce_checkout_boundary`, -`validation.module_distribution.workspace_files`, -`validation.module_distribution.local_replacements`, -`validation.file_size.limit_bytes`, and `validation.file_size.exclusions`. -Profile compilation targets use the existing `GOOS/GOARCH` string convention. +Add `Validation ValidationSpec` and `ExpectedPushURL string` to `ReleaseRequest`. +`Target` is the existing root-facade operating-system/architecture pair. Each +stage adds only the fields it makes operational. The CLI owns corresponding +JSON structs and converts them in `cmd/releasekit`; internal production packages +use their own contracts. -Value groups preserve zero-value defaults. A non-nil Markdown or file-size -group enables its check; an empty JSON object has the same meaning. Each -distribution boolean independently selects inspection for the corresponding -distribution rule. Omitted optional groups select current default validation. -A nil byte limit selects 1,000,000 bytes when file-size checking is enabled; -an explicit zero selects zero bytes. Negative byte limits are invalid because -byte counts are nonnegative. Exclusions identify literal repository-relative -file or directory paths; a directory exclusion includes its committed -descendants. Preserve Git path spelling and use slash-separated paths. +| Go selection | Profile selection | Omitted/zero behavior | +| --- | --- | --- | +| `Go.Race` | `validation.go.race` | Ordinary native test suite | +| `Go.FullVet` | `validation.go.full_vet` | Existing test-time vet | +| `Go.CompileTargets` | `validation.go.compile_targets` | No package-compilation pass | +| `GoFormat` | `validation.go_format` | No formatting check | +| `Markdown` | `validation.markdown` | Nil/omitted/null disables the check; `{}` enables it | +| `Markdown.EnforceCheckoutBoundary` | `validation.markdown.enforce_checkout_boundary` | Outside-checkout links reported as out of scope | +| `ModuleDistribution.WorkspaceFiles` | `validation.module_distribution.workspace_files` | Rule disabled | +| `ModuleDistribution.LocalReplacements` | `validation.module_distribution.local_replacements` | Rule disabled | +| `FileSize` | `validation.file_size` | Nil/omitted/null disables the check; `{}` enables it | +| `FileSize.LimitBytes` | `validation.file_size.limit_bytes` | Nil/omitted/null selects 1,000,000 bytes when enabled | +| `FileSize.Exclusions` | `validation.file_size.exclusions` | No exclusions | +| `ExpectedPushURL` | `expected_push_url` | Empty/omitted disables the publication expectation | -These declarations describe the complete intended model. Public settings -acquire operational behavior with their capability implementations under the -incremental rollout above. Current documentation describes the implemented -boundary precisely. +Profile compilation targets use `GOOS/GOARCH` strings. Require a complete pair +because a partial target would otherwise silently select different compilation. +Use the existing Go target/environment mechanisms; let the selected Go toolchain +report unsupported targets. An artifact naming constraint does not determine +package-compilation compatibility. + +Byte limits are integer counts; zero is an explicit zero-byte limit, and negative +counts are invalid. Exclusions are literal repository-relative file or directory +paths; directory selections include committed descendants. Match path boundaries +so excluding `assets` leaves `assets-other` selected. Ordinary relative path +normalization is sufficient. An unmatched exclusion has no effect. Metacharacters +remain literal Git path characters. ### Execution and ownership -- `internal/candidate` retains capture and rechecks. Its existing `Validate` - entry point delegates shared validation to `internal/validation` and then - invokes `AdditionalChecks` once with the captured candidate. -- `internal/validation` owns internal settings, the shared executor, command - coordination, and diagnostic records. It receives the captured repository - directory and commit explicitly. It depends on internal Go and Git helpers; - internal production packages retain internal contracts. -- Root facade helpers perform request and diagnostic conversions. `Check` and - `Publish` share those helpers. The CLI maps its own JSON settings to the root - facade in `cmd/releasekit`, preserving its helper-package dependency boundary. -- Shared validation runs one base Go suite, selected full vet, selected package - compilation, and selected file checks, followed by product-specific checks. - Artifact builds retain their existing after-validation position. The - foundation executes the currently implemented portion of this procedure. -- Native commands retain the current offline environment. Future race - selection changes that one suite; full vet adds `-vet=off` to testing and a - separate vet invocation. Package compilation uses static target mode with - `CGO_ENABLED=0`, independently of artifact declarations. -- Preserve fail-stop behavior, context propagation, candidate rechecks, local - `Check` behavior, and publication phase/state meanings. Cross-check ordering - is internal procedure except for the relationships selected in the roadmap. - -### Diagnostic model - -Add facade-owned `ValidationCheck` (a string type), `ValidationFinding`, and -`ValidationError`. The error carries `Check`, `Findings`, and `Cause`, implements -`Error() string` and `Unwrap() error`, and is returned as a pointer. Findings -carry `Path`, `Line`, `Column`, and `Message`, with `Target` and `Directive` for -applicable file checks. A nullable `FileSizeMeasurement` containing -`Bytes` and `LimitBytes` supplies structured size details. Each named type -belongs to the root facade, with corresponding internal records and conversions. - -Use check identities `go-test`, `go-vet`, `package-compile`, `go-format`, -`markdown-links`, `workspace-files`, `local-replacements`, and `file-size` as -their checks land. Findings use repository-relative paths and one-based source -locations where available; zero locations mean unavailable. Human-readable -messages supply detail without a promise of exact wording. - -The shared error represents a failed validation check and preserves its -underlying cause. Candidate guards, artifact failures, and publication outcomes -retain their existing classification. Existing additional-check errors retain -their cause and current wrapping; custom callbacks can return facade errors -without losing their identity. Successful out-of-scope Markdown observations -will use the existing output writer when that feature lands, leaving successful -validation successful. - -### Committed-file access - -Provide an internal candidate-tree reader using the captured commit. Enumerate -the full tree with NUL-delimited Git output and record path, object ID, entry -kind/mode, and blob size where available. Read blob bytes by object ID, preserving -binary bytes and filenames containing spaces, tabs, or newlines. Cache reusable -metadata within the validation operation; read contents when needed. - -Regular tracked files include executable files, vendor contents, and nested -modules. The inventory applies no feature-specific exclusion. Symlinks expose -their committed link text as blob contents. Gitlinks expose the recorded -submodule commit and carry no parent-tree file size; the reader enumerates the -parent candidate's committed tree. Traversing a submodule checkout would inspect -different source and require a separately defined capability. - -Formatting and Markdown source parsing operate on regular source blobs. File -size can measure regular and symlink blobs. Supply an internal path-resolution -helper for future Markdown destinations that resolves symlink text within the -candidate tree, classifies destinations outside the checkout, and reports -missing entries or cycles. A submodule's contents are outside the parent -candidate's inspected tree. The Markdown feature owns whether a resulting -observation is a finding or an out-of-scope report under its selected rule. -The helpers read neither symlink targets nor submodule contents from the live -filesystem. Their tests use synthetic trees and local Git repositories. - -## Stage 1: Extract the shared validation executor - -**Completion:** Complete. The default Go suite now runs through -`internal/validation`, candidate capture and callbacks remain in -`internal/candidate`, and `Check` and `Publish` share the public callback -adapter. - -**Outcome:** One internal owner runs current default validation, with current -candidate and publication behavior preserved. - -1. Inspect `internal/candidate/check.go`, `internal/publish/publish.go`, - `internal/gotool`, and their existing tests. Record the capture, validation, - additional-check, build, and recheck boundaries in implementation notes. -2. Move default Go validation into `internal/validation`. Accept context, - captured repository/commit, output, and internal settings explicitly. Start - with ordinary zero-value settings and the existing default invocation. -3. Keep `candidate.Validate` as the shared bridge used by local checks and - publication. Retain additional checks and after-validation builds in their - existing responsibilities. Reuse `gotool.New` and its environment handling. -4. Consolidate root callback/request conversion where `check.go` and - `publish.go` currently duplicate it, using small private helpers. - -**Verification:** Run affected candidate, publication, and facade tests. Add -coverage only for gaps in default suite execution, callback ordering, failure -stopping before builds/tag creation, and cancellation. Existing publication -recovery tests retain ownership of remote-state behavior. Update the internal -inventory to reflect the implemented executor. - -## Stage 2: Introduce internal validation diagnostics - -**Completion:** Complete. Shared Go setup and test failures carry the internal -`go-test` identity and preserve their underlying errors, including cancellation -and subprocess exit errors. - -**Outcome:** The executor returns a small structured failure with an underlying -cause, independently of public error conversion. - -1. Add internal check identity, finding, measurement, and failure records to - `internal/validation`, corresponding to the diagnostic design above. -2. Attribute Go setup/test failures to the base test check. Preserve process - errors and canceled contexts through `Unwrap` and ordinary wrapping. -3. Keep candidate commit context in the candidate wrapper. Keep additional - callback errors and artifact failures in their current flow. -4. Define one internal formatting routine for the failure's useful summary; - avoid duplicating diagnostic prose at each call site. - -**Verification:** Protect `errors.Is` for cancellation and sentinel causes, -`errors.As` for subprocess errors, and distinguish shared failures from callback -and artifact failures. Test semantic fields and cause preservation rather than -complete error text. - -## Stage 3: Add committed candidate-file enumeration - -**Completion:** Complete. `internal/git` enumerates committed tree entries and -blob sizes, while `internal/validation` exposes a lazy candidate-tree reader -that serves blob bytes by object ID. - -**Outcome:** File-oriented validators can share an offline reader bound to the -captured commit. - -1. Add Git tree/blob operations to the existing internal Git boundary and a - small candidate-tree reader used by `internal/validation`. Select a separate - internal package only if it clarifies that responsibility. -2. Implement enumeration and lazy blob reads according to the committed-file - design. Bind queries to the captured commit and preserve Git/process causes. -3. Represent regular files, symlinks, and submodules explicitly. Keep feature - filtering in the respective future checker. -4. Make the reader available to the executor for selected file checks. Default - Go-only validation does not need to load all repository blobs. - -**Verification:** Use real temporary Git repositories to show that bytes and -sizes come from the selected commit despite changed worktree files, that unusual -filenames survive enumeration, and that vendor/nested-module files are present. -Include symlink and gitlink entries without requiring a network or neighboring -checkout. Confirm inspection leaves repository contents unchanged. - -## Stage 4: Add candidate destination-resolution primitives - -**Completion:** Complete. The candidate tree resolves committed relative paths -and symlinks, preserving directory identities and classifying missing, -outside-checkout, submodule, and cycle observations without reading the live -filesystem. - -**Outcome:** Future Markdown validation can resolve committed local destinations -and classify checkout boundaries without filesystem traversal. - -1. Implement a small internal resolver for repository-relative destinations - against the candidate inventory. Keep URL decoding and Markdown parsing in - the later Markdown capability. -2. Resolve committed symlink text relative to its containing path. Distinguish - existing entries, missing entries, outside-checkout paths, submodule contents, - and symlink cycles. Classification is data for the caller. -3. Preserve ordinary directory destinations where the committed tree contains - descendants. Return the resolved identity needed for future fragment lookup. -4. Keep inspection errors separate from normal resolution observations. - -**Verification:** Cover relative paths, parent traversal within and outside the -root, existing directories, symlinks pointing inside/outside the root, cycles, -and submodule traversal. Show identical classifications with neighboring files -present and absent. These tests own path resolution; later Markdown tests own -syntax, anchors, and selected failure policy. - -## Stage 5: Add facade declarations and shared request conversion - -**Completion:** Complete. The root facade exposes its own validation -diagnostic types, and both `Check` and `Publish` convert shared failures while -preserving candidate context and the original error chain. - -**Outcome:** The public model has an agreed representation, shared conversion, -and cause-preserving errors across `Check` and `Publish`. - -1. Implement the public diagnostic types now and retain - the complete specification above as the blueprint for capability stages. - Introduce `ReleaseRequest.Validation`, `ValidationSpec`, and supported - settings with the first capability implementation in subsequent feature work. -2. Define internal counterparts for the intended settings where required by - actual coordination code. Use explicit field/target conversions through - the same root helper for both operations. Add remaining fields as used. -3. Convert internal failures into facade-owned `*ValidationError`, using typed - recognition and explicit diagnostic-field conversion. Retain the original - wrapped error as the cause so candidate context, underlying identity, and - `errors.Is`/`errors.As` behavior survive the conversion. Render the useful - failure once rather than repeating the same context at each wrapper. -4. Keep source publication result conversion unchanged. Extend GoDoc for the - errors and any implemented settings, with links to current consumer guidance. -5. Extend compiled public API checks for facade-owned named types and dependency - direction. Preserve the small independent `buildinfo` dependency graph. - -**Verification:** External-package tests cover typed error access and -`errors.Is`/`errors.As` through both facades. Reuse existing integration fixtures -for a failing suite and an additional-check cause; avoid a new generic test -framework. Run `go run ./internal/apicheck`. - -## Stage 6: Establish equivalent profile mapping and CLI presentation - -**Completion:** Complete. Check and publication share profile conversion, and -the CLI presents typed validation errors through one diagnostic path while -preserving existing status, publication-state, and phase reporting. - -**Outcome:** Profile conversion has one owner and the CLI reports structured -validation failures consistently while retaining current exit classification. - -1. Inspect `cmd/releasekit/internal/cli/config.go` and - `cmd/releasekit/main.go`. Share profile-to-request conversion for check and - publication through a small command-layer helper. Preserve additional-command - argument/environment handling and build/delivery mapping. -2. Under the incremental rollout, add each `validation` setting with its - capability. Use CLI-owned JSON structs and explicit conversion at the command - boundary. Reuse ordinary JSON decoding and existing unknown-field rejection. - The schema blueprint above guides later additions; profile settings acquire - behavior at the same time as their Go counterparts. -3. Add shared CLI presentation for facade validation errors. Show check identity, - useful findings and cause context once. Retain publication phase/state and - uncertain-outcome reporting. Present validation failures through the existing - status 1 path and malformed profile settings through the existing status 2 - path; preserve other statuses. -4. Update current CLI documentation for the diagnostic behavior that has landed. - Update configuration documentation only for implemented settings. - -**Verification:** Exercise default/omitted settings and existing additional -commands. Check useful diagnostics and exit classifications for both operations, -including a publication validation failure before tag creation. Capability work -will add setting-specific mapping/equivalence cases at this established boundary. - -## Stage 7: Record capability integration recipes and consumer shapes - -**Completion:** Complete. Internal guidance now records setting and checker -ownership, Go command coordination, and candidate-file integration. The -prospective examples below compare the agreed declarations with the read-only -consumer review. - -**Outcome:** Subsequent feature prompts can use the foundation without redesigning -its ownership or inventing a public extension framework. - -1. Add focused internal guidance for adding a typed setting, facade/profile - conversion, ordinary checker function, identity/findings, and behavioral - coverage through the shared executor. Update the inventory and link to that - owner for mechanics. -2. Record the Go coordination recipe: construct one test command with selected - flags; select native full vet when requested; use static package compilation - for declared targets after test/vet. Reuse target/environment handling while - keeping artifact metadata and version smoke tests in the builder. -3. Record how file checks consume the candidate reader and return findings. - Keep individual rule semantics in the release roadmap until implemented. - Markdown adopts PromptKit's current conventions as its starting specification; - parser/anchor implementation belongs to the Markdown feature prompt. -4. Add prospective Go/profile examples under this roadmap for the three consumer - shapes: Audita with omitted optional validation and existing artifact builds; - ConfigKit with race, full vet, and two Linux compilation targets; PromptKit - with shared selections plus substantive example assertions in `checks`. - Label prospective fields clearly. Maintained copyable consumer examples gain - selections when those selections are implemented. -5. Compare those declarations with local consumer scripts and profiles read-only. - Record which duplicated mechanics each later capability removes. ConfigKit's - separate toolchain-support commitments remain consumer compatibility decisions. - -**Verification:** Check the proposed declaration pairs against the schema design -and the ownership table in `model.md`. Confirm product checks still fit the -existing callback/profile extension point. Runtime tests are self-contained and -independent of the three sibling checkouts. - -### Prospective consumer shapes - -These examples show the agreed model before its optional settings are -implemented. The `Validation` field and the profile `validation` object are -prospective until their corresponding checkers land. - -#### Audita: retain the existing artifact build - -The zero-value validation selection preserves current defaults while the -existing Linux application artifacts remain declared separately: - -```go -request := releasekit.ReleaseRequest{ - Product: "Audita", - Version: version, - Validation: releasekit.ValidationSpec{}, // prospective; zero value keeps current validation - Build: &releasekit.BuildSpec{ - MainPackage: "./cmd/audita", - BinaryName: "audita", - Targets: []releasekit.Target{ - {OS: "linux", Arch: "amd64"}, - {OS: "linux", Arch: "arm64"}, - }, - }, -} -``` - -Its profile keeps the existing build declaration and omits `validation`: - -```json -{ - "product": "Audita", - "remote": "origin", - "build": { - "main_package": "./cmd/audita", - "binary_name": "audita", - "targets": ["linux/amd64", "linux/arm64"] - }, - "delivery": { - "base_url": "https://gitea.maximumdirect.net", - "owner": "eric", - "repository": "audita", - "token_env": "RELEASEKIT_GITEA_TOKEN" - } -} -``` - -#### ConfigKit: select release compatibility checks - -The declaration expresses its race test, separate full vet, and source-only -Linux compilation commitments without selecting executable artifacts: - -```go -request := releasekit.ReleaseRequest{ - Product: "ConfigKit", - Version: version, - Validation: releasekit.ValidationSpec{ - Go: releasekit.GoValidationSpec{ - Race: true, - FullVet: true, - CompileTargets: []releasekit.Target{ - {OS: "linux", Arch: "amd64"}, - {OS: "linux", Arch: "arm64"}, - }, - }, - }, -} -``` - -```json -{ - "product": "ConfigKit", - "validation": { - "go": { - "race": true, - "full_vet": true, - "compile_targets": ["linux/amd64", "linux/arm64"] - } - } -} -``` - -The consumer's baseline-toolchain requirement remains its compatibility -decision. The selection above describes checks, not a promise to run them with -every Go toolchain. - -#### PromptKit: share mechanics and keep example assertions - -Shared settings cover the maintained race and vet passes, Go formatting, -checkout-bounded Markdown links, and the two distribution rules. Substantive -example assertions remain in the existing `AdditionalChecks` extension point -or profile `checks`: - -```go -request := releasekit.ReleaseRequest{ - Product: "Promptkit", - Version: version, - Validation: releasekit.ValidationSpec{ - Go: releasekit.GoValidationSpec{Race: true, FullVet: true}, - GoFormat: true, - Markdown: &releasekit.MarkdownValidationSpec{EnforceCheckoutBoundary: true}, - ModuleDistribution: releasekit.ModuleDistributionValidationSpec{ - WorkspaceFiles: true, - LocalReplacements: true, - }, - }, - AdditionalChecks: checkExamples, -} -``` - -```json -{ - "product": "Promptkit", - "validation": { - "go": {"race": true, "full_vet": true}, - "go_format": true, - "markdown": {"enforce_checkout_boundary": true}, - "module_distribution": { - "workspace_files": true, - "local_replacements": true - } - }, - "checks": [ - {"args": ["python3", "scripts/check-examples.py"]} - ] -} -``` - -The example-check command is illustrative of a product-owned check retained -from PromptKit's current release assertions; it is not a file in the reviewed -checkout. - -### Read-only consumer review - -Reviewed on 2026-10-07. All three local worktrees were clean. The declarations -were compared with Audita `bd62f36`, ConfigKit `dc09959`, and PromptKit -`7310ef3`; no sibling repository was modified. - -- Audita's `releasekit.json` already declares its product, remote, Linux binary - build, and Gitea destination. Its nine-line `scripts/release.sh` builds the - module-selected ReleaseKit executable and delegates to it. It has no - additional candidate-validation block to remove; omitting optional - selections preserves its current validation. Module-selected CI bootstrap - remains separate later work. -- ConfigKit's 29-line `scripts/release-check.sh` selects one race test run with - test-time vet disabled, runs full vet, and compiles all packages for Linux - amd64 and arm64. Those invocation and target-loop mechanics correspond to - the shared Go settings. Its 133-line publication script also checks an - expected remote URL and advances `main` before publishing a tag. The - endpoint expectation is a separate publication capability; the main-branch - publication flow remains product-specific. Its `CONFIGKIT_BASELINE_TOOLCHAIN` - requirement covers cached supported Go 1.25 patch releases and remains a - consumer commitment. -- PromptKit's 152-line `scripts/release-check.sh` owns the race suite, separate - vet, tracked-Go formatting check, Markdown link and heading checks, - workspace-file and local-replacement checks, a vendor-directory rejection, - and substantive example output assertions. The shared validation settings - correspond to race, vet, formatting, Markdown, workspace-file, and - replacement mechanics; vendor and example assertions remain product checks. - Its 57-line `scripts/release.sh` also checks release-note sections and - publishes an annotated tag, which remain in the product's release procedure. - -The file-size capability has no corresponding local check in these reviewed -scripts. Consumer migrations and measurements of realized code removal remain -outside this implementation plan. - -## Stage 8: Verify and document the completed foundation - -**Completion:** Complete. `Check` and `Publish` now use one shared conversion -from the facade request into candidate validation. The full Go suite and public -API/dependency check pass, and the roadmap distinguishes the completed -foundation from the optional capabilities still to come. - -**Outcome:** The enabling refactor is complete, its current boundary is clear, -and later feature implementation can proceed through the shared model. - -1. Review the assembled request flow, cause conversions, candidate inspection, - CLI presentation, and facade imports against ADR 0003 and the architecture - policy. Address concrete defects within the stages' scope. -2. Run `go test ./...` and `go run ./internal/apicheck` from the repository root. - Add focused integration coverage only for a remaining risk, such as default - behavior diverging between API/profile or check/publication paths. -3. Update current GoDoc, consumer guidance, CLI reference, and internal owners - for implemented behavior. Keep future setting examples and pending capability - contracts in roadmaps. Check local links and Markdown whitespace. -4. Update `model.md` and this plan's status to identify the completed foundation - and the individual capability work remaining in `v0.2.0.md`. A foundation - completion is distinct from a completed v0.2.0 release. -5. Commit the completed unit and report its verification, remaining capability - work, and clean or preserved worktree state. The subsequent architecture - review and testing/next-step decisions belong to the user after this sequence. +The shared procedure is one native test suite, selected full vet, selected +package-compilation targets, and selected file checks, followed by product +checks and existing artifact builds/rechecks. File-check ordering is an internal +procedure: formatting, workspace files, local replacements, file size, then +Markdown. Stop after a failed check. A checker may return multiple findings; +this plan does not require collecting failures from every selected check. + +Resolve the Go environment once per validation operation and reuse it. Native +race/vet work preserves the existing effective cgo/C-tool configuration. Static +package compilation uses `CGO_ENABLED=0`. The existing offline module/toolchain +controls remain owned by `internal/gotool`. + +Pass settings through the root `candidateRequest`, `internal/candidate.Request`, +`internal/publish.Request`, and `validation.Request`. Both operations and their +CLI forms use the same decisions. Keep expected URL comparison in publication +preflight. Existing capture/rechecks, endpoint guards, recovery, publication +completion, and delivery outcomes retain their meaning. + +Reuse the existing internal failures and facade conversion. Add stable identities +`go-vet`, `package-compile`, `go-format`, `workspace-files`, `local-replacements`, +`file-size`, and `markdown-links` as implemented. Supply paths, locations, +targets, directives, and measurements as applicable. Preserve causes and +cancellation through `errors.Is`/`errors.As`. CLI failures use existing exit +classifications and complete contextual presentation. + +File checks share one candidate inventory per validation operation and load blobs +as needed. Inventory includes tracked vendor files and nested modules. Regular +source blobs feed formatting and Markdown parsing. Workspace-file detection +includes named symlink blobs; module parsing follows committed symlinks to +candidate-contained regular declarations. Unavailable selected input produces +an inspection error. File size measures regular and symlink blobs. Gitlinks have +no parent-tree blob size, and their contents remain outside the inspected tree. + +### Dependencies and Markdown convention + +Use standard `go/format` for Go formatting. Its convention follows the Go +standard library used to build ReleaseKit. Use `golang.org/x/mod/modfile` at +`golang.org/x/mod v0.40.0` for complete module-declaration parsing. Use +`github.com/yuin/goldmark/v2 v2.1.6` internally for Markdown AST parsing and source +positions. Both selected module manifests support the existing Go 1.25 baseline; +implementation should record their exact source revisions and notices under the +OSS policy. References: [modfile](https://pkg.go.dev/golang.org/x/mod/modfile) +and [Goldmark](https://github.com/yuin/goldmark/tree/v2.1.6). + +PromptKit's current script supplies the starting heading/link examples. Preserve +its basic anchor transformation: lowercase heading text, retain Unicode letters +and numbers, underscore, hyphen, and spaces, then replace spaces with hyphens. +Use visible heading text from the Markdown AST, including inline code text and +excluding HTML tags/formatting delimiters. Support ATX and Setext headings. For +repeated headings, append increasing numeric suffixes starting at `-1`, selecting +an unused identifier when a generated suffix collides with another heading. +Document these refinements to the starting script's behavior. + +Recognize inline links, images, and full/collapsed/shortcut reference links through +the parser. Code blocks and inline code supply examples rather than link nodes. +Raw HTML destinations remain outside this Markdown-link capability. Undefined +references rendered as ordinary text by the parser are not a new Markdown lint +rule. Decode Markdown escapes/entities through the parser and percent escapes +once when resolving URI path/fragment components. Ignore URI query components +for file existence. Empty paths target the source document; an empty fragment +selects its top. Schemed and protocol-relative URIs receive no availability +request. Fragment checking applies to regular Markdown destinations; other +existing files/directories receive existence checking. + +Use committed destination resolution and cached parsed documents/anchors. +Missing destinations, unresolved cycles, and missing supported anchors fail the +selected Markdown check. Actual outside-checkout destinations are reported as +out of scope by default and fail with boundary enforcement. Submodule-content +observations remain reported as out of scope under either setting: the boundary +option concerns checkout escape and does not establish a submodule prohibition. +Write nonfailure observations to the supplied output writer; a nil writer +selects ordinary quiet library use. Diagnostics identify the source use site, +location, and destination. Document source columns as one-based byte columns. + +### CI tool bootstrap + +Build using temporary copies of the released application's `go.mod` and `go.sum`, +with Go's alternate `-modfile` and normal module preparation in those copies. +Confirm that ReleaseKit is already selected before building its command. This +preserves the application's version declaration and require/replace semantics +while allowing missing tool-only indirect requirements/checksums to be prepared +without dirtying immutable tagged source. It supports consumers whose application +imports only lightweight `buildinfo`. Stages 12–14 implement this agreed approach. + +## Stage 1: Introduce the specification with race selection + +**Outcome:** The first public/profile selection changes the one existing suite. + +1. Add `ReleaseRequest.Validation`, `ValidationSpec.Go`, and + `GoValidationSpec.Race`, plus equivalent CLI-owned JSON settings. Add explicit + conversions through both candidate and publication request paths. +2. Build the base invocation in `internal/validation`: preserve + `go test -mod=readonly -count=1 ./...`, adding `-race` when selected. Reuse + the native Go environment and report tool/prerequisite failures as `go-test`. +3. Preserve additional-check and build ordering. Update exact API/profile + references and add a minimal consumer example for the selection. + +**Verification:** Default and selected invocations, exactly one suite, API/profile +selection equivalence, both operations, unavailable race prerequisites with no +silent fallback, preserved causes/cancellation, and failure before product +checks/builds/tag creation. Use a small real race-enabled fixture on supported +hosts and a controlled Go command for portable prerequisite-failure coverage. + +## Stage 2: Coordinate a separate full vet pass + +**Outcome:** Full vet replaces test-time vet overlap through one declaration. + +1. Add `Go.FullVet` and `validation.go.full_vet` through the same conversion path. +2. When enabled, add `-vet=off` to the one test invocation and run native + `go vet -mod=readonly ./...` afterward using the same tool/environment. +3. Attribute vet failures to `go-vet` and update canonical usage guidance. + +**Verification:** Ordinary, race-only, vet-only, and combined selections; one +suite; vet after successful tests; suppression of test-time vet only when +selected; failure/cancellation stopping; default behavior and API/profile parity. +Protect the selected command relationship without freezing incidental flag order. + +## Stage 3: Compile packages for selected targets + +**Outcome:** Source compatibility checks work independently of artifacts. + +1. Add `Go.CompileTargets` and string-array profile targets. Convert to internal + Go targets and validate complete pairs consistently for API and profile use. +2. After test/vet, run `go build -mod=readonly -o ./...` in static + mode for each selected target. The Go build null-output mode suppresses + executable output, including a module with a single main package. +3. Report failures as `package-compile`, including the selected target. Keep + output names, linker version injection, smoke tests, receipts, and manifests + in artifact building. Document compilation versus target execution. + +**Verification:** Linux amd64/arm64, a supported additional Go pair, source-only +library, single-main and multiple-main modules (including repeated executable +basenames), target failure, unchanged candidate files, `CGO_ENABLED=0`, preserved +ordering, and page-only delivery with compilation selected but no build targets. +Reuse the existing Go environment tests for controls already protected there. + +## Stage 4: Compare the optional expected push URL + +**Outcome:** Publication rejects a different effective destination before validation. + +1. Add `ExpectedPushURL` and `expected_push_url`, with an empty value selecting + existing behavior. Carry it only into the publication request. +2. Immediately after resolving/capturing `endpoint.PushURL`, compare exact strings. + Report expected and resolved values through a publication preflight error. + Add `ErrUnexpectedPushURL` as a public sentinel using the existing shared-error + ownership pattern so callers can use `errors.Is`. +3. Keep later endpoint rechecks and reconciliation intact. Update GoDoc, + publication guidance, and the profile reference. + +**Verification:** Omitted/matching/mismatching values, Git `insteadOf` resolution, +separate fetch/push URLs, exact spelling differences, mismatch before Go/callbacks +or tag creation, and a local-only `Check` that ignores the publication expectation. +Existing endpoint-change and uncertain-push tests keep their ownership. + +## Stage 5: Check committed Go formatting + +**Outcome:** A declaration replaces tracked-file formatting loops. + +1. Add `GoFormat` and `validation.go_format` with working executor integration. +2. Load the shared captured inventory and apply `format.Source` to regular `.go` + blobs. Compare original and formatted bytes, preserving repository contents. +3. Return `go-format` findings for affected paths and preserve parser/inspection + causes. Update usage and formatting-convention documentation. + +**Verification:** Formatted and unformatted files, parse errors, vendor/nested +source, unusual filenames, committed versus worktree bytes, disabled/default +behavior, API/profile parity, and failure before later product/build work. + +## Stage 6: Select committed workspace-file inspection + +**Outcome:** One distribution rule works independently of the Go environment. + +1. Add `ModuleDistributionValidationSpec.WorkspaceFiles` and the matching JSON + group/field. The remaining rule is added in Stage 7. +2. Inspect committed blob entries named `go.work` or `go.work.sum`, including + nested and symlink entries. Report paths using `workspace-files`. +3. Keep testing's existing workspace setting and consumer vendor choices in their + current owners. Document the distinction between environment and distribution. + +**Verification:** Either workspace filename, nested paths, symlink names, +committed files with `GOWORK=off`, uncommitted files excluded from inspection, +selection disabled, and shared API/profile execution. Use meaningful rule cases +rather than retesting Git enumeration mechanics. + +## Stage 7: Select filesystem replacement inspection + +**Outcome:** The second distribution rule parses actual module declarations. + +1. Add `ModuleDistribution.LocalReplacements` and the equivalent profile field. + Prepare `golang.org/x/mod v0.40.0`, module sums, and required OSS notices. +2. Parse committed `go.mod` files with `modfile.Parse`, including nested/vendor + declarations. Resolve symlink declarations within the candidate; report an + inspection error when their selected contents cannot be obtained locally. +3. Identify filesystem replacements by the parsed replacement's absent version; + permit versioned replacements. Report path, directive/source location, and + target through `local-replacements`, preserving parse/inspection causes. +4. Document independent distribution selections and their inspection scope. + +**Verification:** Single and block directives, comments, quoted paths, relative +and absolute filesystem targets, versioned replacements, nested declarations, +valid/broken symlinks, parse failure, and all independent boolean combinations. +The rule applies to candidate contents even when testing disables workspace use. + +## Stage 8: Inspect individual committed file sizes + +**Outcome:** Optional limits and intentional path exceptions are operational. + +1. Add `FileSizeValidationSpec`, `ValidationSpec.FileSize`, and matching JSON + fields according to the declaration table. Validate nonnegative byte limits. +2. Use shared blob sizes for regular files and symlink link-text blobs. Apply + literal file/directory exclusions. On an oversized blob, return `file-size` + with its path and existing `FileSizeMeasurement` fields; reporting one offending + file per failure fits the current diagnostic model. +3. Document decimal bytes, strict greater-than comparison, exclusions, and + current-candidate scope. Preserve default disabled behavior. + +**Verification:** Below/at/above limits, the exact 1,000,000-byte enabled default, +zero/custom/negative limits, nil versus empty objects, directory/path boundaries, +literal metacharacters, unmatched exclusions, small binaries, symlink sizes, and +omitted submodule sizes. Historical and aggregate size do not become release gates. + +## Stage 9: Implement internal Markdown parsing and anchors + +**Outcome:** A parser with source positions and documented anchor semantics is ready. + +1. Add `github.com/yuin/goldmark/v2 v2.1.6`, prepared dependencies, and applicable + OSS notices. Keep parser types inside internal implementation. +2. Parse links/images, reference uses, headings, and source positions into small + internal records. Derive visible heading text and apply the convention above. +3. Cache parsed records/anchors per candidate document. Keep this stage internal; + Stage 11 adds the public selection once complete checking works. +4. Compare fixtures with PromptKit's starting examples. Record intended refinements + in the roadmap until the public behavior lands, avoiding a second regex parser. + +**Verification:** Inline/reference forms and images, escaped/parenthesized +and angle-bracket destinations, optional titles, code fences/inline code, +Unicode/entity headings, ATX/Setext headings, repeated headings and suffix +collisions, and source use-site locations including repeated reference uses. +Undefined references and HTML prose remain governed by parser interpretation. + +## Stage 10: Implement internal destination and fragment checking + +**Outcome:** Committed Markdown navigation is checked with boundary observations. + +1. Resolve parsed local URI components through `CandidateTree.ResolveDestination`. + Apply escaping/query/fragment rules above and use actual resolved identities + for target-document anchor lookup. +2. Check committed existence and supported heading fragments, recording source + path/location/target. Produce `markdown-links` failures and distinct nonfailure + observations for outside-checkout and submodule contents. +3. Implement optional checkout-boundary enforcement internally. Preserve the + distinction between external URIs, checkout escapes, and uninspected submodules. +4. Reuse remediated symlink/cancellation/local-object behavior. Keep parsing, + resolution, and rule evaluation in ordinary internal functions. + +**Verification:** Valid/missing files and anchors, same-document/empty fragments, +percent-escaped paths and fragments, query strings, directories and non-Markdown +files, absolute in-checkout paths, symlink-parent traversal and cycles, outside +links with both settings, submodule observations, neighboring files present/absent, +missing local Git objects, cancellation, and unchanged candidate/worktree bytes. + +## Stage 11: Expose Markdown selection and complete validation integration + +**Outcome:** All agreed validation selections work through both public operations. + +1. Add `MarkdownValidationSpec`, `ValidationSpec.Markdown`, and their JSON fields. + Enable on a non-nil group/empty object and map the boundary boolean explicitly. +2. Wire the checker and nonfailure observations into the shared executor/output + writer. Reuse existing facade/CLI diagnostic formatting and exit classification. +3. Update GoDoc, configuration, check/publish guides, CLI reference, internal + inventory, and maintained validation examples for all operational selections. +4. Use self-contained fixtures representing Audita defaults/artifacts, ConfigKit's + race/vet/compilation, and PromptKit's shared settings plus example assertions. + Document how consumers remove duplicate generic commands when adopting settings. + +**Verification:** Equivalent Go/profile declarations, nil/empty/null Markdown +settings, warnings with successful results, boundary failures before product/build +work, all-zero compatibility, representative combined selections, one suite and +one additional-check callback. Run the compiled API/dependency check, including +`buildinfo`'s standard-library/runtime-only dependency boundary. + +## Stage 12: Build the CI tool from verified released module configuration + +**Outcome:** The standard template has one tool-version declaration. + +1. Revise `examples/woodpecker/tag-delivery.yml` into a compact bootstrap/delivery + step. Use available Git to validate/fetch the explicit event tag, compare its + peeled commit to the full provider object ID using existing case-insensitive + object-ID semantics, check out that commit detached, and confirm HEAD and + the existing clean tagged-source requirement. This ensures module files + actually belong to the verified release before selecting the tool. + Do this before reading/resolving the application module or executing Go. +2. Apply the agreed CI tool bootstrap approach: create a disposable directory + outside the source checkout, copy its `go.mod` and existing `go.sum`, and use + an alternate `-modfile` for tool resolution/build. + Run from the verified source with `GOWORK=off` and `GOTOOLCHAIN=local`. +3. Confirm the ReleaseKit module is already selected by that module configuration + using `go list -m`; then build its `cmd/releasekit` package without an `@version` + suffix. Allow ordinary network-capable module preparation in the temporary + metadata copies (`-mod=mod`). Respect selected require/replace relationships. +4. Invoke the resulting native executable's existing `ci-deliver` with the event + repository, commit, and tag. Keep delivery credentials in the existing delivery + step and use an exit cleanup trap for temporary metadata and executable files. +5. Remove the independent `RELEASEKIT_VERSION` workflow setting. Preserve current + Go-image customization, destination/profile ownership, and delivery outcomes. + Keep the bootstrap Git block small; the built tool retains its runtime guards. + +**Verification:** Execute maintained template commands with a local tag/module +fixture and instrument Go/transport operations. Prove wrong tag/commit stops +before module resolution/build, a dirty module cannot select a different tool, +the verified checkout selects the tool, module metadata and source remain +unchanged, and the executable/temporary files are cleaned up. Tool metadata +preparation is separate from offline candidate checks. + +## Stage 13: Verify upgrades, retries, and bootstrap variants + +**Outcome:** Tool selection follows the triggering release across supported uses. + +1. Add local module-proxy fixtures for two tool versions and tagged consumer + module configurations. Execute the maintained workflow body against both. + Keep live infrastructure outside the default test suite. +2. Verify a retry of an older tag still selects that tag's module configuration + when the default branch has upgraded. Include missing tool-only checksums and + an existing versioned replacement to protect source-based resolution. +3. Align `releasekit-source-delivery.yml` with source verification before self + bootstrap and temporary output. Preserve self-bootstrap from `./cmd/releasekit` + and separately installed-tool guidance using the existing command. +4. Update delivery/configuration/CLI guidance and maintained templates together. + Explain compatible Go environments, dependency preparation, immutable-source + retries, and the distinct tool/app artifact preparation steps. + +**Verification:** Two dependency versions, older-source retries, self bootstrap, +separately installed tool, source-only page delivery, binary delivery using a +local HTTP fixture, and preserved tag/commit/destination/state behavior. An +application without a declared ReleaseKit dependency uses the installed-tool +integration. + +## Stage 14: Migrate Audita's local CI integration + +**Outcome:** Audita's local wrapper and CI select the same module-declared tool. + +1. Read `../audita` orientation/policies and inspect its worktree before editing. + Adapt `.woodpecker/release.yml` to the maintained module-based template, + preserving its Go image, Gitea secret name, and release profile. +2. Retain its existing released ReleaseKit module selection for this migration; + that version already supplies `ci-deliver`. Align `scripts/release.sh` with + the selected bootstrap metadata approach and preserve native executable exit + behavior. Keep generated tool output outside the candidate source where needed. +3. Verify the consumer's actual wrapper/workflow using local tagged fixtures and + prepared module caches. Confirm matching selection and unchanged profiles, + source validation, binary targets, hosted page behavior, and source files. +4. Commit the focused migration in Audita with a plain English message. Record + its commit and local verification in this plan's implementation status. + +**Verification:** The actual adapted consumer declarations use one dependency +version; local and CI bootstraps agree and retain existing caller arguments/status +semantics. Keep integration fixtures self-contained in ReleaseKit's default suite. +This migration uses an existing release and requires no intermediate publication +or live Woodpecker/Gitea run to complete the stage. + +## Stage 15: Audit the completed v0.2.0 implementation + +**Outcome:** The entire scoped feature set is implemented and locally verified. + +1. Match every row in the roadmap/stage table to implemented settings, execution, + diagnostics, current documentation, and focused behavioral evidence. Verify + all-zero compatibility, independent distribution choices, one coordinated Go + suite, source-only compilation/delivery, and selected endpoint preflight. +2. Review new code and tests for unintended defaults, restrictions, caps, or + stronger guarantees. Preserve user choice and the existing facade boundaries. +3. Run `go test ./...` and `go run ./internal/apicheck`. Add further integration + coverage only for a concrete remaining risk. Check documentation links, + fragments, whitespace, dependency notices, and maintained examples. +4. Update statuses in this plan, the release roadmap, and the model roadmap to + reflect actual completion, including the Audita migration evidence. Update + canonical current-behavior owners as needed and remove stale prospective text. +5. Commit the completed unit, report each stage's outcome and remaining work, + and finish with a clean workspace while preserving any unrelated user changes. + The subsequent architecture review and release/testing decisions follow here. + +## Open Questions + +None. diff --git a/docs/roadmap/v0.2.0.md b/docs/roadmap/v0.2.0.md index 4d66f70..284a0a8 100644 --- a/docs/roadmap/v0.2.0.md +++ b/docs/roadmap/v0.2.0.md @@ -1,10 +1,10 @@ # ReleaseKit v0.2.0 roadmap -Status: Draft scope for the next release. +Status: Agreed feature scope; implementation planning is recorded separately. This roadmap catalogs improvements to ReleaseKit v0.1.0. Each item records its -rationale, target state, and scope of work. A staged implementation plan will -follow once the release scope is finalized. +rationale, target state, and relevant scope decisions. The +[implementation plan](implementation.md) owns the staged work. The priorities in [ADR 0002](../adr/0002-routine-releases.md) guide this work: minimize application-owned release code, duplicated mechanics, and routine @@ -14,9 +14,11 @@ developer decisions through a standard, minimal API. ### Rationale and current baseline -ReleaseKit has a shared candidate workflow and a product-specific additional -check extension point. The optional validation capabilities planned for v0.2.0 -need a coherent selection and diagnostic model across the Go API and profile. +The shared validation foundation and its remediation are complete. ReleaseKit +has common candidate execution, facade-owned diagnostics, committed-file +inspection, and a product-specific additional-check extension point. The +optional v0.2.0 capabilities still need their functioning API/profile selections +and checker implementations. The [validation-model roadmap](model.md) records this enabling work and its rationale. A common model lets consumers declare choices once and receive @@ -30,17 +32,8 @@ ReleaseKit owns coordination and diagnostics through the existing `Check` and `Publish` operations. Product-specific checks, publication expectations, artifact builds, and delivery retain their distinct responsibilities. -### Work needed - -- Design and integrate the shared specification, profile mapping, execution, - and error model described in [model.md](model.md). -- Preserve existing default behavior and additional-check support, and align - GoDoc, profile guidance, and CLI reporting as the model lands. -- Evaluate the model against Audita, ConfigKit, and PromptKit before finalizing - the interfaces used by the individual validation features. - -Completion should provide a common foundation for the validation capabilities -below, with small consumer declarations and reusable execution. +Completion should provide equivalent Go and profile declarations for the +validation capabilities below through the existing shared foundation. ## 2. Use the application's module-selected ReleaseKit version in CI @@ -76,21 +69,7 @@ validation and builds. Source publication and hosted delivery retain separate outcomes. ReleaseKit's own source bootstrap and consumers using a separately installed tool remain supported use cases. -### Work needed - -- Revise the maintained CI template to establish the tagged checkout before - selecting and building the module's ReleaseKit command. Remove the separate - version setting from this module-based integration and keep bootstrap logic - small and reusable. -- Update adoption and upgrade guidance to explain module-based selection, - compatible Go environments, dependency preparation, and migration from the - existing workflow pin. Explain the applicable bootstrap for consumers that - use a separately installed tool. -- Adapt workflow verification to exercise tool selection from the tagged - module configuration, including a dependency-version change, while preserving - tag/commit checks and existing source-only and binary delivery behavior. -- Apply the revised integration to Audita as the first consumer migration and - confirm that its local wrapper and CI use the same module-selected tool. +Audita adopts the module-based integration as the first consumer migration. Completion should leave downstream maintainers with one ReleaseKit dependency update for this integration and a maintained template they can adopt directly. @@ -120,15 +99,6 @@ scope, offline execution, ordering, and failure reporting. Additional product checks remain available after shared validation. Selecting race testing reports unavailable prerequisites clearly and preserves the selected validation. -### Work needed - -- Add compact validation options to the facade and profile, and carry them - through both candidate-check and publication paths. -- Extend shared Go invocation handling to apply race selection to the base - suite while preserving its offline environment and native test behavior. -- Update consumer guidance and verify default behavior, one selected suite run, - consistent API/CLI behavior, and propagation of validation failures. - Completion should let ConfigKit and PromptKit select a race-enabled suite once and remove the corresponding consumer-owned test invocation. @@ -151,14 +121,6 @@ with failures reported through the ordinary check and publication flow. The option preserves current defaults for consumers that leave it unset. ReleaseKit owns the offline command and its coordination with base testing. -### Work needed - -- Add the full-vet selection to shared validation configuration and execution. -- Coordinate the base test invocation with the separate pass so consumers - express the desired coverage once. -- Document the selection and verify ordering, test-time vet omission, failure - handling, and unchanged default behavior through the shared validation path. - Completion should replace ConfigKit's and PromptKit's separate vet commands and manual test-time vet settings with one declarative choice. @@ -186,16 +148,6 @@ require no binary name, version smoke command, or artifact manifest. Successful compilation establishes build compatibility; execution on a target remains a separate concern. Consumers select targets for their support commitments. -### Work needed - -- Add a package-compilation target declaration to validation configuration, - distinct from the existing artifact build specification. -- Reuse internal Go environment and target handling for offline compilation, - replacing consumer-owned loops and preserving one base test execution. -- Document the distinction between compatibility checks and deliverables, and - verify selected-target compilation, failure reporting, and unchanged - source-only delivery behavior. - Completion should let ConfigKit declare its two Linux targets and remove its release-specific compilation loop. @@ -221,15 +173,6 @@ The expectation applies to the publication destination. Fetch configuration retains its existing semantics, and `Check` retains its local-only behavior. Consumers that omit the expectation keep the current remote-selection model. -### Work needed - -- Add the optional expectation to the facade and profile and compare it at - the existing publication endpoint-resolution boundary. -- Reuse captured-endpoint handling and define the destination-comparison - semantics in GoDoc and consumer guidance. -- Verify matching, mismatching, and omitted expectations, including resolved - Git URL behavior, while preserving existing recheck and recovery coverage. - Completion should let consumers declare the intended push destination without maintaining their own publication preflight logic. @@ -253,15 +196,6 @@ Consumers select the capability once and rely on ReleaseKit for enumeration, format checking, and failure reporting. Existing validation defaults remain unchanged when the option is unset. -### Work needed - -- Add formatting selection and shared inspection of tracked Go source to the - candidate-validation API, profile, and execution path. -- Provide actionable diagnostics for formatting differences and inspection - failures while preserving source files. -- Document the formatting convention and verify formatted and unformatted - inputs, consistent API/CLI behavior, and unchanged default validation. - Completion should let PromptKit remove its local formatting loop and select the shared check through its release profile. @@ -298,20 +232,6 @@ the checkout a validation failure, using the same parser and diagnostics. Boundary validation remains independent of neighboring checkout contents. Existing validation defaults remain unchanged when the option is unset. -### Work needed - -- Define the supported Markdown link forms and heading-anchor convention, - including destination resolution and diagnostics for out-of-scope links. -- Add shared parsing and local destination/fragment validation behind the - public validation API and profile selection. -- Add the optional checkout-boundary rule to the shared Markdown settings, - with diagnostics that identify the source location and destination. -- Document supported behavior and verify valid and broken links, heading - fragments, representative Markdown syntax, and handling of code examples - and links outside the checkout with the boundary rule enabled and disabled. -- Verify that checking is offline, preserves files, and behaves consistently - through candidate checking and publication. - Completion should let PromptKit replace its local Markdown checker with a profile selection and rely on shared parsing rules and diagnostics. @@ -340,16 +260,6 @@ The checks inspect candidate contents independently of the Go test environment. `Check` and `Publish`, including their CLI forms, apply the same offline, read-only checks. Omitted selections preserve current defaults. -### Work needed - -- Add independent distribution-rule selections to the validation API and profile. -- Implement shared candidate-file inspection and module-declaration parsing, - distinguishing local filesystem replacements from versioned replacements. -- Document the inspection scope and diagnostics, and verify workspace files, - local and versioned replacements, and independent rule selection. -- Verify equivalent API/CLI behavior, unchanged defaults, and inspection of - distributed files regardless of workspace discovery settings during testing. - Completion should let PromptKit declare its distribution requirements and remove the corresponding consumer-owned checks. @@ -376,14 +286,5 @@ repository size remain separate concerns. `Check` and `Publish`, including their CLI forms, use the same offline, read-only inspection. The check is disabled by default. -### Work needed - -- Add file-size selection, a configurable byte limit, and path exclusions to - the shared validation API and profile. -- Implement candidate-file size inspection with actionable diagnostics. -- Document units, threshold behavior, exclusions, and the scope of inspection. -- Verify files below, at, and above the limit; configured limits and exclusions; - and equivalent API/CLI behavior with the check enabled and disabled. - Completion should let consumers catch oversized candidate files through a small declaration and remove any corresponding local inspection code.