From 990ca0b71a4f751f31897382562facb4dfd0bdf6 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 3 Oct 2026 13:31:37 +0000 Subject: [PATCH] Plan independent output destinations --- docs/roadmap/implementation.md | 409 +++++++++---------------------- docs/roadmap/narratio-feature.md | 29 +-- docs/roadmap/policy.md | 8 +- 3 files changed, 121 insertions(+), 325 deletions(-) diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 789b435..c5a5948 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -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-` 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 ``): - - ```markdown - [COPYRIGHT](https://gitea.maximumdirect.net/eric/audita/src/tag//COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/audita/src/tag//LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/audita/src/tag//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. diff --git a/docs/roadmap/narratio-feature.md b/docs/roadmap/narratio-feature.md index 64971fb..8c4b2f2 100644 --- a/docs/roadmap/narratio-feature.md +++ b/docs/roadmap/narratio-feature.md @@ -3,7 +3,8 @@ **Last updated:** 2026-10-03 **Status:** Proposed; not implemented. This roadmap records the intended external -behavior and work needed to reach it. The [Narratio request](feature-request-narratio.md) +behavior and the reasons for it. The [implementation plan](implementation.md) +owns the ordered work; the [Narratio request](feature-request-narratio.md) provides the consumer context. ## Purpose @@ -82,32 +83,6 @@ Audita continues to write stdout and stderr under its existing stream contract. Narratio captures those streams itself. Audita retains its report filenames and its nested debug layout. -## Work Needed - -- Make CLI destination selection distinguish an explicit `--report-dir` from a - `reporting.stdout_dir` value supplied by defaults, a file, or an overlay. - Continue applying the existing ConfigKit flag override for inspection and - precedence; use explicit flag presence when deciding whether reports for file - output move away from the transcript's parent. Do not rename or broaden the - configuration field for this feature. -- Pass the selected directory to the existing output session for both stdout - and file transcript output. Reuse current collision checks, preflight, - initialization, finalization, and failure handling. Preserve independent - `--work-dir`/debug wiring and correct any coupling found during the work. -- Update process help, the CLI and configuration references, operations, and - subprocess guidance. State clearly that debug can be enabled by configuration - as well as `--debug`, and that a chosen debug root does not enable capture. - Keep report schemas in their existing canonical owner; no schema change is - expected. -- Replace tests that assert `--report-dir` is ignored with tests of explicit - precedence and preserved defaults. Add a representative CLI/subprocess case - using three distinct destinations, plus a failure after report initialization - that leaves available reports in the selected directory. Cover inactive - reporting/debug destinations and existing collision protection at the - narrowest useful test boundary. Validation should follow the - [testing policy](../policy/testing.md), without duplicating every case across - layers. - ## Acceptance Criteria - A CLI caller can provide `--output FILE --report-dir DIR --work-dir ROOT` in diff --git a/docs/roadmap/policy.md b/docs/roadmap/policy.md index 06d8665..74e83c6 100644 --- a/docs/roadmap/policy.md +++ b/docs/roadmap/policy.md @@ -3,7 +3,8 @@ **Last updated:** 2026-09-28 **Status:** Implemented. This roadmap replaces its earlier licensing-only scope -and records the accepted end state. [implementation.md](implementation.md) +and records the accepted end state. The +[historical implementation plan](https://gitea.maximumdirect.net/eric/audita/src/commit/61bc467a03da17d52481faa5db96d9e048815be7/docs/roadmap/implementation.md) records the ordered work and verification; the adopted policies are in `docs/policy/`. @@ -213,8 +214,9 @@ Implementation covers the seven policy documents, `AGENTS.md`, `docs/development.md`, `COPYRIGHT`, `docs/oss/attribution.md`, applicable files in `docs/oss/licenses/`, README, the release procedure, and focused hosted-body publication wiring. Update this roadmap's implementation status when appropriate. -The [implementation plan](implementation.md) owns the editing sequence and -verification steps. +The +[historical implementation plan](https://gitea.maximumdirect.net/eric/audita/src/commit/61bc467a03da17d52481faa5db96d9e048815be7/docs/roadmap/implementation.md) +owns the editing sequence and verification steps. The work is complete when: