eric/narratio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 27 Wiki Activity

Expand roadmap to align the full policy set

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-28 01:13:10 +00:00
parent 2237a902b6
commit a5a252ab30
1 changed files with 168 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files

324
docs/roadmap/policy.md
View File

@@ -1,196 +1,208 @@
# Align Licensing Documentation With the Standard Policy # Align Narratio With Standard Repository Policies
Status: Accepted; implementation pending. Status: Accepted; implementation pending.
## Goal ## Goal and Approved Scope
Adopt the agreed licensing-documentation conventions without changing Align Narratio's adopted policy language with Standard Repository Policies.
Narratio's license, runtime behavior, or release responsibility boundary. Make Use upstream wording verbatim for non-substantive differences. Retain variations
project licensing and upstream attribution easy to find and maintain through only for substantive, locally significant requirements or decisions and explain
ordinary development and release preparation. their justification. Follow template adoption instructions and customize required
project-specific sections rather than copying instructional placeholders.
This roadmap defines the target and scope, not implementation sequencing. This document defines the target and scope, not implementation stages. It
supersedes the earlier licensing-only roadmap: public upstream discovery,
copied-policy attribution, and coordinated release-workflow alignment are now
included. The earlier prohibition on policy-project references and deferral of
broader release alignment no longer apply.
## Current Baseline ## Fixed Review Revision and Baseline
The agreed house conventions cover project licensing, component attribution, The approved review compared current local documents directly with upstream
and README/release navigation. Policy templates are internal administrative commit `d84a38ebab26f048cafbe59a2246700c35d29843`, verified against published
material, not an attribution source. Do not cite or link their repository, `main` on 2026-09-28. Historical adoption baselines need not be reconstructed.
filesystem location, or contents in Narratio documentation. Adopted policies Do not imply that this revision was previously adopted.
must be self-contained; license texts and component notices must trace to their
actual public publishers and upstream projects.
Narratio currently has: Follow the [adoption guide at the reviewed revision](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md).
Use this fixed revision for implementation; incorporating a later revision
requires deliberate comparison rather than an implicit refresh.
- A root `COPYRIGHT` identifying Narratio, its copyright holder, and the Narratio has five adopted policies without per-document Upstream Source links.
`GPL-3.0-or-later` grant, warranty disclaimer, and third-party-material caveat. It lacks `docs/policy/meta.md`, `docs/policy/oss.md`, and the OSS attribution
- A complete root `LICENSE` matching the standard GPLv3 text except collection. Its development guide has task routes but not the standard selective
for a missing final newline. No substantive licensing correction is needed. policy-reading guidance. COPYRIGHT already grants GPL-3.0-or-later and LICENSE
- Documentation policy based on v1.1, without the new licensing ownership map, contains GPLv3; only the separate policy-document licensing scope needs adding.
and no `docs/policy/oss.md` or `docs/oss/` attribution collection.
- A README without the prescribed closing license and attribution navigation.
- Release policy and procedure without the new licensing footer convention.
The existing Woodpecker publisher already uses the matching checked-in release
document as the hosted Gitea release body.
Narratio publishes source and tagged Linux amd64/arm64 and best-effort macOS The release process already ends at successful tag publication to `origin`, uses
arm64 binaries with checksums. Successful publication of the intended tag to lightweight tags and source-push-before-tag, and publishes Gitea binaries and
`origin` remains the release command's responsibility boundary; asset publication checksums asynchronously. Current guidance requires standalone validation before
is asynchronous. The current dependency graph includes ConfigKit, AWS modules, publication repeats it. The checker requires fixed note sections and repeats
Go extension packages, YAML libraries, and test dependencies. This roadmap does documentation/example tests included in the full suite. These are alignment
not claim that their individual terms or attribution coverage have been audited. work, not automatic justifications for different policy language.
ConfigKit is now selected at v0.4.1, whose patch contains licensing/documentation ## Policy Target
changes only. Its project grant is LGPL-3.0-or-later and its LICENSE includes
both LGPLv3 and GPLv3. PromptKit v0.11.1 likewise updates licensing documentation
and selects MIT-licensed catalog releases, but is not in Narratio's Go module
graph. Its use by separately installed downstream applications does not make it
a Narratio dependency or justify adding it to this inventory by itself.
## Targeted End State | Document | Target version | Required treatment |
| --- | --- | --- |
| `docs/policy/agents.md` | 1.3 | Adopt upstream wording. Remove redundant general-purpose local elaborations; retain application safeguards in architecture. Existing local-commit behavior remains. |
| `docs/policy/testing.md` | 1.3 | Adopt upstream wording after template removal. Protect requested behavior and established contracts without turning risk categories or examples into new requirements. No local exception is needed. |
| `docs/policy/documentation.md` | 1.11 | Adopt general wording and customize the ownership table. Retain troubleshooting ownership and materially useful stage/integration terminology; omit inapplicable public HTTP/API responsibilities. Add provenance and licensing owners. |
| `docs/policy/architecture.md` | 1.3 | Adopt general framing and customize application-specific sections as instructed. Preserve Narratio's established contracts rather than substituting generic examples. |
| `docs/policy/release.md` | 1.4 | Adopt upstream wording with coordinated executable changes. Tag-push completion and authoritative-remote scope are now standard, not local exceptions requiring compensating controls. |
| `docs/policy/meta.md` | 1.0 | Add local authority, public discovery, adoption-guide navigation, and per-document provenance guidance. |
| `docs/policy/oss.md` | 1.8 | Add current House Format, copied-document treatment, maintenance, and reference-example links; customize project/distribution facts. |
The existing project grant remains unchanged. A tailored OSS policy governs No existing policy is wholly unchanged because provenance and wording require
licensing documentation, and a canonical attribution inventory accurately updates. Narratio's architectural decisions and agent commit behavior need no
describes material incorporated into or distributed with Narratio. Applicable substantive change. Wording preferences alone do not justify local variants.
standard texts are available locally; project-specific upstream notices and
source links identify the actual imported commits.
README and future release documents navigate to these canonical materials. ## Provenance and Orientation
Contributors can discover the policy from the development guide and maintain
attribution in the same change as the relevant dependency or distribution change.
There is no duplicate inventory, new licensing service, or additional release
approval system.
## Required Changes Remove each adopted document's `Base Policy Template` section and replace other
template-only guidance with substantive project content where required. Retain
the actual Base Policy Version, set Last Updated to the adoption date, and add
Upstream Source pointing to that individual file at the reviewed commit:
### Adopt a Tailored OSS Policy ```text
https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/FILE.md
```
Add `docs/policy/oss.md` using the agreed OSS conventions, retaining its base version Substitute the correct filename for each policy. Preserve accurate provenance in
and recording the adoption date. Remove template instructions and adapt links later edits; Git records suffice without a new adoption registry or sync service.
that point to template-only examples or reference collections. Do not introduce
placeholder documents merely to satisfy those links.
Identify Narratio's existing application license and connect the policy to the Adapt upstream `agents/AGENTS.md` into root `AGENTS.md`, preserving applicable
canonical repository and release documentation for its Gitea host, distribution existing instructions. Do not copy upstream's root agent instructions, which
channels, and publication mechanism. Preserve the author's license choice; govern work on that repository. Incorporate the supplied selective Policy Reading
adoption is not relicensing. Leave COPYRIGHT and LICENSE substantively intact; Guide into `docs/development.md`: select by task, read before governed decisions,
normalizing the final newline is optional formatting only. reuse available context, follow relevant cross-references, expand reading when
scope expands, and read affected provisions when revising policies. Do not make
reading the whole suite mandatory. Preserve useful Narratio-specific task routes.
Retain the agreed House Format and settled interpretation of notice links: Meta links to the [public project](https://gitea.maximumdirect.net/eric/policy)
project-specific license and attribution material is linked at its imported and [current adoption guide](https://gitea.maximumdirect.net/eric/policy/src/branch/main/docs/adoption.md).
commit rather than copied locally solely because its terms use reproduction, These are current-discovery links; adopted-source and example links stay
inclusion, or copy language. This convention does not establish license commit-pinned. Reading triggers belong in development guidance and formal credit
compatibility or discharge distinct obligations such as modified-file notices in attribution, not duplicated in meta.
or corresponding source. Preserve required notices in incorporated source.
Record concrete obligations or unresolved rights questions outside the format
with their reason and selected treatment; do not invent exceptions based on
common ownership or require repeated approval of the settled convention.
### Establish Canonical Ownership and Contributor Routing ## Justified Local Customizations
Incorporate the agreed licensing ownership additions into Preserve established stage/adapter boundaries, manifest-driven resume/restore,
`docs/policy/documentation.md`, preserving Narratio-specific ownership artifact/path contracts, publication and lock semantics, credential protections,
and existing unrelated decisions. Clearly assign: group-owned workspace behavior, and platform support. These express Narratio's
operational responsibilities; policy alignment does not authorize changing them.
- Project identity, copyright, and grant to `COPYRIGHT`. Retain Linux amd64/arm64 and best-effort macOS arm64 deliverables, without new
- Complete project license text to `LICENSE`. native-platform gates or Windows/Intel Mac support. Preserve `origin/main`,
- General licensing and attribution conventions to `docs/policy/oss.md`. lightweight tags, and source-push-before-tag in the release procedure. These are
- Component-specific attribution to `docs/oss/attribution.md`. permitted project-specific mechanics, not exceptions to tag-push completion.
- Verbatim standard dependency license texts to `docs/oss/licenses/`.
- Navigation to README and release notes; concrete release URL construction
and publication mechanics to `docs/release.md`.
Record the selective policy update accurately; do not imply unrelated policy Customize documentation ownership for real Narratio interfaces and responsibilities,
changes have been adopted by merely changing version metadata. including troubleshooting; do not create empty API/consumer documents. Keep common
Add a task-specific reading route in `docs/development.md` for licensing, prose verbatim around these customizations and explain substantive local choices
dependency, attribution, and release-document changes. Avoid repeating the OSS in their canonical owner rather than maintaining a parallel general policy essay.
rules in the agent, architecture, or testing policies.
### Establish the Attribution Inventory ## Licensing, Attribution, and Local Materials
Review actual incorporated and distributed material, including relevant Create `docs/oss/attribution.md` with the prescribed title followed directly by
transitive dependencies, Go runtime material in binaries, and copied code or factual component entries. Use the canonical Standard Repository Policies entry
assets. Use the selected source revisions and actual use/distribution to decide from the reviewed commit. Identify actual copied/adapted material, including policy
coverage, not just direct entries in `go.mod`. Neither every development tool files, adapted agent instructions, and copied reading-guide material as applicable.
nor every separately installed subprocess application automatically belongs in Preserve creator, copyright, license, disclaimer, and modification notices. Pin
the inventory. Review any such component if Narratio actually incorporates or source, COPYRIGHT, and LICENSE links to the reviewed full commit.
distributes it.
Create `docs/oss/attribution.md` with the agreed five-field format: project Copy CC-BY-SA-4.0 into `docs/oss/licenses/`. Add the limited policy-document scope
name, faithful upstream copyright statements, applicable SPDX expression, to COPYRIGHT with an attribution link: adapted policy material remains CC-BY-SA-4.0;
license/notice links, and a source repository link. Preserve multiple statements, Narratio's application code remains GPL-3.0-or-later. Root LICENSE needs no
licensing alternatives, versions, and exceptions where applicable. Do not infer replacement. Original upstream licensing-example formatting is CC0 and alone
ownership or invent identifiers; identify nonstandard terms through their texts. does not require attribution.
Resolve source and notice links to the exact imported commit, including for Complete the previously agreed inventory of incorporated/distributed material:
copied material. Version tags and moving branches are not substitutes for those relevant transitive dependencies, Go runtime material in shipped binaries, and
component commit links. Inspect the selected source's license and notices rather copied code, documentation, or assets. Inspect selected sources and actual use;
than assuming terms from a dependency name or current upstream main branch. neither direct dependencies alone nor every development tool defines scope.
ConfigKit v0.4.1 is a dependency. PromptKit is not in Narratio's module graph;
invoking a separately installed downstream application does not itself incorporate
that application's dependencies into Narratio.
Copy only the applicable complete, unmodified standard texts into Follow OSS v1.8's ordered fields and presentation: project heading, applicable
`docs/oss/licenses/`. Reuse a text across entries where appropriate, but preserve faithful copyright statements, applicable SPDX expression, license/notice links,
distinct versions and exceptions. Make required companion texts directly and a link labeled `Source` to the exact commit, ending with a period.
reachable from the affected entry; LGPLv3, if applicable, includes GPLv3. Optional identification remains factual. Preserve
Classify upstream files by content, not filename: a LICENSE file containing alternatives, exceptions, and required notices; do not invent identifiers or add
project-specific notices may require both its upstream link and a local standard research narratives, compliance conclusions, or exception reasoning to entries.
text link. Keep explanatory prose outside the verbatim texts.
### Add README and Release Navigation Copy applicable complete standard texts locally and make companion texts directly
reachable. Link project-specific notices and sources at exact imported commits,
not moving branches or tags. Apply the House interpretation of notice links
without blanket additional local-copy requirements. Distinct concrete obligations
still receive appropriate treatment; preserve notices in incorporated source.
End README with two friendly statements linking to the existing GPL v3-or-later Keep upstream's README, root AGENTS.md, development/adoption guides, and example
grant in COPYRIGHT and the new attribution document. collection upstream. Retain commit-pinned example links in the adopted OSS policy;
create actual local notices instead of copying the example collection. Adopted
policies, project orientation, actual attribution, and applicable standard texts
belong locally. Do not create placeholders for template-only links.
Update `docs/policy/release.md` to reference the OSS footer convention, and End README with the prescribed grant and attribution links. Future release notes
`docs/release.md` to give the concrete Narratio Gitea URL construction. Each new and hosted pages end with `COPYRIGHT | LICENSE | ATTRIBUTION` links at their
release document and its hosted download page must end with three links whose immutable release tag or source revision. The procedure owns concrete Gitea URLs;
visible text is `COPYRIGHT | LICENSE | ATTRIBUTION`. Use absolute URLs at that continue using the checked-in note as the hosted body. Maintain attribution with
release's immutable tag or corresponding immutable source revision. Unlike relevant dependency/material changes through ordinary review.
upstream component links, these release-navigation links may use the release tag.
Retain reuse of the checked-in release note by `.woodpecker/release.yml`; no new ## Coordinated Release Alignment
publisher is expected. Prepare the footer alongside the note and verify its
intended paths against the candidate source. A future tag need not already
resolve remotely. Do not add publication-time network checks or CI polling.
### Keep Ongoing Maintenance Proportionate Update release policy, `docs/release.md`, relevant scripts, tests, and development
guidance together so rules and executable behavior agree:
Update affected entries, source/notice commit links, and texts in changes that - Make publication the normal validating-and-publishing entry point. Standalone
add, remove, upgrade, copy, or alter distribution of relevant components. Review validation remains optional rather than a mandatory duplicate prior pass.
faithful license text copies, statements, and destinations through ordinary - Remove fixed release-note section requirements. Preserve version-matched notes
change review and existing local documentation checks. and titles, relevant compatibility/upgrade information, and the licensing footer.
- Remove duplicate documentation/example test invocations covered by the full
suite. Avoid repeated validation of the same final candidate; no persistent
validation cache is required.
- Select additional gates by concrete risk and distinct protection. Do not keep
race, static, module-hygiene, formatting, or other checks merely because they
exist; document reasons for retained checks. Do not remove useful checks merely
to minimize command count. Resolve the exact set during implementation planning
against these criteria rather than leaving a blanket exemption or expansion.
- Keep offline default tests, required build targets, fresh-version checks,
clean candidate/exact source/tag guards, and explicit-ref publication.
- Treat ordinary review and roadmap retirement as preparation, not new human
approval rounds. Evaluate incidental file prohibitions by their impact on tagged
source rather than banning ignored local files solely because they exist.
- End at successful tag push, without CI polling, asset-availability gates, or
successful-push read-back requirements. Resolve failed/ambiguous pushes from
remote evidence and report asynchronous delivery separately.
- Align recovery guidance: transient delivery failures alone do not require new
versions. Retries/missing-asset additions must preserve published content and
checksum consistency; source/content corrections require a new release.
Apply the formatting convention prospectively. Do not retrofit published tags, Expected implementation surfaces include `scripts/check-release-candidate.sh`,
release notes, binaries, or checksums. Any actual historical omission discovered `scripts/release.sh`, shared helpers/builders where needed, and release tests.
during the inventory requires deliberate treatment under the applicable terms Review workflow references for consistency without expanding into unrelated CI
and existing release correction policy, not silent rewriting of a release. repair or application behavior changes.
## Scope Boundaries ## Boundaries and Completion Evidence
- No license change, automatic copyright-year advancement, or blanket per-file No application relicensing, automatic copyright-year advancement, blanket headers,
header requirement. dependency upgrade, runtime feature, or platform expansion is included. Do not add
- No mandatory scanner, full SBOM, recurring legal sign-off, new release approval mandatory scanners, a full SBOM, recurring legal sign-offs, publication-time network
gate, or new network availability requirement. checks, or release approval gates. New downloadable license assets or packaging
- No automatic requirement for separate downloadable license assets, source formats are not required merely to implement the conventions; concrete component
bundles, or a different binary packaging format. Concrete obligations found obligations still require their applicable treatment.
during the inventory still require their applicable treatment.
- No changes to application behavior, dependency versions, platform support,
or successful-tag-push release completion.
- No wholesale replacement of Narratio-specific policy with generic templates.
- No adoption in this scope of broader release-process changes to
validation, repeated checks, fixed note sections, or release preparation.
Those changes warrant a separate deliberate review of policy, scripts, and
tests. The licensing additions must not silently enact them.
## Completion Evidence Apply formatting prospectively. Preserve published tags, notes, binaries, and
checksums. Address any discovered historical omission deliberately under the
applicable terms and correction policy, not by silently rewriting releases.
The tailored policy and ownership/routing changes are present; the inventory Completion requires comparison with the pinned source, accurate per-file metadata
covers the material identified by the source/distribution review; entries have and material attribution, justified variations, substantive supporting documents,
faithful notices and exact source revisions; applicable local texts and companion valid navigation, and complete applicable texts. Release procedures and tests must
links are complete; README and release guidance provide the prescribed navigation; prove the selected workflow and guards without duplicate mandatory validation or
and local documentation checks pass. Historical releases and existing publication CI waiting. Documentation checks and relevant release tests must pass. Merely
guards remain unchanged. Review must establish these facts rather than treating creating Markdown files is not evidence of alignment.
the mere existence of new Markdown files as completion.
No product decisions remain open for this scope. Component-specific rights or No product-level decision remains open from the approved review. Concrete rights
distribution questions discovered during the inventory must be surfaced with questions or gate tradeoffs unresolved by the risk-based approach must be surfaced
evidence rather than guessed or expanded into blanket restrictions. with evidence during planning, not silently converted into stronger requirements.