Implementation Notes: Establish One Comprehensive Behavior Contract

Summary

• Execution started from the independently reviewed IP-319 plan on the coordinated draft PR branch.
• Wave 1 complete: T1 schema and validator foundation passed worker and parent validation.
• Current checkpoint: T1-T10 are complete under the recorded closeout decision.
• T2 complete: worker gates, parent gates, and two independent acceptance-review rounds passed.
• T3 complete: all API/provider gates, parent validation, and independent acceptance review passed.
• T4 complete: DB/auth gates, failure-safe cleanup proof, and three independent correction reviews passed.
• T5 complete: runtime fixture, independent validator, exact state restoration, ordered teardown, cookie-policy corrections, and independent review passed.
• T6 complete: unit/browser/web/UI contracts, three workspace fragments, cleanup proof, minimal lockfile delta, and independent review passed.
• T7 complete: wiki sync/routes, environment validation, all scaffold runtime schemas, three workspace fragments, safe type validation, minimal two-line lockfile delta, and independent review passed.
• T8 complete: one local-and-CI root command covers all 12 workspace contracts, including packages/config static and consumer proof.
• T9 complete: deterministic repetition, supported concurrency, exact cleanup ownership, and comparable uncached evidence passed.
• T10 complete: private/internal docs artifacts and final review are complete. The maintainer accepted the existing T1-T9, review, and docs evidence and explicitly instructed the team not to run a new global or CI gate.

Execution Mode

• parallel; plan-derived waves with disjoint worker ownership and parent validation.

Deviations From the Plan

• Runtime thread saturation limited the nominal five-way wave to capacity batches. Dependency order and disjoint ownership remain unchanged.

Surprises and Decisions

• Two initial plan-writer workers stalled under thread limits. The parent materialized the plan, then an independent plan-reviewer required and verified three correction rounds before implementation.
• Initial T2/T3 contracts passed their tests but independent review found self-referential fixtures and test-only adapter seams. T2 now freezes raw output and managed bytes, derives command/mode coverage bidirectionally, and exercises the production filesystem/process boundaries.
• Initial T4 tests passed, but independent review found that the real auth target reconstructed production configuration and that Docker cleanup registered too late. The accepted correction invokes production createAuth, permits only DB/Resend resource injection, isolates policy env before import, and proves pool/container cleanup on success and construction failure.
• The T4 mixed data-auth fragment contradicted the one-workspace-per-fragment validator. It was split into truthful auth.json and db.json fragments instead of weakening ownership rules.
• T5 review required a complete runtime fixture to preserve all seven normalized public operation results independently of the validator, restore the complete pre-run access snapshot, and prove natural ordered handler/API-DB/auth-DB teardown. The original IP-319 runtime-product/expected.json remains byte-identical; the test and validator consume the separate authoritative runtime-product-provider.json for provider-enabled results. The accepted cookie correction byte-locks the production __Secure- session-cookie policy (HttpOnly, Secure, SameSite=None) while normalizing only run-varying values.
• T6 browser characterization exposed a real cache-seam bug: typed detail failures lost their prototype after private-cache serialization. The accepted narrow fix caches a plain discriminated result and rehydrates a fresh local API error outside the cache, preserving streamed rejected-detail behavior without production UI changes.
• T7 wiki sync runs only against run-owned temporary wiki and repository trees. Check-only mode proves the stale report without mutation; apply mode locks create, update, prune, and metadata bytes; a second run proves idempotence; cleanup removes the temporary root and preserves canonical wiki content.
• T7 route review expanded the immutable fixture to all 24 concrete section redirects, all 13 legacy spec redirects, and six representative dynamic/rest-preserving redirects. The same public contract covers rendered docs and metadata, search, LLM index/full output, Markdown, 1200×630 OG PNG output, and docs/Markdown/OG not-found outcomes.
• The scaffold source exposes 14 runtime schema values. T7 directly round-trips valid input and rejects invalid input for all 14, while retaining every managed-file kind, provenance, and example-repository unknown-field stripping.
• The final behavior inventory contains 20 public seams: 6 byte-for-byte locked, 13 semantically equivalent, and 1 intentionally changed. Eight adapter families retain focused deterministic and real contracts.
• T9 replaced ambient and prefix-based mutable ownership with exact run-state manifests and fail-closed process/container provenance. Repeat report 3b3dcb3c-6797-4dbf-9597-9becdc5784a9 completed two identical 14/14 runs in 31.427 and 30.944 seconds with valid cleanup.

Sanity Checks

UI Evidence Links

T6 changed no production UI and required no screenshot delta. Durable evidence characterizes existing rendered states through unit and browser contracts.

Runtime Validation Evidence

T5 runtime validation passed through the supported report, Better Auth, authenticated backoffice read, invitation, Postgres, and loopback-email boundaries. The runtime-product test and independent validator matched all seven normalized operations directly to authoritative apps/api/test-fixtures/runtime-product-provider.json; preserved apps/api/test-fixtures/runtime-product/expected.json remains the byte-locked original rather than the provider-mode comparison target. Cleanup restored the full access snapshot and observed natural ordered handler/API-DB/auth-DB disposal.

T6 Playwright passed 8/8, including anonymous/authenticated navigation, action persistence, OTP success and exact failure feedback, unsafe-next sanitization, loading/error/not-found outcomes, and run-owned output. Rejected streamed detail remains document status 200 with visible Nothing here and noindex; an unknown route remains 404.

T7 Characterization Evidence

Wiki passed 6 tests across the temp sync and public route contracts. Sync proof covers check-only non-mutation, exact apply output, create/update/prune/meta behavior, idempotence, canonical-content protection, and run-owned cleanup. Route proof executes 43 immutable redirects and covers docs, search, LLM index/full, Markdown, OG, and 404 outcomes.

Environment validation passed 5 isolated package-consumer cases covering server/client acceptance, invalid and empty input, defaults, and public/server exposure. Scaffold passed 9 package tests; its public table exercises direct valid and invalid behavior for all 14 runtime schema exports. wiki.json, env.json, and scaffold.json each validate with zero errors.

Safe wiki validation used direct next typegen plus tsc --noEmit so the known canonical sync drift could not be applied. Env and scaffold typechecks, focused Oxlint/Oxfmt, canonical-content protection, temp cleanup, and git diff --check passed. T7 adds only the two required Vitest importer lines to bun.lock. Independent review returned PASS after the exhaustive redirect and schema corrections.

Acceptance Criteria Status

Manual Review Checklist

Pre-existing Issues

• None currently blocking IP-319.

Out of Scope Observations

• None.

Remaining Work

• Record the accepted evidence and completed status on Linear IP-330, IP-331, and IP-319.
• Keep draft PR #76 unmerged and undeployed. IP-346 owns the separate downstream readiness decision.
• Existing routed-spec sync drift and unrelated wiki formatting failures remain separately owned.

Steering