notarius/docs/roadmap/implementation.md

PromptKit v0.2.0 Upgrade Implementation Plan

Objective

Upgrade Notarius from gitea.maximumdirect.net/eric/promptkit v0.1.0 to v0.2.0 and adopt the release capabilities that fit the current application:

• native request-level session propagation;
• tri-state, run-wide reasoning-effort overrides;
• backend-aware LLM provenance;
• provider-neutral handling of PromptKit backend-capacity exhaustion; and
• accurate documentation of the layered Notarius and PromptKit concurrency model.

Each numbered stage below is intended to be implemented by one LLM coding-agent prompt, in order. A stage is complete only when its focused tests, documentation updates, and acceptance criteria pass. Do not implement later-stage behavior early unless a small compile-preserving type addition is explicitly required by the current stage.

Repository Baseline

The plan is grounded in the following current implementation:

• go.mod pins PromptKit v0.1.0.
• internal/framework/llm/promptkit_client.go is the sole production adapter from Notarius's provider-neutral StructuredLLMClient contract to PromptKit.
• PromptKitClient.CompleteStructured currently assigns promptkit.RunRequest.Metadata; v0.2.0 removes that field. A temporary v0.2.0 modfile build fails at this assignment.
• The same adapter currently supplies StructuredCompletionRequest.SessionID only through a session_id prompt variable. It does not set a direct PromptKit request session.
• The CLI already supplies one run-wide --session-id, passes it to every prompt-facing stage, records it in checkpoint runtime identity, and exposes it in debug/run metadata.
• PromptKit public values are not persisted wholesale. The adapter maps them into Notarius-owned contracts, debug values, and manifests. PromptKit v0.2.0's public JSON changes therefore do not require conversion of existing Notarius output or checkpoint payloads.
• concurrency.total_llm is enforced by Notarius's application-wide scheduled client. PromptKit v0.2.0 adds an independent engine-local scheduler keyed by backend ID.
• Current production profiles are either PromptKit built-ins or user-supplied endpoint profiles. Notarius has no configuration contract for registering custom PromptKit backends.
• PromptKit composite literals in the repository are keyed; no positional literal migration is expected.
• The pre-upgrade go test ./... baseline passes.

Use the PromptKit v0.2.0 tag, not the moving main branch, as the dependency and API authority. The release guide and exact tagged contracts are:

• https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.2.0/docs/releases/v0.2.0.md
• https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.2.0/docs/consumers/pkg-promptkit.md
• https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.2.0/docs/formats.md
• https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.2.0/types.go
• https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.2.0/backends.go
• https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.2.0/engine.go

Decisions

Dependency and compatibility

• Pin exactly PromptKit v0.2.0.
• Keep all PromptKit struct literals keyed.
• Delete the obsolete RunRequest.Metadata mapping. Do not invent a replacement upstream metadata channel.
• Keep StructuredCompletionRequest.StageName; it remains useful in Notarius-owned stage and debug behavior even though it is no longer sent to PromptKit.
• Update the built-in profile-catalog checkpoint identity from v0.1.0 to v0.2.0.
• Do not add a migration for PromptKit public JSON because Notarius does not persist those values directly.

Session propagation

• --session-id remains the only user-facing session surface.
• Set promptkit.RunRequest.SessionID to the trimmed Notarius request session.
• Continue populating Vars["session_id"] with the same value for prompt compatibility. The direct field is authoritative for provider session behavior; the variable exists only so a maintained prompt that renders .session_id does not break silently.
• Keep the existing checkpoint session fingerprint unchanged.
• Do not add a profile or configuration session setting.

Reasoning override

Expose PromptKit's three states through two CLI flags:

• no flag: inherit the selected PromptKit profile (nil);
• --reasoning-effort VALUE: replace the profile value with trimmed, non-empty VALUE; and
• --clear-reasoning-effort: pass a pointer to an empty string, explicitly clearing inherited reasoning.

The two flags are mutually exclusive. An explicitly empty --reasoning-effort is a CLI usage error with exit status 2.

