Plan the policy alignment implementation
This commit is contained in:
@@ -1,536 +1,285 @@
|
|||||||
# ConfigKit Adoption Implementation Plan
|
# Policy Alignment Implementation Plan
|
||||||
|
|
||||||
## Status, Authority, And Historical Plans
|
## Status, Scope, And Authority
|
||||||
|
|
||||||
Planned on 2026-09-26 against Scriptorium commit
|
Planned on 2026-09-28 against Scriptorium
|
||||||
`43eea5c7c41d2a8134b3dece60f3af5c98b8fd1c`. This document records the
|
`8452b54809b99425a97940da485daaa48c77aeb8`. All stages below are pending.
|
||||||
ordered implementation and its completion evidence. The maintainer resolved
|
Execute them in integer order; each is sized as a focused implementation task
|
||||||
the inspection-policy question:
|
for a gpt-5.6-terra coding agent.
|
||||||
`extra_params` remain visible; only API-key values require secret protection.
|
|
||||||
|
|
||||||
The [feature roadmap](configkit.md) owns scope, target behavior, and user intent.
|
The [feature roadmap](policy.md) owns the agreed end state, scope, and reasons
|
||||||
This plan owns implementation steps and the interface choices needed to execute
|
for local exceptions. This plan owns execution steps and acceptance checks.
|
||||||
them. Read [development](../development.md) and every policy before work:
|
This is documentation work, not application, dependency, or release-tool work.
|
||||||
[agents](../policy/agents.md), [architecture](../policy/architecture.md),
|
|
||||||
[documentation](../policy/documentation.md), [testing](../policy/testing.md),
|
|
||||||
[release](../policy/release.md), and [OSS](../policy/oss.md).
|
|
||||||
[ADR 0004](../adr/0004-definition-boundary.md) continues to govern Promptkit's
|
|
||||||
definition boundary. Do not rewrite accepted ADR decisions.
|
|
||||||
|
|
||||||
This filename previously contained completed Promptkit plans. Older roadmap
|
The selected public upstream revision is
|
||||||
links to this file refer to these historical records, not the ConfigKit stages:
|
`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.
|
||||||
|
|
||||||
- Completed v0.11 implementation and release handoff:
|
Read the current local agent policy and developer orientation before work,
|
||||||
`git show 43eea5c7c41d2a8134b3dece60f3af5c98b8fd1c:docs/roadmap/implementation.md`.
|
then policies governing the stage. Once Stage 2 lands, use the new selective
|
||||||
- Completed v0.9 implementation:
|
reading guide. Reuse unchanged policy text already available in context.
|
||||||
`git show e4405966c87c8a7843b340146e90cc1e515bef42:docs/roadmap/implementation.md`.
|
|
||||||
|
|
||||||
Those deliveries must not be repeated or lost from upcoming release preparation.
|
## Historical Implementation Records
|
||||||
These Git records are available locally without publishing the recent commits.
|
|
||||||
|
|
||||||
## Working Rules And Selected Design
|
This filename previously held completed application plans. Preserve their
|
||||||
|
records through Git rather than carrying their implementation steps forward:
|
||||||
|
|
||||||
The dependency target is `gitea.maximumdirect.net/eric/ConfigKit v0.4.0`,
|
- ConfigKit adoption and release handoff:
|
||||||
commit `e6ced0d3d1194b58e0b3dc8970089471ba175258`. Use its public root package,
|
`git show 8452b54809b99425a97940da485daaa48c77aeb8:docs/roadmap/implementation.md`.
|
||||||
imported as `configkit`. The roadmap links the exact upstream contracts.
|
- Earlier PromptKit plans are referenced within that historical document.
|
||||||
Do not opportunistically upgrade Promptkit or other dependencies, commit a
|
|
||||||
workspace/replacement, or depend on sibling source at runtime.
|
|
||||||
|
|
||||||
This is a clean configuration cutover, not a compatibility project. Native
|
Those stages must not be rerun. Existing release notes, including
|
||||||
ConfigKit syntax, presence, nullability, resource limits, and precedence apply.
|
[the v0.14.0 note](../releases/v0.14.0.md), record prior delivered features.
|
||||||
Do not add a pre-parser, YAML serialization round trip, alternate merge engine,
|
Do not infer a new release obligation from an old prospective handoff.
|
||||||
legacy mode, generic provider abstraction, or a new CLI framework.
|
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.
|
||||||
|
|
||||||
Keep application source discovery and domain rules in `internal/config`;
|
## Common Execution Rules
|
||||||
CLI parsing/output stays in `internal/adapter/cli`. Promptkit remains responsible
|
|
||||||
for prompt/profile/schema parsing, backend semantics, credentials, and engine
|
|
||||||
behavior. Keep one shared server engine and existing HTTP artifact policy.
|
|
||||||
No HTTP schema, execution-report, request-timeout, or retry-orchestration change
|
|
||||||
is part of this plan.
|
|
||||||
|
|
||||||
For every stage:
|
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.
|
||||||
|
|
||||||
1. Inspect the working tree and relevant code/tests through the repository's
|
Do not change Go code, module pins, tests, release scripts, CI, accepted ADR
|
||||||
code-discovery guidance. Preserve unrelated changes.
|
decisions, or published release notes. Do not introduce recurring sync checks,
|
||||||
2. Implement the listed outcome and only supporting refactoring it needs.
|
license approval rounds, release gates, or blanket source headers. Preserve
|
||||||
Internal names below are selected implementation guidance, not public APIs
|
the application grant and dependency terms. Standard license text must remain
|
||||||
or immutable package-layout contracts.
|
verbatim even if a generic whitespace check dislikes publisher formatting.
|
||||||
3. Update canonical current-state docs when behavior lands. Until Stage 3 the
|
|
||||||
new loader is internal preparation, not an advertised executable feature.
|
|
||||||
Never claim later stages are implemented.
|
|
||||||
4. Run focused tests and the development guide's baseline validation for code
|
|
||||||
changes. Tests stay offline, deterministic, and free of real credentials.
|
|
||||||
Reuse existing coverage rather than cloning ConfigKit's parser test matrix.
|
|
||||||
5. Format changed Go files, inspect the diff, validate affected docs/examples,
|
|
||||||
record stage status/evidence here, and commit the coherent unit. Do not push,
|
|
||||||
tag, publish, or add new release gates.
|
|
||||||
|
|
||||||
### Application Configuration Definition
|
## Stage 1: Adopt OSS Rules And Establish Licensing Notices
|
||||||
|
|
||||||
Use a new `Document` type in `internal/config` for the native configuration
|
**Status: Pending.**
|
||||||
shape. It replaces the old on-disk `Config` after CLI cutover. Keep the familiar
|
|
||||||
YAML field names:
|
|
||||||
|
|
||||||
| YAML path | Go shape | Default and selected meaning |
|
Files: `docs/policy/oss.md`, `docs/oss/attribution.md`,
|
||||||
| --- | --- | --- |
|
`docs/oss/licenses/CC-BY-SA-4.0.txt`, `COPYRIGHT`, `README.md`,
|
||||||
| `prompt_dir`, `profile_dir` | `string` | Empty; no source configured. |
|
and the footer portion of `docs/release.md`.
|
||||||
| `schema_dir` | `string` | Existing schema-directory default. Empty remains empty at the application boundary; Promptkit owns any subsequent framework default. |
|
|
||||||
| `transient_retries` | `*int` | Nil; omitted/null delegates, zero disables additional attempts. |
|
|
||||||
| `server` | Non-pointer struct | Its children receive typed defaults; null is invalid. |
|
|
||||||
| `server.addr` | `string` | Existing listen-address default when absent; explicit empty is passed unchanged to the standard HTTP server, not replaced with the Scriptorium default. |
|
|
||||||
| `server.artifact_root` | `string` | Empty; HTTP file input remains disabled. |
|
|
||||||
| Three `server.max_*_bytes` fields | `int64` | Existing defaults; explicit zero disables the respective limit; null is invalid. |
|
|
||||||
| `defaults` | Non-pointer struct | Contains `render_format`; null is invalid. |
|
|
||||||
| `defaults.render_format` | `string` | Existing text default; resolved value must be text or json. Explicit empty is invalid, not defaulted. |
|
|
||||||
| `backends` | `map[string]BackendDocument` | Nil; null is permitted, an empty mapping follows ConfigKit semantics. |
|
|
||||||
|
|
||||||
`BackendDocument` keeps `endpoint string`, `api_key_env string`,
|
1. Read upstream OSS v1.8, COPYRIGHT, the canonical
|
||||||
`extra_params map[string]any`, `concurrency_limit int`, and
|
`examples/licensing/policy-attribution.md`, and referenced licensing
|
||||||
`queue_capacity *int`. Scalar nulls are invalid; nullable maps/pointers retain
|
examples at their pinned URLs. Adopt OSS v1.8 with metadata as above.
|
||||||
native semantics. No catalog IDs or Promptkit fields are added.
|
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.
|
||||||
|
|
||||||
The fresh defaults factory reads existing `internal/defaults` and format
|
Acceptance: OSS text matches the pinned source except the approved project
|
||||||
constants, not a duplicated set of literals. Normalization trims surrounding
|
example and metadata; attribution follows the prescribed format; the added
|
||||||
whitespace from application directory strings, artifact root, and server
|
license text is faithful; project and dependency grants remain unchanged.
|
||||||
address; cleans only nonempty application paths; and lowercases/trims
|
Check affected local paths and upstream notice/example destinations. Missing
|
||||||
`defaults.render_format`. Empty paths remain empty: never let
|
copyright fields are omitted, not explained with agent-authored commentary.
|
||||||
`filepath.Clean("")` turn disabled/unset into `.`. Record actual changes with
|
|
||||||
`configkit.Normalize`, using value-free reasons. Do not normalize backend
|
|
||||||
fields or parameter values on Promptkit's behalf.
|
|
||||||
|
|
||||||
The read-only validator reports negative application size limits, negative
|
## Stage 2: Adopt Provenance, Agent Guidance, And Documentation Ownership
|
||||||
nonnull application retries, and invalid render format through
|
|
||||||
`Validation.Error` at their field paths. It does not print rejected values.
|
|
||||||
Do not call the existing format parser's empty-as-default branch for this field.
|
|
||||||
Do not add endpoint, backend ID, credential-presence, directory-existence,
|
|
||||||
address-format, or positive-only-capacity checks. Existing Promptkit and
|
|
||||||
command-specific validation retains those responsibilities where applicable.
|
|
||||||
|
|
||||||
## Stage 1: Add The Dependency And Native Application Definition
|
**Status: Pending.**
|
||||||
|
|
||||||
**Status: Complete.** The pinned dependency, native definition, focused
|
Files: new `docs/policy/meta.md`, `docs/policy/agents.md`,
|
||||||
presence/normalization/validation tests, and commit-specific attribution are in
|
`docs/policy/documentation.md`, root `AGENTS.md`,
|
||||||
place. The existing executable loader remains active pending the command cutover.
|
`docs/development.md`, and the policy attribution entry.
|
||||||
|
|
||||||
Primary files: `go.mod`, `go.sum`, new focused files under `internal/config`,
|
1. Adopt meta v1.0 and agents v1.3 verbatim after template-section removal
|
||||||
and `docs/oss/attribution.md`.
|
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.
|
||||||
|
|
||||||
1. Add ConfigKit at the selected release. Retain Promptkit v0.11.0 and its
|
Acceptance: all stage policies have their own correct source link and version;
|
||||||
selected catalogs. Provision dependencies outside offline test execution.
|
orientation selects policies by task, including meta for adoption work; local
|
||||||
ConfigKit's yaml/v4 release-candidate dependency is the reviewed upstream
|
links resolve; no upstream handbook or example collection was copied.
|
||||||
choice, not an instruction to upgrade its parser independently.
|
Generic language differences from upstream are eliminated, not rephrased.
|
||||||
2. Implement `Document`, `BackendDocument`, the fresh defaults factory,
|
|
||||||
recorded resolver, and read-only validator described above. Keep the old
|
|
||||||
loader operational until Stage 3 so this stage remains independently
|
|
||||||
buildable; this temporary development state is not a shipped compatibility
|
|
||||||
mode or a second user-selectable configuration path.
|
|
||||||
3. Test the new definition using real `configkit.Load[Document]` with
|
|
||||||
`Bytes` and `NoSource`. Cover explicit zero/empty/null distinctions,
|
|
||||||
retry/queue nil-versus-zero, safe application validation, and a normalized
|
|
||||||
path whose effective output agrees with the returned value. Include nested
|
|
||||||
unknown fields and a representative dynamic numeric parameter.
|
|
||||||
4. Add ConfigKit and yaml/v4 attribution from their selected source material.
|
|
||||||
Resolve the imported yaml/v4 commit from release/module metadata. Preserve
|
|
||||||
actual copyright statements; do not infer a project statement from the
|
|
||||||
FSF license-document copyright. Use applicable SPDX expressions, local
|
|
||||||
standard texts, and commit-pinned upstream license/notice links. Reuse GPL,
|
|
||||||
LGPL, MIT, and Apache texts where applicable, including companion links.
|
|
||||||
Retain yaml.v3 attribution because Promptkit still incorporates it.
|
|
||||||
5. Document the internal definition as preparation in the relevant internal
|
|
||||||
guide without claiming the CLI has switched. No current configuration
|
|
||||||
contract changes yet.
|
|
||||||
|
|
||||||
Acceptance: the dependency and definition compile, focused tests demonstrate
|
## Stage 3: Adopt Architecture And Testing With Narrow Local Decisions
|
||||||
native semantics and audited normalization, and attribution follows the OSS
|
|
||||||
policy. Existing executable behavior still passes its tests.
|
|
||||||
|
|
||||||
## Stage 2: Build Discovery And The Shared Loading Boundary
|
**Status: Pending.**
|
||||||
|
|
||||||
**Status: Complete.** Ordered source discovery, one ConfigKit load, typed
|
Files: `docs/policy/architecture.md`, `docs/policy/testing.md`,
|
||||||
diagnostics, and settings conversion are covered by focused file/default and
|
policy attribution entry, and focused internal docs only if moving existing
|
||||||
override tests. Existing commands still use the old entry point until cutover.
|
implementation detail requires it.
|
||||||
|
|
||||||
Primary files: `internal/config` and its tests; `docs/internal/sources.md`.
|
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.
|
||||||
|
|
||||||
1. Add `LoadOptions` with `Path string`, `Explicit bool`, `Overlay string`,
|
Acceptance: direct comparison isolates only the roadmap's justified local
|
||||||
and `Overrides []configkit.Override`, plus
|
decisions; shared text matches upstream. Architecture describes existing
|
||||||
`Load(LoadOptions) (*configkit.Result[Document], error)`.
|
behavior accurately without implementation work. Testing preserves ownership
|
||||||
Discovery chooses a source; the one ConfigKit call owns actual file reading
|
without duplicating upstream matrices or imposing new coverage gates.
|
||||||
and decoding. Return the result so consumers retain the frozen inspection
|
|
||||||
snapshot as well as the typed configuration.
|
|
||||||
2. With `Explicit=true`, pass the selected path to `configkit.File`;
|
|
||||||
an explicitly empty path is invalid, not implicit discovery or a fallback
|
|
||||||
to the old system filename. Do not silently trim a source filename into a
|
|
||||||
different filename. ConfigKit validates and resolves file sources.
|
|
||||||
3. With `Explicit=false`, ignore the option's path value and examine the
|
|
||||||
existing ordered implicit search locations. Only nonexistence permits
|
|
||||||
examining the next candidate. Other stat failures are errors. Select the
|
|
||||||
first existing candidate and let ConfigKit load it. A selected file's later
|
|
||||||
disappearance/read/parse failure does not restart discovery.
|
|
||||||
4. If neither implicit candidate exists, use `NoSource`. Initially leave
|
|
||||||
imports disabled and the overlay empty; Stage 4 enables composition.
|
|
||||||
Defaults-only loads still accept explicit application overrides. Never
|
|
||||||
reinterpret an empty file as `NoSource`.
|
|
||||||
5. Pass overrides into the ConfigKit call before decoding/validation; do not
|
|
||||||
validate a separately merged lower configuration first. Native parsing and
|
|
||||||
composition failures still follow the upstream lifecycle and are not
|
|
||||||
bypassed by CLI overrides.
|
|
||||||
6. Add a small `Settings(Document) AppSettings` conversion for existing
|
|
||||||
executable wiring. It copies resolved fields, maps the already-validated
|
|
||||||
format, and converts the backend map into ID-sorted backend settings.
|
|
||||||
It performs no file IO, normalization, credential lookup, semantic backend
|
|
||||||
checks, or additional defaults. Dynamic values retain their decoded shapes.
|
|
||||||
7. Preserve ConfigKit's typed `*LoadError` through wrapping so the CLI can
|
|
||||||
render safe structured diagnostics. Discovery-only errors are concise and
|
|
||||||
quote paths safely; no new public error taxonomy is needed.
|
|
||||||
8. Test ordered discovery with temporary paths rather than host system files,
|
|
||||||
explicit missing/empty paths, empty-file rejection versus `{}`,
|
|
||||||
defaults-only loading, source records, override-before-validation behavior,
|
|
||||||
sorted backend conversion, and preservation of zero/nullable values.
|
|
||||||
Remove no existing entry point until all its CLI callers migrate in Stage 3.
|
|
||||||
|
|
||||||
Acceptance: real files and defaults-only inputs produce one reusable result,
|
## Stage 4: Adopt Release Policy Without Changing Publication Behavior
|
||||||
runtime conversion agrees with it, and tests do not depend on machine-wide
|
|
||||||
configuration or secrets. The old and new internals are temporarily buildable,
|
|
||||||
with no new user-visible mode.
|
|
||||||
|
|
||||||
## Stage 3: Cut Existing Commands Over And Remove The Legacy Loader
|
**Status: Pending.**
|
||||||
|
|
||||||
**Status: Complete.** All five command modes use the shared ConfigKit loader;
|
Files: `docs/policy/release.md`, `docs/release.md`, attribution entry.
|
||||||
the legacy decoder and merge path are removed. CLI and configuration contracts
|
|
||||||
now describe native YAML and override behavior. Full test, race, vet, build,
|
|
||||||
and diff checks passed.
|
|
||||||
|
|
||||||
Primary files: `internal/adapter/cli/run.go`, `inspect.go`,
|
1. Read the current release policy, procedure, script, and hosted workflow;
|
||||||
`internal/config/config.go`, and associated tests.
|
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.
|
||||||
|
|
||||||
1. Route run, render, serve, inspect prompt, and inspect profile through the
|
Acceptance: the existing release workflow still satisfies the resulting policy
|
||||||
shared `Load` and `Settings` boundary. Preserve the explicit presence of
|
with no script/CI changes. Source completion, delivery status, immutability,
|
||||||
`--config` in every parser. Centralize the small application-flag mapping
|
tag type, and validation obligations are unchanged. All seven source links
|
||||||
rather than reproduce it in each command.
|
identify their own file at the selected full commit.
|
||||||
2. Use `flag.FlagSet.Visit` (or the existing explicit-set helper) to create
|
|
||||||
one `configkit.Override` per explicitly supplied application flag. Use
|
|
||||||
`configkit.Keys`, built-in scalar values, and a safe `Flag` label containing
|
|
||||||
only the flag name. Standard flag parsing's last occurrence supplies the
|
|
||||||
single override; do not emit duplicate records or parser defaults.
|
|
||||||
|
|
||||||
| Flag | Application path | Existing command scope after cutover |
|
## Stage 5: Verify Language Parity And Complete The Documentation Handoff
|
||||||
| --- | --- | --- |
|
|
||||||
| `--prompt-dir` | `prompt_dir` | run, render, serve, inspect prompt |
|
|
||||||
| `--profile-dir` | `profile_dir` | run, render, serve, inspect profile |
|
|
||||||
| `--schema-dir` | `schema_dir` | run, render, serve |
|
|
||||||
| `--addr` | `server.addr` | serve |
|
|
||||||
| `--artifact-root` | `server.artifact_root` | serve |
|
|
||||||
| `--max-request-bytes` | `server.max_request_bytes` | serve |
|
|
||||||
| `--max-artifact-bytes` | `server.max_artifact_bytes` | serve |
|
|
||||||
| `--max-response-bytes` | `server.max_response_bytes` | serve |
|
|
||||||
|
|
||||||
Register the schema-directory flag on render as well as run/serve so the
|
**Status: Pending.**
|
||||||
advertised application path override is consistently usable. This is not a
|
|
||||||
general expansion of runtime/provider flags to other commands.
|
|
||||||
3. Keep `--format`, `--out`, request `--transient-retries`, prompt/profile
|
|
||||||
selection, model overrides, timeouts, inputs, variables, and reporting
|
|
||||||
options outside the application configuration tree. In particular,
|
|
||||||
`render --format` overrides that invocation's output format without
|
|
||||||
rewriting `defaults.render_format`; omitted format inherits its resolved
|
|
||||||
application value. Existing invocation-only parsing remains unchanged.
|
|
||||||
4. Remove post-load directory trimming/cleaning/defaulting from argument
|
|
||||||
finalizers, including unconditional schema-path cleaning. Keep only
|
|
||||||
invocation-owned transformations such as output-file paths. Explicit
|
|
||||||
empty profile/artifact-root overrides must clear file-provided values;
|
|
||||||
explicit empty prompt directory must reach the existing execution
|
|
||||||
prerequisite rather than revive the lower value.
|
|
||||||
5. Keep existing command prerequisites: run/render/serve and prompt inspection
|
|
||||||
need their effective prompt directory as currently required; profile
|
|
||||||
inspection does not acquire a prompt-directory requirement. All commands
|
|
||||||
still perform the common application schema validation. Do not introduce
|
|
||||||
eager filesystem or credential validation for inspection.
|
|
||||||
6. Add one CLI diagnostic path using `errors.As` and
|
|
||||||
`configkit.WriteDiagnostics` for load errors. Carry successful load warnings
|
|
||||||
to the command boundary and render them once on stderr before execution or
|
|
||||||
output. Handle diagnostic writer errors as command failures. Do not flatten
|
|
||||||
structured failures into raw parser text or print rejected values.
|
|
||||||
Preserve existing process exit classifications; application/parse/load
|
|
||||||
failures are exit 1, not generated-output validation exit 2.
|
|
||||||
7. Remove the old YAML decoder, `strictInteger.UnmarshalYAML`, old on-disk
|
|
||||||
types, `applyConfig`, `ApplyCLIOverrides`, and unused compatibility
|
|
||||||
sentinels/helpers after migrating all callers/tests. Keep only one defaults
|
|
||||||
factory. Remove the direct yaml.v3 import; module tidy may retain yaml.v3
|
|
||||||
as an indirect Promptkit dependency.
|
|
||||||
8. Update tests to the deliberate breaking semantics, not the legacy behavior.
|
|
||||||
Protect explicit empty path clearing, scalar-null rejection, unknown fields,
|
|
||||||
rejected empty/multi-document input, one representative YAML policy change,
|
|
||||||
unchanged request-versus-engine retry precedence, absent optional
|
|
||||||
credentials, and command-specific inspection prerequisites.
|
|
||||||
9. Update configuration and CLI contracts, source/adapter internals, architecture
|
|
||||||
ownership, and the contributor reading guide for the delivered cutover.
|
|
||||||
Preserve existing application defaults, Promptkit definition support,
|
|
||||||
HTTP containment, shared capacity, and report behavior. Adjust the current
|
|
||||||
CLI claim that every command requires a prompt directory to match actual
|
|
||||||
command-specific requirements.
|
|
||||||
|
|
||||||
Acceptance: all existing commands use ConfigKit, no legacy parser or second
|
Files: this plan, the feature roadmap, and only affected documentation needing
|
||||||
application merge remains, relevant tests pass, and diagnostics and docs describe
|
correction within the preceding stages' scope.
|
||||||
the native breaking behavior. Imports/overlays and new inspection commands are
|
|
||||||
not yet advertised.
|
|
||||||
|
|
||||||
## Stage 4: Enable Explicit Imports And Selected Configuration Overlays
|
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.
|
||||||
|
|
||||||
**Status: Complete.** File-backed loads support explicit imports and one
|
Acceptance: policy language is standardized with only justified local
|
||||||
selected overlay under the selected file's canonical directory. All five
|
customization; notice/provenance arrangements describe reality; no runtime,
|
||||||
existing command modes accept `--config-overlay`; real-file composition and a
|
dependency, publication, or historical-release change slipped into the diff.
|
||||||
render workflow are tested. The composed example and contracts are updated;
|
|
||||||
full test, race, vet, build, and diff checks passed.
|
|
||||||
|
|
||||||
Primary files: shared loader, CLI source-selection wiring, configuration and
|
|
||||||
CLI tests, maintained configuration examples.
|
|
||||||
|
|
||||||
1. Enable `Options.Imports` for file-backed loads. Leave it false for
|
|
||||||
`NoSource`, which rejects imports. Use ConfigKit's default canonical
|
|
||||||
selected-file directory as the root; do not supply a wider filesystem root
|
|
||||||
or add application traversal code.
|
|
||||||
2. Wire `LoadOptions.Overlay` into `Options.Overlay`. Register
|
|
||||||
`--config-overlay` on all five existing configuration-loading command
|
|
||||||
modes. Treat the value exactly as an upstream overlay name: no trimming,
|
|
||||||
case folding, extension fallback, path expansion, or local inheritance.
|
|
||||||
Empty and exact lowercase default mean no active overlay under v0.4.0.
|
|
||||||
A requested active overlay without a selected base source fails through
|
|
||||||
ConfigKit; do not manufacture an empty base file or root.
|
|
||||||
3. Use native `configkit.imports` directives for explicit paths/globs. The
|
|
||||||
application enables the feature without requiring a second CLI opt-in;
|
|
||||||
absent directives cause no discovery. Retain conflict-based base
|
|
||||||
composition and native overlay replacement/null semantics.
|
|
||||||
4. Preserve working-directory-relative application path values even when
|
|
||||||
authored in fragments or overlays. Configuration-source containment is
|
|
||||||
not the HTTP artifact policy and is not applied to prompt/schema paths.
|
|
||||||
5. Add focused real-file tests for disjoint backend fragments, an import
|
|
||||||
conflict, overlay replacement, explicit CLI precedence, missing selected
|
|
||||||
overlay, and no-base overlay failure. Verify `--profile` still selects a
|
|
||||||
Promptkit execution profile independently of `--config-overlay`.
|
|
||||||
One real command workflow proves wiring; upstream owns exhaustive glob,
|
|
||||||
symlink, cycle, and parser-limit tests.
|
|
||||||
6. Add a small synthetic import/overlay example under `examples/`; preserve
|
|
||||||
a simple single-file quickstart. Update config/CLI contracts and operations
|
|
||||||
guidance for the new features, root selection, and relative-value policy.
|
|
||||||
|
|
||||||
Acceptance: supported commands load the same native composition pipeline;
|
|
||||||
imports are explicit, overlays remain distinct from execution profiles, and no
|
|
||||||
new scanning, remote acquisition, or path policy is introduced.
|
|
||||||
|
|
||||||
## Stage 5: Add Application Validation, Effective Output, And Source Inspection
|
|
||||||
|
|
||||||
**Status: Complete.** Application-only validation, effective YAML, and ordered
|
|
||||||
JSON source inspection use one shared ConfigKit result without an engine. Tests
|
|
||||||
cover source composition, CLI provenance, stream failures, and the credential
|
|
||||||
reference boundary. Public and internal contracts are updated; full test,
|
|
||||||
race, vet, build, and diff checks passed.
|
|
||||||
|
|
||||||
Primary files: a focused `internal/adapter/cli/config.go`, shared config
|
|
||||||
definition, CLI dispatch/help/tests, and canonical CLI/config documentation.
|
|
||||||
|
|
||||||
1. Apply the maintainer's selected inspection policy: no redaction for
|
|
||||||
`extra_params`, including historical values. API-key values are the only
|
|
||||||
relevant secrets, but this schema stores only `api_key_env` reference names.
|
|
||||||
Keep those names visible and never resolve them in the ConfigKit load.
|
|
||||||
Do not add secret tags to the reference name or parameter container, a
|
|
||||||
catch-all secret predicate, sensitive-key guessing, or a selective masking
|
|
||||||
interface. Actual credentials remain with Promptkit; raw API-key fields
|
|
||||||
remain rejected. Use upstream inspection renderers without adding a second
|
|
||||||
value-rendering path or a synthetic credential field.
|
|
||||||
2. Add a top-level `config` command family using the existing standard-library
|
|
||||||
flag style. The selected interfaces are:
|
|
||||||
|
|
||||||
| Command | Success stdout |
|
|
||||||
| --- | --- |
|
|
||||||
| `scriptorium config validate [flags]` | Empty; exit status communicates application validation success. |
|
|
||||||
| `scriptorium config show [flags]` | `Result.WriteEffective` redacted YAML. |
|
|
||||||
| `scriptorium config sources [flags]` | One newline-terminated JSON array of source records. |
|
|
||||||
| `scriptorium config explain --path <pointer> [flags]` | Added in Stage 6. |
|
|
||||||
|
|
||||||
These are prospective interface specifications, not commands to execute
|
|
||||||
before their stages are implemented.
|
|
||||||
3. All configuration subcommands accept `--config`, `--config-overlay`,
|
|
||||||
and the eight application override flags in Stage 3's table, regardless
|
|
||||||
of which execution command normally uses them. They do not accept request,
|
|
||||||
credential, backend-editing, output-format, or output-file flags. Shell
|
|
||||||
redirection is sufficient for these inspection outputs. No positional
|
|
||||||
arguments are accepted.
|
|
||||||
4. Load exactly once through the common loader. Do not construct a Promptkit
|
|
||||||
engine, restricted artifact reader, listener, or client. Missing prompt
|
|
||||||
directories, unselected/absent credentials, and framework backend validity
|
|
||||||
are not additional application-inspection gates. Invalid application
|
|
||||||
types/ranges/format still fail. Validation describes application load
|
|
||||||
validity, not end-to-end executability.
|
|
||||||
5. For sources, map `Result.Sources()` to a small local DTO with JSON keys
|
|
||||||
`id`, `label`, `layer` (always present), and `path` (omit when empty).
|
|
||||||
Preserve upstream source order; emit `[]\n` for defaults-only input without
|
|
||||||
overrides. Include synthetic CLI sources where present. Do not marshal
|
|
||||||
opaque ConfigKit implementation objects. The standard JSON encoder escapes
|
|
||||||
control characters; no custom terminal rendering is necessary.
|
|
||||||
6. Diagnostics/warnings go only to stderr through the shared diagnostic helper.
|
|
||||||
Successful operations exit 0; parse/load/output/diagnostic-write failures
|
|
||||||
exit 1. No exit 2 meaning is introduced for configuration validation.
|
|
||||||
Ordinary writer failures may leave partial output; do not promise atomic
|
|
||||||
streams or buffering of an entire configuration.
|
|
||||||
7. Test defaults-only show/sources, a composed load with CLI provenance,
|
|
||||||
explicit empty clearing, normalized effective values, failed loads producing
|
|
||||||
no successful stdout, and writer failure. Set a synthetic API-key environment
|
|
||||||
variable: effective output must show its reference name, not its value.
|
|
||||||
Repeat with the variable absent to establish that inspection does not require
|
|
||||||
credentials. Assert that ordinary synthetic parameter values remain visible
|
|
||||||
and runtime ExtraParams stay intact; no real environment or provider is used.
|
|
||||||
8. Update CLI/config contracts, README navigation, subprocess integration,
|
|
||||||
operations, and internal inventory to describe only these delivered modes.
|
|
||||||
Retain the README's license/attribution ending.
|
|
||||||
|
|
||||||
Acceptance: validation, effective output, and source inspection use the same
|
|
||||||
resolved configuration as execution, preserve stream separation, and honor the
|
|
||||||
selected API-key boundary without masking or changing backend parameter data.
|
|
||||||
|
|
||||||
## Stage 6: Add Per-Path Explanation And Verify Credential Boundaries
|
|
||||||
|
|
||||||
**Status: Complete.** `config explain` uses required JSON Pointer paths and
|
|
||||||
ConfigKit's snapshot renderer, including historical and normalized values.
|
|
||||||
Tests cover root, escaped/numeric keys, unknown paths, writer failures, and
|
|
||||||
synthetic credential-reference boundaries. Full test, race, vet, build, and
|
|
||||||
diff checks passed.
|
|
||||||
|
|
||||||
Primary files: configuration command implementation/tests and CLI/config docs.
|
|
||||||
|
|
||||||
1. Implement `config explain` with the same selectors and override flags as
|
|
||||||
Stage 5 plus a required, explicitly supplied `--path`. Parse using
|
|
||||||
`configkit.ParsePath`; syntax is JSON Pointer, not dotted notation, a file
|
|
||||||
path, or a URL fragment. Explicit `--path ""` selects the root; an omitted
|
|
||||||
flag is an error. Preserve escaped and numeric mapping-key semantics.
|
|
||||||
2. Use the successful shared result's `WriteExplanation`. Explain known
|
|
||||||
effective and historical paths, including removed values. An unknown or
|
|
||||||
malformed path exits 1 with no successful explanation output. Quote
|
|
||||||
user-supplied paths safely if included in application diagnostics.
|
|
||||||
Do not rebuild history, look up environment values, or reload sources.
|
|
||||||
3. Keep the upstream human-readable renderer and its redaction semantics rather
|
|
||||||
than inventing a JSON explanation schema or freezing the entire rendered
|
|
||||||
prose as an application guarantee. Writer failures exit 1 and can leave
|
|
||||||
partial output, as with effective output.
|
|
||||||
4. Test a value's default/base/overlay/CLI history, recorded normalization,
|
|
||||||
explicit equal-value writes, an escaped backend key, root selection, and
|
|
||||||
an unknown path. Cover a displaced historical backend parameter value:
|
|
||||||
it remains visible, including in a container/root explanation. Use distinct
|
|
||||||
synthetic environment names and key values to verify reference names remain
|
|
||||||
explainable but resolved API-key bytes are absent from all history/output.
|
|
||||||
5. Update CLI/config docs and operations guidance with path syntax,
|
|
||||||
historical-value meaning, representation differences, and sensitive
|
|
||||||
identifiers/paths. Do not claim that redaction detects arbitrary secrets
|
|
||||||
outside classified paths.
|
|
||||||
|
|
||||||
Acceptance: explain uses the existing snapshot and upstream semantics; its
|
|
||||||
history matches the selected inputs and normalization, parameters remain
|
|
||||||
visible, and explanation neither resolves nor discloses API-key values.
|
|
||||||
|
|
||||||
## Stage 7: Verify Integration, Finish Documentation, And Record Release Handoff
|
|
||||||
|
|
||||||
**Status: Complete.** The feature roadmap, command paths, dependency boundary,
|
|
||||||
documentation, and attribution were audited. Maintained single-file and
|
|
||||||
composed examples passed configuration inspection and no-provider rendering;
|
|
||||||
the optional-credential/integer-parameter backend path passed with a local
|
|
||||||
provider. The full test, race, vet, build, formatting, link, and diff checks
|
|
||||||
passed. Release preparation is recorded below; no tag or publication occurred.
|
|
||||||
|
|
||||||
1. Review the feature roadmap against actual code. Confirm all five original
|
|
||||||
command modes and all four new configuration subcommands use one definition
|
|
||||||
and load pipeline. Remove any transitional loader, duplicated defaults,
|
|
||||||
unused compatibility helpers, or post-snapshot configuration mutation.
|
|
||||||
Do not add architecture machinery merely to assert a particular file layout.
|
|
||||||
2. Exercise maintained single-file and import/overlay examples through the
|
|
||||||
implemented configuration commands and a no-provider render workflow.
|
|
||||||
Use focused backend integration evidence that dynamic integer parameters
|
|
||||||
reach Promptkit correctly and missing optional credentials retain their
|
|
||||||
established meaning. Use a local HTTP server only where provider serialization
|
|
||||||
must be checked; never a real service or credential.
|
|
||||||
3. Retain existing HTTP concurrency, containment, error mapping, retry,
|
|
||||||
timeout, and report tests. Add a representative configuration-to-server
|
|
||||||
wiring test only if existing coverage misses changed settings propagation;
|
|
||||||
do not reproduce all upstream scheduling or HTTP cases.
|
|
||||||
4. Run the development baseline on final code: `go test ./...`,
|
|
||||||
`go test -race ./...`, `go vet ./...`, and
|
|
||||||
`go build ./cmd/scriptorium`. Check formatting, affected examples/links,
|
|
||||||
and `git diff --check`. Do not stage the built binary or scratch files.
|
|
||||||
Compare any new standard license text byte-for-byte; preserve upstream
|
|
||||||
whitespace rather than editing license wording to satisfy a style check.
|
|
||||||
5. Ensure current configuration, CLI, subprocess, operations, internal docs,
|
|
||||||
contributor routing, and architecture ownership agree. Testing policy
|
|
||||||
should identify ConfigKit as the owner of exhaustive upstream loading tests,
|
|
||||||
while Scriptorium owns application adoption tests. Change policy dates when
|
|
||||||
revising policies, not base versions unless adopting new templates.
|
|
||||||
Keep accepted ADR text and published release notes immutable.
|
|
||||||
6. Record the release handoff below and mark only delivered stages complete.
|
|
||||||
Update the feature roadmap's status, including the resolved inspection
|
|
||||||
decision. Preserve deferred work. The next breaking release follows the
|
|
||||||
release policy; version selection, candidate publication validation, release
|
|
||||||
notes at that version, tag creation, and publishing are not this sprint.
|
|
||||||
7. Commit the final coherent handoff and report validation evidence, remaining
|
|
||||||
limitations, and any outstanding work without claiming source/binary
|
|
||||||
publication or complete legal compliance.
|
|
||||||
|
|
||||||
Acceptance: the ConfigKit-native target is delivered with proportionate
|
|
||||||
regression evidence and accurate documentation, and the workspace contains no
|
|
||||||
temporary dependency substitutions or uncommitted implementation artifacts.
|
|
||||||
|
|
||||||
### Release Handoff To Retain
|
|
||||||
|
|
||||||
The upcoming release needs migration guidance for empty files versus `{}`,
|
|
||||||
explicit empty values, nullable versus scalar fields, strict YAML/scalars,
|
|
||||||
reserved keys and upstream size limits, and the invalid explicit-empty config
|
|
||||||
path. Include imports/overlays, application path interpretation, CLI presence,
|
|
||||||
inspection command scope, and the selected API-key-only secret policy. Explicit
|
|
||||||
empty server address reaches standard HTTP server behavior instead of restoring
|
|
||||||
Scriptorium's default; operators should supply their intended listen address.
|
|
||||||
|
|
||||||
Keep request retry overrides and Promptkit credential semantics distinct from
|
|
||||||
application settings. Explain that configuration validation is not a provider
|
|
||||||
probe or complete Promptkit definition validator, and that inspection output
|
|
||||||
is not guaranteed reloadable. Include dependency/attribution changes and the
|
|
||||||
existing LICENSE | ATTRIBUTION footer. Preserve the still-relevant Promptkit
|
|
||||||
v0.11 release handoff identified above when preparing a combined next release.
|
|
||||||
|
|
||||||
### Implementation And Release Preparation Record
|
|
||||||
|
|
||||||
The ConfigKit v0.4.0 adoption is implemented in committed source. The next
|
|
||||||
breaking release still needs version selection, version-matched release notes,
|
|
||||||
candidate validation, tagging, and publication under the release policy; none
|
|
||||||
has occurred as part of this work. Keep the earlier Promptkit v0.11 handoff
|
|
||||||
linked above when preparing a combined release.
|
|
||||||
|
|
||||||
The release note should summarize the deliberate configuration migration:
|
|
||||||
empty files now fail and `{}` means an empty mapping; explicitly empty strings
|
|
||||||
and zero values override lower values; `null` follows declared nullable types;
|
|
||||||
strict YAML rejects additional documents, anchors/aliases, unsupported scalar
|
|
||||||
forms, and unknown fields; `configkit` is reserved and ConfigKit's source and
|
|
||||||
resource limits apply. Explicit `--config ''` is invalid. Imports are opt-in
|
|
||||||
per file directive, while `--config-overlay` selects one named overlay under
|
|
||||||
the selected file's canonical directory; application path *values* remain
|
|
||||||
process-working-directory-relative. Only explicitly supplied application CLI
|
|
||||||
flags override configuration. An explicit empty server address is passed to
|
|
||||||
the standard HTTP server and does not restore Scriptorium's default.
|
|
||||||
|
|
||||||
Document the four application-inspection modes and the selected policy:
|
|
||||||
`extra_params`, including history, and `api_key_env` reference names remain
|
|
||||||
visible, but actual API-key bytes are never resolved by ConfigKit. Inspection
|
|
||||||
output can be sensitive and is not guaranteed reloadable. Application
|
|
||||||
validation neither probes a provider nor completely validates Promptkit
|
|
||||||
definitions. Keep request retry overrides and Promptkit's credential rules
|
|
||||||
separate from application settings. Include the new dependency and attribution
|
|
||||||
notices, and retain the existing LICENSE | ATTRIBUTION footer. Deferred
|
|
||||||
secrets bootstrap, schema versioning, reload, and remote acquisition remain
|
|
||||||
deferred; do not imply source or binary publication has happened.
|
|
||||||
|
|
||||||
## Open Questions
|
## Open Questions
|
||||||
|
|
||||||
None remain for this scope. On 2026-09-26 the maintainer selected no redaction
|
None. The maintainer approved the public discovery URLs, the standard
|
||||||
for `extra_params` and specified that the API key is the only secret requiring
|
CC-BY-SA arrangement for copied policy material, the selected upstream revision,
|
||||||
ConfigKit redaction. Stages 5–6 implement that decision through visible parameter
|
and the justified local variations. The existing application grant, dependency
|
||||||
values/reference names and the existing separation of actual credentials from
|
grants, and release approach remain unchanged; do not reopen them merely to
|
||||||
application configuration. Do not reopen it or substitute blanket masking.
|
perform this adoption.
|
||||||
|
|
||||||
This does not claim automatic detection of credentials embedded in arbitrary
|
|
||||||
strings or provider parameters. The application schema still rejects raw API-key
|
|
||||||
fields, and Promptkit remains responsible for resolving named credential sources.
|
|
||||||
|
|||||||
@@ -5,7 +5,8 @@
|
|||||||
Agreed on 2026-09-28; implementation is pending. This roadmap replaces the
|
Agreed on 2026-09-28; implementation is pending. This roadmap replaces the
|
||||||
earlier licensing-only proposal with alignment of the complete applicable
|
earlier licensing-only proposal with alignment of the complete applicable
|
||||||
policy set and its supporting documentation. It defines the targeted end state
|
policy set and its supporting documentation. It defines the targeted end state
|
||||||
and required changes, not staged implementation instructions.
|
and required changes; the [implementation plan](implementation.md) owns ordered
|
||||||
|
stages and their verification.
|
||||||
|
|
||||||
The goal is identical policy language across adopting projects except where a
|
The goal is identical policy language across adopting projects except where a
|
||||||
substantive, locally significant requirement or decision warrants customization.
|
substantive, locally significant requirement or decision warrants customization.
|
||||||
@@ -204,10 +205,11 @@ Completion means:
|
|||||||
- Policy attribution and document-license scope match the material actually
|
- Policy attribution and document-license scope match the material actually
|
||||||
incorporated; required standard texts are complete and unmodified.
|
incorporated; required standard texts are complete and unmodified.
|
||||||
- README, attribution, release navigation, and still-operative roadmap
|
- README, attribution, release navigation, and still-operative roadmap
|
||||||
handoffs agree with the new conventions. Supersede stale instructions in
|
handoffs agree with the new conventions. Historical implementation evidence
|
||||||
[the implementation record](implementation.md) without rewriting historical
|
remains available through the Git references in the implementation plan,
|
||||||
completion evidence. Preserve the earlier author-selected license change
|
without making old footer directions current policy. The earlier
|
||||||
in the next release's preparation context; publication remains separate work.
|
author-selected license change remains in the next release's preparation
|
||||||
|
context; publication remains separate work.
|
||||||
- Review checks the resulting rules, source/example URLs, notice facts, local
|
- Review checks the resulting rules, source/example URLs, notice facts, local
|
||||||
links, license-text fidelity, and final diff. Runtime tests are unnecessary
|
links, license-text fidelity, and final diff. Runtime tests are unnecessary
|
||||||
for documentation-only changes. A Git adoption record is sufficient; no
|
for documentation-only changes. A Git adoption record is sufficient; no
|
||||||
|
|||||||
Reference in New Issue
Block a user