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#
- 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.
- V8 provenance no longer promotes a locator-derived digest to an asset-byte
digest.
AssetProvenanceEntrypreserves normalizedhashScopeandsignedstate, with legacy omissions resolving honestly tolocatorandfalse. Pipeline and asset-binding tests distinguish locator/unsigned from asset-bytes/signed records. scripts/audit/machine-adjacent-doc-contract.jsonis 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..github/workflows/machine-adjacent-doc-drift.ymlruns the focused contract gate, and the canonical audit-record workflow runs the same verifier when relevant runtime, contract, generated-reference, or umbrella files change.- 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.181Zthrough2026-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-assetssuite — 56/56 tests passed. - Focused
yemaya-case-pipelinesuite — 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-pipelinepassed. pnpm verify:audit:v1-v9-verification-recordpassed 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 --checkpassed 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
hashScopeandsignedprevents 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 --excludeTaskDependenciespath did not resolve the existing@yemaya/agents/quality-assurance/mystery-fairness-validatordependency 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.