The override is invocation-wide and applies to every PromptKit call made by that command. Persistent reasoning policy remains in PromptKit profiles; do not add a Notarius configuration field or per-lane reasoning option.

Use a dedicated value object, named LLMRuntimeOverrides, at the CLI factory boundary. It must contain ReasoningEffort *string, where:

• nil means inherit;
• a non-empty pointed-to string means replace; and
• an empty pointed-to string means clear.

The PromptKit client must defensively copy the pointed-to value during construction. It must create a keyed promptkit.ExecutionTargetOverride{ReasoningEffort: ...} for each run request when the override is non-nil and leave RunRequest.Execution nil otherwise.

Checkpoint and debug identity

• Add the reasoning override to checkpoint runtime identity because it can change generated output.
• Omit the fingerprint when the override is inherited.
• Use fingerprint name reasoning_effort_override.
• Use the trimmed value for replacement and the stable literal <cleared> for explicit clearing. Do not use an empty fingerprint value.
• Record the tri-state value in debug invocation metadata as reasoning_effort_override using *string with omitempty; a non-nil empty string must remain distinguishable from omission.
• Reasoning effort is non-secret provider configuration, but it must still pass through the existing redaction-safe debug path.

Backend identity and concurrency

• Keep the Notarius total_llm scheduler. It is an application-wide limit across every provider and backend.
• Allow PromptKit's v0.2.0 backend scheduler to impose a narrower backend-specific limit. Do not attempt to merge, disable, or reimplement the two schedulers.
• Document the effective active generation bound as the intersection of the Notarius global limit and the selected PromptKit backend limit.
• Endpoint-only profiles remain limited only by Notarius.
• Built-in OpenRouter profiles automatically select PromptKit's reserved openrouter backend and its upstream capacity policy.
• Add optional backend_id and reasoning_effort fields to Notarius LLMProfileManifest values and published manifest JSON.
• Populate those fields from RunResult.SelectedBackendID and RunResult.EffectiveModelParams.ReasoningEffort.
• Include both fields in recorder identity and sorting so distinct effective executions are not collapsed.
• Extend Notarius debug prompt metadata with selected_backend_id; retain the existing serialized effective-model parameters.

Capacity failure

• Add a provider-neutral sentinel contracts.ErrLLMCapacityExceeded.
• When PromptKitClient receives an error matching promptkit.ErrCapacityExceeded, return an error matching the Notarius sentinel and include redacted diagnostic context.
• Do not require callers outside internal/framework/llm to import PromptKit or match a PromptKit error.
• Capacity exhaustion is an operational stage error, not invalid structured output and not a validator rejection.
• Do not retry inside the adapter. Existing configured stage retry behavior applies, and the run fails if those retries are exhausted.

Configuration and versioning

• Keep Notarius configuration version 4.
• Do not add promptkit.backends, backend registration fields, or a configuration-level reasoning override.
• Existing PromptKit profile files remain valid because v0.2.0 continues to support endpoint-only profiles.

Documentation and decision records

• Update canonical documentation in the same stage that changes its behavior.
• No ADR is required: this work advances the existing LLM boundary and scheduler architecture without changing its direction or replacing a prior durable decision.
• Remove the completed “Native Session Propagation” item from docs/roadmap/future.md only after native session behavior is implemented and documented.
• Do not add custom backend registration to this implementation plan. A concise future-roadmap item may be added during final cleanup if it records the demonstrated boundary and avoids implying a commitment.

Non-Goals

This implementation must not:

• register user-defined PromptKit backends;
• expose backend endpoint, API-key environment, extra-parameter, concurrency, or queue-capacity fields in Notarius configuration;
• remove or weaken concurrency.total_llm;
• add module-specific or lane-specific reasoning overrides;
• add another session flag or configuration field;
• remove the compatibility session_id prompt variable;
• persist or expose raw PromptKit RunResult/PreparedRun JSON as a Notarius contract;
• translate old PromptKit v0.1.0 JSON;
• change D&D prompt text, response schemas, or artifact contracts;
• change pipeline retry semantics; or
• call a live model provider in tests.

Stage 1 — Upgrade The Dependency And Restore Compilation

Goal

Move to PromptKit v0.2.0 with no intentional user-visible behavior change beyond using the new upstream release.

Files and areas

• go.mod
• go.sum
• internal/framework/llm/promptkit_client.go
• internal/framework/llm/promptkit_profile_fingerprint.go
• corresponding LLM adapter and fingerprint tests
• docs/integrations/pkg-promptkit.md

Implementation

1. Run:

   go get gitea.maximumdirect.net/eric/promptkit@v0.2.0
   go mod tidy
   

2. Remove the Metadata field from the constructed promptkit.RunRequest.

3. Delete promptKitMetadata and tests that exist only for the removed upstream metadata mapping. Do not delete StageName from Notarius contracts.

4. Change promptKitBuiltinProfileCatalogID to promptkit:v0.2.0:builtin-profiles.

5. Update fingerprint expectations so v0.2.0 has a distinct deterministic checkpoint identity.

6. Review every promptkit.*{...} literal touched by compilation and keep it keyed.

7. Update the PromptKit integration document to identify v0.2.0 and link to the tagged v0.2.0 consumer and format documentation. Remove metadata from the stated supported boundary. Do not yet claim that later-stage native session, reasoning CLI, or Notarius capacity classification is implemented.

Tests

• Existing PromptKit asset, profile, adapter, scheduler, and D&D prompt tests must compile and pass.
• Do not add a test whose only purpose is to assert the dependency-version string. The fingerprint behavior is the meaningful compatibility boundary.

Acceptance criteria

• go.mod and go.sum contain v0.2.0 and no v0.1.0 PromptKit entry.
• No production use of RunRequest.Metadata remains.
• The built-in profile checkpoint fingerprint changes deterministically.
• Existing endpoint-only profiles continue to load.
• No Notarius durable schema or configuration version changes.
• Stage documentation describes the actual post-stage boundary.

Validation

go mod tidy
git diff --check
go test ./internal/framework/llm/... ./internal/cli/...
go test ./internal/modules/dnd/...
go test ./...
go vet ./...
go build ./cmd/notarius

This stage is small enough for one implementation prompt.

Stage 2 — Adopt Native Session Propagation

Goal

Make the existing run-wide Notarius session ID reach PromptKit's native direct session field without breaking prompt-variable consumers.

Files and areas

• internal/framework/llm/promptkit_client.go
• internal/framework/llm/promptkit_client_test.go
• PromptKit adapter test prompt fixtures
• existing CLI assembled-run session tests
• docs/internal/llm.md
• docs/integrations/pkg-promptkit.md
• docs/roadmap/future.md

Implementation

1. In PromptKitClient.CompleteStructured, trim StructuredCompletionRequest.SessionID once and assign it to promptkit.RunRequest.SessionID.
2. Continue passing that same trimmed value as Vars["session_id"]. Preserve caller-supplied variables, with the explicit Notarius session taking precedence over a caller-supplied variable of the same name.
3. Leave an empty Notarius session as an empty direct value so PromptKit's prompt-defined session template behavior remains available.
4. Keep session checkpoint identity, CLI behavior, module request propagation, and debug/run metadata unchanged except that debug material should now show PromptKit's native effective session.
5. Update LLM and integration documentation to state:
   • the direct PromptKit session is authoritative for provider behavior;
   • the prompt variable is retained for compatibility;
   • session IDs are stable, non-secret correlation identifiers and may be exposed to providers and provider observability.
6. Remove the completed Native Session Propagation section from docs/roadmap/future.md. Do not replace it with implementation history.

Tests

Add or adapt behavior-focused coverage proving:

• a nonblank Notarius session reaches GenerateRequest.Prompt.SessionID through a prompt definition that has no session_id template;
• the effective session appears in prepared/debug prompt material;
• a prompt that renders .session_id still receives the compatibility variable;
• an empty request does not invent a direct session; and
• the existing assembled-run test still observes one session across every prompt-facing module.

Rely on PromptKit for exhaustive Unicode-length and internal normalization tests. Notarius needs only representative adapter-boundary coverage. Do not add tests for PromptKit's private implementation sequence.

