Complete implementation handoff documentation

README.md

@@ -5,8 +5,8 @@ process. The Go module, root `releasekit` facade, `buildinfo` runtime package,
 local candidate check, source-tag publication API, selected-target build API,
 tagged-source delivery API, and `version`, `check`, `publish`, `build`, and
 `deliver` commands are implemented. ReleaseKit's source-only maintainer
-procedure is documented. Its own hosted-page wiring and executable artifacts
+procedure and prepared Woodpecker workflow for hosted note-page delivery are
-remain future work. The
+documented. ReleaseKit does not declare binary deliverables. The
 [product roadmap](docs/roadmap/releasekit.md) and
 [implementation plan](docs/roadmap/implementation.md) describe their selected
 behavior and sequence.
@@ -41,8 +41,8 @@ failure recovery.
 
 ## Documentation
 
-- [ReleaseKit proposal](docs/roadmap/releasekit.md): proposed publication, builds,
+- [ReleaseKit proposal](docs/roadmap/releasekit.md): selected publication, builds,
-  version injection, and delivery, with the initial implementation plan.
+  version injection, and delivery conventions, with the implementation plan.
 - [Contributor guide](docs/development.md): orientation, validation, and selective
   policy reading.
 - [CLI contract](docs/cli.md): the `version`, `check`, `publish`, `build`, and

docs/config.md

@@ -43,7 +43,7 @@ builds selected tagged-source targets into temporary storage or loads verified
 assets from the directory selected by `--assets`. An absent build object or an
 empty target set selects page-only delivery.
 
-ReleaseKit's source-only publication profile is
+ReleaseKit's source-only profile is
 [releasekit.json](../releasekit.json).
 See the [source-only profile](../examples/releasekit.json) and
 [binary profile](../examples/releasekit-binary.json). The

docs/development.md

@@ -69,5 +69,6 @@ Run the source publication command from the candidate repository root with
 `./scripts/release VERSION`. It uses the local Go toolchain and committed
 `releasekit.json` profile; prepare module dependencies before offline candidate
 validation. The [maintainer release procedure](release.md) owns preparation,
-publication, and recovery. Executable artifacts and delivery remain outside
+publication, and recovery. Hosted note-page delivery is a separate prepared
-ReleaseKit's initial source-only release.
+workflow and does not change the successful-tag-push completion point. ReleaseKit
+does not declare binary deliverables.

docs/internal/overview.md

@@ -1,40 +1,82 @@
-# Internal package inventory
+# Package and capability inventory
 
-Public facades and their contracts are defined in Go declarations and GoDoc.
+Public Go contracts are defined in declarations and GoDoc. ReleaseKit supports
-The [runtime consumer guide](../consumers/runtime-version.md) covers application
+two Go facades and a command-line interface:
-usage, and the [CLI contract](../cli.md) covers command behavior.
 
-Implemented internal packages:
+- The root `releasekit` package is the orchestration facade. `Check` validates
+  one local candidate, `Publish` validates and publishes its exact annotated
+  source tag, `Build` compiles selected application targets, and `Deliver`
+  delivers a tagged note page and any declared assets.
+- `buildinfo` is the small runtime facade. `Version` reports the injected
+  application version, the main-module version when available, or `dev`.
+- `cmd/releasekit` is the executable interface. Its `version`, `check`,
+  `publish`, `build`, and `deliver` commands adapt profiles and command output
+  to the supported library operations.
 
