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

Plan independent output destinations

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-03 13:31:37 +00:00
parent 61bc467a03
commit 990ca0b71a
3 changed files with 121 additions and 325 deletions
Download Patch File Download Diff File Expand all files Collapse all files

409
docs/roadmap/implementation.md
View File

@@ -1,313 +1,132 @@
# Implementation Plan: Standard Policy Alignment
# Implementation Plan: Independent Output Destinations
**Last updated:** 2026-09-28
**Status:** Complete; Stages 1–4 implemented.
**Last updated:** 2026-10-03
**Status:** Ready for implementation.
**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.
Implement the target behavior in the [Narratio feature roadmap](narratio-feature.md),
in Stage 1 then Stage 2. That roadmap owns the user intent and external contract;
this plan owns the implementation sequence and verification. The original
[Narratio request](feature-request-narratio.md) supplies consumer context. The
completed policy-adoption plan previously at this path remains available at
[its final committed revision](https://gitea.maximumdirect.net/eric/audita/src/commit/61bc467a03da17d52481faa5db96d9e048815be7/docs/roadmap/implementation.md).
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.
Begin with [development guidance](../development.md) and the applicable
[agent](../policy/agents.md), [architecture](../policy/architecture.md),
[documentation](../policy/documentation.md), and
[testing](../policy/testing.md) policies. Use graph-first code discovery as the
agent policy directs. Commit each completed unit with a short, plain English
message; do not release, tag, or push as part of this feature. No approval gate
is needed between stages.
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.
Keep the change at the CLI destination-selection boundary. `--report-dir` is
already parsed as a ConfigKit override of `reporting.stdout_dir`; retain that
mapping so effective-configuration views and flag precedence remain intact.
For `process` only, also retain whether the caller explicitly supplied the flag.
The configured `reporting.stdout_dir` value alone must not redirect file-output
reports. Do not add a configuration key, alter report schemas, add output-root
separation rules, or change the output session's existing lifecycle merely to
support this selection.
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.
Use this selection rule after configuration is loaded:
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.
| Reporting state and transcript destination | Selected ordinary report directory |
| --- | --- |
| Reporting disabled | None; do not preflight or create the chosen report directory |
| Reporting enabled, stdout transcript | Effective `reporting.stdout_dir`, including any `--report-dir` override |
| Reporting enabled, file transcript, explicit `--report-dir` | Effective `reporting.stdout_dir` from that flag |
| Reporting enabled, file transcript, no explicit `--report-dir` | Parent of `--output FILE` |
## Common Adoption Decisions
An active selected report directory must be nonblank. A blank
`reporting.stdout_dir` must not newly invalidate file output when no explicit
`--report-dir` was supplied. Continue to let existing configuration validation
handle invalid setting values; this plan does not add special handling for an
invalid but inactive flag. Existing `--work-dir` and effective
`diagnostics.debug` controls already select and enable debug capture
independently. Selecting `--report-dir` or `--work-dir` alone never turns on
reporting or debug capture. A failed report still appears in the selected
directory only when the existing output lifecycle would produce it; failures
before report initialization remain outside that guarantee.
- 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 — Implement Explicit Report-Destination Selection
## Stage 1 — Establish Provenance and Shared Agent/Testing Policies
**Files:** `internal/cli/config_input.go`, `internal/cli/process.go`,
`internal/cli/run.go`, `internal/cli/config_input_test.go`, and the existing
affected subprocess test in `cmd/audita/main_integration_test.go`.
**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.
1. In `configInput`, record explicit `--report-dir` presence from the parsed
flag set's `Visit` callback. Preserve the existing ConfigKit override and
its `--report-dir` provenance. Do not infer explicitness from the effective
config value, because a default, file, or overlay can yield the same value.
Other commands may continue accepting the override for inspection without
changing their behavior.
2. Extend `selectedReportDir` to accept that explicitness and implement the
table above. Make `runProcess` pass the new input to it, then continue
passing the selected path to the existing `diagnostics.PrepareOutput` call.
Leave `PrepareOutput` collision, preflight, initialization, failure, and
finalization behavior in place. Leave the existing `cfg.Diagnostics.Debug`
and `cfg.Diagnostics.WorkDir` path into debug startup intact.
3. Update focused CLI tests for explicit presence and selection: file output
with explicit flag uses the selected directory; file output with only a
configured or overlay `reporting.stdout_dir` still uses the output parent;
stdout uses the effective report directory; disabled reporting selects no
active report directory. Test active blank values only where they affect
selection. Retain coverage that the flag remains a ConfigKit override.
4. Replace the existing subprocess assertion in
`TestSubprocessReportingAndDebugSelections` that relies on an ignored
`--report-dir` with the new behavior. Keep its separate check that an
inactive destination is not probed. Avoid duplicating every unit-selection
case at the subprocess layer.
5. Update `audita process` help so it no longer says `--report-dir` is ignored
with file output. Keep help aligned with the selection rule above.
**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`.
**Stage completion:** Run targeted tests for the changed CLI and subprocess
packages (`go test ./internal/cli ./cmd/audita`) and `git diff --check`. Review
the diff for accidental configuration-schema changes or newly strengthened
destination constraints, then commit the coherent code/test unit.
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.
## Stage 2 — Verify End-to-End Behavior and Update the Public Contract
**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.
**Files:** `cmd/audita/main_integration_test.go`, `docs/cli.md`,
`docs/config.md`, `docs/operations.md`,
`docs/integrations/subprocess.md`, and `docs/roadmap/narratio-feature.md`.
Touch another document only if its current statement actually conflicts with
the new behavior.
## Stage 2 — Customize Remaining Policies and Install Selective Orientation
1. Add one representative subprocess success case with distinct transcript
file, report directory, and debug root, enabling debug explicitly. Verify
the transcript, ordinary reports, and `run-<id>` debug capture appear at
their selected destinations and that the report files are not placed beside
the transcript. Reuse the existing test fixture; do not prescribe a new
report format or a Narratio-specific directory layout.
2. Add a subprocess case based on the invalid-input fixture used by
`TestSubprocessInvalidInputLeavesFailedReports`. It fails **after** report
initialization; check that its available failed-status reports use an
explicit report directory. Preserve the existing test of default placement
and the existing early-failure semantics. Rely on current output-session
collision and inactive-debug tests where they already prove the behavior;
add a narrow test only if this new CLI route exposes an uncovered interaction.
3. Change the CLI, configuration, operations, and subprocess documents to state
the four selection cases above. Explain that a config-file or overlay value
for `reporting.stdout_dir` remains stdout-only, while an explicit
`--report-dir` flag selects reports for either transcript destination.
Clarify that `--work-dir` chooses a
debug root without enabling capture and that configuration or `--debug` can
enable it. Describe reports after failures only to the extent the current
output lifecycle supplies them. Leave the canonical output-file schema
document unchanged unless this work exposes a factual error in it.
4. Review the completed behavior against the feature roadmap's acceptance
criteria. Run `go test ./...`, check documentation links and examples, and
run `git diff --check`. If a test fails, resolve that failure before marking
the feature complete; do not add unrelated gates. Mark the feature roadmap
implemented once the final behavior and documentation are verified, then
review the staged diff and commit the completed unit with a short, plain
English message. Leave a clean workspace.
**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.
No open policy or design decision is required to execute these stages. The
explicit-flag precedence, preserved defaults, inactive-destination behavior,
failure-report limit, and existing debug controls are settled in the feature
roadmap. If implementation uncovers a conflict with an established contract,
report the concrete conflict instead of silently broadening this feature.