# AUD-005 evidence pack — machine-adjacent documentation truth

## Work-package charter

- **Task ID:** `AUD-005`
- **Owner:** Oshun portfolio audit-integrity maintainer; implementation owner:
  Codex
- **Accountable products:** V1 Agentic Studio/BFF and V8 Yemaya case pipeline
- **Priority:** P0
- **Target milestone:** 2026-07-15 SOTA gap-closure program
- **Risk tier:** High documentation/runtime-truth integrity
- **Dependencies:** AgentRun execution route and store, V8 asset provenance,
  umbrella architecture Markdown, generated reference renderer, CI
- **Affected schemas and content slots:** Versioned documentation contract for
  V1 execution-envelope fields and V8 provenance fields; no customer content
  slot or user-facing flow changed
- **Rollout strategy:** Correct the enforcement seams and real behavior first,
  generate field references from one contract, then make CI compare the
  enforcement comments, real-path tests, generated references, and umbrella
  prose as a single drift boundary.
- **Rollback strategy:** Revert the runtime truth fixes, contract, generated
  references, verifier, tests, and umbrella prose together. Never retain an
  asset-byte or populated-telemetry claim after removing its producer.
- **Evidence-pack location:** This file

## Completed implementation

1. V1's executed-run route now returns the same completed status it persists.
   Its route, lifecycle-store, dispatcher, and executor comments state the
   actual boundary: this path finalizes timestamps/status but does not append
   tool calls or evidence, retain a termination audit event, or consume measured
   cost. The route test asserts those fields remain empty on the real path.
2. V8 provenance no longer promotes a locator-derived digest to an asset-byte
   digest. `AssetProvenanceEntry` preserves normalized `hashScope` and `signed`
   state, with legacy omissions resolving honestly to `locator` and `false`.
   Pipeline and asset-binding tests distinguish locator/unsigned from
   asset-bytes/signed records.
3. `scripts/audit/machine-adjacent-doc-contract.json` is the versioned field
   contract. Its generator owns the V1 and V8 field-reference Markdown; its
   verifier rejects stale generated output, forbidden enforcement overclaims,
   missing real-path assertions, and umbrella prose that diverges from the
   enforcement boundary.
4. `.github/workflows/machine-adjacent-doc-drift.yml` runs the focused contract
   gate, and the canonical audit-record workflow runs the same verifier when
   relevant runtime, contract, generated-reference, or umbrella files change.
5. The canonical audit and adversarial review describe the remaining runtime
   gaps explicitly rather than treating documentation alignment as runtime
   implementation.

## Published implementation

- **Behavior, contract, test, and source-doc commit:**
  `13602f854cee508abcc3246e340c732e2324c8bb`
- **Rendered V8 reference publication commit:**
  `dc51ad2a613333881200f8d054363367fcfbbaac`
- **Canonical verification-record publication commit:**
  `ae73dc3b0f57b56ae836a5da1366ee64214c02ca`
- **Canonical record tested source:** `dc51ad2a613333881200f8d054363367fcfbbaac`
- **Canonical run interval:** `2026-07-15T15:39:36.181Z` through
  `2026-07-15T15:44:18.395Z`

| Contract artifact                                           | SHA-256                                                            |
| ----------------------------------------------------------- | ------------------------------------------------------------------ |
| `scripts/audit/machine-adjacent-doc-contract.json`          | `ac5cd11b1db77cf778c5c7ee5c939f5e7bd5633e41abfe5f4cc216d2bdb08032` |
| `scripts/audit/generate-machine-adjacent-docs.mjs`          | `852bbe3190d70e60f7e7b8001fd600e5bbdde65f3f955c3f0114b4fd3c5971b8` |
| `scripts/audit/verify-machine-adjacent-docs.mjs`            | `14f919e1b7f7366d6ba62f7c313b2ec844f9d67fa3982432dc1700cdb76cca5a` |
| `scripts/audit/machine-adjacent-doc-contract.test.mjs`      | `b1639d2201031ae54db44c7ba6fad5bb8c83ffabcdf64b8c7c4d785e53c6363c` |
| `V1/architecture/agentic-run-execution-fields.generated.md` | `e3478187bcca106e5eb2129e5d8c227ff72e056780d61dc8e693464784820f44` |
| `V8/architecture/asset-provenance-fields.generated.md`      | `ccba2367588059e497342e6ca185fcae06d026d229be31384aebb5866d468d60` |
| `.github/workflows/machine-adjacent-doc-drift.yml`          | `99f11b3155dac7026af0b3cf5bfc5f561ee94610e4e57dd6b13ee9352484b050` |

## Verification

- `pnpm verify:audit:machine-adjacent-docs` — passed: 3/3 adversarial contract
  tests plus enforcement-comment, real-path-test, generated-reference, and
  umbrella-document coherence.
- Focused BFF `runs-route.test.ts` — 14/14 tests passed.
- Focused `yemaya-case-assets` suite — 56/56 tests passed.
- Focused `yemaya-case-pipeline` suite — 22/22 tests passed.
- BFF ratchet typecheck and the case-assets/case-pipeline TypeScript typechecks
  passed.
- Targeted ESLint with `--no-ignore --max-warnings=0`, targeted Prettier, Node
  syntax, and both affected workflow YAML parses passed.
- The BFF's project-local esbuild command passed. A direct case-pipeline emit
  with
  `pnpm exec tsc -p tsconfig.lib.json --outDir /tmp/oshun-aud005-case-pipeline`
  passed.
- `pnpm verify:audit:v1-v9-verification-record` passed after regeneration. The
  authenticated record contains 351/351 passing V8 tests across the exact 18
  configurations and retains the separate, known V8 generated-contract drift
  failure as exit 1.
- `git diff --check` passed for the closure changes.

## Claim boundary and build note

- This task does not implement tool-call/evidence accumulation, termination
  audit-event retention, or measured-cost consumption for the V1 route. It makes
  their absence explicit and mechanically checked.
- Preserving V8 `hashScope` and `signed` prevents semantic escalation. It does
  not prove that a producer hashed asset bytes or signed a record unless those
  fields say so and the relevant producer evidence exists.
- The isolated Nx `yemaya-case-pipeline:build --excludeTaskDependencies` path
  did not resolve the existing
  `@yemaya/agents/quality-assurance/mystery-fairness-validator` dependency from
  dependency output. That project-graph/output coupling is outside AUD-005's
  changed sources; the project-local direct TypeScript emit passed. No broad Nx
  build or green isolated-Nx-build claim is made.