-- `internal/runtimeinfo` holds the injected version value and selects the
+See the [CLI contract](../cli.md), [configuration reference](../config.md),
-  executable's main-module version when no injected value is present.
+[candidate check guide](../consumers/check.md),
-- `internal/versioncontract` names the linker symbol and stable version form
+[build guide](../consumers/build.md),
-  shared with the build and candidate operations.
+[delivery guide](../consumers/delivery.md), and
-- `internal/apicheck` checks compiled exports with `go/types` and checks import
+[runtime version guide](../consumers/runtime-version.md) for task-oriented use.
-  direction. Run it with `go run ./internal/apicheck` from the repository root.
+Go declarations and GoDoc remain the owners of exact exported contracts.
-- `internal/process` runs cancellable child commands with per-child environment
-  overlays.
-- `internal/build` compiles explicit Go targets with shared version injection,
-  verifies native version output, and returns generated file digests.
-- `internal/gitea` verifies hosted source tags, manages matching stable release
-  pages, and inspects and uploads declared attachments through the Gitea REST API.
-- `internal/candidate` captures and validates one clean local candidate, checks
-  its committed release note and local tag state, runs validation once, and
-  rechecks mutable repository state.
-- `internal/git` resolves one effective push destination, applies it to a
-  command-scoped remote, reads exact authoritative branch and tag refs, and
-  creates and pushes exact annotated tag objects.
-- `internal/publish` coordinates local and remote guards around one validation
-  run and reports the publication state reached by that invocation.
-- `internal/delivery` verifies a tagged checkout and coordinates note, build
-  identity, hosted page, asset inspection, and additive upload outcomes.
-- `cmd/releasekit/internal/cli` parses implemented commands, loads strict JSON
-  profiles, adapts configured checks, and writes and validates private local
-  build receipts used for delivery.
 
