diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 3db35ac..d23fa97 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,287 +1,284 @@ -# Implementation Plan: Partial Validator Decision Sets +# Implementation Plan: Standard Policy Alignment -**Last updated:** 2026-09-25 +**Last updated:** 2026-09-28 -**Status:** Implemented; all stages completed. -**Source baseline:** `60e2fe7`. +**Status:** Planned; no stages implemented. **Audience:** gpt-5.6-terra coding agent. +**Audita planning baseline:** `91d9be68a7bb3a102900253fdfd8438f0a43f666`. +**Selected upstream revision:** `d84a38ebab26f048cafbe59a2246700c35d29843`. ## Scope and Execution -Implement [partial success for validator decision sets](decision-set-reconciliation.md). -That roadmap owns product intent and target semantics; this document selects the -implementation and verification work. Follow Stage 1 through Stage 3 in order and -record completion evidence beneath each stage. Each stage is a focused agent task. +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. -Read [development guidance](../development.md) and all policies under -[docs/policy](../policy/): [agents](../policy/agents.md), -[architecture](../policy/architecture.md), [documentation](../policy/documentation.md), -[testing](../policy/testing.md), and [release](../policy/release.md). Use graph-first -code discovery, preserve unrelated work, and commit completed coherent units with -plain English messages. Do not introduce approval rounds between stages. +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. -Aim directly at the final implementation. No temporary modes, compatibility shims, -new configuration, extra model calls, or upstream dependency work is required. -Keep PromptKit structural validation/repair and the runner's internal cardinality -checks. Implement the agreed outcomes, not extra restrictions suggested by existing -tests or incidental internal structure. Internal helper signatures and layout can -be adjusted idiomatically while preserving the decisions below. +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 replaces the completed span-deletion plan, available in Git at -`60e2fe7:docs/roadmap/implementation.md`. It does not reopen that feature. The final -stage includes correcting historical links that otherwise point to this new plan. -No release preparation, tag, push, CI wait, or paid-provider evaluation is included. +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. -## Selected Implementation Decisions +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. -### Reconciliation boundary +## Common Adoption Decisions -Keep reconciliation in `internal/framework/validators`, after successful structured -completion and before converting the batch into runner-facing results. Replace -`mapLLMResponseToDecisions` with a small pure reconciliation helper; use an ordinary -private result struct containing: +- 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. -- `Decisions []Decision`: one outcome per requested item, in request order; -- `UnavailableIndices []int`: requested indices without a usable verdict; -- `IgnoredIndices []int`: unexpected indices encountered in response order, including - repeated unexpected entries, for debug attribution. +## Stage 1 — Establish Provenance and Shared Agent/Testing Policies -No generic reconciliation framework or new shared abstraction is needed. Requested -identities come from `batch.Items`, not transcript segment IDs, the whole section, -or any other batch. Expected input identities remain an Audita internal contract. +**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`. -First collect response entries by requested index and count occurrences, separating -unexpected indices. Then walk requested items once to construct outcomes. This -avoids accepting an early duplicate before seeing a conflicting later entry. +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. -Use these candidate-level reason codes in `validators/models.go`: +**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. -| Condition | Internal outcome/reason | -| --- | --- | -| Missing requested entry | `DispositionUnavailable`, `missing_validation_decision` | -| More than one entry for a requested index | `DispositionUnavailable`, `duplicate_validation_decision` | -| Single requested entry failing the existing confidence range check | `DispositionUnavailable`, `invalid_validation_decision` | -| Single usable entry | Existing approved or `llm_rejected` decision with its model reason. | +## Stage 2 — Customize Remaining Policies and Install Selective Orientation -Unavailable outcomes have `Approved: false` and fixed safe explanatory messages. -Duplicate classification takes precedence over inspecting individual duplicate -values; identical duplicates follow the same rule. Unexpected entries are ignored -before inspecting confidence. Retain the existing confidence check as a local -check for decoded callers/test doubles, scoped to that candidate; do not broaden -this into structural salvage, confidence thresholds, or new semantic validation. -The production JSON Schema still rejects out-of-range confidence before mapping. +**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. -An empty response list makes every requested item unavailable. Response ordering -must not change verdicts or which candidate is affected. Preserve the existing -handling of valid negative decisions, including reason text. No candidate may -advance merely because another candidate was approved. +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. -### Operation accounting and ordinary reports +**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. -Each actual validation batch remains one `outcomes.Operation`. Use existing -`ReasonValidationDecisionsInvalid` (`validation_decisions_invalid`) for a batch -with unavailable requested candidates. Set `Succeeded: false`, set `ProposalIndices` -to only those unavailable indices, retain execution counts, and leave recovery -reasons empty. Still return usable decisions from that batch alongside explicit -unavailable outcomes, with no Go error for the reconciled model defect. +## Stage 3 — Complete Component Attribution and README Navigation -If no requested candidates are unavailable, set `Succeeded: true`. Add -`outcomes.RecoveryValidationDecisionsFiltered` with serialized value -`validation_decisions_filtered` when extras were ignored. Merge it with actual -`output_repaired` and `service_recovered` reasons in the same recovery operation. -Valid negative decisions do not prevent operation success. A clean response creates -no new recovery reason. +**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. -When unavailable candidates and extras coexist, record the failed operation only; -keep ignored-entry evidence in debug. Do not create both an error and a recovery -for that operation. Successful survivors must continue even though the operation -itself records a failure. Retain actual execution counts on all paths. +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. -Reuse existing ordinary YAML structures and version 1. The only new public report -value is the decision-specific recovery reason; affected error indices already fit -`Failure.ProposalIndices`. Do not add ignored entries to `Operation.Filtered` or -`filtered_proposals`, which describe correction proposals, and do not increment -`proposal_responses_with_filtering`. The recovery reason and existing operation -identity suffice for ordinary reporting; detailed extra indices belong in debug. +**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. -Update `processreport.safeMessage` for `validation_decisions_invalid` to explain -that some required decisions were unavailable without claiming all batch decisions -were discarded. Generalize the recovery message to include response filtering, -rather than only proposal filtering. Exact prose is not a test contract. Preserve -work-unit error grouping, operation counts, and existing YAML/Markdown/CLI totals. +## Stage 4 — Integrate Release Notes and Finish Cross-Document Validation -### Debug evidence and runner records +**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. -Existing interaction diagnostics already retain the full decoded response and final -content. Add the reconciliation result to the response diagnostic payload for a -successfully decoded validation response. Perform reconciliation before writing -that diagnostic; retain existing call-error diagnostics and diagnostic-write failure -handling. All reconciled decisions, including unavailable outcomes, receive the -returned response artifact path. This records unexpected indices and duplicates -without inventing candidate ledger entries or an additional debug file. +1. Add this setting to the existing `publish-release` step: -Carry `validators.DecisionDisposition` through `runner.ValidatorDecisionRecord` -and `runner.ValidatorRejectedChange` in an additive `disposition` field. Populate -it from each actual `Decision`, including partial decision evidence returned on -fatal paths. Keep the existing collection names and application flow; no parallel -unavailable-candidate collection is necessary. + ```yaml + note: docs/releases/${CI_COMMIT_TAG}.md + ``` -In `processreport`, add `disposition` to `LedgerValidatorDecisionRecord` and map -unavailable candidates to a top-level ledger disposition `unavailable`, instead -of `rejected`. Ordinary editorial/deterministic rejections remain `rejected`. -Use the explicit disposition, not a reason-code allowlist, so existing timeout, -provider-failure, and oversized-input outcomes retain the same distinction too. -Update affected test fixtures to supply dispositions where they represent real -validator outputs. Do not invent a fatal check or compatibility subsystem for a -zero-value disposition in handcrafted fixtures. + 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 ``): -Retain candidate identity, literal proposed replacements (including explicit empty -strings), and omission of applied replacements for unapplied candidates. Existing -fatal/interrupted/module-failure handling and debug-off behavior remain. Supplied -model decisions remain visible in interaction evidence even when reconciliation -cannot accept them as authoritative verdicts. + ```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) + ``` -## Stage 1 — Reconcile Model Decisions and Preserve Valid Work + 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. -**Completed:** 2026-09-25. Reconciliation preserves usable decisions, attributes -unavailable requested indices and ignored extras, and keeps strict runner -cardinality. Validator and runner boundary checks passed with -`go test ./internal/framework/validators ./internal/framework/runner`. - -**Work** - -1. Read the validator models, `llm_validators.go`, existing partial-batch tests, - `outcomes/outcomes.go`, and `runner.validateSectionCandidates`. -2. Implement the reconciliation result/helper and candidate reason codes selected - above. Replace the whole-batch mapping-error branch with outcome construction - and correct batch accounting. Add the decision-specific recovery constant. -3. Move successful-response diagnostic assembly after reconciliation and include - its result. Preserve raw/decoded response evidence and diagnostic paths; keep - recoverable call errors, fatal errors, and cancellation on their existing paths. -4. Keep `EnforceDecisionCardinality` and `EnforcePartialDecisionCardinality` strict. - Ensure final validator decisions are complete and unique internally. The runner - should continue passing only approved candidates onward without treating an - operation's failure metadata as a reason to discard valid decisions. -5. Replace obsolete batch-rejection expectations in `llm_validators_test.go` and - relevant runner tests. Preserve cardinality tests that exercise broken internal - validators. Update the repaired-but-domain-invalid tests so actual unavailable - cases remain errors with counts retained and no recovery record. - -**Focused verification** - -Use a small table at the validator boundary for mixed missing/extra indices, -conflicting and identical requested duplicates, extra-only responses, empty lists, -reordered responses, and a single invalid-confidence decoded test-double entry. -Include noncontiguous expected indices and valid negative decisions. Assert semantic -outcomes and affected indices, not helper layout or exact messages. Include one -controlled case combining successful structural/service recovery facts with ignored -extras and one failed reconciliation retaining counts without recovery reasons. - -At the runner boundary, use the real LLM-backed validator with a controlled client -and a later validator: prove a survivor reaches later required validation, a later -rejection prevents application, and unavailable candidates never reach that later -validator as approved. Use successful proposal operation facts where accounting is -asserted; do not check an empty operation list. Reuse existing fixtures/tests rather -than creating a second framework or duplicating every table case. - -Run `go test ./internal/framework/validators ./internal/framework/runner`. - -**End state:** Usable decisions survive model indexing defects, strict internal -cardinality remains satisfied, and operation facts explain partial failure or -successful extra filtering. No extra model generation is introduced. - -## Stage 2 — Carry Dispositions Through Debug and Report Partial Outcomes - -**Completed:** 2026-09-25. Runner and ledger records carry explicit -dispositions; ordinary reports distinguish unavailable decision errors from -extra-index filtering recoveries. Focused report, ledger, runner, and YAML -checks passed with `go test ./internal/framework/runner -./internal/framework/processreport ./internal/core/reporting`. - -**Work** - -1. Add and populate disposition fields through the runner and ledger as selected - above. Map unavailable candidates distinctly and preserve empty replacement - serialization. Check both normal and fatal partial-evidence paths. -2. Update `processreport` messages and review `Build`, `mapFailure`, and `mapRecovery`. - Reuse their existing aggregation; change only assumptions that would misreport - the new operation facts. Core YAML structures and Markdown table layout remain. -3. Extend existing report/ledger tests for an operation with surviving work plus - unavailable indices, extra-only recovery, and a mixed defect operation. Verify - error indices exclude survivors, extra filtering does not count as proposal - filtering, and failed operations do not also generate recovery records. -4. Verify debug ledger entries distinguish genuine rejection from unavailability, - and interaction diagnostics preserve ignored entries and reconciliation reasons. - Unknown response indices must not create fake ledger candidates. Retain existing - redaction and optional-debug-failure tests rather than reproducing them all. -5. Update `docs/integrations/output-files.md` for the new recovery reason and debug - disposition, and `docs/internal/diagnostics-reporting.md` for the mapping changes. - Explain that validation failure indices identify unavailable candidates, not - necessarily every candidate submitted to that batch. - -**Validation** - -Run `go test ./internal/framework/runner ./internal/framework/processreport ./internal/core/reporting`. -Use semantic YAML/summary assertions; no whole-report prose golden, exact message -snapshot, new schema version, or new rendering mode is needed. - -**End state:** Reports and debug evidence accurately describe partial validation -success and handled extras through existing reporting mechanisms. - -## Stage 3 — Verify the Assembled Workflow and Finalize Documentation - -**Completed:** 2026-09-25. Controlled subprocess runs covered a mixed decision -response and an extra-only response through the CLI, transcript, YAML, Markdown, -debug ledger, and interaction evidence. Fixture execution facts showed one -provider attempt and zero structural repairs per logical call. `go test -./cmd/audita` and `go test ./...` passed. Canonical validator guidance and -roadmap status were updated; the two span-deletion plan links now target the -historical plan at `60e2fe7`. - -**Work** - -1. Extend the existing local-provider subprocess fixtures in - `cmd/audita/main_integration_test.go`. Add a representative mixed-decision run - with an applied survivor, a legitimate rejection, a missing requested decision, - a duplicate requested decision, and an extra index. Return responses by the - requested correction identities; do not freeze incidental validator call order. - Ensure the survivor passes all remaining required validation. Assert successful - CLI completion, correct transcript, one work-unit error with only unavailable - indices, no reconciliation recovery for the failed operation, and debug - evidence distinguishing rejection/unavailability without unknown candidates. -2. Add or adapt a compact extra-only case proving usable work survives and one - `validation_decisions_filtered` recovery appears. Verify YAML, Markdown, and CLI - agree on totals using semantic assertions. Keep proposal-filtering counts separate. - Existing reporting-disable/debug selection tests remain the owners of those options. -3. In these fixtures give PromptKit its normal configured structural repair allowance, - but supply schema-valid responses. Verify reconciliation adds no generations or - structural repairs using fixture requests/execution facts, without encoding today's - total validator count as a permanent contract. Keep structural-malformation tests - and recoverable batch-failure tests; do not relax the schema to make fixtures pass. -4. Update `docs/internal/validators.md` and any affected canonical descriptions found - by searching for whole-batch rejection claims. Explain tolerant external response - reconciliation versus strict internal cardinality. The structural-validation - boundary remains explicit, and guided recovery remains deferred in `future.md`. -5. Mark the feature roadmap implemented only after the assembled checks pass, and - record actual completion evidence in this plan. Repair the two span-deletion - roadmap links to the old plan with the historical URL - `https://gitea.maximumdirect.net/eric/audita/src/commit/60e2fe7/docs/roadmap/implementation.md`. - Preserve historical release notes and unrelated roadmaps. - -**Validation** - -Run `go test ./cmd/audita` while developing the fixture, then `go test ./...` once -for the completed implementation. Run `git diff --check` and verify affected -Markdown links. Do not add live-provider checks, a platform matrix, repeated full -suite runs, or release gates solely for this feature. No code is implemented by -this planning pass; these commands are instructions for the implementation sprint. - -**End state:** The accepted partial-success behavior is exercised through the real -CLI/library boundary, canonical documentation matches it, and coherent changes -are committed for subsequent release consideration. +**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 required before implementation. The implementation decisions above preserve -the agreed product scope. General structural salvage and guided regeneration remain -separate future decisions, not unresolved prerequisites for this work. +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. diff --git a/docs/roadmap/policy.md b/docs/roadmap/policy.md index fa00462..caca80f 100644 --- a/docs/roadmap/policy.md +++ b/docs/roadmap/policy.md @@ -4,7 +4,8 @@ **Status:** Accepted direction; implementation pending. This roadmap replaces its earlier licensing-only scope and defines the desired end state, not a staged -implementation plan. Updating this roadmap does not adopt the policies below. +implementation plan. [implementation.md](implementation.md) owns the ordered +work and verification. This roadmap does not itself adopt the policies below. ## Purpose and Review Revision @@ -212,7 +213,8 @@ 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. -A separate staged implementation plan can define the editing sequence. +The [implementation plan](implementation.md) owns the editing sequence and +verification steps. The work is complete when: