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

Update the policy alignment roadmap

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-28 01:10:25 +00:00
parent 1301c445bb
commit ff9b05077c
1 changed files with 225 additions and 171 deletions
Download Patch File Download Diff File Expand all files Collapse all files

396
docs/roadmap/policy.md
View File

@@ -1,207 +1,261 @@
# Licensing Policy And Attribution Alignment
# Standard Repository Policy Alignment
## Purpose
Adopt the licensing-documentation conventions defined below while
preserving its deliberate policy adaptations, existing project grant, and
source-only release process. This is a documentation and policy work set, not
a relicensing, runtime, or release-automation project.
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 feature roadmap defines the target end state and required changes. It does
not implement the policy or authorize release publication.
This roadmap defines the agreed target and update scope. It does not itself
adopt policies, alter runtime behavior, or authorize a release.
## Reviewed Baseline
## Selected Upstream Revision And Current Baseline
Reviewed on 2026-09-26 against Notarius's current policy documents and pinned
dependencies. The table records the selected policy-version targets; repository
documentation must remain self-contained.
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`.
| Policy | Current Notarius baseline | Target version | Required change |
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/oss.md` | Absent | 1.2 | Adopt the licensing and attribution policy with Notarius-specific adaptation. |
| `docs/policy/documentation.md` | 1.3 | 1.5 | Merge licensing ownership and discoverability rules. |
| `docs/policy/release.md` | 1.1 | 1.2 | Add prospective release-footer guidance without new publication gates. |
| Agents, architecture, testing | 1.1 | 1.1 | Retain existing substantive rules. |
| `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. |
`COPYRIGHT` already identifies Notarius, its copyright statement, and the
`GPL-3.0-or-later` grant, including the warranty disclaimer and third-party
material statement. `LICENSE` contains the matching GPLv3 text. No substantive
license-text change is required.
No existing policy remains entirely unchanged: all five need wording and/or
provenance updates. This does not imply new substantive testing or agent rules.
Current gaps are the absent `docs/oss/` attribution materials, missing README
licensing navigation, missing contributor routing to an OSS policy, and missing
release-footer instructions. `docs/integrations/pkg-promptkit.md` currently
contains a dependency-license paragraph but is not a canonical attribution
inventory.
### Architecture Exceptions
## Target End State
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.
### Policy Alignment Without Policy Replacement
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.
Adopt the OSS House Format and maintenance rules defined below in
`docs/policy/oss.md`, adapted to Notarius. All links must resolve within this
repository or to public authoritative sources; no adjacent checkout is required.
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.
Identify Notarius as an application with its already selected
`GPL-3.0-or-later` grant. Preserve the distinction between licensing
defaults and explicit author choices: adopting the policy does not change
existing grants, infer different licenses for internal packages, automatically
advance copyright years, or assume ownership of third-party contributions.
### Documentation Exceptions
Merge the new documentation ownership rows and licensing boundary guidance into
Notarius's adapted documentation policy. Merge the release-footer provision
into its adapted release policy. Do not replace either document wholesale.
Preserve subprocess-consumer ownership, prospective/current documentation
boundaries, immutable accepted ADRs, and the distinction between descriptive
implementation details and adopted policy.
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.
Changed or newly adopted policies must record their base policy version and
actual adoption date. Do not add private provenance headers, links, or attribution
entries. Unchanged policies need no version or date churn.
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.
### Canonical Licensing Documentation
### Release Exceptions
| Path | Target responsibility |
| --- | --- |
| `COPYRIGHT` | Existing project identity, copyright statement, SPDX expression, grant, disclaimer, and third-party scope statement. |
| `LICENSE` | Existing complete project license text. |
| `docs/policy/oss.md` | Licensing conventions, attribution format, maintenance, discoverability, and treatment of concrete exceptions. |
| `docs/oss/attribution.md` | Canonical component-specific attribution entries. |
| `docs/oss/licenses/` | Applicable complete, verbatim standard dependency license texts, including required companion texts. |
| `README.md` | Friendly navigation to the project grant and attribution. |
| `docs/development.md` | Task-specific routing for licensing, dependency, attribution, and release-document changes. |
| `docs/release.md` | Concrete release-footer URLs and preparation instructions for Notarius's existing publication channel. |
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 substance of `COPYRIGHT` and `LICENSE`. Adding a missing final newline
is optional formatting cleanup, not relicensing or a prerequisite to adoption.
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.
### Attribution Based On Actual Incorporated Components
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.
Inventory relevant direct and transitive dependencies and copied code/assets.
Use `go.mod`, the resolved dependency/build graph, pinned module contents, and
repository evidence to identify scope; do not treat either direct dependencies
alone or every `go.sum` entry as the complete attribution inventory. Development
tools do not automatically require entries merely because maintainers use them.
## Provenance And Selective Reading
The current module declarations identify these starting points:
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:
- ConfigKit v0.4.1 and PromptKit v0.11.1;
- `github.com/santhosh-tekuri/jsonschema/v6` v6.0.2;
- `golang.org/x/text` v0.40.0;
- `gopkg.in/yaml.v3` v3.0.1 and `go.yaml.in/yaml/v4` v4.0.0-rc.6;
- PromptKit's OpenRouter and Rakestrawhome backend catalogs at their pinned
v2.20260926.0 revisions (now MIT licensed).
This list is an inspection starting point, not a pre-approved license inventory.
Verify each relevant component's terms, notices, and exact source revision at
the imported version; do not infer them from a newer sibling checkout or common
project ownership. Inspect copied material separately from Go module imports.
Each attribution entry follows the five-field House Format:
1. Project name.
2. Upstream copyright statement or statements, preserving their wording.
3. Applicable SPDX identifier or expression, preserving alternatives/exceptions.
4. License and notice links.
5. Corresponding source repository link.
Copy only applicable standard license texts from public authoritative sources,
such as the license publisher or the verified dependency release.
Preserve them verbatim and keep explanations outside the texts. Shared standard
texts may serve multiple entries. Include directly reachable companion texts;
for example, an LGPLv3 entry must link to both LGPLv3 and GPLv3 texts.
Component source and project-specific notice links must identify the exact
imported commit, not a branch or version tag. Determine those commits from
authoritative module/VCS metadata; do not guess them. Classify upstream files
by their contents: `LICENSE` or `COPYING` can contain project-specific statements
as well as standard wording.
Use the selected convention that direct links to project-specific
notices satisfy the notice-reproduction format. Do not add local copies or
repeated approval requirements solely because license language refers to
reproduction or inclusion. Preserve notices already present in incorporated
source. Concrete obligations or unresolved rights questions outside this
convention receive their own documented treatment; the formatting policy is not
a blanket license-compatibility determination.
### Discoverability And Maintenance
End README with these links, consistent with the existing project grant:
```markdown
Notarius is licensed under the [GPL v3.0 or later](COPYRIGHT).
[Open Source attribution notices](docs/oss/attribution.md) are available.
```text
https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/testing.md
```
Add a contributor reading-guide entry that routes licensing, dependency,
attribution, and release-document changes to `docs/policy/oss.md` and the relevant
canonical materials. Update component entries in the same change that adds,
removes, upgrades, copies, or changes distribution of a relevant component.
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.
The PromptKit integration guide should link to its canonical attribution entry
instead of maintaining a competing notice inventory. Keep integration behavior
and pinned API documentation in that guide; the exact-commit rule for attribution
links does not require rewriting unrelated API-reference links.
Use current public discovery URLs in `meta.md`:
### Prospective Release Navigation
- https://gitea.maximumdirect.net/eric/policy
- https://gitea.maximumdirect.net/eric/policy/src/branch/main/docs/adoption.md
New release notes end with links whose visible text is
`COPYRIGHT | LICENSE | ATTRIBUTION`, using absolute URLs to the corresponding
Notarius files at the immutable release tag or source revision. Unlike upstream
component attribution links, these release-navigation links may use the release
tag.
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.
`docs/release.md` supplies a copyable footer using Notarius's Gitea repository
and the selected release version. Check intended paths against the candidate
source during preparation; an unpublished tag need not resolve remotely yet.
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.
Notarius continues publishing source through lightweight Git tags and checked-in
release notes. It has no hosted release objects or separate download pages, so
hosted-page guidance is currently inapplicable. Do not create
another publication channel to satisfy it. Preserve branch-before-tag order,
the existing validation command, and successful tag push as release completion.
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.
Apply the formatting convention prospectively. Do not rewrite historical notes,
published tags, or accepted ADRs merely to retrofit navigation. Handle any actual
omission discovered during inventory deliberately under the applicable policy,
not by changing published history.
## Licensing And Attribution Target
## Scope Boundaries
### Copied Policy Material
- No application-code or dependency-version changes are needed for this work.
- No substantive rewrite of the existing project grant is proposed.
- No new ADR is needed merely to adopt these explicit policy choices.
- No mandatory license scanner, SBOM, blanket per-file header sweep, recurring
legal sign-off, or full dependency security audit is introduced.
- No publication-time network check, CI polling, extra approval gate, binary
packaging, or release-script redesign is introduced.
- Do not copy unused standard license texts or create placeholder documentation.
- Do not weaken or strengthen unrelated Notarius invariants and operator choices.
Follow the selected upstream grant and canonical policy-attribution example:
## Acceptance And Verification
- 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 adopted OSS policy, documentation policy 1.5, and release policy 1.2 agree
on canonical ownership and preserve Notarius's deliberate adaptations.
- Policy metadata identifies the base policy version and actual adoption
date, without private provenance; unchanged policies retain their existing
metadata.
- Project licensing statements remain consistent with `GPL-3.0-or-later`.
- Attribution covers the relevant incorporated components identified by the
inventory, including applicable transitive dependencies and copied material.
Entries preserve upstream statements and use verified exact-commit links.
- Applicable local standard texts are complete and faithful, with companion
texts directly reachable from their entries. No unrelated license bundle is
imported.
- README, contributor guidance, integration references, and the release runbook
link to canonical materials without duplicating the attribution inventory.
- New-release footer instructions work with the existing source-only workflow;
historical releases and publication mechanics are unchanged.
- Review edited relative links, source/notice destinations, SPDX expressions,
and standard-text comparisons, and run `git diff --check`. This documentation
change does not itself warrant production model runs or new runtime tests.
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.
There are no blocking design decisions at the reviewed baseline. Any concrete
unresolved upstream notice or rights issue found during inventory should be
recorded with its evidence rather than resolved by an invented blanket rule.
### 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.
## Recommended Work Sequence
1. Adopt the policy set and orientation changes together with copied-policy
attribution, its local license text, and the COPYRIGHT scope statement.
Keep cross-links valid at this boundary.
2. Complete incorporated-component attribution and applicable license texts;
connect README, integration guidance, and prospective release navigation.
3. Compare the result directly with the selected upstream files, verify that
remaining variations have the stated local justification, and check notices,
metadata, and links.
These are coherent work boundaries, not authorization to execute them during
roadmap preparation. A later implementation plan may subdivide them.
## 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.