-The executable controller uses the runtime facade and the command-owned CLI
+## Module and dependencies
-adapter. The adapter uses the process runner and imports neither public facade.
+
-The publication operation coordinates the candidate and Git packages. The
+The module is `gitea.maximumdirect.net/eric/ReleaseKit`, with Go language
-internal Gitea client is documented in the
+version `1.25.0`. `go.mod` has no required third-party modules; packages use the
-[Gitea integration guide](../integrations/gitea.md); tagged-source orchestration
+standard library and first-party ReleaseKit packages. `go list ./...` reports
-is exposed through the public delivery facade and CLI.
+these implemented packages:
+
+| Package | Responsibility |
+| --- | --- |
+| `releasekit` | Public orchestration facade and consumer-owned request/result types. |
+| `buildinfo` | Public runtime version accessor. |
+| `cmd/releasekit` | Executable entry point, command routing, output, and exit status. |
+| `cmd/releasekit/internal/cli` | Command parsing, strict JSON profile loading, configured checks, and private build receipts. |
+| `internal/apicheck` | Compiled-export and import-boundary checks run during development. |
+| `internal/build` | Selected Go target compilation, version injection, native smoke check, and artifact digests. |
+| `internal/candidate` | Stable-version, note, repository-state, candidate capture, and post-validation checks. |
+| `internal/delivery` | Tagged-checkout verification and coordination of release pages, assets, and delivery results. |
+| `internal/git` | Git command boundary, push-destination resolution, exact ref inspection, and tag operations. |
+| `internal/gitea` | Gitea API transport, hosted release pages, asset inspection, manifests, and uploads. |
+| `internal/process` | Cancellable child-process execution with per-command environment overlays. |
+| `internal/publish` | Publication guards, one validation run, annotated tag creation, push, and recovery state. |
+| `internal/runtimeinfo` | Private version lookup used by the runtime facade. |
+| `internal/versioncontract` | Shared stable-version rules and linker-symbol identity. |
+
+The `buildinfo` facade depends only on its small runtime implementation. The
+root facade forwards to internal implementation packages. The CLI adapter is
+owned under `cmd/releasekit/internal`; implementation packages do not import
+either public facade. `internal/apicheck` verifies exported type ownership and
+dependency direction with `go run ./internal/apicheck`. These constraints are
+also recorded in [ADR 0001](../adr/0001-public-facade.md) and the
+[architecture policy](../policy/architecture.md).
+
+## Capability owners and behavioral evidence
+
+The following tests are representative evidence from the current offline suite,
+not a separate release matrix:
+
+| Capability | Implementation owner | Existing evidence |
+| --- | --- | --- |
+| Runtime version lookup and injected application version | `buildinfo`, `internal/runtimeinfo`, `internal/versioncontract`, `internal/build` | `TestVersionInConsumerExecutable`, `TestVersion` |
+| Candidate capture, committed note, one validation, and rechecks | `releasekit.Check`, `internal/candidate`, `cmd/releasekit/internal/cli` | `TestCheckCapturesCandidateAndCallsValidationOnce`, `TestCheckRechecksHeadAndWorktreeAfterCallback`, `TestCheckCommandBindsConfiguredChecksToCapturedCandidate` |
+| Authoritative endpoint and exact annotated tag publication | `releasekit.Publish`, `internal/publish`, `internal/git` | `TestPublishPushesOnlyTheCapturedAnnotatedTag`, `TestResolveUsesPushURLAndQueriesWithoutMutation` |
+| Publication partial and uncertain recovery | `internal/publish` | `TestPublishRejectedPushKeepsLocalTagAndReportsNotPublished`, `TestPublishLostAcknowledgmentConfirmsExactRemoteObject`, `TestPublishUnavailableReconciliationRemainsUnknownAndPreservesPushError` |
+| Cross-builds, version smoke checks, empty target sets, and partial outputs | `releasekit.Build`, `internal/build`, `buildinfo` | `TestBuildCreatesSelectedTargetsAndInjectsVersion`, `TestBuildWithNoTargetsDoesNotInvokeCompiler`, `TestBuildReturnsPartialArtifactsAfterTargetFailure` |
+| Page-only and binary tagged-source delivery | `releasekit.Deliver`, `internal/delivery`, `internal/gitea`, CLI | `TestDeliverPageOnlyCreatesAndReusesRelease`, `TestDeliverBuildsTaggedArtifactsAndReusesAssets`, `TestDeliverRejectsTamperedAssetsAndStaleReceiptBeforeRemoteWrites` |
+| Page, manifest, asset comparison, and additive retry outcomes | `internal/gitea` | `TestEnsureReleaseCreatesMissingPageFromCommittedNote`, `TestInspectAssetsDetectsSameNameAndSizeWithDifferentBytes`, `TestUploadMissingPartialFailureThenRerunOnlyMissingAssets` |
+| CLI profiles and prepared Woodpecker sequences | `cmd/releasekit`, `cmd/releasekit/internal/cli`, `examples/woodpecker/` | `TestLoadSettingsRejectsInvalidProfiles`, `TestWoodpeckerDeliveryCommandSequences`, `TestReleaseKitSourceDeliveryWorkflowFromTaggedCheckout` |
+
+Run the complete suite with `go test ./...`. The public API and import boundary
+check is `go run ./internal/apicheck`. Local HTTP and Git fixtures exercise
+publication and delivery without real credentials or a hosted service.
+
+## Integration references
+
+The [Gitea integration guide](../integrations/gitea.md) owns the HTTP contract
+and hosted response handling. The [Woodpecker examples](../../examples/woodpecker/)
+are prepared integrations; their YAML is not active in this repository, and no
+live Woodpecker runner, configured secret, or hosted delivery has been used.
+Consumer migrations and measurement of removed consumer infrastructure remain
+future adoption work.

docs/roadmap/implementation.md

@@ -1,6 +1,6 @@
 # ReleaseKit staged implementation plan
 
-Status: In progress. Stages 1–17 are complete; later stages remain pending.
+Status: Complete. Stages 1–18 are complete.
 
 Date: 2026-10-05
 
@@ -170,8 +170,10 @@ directory. A profile supplies product identity, remote, candidate commands,
 optional build specification, and optional Gitea delivery declaration. The
 command supplies the version rather than persisting it in the profile.
 
