210 lines
13 KiB
Markdown
210 lines
13 KiB
Markdown
# Align Narratio With Standard Repository Policies
|
|
|
|
Status: Accepted; implementation pending.
|
|
|
|
## Goal and Approved Scope
|
|
|
|
Align Narratio's adopted policy language with Standard Repository Policies.
|
|
Use upstream wording verbatim for non-substantive differences. Retain variations
|
|
only for substantive, locally significant requirements or decisions and explain
|
|
their justification. Follow template adoption instructions and customize required
|
|
project-specific sections rather than copying instructional placeholders.
|
|
|
|
This document defines the target and scope; the [implementation plan](implementation.md)
|
|
owns sequencing and concrete validation choices. 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.
|
|
|
|
## Fixed Review Revision and Baseline
|
|
|
|
The approved review compared current local documents directly with upstream
|
|
commit `d84a38ebab26f048cafbe59a2246700c35d29843`, verified against published
|
|
`main` on 2026-09-28. Historical adoption baselines need not be reconstructed.
|
|
Do not imply that this revision was previously adopted.
|
|
|
|
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.
|
|
|
|
Narratio has five adopted policies without per-document Upstream Source links.
|
|
It lacks `docs/policy/meta.md`, `docs/policy/oss.md`, and the OSS attribution
|
|
collection. Its development guide has task routes but not the standard selective
|
|
policy-reading guidance. COPYRIGHT already grants GPL-3.0-or-later and LICENSE
|
|
contains GPLv3; only the separate policy-document licensing scope needs adding.
|
|
|
|
The release process already ends at successful tag publication to `origin`, uses
|
|
lightweight tags and source-push-before-tag, and publishes Gitea binaries and
|
|
checksums asynchronously. Current guidance requires standalone validation before
|
|
publication repeats it. The checker requires fixed note sections and repeats
|
|
documentation/example tests included in the full suite. These are alignment
|
|
work, not automatic justifications for different policy language.
|
|
|
|
## Policy Target
|
|
|
|
| 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. |
|
|
|
|
No existing policy is wholly unchanged because provenance and wording require
|
|
updates. Narratio's architectural decisions and agent commit behavior need no
|
|
substantive change. Wording preferences alone do not justify local variants.
|
|
|
|
## Provenance and Orientation
|
|
|
|
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:
|
|
|
|
```text
|
|
https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/FILE.md
|
|
```
|
|
|
|
Substitute the correct filename for each policy. Preserve accurate provenance in
|
|
later edits; Git records suffice without a new adoption registry or sync service.
|
|
|
|
Adapt upstream `agents/AGENTS.md` into root `AGENTS.md`, preserving applicable
|
|
existing instructions. Do not copy upstream's root agent instructions, which
|
|
govern work on that repository. Incorporate the supplied selective Policy Reading
|
|
Guide into `docs/development.md`: select by task, read before governed decisions,
|
|
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.
|
|
|
|
Meta links to the [public project](https://gitea.maximumdirect.net/eric/policy)
|
|
and [current adoption guide](https://gitea.maximumdirect.net/eric/policy/src/branch/main/docs/adoption.md).
|
|
These are current-discovery links; adopted-source and example links stay
|
|
commit-pinned. Reading triggers belong in development guidance and formal credit
|
|
in attribution, not duplicated in meta.
|
|
|
|
## Justified Local Customizations
|
|
|
|
Preserve established stage/adapter boundaries, manifest-driven resume/restore,
|
|
artifact/path contracts, publication and lock semantics, credential protections,
|
|
group-owned workspace behavior, and platform support. These express Narratio's
|
|
operational responsibilities; policy alignment does not authorize changing them.
|
|
|
|
Retain Linux amd64/arm64 and best-effort macOS arm64 deliverables, without new
|
|
native-platform gates or Windows/Intel Mac support. Preserve `origin/main`,
|
|
lightweight tags, and source-push-before-tag in the release procedure. These are
|
|
permitted project-specific mechanics, not exceptions to tag-push completion.
|
|
|
|
Customize documentation ownership for real Narratio interfaces and responsibilities,
|
|
including troubleshooting; do not create empty API/consumer documents. Keep common
|
|
prose verbatim around these customizations and explain substantive local choices
|
|
in their canonical owner rather than maintaining a parallel general policy essay.
|
|
|
|
## Licensing, Attribution, and Local Materials
|
|
|
|
Create `docs/oss/attribution.md` with the prescribed title followed directly by
|
|
factual component entries. Use the canonical Standard Repository Policies entry
|
|
from the reviewed commit. Identify actual copied/adapted material, including policy
|
|
files, adapted agent instructions, and copied reading-guide material as applicable.
|
|
Preserve creator, copyright, license, disclaimer, and modification notices. Pin
|
|
source, COPYRIGHT, and LICENSE links to the reviewed full commit.
|
|
|
|
Copy CC-BY-SA-4.0 into `docs/oss/licenses/`. Add the limited policy-document scope
|
|
to COPYRIGHT with an attribution link: adapted policy material remains CC-BY-SA-4.0;
|
|
Narratio's application code remains GPL-3.0-or-later. Root LICENSE needs no
|
|
replacement. Original upstream licensing-example formatting is CC0 and alone
|
|
does not require attribution.
|
|
|
|
Complete the previously agreed inventory of incorporated/distributed material:
|
|
relevant transitive dependencies, Go runtime material in shipped binaries, and
|
|
copied code, documentation, or assets. Inspect selected sources and actual use;
|
|
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.
|
|
|
|
Follow OSS v1.8's ordered fields and presentation: project heading, applicable
|
|
faithful copyright statements, applicable SPDX expression, license/notice links,
|
|
and a link labeled `Source` to the exact commit, ending with a period.
|
|
Optional identification remains factual. Preserve
|
|
alternatives, exceptions, and required notices; do not invent identifiers or add
|
|
research narratives, compliance conclusions, or exception reasoning to entries.
|
|
|
|
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.
|
|
|
|
Keep upstream's README, root AGENTS.md, development/adoption guides, and example
|
|
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.
|
|
|
|
End README with the prescribed grant and attribution links. Future release notes
|
|
and hosted pages end with `COPYRIGHT | LICENSE | ATTRIBUTION` links at their
|
|
immutable release tag or source revision. The procedure owns concrete Gitea URLs;
|
|
continue using the checked-in note as the hosted body. Maintain attribution with
|
|
relevant dependency/material changes through ordinary review.
|
|
|
|
## Coordinated Release Alignment
|
|
|
|
Update release policy, `docs/release.md`, relevant scripts, tests, and development
|
|
guidance together so rules and executable behavior agree:
|
|
|
|
- Make publication the normal validating-and-publishing entry point. Standalone
|
|
validation remains optional rather than a mandatory duplicate prior pass.
|
|
- Remove fixed release-note section requirements. Preserve version-matched notes
|
|
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. The implementation plan records the selected checks
|
|
and their distinct justification under these criteria.
|
|
- 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.
|
|
|
|
Expected implementation surfaces include `scripts/check-release-candidate.sh`,
|
|
`scripts/release.sh`, shared helpers/builders where needed, and release tests.
|
|
Review workflow references for consistency without expanding into unrelated CI
|
|
repair or application behavior changes.
|
|
|
|
## Boundaries and Completion Evidence
|
|
|
|
No application relicensing, automatic copyright-year advancement, blanket headers,
|
|
dependency upgrade, runtime feature, or platform expansion is included. Do not add
|
|
mandatory scanners, a full SBOM, recurring legal sign-offs, publication-time network
|
|
checks, or release approval gates. New downloadable license assets or packaging
|
|
formats are not required merely to implement the conventions; concrete component
|
|
obligations still require their applicable treatment.
|
|
|
|
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.
|
|
|
|
Completion requires comparison with the pinned source, accurate per-file metadata
|
|
and material attribution, justified variations, substantive supporting documents,
|
|
valid navigation, and complete applicable texts. Release procedures and tests must
|
|
prove the selected workflow and guards without duplicate mandatory validation or
|
|
CI waiting. Documentation checks and relevant release tests must pass. Merely
|
|
creating Markdown files is not evidence of alignment.
|
|
|
|
No product-level decision remains open from the approved review. Concrete rights
|
|
questions or gate tradeoffs unresolved by the risk-based approach must be surfaced
|
|
with evidence during planning, not silently converted into stronger requirements.
|