From e1ce526114592c1c5d66db0ff2aaae537a6be841 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 3 Oct 2026 17:26:28 +0000 Subject: [PATCH] Plan ConfigKit inheritance implementation --- docs/roadmap/implementation.md | 594 ++++++++++++++++++--------------- 1 file changed, 331 insertions(+), 263 deletions(-) diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 3b3e4db..2a03d3f 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,303 +1,371 @@ -# Policy Alignment Implementation Plan +# ConfigKit v0.5.0 Implementation Plan -## Status, Scope, And Authority +## Status, Baseline, And Authority -Planned on 2026-09-28 against Scriptorium -`8452b54809b99425a97940da485daaa48c77aeb8`. All five stages are complete. -The ordered stages below retain the implementation instructions and completion -evidence for this delivered work set. +Planned on 2026-10-03 against Scriptorium +`8b6c12f912b28ac00016f047f9846798a5de95d9`. All five stages are pending. +The [feature roadmap](configkit.md) owns scope, intent, and the target state. +This plan gives a Luna coding agent concrete implementation steps and acceptance +checks. Implement Stage 1 through Stage 5 in order, one stage per work unit. -The [feature roadmap](policy.md) owns the agreed end state, scope, and reasons -for local exceptions. This plan owns execution steps and acceptance checks. -This is documentation work, not application, dependency, or release-tool work. +The baseline selects ConfigKit v0.4.2 and Promptkit v0.11.2. The target is the +published ConfigKit v0.5.0 at +`dc09959cca4e105f49ec316c6d4ba585bd2340bd`. +Use its [configuration contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/config.md) +and [consumer guide](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/consumers/README.md). +Inspect this exact revision through the downloaded module, a verified checkout, +or pinned upstream links. Do not adopt unpublished sibling changes. -The selected public upstream revision is -`d84a38ebab26f048cafbe59a2246700c35d29843`. -Start with its -[adoption guide](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md). -Retrieve source files at this revision, not whatever main contains when a -stage runs. A verified checkout of this exact revision is acceptable; no -sibling checkout is a prerequisite. If source retrieval fails, report that -blocker rather than inventing source content or provenance. +The previous content of this filename is the completed policy-alignment plan: +`git show 8b6c12f912b28ac00016f047f9846798a5de95d9:docs/roadmap/implementation.md`. +Do not rerun it. The initial ConfigKit cutover is already delivered; this work +adds upstream inheritance to the existing integration. -Read the current local agent policy and developer orientation before work, -then policies governing the stage. Once Stage 2 lands, use the new selective -reading guide. Reuse unchanged policy text already available in context. +## Execution Rules And Fixed Decisions -## Historical Implementation Records +Before each stage, inspect status and relevant diffs, read +`docs/development.md` and `docs/policy/agents.md`, and select other policies +using the development guide. Architecture, testing, and OSS govern dependency +and integration work; documentation governs examples and prose; release governs +compatibility and the release handoff. Reuse unchanged instructions already in +context. Prefer the repository's code graph for symbol discovery. -This filename previously held completed application plans. Preserve their -records through Git rather than carrying their implementation steps forward: +Keep the following agreed choices throughout: -- ConfigKit adoption and release handoff: - `git show 8452b54809b99425a97940da485daaa48c77aeb8:docs/roadmap/implementation.md`. -- Earlier PromptKit plans are referenced within that historical document. +- Retain ordinary `configkit.Load`, the current `Document` schema and + definition callbacks, and the shared execution/inspection result. ConfigKit + already expands inheritance before decoding. Do not add an `Extends` Go + field, application merge pass, opt-in, keyword escape, or compatibility loader. +- Keep current discovery, explicit imports, selected overlay, CLI override + presence, working-directory-relative application paths, and normalization. + Backend conversion still uses resolved values and sorted IDs. +- A parent backend remains an ordinary configured backend. It is registered + and validated with the child. Inheritance copies settings; it does not create + a shared capacity pool across distinct backend IDs or abstract templates. + Existing sharing of each backend's capacity across server requests remains. +- Keep `api_key_env` as a visible environment-name string passed to Promptkit. + Do not resolve it through ConfigKit or mark it secret. Effective and historical + ordinary `extra_params` values stay visible under the maintainer's policy. + Existing raw-key restrictions and credential ownership remain. +- ConfigKit reserves `extends` across application input mappings, including + dynamic provider data and mapping names. Accept that upstream compatibility + change. It does not apply to separately parsed Promptkit definitions or HTTP + payloads. +- Underlays, native filesystem/mapping source APIs, source-relative resources, + schema versioning, secret bootstrap, and hot reload are deferred. Do not add + flags, HTTP configuration routes, source DTO fields, or APIs for them here. +- Keep Promptkit and other dependency versions, public HTTP behavior, accepted + ADR decisions, policy template baselines, release automation, and published + release notes unchanged except for the selected ConfigKit integration. + A concrete upstream defect should be reported with a reproducer; do not copy + its implementation into Scriptorium or assume a different unreleased target. -Those stages must not be rerun. Existing release notes, including -[the v0.14.0 note](../releases/v0.14.0.md), record prior delivered features. -Do not infer a new release obligation from an old prospective handoff. -The new policy and licensing changes still need a concise summary in the next -release, including the already-selected GPL-3.0-or-later application grant and -the separately licensed policy material. Version selection and publication -are not part of this plan. +Production code changes are expected only if validation exposes a real +integration defect. Prefer the existing implementation when it already works. +Use small behavioral tests with real ConfigKit and Promptkit collaborators, +temporary files, and existing helpers. Do not add parser/inheritance matrices, +full prose snapshots, live provider calls, or test frameworks. -## Common Execution Rules +Each stage must leave a coherent, reviewable state. Record concise completion +evidence under that stage and commit its files with a short plain-English +message under the agent policy. Preserve unrelated user changes. Do not push, +tag, publish, or invoke the release command as part of this implementation. -1. Inspect status and relevant diffs before each stage. Preserve unrelated - changes; do not silently include them in the stage commit. -2. Read the selected upstream files completely before adopting them. Compare - directly with local files; do not reconstruct historical adoption baselines. -3. Start from upstream text, remove the complete Base Policy Template section, - and apply only the customizations selected below. Preserve shared language - verbatim, including its meaning and strength. Do not retain old paraphrases - merely because they are familiar or add prohibitions for hypothetical risks. -4. For each policy adopted in that stage, set the target Base Policy Version, - the actual adoption date, and an Upstream Source link: - `https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/FILE.md`. - Substitute the actual filename. Do not stamp a source on a policy before - incorporating it. Intermediate commits may legitimately have mixed versions. -5. Update the single policy-attribution entry as its copied/adapted scope grows. - Do not claim later-stage material has already been adopted. -6. Validate affected text, links, notices, and diff; record concise completion - evidence under the completed stage here. Commit each coherent stage with a - short plain-English message under the agent policy. Do not push or publish. +For stages changing modules, Go code, or tests, run the development baseline +before committing: `go test ./...`, `go test -race ./...`, +`go vet ./...`, and `go build ./cmd/scriptorium`. Also run each stage's focused +checks and `git diff --check`; format changed Go files with `gofmt`. +Reuse successful checks for unchanged content. Documentation-only changes need +affected examples and link checks, not unrelated new runtime tests. -Do not change Go code, module pins, tests, release scripts, CI, accepted ADR -decisions, or published release notes. Do not introduce recurring sync checks, -license approval rounds, release gates, or blanket source headers. Preserve -the application grant and dependency terms. Standard license text must remain -verbatim even if a generic whitespace check dislikes publisher formatting. +## Stage 1: Adopt The Published Dependency And Its Compatibility Notice -## Stage 1: Adopt OSS Rules And Establish Licensing Notices +Status: Pending. -**Status: Complete.** OSS language was compared with the pinned source after -the approved metadata and example changes. The CC-BY-SA text matches its pinned -source byte-for-byte; attribution and navigation were checked against the -specified format and local paths. +Files: `go.mod`, `go.sum`, `docs/oss/attribution.md`, +`docs/config.md`, `docs/development.md`, and +`docs/policy/architecture.md`. -Files: `docs/policy/oss.md`, `docs/oss/attribution.md`, -`docs/oss/licenses/CC-BY-SA-4.0.txt`, `COPYRIGHT`, `README.md`, -and the footer portion of `docs/release.md`. +1. Review the current `internal/config.Load`, `documentDefinition`, + `resolveDocument`, `validateDocument`, and `Settings`, plus CLI + `loadApplicationSettings` and `newEngine`. Confirm that the existing + ConfigKit lifecycle owns input assembly and no second merge is introduced. +2. Select only the published ConfigKit release: -1. Read upstream OSS v1.8, COPYRIGHT, the canonical - `examples/licensing/policy-attribution.md`, and referenced licensing - examples at their pinned URLs. Adopt OSS v1.8 with metadata as above. - Remove template-only content; retain upstream common wording and its - existing commit-pinned example links. Customize the README example to - Scriptorium and GPL v3 or later. No other OSS exception is selected. -2. Copy the complete CC-BY-SA-4.0 reference text from the selected revision - into the named local license file and compare it byte-for-byte with that - source. Do not copy the rest of the reference collection or add CC0 merely - because example formatting is used. -3. Reformat the attribution document to the exact v1.8 House Format. Use - `# Open Source Attribution Notices`, immediately followed by entries. - Place Standard Repository Policies first, using the canonical entry, - with its COPYRIGHT, LICENSE, and Source URLs pinned to the selected full - commit. In this stage identify `docs/policy/oss.md` as the newly adapted - material. Do not research or make claims about prior adoption provenance. -4. Preserve the eight existing dependency entries and their imported commits, - copyright wording, SPDX expressions, and required notices. Optional module - identification paragraphs may retain versions currently in source labels. - Remove the introductory prose, missing-copyright filler, and editorial - YAML license explanations. Preserve the factual MIT AND Apache-2.0 - expressions. Use actual upstream filename labels, local license names, - terminal periods, and the exact `[Source](COMMIT_URL).` source form. - Do not upgrade dependencies or relabel their grants. -5. Add a scoped paragraph to COPYRIGHT stating that material adapted from - Standard Repository Policies remains CC-BY-SA-4.0, with - `docs/oss/attribution.md` identifying affected material and links. This - covers the scoped material as stages add it; it does not relicense unrelated - application code or documentation. Keep the existing GPL grant and LICENSE. -6. Correct the README ending to link GPL v3 or later to COPYRIGHT and keep - the attribution link. Change the release-procedure footer to absolute - immutable-tag COPYRIGHT, LICENSE, and ATTRIBUTION links, updating the - references to the number of URLs. Change no publication commands. - Do not retrofit published notes or create a release note/version now. + ```sh + go get gitea.maximumdirect.net/eric/ConfigKit@v0.5.0 + go mod tidy + ``` -Acceptance: OSS text matches the pinned source except the approved project -example and metadata; attribution follows the prescribed format; the added -license text is faithful; project and dependency grants remain unchanged. -Check affected local paths and upstream notice/example destinations. Missing -copyright fields are omitted, not explained with agent-authored commentary. + Review module and checksum changes. The YAML dependency remains + `go.yaml.in/yaml/v4 v4.0.0-rc.6`; keep Promptkit v0.11.2 and the selected + catalogs. Investigate incidental changes rather than silently including them. + Do not commit a workspace, replacement, or vendored dependency. +3. Inspect the selected upstream COPYRIGHT, LICENSE, and notices. Update only + ConfigKit's attribution entry to v0.5.0 and the full target commit in its + COPYRIGHT, LICENSE, and Source links. Retain its copyright statement, + LGPL-3.0-or-later expression, local LGPL/GPL links, and House Format. + Existing license texts remain applicable; no new policy-document copying + or attribution entry is needed merely to use the library. +4. Update the current ConfigKit version references in development, architecture, + and configuration documentation. Preserve policy Base Policy Version and + Upstream Source; update architecture's Last Updated date when editing its + local dependency statement. Do not revise shared policy language. +5. In `docs/config.md`, add a concise application inheritance subsection + linked to the pinned upstream contract. Explain `extends: sibling`, + inherited settings, explicit replacements, post-overlay/override expansion, + and `extends: null` cancellation. State that parents remain configured + backends, and the keyword applies beyond just the `backends` collection. + Include the reserved-key compatibility notice now so this dependency commit + does not leave accepted syntax incorrectly documented. +6. Explain that quoting does not escape `extends`. Distinguish renameable + application names from literal provider parameters whose names cannot be + changed without provider support. The current target has no escape or opt-out; + a concrete need should be handled upstream. Keep the Promptkit definition + boundary explicit. Stage 4 will add the example and remaining presentation. -## Stage 2: Adopt Provenance, Agent Guidance, And Documentation Ownership +Validation: run the development baseline, review module/version/notice changes, +and check affected documentation links. Existing tests are expected to pass; +update an expectation only when it encodes the selected upstream change. -**Status: Complete.** The three policies carry the selected versions, source -links, and local adoption date; shared text and the orientation template were -compared with the pinned source. The seven-link reading guide and local links -were checked, and attribution names only the incorporated material. +Acceptance: ConfigKit v0.5.0 is selected, attribution identifies its actual +revision, and current documentation acknowledges the newly reserved syntax. +The application retains the existing single loading pipeline. -Files: new `docs/policy/meta.md`, `docs/policy/agents.md`, -`docs/policy/documentation.md`, root `AGENTS.md`, -`docs/development.md`, and the policy attribution entry. +## Stage 2: Protect Application Loading, Presence, And Runtime Conversion -1. Adopt meta v1.0 and agents v1.3 verbatim after template-section removal - and metadata substitution. Keep meta's live project and main-branch - adoption-guide discovery URLs; its own Upstream Source is commit-pinned. - Retain local relative links to developer guidance and attribution. -2. Adopt documentation v1.11. Customize only applicable topic-map rows: - configuration remains application configuration, framework formats belong - to PromptKit, consumers cover executable use and migration rather than a - Scriptorium public Go API, and integrations cover Scriptorium-owned - executable/process contracts. Keep upstream rows for meta, COPYRIGHT, - LICENSE, and attribution. Remove instructional “if applicable” qualifiers - from selected rows. Preserve the rest of the shared language. -3. Use the upstream ADR lifecycle and examples guidance without retaining - generic local expansions. This does not edit accepted ADRs or change their - decisions. Metadata maintenance follows the adoption guide through meta, - rather than a duplicate custom rule set. -4. Adapt upstream `agents/AGENTS.md` into root AGENTS.md. Preserve any actual - repository-specific code-discovery instructions; do not copy environment- - injected instructions into the file just because they appeared in a session. - Do not copy upstream's own root AGENTS.md. -5. Add the adoption guide's Policy Reading Guide table and selection bullets - verbatim to the developer guide with the seven local links. Replace its - unconditional architecture-reading instruction and duplicated policy-reading - prose with this selective guide. Retain project orientation, task-specific - contract rows, dependency boundaries, and baseline validation commands. - Avoid maintaining competing policy trigger rules in multiple places. -6. Expand the policy entry's Material sentence to identify the adopted OSS, - meta, agents, and documentation policies plus adapted root AGENTS.md and - the copied Policy Reading Guide section of docs/development.md. Mark them - adapted for this repository; do not imply the whole developer guide or - unrelated tooling instructions have changed license. +Status: Pending. Depends on Stage 1. -Acceptance: all stage policies have their own correct source link and version; -orientation selects policies by task, including meta for adoption work; local -links resolve; no upstream handbook or example collection was copied. -Generic language differences from upstream are eliminated, not rephrased. +Files: primarily `internal/config/load_test.go` and +`internal/config/document_test.go`; production configuration files only if a +specific adoption defect requires a fix. -## Stage 3: Adopt Architecture And Testing With Narrow Local Decisions +Use existing `loadDocumentBytes` and `writeApplicationFile` helpers and +`TestLoadComposesExplicitImportsAndSelectedOverlay` as patterns. Add the +following bounded scenarios rather than a general fixture framework. -**Status: Complete.** The three shared architecture sections and the common -testing text match the pinned source. Local architecture decisions were checked -against the accepted ADRs and internal guides; focused test ownership and the -expanded attribution scope were reviewed without changing application code. +1. Add a backend-inheritance test using an actual `Document`: + - Parent `base` has an endpoint, an environment-reference name, + concurrency limit 2, queue capacity 4, and dynamic parameters + `enabled: true`, `shared: visible`, and `count: 7`. + - Child `child` extends `base`, sets queue capacity 0, and overrides + `enabled` to false. Assert inherited endpoint/reference/limit and + retained shared/count values, plus explicit zero and false replacements. + - A second child extends `base` and sets queue capacity to null. + Assert the nullable pointer remains nil rather than inheriting 4. + - Convert through `Settings(result.Config)`. Assert that all declared + backend IDs, including `base`, survive in the existing sorted order, + inherited settings survive conversion, zero capacity has a non-nil pointer, + and the dynamic integer uses the existing `int64` representation. +2. Query `result.Metadata()` for the inherited child endpoint with + `configkit.Keys("backends", "child", "endpoint")`. + Check `IsExplicit` and `Lookup`, then verify a public + `Origin.Inheritance` step links the parent field, child field, and controlling + `/backends/child/extends` path. Do not assert exact location numbers, + internal traversal counts, or all history records. +3. Add a file-backed assembly test: + - Main input imports a fragment defining `base` and declares a child + extending it. Put a relative `prompt_dir` value in the fragment. + - A selected overlay changes the parent's endpoint and gives the child an + explicit queue capacity of 0. Supply an ordinary explicit CLI override + for `server.addr` through `LoadOptions.Overrides`. + - Assert the child inherits the overlay-adjusted parent endpoint, its own + zero wins, the CLI address wins, and the relative prompt directory keeps + the current cleaning/working-directory-relative representation rather + than becoming relative to the fragment. + - Reuse the same fixture with a cancelling overlay that sets + `extends: null` and gives the child its own valid endpoint. Check that + the child no longer inherits the parent's reference or capacity. +4. Add one reserved-key failure case through `Load`: under a valid backend, + set `extra_params.extends` to a missing sibling name. Require a nil result, + use `errors.As` to reach `*configkit.LoadError`, and find + `CodeInheritanceMissing` at the directive path in `Diagnostics()`. + This protects propagation of the compatibility change without re-testing + upstream's cycle, nesting, grammar, or expansion-limit matrices. -Files: `docs/policy/architecture.md`, `docs/policy/testing.md`, -policy attribution entry, and focused internal docs only if moving existing -implementation detail requires it. +Validation: `go test ./internal/config`, development baseline, formatting, +and diff checks. -1. Read the existing architecture, relevant accepted ADRs, source/adapter - internal guides, and the pinned architecture v1.3 template. Retain upstream - Purpose And Ownership, Architectural Approach, and Adopted Constraints And - Implemented Structure text verbatim. Replace the Application-Specific - Topics placeholder with Scriptorium's existing substantive decisions. -2. Preserve public PromptKit/ConfigKit responsibility boundaries, definition - support, strict decoding, presence handling, HTTP artifact containment, - request independence and concurrency-safe shared capacity, credential/error - boundaries, dependency restrictions, and explicit workflow non-goals. - Retain the existing lexical containment and privileged-host threat scope, - not a stronger filesystem-sandbox promise. Customize the trust discussion - to those decisions rather than retaining instructional example prose. -3. Correct system shape to include run, render, serve, inspect, and config. - Link to internal documentation for concrete package inventory/mechanics. - Where material moves, preserve it in its canonical internal owner without - duplicating it. Do not introduce new wrappers, ports, orchestration, or - package constraints merely to “implement” the architectural recommendation. -4. Adopt testing v1.3 common text verbatim. Add one clearly identified local - test-ownership section for configuration, CLI, HTTP, formatting, architecture - guards, and PromptKit/ConfigKit boundaries. Preserve the existing distinction - between adoption/integration fixtures and upstream exhaustive tests. - Retain a short application-specific note explaining HTTP containment and - shared-state risks where useful; do not replace upstream risk-based coverage - guidance or create percentage targets, quotas, or new test requirements. -5. Add accurate source/version/date metadata and extend the policy attribution - scope to architecture and testing. Record any moved adapted prose in the - Material scope if it is placed outside the already identified files. +Acceptance: inherited input and explicit replacements retain their application +types and presence, source assembly precedes inheritance, structured failures +survive application wrapping, and `Settings` performs no hidden merge. +No new field ranges, secret handling, or source/path policies appear. -Acceptance: direct comparison isolates only the roadmap's justified local -decisions; shared text matches upstream. Architecture describes existing -behavior accurately without implementation work. Testing preserves ownership -without duplicating upstream matrices or imposing new coverage gates. +## Stage 3: Protect CLI Inspection And Promptkit Engine Adoption -## Stage 4: Adopt Release Policy Without Changing Publication Behavior +Status: Pending. Depends on Stage 2. -**Status: Complete.** The shared release language matches the pinned source; -the local selections match the existing script, hosted workflow, and runbook. -Commands, build targets, recovery behavior, and the three-link footer remain -unchanged. Attribution now names all seven adopted policies. +Files: `internal/adapter/cli/config_test.go` and +`internal/adapter/cli/run_test.go`; CLI production code only if an actual +boundary defect is demonstrated. -Files: `docs/policy/release.md`, `docs/release.md`, attribution entry. +1. Add a small file-backed parent/child fixture for CLI inspection, borrowing + existing `runCLICommand`, `writeAppConfigFile`, and inspection test + patterns. Omit framework source directories and run validation with the + referenced environment variable absent; use a synthetic name and value with + `t.Setenv` for the inspection checks. Check: + - `config validate` succeeds without credentials or a Promptkit engine. + - `config show` exposes resolved inherited endpoint/reference/ordinary + parameters and the child's false/zero values, and omits the structural + `extends` directive from effective backend data. + - `config explain --path /backends/child/endpoint` identifies parent, + destination, controlling directive, and effective endpoint. Use stable + semantic fragments rather than a complete text snapshot. + - Explanation of a replaced child parameter keeps the inherited and + replacement values visible. The environment reference remains visible; + synthetic API-key bytes never appear in successful output. + - `config sources` still uses its current JSON DTO; a one-file fixture + has one acquired file source and no fabricated inheritance source. + Parse structured output where useful; do not add output fields or promise + byte-stable upstream YAML/explanation wording. +2. Check the reserved-key failure from Stage 2 at the CLI boundary once: + `config validate` returns `ExitRuntimeError`, successful stdout is empty, + and stderr identifies the inheritance code/path through existing safe + diagnostic rendering. Avoid a complete error-string assertion. +3. Add a render integration test alongside + `TestRenderCommandUsesConfiguredCustomBackend`. Use a minimal synthetic + prompt/profile selecting a child backend. Define its endpoint on the parent + and only `extends` plus explicit replacements on the child. + Verify preparation succeeds and reports the child's backend ID and inherited + endpoint using the established prepared output contract. Stage 2 owns + detailed assertions on capacity and dynamic value conversion. +4. Demonstrate the parent is not treated as an abstract template: in a focused + variant, give the parent an invalid endpoint and the child its own valid + endpoint. Application loading may succeed, but existing `newEngine` + initialization must return an error identifiable as + `promptkit.ErrInvalidConfig`. Follow + `TestConfiguredBackendValidationComesFromPromptkit` for that boundary. + Do not add endpoint validation to ConfigKit or suppress parent registration. -1. Read the current release policy, procedure, script, and hosted workflow; - inspect them read-only. Adopt upstream release v1.4 common wording. -2. Add a compact Scriptorium-specific section preserving the established - selections: main/origin, branch-before-tag publication with exact remote - candidate agreement, annotated tags derived from the checked-in note, - stable releases only, asynchronous Linux binaries/checksums, one race-enabled - offline test invocation, and source-boundary guards. Keep rationale for - selected gates in policy and command/target details in the procedure. -3. Retain upstream's general alternatives verbatim but state which existing - approach Scriptorium selects. Atomic push and source-only release remain - template-supported alternatives, not newly supported Scriptorium workflows. - Preserve successful tag publication as completion; no CI polling, artifact - availability, or consumer installation gate is added. -4. Align the procedure with this allocation without changing its commands, - required checks, supported platforms, or failure-recovery behavior. Confirm - the Stage 1 three-link footer survives hosted-body reuse. Do not run the - publication command or mutate remote state to validate documentation. -5. Add metadata and expand the policy attribution scope to all seven policies. - The final Material description also identifies adapted AGENTS.md and the - developer-guide reading section, plus any actually moved adapted text. +Use render/preparation and real local libraries; no live provider calls or +generation fixture is needed. Reuse existing shared-server capacity tests +rather than adding a new concurrency matrix for copied backend settings. -Acceptance: the existing release workflow still satisfies the resulting policy -with no script/CI changes. Source completion, delivery status, immutability, -tag type, and validation obligations are unchanged. All seven source links -identify their own file at the selected full commit. +Validation: `go test ./internal/adapter/cli`, development baseline, +formatting, and diff checks. -## Stage 5: Verify Language Parity And Complete The Documentation Handoff +Acceptance: inspection and engine construction consume the same inherited +configuration, provenance is understandable, intentional visibility is retained, +and all configured backends follow existing registration rules. -**Status: Complete.** All seven policies were compared directly with the pinned -upstream files; differences are limited to metadata, removed template text, -the selected project example and topic rows, and the identified local sections. -The copied license matches byte-for-byte. A Markdown-aware check resolved 86 -local links; historical plan references resolve to Git objects. Attribution, -notice scope, release navigation, and the final documentation-only diff were -reviewed without changing application or publication artifacts. +## Stage 4: Deliver A Maintained Example And Finish Current Documentation -Files: this plan, the feature roadmap, and only affected documentation needing -correction within the preceding stages' scope. +Status: Pending. Depends on Stage 3. -1. Compare all seven adopted documents directly with their selected upstream - counterparts. Account for metadata, removed template sections, approved - substitutions, and the narrow local sections. Correct every remaining - non-substantive wording difference. Do not turn this comparison into a - permanent script, CI requirement, or release gate. -2. Check there are no adoption placeholders, copied template-only instructions, - absent local example links, stale BSD descriptions of Scriptorium itself, - or contradictory selective-reading directions. Legitimate BSD dependency - attribution remains. Validate links using Markdown-aware handling so - illustrative syntax in inline code is not treated as a broken real link. -3. Confirm per-document source metadata, the policy entry's exact scope, - COPYRIGHT's scoped license treatment, existing dependency grants/notices, - and the byte-for-byte new license text. Keep example/source links pinned - and public discovery links current. Check footer paths in the candidate; - unpublished release tags need not resolve online. -4. Review affected roadmap references to implementation.md. Where a link - specifically means an old completed plan, replace it with a clear historical - Git reference from this plan, not this new policy sequence. Preserve - deferred application features and historical completion evidence. - Current release directions link to the canonical procedure, not an old - two-link footer. Do not rewrite published release notes. -5. Mark only actually delivered stages complete with concise evidence here. - Update the feature roadmap's status to delivered and keep its end-state - focus. Record the next-release summary described above without choosing a - version, creating a tag, or claiming publication. -6. Run diff/whitespace and affected-document/link checks. Do not reformat - verbatim license text to satisfy a style check. No Go test/build rerun is - necessary for this documentation-only work; no executable example or - publication command needs changing. Inspect status and staged diff, commit, - and report the commit and remaining work under the agent policy. +Files: new `examples/config.inheritance.yml`, `README.md`, +`docs/config.md`, `docs/cli.md`, `docs/internal/sources.md`, and +`docs/internal/adapters.md` only where its description needs correction. -Acceptance: policy language is standardized with only justified local -customization; notice/provenance arrangements describe reality; no runtime, -dependency, publication, or historical-release change slipped into the diff. +1. Create `examples/config.inheritance.yml` with the existing example prompt, + profile, and schema directories. Define: + - `local-base`: localhost OpenAI-compatible endpoint, reference + `LOCAL_GPU_API_KEY`, concurrency limit 2, queue capacity 4, and an + illustrative `extra_params.provider_option: true`. + - `local-gpu`: `extends: local-base`, queue capacity 0, and + `extra_params.provider_option: false`. + The existing `examples/profiles/local-gpu.yml` selects the child ID. + Keep both parent and child valid ordinary backend definitions. Add a short + comment that application paths are relative to the repository invocation + directory. No new template collection or credential fixture is needed. +2. Link the new example from README's Examples list and the application + inheritance subsection in `docs/config.md`. Keep complete YAML in the + maintained file, not duplicated in prose. +3. In `docs/config.md`, finish the inheritance description started in Stage 1: + explicit zero/false/empty/null replacement subject to the schema, sibling + lookup, ordinary parent registration, eager resolution of effective + relationships, cancellation, and inspection. Link the pinned ConfigKit + contract for detailed rules. Retain migration guidance for literal keys + and named mapping entries, without implying a universal rename solution. +4. Add structural inheritance to `docs/cli.md`'s explanation-history + description. Commands and flags remain unchanged, and `sources` retains + its documented fields. Do not copy inheritance semantics into the CLI owner. +5. Update `docs/internal/sources.md` to describe post-assembly, pre-decode + inheritance and downstream runtime conversion. Link the owning config + reference. If needed, clarify native writer use in adapter internals; do + not duplicate the configuration contract. +6. Check current ConfigKit version references throughout nonhistorical docs. + Preserve old release records and explicitly historical cutover references. + Keep scope distinctions clear: ordinary application path values and + credential references retain their current meaning; Promptkit formats and + HTTP bodies do not acquire ConfigKit directives. + +Run these example commands from the repository root: + +```sh +go run ./cmd/scriptorium config validate --config examples/config.inheritance.yml +go run ./cmd/scriptorium config show --config examples/config.inheritance.yml +go run ./cmd/scriptorium config sources --config examples/config.inheritance.yml +go run ./cmd/scriptorium config explain --config examples/config.inheritance.yml --path /backends/local-gpu/endpoint +go run ./cmd/scriptorium render --config examples/config.inheritance.yml --prompt generic.markdown_summary --profile local-gpu --input transcript=./examples/fixtures/transcript.md --input glossary=./examples/fixtures/glossary.yml +``` + +The render command prepares output without calling a model. Inspect that its +selected backend is the child and the effective endpoint is inherited. The +sample parameter is illustrative, not a claim of support by a particular +provider. Validate changed local/upstream links and run diff checks. + +Acceptance: a complete example works without credentials or provider access, +users can discover and inspect it, and current documentation describes +implemented native behavior without inventing stronger guarantees. + +## Stage 5: Verify The Complete Work Set And Record The Handoff + +Status: Pending. Depends on Stage 4. + +Files: this plan and `docs/roadmap/configkit.md`; the historical-reference +portion of `docs/roadmap/policy.md`; other previously affected files only if +a correction is needed within this scope. + +1. Review the complete diff against the baseline and check each roadmap + completion criterion. Confirm the dependency/notice revision, ordinary + `Load`, application presence/path/credential handling, inherited backend + mapping, inspection behavior, and maintained example. +2. Confirm no new wrappers, source APIs, redaction rules, HTTP contracts, + abstract backend behavior, cross-ID capacity pooling, unrelated dependency + upgrades, permanent validation gates, or release automation slipped in. + Correct actual divergence rather than weakening the selected tests. +3. Run final development validation if not already successful for the unchanged + Go/module/test content: + + ```sh + go test ./... + go test -race ./... + go vet ./... + go build ./cmd/scriptorium + git diff --check + ``` + + Reuse Stage 4's successful commands and links when those files are unchanged. + Record actual checks and outcomes; do not claim the exploratory review + replaced final validation. No live API, CI polling, cross-platform expansion, + or publication command is needed to complete this work set. +4. Repair the completed policy roadmap's current `implementation.md` link: + replace it with the historical Git reference + `git show 8b6c12f912b28ac00016f047f9846798a5de95d9:docs/roadmap/implementation.md`. + This is a navigation correction, not a new policy adoption. +5. Mark stages complete here only after their acceptance checks pass. + Mark the ConfigKit feature roadmap delivered, retaining target-state rationale + and deferred scope. Do not put the ordered steps into that roadmap. +6. Record a concise release handoff in this plan: ConfigKit v0.5.0, backend + inheritance, globally reserved application `extends`, no keyword escape, + parent registration, and unchanged application path/credential ownership. + The next intended minor is currently v0.16.0. Version availability checks, + its checked-in release note with COPYRIGHT | LICENSE | ATTRIBUTION links, + roadmap retirement, tagging, and publication belong to separate release + preparation under `docs/release.md`. Do not create or publish a release here. +7. Review status and staged changes, commit the completed handoff, and report + completion, verification, commit IDs, and any remaining uncommitted work. + The implementation is complete independently of release publication. + +Acceptance: all five stages have truthful completion evidence, the feature +roadmap reflects delivery, historical navigation remains accurate, and the +final application work matches the agreed scope. ## Open Questions -None. The maintainer approved the public discovery URLs, the standard -CC-BY-SA arrangement for copied policy material, the selected upstream revision, -and the justified local variations. The existing application grant, dependency -grants, and release approach remain unchanged; do not reopen them merely to -perform this adoption. +None within the accepted scope. Native inheritance and its reserved-key +compatibility change, visible ordinary parameters and reference names, existing +source/path policies, and deferral of new source APIs are already selected. +A future concrete requirement to pass literal provider `extends` data needs +upstream consideration; it is not an unresolved implementation decision for +this work set.