-Use this eventual profile shape; add each optional responsibility only when its
+This composite profile shows the implemented fields together; working
-stage implements it:
+[source-only](../../examples/releasekit.json) and
+[binary-producing](../../examples/releasekit-binary.json) profiles are maintained
+under `examples/`:
 
 ```json
 {
@@ -192,8 +194,7 @@ stage implements it:
 }
 ```
 
-This is a planned example, not an existing file or working invocation. Command
+Command entries also accept an `env` map. Run argument vectors directly, without
-entries also accept an `env` map. Run argument vectors directly, without
 implicit shell parsing. A repository that needs shell syntax selects `sh` or
 `bash` explicitly. Run commands in the captured repository directory and supply
 `RELEASEKIT_VERSION` and `RELEASEKIT_CANDIDATE` for candidate-specific checks.
@@ -920,7 +921,7 @@ was used.
 
 ## Stage 18: Complete the initial implementation and handoff documentation
 
-Status: Pending. Depends on Stage 17.
+Status: Complete. Depends on Stage 17.
 
 1. Map each initial capability in the feature roadmap to its implemented owner
    and existing behavioral evidence. Record the concrete package and dependency
@@ -946,6 +947,26 @@ implemented boundary accurately. Completion depends on local implementation
 and development evidence; architectural review, a broader testing plan,
 consumer migrations, and release/deployment decisions follow this sequence.
 
+Evidence and handoff: `docs/internal/overview.md` records both public Go
+facades, all 14 implemented Go packages, the absence of third-party module
+dependencies, capability ownership, and representative behavioral tests. The
+README and canonical CLI, configuration, consumer, integration, development,
+and release documents describe the implemented behavior; the policy and product
+roadmaps no longer present completed facade, delivery, or workflow work as
+pending. `go test ./...`, `go run ./internal/apicheck`, local Markdown link and
+fragment checks, and prose whitespace checks pass. All three maintained
+Woodpecker examples parse with local PyYAML 6.0.3, with the token mapped only in
+each delivery step. Local Git and HTTP fixtures exercise source-only delivery,
+binary delivery, publication recovery, and the ReleaseKit tagged-source workflow.
+
+The Woodpecker workflows remain prepared, not activated. No live runner,
+configured deployment secret, immutable deployment pin, hosted Gitea delivery,
+or ReleaseKit source release was used or verified. Consumer migrations and
+measurement of removed consumer infrastructure remain future adoption work.
+The implementation is ready for the maintainer's subsequent architecture
+review; broader testing and release or deployment decisions remain outside this
+completed implementation sequence.
+
 ## Coverage of the feature roadmap
 
 | Initial target responsibility | Implementing stages |

docs/roadmap/policy.md

@@ -1,8 +1,8 @@
 # Adopt the policy framework
 
-Status: Policy adoption complete. Source publication and its maintainer runbook
+Status: Policy adoption complete. Source publication, its maintainer runbook,
-are implemented; no ReleaseKit release has been published. Executable delivery
+and prepared hosted note-page delivery are implemented; no ReleaseKit release
-remains pending.
+has been published. Binary distribution remains deferred.
 
 Date: 2026-10-05
 
@@ -130,8 +130,9 @@ policy has separate defaults for applications and libraries.
 
 - [x] Adopt the general versioning, compatibility, integrity, immutability, and
   successful-tag-push completion rules.
-- [x] Select source only as ReleaseKit's initial deliverable in the release
+- [x] Select the immutable source tag as the source-completion point and the
-  policy. Supporting downstream cross-builds does not declare ReleaseKit binaries.
+  hosted note page as a separate asynchronous deliverable. Supporting downstream
+  cross-builds does not declare ReleaseKit binaries.
 - [x] Add `docs/release.md` alongside the first working publication command,
   documenting real prerequisites, authoritative remote, branch, validation,
   publication, and failure recovery.
@@ -145,8 +146,8 @@ policy has separate defaults for applications and libraries.
   separate. This task is deferred unless executable deliverables are selected.
 
 The publication command, its automated guards, offline candidate validation,
