Skip to content

godaudits 2.13.0: wayfinding the remediation plan

Choose a tag to compare

@hannsxpeter hannsxpeter released this 31 Jul 07:54
· 20 commits to main since this release
3eb57e9

Drawn from reviewing what the wayfinder skill (mattpocock/skills, MIT) could contribute. Its planning machinery has no place here: godaudits does not chart decision tickets, and the audit already produces the graph wayfinder assembles by hand. What was worth taking was its discipline about reading a graph back, which godaudits had never applied to its own remediation plan.

An audit ended with a list of phases and waves. That answers "what did the audit decide" and not "what can I start now", and it said nothing about what the audit consciously did not cover.

Added

godaudits wayfind AUDIT.json (and --format json) reports the destination, frontier, claims, blockers, fog, and scope boundary. It is a read: it compiles nothing and mutates nothing, so it stays correct on a half-written plan and the instant a task closes. The frontier is deliberately not written into computed, because a frontier committed into the audit record is stale the moment a task closes.

Three frontier rules the phase-and-wave listing could not express:

  • A superseded dependency counts as closed. A replaced task will never complete, so treating it as an open blocker would strand its dependents forever.
  • The final re-audit gate is the destination, not a member of the route. It depends on every task by validation rule, so counting it as an ordinary blocked task would put one permanently unreachable entry in every map and credit every task with the same meaningless unblock.
  • Frontier tasks sharing a file are named as a concurrency conflict. Validation only rejects parallel file overlap inside a single wave; across waves it is legal state.

Four optional AUDIT.json fields, each validated:

Field Rule
audit.destination Prose naming what reaching the end looks like. An audit stating none is reported as stating none, not silently omitted.
task.claim Owner and date. Rejected once the task is no longer open, where it would read as work in flight that is not.
check.question On an unknown check, the question whose answer resolves it. Rejected on any resolved outcome.
not_yet_specified Its domain must be applicable (fog only gathers toward the destination); any check it names must still be unknown (fog that graduated is cleared, not restated).

There is deliberately no rule requiring every unknown check to carry a question. A fresh audit initializes every check to unknown and a medium budget holds every deep-trace check unknown by design, so the gate would be unsatisfiable. The map reports the count instead.

docs/WAYFINDING.md records the borrowed disciplines, what was cut, and why.

Changed

The generated report leads the remediation plan with the destination and the frontier, both read before a task is chosen, and reports fog and scope in separate sections. Collapsing them would let a coverage gap read as a deliberate boundary, or a boundary read as a gap.

Task and finding references now carry their title with the id inside, replacing bare id lists on Depends on and Fixes. Check ids stay bare: their titles live in the catalog rather than in AUDIT.json, and the plan-aware mirror already uses that slot for the godplans R-id.

Fixed

A latent bug this version bump surfaced: the dogfood publication gate compiled retained historical artifacts against the current pack version, so every release after a dogfood publication would have failed it. The only escapes would have been editing the pinned engine_version (misattributing the run) or dropping the artifact. The version identity alone is now relaxed and every content rule stays live.

Compatibility

Every wayfinding field is optional and nothing was added to computed. Audits written before 2.13, including the committed dogfood and detector artifacts, validate unchanged and still produce a map.

The published auth0/node-jsonwebtoken dogfood report is deliberately not re-rendered: its AUDIT.json pins engine 2.12.0, so rendering it with this engine would misattribute the run. A retained report is evidence of a specific engine at a specific commit, not a live view.

Release cadence

This is a minor release outside the 30-day cadence in docs/RELEASE-POLICY.md and matches none of its three exceptions. It is cut because the change alters the shape of the generated report and the published AUDIT.json contract, and a documented contract change is clearer as a version than as unversioned drift on main.

Full changelog: v2.12.0...v2.13.0