diff --git a/docs/oss/attribution.md b/docs/oss/attribution.md index a1616e5..ddb92e4 100644 --- a/docs/oss/attribution.md +++ b/docs/oss/attribution.md @@ -5,7 +5,8 @@ Material: All documents under `docs/policy/`, root `AGENTS.md`, and the Policy Reading Guide in `docs/development.md`, adapted for this repository. `docs/policy/release.md` incorporates revision -`e833faddf120c789a9b45348edaf75720de16348`; the remaining listed material +`e833faddf120c789a9b45348edaf75720de16348`; `docs/policy/documentation.md` +incorporates revision `beb5f191470a9daef2383981a6bfd02232490ab4`; the remaining listed material incorporates revision `d84a38ebab26f048cafbe59a2246700c35d29843`. Copyright (C) 2026 Eric Rakestraw @@ -16,12 +17,16 @@ License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) | [COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/LICENSE) | [COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/COPYRIGHT) | -[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/LICENSE). +[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/LICENSE) | +[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/beb5f191470a9daef2383981a6bfd02232490ab4/COPYRIGHT) | +[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/beb5f191470a9daef2383981a6bfd02232490ab4/LICENSE). [Source](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843). [Source](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348). +[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/beb5f191470a9daef2383981a6bfd02232490ab4). + ## ConfigKit Selected module: `gitea.maximumdirect.net/eric/ConfigKit` at `v0.7.1`. diff --git a/docs/policy/documentation.md b/docs/policy/documentation.md index bafacb7..a4dcafd 100644 --- a/docs/policy/documentation.md +++ b/docs/policy/documentation.md @@ -2,8 +2,8 @@ **Base Policy Version:** 1.11 -**Last Updated**: 2026-09-28 -**Upstream Source:** [Standard Repository Policies documentation](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md) +**Last Updated**: 2026-11-08 +**Upstream Source:** [Standard Repository Policies documentation](https://gitea.maximumdirect.net/eric/policy/src/commit/beb5f191470a9daef2383981a6bfd02232490ab4/docs/policy/documentation.md) ## Purpose @@ -86,7 +86,7 @@ secret values. | Behavior and architecture of internal packages | Other files under `docs/internal/` | Implementation flow, collaborators, state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. | | Contributor change recipes | Relevant files under `docs/internal/`, including `docs/internal/cli-config.md`, `docs/internal/modules.md`, and `docs/internal/validators.md` | Concrete editing and validation steps for each component. | Contributor orientation, global policy, and definitions of external contracts. | | Architectural decision records | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, task sequencing. | -| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, deferred, or rejected work; implementation status, sequencing, and task breakdowns. | Implemented behavior reference and architectural decision rationale. | +| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, or deferred work; implementation status, sequencing, and task breakdowns. | Implemented behavior reference and architectural decision rationale. | | Release-note history | `docs/releases/` | One checked-in summary per source release under the procedure; the note at its immutable tag is the release record. | Current commands, behavior, contracts, and compatibility definitions. | | Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other copyable or runnable files. | Field-by-field reference, command reference, prose explanation. | @@ -154,8 +154,15 @@ Use sequentially numbered ADR filenames such as Treat the decision content of an accepted ADR as immutable. When a decision changes, create a new ADR and update the earlier ADR's status to superseded. -Rejected architectural alternatives belong in the ADR; rejected product ideas -belong in the roadmap. + +ADRs should be reserved for major architectural decisions, such as ownership +boundaries, large-scale architectural features, or invariants that rise to +the level of architectural significance. Routine choices, implementation +decisions, and rejected suggestions do not warrant an ADR unless they +otherwise represent a significant architectural decision. + +Roadmaps should preserve plausible future work, not rejected product +ideas. ## Maintenance diff --git a/docs/roadmap/glossary-stages.md b/docs/roadmap/glossary-stages.md index 5d7f0cd..3c80e6b 100644 --- a/docs/roadmap/glossary-stages.md +++ b/docs/roadmap/glossary-stages.md @@ -119,12 +119,14 @@ semantics remain part of the open decision below. ### Durable Decision Record -Completion requires recording the scope model and its rationale in an accepted -[ADR](../adr/README.md) before retiring this roadmap. Put the enduring -classification rule in the [architecture policy](../policy/architecture.md), -linked to that ADR; keep the implemented per-field scope and fallback contracts -in the [configuration reference](../config.md). The roadmap continues to own -implementation status until the feature lands. +Completion requires recording the scope model in durable documentation before +retiring this roadmap. Put the enduring classification rule and its rationale +in the [architecture policy](../policy/architecture.md); keep the implemented +per-field scope and fallback contracts in the [configuration reference](../config.md). +These configuration design decisions do not require an ADR. Reserve ADRs for +major architectural decisions under the +[documentation policy](../policy/documentation.md#architecture-decision-records). +The roadmap continues to own implementation status until the feature lands. Update the [configuration change guide](../internal/cli-config.md) to require classifying each new setting by consumer lifecycle, specifying its inheritance @@ -175,7 +177,7 @@ Exercise the selected request and validation overrides through stage consumers, including independent budgets without changing shared backend admission or the initial transcript sections. Cover all validation-profile fallback cases above and preserve the distinction between explicit and derived values in inspection. -Confirm that the durable policy, ADR, configuration contracts, and contributor +Confirm that the durable policy, configuration contracts, and contributor guidance are in place before declaring this feature complete. ## Open Decisions