-and executable maintainer runbook are implemented. This adoption does not claim
+executable maintainer runbook, and prepared hosted-page workflow are implemented.
-that a ReleaseKit version has been published.
+This adoption does not claim that a ReleaseKit version has been published.
 
 ## Validation and completion
 
@@ -157,8 +158,8 @@ examples added later require appropriate execution checks.
 
 Adoption is complete when the tailored policy set, contributor navigation,
 documentation ownership, and licensing notices are coherent and verified. The
-release-path stage may remain pending until publication is implemented; record
+source-publication command and hosted-page delivery are implemented; actual
-that status without documenting an unavailable command as usable.
+publication and binary distribution remain outside policy adoption.
 
 Do not inherit PromptKit's or ConfigKit's extra release gates automatically.
 Select additional checks only for identified ReleaseKit risks, recording their
@@ -169,13 +170,14 @@ approval, and CI polling are not additional adoption or release gates.
 
 The seven policies, root agent orientation, developer reading guide, documentation
 ownership, project grant, attribution, license texts, source publication command,
-and maintainer runbook are in place. The product proposal lives at
+maintainer runbook, and prepared hosted-page delivery are in place. The product
-`docs/roadmap/releasekit.md`; `ideas.md` remains a navigation pointer. Executable
+proposal lives at `docs/roadmap/releasekit.md`; `ideas.md` remains a navigation
-delivery remains pending, and no ReleaseKit release has been published.
+pointer. Binary distribution is deferred, and no ReleaseKit release has been
+published.
 
 Verification covers local file and fragment links, per-policy source revision and
 base version, removed template adoption sections, attribution scope and pinned
 notice destinations, verbatim license bytes, and prose whitespace. The preserved
 ADR decision and relocated proposal are checked against their pre-adoption source.
-ReleaseKit's source publication command and runbook are implemented; executable
+ReleaseKit's source publication command, runbook, and hosted-page deliverable are
-delivery declarations remain pending under stage 4.
+implemented; binary delivery declarations remain deferred under stage 4.

docs/roadmap/releasekit.md

@@ -1,14 +1,16 @@
 # ReleaseKit: shared release process
 
-This is a proposal based on a review of PromptKit, ConfigKit, Audita, Notarius,
+This proposal records a review of PromptKit, ConfigKit, Audita, Notarius,
-Narratio, and Scriptorium on 2026-09-29. The implementation plan records the
+Narratio, and Scriptorium on 2026-09-29. The initial library, CLI, build and
-current implemented boundary; the internal Gitea page and asset-delivery
+delivery paths, and prepared Woodpecker examples are implemented; the
-client is implemented, while facade/CLI integration and broader integrations
+[implementation plan](implementation.md) records the completed boundary and
-remain planned. The public facade architecture is
+evidence. The public facade architecture is accepted in
-accepted in [ADR 0001](../adr/0001-public-facade.md) and is implemented for
+[ADR 0001](../adr/0001-public-facade.md) and implemented for runtime version,
-runtime version, candidate validation, and source publication.
+candidate validation, source publication, selected-target builds, and tagged-
+source delivery.
 The [implementation plan](implementation.md) owns ordered stages, execution
-instructions, acceptance checks, and progress toward this target state.
+instructions, acceptance checks, and implementation status. Consumer migration
+and measurement of local infrastructure reduction remain future adoption work.
 
 ## Opportunity
 
@@ -29,7 +31,7 @@ of publication scripts, 150–250 lines of checks and builders, and 400–500 li
 of repeated publication tests. ReleaseKit would gain its own implementation and
 tests, so this is a reduction in local code, not a net line-count saving.
 
-## Proposed publication standard
+## Selected publication standard
 
 1. Prepare and commit a version-matched note at `docs/releases/<version>.md`.
 2. Publish the candidate commit to authoritative `main` before invoking the