Acceptance criteria

• Provider-facing PromptKit requests use the native session field.
• Existing --session-id syntax and exit behavior are unchanged.
• Checkpoints remain session-separated.
• Prompt-variable compatibility remains intact.
• No second session configuration surface exists.
• The future roadmap no longer describes native session support as blocked.

Validation

go test ./internal/framework/llm/... -run 'Session|PromptKit'
go test ./internal/cli/... -run 'Session|Checkpoint'
go test ./internal/modules/dnd/...
go test ./...
git diff --check

This stage is small enough for one implementation prompt.

Stage 3 — Add Internal Tri-State Reasoning Support

Goal

Teach the PromptKit adapter and CLI factory boundary to represent and apply inherit, replace, and clear states before exposing new command flags.

Files and areas

• internal/framework/llm/promptkit_client.go
• internal/framework/llm/promptkit_client_test.go
• internal/cli/run.go
• internal/cli/catalog.go
• CLI option/factory test helpers and fakes
• docs/internal/llm.md
• docs/internal/cli.md

Implementation

1. Define LLMRuntimeOverrides at the CLI's LLM-client factory boundary with ReasoningEffort *string.
2. Change LLMClientFactory and all production/test implementations to accept LLMRuntimeOverrides. At this stage, ordinary CLI execution passes the zero value, preserving inheritance.
3. Add ReasoningEffort *string to PromptKitClientConfig or an equivalently focused run-override field.
4. Defensively copy the pointer and its string in NewPromptKitClient; do not retain caller-owned mutable pointer state.
5. When non-nil, construct a keyed promptkit.ExecutionTargetOverride for every adapter request and set its ReasoningEffort pointer. When nil, keep RunRequest.Execution nil.
6. Preserve an empty pointed-to value exactly; do not trim it into a missing override. Trim a non-empty replacement once at the CLI boundary in the next stage.
7. Update internal docs to describe the tri-state adapter capability and factory boundary without documenting CLI flags that do not yet exist.

Tests

Use an injected PromptKit LLMClient and table-driven adapter test for:

• nil pointer inherits the selected profile value;
• pointer to a nonblank value replaces it;
• pointer to an empty string clears it; and
• mutating the caller's original pointer after client construction cannot change subsequent requests.

Assert the effective value received in promptkit.GenerateRequest.Target.ReasoningEffort, not internal PromptKit call order.

Acceptance criteria

• The factory and adapter preserve all three states.
• Existing production construction passes nil and retains current profile behavior.
• No CLI or config surface has been added yet.
• Tests use offline injected clients only.

Validation

go test ./internal/framework/llm/... -run 'Reasoning|PromptKit'
go test ./internal/cli/...
go test ./...
git diff --check

This stage is small enough for one implementation prompt.

Stage 4 — Expose The Run-Wide Reasoning CLI Contract

Goal

Make the internal tri-state reasoning override available to users while preserving checkpoint and debug correctness.

Files and areas

• internal/cli/run.go
• internal/cli/catalog.go
• CLI parsing, run-contract, checkpoint, and debug-summary tests
• internal/core/debugbundle/summary.go
• related debugbundle tests
• docs/cli.md
• docs/operations.md
• docs/internal/cli.md
• docs/internal/llm.md

Implementation

1. Add --reasoning-effort VALUE and --clear-reasoning-effort to notarius run.
2. Use a flag value that tracks presence separately from content, following the established sessionIDFlag/single-value patterns where appropriate.
3. Validate before run construction:
   • both flags together are a usage error;
   • an explicitly empty or whitespace-only reasoning value is a usage error;
   • repeated single-value flags follow the CLI's existing duplicate-flag policy.
4. Construct one LLMRuntimeOverrides value:
   • neither flag -> nil;
   • replacement -> pointer to the trimmed value;
   • clear -> pointer to "".
5. Pass it through LLMClientFactory to production PromptKit client construction. The same client is shared across the invocation, so the override applies to chunking, extraction, normalization, validators, and retries without adding fields to module request types.
6. Extend runtimeOverrideFingerprints and every relevant checkpoint-identity call to include the reasoning fingerprint defined in “Decisions.”
7. Add ReasoningEffortOverride *string with JSON name reasoning_effort_override and omitempty to debugbundle.Invocation. Copy the invocation value defensively if any writer retains it.
8. Update command, operations, and internal documentation. Persistent reasoning remains a PromptKit profile concern.

Tests

Add focused behavior coverage for:

• no flags, replacement, and clear;
• the mutual-exclusion error;
• empty replacement rejection;
• forwarding of all three states to the test LLM factory;
• different reasoning states produce different checkpoint identities;
• inherit omits the reasoning fingerprint;
• explicit clear uses <cleared>;
• debug invocation JSON distinguishes omission from ""; and
• existing CLI commands and examples remain unaffected.

Do not replicate the same tri-state cases at every module layer. The CLI, checkpoint, debugbundle, and adapter boundaries each own one distinct risk.

Acceptance criteria

• The public CLI exposes exactly the two agreed flags.
• The override applies run-wide and does not modify resolved pipeline structure or PromptKit profile files.
• Checkpoint reuse cannot cross reasoning states.
• Debug invocation metadata preserves the tri-state distinction.
• CLI reference and operations documentation are current.
• Notarius configuration remains version 4 with no reasoning field.

Validation

go test ./internal/cli/... -run 'Reasoning|Checkpoint|Run'
go test ./internal/core/debugbundle/...
go test ./internal/framework/llm/... -run 'Reasoning'
go test ./...
go run ./cmd/notarius run --help
git diff --check

run --help is expected to follow the repository's documented flag-parser usage behavior and may exit with status 2. Verify the displayed result and status against docs/cli.md.

This stage is substantial but coherent and small enough for one focused implementation prompt. Do not combine it with backend provenance.

Stage 5 — Publish Backend And Effective Reasoning Provenance

Goal

Expose the new PromptKit backend identity and effective reasoning setting in Notarius-owned debug and manifest contracts.

Files and areas

• internal/core/artifacts/artifacts.go
• artifact cloning, sorting, equality, and JSON tests
• internal/framework/llm/promptkit_client.go
• profile recorder and adapter tests
• internal/framework/pipeline/runner.go and profile-manifest merge logic
• pipeline tests involving LLM profile manifests
• internal/framework/contracts/contracts.go debug types if required
• docs/integrations/json-output.md
• docs/integrations/pkg-promptkit.md
• docs/internal/llm.md

Implementation

1. Add optional JSON fields to artifacts.LLMProfileManifest:

   BackendID      string `json:"backend_id,omitempty"`
   ReasoningEffort string `json:"reasoning_effort,omitempty"`
   

   Use the repository's normal Go alignment/formatting.

2. Populate:

   • BackendID from promptkit.RunResult.SelectedBackendID; and
   • ReasoningEffort from RunResult.EffectiveModelParams.ReasoningEffort.

3. Trim both strings at the Notarius boundary.

4. Include both fields in LLMProfileRecorder's deduplication key.

5. Update deterministic merge/sort keys everywhere LLM profile manifests are combined so entries differing in backend or effective reasoning are not collapsed and output order remains stable.

6. Add SelectedBackendID to the Notarius debug prompt representation and populate it from promptkit.PreparedRun.SelectedBackendID.

7. Keep EffectiveModelParams in debug output; it now uses PromptKit v0.2.0's stable lower-case JSON representation and can include backend_id.

8. Update the JSON output integration contract to define the optional backend_id and reasoning_effort members of each llm_profiles entry. Do not claim that Notarius supports user-defined backend registration.

9. Do not bump a D&D artifact schema or configuration version. These are additive optional run-manifest provenance fields, and the JSON bundle contract already requires consumers to tolerate omitted optional manifest fields.

Tests

Add or update tests proving:

• the adapter records backend ID and effective reasoning from a PromptKit result;
• endpoint-only profiles omit backend_id;
• built-in or test registered backend profiles record a non-empty ID;
• profile entries with otherwise equal ID/provider/model but different backend or reasoning remain distinct;
• ordering is deterministic; and
• published manifest JSON uses the documented optional field names.

Do not snapshot an entire debug bundle or published manifest when focused semantic assertions protect the same contract.

Acceptance criteria

• Backend identity does not leak PromptKit types beyond the adapter.
• Published provenance distinguishes effective backend and reasoning.
• Endpoint-only profiles remain valid and omit backend identity.
• Existing JSON consumers remain compatible with additive optional fields.
• Documentation owns the field semantics in the JSON output contract.

Validation

go test ./internal/core/artifacts/...
go test ./internal/framework/llm/... -run 'Profile|Backend|Reasoning'
go test ./internal/framework/pipeline/... -run 'Profile|Manifest'
go test ./internal/modules/generic/output/json/... -run 'Manifest|Profile'
go test ./...
git diff --check

This stage is small enough for one implementation prompt.

Stage 6 — Translate PromptKit Capacity Exhaustion

Goal

Give the application a provider-neutral overload classification while leaving scheduling and retry ownership in their existing layers.

Files and areas

• internal/framework/contracts/errors.go
• internal/framework/llm/promptkit_client.go
• PromptKit adapter tests
• scheduler/scheduled-client tests for regression only
• docs/internal/llm.md
• docs/operations.md
• docs/integrations/pkg-promptkit.md
• docs/policy/architecture.md

Implementation

1. Add:

   var ErrLLMCapacityExceeded = errors.New("LLM capacity exceeded")
   

   with a comment that identifies backend admission exhaustion before generation.

2. In the PromptKit Run error path, check errors.Is(err, promptkit.ErrCapacityExceeded) before generic wrapping.

3. Return an error matching contracts.ErrLLMCapacityExceeded. Include the prompt context and sanitized upstream diagnostic, but do not require an external caller to match the PromptKit sentinel.

4. Preserve context cancellation precedence: when ctx.Err() is non-nil, return the context error as today.

5. Do not classify capacity as ErrInvalidStructuredOutput.

6. Do not add an adapter retry. Allow the calling module/pipeline's existing configured attempt policy to see an operational error.

7. Keep the Notarius scheduled client around the PromptKit adapter.

8. Document:

   • the two independent concurrency layers;
   • built-in OpenRouter's upstream backend limit;
   • endpoint-only profiles having no PromptKit backend limit;
   • capacity failure and stage retry behavior; and
   • the possible effective limit being narrower than total_llm.

9. Add one sentence to architecture policy permitting provider runtime adapters to apply a narrower backend-specific limit beneath the mandatory application-wide scheduler. Do not copy numeric upstream defaults into architecture policy.

Tests

At the adapter boundary, use:

• a test promptkit.Backend with ConcurrencyLimit: 1;
• an explicit zero QueueCapacity;
• a profile selecting that backend; and
• a blocking injected promptkit.LLMClient.

Prove relationally that:

• the first run occupies the one active slot;
• one additional direct adapter run receives an error matching contracts.ErrLLMCapacityExceeded;
• the injected client is not called for the rejected request;
• the error is not ErrInvalidStructuredOutput; and
• provider diagnostic redaction still applies.

Do not duplicate PromptKit's queue fairness, default-capacity, or complete backend scheduler tests. Existing Notarius scheduler tests continue to own the global limit.

Acceptance criteria

• Capacity exhaustion has a stable Notarius error identity.
• PromptKit error types do not become a framework-wide contract.
• The global scheduler remains in production composition.
• No hidden retry or HTTP/status policy is introduced.
• Architecture, operations, integration, and internal docs agree on concurrency ownership.

Validation

go test ./internal/framework/llm/... -run 'Capacity|Scheduler|PromptKit'
go test -race ./internal/framework/llm/...
go test ./internal/cli/... -run 'Concurrency|Retry|Production'
go test ./...
git diff --check

This stage is small enough for one implementation prompt.

Stage 7 — Final Documentation And Release Verification

Goal

Verify the completed upgrade as one coherent current contract, remove stale v0.1.0/native-session planning language, and run the release-recommended test matrix.

Files and areas

• docs/integrations/pkg-promptkit.md
• docs/internal/llm.md
• docs/internal/cli.md
• docs/cli.md
• docs/operations.md
• docs/integrations/json-output.md
• docs/policy/architecture.md
• docs/config.md only if it currently states upstream version or concurrency behavior that became inaccurate
• docs/roadmap/future.md
• go.mod
• go.sum
• all tests

Implementation

1. Review all PromptKit references outside docs/roadmap/ against the v0.2.0 tag.
2. Ensure canonical ownership:
   • CLI owns reasoning flag syntax and errors;
   • configuration owns profile-source and total_llm fields;
   • operations owns effective limits and failure handling;
   • internal LLM docs own adapter/session/reasoning/scheduler mechanics;
   • PromptKit integration owns the upstream version and supported dependency boundary;
   • JSON output owns manifest field semantics; and
   • architecture owns only the invariant that backend limits may narrow the application-wide bound.
3. Remove all claims that PromptKit v0.1.0 is pinned or that native session propagation is blocked.
4. Ensure future.md contains only unimplemented work. If adding a deferred custom-backend item, state that it requires a demonstrated reusable custom endpoint or per-backend policy and must define configuration, redaction, fingerprint, validation, and layered-queue behavior. Do not add implementation staging or imply commitment.
5. Verify that no documentation says Notarius registers custom backends.
6. Confirm examples remain version 4 and unchanged unless a factual documentation link requires adjustment.
7. Run go mod tidy and confirm it produces no additional diff.

Final validation

go mod tidy
go test ./...
go test -race ./...
go vet ./...
go build ./cmd/notarius
git diff --check

go run ./cmd/notarius config validate \
  --config examples/dnd-minimal.config.yml \
  --pipeline dnd-session

OPENROUTER_API_KEY=validation-placeholder \
  go run ./cmd/notarius config validate \
    --config examples/dnd-complete.config.yml \
    --pipeline dnd-session

go run ./cmd/notarius pipelines list \
  --config examples/dnd-minimal.config.yml

OPENROUTER_API_KEY=validation-placeholder \
  go run ./cmd/notarius pipelines list \
    --config examples/dnd-complete.config.yml

rg -n 'promptkit v0\\.1\\.0|PromptKit v0\\.1\\.0|native session.*blocked|Metadata:' \
  README.md docs internal go.mod go.sum

Review search results rather than deleting legitimate historical text blindly. No v0.1.0 PromptKit ADR history currently exists, so the expected final result is no stale version claim.

Acceptance criteria

• PromptKit v0.2.0 is the only selected PromptKit module version.
• Full ordinary and race-enabled test suites pass offline.
• Vet, build, example validation, pipeline listing, and whitespace checks pass.
• Documentation describes only implemented behavior outside the roadmap.
• Native session, reasoning tri-state, backend provenance, and capacity behavior each have one canonical documentation owner.
• Custom backend registration remains unimplemented and is not implied.
• The working tree contains only intentional upgrade changes.

This stage is small enough for one implementation prompt because it is a verification and documentation-consistency pass, not a feature stage.

Completion Checklist

Before declaring the plan complete, verify all of the following:

• PromptKit is pinned to v0.2.0.
• RunRequest.Metadata and promptKitMetadata are gone.
• Built-in profile checkpoint identity names v0.2.0.
• Native direct sessions and the compatibility variable are both present.
• Existing session checkpoint isolation remains intact.
• Reasoning inherit/replace/clear states reach PromptKit exactly.
• CLI reasoning states are mutually exclusive and checkpoint-safe.
• Backend ID and effective reasoning are published as optional provenance.
• Endpoint-only profiles remain supported.
• PromptKit capacity maps to ErrLLMCapacityExceeded.
• Notarius's global scheduler remains active.
• No custom backend configuration was added.
• No PromptKit raw-JSON migration was added.
• Canonical documentation and future.md are current.
• All focused, full, race, vet, build, example, and diff checks pass.

Open Questions

None. The implementation choices required for this scope are resolved above.