From f5b066beeef434c62084564109bf25d7d82f0d0a Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 4 Oct 2026 11:38:01 +0000 Subject: [PATCH] Plan the PromptKit upgrade and configuration inspection --- docs/roadmap/implementation.md | 997 +++++++++++++++++++-------------- docs/roadmap/promptkit.md | 4 +- 2 files changed, 569 insertions(+), 432 deletions(-) diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 01f08557..bb0bebbd 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,528 +1,665 @@ -# ConfigKit Inheritance Implementation Plan +# PromptKit 0.12 Implementation Plan -## Purpose And Scope +## Purpose And Baseline -Implement [ConfigKit 0.5 And Configuration Inheritance](configkit.md). That -feature roadmap owns the intended behavior and policy choices. This document -owns the ordered implementation work. Each numbered stage is one prompt for a -Luna coding agent; complete its acceptance criteria before starting the next. +Implement [PromptKit 0.12 Configuration Migration](promptkit.md). That roadmap +owns the accepted target state; this document owns implementation decisions, +ordered steps, and verification. It replaces the completed ConfigKit plan. +Each numbered stage is one bounded prompt for a Luna coding agent. Execute in +order, inspecting the named code and tests before editing. -The starting baseline pins ConfigKit v0.4.2 and PromptKit v0.11.2, uses ordinary -`configkit.Load`, and accepts Notarius configuration version 5. Upgrade only -ConfigKit to v0.5.0, source commit -`dc09959cca4e105f49ec316c6d4ba585bd2340bd`. The release tag is annotated: use -`git rev-parse 'v0.5.0^{commit}'` when verifying the source commit in a checkout. +The starting revision is `aae01a5`: ConfigKit v0.5.0, PromptKit v0.11.2, and +Notarius configuration version 5. Target PromptKit v0.12.0 at full commit +`4b8169da286917fde7875425bb32b799b12c6af3`, with its selected OpenRouter and +Rakestrawhome `/v3` catalogs at `v3.20260930.0`. ConfigKit and Go remain at the +existing v0.5.0 and 1.25.5 baselines. Inspect released source, not a moving +sibling branch. Use `git show v0.12.0:` in `../promptkit` where helpful; +the annotated tag's source commit is `v0.12.0^{commit}`. -The implementation adds supported native configuration inheritance and a -maintained example. It does not require changing pipeline execution, artifact -schemas, or release tooling. Release preparation and publication remain a -separate task; this feature belongs in a future minor release. +The focused LLM, CLI, and module-integration baseline tests passed during +planning. This is not evidence that the upgraded implementation passes. -## Working Instructions For Every Stage +## Instructions For Every Stage - Read `docs/development.md`, `docs/policy/agents.md`, and the feature roadmap. - Use the development guide to select additional applicable policies, including - architecture, testing, documentation, and OSS for the changes being made. -- Inspect the named code and tests before editing. Prefer the repository's - code knowledge graph for code discovery. Inspect the pinned upstream release - and public API when an integration detail needs confirmation; do not assume - a sibling checkout's current branch equals the released version. -- Keep ordinary `configkit.Load`, typed defaults, and the existing private - configuration boundary. ConfigKit handles `extends` before decoding; add no - `Extends` field, second merge pass, application template registry, or opt-in - flag. Accept valid native inheritance locations under existing domain rules. -- Make production changes only where a concrete integration failure requires - them. A stage may consist of focused tests and documentation when the - existing adapter already behaves correctly. Fix a regression rather than - weakening an established expectation to accommodate the upgrade. -- Test Notarius's boundary with the real ConfigKit dependency and small, - deterministic fixtures. Reuse existing helpers and coverage; do not replicate - ConfigKit's complete test matrix, add diagnostic snapshots, or assert - incidental output formatting. Keep the default suite offline and independent - of credentials and model calls. -- Use `GOWORK=off` for Go commands so a sibling checkout cannot substitute for - the pinned modules. Update canonical documentation as each behavior lands. - Review the diff, run the stage's checks, and commit the coherent result under - the agent policy. Record any unresolved failure in the handoff rather than - marking that stage complete. Do not push or publish a release as part of this - plan. + Select applicable architecture, testing, documentation, and OSS policies. + Prefer the code knowledge graph for code discovery. Reuse unchanged policy + context; do not read unrelated policies merely to fill a checklist. +- Use `GOWORK=off` for Go commands. No local dependency `replace`, fork, + legacy-format parser, whole-profile replacement shim, section whitelist, + custom inheritance engine, or filename-priority merger belongs here. +- Keep upstream configuration types in the LLM integration boundary. Modules + retain transport-neutral requests, typed outputs, and asset ownership. The + root `assets` Go package remains content-only. +- Preserve prompt text/order, identities, schema contents, retry budgets, + sessions, reasoning overrides, warnings, scheduling, and artifact/subprocess + contracts. Deliberately update tests for accepted configuration-format, + recursive-overlay, and eager-validation changes, not unrelated expectations. +- Use real loading and offline injected clients or local HTTP fixtures. Add + narrowly owned behavioral tests for actual risks; reuse existing coverage. + Do not mirror the complete upstream suite, snapshot long errors/reports, or + introduce exact shared-prefix-length detector tests. +- Keep credentials and live inference out of default tests. Do not add new + permission enforcement, credential requirements, publication gates, or source + restrictions. Fix actual regressions rather than weakening coverage. +- Review the diff, validate, and commit each nonempty coherent stage with a + plain-English message under agent policy. No empty commits. Record actual + checks and remaining work; do not call the upgrade complete before Stage 15. + Do not push, tag, retire other roadmaps, or publish. -## Stage 1 — Upgrade The Dependency And Its Notices +### Bounded Migration Window -> Completion: complete. +The new format and removed APIs are incompatible with the old integration. +Stages 1–5 divide that migration into small prompts. Intermediate revisions +can have expected format/test-compilation failures. Record them precisely; +do not add dual-version machinery to keep every intermediate revision green. +Native application compilation must be restored by Stage 3, the LLM suite by +Stage 4, and the full default suite by Stage 5. Do not deploy intermediate +revisions. Later stages use focused passing checks before committing. -Goal: establish the released dependency baseline without redesigning the -configuration adapter. +## Settled Implementation Decisions -Inspect: +### Sources And Engine Ownership -- `go.mod`, `go.sum`, and `internal/core/config/load.go`. -- `docs/integrations/pkg-configkit.md` and the ConfigKit entry in - `docs/oss/attribution.md`. -- ConfigKit's pinned `docs/releases/v0.5.0.md`, `go.mod`, `COPYRIGHT`, and - `LICENSE`; consult the sibling checkout with `git show v0.5.0:`. +Build the same source stack for execution, preflight, and inspection: -Work: +1. Upstream catalogs and PromptKit-owned definitions, supplied by PromptKit. +2. One application underlay containing registered prompt and fallback-profile + inputs, each retaining its own filesystem context. +3. One operator underlay from the selected file or recursively selected + directory. Set `Input.Imports = true` on operator inputs only. Accept native + combined `profiles`, `backends`, and `prompts` documents. +4. A final programmatic underlay for `backends.local` when Notarius's + `local_backend` is configured. Use `BackendSource` with + `LocalBackend(endpoint, concurrencyLimit)` to preserve explicit zero. -1. Run `GOWORK=off go get gitea.maximumdirect.net/eric/ConfigKit@v0.5.0`, then - `GOWORK=off go mod tidy`. Review the selected dependency graph. Retain - PromptKit v0.11.2 and unrelated pins unless module resolution requires a - change; explain any such change in the handoff. -2. Search maintained configuration, fixtures, YAML tags, and documentation for - ordinary uses of the key or entry name `extends`. For example, use - `rg -n '\bextends\b' examples internal docs assets`. Classify any matches: - new inheritance instructions are valid; ordinary field/key uses collide - with the new reserved directive. Rename actual maintained collisions and - their consumers together, without an alias or bypass. Do not rename the - unrelated PromptKit `base_profile` setting. -3. Run focused existing tests. Address compile/API compatibility failures with - the smallest necessary adapter changes. Native inheritance needs no - registration or load option. -4. Update the integration document's pin and brief description to v0.5.0; - replace the v0.4.2 patch-only explanation with the new composition boundary. - Link to pinned upstream release/configuration documentation. -5. Update only ConfigKit's attribution version and exact source/notice links - to the target commit, preserving the verified copyright and - `LGPL-3.0-or-later` expression. Reuse the existing LGPL/GPL texts when - unchanged. Do not refresh unrelated component attribution or policies. +Leave `Sources.Main` nil. Use `FilesystemInputs` for embedded views, +`DirectoryInputs` for a directory, and +`configkit.Input{Source: configkit.File(path), Imports: true}` for one file. +Provide native filesystem resource context where necessary. File sources +derive their declaring directory; directory inputs retain the helper's root. +Do not make host files and embedded resources share an artificial root. +Native imports, root rules, and exact-key inheritance remain upstream behavior. -Acceptance criteria: +Sources in a group compose strictly; later groups overlay fields recursively. +Missing selected sources fail; empty selected directories contribute nothing. +No operator source means no operator group. Nil optional assets on the existing +profile inspector mean no application group; production supplies registered +assets. Preserve the client's required-assets check. Keep `WithSchemaFS` and +injected runtime options separate from definition sources. Register no catalog +backend manually. -- The declared and selected ConfigKit module is v0.5.0, without a workspace or - local `replace` dependency. -- Existing configuration and CLI tests pass; maintained ordinary `extends` - collisions, if any, have been resolved explicitly. -- Integration and attribution documents agree with the actual dependency and - imported source commit. The adapter still uses ordinary `Load`. +### CLI Inspection Contract -Validation: +Implement these commands, with flags before positional selectors as in the +current Go flag parser: ```sh -GOWORK=off go list -m gitea.maximumdirect.net/eric/ConfigKit -GOWORK=off go test ./internal/core/config ./internal/cli -git diff --check +notarius config effective --scope promptkit [--config path] [--config-overlay name] +notarius config explain --scope promptkit [--config path] [--config-overlay name] +notarius config profile [--config path] [--config-overlay name] ``` -Prompt size: one dependency upgrade, its notices, and demonstrated compatibility -adjustments. Leave new inheritance coverage to the following stages. +For effective/explain, omitted `--scope` or `--scope notarius` preserves the +current report and avoids constructing a PromptKit engine. Accept only +`notarius` and `promptkit`; explicit blank/unknown scope is a syntax error. +`config profile` inspects PromptKit only and needs no scope flag. Add no input, +pipeline selection, model override, or second source flag to these commands. +Load the selected Notarius configuration, use its normalized PromptKit sources +plus production assets, and inspect one engine without resolving a pipeline or +materializing references. -## Stage 2 — Prove Pipeline Composition And Runtime Conversion +Effective output is upstream redacted YAML; explanation output is upstream +human-readable history. Profile output is one Notarius-owned JSON object plus +newline with `profile_id`, `api_key_required`, and `effective_model_params`. +The last object uses the upstream target's lower-case field vocabulary: +`backend_id`, `endpoint`, `model`, `temperature`, `max_tokens`, `top_p`, +`timeout_seconds`, `service_tier`, `reasoning_effort`, `api_key_env`, and +`extra_params`. Include empty `backend_id` for endpoint-only profiles. Copy +fields into a local DTO; do not publish the upstream `ProfileInspection` Go +struct as the CLI contract. These are inspected settings, not provider-default +predictions. Zero sampling values alone do not distinguish omission from +explicit zero; effective/explanation reports supply presence context. -> Completion: complete. +Preserve exact profile IDs. Pointers use canonical JSON Pointer escaping; +an explicitly supplied empty pointer selects root. Use existing exit classes: +0 success, 2 malformed syntax/pointer/scope or wrong argument count, 1 load/ +inspection failure or unknown path/profile. Known historical-only paths are +valid. Check `Explain`'s found result before writing: the upstream writer emits +nothing for an unknown path. Stdout contains only the selected report; +diagnostics go to stderr. Writer errors can leave partial output; add no +transactional-output or byte-stability guarantee. -Goal: establish whole-pipeline reuse through the real configuration boundary. +Inspection never resolves credential values or contacts a provider. Report +credential names and actual upstream `APIKeyRequired` metadata without inferring +availability. Redact credential-shaped provider-parameter keys as upstream +configuration inspection does. Keep reporting projection separate from private +checkpoint hashing. Do not read unrelated environment values to sanitize +reports. Deliberately requested ordinary prompt/provider data remains visible; +add no automatic persistence, confirmation, or permission enforcement. -Inspect `load.go`, `document.go`, `loaded_config.go`, `pipeline_document.go`, -`document_test.go`, `pipeline_document_test.go`, and -`effective_config_contract_test.go` under `internal/core/config`. Reuse the -existing test catalog for runtime resolution. +### Captured Checkpoint Identity + +Compute one immutable identity at execution-engine construction, using public +captured inspection/definition APIs. Retain it on the client; return defensive +copies through `LLMCheckpointFingerprints`. Use name `promptkit_configuration` +and a versioned snapshot marker incorporating PromptKit and both catalog +versions. It supersedes separate profile-file/local-endpoint fingerprints; old +execution checkpoints naturally miss without migration/deletion. Source- +addressed chunk plans are unchanged. + +The private digest input contains: + +- The captured effective definition tree from `InspectConfiguration`. +- Every effective profile ID and its `InspectProfile` target and credential- + policy metadata, covering resolved backend defaults/provider parameters. +- Every effective prompt ID/version and `InspectPrompt.PromptHash`, covering + captured message content rather than just content-file paths. + +Obtain the first tree by writing captured effective YAML to a private buffer +and decoding that report into a generic map with the existing YAML v4 +dependency. This is inspection projection, not a second authoritative loader: +it performs no discovery, imports, inheritance, defaults, or validation. Use +its keys to enumerate profiles and prompt versions; sort entries and encode +the digest payload with `encoding/json`. Do not enumerate historical-only +definitions or hash history. Preserve null versus zero/omission in the tree. +Remove only `backends.local.concurrency_limit` and `.queue_capacity` from the +private tree to preserve that backend's established scheduling-only exclusion. +Other identity choices stay conservative; selected-profile optimization is +not required. + +The redacted effective report is insufficient alone: include copied public +profile targets with their actual JSON-compatible provider parameters in the +private payload. This covers execution-relevant values whose names the report +redacts. Never publish the payload, raw sources, paths, endpoint, parameter +values, or prompt bodies as checkpoint metadata. Only its digest is retained. +Public profile inspection can describe partial definitions; do not turn an +incomplete unused profile into a construction failure while fingerprinting. +Constructor validation remains PromptKit's. + +A new engine captures edits; an existing engine/fingerprint remains unchanged. +Preserve module/schema and CLI execution-override fingerprints, actual-used +profile provenance, and reusable-state eligibility. Imported definitions and +operator message edits participate through captured definitions/hashes, not a +separate filesystem scan. + +## Stage 1 — Migrate Embedded And Maintained Definition Assets + +Goal: convert data without rewriting prompt semantics. + +Inspect `assets/**/prompts/prompt.yaml`, +`assets/dnd/profiles/dnd-extraction.yaml`, +`examples/llm-profiles/dnd-extraction.yml`, their ordered manifests, and the +pinned upstream format reference. Work: -1. Add focused loading coverage in `internal/core/config/inheritance_test.go`. - Define a valid parent pipeline and a child with `extends: parent` plus a - pipeline-level override. Assert the inherited input, bindings, and ordered - steps survive conversion, while the child retains its own pipeline ID and - the parent keeps its own settings. - Keep the fixture small rather than copying the complete D&D example. -2. Resolve the resulting child with the existing catalog. Assert its selected - ID and overridden setting reach the resolved pipeline. Use the catalog's - registered module keys and avoid generated-reference requirements in this - small fixture; the full generated-reference handoff is covered in Stage 7. - Reuse existing resolution tests for unrelated defaults and digests. -3. Add one replacement case: the child supplies a complete different `steps` - list. Assert replacement and ordering, with no parent steps appended or - merged by ID. Both resulting pipelines must satisfy ordinary validation. -4. Add one native nested-mapping case using sibling artifact lanes in an - `artifacts` mapping: a child lane inherits a valid parent lane and overrides - a binding value. This proves that Notarius does not limit inheritance to - pipeline mappings. Other upstream-supported mapping shapes need no custom - permission mechanism. -5. In `docs/config.md`, add the canonical inheritance explanation: exact - immediate-sibling lookup, one parent, source composition before expansion, - recursive mapping combination, sequence/scalar/null replacement, normal - validation of parent and child, and all effective relationships being - resolved. State that step-sequence entries cannot extend each other. - Include a small illustrative pipeline snippet and the reserved `extends` - migration note. Distinguish configuration overlays and PromptKit profiles. +1. Wrap each prompt body under `prompts: : v1:`; remove embedded + `id`/`version`. Keep every other field and content path. +2. Wrap both profile files under `profiles: dnd-extraction:`. Preserve + `openrouter`, `openai/gpt-5.6-luna`, timeout 240, `service_tier: flex`, and + unset reasoning. Keep filenames/root embedding unchanged. +3. Review identities against manifests and schema registrations. Change no + Markdown fragment, schema, cache control, or message ordering. Leave test + fixture migration to Stages 4–5. -Acceptance criteria: +Acceptance: all production definitions are keyed; non-identity bodies preserve +meaning and inventories select the same files. Only intended data changes land. -- Loading and resolving a child yields an ordinary independently identified - pipeline with the expected inherited composition and explicit override. -- Replacement lists retain only the child list, in its configured order. -- Valid nested artifact-lane inheritance works through native ConfigKit - behavior without extra runtime types or application merging. -- Configuration version remains 5 and the user reference describes the - implemented syntax and reserved-key compatibility impact. +Validation: `git diff --check` and YAML-aware/manual comparison with prior +bodies. Legacy-loader failures are expected here, not runtime validation. -Validation: +Prompt size: one mechanical conversion, no constructor work. -```sh -GOWORK=off go test ./internal/core/config -git diff --check -``` +## Stage 2 — Upgrade Dependencies And Assemble Native Source Groups -Prompt size: small composition fixtures, runtime handoff, and one canonical -syntax section. Presence-sensitive cases belong to Stage 3. +Goal: establish v0.12 and shared native source construction. -## Stage 3 — Preserve Presence And Existing Domain Validation - -> Completion: complete. - -Goal: ensure inherited input remains explicit through Notarius normalization, -defaulting, and validator-chain conversion. - -Inspect `operational_document.go`, `pipeline_document.go`, -`document_normalizer.go`, `loaded_config.go`, and their existing presence tests. -Extend `inheritance_test.go` rather than adding a parallel fixture framework. +Inspect `go.mod`, `go.sum`, `asset_registry.go`, `promptkit_profiles.go`, +`promptkit_client.go`, and upstream source/backend configuration APIs. Work: -1. Cover inherited `structured_output_repair_attempts: 0`: it remains a - populated zero override after loading and resolution, rather than reverting - to a pipeline or prompt default. Also cover a child explicitly overriding a - nonzero parent budget with zero. -2. Cover an inherited supported `validators: []` on a chunk or extraction - binding. Its runtime override retains `Set=true` and an empty chain. Cover - a child replacing a nonempty parent chain with `[]`; do not concatenate it - or reinstall default validators because the child list is empty. -3. Cover an inherited false module-option value, such as - `output.options.evidence_context.enabled: false`, remaining false in runtime - configuration. Inspect the decoded document's input metadata to establish - explicit presence where needed, rather than relying on truthiness. -4. Cover inherited or child-supplied null for a field already rejected when - explicit, such as `structured_output_repair_attempts`. Require the existing - contextual load failure. Inheritance's support for null does not make that - field nullable. Reuse existing direct-input null coverage. -5. Use a small overlay fixture to demonstrate the sequencing: an overlay that - changes the parent before expansion changes the child's inherited value; - a child's own explicit replacement wins over the parent's value. Verify - `extends: null` cancellation using a child with its own valid input binding, - and verify omission of the directive in an overlay preserves the base - relationship. An explicit override record for the parent value must be - reflected in an inheriting child as well. -6. If any integration defect appears, correct Notarius's existing presence or - conversion handling, using ConfigKit's metadata. Add no application - inheritance evaluator. Refine `docs/config.md` to explain explicit - zero/false/empty/null and cancellation without promising universal validity. +1. Upgrade PromptKit to v0.12.0 and tidy. Keep ConfigKit v0.5.0 and unrelated + pins; remove obsolete `/v2` catalogs. Promote YAML v4 to a direct dependency + when used for inspection projection without upgrading its version needlessly. +2. Implement source assembly specified above inside `internal/framework/llm`. + Replace source options with filesystem inputs, and backend registration with + keyed `BackendSource`. A registry-facing helper can return configuration + sources plus schema options; migrate direct callers in following stages. +3. Enable imports on operator inputs only. Preserve optional selection, resource + context, exact IDs, group order, and local concurrency zero. Do not auto- + clear retained queue settings if a later limit makes them invalid; native + validation decides. +4. Update PromptKit/catalog attribution, verifying released notices and full + commits: PromptKit `4b8169da286917fde7875425bb32b799b12c6af3`, OpenRouter + `f17d208cb7ad1fb043cda2266cd3011d11b40aa0`, Rakestrawhome + `993443d88c451901f4c917fa00c204fd3b54d28d`. Reuse unchanged standard texts; + change no project grant or unrelated notice. -Acceptance criteria: +Acceptance: selected graph and notices identify released revisions; shared +source construction uses native APIs. Name remaining constructor/test compile +failures for Stages 3–5 rather than hiding them with wrappers. -- Inherited and direct replacements retain their existing explicit-value - semantics, including zero repair budgets and empty validator overrides. -- Existing null restrictions are neither relaxed nor expanded. -- Overlay/explicit-override composition precedes inheritance, and cancellation - behaves as described by the pinned upstream contract. +Validation: `GOWORK=off go list -m all`, `GOWORK=off go mod tidy -diff`, +`git diff --check`, and a native compilation attempt to locate removed APIs. -Validation: +Prompt size: dependency/notices and one source-construction boundary. -```sh -GOWORK=off go test ./internal/core/config -git diff --check -``` +## Stage 3 — Switch Runtime And Preflight To Shared Engine Configuration -Prompt size: presence and precedence at one package boundary. This stage does -not change defaults or add CLI flags for arbitrary configuration overrides. +Goal: restore application compilation and consistent sources. -## Stage 4 — Verify Declaration-Relative Paths Through Inheritance - -> Completion: complete. - -Goal: keep inherited resource paths anchored to the original declaration. - -Inspect `document_paths.go`, `document_paths_test.go`, the original-path map in -`pipeline_document.go`, and sequence mutation recording in -`document_normalizer.go`. Consult ConfigKit's public `InputInfo`, `Origin`, and -`Source` contracts at v0.5.0. +Inspect `NewPromptKitClient`, `NewPromptKitProfileInspector`, +`promptKitProfileSourceEngineOptions`, `PromptKitLocalBackendOption`, +`internal/cli/promptkit_profiles.go`, and production LLM composition. Work: -1. Extend real-file tests using `t.TempDir()`: import parent and child pipeline - definitions from different subdirectories beneath one configuration root. - Give the parent pipeline a relative external reference and one reference - inside an inherited ordered step. Assert both inherited paths resolve from - the parent's file; a direct child reference replacement resolves from the - child's file. Reference files may be minimal public fixture data. -2. Add an overlay replacement case where the parent reference is declared by - the overlay and subsequently inherited. Its base must be the overlay's - directory. A nested reference-mapping inheritance case must preserve its - original contributor when copied into a derived pipeline. -3. Combine one inherited path case with whitespace-normalized pipeline or - reference keys. The existing `originalPath` mechanism must still find the - input's origin. ConfigKit exact sibling matching happens before Notarius - trims names; do not pre-normalize the inheritance lookup. -4. Include a legitimate `../` reference, retaining the current host-path - behavior. Reuse existing coverage for built-in destination bases, explicit - CLI destination bases, absolute paths, and empty cache roots unless the - upgrade reveals a distinct regression. -5. Fix `documentPathBase` or related origin handling only if these tests expose - a failure. Query the surviving value's contributor, not the `extends` - control location or an arbitrary sibling. Keep the existing host-path - resolution model; do not replace it with resource opening through - `ResourceContext.FS`, which could introduce containment restrictions. -6. Clarify inherited declaring-file behavior in `docs/config.md`. Update the - loading/path explanation in `docs/internal/configuration.md` to reflect - expansion before decoding and source-aware recorded normalization. +1. Construct both engines with shared `Config.Sources`; remove obsolete + directory fields, source options, and `WithBackend`. Production preflight + includes application prompts, not just profiles, for partial overlays. +2. Retain timeout, HTTP client, transient retries, runtime injection options, + recorder, reasoning-pointer copies, and required client assets. Keep + `CompleteStructured` preparation/execution unchanged. +3. Retain safe errors and established `errors.Is`/`errors.As` behavior. Eager + constructor failures must not dump raw configuration/credentials into CLI + diagnostics. Do not classify by parsing upstream error wording. +4. Keep explicit-profile selection and credential-free inspection. Nil optional + inspector assets remain usable in tests; compose no modules in the framework. +5. Remove dead option helpers/fields, except old fingerprint inputs still used + until Stage 7. A new catalog marker is not a substitute for captured identity. -Acceptance criteria: +Acceptance: `cmd/notarius` builds; both construction paths use the same policy. +No upstream type leaks into domain/pipeline contracts. Report remaining test- +only compile failures for fixture migration. -- Imported, nested, and overlaid inherited paths use the file supplying the - surviving value; direct child replacements use their own declaring file. -- Normalized identifiers and inherited ordered-step references retain correct - bases without unrecorded sequence mutation failures. -- Existing path access and destination policies are preserved. No new path - containment, existence, or resource-format restriction is introduced. +Validation: native `GOWORK=off go build` of `./cmd/notarius` to an executable +beneath a `mktemp -d` directory outside the repository; `git diff --check`. -Validation: +Prompt size: constructor/error call sites only. -```sh -GOWORK=off go test ./internal/core/config -git diff --check -``` +## Stage 4 — Migrate LLM Fixtures And Restore The Adapter Suite -Prompt size: one path-resolution seam and focused real-file regressions. -Inspection rendering is checked separately in Stage 5. +Goal: exercise released configuration through existing adapter coverage. -## Stage 5 — Preserve Inspection, Derivation, And Ownership - -> Completion: complete. - -Goal: prove inherited configuration remains correctly inspectable after -Notarius's recorded normalization and runtime conversion. - -Inspect `loaded_config.go`, `loaded_config_test.go`, `document_normalizer.go`, -`redaction_test.go`, and the new inherited path fixtures. Review upstream -metadata/history APIs rather than inventing a new provenance format. +Inspect `promptkit_client_test.go`, `promptkit_observation_test.go`, +`asset_registry_test.go`, and helpers under `internal/framework/llm`. Work: -1. Through `LoadedConfig.WriteEffective`, check a derived pipeline's expanded - values and resolved reference paths agree with its runtime configuration. - Verify consumed `extends` directives are absent from the effective typed - configuration. Assert selected values/paths, not the full YAML document. -2. Through `WriteExplanation`, inspect one inherited scalar and one inherited - path that Notarius normalizes. Assert useful parent/source and inheritance - evidence remains available alongside the final normalization result. - Use structured upstream metadata within the configuration package for - precise provenance checks, and minimal stable fragments for rendered text. - Do not require a new Notarius renderer or exact diagnostic wording. -3. Add a synthetic credential-shaped option to a parent and inherit it into a - child. Verify effective and explanation views redact its value, including - inherited/displaced history where present. Use only fake secret strings and - the existing sensitivity predicate; add no new credential rules. -4. Extend the existing ownership test: mutating a child's runtime nested map - must not mutate the parent's runtime map or the frozen inspection snapshot. - Retain the `RuntimeConfig()` detached-copy behavior without a new cloning - mechanism unless the test demonstrates a conversion defect. -5. Update `docs/internal/configuration.md` to describe inherited explicit input, - retained derivation, normalization, and the detached runtime boundary. Repair - any affected stale loading terminology, such as calling a configuration - overlay a profile. Link to `docs/config.md` for syntax and field rules. +1. Convert literal files to keyed documents. Replace `WithProfiles` with + `ProfileSource` inputs and pointer fields preserving omission/explicitness. + Update engine setup to consume registry sources plus schema/runtime options. +2. Translate `base_profile` to `extends`. Deliberately adjust tests of whole- + profile replacement and selection-time failures only. Invalid unused final + entries fail construction; superseded contributions are not independently + domain-validated. +3. Preserve prepared execution, repairs, correction pairs, session/reasoning, + admission, transient errors, observations, cancellation, schemas, and safe + debug coverage. Fix owning adapter regressions instead of weakening tests. +4. Reuse small setup helpers; no legacy-format test converter. Fingerprint + fixtures become keyed now, with behavior changed later in Stage 7. -Acceptance criteria: +Acceptance: the full LLM suite compiles/passes offline, with no removed API +fixtures. Intentional semantic expectation changes are clear in the diff. -- Effective paths agree with runtime paths; explanations retain useful source - and transfer evidence after normalization. -- Existing redaction applies to inherited values and history. -- Parent, child, returned copies, and inspection snapshots have the established - ownership behavior. Upstream inspection types stay private to configuration. +Validation: `GOWORK=off go test ./internal/framework/llm`; `git diff --check`. -Validation: +Prompt size: mechanical adapter fixture migration and restoring its suite. -```sh -GOWORK=off go test ./internal/core/config -git diff --check -``` +## Stage 5 — Restore CLI And Registered-Module Fixture Coverage -Prompt size: configuration inspection and ownership, with focused tests and its -internal documentation. +Goal: close the initial format/API migration window. -## Stage 6 — Exercise CLI Selection And Failure Reporting - -> Completion: complete. - -Goal: make derived pipelines first-class through the existing commands and -preserve the normal load-error path for invalid inheritance. - -Inspect `internal/cli/configkit_commands_test.go`, `command_contract_test.go`, -and the configuration command/load helpers. Use the existing injected catalog -and fake collaborators; do not construct providers or make LLM calls. +Inspect `internal/cli/promptkit_profiles_test.go`, `production_contract_test.go`, +D&D `register/prompt_cache_test.go`, and direct PromptKit setup in chunk, +extract, normalize, and validator prompt asset tests. Discover remaining +legacy fixtures across tests, not just this initial inventory. Work: -1. Add a small valid parent/child fixture. Exercise `pipelines list` and - `config validate --pipeline child`; assert the child can be selected by its - own ID and listing remains sorted. Reuse existing command rendering tests - rather than duplicating every output mode. -2. Exercise `config effective` and `config explain` for that child to prove CLI - wiring reaches the safe upstream inspection views. Assert successful status - and relevant inherited evidence, not a whole-output snapshot. -3. Add representative invalid load cases for a missing parent, a cycle, and an - invalid directive type. Keep one invalid relationship in an unselected - pipeline to prove selecting a different valid pipeline cannot hide it. - Assert runtime-error status, no success output, and meaningful safe - configuration diagnostics. Reuse package-level diagnostics for more detailed - path checks; ConfigKit owns the full malformed-directive matrix. -4. Check exact-key behavior with a whitespace-bearing parent name: the matching - declaration works and existing identifier normalization follows expansion. - A mismatch should produce the upstream missing-parent failure. No automatic - trimming, aliases, or application-specific inheritance restrictions are - added. -5. Change production CLI code only if these tests expose a wiring defect. - `docs/cli.md` may gain a short link to configuration inheritance where useful, - but commands and flags remain the same. +1. Migrate direct construction and keyed fixtures mechanically through the + new registry boundary. Keep fake outputs and domain expectations intact. +2. Change CLI expectations only for eager definition/source failures; preserve + unknown-profile, credential-free validation, cancellation, and safe errors. + Do not introduce a required API-key placeholder. +3. Prepare registered prompts using representative existing tests. Fix real + content-context/schema/mount regressions without rewriting prompt text. +4. Update the integration reference's supported pin/API links and basic + constructor boundary. Full inspection/deployment docs follow later. -Acceptance criteria: +Acceptance: the full offline suite compiles/passes, registered assets prepare, +and the integration reference no longer describes removed APIs as current. -- Derived pipelines use the ordinary selection, listing, validation, and - inspection commands. -- Invalid relationships reach the existing load-error reporting path, even - when their entries are not selected for execution. -- Read-only command tests require neither credentials nor provider work. +Validation: `GOWORK=off go test ./internal/cli ./internal/modules/...`, then +`GOWORK=off go test ./...`; `git diff --check`. -Validation: +Prompt size: mechanical consumer fixture sweep, no new domain behavior. -```sh -GOWORK=off go test ./internal/cli ./internal/core/config -git diff --check -``` +## Stage 6 — Prove Native Operator Composition And Credential Policy -Prompt size: command-boundary behavior and representative error propagation. +Goal: verify accepted unified sources through the shared boundary. -## Stage 7 — Publish And Test The Development Pipeline Example - -> Completion: complete. - -Goal: give operators one complete, runnable demonstration without duplicating -the full pipeline. - -Inspect `examples/dnd-complete.config.yml`, -`examples/pipelines/dnd-session.yml`, `examples/overlays/development.yml`, -`internal/cli/example_contract_test.go`, and `maintainedExampleFiles` in -`internal/cli/production_contract_test.go`. +Inspect source assembly, profile/preflight tests, and adapter source tests. +Use small real files and real PromptKit loading. Work: -1. Add this sibling to `examples/pipelines/dnd-session.yml`: +1. Add a combined operator document with profiles, a custom backend, a catalog + backend field override, and a partial embedded-prompt overlay. Assert + preflight/runtime construct the same effective definitions. +2. Cover an import, a derived profile, omission retaining a field, explicit + zero/false, and null clearing an inherited tier/provider map. Cover `{}` + versus null only where consequential for the workflow. +3. Cover directory-group conflicts versus valid later-layer overrides, + selected-missing/empty sources, an invalid lower field repaired by an + overlay, and an invalid unused final entry. No raw-layer audit is added. +4. Cover explicit Notarius local endpoint/limit precedence and custom backend + admission through existing injected-client tests, not an upstream matrix. +5. Check optional versus required credential policy with synthetic names. + Inspection succeeds unset; preparation/execution follows native requirements. + Explicit profile environment sources differ from inherited backend sources. - ```yaml - dnd-session-development: - extends: dnd-session - structured_output_repair_attempts: 0 - ``` +Acceptance: native presence/composition works without a second loader, +whitelist, implicit credential requirement, or generation during preflight. - Keep it beneath `pipelines`, beside the complete parent. Explain with a short - comment that this development variant disables PromptKit structural repairs - while inheriting the steps and configured producer-stage retry budgets. - It uses the parent's existing `dnd-extraction` profile. -2. Update the complete example's expected pipeline IDs to include the child in - sorted order. Keep the minimal example and existing operational overlay. - Do not add a third standalone configuration or duplicate the parent's steps. -3. Extend maintained-example coverage to load, resolve, and materialize external - references for both complete-example pipelines. Compare the child to the - parent for step/lane composition and generated-reference bindings, and assert - the selected zero structural-repair setting reaches eligible resolved - bindings. Do not assert equal pipeline digests: their IDs/settings differ. -4. Update `TestMaintainedExamplesValidateEffectiveProfilesOffline` to validate - every expected pipeline in each maintained example, including the new child, - with credentials absent. Retain the existing two-root-example inventory. -5. Update `docs/config.md`'s maintained-example guidance to show selection of the - variant and explain that operators may instead override `llm_profile` when - supplying another profile. Link to the inherited fragment. Add only a short - configuration link in `docs/consumers/dnd-pipeline.md` if useful; keep its - complete parent workflow and artifact instructions intact. +Validation: `GOWORK=off go test ./internal/framework/llm ./internal/cli`; +`git diff --check`. -Acceptance criteria: +Prompt size: operator-source fixtures, not identity or content lifecycle. -- The existing complete root imports both valid pipelines, and the derived - pipeline contains only the relationship and its intentional override. -- Both variants resolve and validate offline using the maintained profile, - external references, generated bindings, and full module catalog. -- Maintained examples and navigation accurately explain the variant without - confusing it with the operational overlay or PromptKit profile inheritance. +## Stage 7 — Compute Immutable Captured Configuration Identity -Validation: +Goal: replace live-file fingerprinting with the settled snapshot algorithm. -```sh -GOWORK=off go test ./internal/cli -run 'TestMaintained' -GOWORK=off go test ./internal/core/config ./internal/cli -git diff --check -``` - -Prompt size: one example fragment, its existing test inventory, and focused -operator guidance. No full live extraction run is needed. - -## Stage 8 — Consolidate Documentation And Verify The Complete Upgrade - -> Completion: complete. - -Goal: finish with an internally consistent, validated upgrade ready for review. - -Inspect all changed files, `docs/config.md`, -`docs/internal/configuration.md`, `docs/integrations/pkg-configkit.md`, -`docs/oss/attribution.md`, and affected CLI/consumer navigation. Compare against -the feature roadmap's acceptance criteria. +Inspect `promptkit_profile_fingerprint.go`, client construction/fingerprint +methods, public inspection APIs, and module/schema identity contributions. Work: -1. Confirm canonical ownership: configuration defines syntax/precedence/path - rules; internals explain the adapter; integration documentation identifies - the supported upstream contract; attribution records the imported version - and notices. Remove duplicate definitions introduced during earlier stages. -2. Check the documentation covers the reserved key in every input mapping, - exact sibling naming, normal validation of all definitions, replacement of - step/validator sequences, source-relative inherited paths, explicit values, - and cancellation. Do not describe deferred `LoadLayered`, filesystem source, - mapping source, or underlay workflows as available Notarius features. -3. Search for stale ConfigKit v0.4.2/current-pin claims in active documentation - and dependency files, ordinary reserved-key collisions, and confusing profile - terminology. Leave historical releases and archived roadmaps intact. Verify - relative document links locally and pinned external links where accessible; - no new documentation-checking tool or recurring network gate is required. -4. Run the full offline default suite, vet, and native build. Build to a - `mktemp -d` destination so no binary is left in the repository. Run - `GOWORK=off go mod tidy -diff`; an unexpected diff must be resolved and - reviewed rather than accepted silently. -5. Review the final implementation for unintended restrictions or guarantees: - no new schema version, inheritance whitelist, abstract-template exemption, - custom list merge, host-path restriction, configuration source tier, - additional CLI knobs, or upstream types leaking into runtime contracts. -6. Report the implemented behavior, successful checks, and any concrete gaps. - Keep roadmap retirement and release publication for a later request. +1. Implement the private captured projection and digest specified above using + the just-constructed engine, never a second load or current file scan. +2. Inspect all effective profile IDs, including valid partial definitions. + Hash presence-aware definitions plus resolved targets and captured prompt + hashes; redacted reports or zero-valued targets alone are insufficient. +3. Store only the resulting fingerprint slice. Delete old file/directory scans, + catalog-only marker, local-target fingerprint, and obsolete client fields. +4. Preserve local scheduling-only exclusion and module/schema/override identity. + Change no chunk-plan key or resume eligibility. Update focused fingerprint + tests for the new boundary. -Acceptance criteria: +Acceptance: immutable `promptkit_configuration` reflects the captured engine +and pinned graph. The fingerprint API performs no later read/reload. No raw +payload is persisted, returned, or logged. -- Every required outcome in `configkit.md` is implemented and covered at the - appropriate boundary, with no unexplained scope expansion. -- Maintained examples and canonical documents agree with the selected module - and observed loading behavior. Dependency metadata is tidy. -- Full offline tests, vet, build, and relevant diff/link checks pass. Any - unavailable optional external-link verification is reported accurately. +Validation: `GOWORK=off go test ./internal/framework/llm`; private projection/ +propagation review; `git diff --check`. + +Prompt size: one private snapshot/digest mechanism; broader reuse tests follow. + +## Stage 8 — Protect Captured Identity And Resume Behavior + +Goal: prove identity correctness across edits and checkpoint reuse. + +Inspect adapter identity tests, CLI fingerprint handoff, and existing recorded- +checkpoint/resume integration fixtures. + +Work: + +1. Construct A from operator definitions/imports/message files. Edit them; + A's captured content and fingerprint remain unchanged. B captures semantic + definition/message changes and receives a different identity. +2. Cover model, endpoint, credential-policy, inherited/imported changes, null + versus zero, and provider parameters whose keys are report-redacted. Cover + local concurrency-only identity separately from local endpoint changes. +3. Check detached fingerprint ownership and absence of raw source/settings/ + bodies in values or ordinary metadata. Compare behavior, not fixed hashes. +4. Extend one recorded-checkpoint workflow: changed captured config prevents + stale execution reuse; same-snapshot reuse, override identity, and source- + only chunk-plan reuse remain intact. + +Acceptance: reusable state follows the executing engine, not edited files; +local scheduling-only changes do not accidentally change the chosen identity. + +Validation: `GOWORK=off go test ./internal/framework/llm ./internal/cli ./internal/modules/integration`; +`git diff --check`. + +Prompt size: snapshot/resume regressions, no checkpoint redesign. + +## Stage 9 — Verify Source-Relative Content And Capture Lifetime + +Goal: protect resource contexts and static template/content capture. + +Inspect manifests, source construction, and existing prepared/prompt asset +tests; consult upstream origin/frozen-rendering contracts for timing. + +Work: + +1. Use directory-distinguishing files to prove an imported/inherited message + resolves from its declaring source. Add a later prompt replacement with + replacement-file-relative content and a partial overlay over embedded base. +2. Existing engines retain captured content/templates; a new engine sees edits. + Bad static syntax/missing message files fail construction, while missing + request variables remain preparation failures. +3. Keep schema preparation timing and inline request inputs unchanged. Preserve + representative rendered bytes/order/cache metadata. Fix only real context + or mounting defects; do not expand host-root policy. + +Acceptance: no source is rebased to the caller/CWD; captured definitions remain +distinct from schemas and request artifacts. + +Validation: `GOWORK=off go test ./internal/framework/llm ./internal/modules/...`; +`git diff --check`. + +Prompt size: origin/lifecycle cases, not new execution policy. + +## Stage 10 — Expose A Provider-Neutral Inspection Facade + +Goal: support CLI reports without exposing upstream dependency types. + +Inspect profile result/error types, shared source construction, and public +PromptKit inspection APIs. + +Work: + +1. Add adapter string/writer operations for effective/explanation reports. + Parse canonical pointers privately; preserve writer causes, invalid-versus- + unknown distinctions, and known historical paths. Keep upstream values private. +2. Extend the neutral profile result with copied fields for the settled JSON + DTO. Copy actual target, credential name, and `APIKeyRequired` metadata; do + not infer environment availability or provider defaults. Existing preflight + consumers retain their needed metadata. +3. Redact credential-shaped keys recursively in the reporting copy of provider + parameters. Reuse a suitable helper without reversing dependencies, or add + a small local projection using upstream's case-insensitive vocabulary: + `api_key`, `apikey`, `authorization`, `credential`, `credentials`, + `password`, `secret`, `token`, `access_token`. Do not reject those keys, + redact unrelated content, or mutate the private digest projection. +4. Test detached ownership, safe errors, parameter redaction, escaped pointers, + absent selectors, and unset synthetic credential names. + +Acceptance: all three views are available without leaked types, credential +resolution, provider calls, automatic dumps, or mutation of identity. + +Validation: `GOWORK=off go test ./internal/framework/llm`; `git diff --check`. + +Prompt size: one facade/DTO, not CLI parsing. + +## Stage 11 — Add Scoped Effective And Explanation Commands + +Goal: expose captured configuration/history through explicit PromptKit scope. + +Inspect `internal/cli/configkit_commands.go`, `runConfig`, usage text, +normalized composition options, and configuration command tests. + +Work: + +1. Add `--scope` with settled values/default; keep the ordinary report branch + unchanged. Only PromptKit scope constructs an inspector using selected + normalized config and registered assets. +2. Route pointer/history and writer failures through the facade and existing + exit classes. Allow empty root and escaped IDs. Do not invoke the LLM client + factory, resolve a pipeline, prepare requests, or materialize references. +3. Add focused CLI coverage for default report preservation, scopes, malformed/ + unknown/historical selectors, import/overlay origins, redaction, and writer + failure. Use zero-call counters at external boundaries. +4. Update help and `docs/cli.md` syntax/output behavior. State that construction + validates/captures definitions and requested reports can contain ordinary + inline prompt/provider data. + +Acceptance: current invocations retain meaning; explicit scope produces only +its requested report without transcript input, credentials, or provider work. + +Validation: `GOWORK=off go test ./internal/cli`; `git diff --check`. + +Prompt size: two scoped branches, not resolved-profile parsing. + +## Stage 12 — Add Resolved Profile Inspection To The CLI + +Goal: report backend-completed profile settings explicitly. + +Inspect command dispatch, the profile facade, preflight, and JSON/error tests; +reuse Stage 11's inspector construction. + +Work: + +1. Add `config profile`, settled flags, and exactly one nonblank literal ID. + Emit the neutral DTO as one JSON object/newline, not the upstream Go struct. +2. Preserve syntax/runtime exit distinctions and safe missing-profile/config/ + writer failures. Inspect no credential availability and apply no run override. +3. Cover inheritance/backend defaults, endpoint-only identity, null suppression, + required unset credentials, credential-shaped params, and unknown profiles. + Assert fields rather than whole JSON snapshots or inferred provider defaults. +4. Update help and `docs/cli.md`: JSON shape, request/default distinction, + zero/presence caveat, failures, and links to effective/explanation. + +Acceptance: detached redacted profile inspection needs no transcript or model +call; preflight/run behavior remains unchanged. + +Validation: `GOWORK=off go test ./internal/cli ./internal/framework/llm`; +`git diff --check`. + +Prompt size: one focused subcommand and its contract. + +## Stage 13 — Maintain Examples And Operator Guidance + +Goal: make native features understandable and deployable. + +Inspect the two maintained config examples, imported pipeline/development +variant, deployment profile file, example tests, config and operations docs. + +Work: + +1. Keep two top-level examples and normal default execution policy. Add a + small derived development profile to the existing deployment profile file, + demonstrating `extends` and a supported override without an unavailable + model. Do not select it for the normal complete pipeline or duplicate steps. +2. Explain unified sources, recursion/exact keys, imports, strict directories, + source roots, and Notarius overlays versus PromptKit layers. Use small + snippets for custom/catalog backends, local null clearing, prompt overlays, + and file-root imports. Add no third full pipeline/example framework. +3. Replace old whole-replacement, `base_profile`, embedded-ID, unsupported file + `api_key_required`, and stale format claims with v0.12 behavior. Include + external-file migration guidance, not aliases or a compatibility parser. +4. Add a concise operations workflow using three inspection views. Explain + engine reconstruction, credential names/availability, zero/presence, report + versus prepared/debug data, and operator-owned report handling. +5. Update existing example tests for the additional profile and actual native + behavior. Validate minimal, complete, and inherited development pipelines + offline with no required credentials or file-length assertions. + +Acceptance: valid examples and accurate canonical config/operations guidance, +linked to CLI/upstream contracts rather than duplicating their manuals. + +Validation: `GOWORK=off go test ./internal/core/config ./internal/cli`; +`git diff --check`; verify local/pinned links. + +Prompt size: maintained examples and two operator documents. + +## Stage 14 — Finish Developer Contracts And Record The Decision + +Goal: document implemented ownership, capture, identity, and inspection. + +Inspect `docs/internal/llm.md`, `docs/internal/cli.md`, +`docs/integrations/pkg-promptkit.md`, ADR-0010/0018, and final implementation. + +Work: + +1. Update LLM internals for shared groups, final-value validation, capture, + snapshot identity, schema lifecycle, and neutral reports. Remove live-file + fingerprint claims. +2. Update CLI internals for scoped/profile reports, source parity, and credential- + free construction. Keep exact syntax/defaults in public references. +3. Finish pinned v0.12 and `/v3` integration guidance. Preserve prepared + execution, observations, corrections, retry separation, omission, and resource + timing. Explain final-only validation, not superseded-source audits; verify + license links. +4. Add `docs/adr/0019-adopt-native-promptkit-configuration.md`: native overlays, + unified sources/ownership, capture, compatibility, and alternatives. Add a + concise status/supersession link to ADR-0010 for only its whole-profile + replacement clause; preserve historical rationale and workload ownership. + ADR-0018's Notarius loader decision remains in force. +5. Repair other genuinely affected links/claims. Do not rewrite policy + provenance, historical releases, or unrelated artifact contracts. + +Acceptance: actual final behavior has canonical owners and a durable decision +record without erasing history or elevating incidental choices into policy. + +Validation: documentation/link review, scoped stale-term search, and +`git diff --check`. Reuse code/example checks when unchanged; no new scanner +or paid inference is required for prose. + +Prompt size: focused internal/integration references and one short ADR. + +## Stage 15 — Verify Completeness And Remove Only Obsolete Machinery + +Goal: prove the entire target state, not just a green dependency build. + +Work: + +1. Compare code/tests/examples/docs against every target section and settled + decision. Address small finishing defects. Report significant gaps rather + than silently narrowing source, identity, or reporting acceptance. +2. Find genuinely obsolete APIs, formats, option/fingerprint helpers, and + contradictory current documentation. Distinguish historical migration text + and normal application identifiers from obsolete PromptKit definitions. + Remove dead machinery, not retained behavioral tests. Review restrictions/ + guarantees for accidental strengthening. +3. Run full offline tests, vet, tidy diff, and native temporary build. Verify + selected modules. With provider credential variables unset, smoke-test + help, all three new reports, and maintained complete/development pipeline + validation. No real run or inference is needed. +4. Check report source parity/redaction, captured identity/reuse and origin + coverage, attribution/source links, and local navigation. Optional live + evaluation is follow-up evidence, not a new release gate. +5. Report completion and actual validation. Leave release selection/publication + and completed-roadmap retirement to a separate request. No file change means + no empty commit. + +Acceptance: all roadmap capabilities are implemented/demonstrated, deterministic +checks pass, no removed configuration-source API remains in implementation, +and no unrelated contract/restriction was introduced. Validation: ```sh GOWORK=off go test ./... GOWORK=off go vet ./... -build_dir=$(mktemp -d) -GOWORK=off go build -o "$build_dir/notarius" ./cmd/notarius GOWORK=off go mod tidy -diff +GOWORK=off go list -m gitea.maximumdirect.net/eric/ConfigKit gitea.maximumdirect.net/eric/promptkit gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v3 gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v3 git diff --check -git status --short ``` -These are development checks for this upgrade, not additional permanent release -gates. Do not repeat successful checks for unchanged content solely to satisfy -another handoff step; rerun the affected checks after any correction. +Build beneath a `mktemp -d` directory and use that executable for smoke tests; +keep temporary products outside the repository. These are migration checks, +not additions to release policy or production-key requirements. -Prompt size: final review, small documentation consolidation, and aggregate -verification. A newly discovered substantial defect must be reported with its -evidence and required follow-up rather than folded into an unrelated refactor. +Prompt size: final evidence review/small cleanup, no new feature. ## Open Questions -None at this baseline. The dependency target, native inheritance semantics, -path policy, example override, documentation owners, and deferred features are -specified. Whether an adapter needs a small correction is determined by the -integration tests above, rather than a new product-policy decision. +None. Native overlays, unified sources/imports, and operator inspection are +accepted. Command syntax, report shapes, source precedence, captured identity, +and migration boundaries are specified above. Raise any new upstream API +incompatibility with evidence; do not silently drop a feature or add a shim. diff --git a/docs/roadmap/promptkit.md b/docs/roadmap/promptkit.md index b76fd6f6..74fe6e47 100644 --- a/docs/roadmap/promptkit.md +++ b/docs/roadmap/promptkit.md @@ -10,8 +10,8 @@ or changing Notarius's domain extraction and pipeline acceptance policies. This is a feature roadmap, not an execution sequence. The operator-source and native-overlay decisions were accepted on 2026-10-04 and are incorporated below. -A separate implementation plan will define the execution sequence. Release -preparation and publication are separate work. +The [implementation plan](implementation.md) owns the ordered work and +verification sequence. Release preparation and publication are separate work. ## Reviewed Baseline