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

Plan the standard policy alignment work

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-28 00:59:27 +00:00
parent 91d9be68a7
commit f36cb58781
2 changed files with 253 additions and 254 deletions
Download Patch File Download Diff File Expand all files Collapse all files

501
docs/roadmap/implementation.md
View File

@@ -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 `<version>`):
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/<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)
```
## 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.

6
docs/roadmap/policy.md
View File

@@ -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: