314 lines
20 KiB
Markdown
314 lines
20 KiB
Markdown
# Implementation Plan: Standard Policy Alignment
|
||
|
||
**Last updated:** 2026-09-28
|
||
|
||
**Status:** Complete; Stages 1–4 implemented.
|
||
**Audience:** gpt-5.6-terra coding agent.
|
||
**Audita planning baseline:** `91d9be68a7bb3a102900253fdfd8438f0a43f666`.
|
||
**Selected upstream revision:** `d84a38ebab26f048cafbe59a2246700c35d29843`.
|
||
|
||
## Scope and Execution
|
||
|
||
Implement the accepted [Standard Policy Alignment roadmap](policy.md). It owns
|
||
the intended end state and reasons for local variations; this plan owns ordered
|
||
implementation and verification. Complete Stage 1 through Stage 4 in order, each
|
||
as one focused agent task. Record completion evidence under each stage and commit
|
||
completed units with short, plain English messages under the agent policy.
|
||
|
||
Begin with [development guidance](../development.md) and the
|
||
[agent policy](../policy/agents.md). Read the policies governing each stage;
|
||
reuse unchanged policy context. For policy edits, read that policy and affected
|
||
cross-references. Follow the adopted selective reading guide once installed.
|
||
Use graph-first discovery for application code; document and shell/configuration
|
||
inspection does not need a graph lookup.
|
||
|
||
Use the public upstream repository at
|
||
`https://gitea.maximumdirect.net/eric/policy` and check out the exact revision above
|
||
in a temporary directory outside Audita. Verify its full commit before copying.
|
||
Read its `docs/adoption.md`, relevant `docs/policy/` files, `COPYRIGHT`, and
|
||
referenced assets. Do not replace the selected revision with current main or
|
||
reconstruct prior adoption baselines. The public repository and its attribution
|
||
are now explicitly approved.
|
||
|
||
This plan replaces the completed decision-set plan, preserved at
|
||
[the planning baseline](https://gitea.maximumdirect.net/eric/audita/src/commit/91d9be68a7bb3a102900253fdfd8438f0a43f666/docs/roadmap/implementation.md).
|
||
Repair historical roadmap references in Stage 4; do not reopen those features.
|
||
|
||
Implement directly toward the final state. Intermediate commits need no temporary
|
||
policy files, compatibility machinery, or complete dependency inventory. Keep
|
||
partial work truthful and finish cross-document consistency by Stage 4. Do not
|
||
release, tag, push, rewrite published material, change dependency versions, or
|
||
refactor application code as part of this work. No extra approval round is needed
|
||
between stages. If factual verification uncovers a concrete unresolved rights or
|
||
publication issue, report it rather than inventing an obligation or claiming it
|
||
resolved.
|
||
|
||
## Common Adoption Decisions
|
||
|
||
- Start each policy from the selected upstream file. Preserve shared substantive
|
||
wording verbatim. Remove its `Base Policy Template` section after fulfilling
|
||
the instructions; include only the project customizations selected below.
|
||
- Retain the upstream base version and set `Last Updated` to the actual adoption
|
||
date. Add `**Upstream Source:**` with a Markdown link to that same file at the
|
||
full selected commit, using the URL prefix
|
||
`https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/`.
|
||
Do not claim this was the source of old local documents.
|
||
- Keep discovery URLs in `meta.md` pointed to the public repository and
|
||
`/src/branch/main/docs/adoption.md`. Pin example links in the adopted OSS policy
|
||
to this selected commit, after checking their paths. Preserve examples upstream.
|
||
- Explain substantive local variations briefly where they apply. No separate
|
||
exception register, synchronization system, policy snapshot tests, or legal
|
||
approval workflow is needed.
|
||
- Keep policy credit in the single canonical attribution entry. Describe only
|
||
material adopted so far, expanding it as later stages copy more material.
|
||
Metadata and template removal mean an adopted file can truthfully be described
|
||
as adapted even when its substantive rules are verbatim.
|
||
- Ordinary link/text review is sufficient for documentation changes. Do not run
|
||
application tests simply because a policy document changed. Each stage ends
|
||
with `git diff --check` and review of its staged diff before committing.
|
||
|
||
## Stage 1 — Establish Provenance and Shared Agent/Testing Policies
|
||
|
||
**Completed:** 2026-09-28. Adopted meta 1.0, agents 1.3, and testing 1.3 from
|
||
the verified upstream commit, preserving Audita's graph-first discovery rule.
|
||
The initial attribution and scoped copyright notice identify only these three
|
||
adapted policies; the CC-BY-SA text matches upstream byte-for-byte. Substantive
|
||
policy text, pinned source paths, local links, and `git diff --check` were checked.
|
||
|
||
**Files:** `docs/policy/meta.md`, `docs/policy/agents.md`,
|
||
`docs/policy/testing.md`, `docs/oss/attribution.md`,
|
||
`docs/oss/licenses/CC-BY-SA-4.0.txt`, and `COPYRIGHT`.
|
||
|
||
1. Adopt meta 1.0, agents 1.3, and testing 1.3 with the common metadata and
|
||
template-removal rules. Preserve the existing Codebase Discovery section as
|
||
the one local addition to agents: Audita deliberately uses graph-first
|
||
discovery. Adopt the remaining agent rules and the testing rules verbatim.
|
||
2. Create attribution with `# Open Source Attribution Notices`, followed directly
|
||
by the canonical entry from `examples/licensing/policy-attribution.md`.
|
||
Substitute the selected commit in its COPYRIGHT, LICENSE, and Source URLs.
|
||
Initially identify the three newly adapted policy files in its `Material:`
|
||
sentence. Do not claim the remaining files have already been updated.
|
||
3. Copy the selected revision's `docs/oss/licenses/CC-BY-SA-4.0.txt` byte-for-byte.
|
||
Keep the supplied upstream copyright and links to its grant/disclaimer.
|
||
4. Add the adoption guide's scoped CC-BY-SA notice to Audita's `COPYRIGHT`, with
|
||
affected material identified through attribution. Preserve Audita's name,
|
||
copyright, GPL-3.0-or-later application grant, warranty statement, and third-party
|
||
statement. Leave the root GPLv3 `LICENSE` unchanged.
|
||
5. Keep metadata local and truthful. `meta.md` points to the local attribution
|
||
and developer guide even though selective reading guidance is added next.
|
||
|
||
**Validation and completion:** Compare the substantive agent/testing text directly
|
||
with the selected upstream documents, allowing only template removal, metadata,
|
||
and the identified discovery addition. Verify each new source link's exact file
|
||
and revision, local attribution links, copied license bytes, and narrow grant
|
||
scope. No application test or publication is required.
|
||
|
||
## Stage 2 — Customize Remaining Policies and Install Selective Orientation
|
||
|
||
**Completed:** 2026-09-28. Adopted architecture 1.3, documentation 1.11,
|
||
release 1.4, and OSS 1.8 with the selected Audita variations. Installed the
|
||
upstream root orientation and verbatim Policy Reading Guide, expanded the
|
||
scoped attribution, and repaired the release documentation heading link.
|
||
Checked versions, provenance and example destinations, local links, policy
|
||
differences, and `git diff --check`.
|
||
|
||
**Files:** `docs/policy/architecture.md`, `docs/policy/documentation.md`,
|
||
`docs/policy/release.md`, `docs/policy/oss.md`, `AGENTS.md`,
|
||
`docs/development.md`, `docs/oss/attribution.md`, and `COPYRIGHT` as needed for
|
||
accurate copied-guidance scope.
|
||
|
||
1. Adopt architecture 1.3. Retain the upstream general Purpose And Ownership,
|
||
Architectural Approach, and Adopted Constraints And Implemented Structure
|
||
guidance. Replace Application-Specific Topics with Audita's established
|
||
purpose, ownership/dependency boundaries, correction/concurrency rules,
|
||
recovery, state/compatibility, secret handling, and selected library ownership.
|
||
Reuse existing local decisions; avoid duplicating general upstream prose.
|
||
Replace example threat discussion with the existing secret/input boundaries
|
||
and canonical links where useful. Do not infer new threat exclusions,
|
||
filesystem guarantees, interfaces, or package restructuring from the template.
|
||
2. Adopt documentation 1.11. Keep applicable upstream ownership rows verbatim;
|
||
omit public HTTP and public Go API rows. Add the existing concrete ownership
|
||
of `docs/integrations/output-files.md` and contributor change recipes, and
|
||
retain the deliberate retirement of standalone troubleshooting documentation.
|
||
Account for the retained agent discovery/commit responsibilities in its owner
|
||
row. Keep reading triggers in development guidance, not a second policy table.
|
||
3. Adopt release 1.4. Retain upstream completion, validation, guard, immutability,
|
||
recovery, and preparation language. Preserve the existing Supported Platforms
|
||
table and unsupported-platform statement as Audita's support commitment.
|
||
Replace the upstream discretionary human-gate paragraph with Audita's selected
|
||
rule against manual approvals, sign-offs, and routine confirmations as release
|
||
gates. Remove the obsolete list describing now-shared upstream rules as local
|
||
deviations. Keep concrete atomic-push mechanics in the runbook.
|
||
4. Adopt OSS 1.8. Add a concise Audita context paragraph identifying the existing
|
||
GPL-3.0-or-later grant and linking to COPYRIGHT and the release procedure for
|
||
Gitea distribution. Use the upstream House Format and interpretation language
|
||
verbatim. Pin application/library COPYRIGHT and attribution examples to the
|
||
selected upstream commit; remove template-only setup text. No license change
|
||
to application code or blanket dependency compatibility claim is authorized.
|
||
5. Replace root orientation with upstream `agents/AGENTS.md` wording while
|
||
retaining any existing applicable repository instructions. Keep detailed
|
||
discovery rules in their current agent-policy owner rather than duplicating
|
||
them in a newly created block.
|
||
6. Insert the adoption guide's Policy Reading Guide and accompanying reading rules
|
||
into `docs/development.md` verbatim. Remove the blanket architecture-reading
|
||
instruction; preserve contributor commands and component-specific task rows.
|
||
Adjust cross-links that would otherwise contradict selective reading.
|
||
7. Expand the single policy attribution entry to identify all `docs/policy/`
|
||
documents, adapted root orientation, and the copied Policy Reading Guide in
|
||
`docs/development.md`. Scope the COPYRIGHT CC-BY-SA notice to those materials,
|
||
not unrelated contributor prose or application documentation. Keep the material
|
||
sentence factual and concise; retain the pinned upstream credit links.
|
||
8. Find and repair local links to policy headings renamed by adoption, including
|
||
the release correction heading. Do not edit published historical release
|
||
notes to retrofit new headings or licensing conventions.
|
||
|
||
**Validation and completion:** Compare all seven policies to the pinned source;
|
||
review every substantive difference against the roadmap's justified variations.
|
||
Check versions (1.3, 1.3, 1.11, 1.3, 1.4, 1.0, 1.8 for agents, architecture,
|
||
documentation, testing, release, meta, OSS respectively), file-specific source
|
||
links, removed template sections, example destinations, ownership consistency,
|
||
and selective reading. Temporary pending release/attribution implementation is
|
||
completed by the following stages; do not create scaffolding for it.
|
||
|
||
## Stage 3 — Complete Component Attribution and README Navigation
|
||
|
||
**Completed:** 2026-09-28. Both CGO-disabled Linux target dependency lists
|
||
selected the same eight production modules. Inspected their selected source
|
||
notices and copied assets, excluded test-only dependencies, and resolved the
|
||
Go 1.25.5 source tag and its four incorporated vendored modules. Added 14
|
||
House Format entries including policy provenance, complete applicable license
|
||
texts, and the README footer. Checked 33 pinned source and notice destinations,
|
||
license bytes, local links, entry shape, and `git diff --check`.
|
||
|
||
**Files:** `docs/oss/attribution.md`, applicable texts under
|
||
`docs/oss/licenses/`, and `README.md`. Add factual exception treatment to the OSS
|
||
policy only if the actual inventory uncovers a concrete need.
|
||
|
||
1. Inventory actual incorporated material using the selected modules, production
|
||
package dependencies for both Linux targets, source/assets, and shipped Go
|
||
runtime. Use `go list -deps` for `./cmd/audita` with `CGO_ENABLED=0` and each
|
||
target architecture, plus source inspection for copied material. Inspect test
|
||
dependencies where relevant to included material; a go.mod entry or tool use
|
||
alone is not sufficient reason for attribution. Do not change go.mod/go.sum.
|
||
2. At the planning baseline, production dependencies include ConfigKit v0.4.1,
|
||
PromptKit v0.11.1, both catalogs v2.20260926.0, jsonschema/v6 v6.0.2,
|
||
yaml/v4 v4.0.0-rc.6, x/text v0.14.0, and yaml.v3 v3.0.1. Start with the four
|
||
verified source commits recorded in the feature roadmap; resolve remaining
|
||
module versions to exact source commits and inspect their COPYRIGHT, LICENSE,
|
||
NOTICE, PATENTS, and relevant bundled material as applicable. Account for
|
||
additional material discovered in that inspection rather than treating this
|
||
starting list as an exhaustive guarantee.
|
||
3. For the Go runtime, use the release build's configured Go 1.25.5 source tag
|
||
and resolve it to its full source commit. Do not silently substitute the
|
||
inspecting agent's installed toolchain (Go 1.26.8 during planning). Preserve
|
||
actual runtime/standard-library notices, including relevant bundled third-party
|
||
material. Document maintenance of this entry when the distributed toolchain
|
||
changes; do not pin new toolchain behavior or reject other supported local Go
|
||
versions merely to simplify attribution.
|
||
4. Add entries following OSS 1.8 exactly, with selected module/version or material
|
||
scope where useful. Preserve supplied copyrights and accurate license
|
||
expressions; use the prescribed link labels and `[Source](COMMIT_URL).`
|
||
spelling. Keep policy attribution first. Order other entries consistently by
|
||
project name; ordering is presentation, not a new public contract.
|
||
5. Copy applicable complete standard texts from verified sources, using the
|
||
pinned reference collection where applicable. Share identical standard texts
|
||
and include required companions (LGPLv3 and GPLv3 for the two libraries).
|
||
Include upstream commit links when a file contains project-specific material
|
||
in addition to standard wording. Preserve existing incorporated notices.
|
||
6. Apply the adopted house interpretation for project-specific notice links.
|
||
Put concrete exception reasoning in OSS policy or an appropriate decision
|
||
record, never in attribution. Do not add missing-copyright filler, research
|
||
narratives, inferred licensing choices, or legal conclusions to entries.
|
||
7. End README with the two OSS statements, identifying Audita as GPL v3.0 or later
|
||
and linking to `COPYRIGHT` and `docs/oss/attribution.md`. The linked grant owns
|
||
the separately licensed policy scope; no duplicated notice list is needed.
|
||
|
||
**Validation and completion:** Inspect entries against selected source evidence,
|
||
resolve every source/notice commit and path, compare standard license bytes, and
|
||
check local links. Confirm that actual distributed material is accounted for
|
||
without blindly including dependency graph or development-tool entries. Record
|
||
concise inventory/check evidence under this stage; no new SBOM, scanner, durable
|
||
inventory generator, or test suite is required.
|
||
|
||
## Stage 4 — Integrate Release Notes and Finish Cross-Document Validation
|
||
|
||
**Completed:** 2026-09-28. Wired the checked-in release note into the hosted
|
||
release plugin, documented immutable-tag notice links and release preparation,
|
||
repaired the specified historical roadmap references, and marked the feature
|
||
roadmap implemented. Parsed the YAML, substituted `v2.0.0` to a tracked note,
|
||
checked non-overwrite settings and candidate footer paths, reviewed all seven
|
||
policies against the pinned source, and checked repository-local Markdown links
|
||
and `git diff --check`. Hosted execution awaits the next real release.
|
||
|
||
**Files:** `.woodpecker/release.yml`, `docs/release.md`, affected documentation
|
||
links, `docs/roadmap/policy.md`, and this plan. Repair the historical references
|
||
specified below; do not retire unrelated roadmaps in this sprint.
|
||
|
||
1. Add this setting to the existing `publish-release` step:
|
||
|
||
```yaml
|
||
note: docs/releases/${CI_COMMIT_TAG}.md
|
||
```
|
||
|
||
The [official release-plugin documentation](https://woodpecker-ci.org/plugins/release)
|
||
supports a file path in `note`; the
|
||
[environment reference](https://woodpecker-ci.org/docs/usage/environment)
|
||
makes `CI_COMMIT_TAG` available for configuration substitution. These interfaces
|
||
were checked during planning. Use the checked-out tagged note directly; no
|
||
generator, custom publisher, or additional dependency is needed. Preserve
|
||
`overwrite: false`, `file-exists: skip`, existing assets/checksum settings,
|
||
secret reference, image, and step dependency.
|
||
2. In `docs/release.md`, add the footer preparation instruction with this pattern
|
||
(substitute the selected release version for `<version>`):
|
||
|
||
```markdown
|
||
[COPYRIGHT](https://gitea.maximumdirect.net/eric/audita/src/tag/<version>/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/audita/src/tag/<version>/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/audita/src/tag/<version>/docs/oss/attribution.md)
|
||
```
|
||
|
||
Explain that the plugin uses the checked-in note for new hosted releases and
|
||
preserves existing release information on retries. Keep old notes and pages
|
||
intact. Validate intended paths locally during preparation; do not add remote
|
||
footer checks, a footer parser, or a new release-script gate.
|
||
3. Align the runbook with the adopted policy: retain `origin`, `main`, atomic
|
||
source/tag publication, one offline validation pass, required Linux builds,
|
||
optional check mode, and asynchronous immutable delivery retries. Reference
|
||
the policy for requirements rather than introducing additional ones. Add
|
||
proportionate completed-roadmap retirement guidance for future release
|
||
preparation without making it a script-enforced condition. No release script
|
||
change is expected from this adoption.
|
||
4. Repair both current-plan links in `decision-set-reconciliation.md` to the
|
||
historical plan at the full Audita planning baseline listed above. Remove
|
||
the stale sentence in `library-adoption.md` saying the current implementation
|
||
plan covers span deletion. Preserve historical records and deferred work.
|
||
5. Review the final adoption diff against upstream and the feature roadmap.
|
||
Check all policy source metadata, template removal, local exception reasons,
|
||
copied-material scope, license text fidelity, local links/anchors, and pinned
|
||
upstream destinations. Ensure the feature roadmap records implemented status
|
||
only after its accepted outcomes are achieved.
|
||
6. Parse/review the affected YAML using an available YAML parser or Woodpecker
|
||
linter. Substitute a representative existing release tag locally and confirm
|
||
the note path resolves to the tracked note; old notes need not have the new
|
||
footer. Check a temporary example of the new footer against candidate paths.
|
||
Verify non-overwriting publication settings remain unchanged. Do not call the
|
||
forge to create a test release, run a plugin with production credentials, or
|
||
wait for CI. Static configuration and documented plugin-interface validation
|
||
are sufficient for this wiring change; report that hosted execution awaits
|
||
the next real release rather than claiming it was exercised.
|
||
|
||
**Validation and completion:** Run `git diff --check`, review staged content and
|
||
all affected links, and record the final verification evidence. No full Go suite
|
||
or build matrix is required when only documents and the note setting changed.
|
||
If an actual release-script behavior change becomes necessary, justify its
|
||
scope and run focused `go test ./scripts` coverage for that behavior rather than
|
||
inventing additional release gates. Commit the completed work; leave a clean
|
||
workspace without publishing.
|
||
|
||
## Open Questions
|
||
|
||
None requiring a policy or design decision before implementation. The upstream
|
||
revision, local exceptions, attribution arrangement, target documents, and
|
||
release-body mechanism are selected. Exact component notice details and source
|
||
revisions are factual verification work in Stage 3, not permission gates. If
|
||
that inspection reveals an uncovered obligation, follow the adopted exception
|
||
procedure and identify the concrete decision instead of silently expanding scope.
|