Plan ConfigKit inheritance implementation

This commit is contained in:
2026-10-03 17:26:28 +00:00
parent 8b6c12f912
commit e1ce526114

View File

@@ -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 Planned on 2026-10-03 against Scriptorium
`8452b54809b99425a97940da485daaa48c77aeb8`. All five stages are complete. `8b6c12f912b28ac00016f047f9846798a5de95d9`. All five stages are pending.
The ordered stages below retain the implementation instructions and completion The [feature roadmap](configkit.md) owns scope, intent, and the target state.
evidence for this delivered work set. 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 The baseline selects ConfigKit v0.4.2 and Promptkit v0.11.2. The target is the
for local exceptions. This plan owns execution steps and acceptance checks. published ConfigKit v0.5.0 at
This is documentation work, not application, dependency, or release-tool work. `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 The previous content of this filename is the completed policy-alignment plan:
`d84a38ebab26f048cafbe59a2246700c35d29843`. `git show 8b6c12f912b28ac00016f047f9846798a5de95d9:docs/roadmap/implementation.md`.
Start with its Do not rerun it. The initial ConfigKit cutover is already delivered; this work
[adoption guide](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md). adds upstream inheritance to the existing integration.
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.
Read the current local agent policy and developer orientation before work, ## Execution Rules And Fixed Decisions
then policies governing the stage. Once Stage 2 lands, use the new selective
reading guide. Reuse unchanged policy text already available in context.
## 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 Keep the following agreed choices throughout:
records through Git rather than carrying their implementation steps forward:
- ConfigKit adoption and release handoff: - Retain ordinary `configkit.Load`, the current `Document` schema and
`git show 8452b54809b99425a97940da485daaa48c77aeb8:docs/roadmap/implementation.md`. definition callbacks, and the shared execution/inspection result. ConfigKit
- Earlier PromptKit plans are referenced within that historical document. 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 Production code changes are expected only if validation exposes a real
[the v0.14.0 note](../releases/v0.14.0.md), record prior delivered features. integration defect. Prefer the existing implementation when it already works.
Do not infer a new release obligation from an old prospective handoff. Use small behavioral tests with real ConfigKit and Promptkit collaborators,
The new policy and licensing changes still need a concise summary in the next temporary files, and existing helpers. Do not add parser/inheritance matrices,
release, including the already-selected GPL-3.0-or-later application grant and full prose snapshots, live provider calls, or test frameworks.
the separately licensed policy material. Version selection and publication
are not part of this plan.
## 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 For stages changing modules, Go code, or tests, run the development baseline
changes; do not silently include them in the stage commit. before committing: `go test ./...`, `go test -race ./...`,
2. Read the selected upstream files completely before adopting them. Compare `go vet ./...`, and `go build ./cmd/scriptorium`. Also run each stage's focused
directly with local files; do not reconstruct historical adoption baselines. checks and `git diff --check`; format changed Go files with `gofmt`.
3. Start from upstream text, remove the complete Base Policy Template section, Reuse successful checks for unchanged content. Documentation-only changes need
and apply only the customizations selected below. Preserve shared language affected examples and link checks, not unrelated new runtime tests.
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.
Do not change Go code, module pins, tests, release scripts, CI, accepted ADR ## Stage 1: Adopt The Published Dependency And Its Compatibility Notice
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 OSS Rules And Establish Licensing Notices Status: Pending.
**Status: Complete.** OSS language was compared with the pinned source after Files: `go.mod`, `go.sum`, `docs/oss/attribution.md`,
the approved metadata and example changes. The CC-BY-SA text matches its pinned `docs/config.md`, `docs/development.md`, and
source byte-for-byte; attribution and navigation were checked against the `docs/policy/architecture.md`.
specified format and local paths.
Files: `docs/policy/oss.md`, `docs/oss/attribution.md`, 1. Review the current `internal/config.Load`, `documentDefinition`,
`docs/oss/licenses/CC-BY-SA-4.0.txt`, `COPYRIGHT`, `README.md`, `resolveDocument`, `validateDocument`, and `Settings`, plus CLI
and the footer portion of `docs/release.md`. `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 ```sh
`examples/licensing/policy-attribution.md`, and referenced licensing go get gitea.maximumdirect.net/eric/ConfigKit@v0.5.0
examples at their pinned URLs. Adopt OSS v1.8 with metadata as above. go mod tidy
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.
Acceptance: OSS text matches the pinned source except the approved project Review module and checksum changes. The YAML dependency remains
example and metadata; attribution follows the prescribed format; the added `go.yaml.in/yaml/v4 v4.0.0-rc.6`; keep Promptkit v0.11.2 and the selected
license text is faithful; project and dependency grants remain unchanged. catalogs. Investigate incidental changes rather than silently including them.
Check affected local paths and upstream notice/example destinations. Missing Do not commit a workspace, replacement, or vendored dependency.
copyright fields are omitted, not explained with agent-authored commentary. 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 Acceptance: ConfigKit v0.5.0 is selected, attribution identifies its actual
links, and local adoption date; shared text and the orientation template were revision, and current documentation acknowledges the newly reserved syntax.
compared with the pinned source. The seven-link reading guide and local links The application retains the existing single loading pipeline.
were checked, and attribution names only the incorporated material.
Files: new `docs/policy/meta.md`, `docs/policy/agents.md`, ## Stage 2: Protect Application Loading, Presence, And Runtime Conversion
`docs/policy/documentation.md`, root `AGENTS.md`,
`docs/development.md`, and the policy attribution entry.
1. Adopt meta v1.0 and agents v1.3 verbatim after template-section removal Status: Pending. Depends on Stage 1.
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.
Acceptance: all stage policies have their own correct source link and version; Files: primarily `internal/config/load_test.go` and
orientation selects policies by task, including meta for adoption work; local `internal/config/document_test.go`; production configuration files only if a
links resolve; no upstream handbook or example collection was copied. specific adoption defect requires a fix.
Generic language differences from upstream are eliminated, not rephrased.
## 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 1. Add a backend-inheritance test using an actual `Document`:
testing text match the pinned source. Local architecture decisions were checked - Parent `base` has an endpoint, an environment-reference name,
against the accepted ADRs and internal guides; focused test ownership and the concurrency limit 2, queue capacity 4, and dynamic parameters
expanded attribution scope were reviewed without changing application code. `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`, Validation: `go test ./internal/config`, development baseline, formatting,
policy attribution entry, and focused internal docs only if moving existing and diff checks.
implementation detail requires it.
1. Read the existing architecture, relevant accepted ADRs, source/adapter Acceptance: inherited input and explicit replacements retain their application
internal guides, and the pinned architecture v1.3 template. Retain upstream types and presence, source assembly precedes inheritance, structured failures
Purpose And Ownership, Architectural Approach, and Adopted Constraints And survive application wrapping, and `Settings` performs no hidden merge.
Implemented Structure text verbatim. Replace the Application-Specific No new field ranges, secret handling, or source/path policies appear.
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: direct comparison isolates only the roadmap's justified local ## Stage 3: Protect CLI Inspection And Promptkit Engine Adoption
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 4: Adopt Release Policy Without Changing Publication Behavior Status: Pending. Depends on Stage 2.
**Status: Complete.** The shared release language matches the pinned source; Files: `internal/adapter/cli/config_test.go` and
the local selections match the existing script, hosted workflow, and runbook. `internal/adapter/cli/run_test.go`; CLI production code only if an actual
Commands, build targets, recovery behavior, and the three-link footer remain boundary defect is demonstrated.
unchanged. Attribution now names all seven adopted policies.
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; Use render/preparation and real local libraries; no live provider calls or
inspect them read-only. Adopt upstream release v1.4 common wording. generation fixture is needed. Reuse existing shared-server capacity tests
2. Add a compact Scriptorium-specific section preserving the established rather than adding a new concurrency matrix for copied backend settings.
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.
Acceptance: the existing release workflow still satisfies the resulting policy Validation: `go test ./internal/adapter/cli`, development baseline,
with no script/CI changes. Source completion, delivery status, immutability, formatting, and diff checks.
tag type, and validation obligations are unchanged. All seven source links
identify their own file at the selected full commit.
## 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 ## Stage 4: Deliver A Maintained Example And Finish Current Documentation
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.
Files: this plan, the feature roadmap, and only affected documentation needing Status: Pending. Depends on Stage 3.
correction within the preceding stages' scope.
1. Compare all seven adopted documents directly with their selected upstream Files: new `examples/config.inheritance.yml`, `README.md`,
counterparts. Account for metadata, removed template sections, approved `docs/config.md`, `docs/cli.md`, `docs/internal/sources.md`, and
substitutions, and the narrow local sections. Correct every remaining `docs/internal/adapters.md` only where its description needs correction.
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.
Acceptance: policy language is standardized with only justified local 1. Create `examples/config.inheritance.yml` with the existing example prompt,
customization; notice/provenance arrangements describe reality; no runtime, profile, and schema directories. Define:
dependency, publication, or historical-release change slipped into the diff. - `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 ## Open Questions
None. The maintainer approved the public discovery URLs, the standard None within the accepted scope. Native inheritance and its reserved-key
CC-BY-SA arrangement for copied policy material, the selected upstream revision, compatibility change, visible ordinary parameters and reference names, existing
and the justified local variations. The existing application grant, dependency source/path policies, and deferral of new source APIs are already selected.
grants, and release approach remain unchanged; do not reopen them merely to A future concrete requirement to pass literal provider `extends` data needs
perform this adoption. upstream consideration; it is not an unresolved implementation decision for
this work set.