Add local candidate validation

docs/cli.md

@@ -1,13 +1,30 @@
 # Command line
 
-ReleaseKit currently provides one command:
+ReleaseKit currently provides two commands.
+
+Print the executable version:
 
 ```sh
 go run ./cmd/releasekit version
 ```
 
-It prints `releasekit <version>` followed by a newline and exits with status 0.
+This prints `releasekit <version>` followed by a newline and exits with status 0.
 The version comes from [`buildinfo.Version`](consumers/runtime-version.md).
 
-Any other argument sequence prints an error message followed by
-`usage: releasekit version` to standard error and exits with status 2.
+Check a local candidate:
+
+```sh
+go run ./cmd/releasekit check [--repo DIR] [--config FILE] VERSION
+```
+
+`VERSION` must use stable `vMAJOR.MINOR.PATCH` syntax. Options must precede the
+version. The repository defaults to the current directory, and the profile
+defaults to `<repository>/releasekit.json`. A successful command prints the
+captured local commit and version. It checks the committed release note, local
+Git state, and configured validation, but does not inspect remote availability
+or publish a tag.
+
+Both commands write errors and diagnostic output to standard error. `check`
+returns status 0 after local validation, 1 after a candidate validation failure,
+and 2 for usage, profile, or invalid-version errors. Unsupported argument
+sequences print usage to standard error.

docs/config.md

@@ -19,9 +19,11 @@ shell syntax. Each `env` map overlays the current environment for that child.
 The overlay does not modify the ReleaseKit process environment.
 
 Unknown fields are rejected so a setting cannot be silently ignored. Build and
-delivery fields will be added when those operations are implemented. Profile
-loading and child-command adaptation are implemented; no CLI operation consumes
-the profile yet.
+delivery fields will be added when those operations are implemented. The `check`
+command uses `product`, `remote`, and `checks`. If `checks` is omitted or empty,
+it runs `go test -mod=readonly -count=1 ./...` with Go module and toolchain
+network access disabled. If checks are configured, they replace that default and
+run in order.
 
 See the [profile example](../examples/releasekit.json). The
 [CLI contract](cli.md) lists the currently available command.

docs/consumers/check.md

@@ -0,0 +1,34 @@
+# Local candidate check
+
+Use `releasekit.Check` to verify a candidate against the current local
+repository state:
+
+```go
+result, err := releasekit.Check(ctx, releasekit.ReleaseRequest{
+	RepositoryDir: "/work/project",
+	Product:       "Example",
+	Version:       "v1.2.3",
+	Validate: func(ctx context.Context, candidate releasekit.Candidate) error {
+		return runProjectChecks(ctx, candidate.RepositoryDir)
+	},
+})
+if err != nil {
+	return err
+}
+fmt.Println(result.Version, result.Commit)
+```
+
+The repository must have a clean index and worktree on `main`, and the selected
+version must be stable `vMAJOR.MINOR.PATCH`. The committed
+`docs/releases/<version>.md` note must have a first Markdown H1 containing the
+product name and exact version as complete title elements. No local tag with
+that version may already exist.
+
+The callback receives the captured repository, commit, and version. ReleaseKit
+calls it once. When omitted, ReleaseKit runs the offline Go test command. The
+check revalidates the branch, commit, and cleanliness after validation.
+
+A successful check is evidence about the local candidate only. It does not
+check whether a remote branch or tag is available and does not create a tag.
+The [`check` command](../cli.md) reads the product and optional validation
+commands from `releasekit.json`.

docs/development.md

@@ -49,9 +49,9 @@ root with:
 go run ./internal/apicheck
 ```
 
-See the [internal package inventory](internal/overview.md) and
-[implementation plan](roadmap/implementation.md) for current implementation
-progress.
+See the [candidate check guide](consumers/check.md), [internal package
+inventory](internal/overview.md), and [implementation plan](roadmap/implementation.md)
+for current implementation progress.
 
 For prose changes, review the diff and check local links, fragment destinations,
 provenance, template residue, and consistency with current repository contents.

docs/internal/overview.md

@@ -14,6 +14,9 @@ Implemented internal packages:
   direction. Run it with `go run ./internal/apicheck` from the repository root.
 - `internal/process` runs cancellable child commands with per-child environment
   overlays.
+- `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.
 - `cmd/releasekit/internal/cli` parses implemented commands, loads strict JSON
   profiles, and adapts configured checks to the process runner.
 

docs/roadmap/implementation.md

@@ -538,7 +538,7 @@ internal package documentation.
 
 ## Stage 5: Capture and validate one local candidate
 
-Status: Pending. Depends on Stage 4.
+Status: Complete. Depends on Stage 4.
 
 1. Implement stable-version syntax, clean `main` and index/worktree inspection,
    captured HEAD, profile snapshot/note loading, title identity, and unused local
@@ -558,6 +558,13 @@ HEAD, callback failure, and a callback changing HEAD or the worktree. Count a
 successful callback once. No test needs a publication service, and `Check`
 creates no tag or remote ref.
 
+Evidence: `internal/candidate` validates stable versions and committed note
+identity, captures a clean `main` commit, runs either the offline default or the
+configured callback once, and rechecks local mutable state. The public
+`releasekit.Check` API and `releasekit check` command provide the local
+diagnostic. Temporary Git repositories cover the acceptance cases; offline
+`go test -count=1 ./...` and `go run ./internal/apicheck` pass.
+
 ## Stage 6: Resolve and inspect the authoritative endpoint
 
 Status: Pending. Depends on Stage 5.