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 ## Purpose
Adopt the licensing-documentation conventions defined below while Bring Notarius's adopted policies into alignment with Standard Repository
preserving its deliberate policy adaptations, existing project grant, and Policies, using identical upstream language wherever a substantive,
source-only release process. This is a documentation and policy work set, not project-specific decision does not require customization. Preserve Notarius's
a relicensing, runtime, or release-automation project. 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 This roadmap defines the agreed target and update scope. It does not itself
not implement the policy or authorize release publication. 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 The agreed review, performed on 2026-09-28, uses full upstream commit
dependencies. The table records the selected policy-version targets; repository `d84a38ebab26f048cafbe59a2246700c35d29843` of
documentation must remain self-contained. [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/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/documentation.md` | 1.3 | 1.5 | Merge licensing ownership and discoverability rules. | | `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/release.md` | 1.1 | 1.2 | Add prospective release-footer guidance without new publication gates. | | `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. |
| Agents, architecture, testing | 1.1 | 1.1 | Retain existing substantive rules. | | `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 No existing policy remains entirely unchanged: all five need wording and/or
`GPL-3.0-or-later` grant, including the warranty disclaimer and third-party provenance updates. This does not imply new substantive testing or agent rules.
material statement. `LICENSE` contains the matching GPLv3 text. No substantive
license-text change is required.
Current gaps are the absent `docs/oss/` attribution materials, missing README ### Architecture Exceptions
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.
## 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 Keep concrete package inventories and implementation mechanics in their current
`docs/policy/oss.md`, adapted to Notarius. All links must resolve within this internal-documentation homes. No architecture redesign, new threat model, or
repository or to public authoritative sources; no adjacent checkout is required. new abstraction is part of this work.
Identify Notarius as an application with its already selected ### Documentation Exceptions
`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.
Merge the new documentation ownership rows and licensing boundary guidance into Notarius's consumer interface is primarily a subprocess CLI, not a public Go
Notarius's adapted documentation policy. Merge the release-footer provision API. Retain `docs/consumers/` ownership for that workflow and its consumer
into its adapted release policy. Do not replace either document wholesale. responsibilities. Retain integration contracts as the owners of durable receipt
Preserve subprocess-consumer ownership, prospective/current documentation and artifact shapes. No HTTP service documentation or placeholder API document
boundaries, immutable accepted ADRs, and the distinction between descriptive is needed.
implementation details and adopted policy.
Changed or newly adopted policies must record their base policy version and Other editorial variations should use upstream language, including the current
actual adoption date. Do not add private provenance headers, links, or attribution versus future behavior and accepted-ADR rules. Preserve their meaning without
entries. Unchanged policies need no version or date churn. retaining duplicate local formulations.
### Canonical Licensing Documentation ### Release Exceptions
| Path | Target responsibility | Preserve source-only delivery, lightweight tags, `main` on `origin`,
| --- | --- | branch-before-tag publication, and no prereleases. There are no binaries,
| `COPYRIGHT` | Existing project identity, copyright statement, SPDX expression, grant, disclaimer, and third-party scope statement. | hosted release objects, or asynchronous artifacts to publish or recover.
| `LICENSE` | Existing complete project license text. | Use upstream generic language where applicable, but do not introduce those
| `docs/policy/oss.md` | Licensing conventions, attribution format, maintenance, discoverability, and treatment of concrete exceptions. | channels or atomic-push requirements.
| `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. |
Retain the substance of `COPYRIGHT` and `LICENSE`. Adding a missing final newline Retain the native CLI build and injected-version check with `GOWORK=off`:
is optional formatting cleanup, not relicensing or a prerequisite to adoption. 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. ## Provenance And Selective Reading
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.
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; ```text
- `github.com/santhosh-tekuri/jsonschema/v6` v6.0.2; https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/testing.md
- `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.
``` ```
Add a contributor reading-guide entry that routes licensing, dependency, Substitute the correct filename for each policy; do not link every header to
attribution, and release-document changes to `docs/policy/oss.md` and the relevant the repository root or adoption guide. Retain provenance through subsequent
canonical materials. Update component entries in the same change that adds, local edits.
removes, upgrades, copies, or changes distribution of a relevant component.
The PromptKit integration guide should link to its canonical attribution entry Use current public discovery URLs in `meta.md`:
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.
### 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 Discovery links intentionally follow the current project and guide.
`COPYRIGHT | LICENSE | ATTRIBUTION`, using absolute URLs to the corresponding Adopted-source, example, and attribution links identify immutable commits.
Notarius files at the immutable release tag or source revision. Unlike upstream The OSS template already includes commit-pinned example references; retain
component attribution links, these release-navigation links may use the release accurate pinned references rather than converting them to branch links.
tag.
`docs/release.md` supplies a copyable footer using Notarius's Gitea repository Adapt upstream `agents/AGENTS.md` into root `AGENTS.md`, preserving applicable
and the selected release version. Check intended paths against the candidate existing instructions. Direct readers to `docs/development.md`, require agent
source during preparation; an unpublished tag need not resolve remotely yet. 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 Merge the upstream adoption guide's Policy Reading Guide into
release notes. It has no hosted release objects or separate download pages, so `docs/development.md`. Include all seven task triggers, especially policy
hosted-page guidance is currently inapplicable. Do not create updates, dependency/licensing changes, validation selection, and compatibility
another publication channel to satisfy it. Preserve branch-before-tag order, decisions. Preserve focused subsystem navigation without duplicating policy
the existing validation command, and successful tag push as release completion. 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, ## Licensing And Attribution Target
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.
## Scope Boundaries ### Copied Policy Material
- No application-code or dependency-version changes are needed for this work. Follow the selected upstream grant and canonical policy-attribution example:
- 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.
## 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 The upstream licensing-format examples are CC0; using their original formatting
on canonical ownership and preserve Notarius's deliberate adaptations. alone does not require a separate attribution entry. This does not exempt
- Policy metadata identifies the base policy version and actual adoption copied policy prose from its stated terms.
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.
There are no blocking design decisions at the reviewed baseline. Any concrete ### Incorporated Dependencies And Assets
unresolved upstream notice or rights issue found during inventory should be
recorded with its evidence rather than resolved by an invented blanket rule. 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.