253 lines
14 KiB
Markdown
253 lines
14 KiB
Markdown
# Standard Repository Policy Alignment
|
|
|
|
## Purpose
|
|
|
|
Bring Notarius's adopted policies into alignment with Standard Repository
|
|
Policies, using identical upstream language wherever a substantive,
|
|
project-specific decision does not require customization. Preserve Notarius's
|
|
application contracts, operator choices, selected code license, and source-only
|
|
release process.
|
|
|
|
This roadmap defines the agreed target and update scope. It does not itself
|
|
adopt policies, alter runtime behavior, or authorize a release.
|
|
|
|
## Selected Upstream Revision And Current Baseline
|
|
|
|
The agreed review, performed on 2026-09-28, uses full upstream commit
|
|
`d84a38ebab26f048cafbe59a2246700c35d29843` of
|
|
[Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy).
|
|
Follow the [adoption and update guide at that revision](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md).
|
|
Use that fixed revision for implementation, not whichever revision is then on
|
|
`main`.
|
|
|
|
The comparison is between the current Notarius documents and that revision.
|
|
Historical adoption baselines need not be reconstructed or assessed. Introducing
|
|
source metadata records the revision actually incorporated by this update, not
|
|
a claim about previous adoptions.
|
|
|
|
Notarius currently has five policies, no `meta.md` or `oss.md`, and no
|
|
`docs/oss/` attribution collection. Its current agent entry point and developer
|
|
guide provide orientation but lack the complete selective policy-reading guide.
|
|
The project grant is GPL-3.0-or-later; root `LICENSE` contains the GPLv3 text.
|
|
README licensing navigation and prospective release-footer instructions are
|
|
missing.
|
|
|
|
Public upstream discovery and attribution are now expressly approved. This
|
|
supersedes the earlier instruction to omit references to the policy source;
|
|
local checkout paths are neither necessary nor appropriate public references.
|
|
|
|
## Alignment Rules
|
|
|
|
- Start from the selected upstream wording, not a paraphrase of it. Adopt
|
|
non-substantive wording changes verbatim.
|
|
- Retain local variations only for substantive, locally significant
|
|
requirements or decisions. Explain their purpose in the relevant policy
|
|
section or link to existing rationale; do not add a separate exception registry.
|
|
- Follow each template's adoption instructions and remove its entire
|
|
`Base Policy Template` section. Replace required project-specific guidance
|
|
rather than leaving template instructions in an adopted policy.
|
|
- Preserve deliberately selected contracts. Simplifying duplicate wording does
|
|
not authorize changing architecture, runtime behavior, or release mechanics.
|
|
- Keep local policies authoritative. Upstream changes take effect only through
|
|
deliberate adoption; no automatic synchronization is introduced.
|
|
|
|
## Target Policy Set And Justified Customizations
|
|
|
|
| Local file | Current version | Target version | Required treatment |
|
|
| --- | --- | --- | --- |
|
|
| `docs/policy/agents.md` | 1.1 | 1.3 | Adopt substantive upstream wording verbatim. Remove redundant local preamble and the ADR-0017 illustration; architecture already owns the deployment-permissions decision. No substantive exception is needed. |
|
|
| `docs/policy/architecture.md` | 1.1 | 1.3 | Adopt general purpose, ownership, architectural approach, and constraint-versus-implementation guidance while retaining the application-specific decisions described below. |
|
|
| `docs/policy/testing.md` | 1.1 | 1.3 | Adopt substantive upstream wording verbatim. Existing risk-based testing remains intact; no project-specific exception or test rewrite is needed. |
|
|
| `docs/policy/documentation.md` | 1.3 | 1.11 | Adopt upstream wording and licensing/provenance ownership rows. Customize consumer ownership for subprocess use and omit the inapplicable HTTP-contract row. Remove the duplicate local implementation-details-versus-policy section; agent policy owns that rule. |
|
|
| `docs/policy/release.md` | 1.1 | 1.4 | Adopt upstream wording with the existing source-only choices and selected gates below. Add prospective OSS-footer guidance. |
|
|
| `docs/policy/meta.md` | Absent | 1.0 | Add upstream substantive wording, including public discovery links, local authority, and local attribution navigation. |
|
|
| `docs/policy/oss.md` | Absent | 1.8 | Add upstream substantive wording, commit-pinned example links, and required Notarius context through canonical documents. |
|
|
|
|
No existing policy remains entirely unchanged: all five need wording and/or
|
|
provenance updates. This does not imply new substantive testing or agent rules.
|
|
|
|
### Architecture Exceptions
|
|
|
|
The architecture template expressly requires application-specific content.
|
|
Retain Notarius's fixed stage sequence rather than an arbitrary DAG,
|
|
artifact-family ownership across stages, domain-neutral framework, inward
|
|
dependency direction, external adapter boundaries, and content-only assets
|
|
package. Retain adopted validation/retry, scheduling, identity, evidence,
|
|
configuration, and provenance contracts.
|
|
|
|
Preserve operator-owned filesystem access policy and the separately adopted
|
|
correctness boundaries, cache/checkpoint eligibility, output/debug lifecycle,
|
|
secret handling, and platform/distribution decisions. These express existing
|
|
product requirements and ADR-backed choices, not stylistic variations.
|
|
Use existing architecture and ADRs as their authority; this migration does not
|
|
authorize strengthening or weakening them.
|
|
|
|
Keep concrete package inventories and implementation mechanics in their current
|
|
internal-documentation homes. No architecture redesign, new threat model, or
|
|
new abstraction is part of this work.
|
|
|
|
### Documentation Exceptions
|
|
|
|
Notarius's consumer interface is primarily a subprocess CLI, not a public Go
|
|
API. Retain `docs/consumers/` ownership for that workflow and its consumer
|
|
responsibilities. Retain integration contracts as the owners of durable receipt
|
|
and artifact shapes. No HTTP service documentation or placeholder API document
|
|
is needed.
|
|
|
|
Other editorial variations should use upstream language, including the current
|
|
versus future behavior and accepted-ADR rules. Preserve their meaning without
|
|
retaining duplicate local formulations.
|
|
|
|
### Release Exceptions
|
|
|
|
Preserve source-only delivery, lightweight tags, `main` on `origin`,
|
|
branch-before-tag publication, and no prereleases. There are no binaries,
|
|
hosted release objects, or asynchronous artifacts to publish or recover.
|
|
Use upstream generic language where applicable, but do not introduce those
|
|
channels or atomic-push requirements.
|
|
|
|
Retain the native CLI build and injected-version check with `GOWORK=off`:
|
|
it protects the executable entry point and release version, which package tests
|
|
alone do not verify. Preserve its documented rationale and existing optional
|
|
diagnostics. No additional validation gate is warranted.
|
|
|
|
Retain the decision not to create retrospective notes for v0.1.0, v0.2.0, or
|
|
v0.3.0. Apply new footer formatting prospectively; do not rewrite published
|
|
history to retrofit it.
|
|
|
|
## Provenance And Selective Reading
|
|
|
|
Each of the seven policies must retain its actual target `Base Policy Version`,
|
|
set `Last Updated` to its actual local adoption date, and add an
|
|
`Upstream Source` link to its own source file. For example:
|
|
|
|
```text
|
|
https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/testing.md
|
|
```
|
|
|
|
Substitute the correct filename for each policy; do not link every header to
|
|
the repository root or adoption guide. Retain provenance through subsequent
|
|
local edits.
|
|
|
|
Use current public discovery URLs in `meta.md`:
|
|
|
|
- https://gitea.maximumdirect.net/eric/policy
|
|
- https://gitea.maximumdirect.net/eric/policy/src/branch/main/docs/adoption.md
|
|
|
|
Discovery links intentionally follow the current project and guide.
|
|
Adopted-source, example, and attribution links identify immutable commits.
|
|
The OSS template already includes commit-pinned example references; retain
|
|
accurate pinned references rather than converting them to branch links.
|
|
|
|
Adapt upstream `agents/AGENTS.md` into root `AGENTS.md`, preserving applicable
|
|
existing instructions. Direct readers to `docs/development.md`, require agent
|
|
policy before recommending/planning/implementing changes, and explicitly avoid
|
|
reading the whole policy suite by default.
|
|
|
|
Merge the upstream adoption guide's Policy Reading Guide into
|
|
`docs/development.md`. Include all seven task triggers, especially policy
|
|
updates, dependency/licensing changes, validation selection, and compatibility
|
|
decisions. Preserve focused subsystem navigation without duplicating policy
|
|
triggers across competing tables. Reuse policies already in context, expand
|
|
reading when scope expands, and read affected cross-policy provisions when
|
|
revising a policy.
|
|
|
|
## Licensing And Attribution Target
|
|
|
|
### Copied Policy Material
|
|
|
|
Follow the selected upstream grant and canonical policy-attribution example:
|
|
|
|
- Create `docs/oss/attribution.md` with the House Format title and insert the
|
|
Standard Repository Policies entry using the selected full commit for its
|
|
source, COPYRIGHT, and LICENSE URLs.
|
|
- Identify actual copied/adapted material and modification status. Include
|
|
`docs/policy/`, the adapted root `AGENTS.md`, and the copied policy-reading
|
|
guide within `docs/development.md` as applicable. Do not claim unrelated
|
|
developer documentation was copied or relicense unrelated material.
|
|
- Preserve supplied copyright, license, and disclaimer notices through the
|
|
specified arrangement; keep the entry factual rather than adding compliance
|
|
or research commentary.
|
|
- Copy the complete, verbatim `CC-BY-SA-4.0.txt` to `docs/oss/licenses/`.
|
|
- Add the separately licensed policy-material scope to `COPYRIGHT`, pointing
|
|
to attribution for exact scope and notices. Adapted policy material remains
|
|
CC-BY-SA-4.0; application code remains GPL-3.0-or-later. Leave root `LICENSE`
|
|
unchanged.
|
|
|
|
The upstream licensing-format examples are CC0; using their original formatting
|
|
alone does not require a separate attribution entry. This does not exempt
|
|
copied policy prose from its stated terms.
|
|
|
|
### Incorporated Dependencies And Assets
|
|
|
|
Complete the previously planned inventory of relevant direct/transitive
|
|
dependencies and copied code/assets using `go.mod`, resolved build dependencies,
|
|
and exact pinned source contents. Neither direct imports alone nor every
|
|
`go.sum` entry defines the inventory.
|
|
|
|
Current starting points are ConfigKit v0.4.1, PromptKit v0.11.1, both PromptKit
|
|
backend catalogs v2.20260926.0, jsonschema/v6 v6.0.2, x/text v0.40.0, yaml.v3
|
|
v3.0.1, and yaml/v4 v4.0.0-rc.6. Verify actual incorporation, terms, notices,
|
|
and exact commits; this list is not a pre-approved attribution inventory.
|
|
|
|
Use the upstream OSS House Format without editorial elaboration. Copy only
|
|
applicable standard and companion license texts, retaining their wording.
|
|
Link component-specific notices and sources at the exact imported commit.
|
|
Apply the upstream house interpretation of linked notices without inventing
|
|
extra local-copy requirements, recurring approvals, or licensing conclusions.
|
|
Handle a concrete uncovered obligation separately if one is discovered.
|
|
|
|
### Navigation And Canonical Ownership
|
|
|
|
- End `README.md` with the project-grant and attribution links prescribed by
|
|
OSS policy, using Notarius's GPL-3.0-or-later grant.
|
|
- Update `docs/release.md` with a copyable prospective
|
|
`COPYRIGHT | LICENSE | ATTRIBUTION` footer using absolute Notarius URLs at
|
|
the release tag or corresponding immutable source revision. Check intended
|
|
local paths before publication; do not require an unpublished tag to resolve.
|
|
- Update `docs/integrations/pkg-configkit.md` and
|
|
`docs/integrations/pkg-promptkit.md` to link to canonical attribution rather
|
|
than maintaining competing notice inventories. Keep behavioral/API references
|
|
in those integration guides.
|
|
|
|
## Local Materials And Upstream-Only References
|
|
|
|
Keep the seven adopted policies, adapted agent entry point, project-specific
|
|
developer guide, actual notices, and applicable license texts locally.
|
|
|
|
Keep the upstream README, root AGENTS.md, contributor guide, adoption guide,
|
|
and example collection upstream. Link to them when appropriate instead of
|
|
copying an additional documentation tree. Do not copy unused license texts,
|
|
example projects, or placeholder documents. Root Notarius `AGENTS.md` is based
|
|
on upstream `agents/AGENTS.md`, not upstream's own contributor instructions.
|
|
|
|
## Implementation Ownership
|
|
|
|
[Implementation Plan](implementation.md) owns the ordered work stages and their
|
|
validation. This document owns the target end state, scope, and policy choices.
|
|
|
|
## Scope Boundaries And Acceptance
|
|
|
|
- No application code, dependency pins, tests, release scripts, or published
|
|
history change merely to adopt policy wording.
|
|
- No new ADR, recurring policy-sync job, SBOM, scanner, blanket header sweep,
|
|
security audit, platform matrix, approval round, or release gate is required.
|
|
- All seven policies use the selected versions and correct file-specific source
|
|
links, with actual adoption dates and no remaining template-only sections.
|
|
- Non-substantive differences use upstream wording; substantive variations are
|
|
confined to justified Notarius responsibilities and decisions.
|
|
- Orientation supports selective reading and public upstream discovery without
|
|
requiring a sibling checkout.
|
|
- Attribution accurately identifies copied material, modifications, selected
|
|
dependency revisions, notices, and faithful local license texts. Application
|
|
and policy-material license scopes remain distinct.
|
|
- Canonical navigation works without duplicate notice inventories, nonexistent
|
|
interface documents, or copied upstream guide/example collections.
|
|
- Validate affected relative and public links, metadata targets, license-text
|
|
fidelity, and `git diff --check`. Ordinary document review is sufficient;
|
|
production model runs and new runtime tests are not warranted.
|
|
- Resolve only concrete newly discovered rights or scope issues with the user;
|
|
do not reopen settled choices through blanket approval requirements.
|
|
|
|
There are no blocking open design decisions at the agreed review baseline.
|