Plan ConfigKit inheritance implementation
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user