Plan: Establish One Comprehensive Behavior Contract

Plan State

• Status: T1-T10 complete; maintainer accepted the existing delivery evidence without a new global or CI gate
• Mode: parallel: true
• Scope: IP-319 with every IP-330 and IP-331 acceptance signal
• Branch: team/stefan/refactor-cli-architecture
• Pull request: https://github.com/wearedevpunks/harness-intelligence/pull/76
• Merge policy: keep the coordinated PR draft, unmerged, and undeployed until IP-346 passes

Initial Situation

The root test command is only turbo run test. Twelve workspaces are in scope, but only api, backoffice, cli, auth, contract, db, and scaffold expose test tasks. A forced-uncached run on 2026-07-14 passed 309 tests across those seven tasks in 22.79 seconds wall time. Web, wiki, config, env, and ui contribute no test task. Turbo's test task declares only a build dependency; behavior-affecting inputs, environment, isolation, and comparable benchmark evidence are not explicit.

Existing tests are strong in selected seams but do not form the accepted contract. CLI JSON is generally parsed and subset-matched rather than byte-locked; managed assets lack an exhaustive manifest-derived byte fixture; context outcomes lack one semantic fixture. API request tests mock the important external families. Browser routes, wiki generation, env validation, shared UI, real persistence, and packaged consumer behavior are incomplete or outside the root suite.

Issue

IP-330 requires every externally visible result to be classified as byte-locked, semantically equivalent, or intentionally changed, then characterized at its public seam. IP-331 requires one local-and-CI contract across every behavior-owning workspace, real domain policy with deterministic boundary substitutes, one real contract per adapter family, isolated mutable state, explicit task hashes, and comparable uncached optimization evidence. No fixed runtime, worker count, coverage, pass, release, or deadline threshold may be introduced.

Proposed Solution Shape

Create one root behavior-contract schema and validator as the authority for workspace participation, public seams, classification, fixture ownership, adapter families, behavior inputs, isolation, and the sole reason_not_testable declaration. Build disjoint family fragments and vertical characterization slices in parallel behind that authority. Each slice owns its fragment, public-seam fixtures, and real/deterministic adapter contract. Finish by validating all fragments through one root command and required CI workflow, proving isolation at multiple supported concurrency settings, and recording forced-uncached before/after evidence without turning measurements into gates.

Design-it-twice result:

1. A monolithic test package centralizes orchestration but duplicates workspace configuration and couples fixtures to private imports.
2. A thin root manifest/validator with family-local tests keeps one authority while tests remain at the public seams callers use.

Choose option 2 for depth, locality, and lower migration cost.

Locked Decision Ledger

Dependency Readiness

• Status: No Stack Required
• Dependency: none upstream
• Evidence: Linear IP-319, IP-330, and IP-331 have no blockedBy relation; draft PR #76 is the coordinated delivery vehicle.
• Reason: IP-330 is the downstream characterization foundation. Plan dependencies control task order, not PR topology.

Research and Codebase Findings

• Turbo custom inputs replace defaults unless $TURBO_DEFAULT$ is retained; tracked files, declared env, flags, and arguments affect hashes.
• Vitest 3.2 supports seeded shuffle and isolation controls; repository-wide repetition needs a small root runner because Vitest has no repeat-suite flag.
• Effect Layers are the deterministic substitution seam; IP-319 must not pre-empt IP-320's v4 pin.
• CLI packaged assertions cover shebang, binaries, help, and version only as a build side effect.
• API has broad Request-to-Response coverage but lacks exact serialization and real Postgres/Better Auth contracts.
• Wiki sync mutates its tree; CLI tests mutate env, HOME, XDG cache, git, ports, fetch, and time. These need run-owned roots and cleanup.

Dependency Graph

T1 -> [T2, T3, T4, T6, T7] [T3, T4] -> T5 [T2, T5, T6, T7] -> T8 -> T9 -> T10

Parallel Execution Waves

Tasks

T1: Establish the public-behavior classification authority

• depends_on: []
• location: behavior-contract/schema.json, scripts/behavior-contract/validate.mjs, scripts/behavior-contract/validate.test.ts, scripts/behavior-contract/test-fixtures
• description: Define and unit-test the schema for workspace participation, public seams, classifications, fixture/test ownership, adapter families, behavior inputs, isolation ownership, and reason_not_testable evidence. Reject missing fields, invalid classifications, absent fixtures, undeclared adapter proof, or extra waivers without yet writing family fragments.
• validation: Validator fixtures prove every accepted rule, including the sole config waiver, and reject each malformed contract independently.
• status: Completed
• log: Added the declarative workspace contract schema and a path-based validator that enforces schema structure, workspace ownership, classification intent, adapter declarations, proof existence, isolation cleanup, and the sole config waiver. Added independent valid/invalid fixtures for every accepted T1 rule.
• files edited/created: behavior-contract/schema.json; scripts/behavior-contract/validate.mjs; scripts/behavior-contract/validate.test.ts; scripts/behavior-contract/test-fixtures/{evidence/{cli-output.json,deterministic-adapter.txt,real-adapter.txt},invalid-{absent-fixture,classification,config-waiver-evidence,extra-intentional-requirement,extra-waiver,incomplete-adapter-proof,input-owner,intentional-requirement,isolation-cleanup,isolation-owner,missing-field,missing-fixture,missing-public-seam,proof-path,testable-waiver-fields,undeclared-adapter,unowned-classification,workspace}.json,valid-{config-waiver,intentional,semantic,testable}.json}
• backlog_item_id: IP-330
• backlog_item_url: https://linear.app/devpunks/issue/IP-330/classify-and-characterize-every-public-behavior-seam
• relation_mode: native
• assigned_skills: [codebase-design, quality-types, tdd, turborepo, simplify]
• tdd_status: required
• tdd_target: The validator accepts an invalid fixture with a missing workspace seam or unowned classification.
• red_command: bun test ./scripts/behavior-contract/validate.test.ts
• expected_red_failure: Invalid workspace participation or classification/fixture ownership is not rejected.
• green_command: bun test ./scripts/behavior-contract/validate.test.ts
• reason_not_testable:
• red_evidence: 2026-07-14 bun test ./scripts/behavior-contract/validate.test.ts exited 1: the accepting stub returned valid: true for both missing-public-seam and unowned-classification fixtures (Expected: false, Received: true; 1 pass, 2 fail).
• green_evidence: 2026-07-14 bun test ./scripts/behavior-contract/validate.test.ts exited 0 with 22 pass, 0 fail, 40 assertions; git diff --check exited 0.
• codebase_design_notes: Compared an object-only checker with a repository-path validator. Chose one path-based validateBehaviorContract interface: the schema owns vocabulary and structural rules; the deep validator owns cross-field ownership, declared-adapter, waiver, and on-disk proof invariants. Family behavior remains outside this module and behind its public seams.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T2: Characterize CLI, context, scaffold, update, and packaged output

• depends_on: [T1]
• location: apps/cli/package.json, apps/cli/src/cli/public-output-contract.test.ts, apps/cli/src/context/public-context-contract.test.ts, apps/cli/src/adapters/filesystem-adapter-contract.test.ts, apps/cli/src/adapters/process-adapter-contract.test.ts, apps/cli/src/testing, apps/cli/scripts/assert-dist-commands.mjs, apps/cli/test-fixtures, behavior-contract/cli.json
• description: Add subprocess fixtures for command/mode stdout, stderr, exit status, exact JSON bytes/newline; manifest-derived managed-asset bytes; semantic context outcomes; accepted intentional deltas; packaged hi/hint consumer assertions; and shared filesystem/process family contracts run against deterministic and real adapters.
• validation: Every shipped command/mode is classified; one-byte drift fails; context compares scope, packs, contributions, provenance, compatibility, and meaningful ordering; deterministic and real filesystem/process adapters satisfy the same focused contracts and clean their run-owned roots/processes.
• status: Completed
• log: 2026-07-14 classified the complete shipped command/mode inventory bidirectionally from executable help/flags and production-backed behavior proofs, executed controlled witnesses for every classified mode, locked version and canonical JSON streams as raw subprocess results, characterized current context semantics and a frozen manifest path/kind/hash inventory, proved packaged hi/hint output, and ran shared filesystem/process contracts against deterministic and production adapters with run-owned cleanup.
• files edited/created: apps/cli/scripts/assert-dist-commands.mjs, apps/cli/src/adapters/filesystem-adapter-contract.test.ts, apps/cli/src/adapters/process-adapter-contract.test.ts, apps/cli/src/cli/public-output-contract.test.ts, apps/cli/src/context/public-context-contract.test.ts, apps/cli/src/runtime/filesystem.ts, apps/cli/src/runtime/scripts.ts, apps/cli/src/scaffold/run.ts, apps/cli/src/testing/filesystem-contract.ts, apps/cli/src/testing/process-contract.ts, apps/cli/test-fixtures/public-output/command-modes.json, apps/cli/test-fixtures/public-output/context-outcome.json, apps/cli/test-fixtures/public-output/json-serialization.json, apps/cli/test-fixtures/public-output/managed-assets.json, apps/cli/test-fixtures/public-output/version.json, behavior-contract/cli.json
• backlog_item_id: IP-330
• backlog_item_url: https://linear.app/devpunks/issue/IP-330/classify-and-characterize-every-public-behavior-seam
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, effect-authoring, effect-backend-structure, effect-best-practices, effect-recoverable-actions, improve-codebase-architecture, parallel-research, quality-types, simplify, swarm-planner, tdd, turborepo]
• tdd_status: required
• tdd_target: A packaged JSON fixture fails because current tests do not lock bytes and stream separation.
• red_command: bun run --cwd apps/cli build && bun run --cwd apps/cli test -- src/cli/public-output-contract.test.ts
• expected_red_failure: Missing exact fixture or byte mismatch for stdout, stderr, exit, or trailing newline.
• green_command: bun run --cwd apps/cli test && bun run --cwd apps/cli build
• reason_not_testable:
• red_evidence: 2026-07-14 exact initial RED command exited 1 because the executable version result had no byte fixture: ENOENT ... apps/cli/test-fixtures/public-output/version.json at public-output-contract.test.ts. Second-review RED bun run --cwd apps/cli test -- src/adapters/process-adapter-contract.test.ts src/cli/public-output-contract.test.ts exited 1 on missing check:human behavior proof; the focused process RED then observed only 1 capture call instead of 3, proving production execute bypassed the shared capture boundary.
• green_evidence: 2026-07-14 exact GREEN command exited 0: 29 files, 225 tests passed, then packaged build/assertion passed. The second-review focused process/mode suite passed 2 files and 6 tests after proving production execute delegates through capture and adding controlled mode witnesses. bun run --cwd apps/cli check-types, CLI fragment validation ({"valid":true,"errors":[]}), focused Oxlint/Oxfmt for changed T2 files, and git diff --check also exited 0. Full apps/cli check remains repository-baseline red on pre-existing generated/source lint debt outside T2; no T2-local lint finding remains.
• codebase_design_notes: Kept executable subprocesses and existing public runners as behavior seams. One small production-owned contract interface per filesystem/process family drives both deterministic test adapters and the Node adapters used by scaffold/script execution; production execute delegates through the same capture method that the shared contract exercises and retains throwing failure semantics. Exact mode sets derive from executable command/help flags plus mappings to existing high-signal command tests, while run-owned witnesses directly exercise help, human, JSON, check, interactive, and write modes without user/network/global mutation. Current detection, pack resolution, prompt contributions, bundled provenance, source compatibility, and meaningful order form the pre-v4 semantic context projection. Managed-byte proof compares the emitted manifest to a frozen inventory, then independently hashes disk bytes against those frozen hashes, including symlink target encoding. Packaged hi/hint assertions share the existing dist consumer harness.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T3: Characterize API, shared protocol bytes, and HTTP adapter contracts

• depends_on: [T1]
• location: apps/api/package.json, apps/api/src/public-api-contract.test.ts, apps/api/src/http-adapter-contract.test.ts, packages/contract/package.json, packages/contract/src/public-protocol-contract.test.ts, behavior-contract/api-contract.json
• description: Cover every endpoint, method, request/response/error schema, security declaration, status, header, and exact public JSON body through Request-to-Response and typed-client seams. Run shared contracts against deterministic and real GitHub and OpenRouter HTTP adapters owned by the API.
• validation: A one-byte, status, header, schema, endpoint, security, or owned HTTP adapter drift fails; local provider servers and run-owned env/global state are cleaned.
• status: Completed
• log: 2026-07-14 — Locked the generated OpenAPI inventory and hash, round-tripped all 13 operations through the typed client, and asserted all 13 successful runtime operations plus representative declared failures/security paths through exact Request-to-Response status/content-type/body snapshots. Wired reports and backoffice GitHub listing, label creation, issue creation, and OpenRouter metadata generation through the shared provider boundary exercised by one deterministic transport and the real fetch transport via a protocol-faithful scoped loopback server. Added a production BackofficeSession service and API composition seam so contract authentication uses the same boundary as Better Auth without a test bypass. Declared the API seam, adapter families, behavior inputs, and isolation cleanup in the validated behavior fragment.
• files edited/created: apps/api/src/backoffice-access.ts; apps/api/src/backoffice.ts; apps/api/src/http-adapter-contract.test.ts; apps/api/src/http-adapters.ts; apps/api/src/index.ts; apps/api/src/memory-state.ts; apps/api/src/public-api-contract.test.ts; apps/api/src/snapshots/public-api-contract.test.ts.snap; apps/api/src/reports.ts; behavior-contract/api-contract.json; packages/contract/src/public-protocol-contract.openapi.json; packages/contract/src/public-protocol-contract.test.ts
• backlog_item_id: IP-330
• backlog_item_url: https://linear.app/devpunks/issue/IP-330/classify-and-characterize-every-public-behavior-seam
• relation_mode: native
• assigned_skills: [autoreview, backend-domain-structure, backend-recoverable-actions, codebase-design, effect-authoring, effect-backend-structure, effect-best-practices, effect-recoverable-actions, improve-codebase-architecture, logging-best-practices, parallel-research, quality-types, simplify, tdd]
• tdd_status: required
• tdd_target: Exhaustive protocol fixture reports uncharacterized endpoints, errors, and exact responses.
• red_command: bun run --cwd packages/contract test -- src/public-protocol-contract.test.ts
• expected_red_failure: Endpoint/schema/security inventory or exact response fixture is incomplete.
• green_command: bun run --cwd packages/contract test && bun run --cwd apps/api test
• reason_not_testable:
• red_evidence: 2026-07-14 exact RED command exited 1 because packages/contract/src/public-protocol-contract.openapi.json did not exist (ENOENT), proving the endpoint/schema/security inventory had no accepted fixture. Correction RED: provider contract failed 2/2 at missing github.createLabel; focused public contract expected report-contract but received a random UUID response, proving neither the full production provider family nor successful runtime bytes were locked.
• green_evidence: 2026-07-14 exact GREEN command exited 0: packages/contract 2 files, 16 tests passed; apps/api 7 files, 65 tests passed. bun run --cwd packages/contract check-types, bun run --cwd apps/api check-types, API behavior-fragment validation ({"valid":true,"errors":[]}), root-config focused Oxlint, focused Oxfmt, and git diff --check passed.
• codebase_design_notes: Contract owns protocol; API owns runtime/policy. The fixture derives all 13 endpoint/method/request/response/error/status/header/security declarations from HarnessApi, while typed-client and fixed Request-to-Response snapshots lock both consumers. Reports and backoffice call one ProviderHttp boundary for every owned GitHub/OpenRouter operation; the same family assertions run against deterministic and fetch-backed Layers without module mocks or production network mutation. Backoffice authentication depends on BackofficeSession; production delegates to Better Auth and tests compose a deterministic session through the same service. Scoped server disposal, handler disposal, deterministic clocks/IDs, and environment restoration make isolation ownership explicit.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T4: Add persistence, auth, and email adapter contract spines

• depends_on: [T1]
• location: packages/db/package.json, packages/db/src/postgres-contract.test.ts, packages/db/test-fixtures, packages/auth/package.json, packages/auth/src/auth-email-contract.test.ts, packages/auth/test-fixtures, behavior-contract/db.json, behavior-contract/auth.json
• description: Run the same family contract against deterministic and real Postgres, Better Auth/session/cookie, and email adapters where owned. Cover migrations, transactions, idempotency, lifecycle, typed failures, and cleanup.
• validation: Each adapter family has one shared contract; deterministic and real implementations pass it, then drop run-id data, close connections, and remove owned email fixtures.
• status: Completed
• log: 2026-07-14 — Added one persistence contract shared by deterministic state and a run-owned Postgres 15 container, covering repeatable real migrations, commit/rollback behavior, conflict idempotency, normalized constraint failure, row cleanup, pool closure, and container removal. Added one Better Auth HTTP lifecycle shared by the deterministic memory adapter and the production createAuth builder with injected real Drizzle/Resend resources, covering OTP delivery, typed invalid-OTP rejection, session-cookie policy, session observation, revocation, loopback email protocol, explicit pool closure, and server/container teardown. Production security and policy remain exclusively env-owned. A protocol-only child receives scoped production env before module import, contains the eager exported singleton within its process lifetime, acquires the injected DB before auth construction, and proves both successful and construction-failure pool cleanup before exit. Both Docker contracts register force-removal immediately after docker run and prove cleanup after simulated port-discovery failure. Split the mixed data/auth fragment into one authoritative fragment per owning workspace because the accepted schema enforces one workspace owner per fragment.
• files edited/created: bun.lock; packages/auth/package.json; packages/auth/src/index.ts; packages/auth/src/auth-email-contract.test.ts; packages/auth/test-fixtures/auth-contract.json; packages/auth/test-fixtures/auth-real-harness.ts; packages/db/src/postgres-contract.test.ts; packages/db/test-fixtures/public-schema.json; behavior-contract/auth.json; behavior-contract/db.json; behavior-contract/data-auth.json (removed)
• backlog_item_id: IP-331
• backlog_item_url: https://linear.app/devpunks/issue/IP-331/run-one-comprehensive-high-signal-repository-suite
• relation_mode: native
• assigned_skills: [autoreview, backend-domain-structure, backend-recoverable-actions, better-auth-best-practices, codebase-design, effect-authoring, effect-backend-structure, effect-best-practices, effect-recoverable-actions, improve-codebase-architecture, logging-best-practices, parallel-research, quality-types, simplify, tdd]
• tdd_status: required
• tdd_target: Real Postgres contract fails because current coverage does not migrate, persist, transact, and close a real instance.
• red_command: bun run --cwd packages/db test -- src/postgres-contract.test.ts
• expected_red_failure: Missing real Layer/fixture or persistence, transaction, idempotency, and cleanup proof.
• green_command: bun run --cwd packages/db test && bun run --cwd packages/auth test
• reason_not_testable:
• red_evidence: 2026-07-14 exact RED command exited 1 with No test files found for filter src/postgres-contract.test.ts, proving the real persistence contract spine was absent. Correction RED: focused auth test found const production = betterAuth({, proving the real target duplicated production configuration; the ownership assertion expected packages/db but received packages/auth for the Postgres seam; inspection showed both container finalizers registered only after port/readiness acquisition completed. Final correction RED: focused auth test found exported environment?: AuthBuilderEnvironment, proving security policy was injectable, and the required pre-construction pool acquisition harness was absent.
• green_evidence: 2026-07-14 exact GREEN command exited 0: packages/db 2 files, 3 tests passed; packages/auth 2 files, 6 tests passed. Both package type checks, DB/auth fragment validation ({"valid":true,"errors":[]} each), root-config focused Oxlint, focused Oxfmt, git diff --check, and empty docker ps --filter name=hi-ip319- proof passed. The direct catalog effect test dependency has a minimal matching workspace entry in bun.lock.
• codebase_design_notes: Family contract is the interface; real and deterministic adapters satisfy it without importing app policy. Persistence assertions exercise production createDb, shipped Drizzle migrations, transactions, unique-event conflict handling, and PostgreSQL error code 23502. Auth assertions exercise Better Auth only through Request-to-Response behavior; the real target calls production createAuth with only scoped database and Resend resources, while secret, base URL, trusted origins, cookie policy, and sender address remain on the unchanged production env path. The child protocol harness contains the eager singleton and guarantees the acquired pool closes before process exit, including construction failure. Docker process acquisition is separate from port/readiness acquisition, so cleanup ownership begins immediately after start. Protocol-faithful loopback email delivery avoids production network mutation and module mocks. Plan deviation: the former mixed data/auth fragment was split because the authoritative validator permits exactly one owning workspace per fragment.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T5: Prove a supported public API persistence, auth, and email scenario

• depends_on: [T3, T4]
• location: apps/api/package.json, apps/api/src/runtime-product-contract.test.ts, apps/api/scripts/validate-runtime-product.mjs, apps/api/test-fixtures/runtime-product/api-harness.ts, apps/api/test-fixtures/runtime-product/expected.json, apps/api/test-fixtures/runtime-product-provider.json
• description: Through supported HTTP actions, submit a run-id report, authenticate an operator through Better Auth, observe the persisted report through the backoffice API, and invite an access user through the email adapter against local Postgres. Correlate every public result with persisted state and run-id diagnostics.
• validation: The public requests return their exact contract results; the authenticated read observes the same report; the invitation produces the correlated email; every resource is removed by provenance.
• status: Completed
• log: Added one run-owned Postgres runtime-product scenario that drives the production API through Request-to-Response boundaries, authenticates through Better Auth, observes the submitted report through the authenticated backoffice API, and delivers correlated OTP email through a protocol-faithful local Resend endpoint. The original IP-319 expectation at apps/api/test-fixtures/runtime-product/expected.json remains byte-identical for immutable retention. Provider-enabled execution is locked separately by apps/api/test-fixtures/runtime-product-provider.json, the complete authoritative document consumed directly by both the runtime-product test and independent validator. Each run writes only sanitized evidence to ignored tmp/runtime-product/evidence.json. The API owns one shared persistence DB in database mode and disposes it, then the lazily loaded auth DB, with ordered child-process markers and observed natural exit. Cleanup restores the complete pre-run access-table snapshot and preserves unrelated state.
• files edited/created: apps/api/package.json; apps/api/src/index.ts; apps/api/src/runtime-product-contract.test.ts; apps/api/src/backoffice-access.ts; apps/api/src/backoffice.ts; apps/api/src/reports.ts; apps/api/src/telemetry.ts; apps/api/scripts/validate-runtime-product.mjs; apps/api/test-fixtures/runtime-product/api-harness.ts; apps/api/test-fixtures/runtime-product/expected.json; apps/api/test-fixtures/runtime-product-provider.json; packages/auth/src/index.ts; apps/wiki/content/docs/project/specs/cli/IP-319-establish-one-comprehensive-behavior-contract/PLAN.md; apps/wiki/content/docs/project/specs/cli/IP-319-establish-one-comprehensive-behavior-contract/IMPLEMENTATION-NOTES.md
• backlog_item_id: IP-331
• backlog_item_url: https://linear.app/devpunks/issue/IP-331/run-one-comprehensive-high-signal-repository-suite
• relation_mode: native
• assigned_skills: [autoreview, backend-domain-structure, backend-recoverable-actions, codebase-design, effect-authoring, effect-backend-structure, effect-best-practices, effect-recoverable-actions, improve-codebase-architecture, logging-best-practices, parallel-research, quality-types, simplify, tdd]
• tdd_status: required
• tdd_target: The supported report-to-backoffice flow fails because current runtime composition cannot prove real persistence, session, and email effects together.
• red_command: bun run --cwd apps/api test -- src/runtime-product-contract.test.ts
• expected_red_failure: The public scenario lacks real Postgres/auth/email composition or correlated durable evidence.
• green_command: bun run --cwd apps/api test -- src/runtime-product-contract.test.ts && bun run --cwd apps/api validate:runtime-product
• reason_not_testable:
• red_evidence: 2026-07-14 initial exact RED exited 1 with No test files found. Correction RED then proved all rejected gaps together: expected shutdown markers were absent, the access table retained bootstrapped Simone plus activated Stefan instead of matching its empty pre-run snapshot, and immutable normalized operation/hash expectations were missing. After marker implementation, removing forced process.exit exposed the four store-local pools: the child emitted handler/auth markers but required SIGKILL after 5 seconds. This drove the explicit shared API DB lifecycle.
• green_evidence: 2026-07-14 final exact GREEN exited 0: 1 file and 1 test passed in 1.927s; validate:runtime-product returned {"valid":true,"errors":[]}. Full API validation passed 8 files and 66 tests; full auth validation passed 2 files and 6 tests; both typechecks, focused Oxlint/Oxfmt, git diff --check, empty docker ps --filter name=hi-ip319-, and empty runtime API process proof passed.
• codebase_design_notes: Product mutations use supported public HTTP actions only. The original IP-319 fixture remains immutable historical evidence and is not rewritten for provider mode. The complete provider-mode fixture preserves operation order, statuses, content types, relevant headers, and normalized raw JSON bytes/field order; normalization is limited to declared run-varying IDs, timestamps, HTTP dates, and cookie values. The test and independent validator both read that provider-mode document directly, while the validator also recomputes every normalized body hash before comparing all seven operations. Database inspection remains limited to fixture snapshot/setup, persistence proof, provenance cleanup, exact access-state restoration, and cleanup verification. Database-mode API stores receive one index-owned shared DB while all no-argument builders/Layers remain supported; exported API disposal closes handler, API DB, and lazily loaded auth DB in order.
• review_mode: cli
• runtime_validation: required
• runtime_target: POST /api/reports, Better Auth operator session, GET /api/backoffice/project-usages, and POST /api/backoffice/access-users against supported local Postgres and email adapters.
• runtime_evidence: Ignored tmp/runtime-product/evidence.json records correlation ip319-89f086d1-87b1-4158-9ef7-faeac93267ab; all seven normalized provider-enabled public operations exactly match authoritative apps/api/test-fixtures/runtime-product-provider.json, including raw JSON byte order and recomputed SHA-256 hashes. The preserved original apps/api/test-fixtures/runtime-product/expected.json remains governed immutable evidence but is not the provider-mode comparison target. Authenticated observation found report dfc02e7c-87d3-4b1f-8002-6cb5181a338e; production persistence, invitation persistence, and captured email correlate to the same run. Lifecycle evidence records natural exit 0, no forced termination, and ordered handler/API-DB/auth-DB disposal markers.
• runtime_cleanup: Snapshotted every access row before child start, deleted exact introduced access/auth/report/verification/project rows, restored every pre-existing access row field-for-field, and asserted the full sorted table equals its snapshot. Verified report/access absence, preserved ip319-runtime-sentinel, closed email/verification DB resources and the run-owned container, and proved no hi-ip319-* container or runtime API harness process remained.

T6: Characterize backoffice, web, and shared UI behavior

• depends_on: [T1]
• location: apps/backoffice/package.json, apps/backoffice/src/public-routes.test.tsx, apps/backoffice/src/lib/actions.test.ts, apps/backoffice/e2e/public-routes.spec.ts, apps/backoffice/playwright.config.ts, apps/web/package.json, apps/web/src/public-routes.test.tsx, packages/ui/package.json, packages/ui/src/public-ui-contract.test.tsx, apps/backoffice/test-fixtures/browser, apps/web/test-fixtures, packages/ui/test-fixtures, behavior-contract/frontend.json, behavior-contract/web.json, behavior-contract/ui.json
• description: Cover API normalization/cookies, auth redirects, visible loading/error/forbidden/not-found states, forms/invalidation, current web routes, shared UI interaction, accessibility, state/class behavior, and CSS consumer integration.
• validation: Component/route tests and browser scenarios cover visible states without private assertions.
• status: Completed
• log: Characterized existing backoffice, parked web, and shared UI outcomes with one immutable fixture and one authoritative behavior fragment per owning workspace. Added comprehensive server-action contracts, unique run-owned portless app/API origins, deterministic authenticated/anonymous/error fixtures, OTP success/failure and unsafe-redirect sanitization, loading proof, and one persisted invite mutation. Fixed the discovered private-cache error-prototype loss at the narrow API seam so rejected detail reads rehydrate a fresh local error and render the intended not-found outcome; unavailable reads remain inline. Browser output is confined to the runner-owned OS temp directory and removed on success, failure, or signal. No visual product redesign or screenshot delta.
• files edited/created: bun.lock; apps/backoffice/package.json; apps/backoffice/playwright.config.ts; apps/backoffice/src/public-routes.test.tsx; apps/backoffice/src/lib/actions.test.ts; apps/backoffice/src/lib/api.ts; apps/backoffice/src/lib/api.test.ts; apps/backoffice/e2e/public-routes.spec.ts; apps/backoffice/test-fixtures/browser/api-harness.ts; apps/backoffice/test-fixtures/browser/run.ts; apps/backoffice/test-fixtures/browser/expected.json; apps/web/package.json; apps/web/src/public-routes.test.tsx; apps/web/test-fixtures/public-routes.json; packages/ui/package.json; packages/ui/src/public-ui-contract.test.tsx; packages/ui/test-fixtures/public-ui.json; behavior-contract/frontend.json; behavior-contract/web.json; behavior-contract/ui.json; apps/wiki/content/docs/project/specs/cli/IP-319-establish-one-comprehensive-behavior-contract/PLAN.md
• backlog_item_id: IP-330
• backlog_item_url: https://linear.app/devpunks/issue/IP-330/classify-and-characterize-every-public-behavior-seam
• relation_mode: native
• assigned_skills: [agent-browser, async-react-patterns, autoreview, better-auth-best-practices, codebase-design, design-taste-frontend, effect-authoring, effect-backend-structure, effect-best-practices, effect-recoverable-actions, frontend-domain-structure, improve-codebase-architecture, next-best-practices, next-cache-components, parallel-research, quality-types, react-doctor, simplify, tdd, vercel-composition-patterns, vercel-react-best-practices]
• tdd_status: required
• tdd_target: Backoffice public route scenario fails because key visible states are not characterized.
• red_command: bun run --cwd apps/backoffice test -- src/public-routes.test.tsx
• expected_red_failure: Missing route/component fixture or visible state assertion.
• green_command: bun run --cwd apps/backoffice test && bun run --cwd apps/backoffice test:browser && bun run --cwd apps/web test && bun run --cwd packages/ui test
• reason_not_testable:
• red_evidence: 2026-07-14 exact RED exited 1 with No test files found for src/public-routes.test.tsx. Browser correction RED then proved typed BackofficeRequestRejected errors lost their prototype across the private cache boundary and rendered the generic error boundary. Focused cache regression RED failed 2/2 because no decoder rehydrated rejected/unavailable results after JSON round-trip.
• green_evidence: 2026-07-14 exact GREEN passed: backoffice 7 files/26 tests, isolated Playwright 8/8, web 1 file/2 tests, and shared UI 1 file/2 tests. Backoffice, web (with required NEXT_PUBLIC_SERVER_URL), and UI typechecks passed; frontend, web, and UI fragment validation passed; backoffice/web/UI Oxlint and Oxfmt, focused root Oxfmt, dependency-resolution checks, 11-line T6-only lock diff, git diff --check, and cleanup process/temp/repo-output audits passed. React Doctor exited 0 with empty diagnostics (backoffice 87, web 100, UI 100).
• codebase_design_notes: Tests assert rendered/public outcomes while product routes stay in apps and reused UI stays in packages/ui. Each owning workspace has an immutable checked-in expectation fixture consumed by its tests and a separately validated behavior fragment. Server-action tests lock exact API calls, feedback, cache tags, paths, validation short-circuits, and normalized public failures. The cached detail reader returns only a plain discriminated result; the exported non-cached wrapper rehydrates a fresh local BackofficeApiError, preserving cache tags/invalidation and page instanceof semantics. Browser services use direct installed binaries and runner-owned process handles; cleanup terminates Playwright, app, API, and proxy in reverse order. Rejected detail renders the not-found UI with noindex under document status 200 because the loading boundary has already streamed; unknown static routes remain HTTP 404.
• review_mode: mixed
• runtime_validation: required
• runtime_target: Temp-output ownership; anonymous redirects/login interaction; OTP send, invalid OTP, successful session, and unsafe-next sanitization; authenticated dashboard, access, and project detail; streamed loading; rejected and unavailable detail outcomes; persisted invite mutation; unknown-route not-found through isolated portless browser services.
• runtime_evidence: Playwright passed 8/8 in 11.1s: temp output stayed in run-owned state; anonymous redirects/login interaction; OTP success, exact invalid-OTP feedback, successful sentinel-cookie session, and unsafe next sanitized to /; authenticated route navigation; real loading boundary; rejected not-found versus unavailable inline failure; persisted invite; unknown-route 404. Rejected detail froze exact streamed semantics: document status 200, visible Nothing here, and head robots noindex.
• runtime_cleanup: Runner-generated origins and proxy port are unique per run. Playwright output lives only under the runner-owned OS temp state. The runner retains and terminates Playwright, Next, API, and proxy handles in reverse order and removes state on success, failure, SIGINT, or SIGTERM. Post-success audit found no matching PID, temp directory, or repo-local browser result.

T7: Characterize wiki generation, env validation, and scaffold schemas

• depends_on: [T1]
• location: apps/wiki/package.json, apps/wiki/scripts/public-wiki-contract.test.ts, apps/wiki/src/public-routes.test.tsx, apps/wiki/test-fixtures, packages/env/package.json, packages/env/src/public-env-contract.test.ts, packages/env/test-fixtures, packages/scaffold/package.json, packages/scaffold/src/public-scaffold-contract.test.ts, packages/scaffold/test-fixtures, behavior-contract/wiki.json, behavior-contract/env.json, behavior-contract/scaffold.json
• description: Add temp wiki sync create/update/prune/meta tests; redirects/docs/search/LLM/Markdown/OG/404 evidence; env valid/invalid/empty/default/exposure tests; scaffold rejection, round-trip, managed-file, provenance, and semantic shape tests.
• validation: Generation/routes are deterministic; env exposure/failures explicit; scaffold schemas reject invalid input and round-trip complete records; temp sync trees, outputs, servers, and route fixtures are removed without mutating canonical wiki content.
• status: Completed
• log: Characterized wiki sync entirely in run-owned temp trees, including stale check-only reporting without mutation, exact create/update/prune/meta bytes, idempotence, canonical-content protection, and cleanup. Characterized all 24 concrete section redirects, all 13 legacy spec redirects, six dynamic/rest-preserving redirects, and current docs rendering/metadata, deterministic search, LLM index/full, Markdown, OG PNG dimensions, and missing-route outcomes. Locked env server/client acceptance, rejection, empty/default, and exposure behavior through isolated package-consumer processes. Locked all 14 exported runtime scaffold schemas through direct valid round trips and invalid rejection, while retaining every managed-file kind, provenance, and unknown-field shape. Split the planned combined fragment into one authoritative fragment per owning workspace as required by the validator.
• files edited/created: bun.lock; apps/wiki/package.json; apps/wiki/scripts/public-wiki-contract.test.ts; apps/wiki/src/public-routes.test.tsx; apps/wiki/test-fixtures/public-wiki-sync.json; apps/wiki/test-fixtures/public-routes.json; packages/env/package.json; packages/env/src/public-env-contract.test.ts; packages/env/test-fixtures/public-env.json; packages/scaffold/src/public-scaffold-contract.test.ts; packages/scaffold/test-fixtures/public-scaffold.json; behavior-contract/wiki.json; behavior-contract/env.json; behavior-contract/scaffold.json; apps/wiki/content/docs/project/specs/cli/IP-319-establish-one-comprehensive-behavior-contract/PLAN.md
• backlog_item_id: IP-330
• backlog_item_url: https://linear.app/devpunks/issue/IP-330/classify-and-characterize-every-public-behavior-seam
• relation_mode: native
• assigned_skills: [agent-browser, async-react-patterns, autoreview, codebase-design, design-taste-frontend, effect-authoring, effect-backend-structure, effect-best-practices, effect-recoverable-actions, frontend-domain-structure, improve-codebase-architecture, next-best-practices, next-cache-components, parallel-research, quality-types, react-doctor, simplify, tdd, vercel-composition-patterns, vercel-react-best-practices]
• tdd_status: required
• tdd_target: A temp-tree wiki sync fixture produces an incorrect create/update/prune/meta result.
• red_command: bunx vitest run apps/wiki/scripts/public-wiki-contract.test.ts
• expected_red_failure: The public sync result differs from the expected temp-tree create/update/prune/meta fixture.
• green_command: bun run --cwd apps/wiki test && bun run --cwd packages/env test && bun run --cwd packages/scaffold test
• reason_not_testable:
• red_evidence: 2026-07-14 exact RED bunx vitest run apps/wiki/scripts/public-wiki-contract.test.ts exited 1 with No test files found, proving the public sync characterization target was absent.
• green_evidence: 2026-07-14 exact GREEN package tests exited 0: wiki 2 files/6 tests, env 1 file/5 tests, scaffold 2 files/9 tests. The wiki route test executes 43 immutable redirect cases: all 24 concrete section mappings, all 13 legacy spec mappings, and six dynamic/rest-preserving cases. The scaffold contract directly round-trips valid input and rejects invalid input for all 14 current runtime schema exports. Safe wiki next typegen plus direct tsc --noEmit, env/scaffold typechecks, all three authoritative fragment validators ({\"valid\":true,\"errors\":[]}), focused Oxlint/Oxfmt, canonical wiki/source/docs no-diff proof, temp-root cleanup, minimal two-line lock importer diff, and git diff --check passed. Full wiki/env/scaffold checks remain repository-baseline red on pre-existing formatting/lint findings outside T7; no T7-local finding remains.
• codebase_design_notes: Kept sync behind its exported script seam and injected only run-owned wiki/repository roots; check-only fingerprints the full tree and apply mode locks exact output before proving idempotence. Route tests call exported pages/handlers and substitute only framework/source boundaries with deterministic fixtures while retaining the real OG response encoder. Env tests consume the package exports in isolated Bun processes so validation, defaults, exposure, and failures stay at the caller seam. Scaffold remains behavior-free; tests exercise only exported Effect schemas. Separate wiki/env/scaffold fragments preserve the validator's one-workspace ownership invariant.
• review_mode: mixed
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T8: Make one comprehensive local-and-CI contract

• depends_on: [T2, T5, T6, T7]
• location: package.json, turbo.json, scripts/behavior-contract/root-suite.test.ts, scripts/behavior-contract/validate-repository.mjs, .github/workflows/behavior-contract.yml
• description: Validate and aggregate every family fragment through the root behavior command; make config declare reason_not_testable and run static/consumer proof; retain $TURBO_DEFAULT$ while declaring behavior inputs/env; add a required CI workflow that invokes the exact same single root command with manifest validation inside it.
• validation: One forced run reports 12 participants, identical local/CI command identity, explicit hashes, and no CI-only branch.
• status: Complete
• log: 2026-07-14 completed T8 as the structural breadth checkpoint: one aggregate-guarded root command, config static consumer proof, exact Turbo declarations and resolved inputs/env/hashes, 12-workspace participation, browser and runtime-product coverage, and byte-identical CI invocation. The earlier exact root breadth run passed all 14 uncached tasks in 30.19s. Review found the first root selection omitted the declared backoffice browser seam and API runtime validator; structural RED reproduced both omissions, and package-scoped Turbo tasks now include them without creating non-existent tasks in other workspaces. API test caching is disabled so its ignored runtime evidence is always produced before the uncached validator. CI installs Playwright Chromium before invoking the unchanged root command. A second review found the browser runner depended on machine-global portless. Official docs, registry, and source inspection established project-local installation and its binary contract. The latest 0.15.2 proxy stalled before routing when invoked through Bun; cleanup completed. Backoffice therefore owns the previously proven exact 0.14.0 dependency, invokes its workspace binary directly, and CI supplies the package's declared Node 24 runtime. Lock audit retained scaffold-managed wiki latest declarations while root overrides preserve the already-baselined oxfmt 0.57.0, oxlint 1.72.0, and ultracite 7.8.3 behavior; Bun 1.3.5 produces only the required +11/-3 lock delta and accepts a frozen install. The strengthened aggregate passes 4/4 with 81 assertions, validates 12/12 workspace contracts, and checks exact declared and resolved inputs plus env. Direct browser RED exposed a false-ready 404 from portless; readiness now accepts only status below 400, and the rerun passed 8/8 with owned-process and run-directory cleanup. The current exact root rerun is 13/14 solely because the reproducible CLI live-registry metadata lookup exceeded its ambient 750 ms cutoff. That failure is preserved and carried explicitly to T9 as determinism RED, not masked with a fixture or timeout change. T8 Complete therefore means structural breadth is proven; T9 owns stable determinism under repeated and concurrent execution.
• files edited/created: package.json (root toolchain overrides), turbo.json, bun.lock, .github/workflows/behavior-contract.yml, scripts/behavior-contract/root-suite.test.ts, scripts/behavior-contract/validate-repository.mjs, behavior-contract/api-contract.json, behavior-contract/config.json, behavior-contract/contract.json, packages/config/package.json, packages/config/public-config-contract.test.ts, packages/config/test-fixtures/public-config.json, apps/backoffice/package.json, apps/backoffice/test-fixtures/browser/run.ts (status-below-400 readiness and cleanup), apps/wiki/content/docs/project/specs/cli/IP-319-establish-one-comprehensive-behavior-contract/PLAN.md
• backlog_item_id: IP-331
• backlog_item_url: https://linear.app/devpunks/issue/IP-331/run-one-comprehensive-high-signal-repository-suite
• relation_mode: native
• assigned_skills: [codebase-design, quality-types, tdd, turborepo, simplify]
• tdd_status: completed
• tdd_target: The aggregate test parses Turbo dry-run JSON and reports only 7 of 12 participants, undeclared inputs, and no identical CI command.
• red_command: bun test ./scripts/behavior-contract/root-suite.test.ts
• expected_red_failure: Five workspaces, explicit behavior inputs, repository validation, or the exact CI command identity is absent.
• green_command: bun test ./scripts/behavior-contract/root-suite.test.ts && bun run test -- --force --output-logs=errors-only
• reason_not_testable: not_applicable
• red_evidence: 2026-07-14 the initial exact RED command found no target file. After authoring the aggregate contract, it failed 0/3: repository validator absent, Turbo test inputs empty (and config command non-existent), and CI workflow absent. Review RED failed 2/3: Turbo rejected missing project tasks test:browser and validate:runtime-product, and CI lacked Playwright Chromium installation; the root script also did not execute its aggregate guard. The tightening source audit then failed because exact input/env equality assertions were absent. The strengthened aggregate failed 3/4 with 20 assertions when it treated Turbo's resolved ../../ globs as undeclared root tokens; the corrected contract verifies both declared and resolved forms. Direct browser validation failed 7/8 because the readiness probe accepted portless's route-not-ready 404.
• green_evidence: 2026-07-14 structural breadth GREEN: an earlier exact root command passed all 14 uncached tasks in 30.19s, comprising all 12 workspace tests plus @punks/backoffice#test:browser and dependent @punks/api#validate:runtime-product. The current strengthened aggregate passes 4/4 with 81 assertions; the repository validator reports 12 workspaces/12 contracts with no errors. It checks the exact four declared task definitions and all 14 resolved tasks: each declaration retains $TURBO_DEFAULT$ and both $TURBO_ROOT$ behavior globs, and every resolved task has a 16-byte hex hash, exact repository inputs, and exact CI/NODE_ENV/TZ env. Config's locked static options and OS-temp TypeScript consumer proof passed. Bun 1.3.5 frozen install reported no changes; the surgical lock delta is +11/-3 and contains only the backoffice portless importer/resolution, wiki latest declarations, and root overrides for the already-baselined tool versions. Direct browser validation passed 8/8 after changing readiness to require status below 400, with no owned process or run directory remaining. Focused Oxlint, Oxfmt, TypeScript, fragment validation, and git diff check passed; Oxlint emitted only the pre-existing module-type warning for packages/config. The current exact root rerun is 13/14: only @punks/cli#test fails because its live-registry package metadata request reproducibly exceeds the ambient 750 ms cutoff. This is the explicit T9 isolation/determinism RED and remains unmasked; it does not negate T8's completed structural breadth checkpoint.
• codebase_design_notes: Root orchestration executes its non-recursive aggregate guard, then delegates to package-owned Turbo commands. Package-scoped task definitions avoid phantom tasks. The API validator depends on its uncached API test producer, preserving ignored evidence coherence; backoffice owns the exact portless dependency, binary path, and 2xx/3xx readiness boundary. Root package overrides reconcile scaffold-managed wiki latest specs with the existing reproducible toolchain without changing the wiki manifest. Config remains the sole reason_not_testable workspace but participates through static/consumer proof. The public HTTP protocol seam belongs to packages/contract; API request/provider seams remain with apps/api. CI installs Chromium, then invokes the exact local root command without a conditional branch.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T9: Prove isolation, determinism, and comparable optimization evidence

• depends_on: [T8]
• location: scripts/behavior-contract/isolation.test.ts, scripts/behavior-contract/repeat.mjs, scripts/behavior-contract/cleanup.mjs, package.json, .reports/behavior-contract
• description: Audit the run-owned env/global/HOME/XDG/git/port/time fixtures created by family tasks; prove repeated, Vitest seeded-shuffle, serial-Turbo, and normal-concurrency results; assert cleanup; record a forced-uncached after measurement comparable to the 22.79-second baseline and investigate regressions.
• validation: Supported concurrency settings, fixed seeds, repeats, and cleanup are green with identical results. Measurements remain threshold-free.
• status: Complete
• log: 2026-07-16 completed T9 after replacing global prefix/substr cleanup with exact run-state manifests, independent session/root/browser/API fragments, verified detached process groups, exact run-scoped evidence/container ownership, fail-closed Docker inspection, aggregate cleanup reports, strict repeat arguments, isolated parent/browser route handoff, and task-scoped Turbo pass-through. Final repeat report .reports/behavior-contract/repeat-session-3b3dcb3c-6797-4dbf-9597-9becdc5784a9.json recorded identical:true and successful:true: run 1 completed 14/14 tasks with exit 0 in 31.427s and run 2 completed 14/14 tasks with exit 0 in 30.944s. Internal cleanup was valid:true with errors:[]. Standalone cleanup was valid:true with empty discovered, removed, remaining, unknown, and reports. The timed forced root exited 0 with all 14 Turbo tasks green; its root guard passed 4/4 with 99 assertions, and /usr/bin/time -p reported real 32.16, user 105.53, and sys 42.01. Worktree status was byte-identical before and after, and final owned state was clean.
• files edited/created: scripts/behavior-contract/isolation.test.ts; scripts/behavior-contract/repeat.mjs; scripts/behavior-contract/cleanup.mjs; scripts/behavior-contract/measurement.schema.json; scripts/behavior-contract/root-suite.test.ts; turbo.json; apps/backoffice/test-fixtures/browser/run.ts; apps/api/src/runtime-product-contract.test.ts; apps/api/scripts/validate-runtime-product.mjs; packages/auth/src/auth-email-contract.test.ts; package.json; .gitignore
• backlog_item_id: IP-331
• backlog_item_url: https://linear.app/devpunks/issue/IP-331/run-one-comprehensive-high-signal-repository-suite
• relation_mode: native
• assigned_skills: [codebase-design, quality-types, simplify, tdd, turborepo]
• tdd_status: completed
• tdd_target: Isolation validator rejects ambient mutable state and missing cleanup declarations.
• red_command: bun test ./scripts/behavior-contract/isolation.test.ts
• expected_red_failure: The audit identifies a concrete ambient env/global/HOME/XDG/git/port/clock, wiki sync, CLI dist, or missing-cleanup owner.
• green_command: bun test ./scripts/behavior-contract/isolation.test.ts && bun run test -- --force --concurrency=1 && bun run test -- --force --concurrency=100% && bun run test -- --force -- --sequence.shuffle --sequence.seed=319 && bun run behavior:repeat -- --runs=2 && bun run behavior:cleanup && /usr/bin/time -p bun run test -- --force --output-logs=errors-only
• reason_not_testable:
• red_evidence: T8 forced runs reproduced the CLI public-output JSON mismatch under full concurrency and twice in focused execution; expected current package metadata became unavailable/null. Direct Bun probes identified a live npm-registry request with a 750 ms cutoff as the ambient owner: 4/5 aborted and one completed in 698 ms before an unchanged root retry passed. Another forced run timed out two packages/contract tests at 5 seconds while the immediate focused suite passed 16/16 in 790ms. T9 must preserve both witnesses and replace ambient resource dependence through the existing public seams.
• green_evidence: 2026-07-16 final GREEN report .reports/behavior-contract/repeat-session-3b3dcb3c-6797-4dbf-9597-9becdc5784a9.json was identical:true and successful:true. Run 1 exited 0 after 31.427s with 14/14 tasks; run 2 exited 0 after 30.944s with 14/14 tasks. Internal cleanup was valid:true with errors:[]; standalone cleanup was valid:true with empty discovered, removed, remaining, unknown, and reports. The final forced root exited 0 with 14/14 Turbo tasks; root-suite passed 4/4 with 99 assertions; /usr/bin/time -p reported real 32.16, user 105.53, and sys 42.01. Worktree status was byte-identical before and after, and final owned state was clean.
• codebase_design_notes: Put mutable dependencies behind existing public seams and per-run fixtures; no test-only product API.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T10: Close IP-319 evidence and documentation

• depends_on: [T9]
• location: apps/wiki/content/docs/project/specs/cli/IP-319-establish-one-comprehensive-behavior-contract, docs/README.md, relevant wiki/runbooks, Linear IP-319/IP-330/IP-331
• description: Fill RED/GREEN/runtime evidence, uncached measurements, participation, adapter contracts, review, docs-ingest, PR #76, and tracker links. Do not ready downstream epics until IP-330 proof is explicit.
• validation: Task evidence complete, mandatory review has no blocker, docs ingest complete/no-op, Linear links durable.
• status: Complete
• log: 2026-07-16 private/internal docs ingest recorded the proven IP-319 contract: 12 participating workspaces, 11 testable workspaces, packages/config static and consumer proof, 20 public seams (6 byte-for-byte locked, 13 semantically equivalent, 1 intentionally changed), eight deterministic/real adapter families, repeat report 3b3dcb3c-6797-4dbf-9597-9becdc5784a9 with identical successful 14/14 runs in 31.427 and 30.944 seconds, valid cleanup, and final findings-first review PASS. The last pushed-head behavior-contract CI at fabd4b23 was red from bounded clean-checkout assumptions plus unrelated or stale scaffold baseline/hash drift. Per maintainer direction, no further investigation or global/CI gate was run. The maintainer accepted the existing T1-T9, review, and docs evidence. T10 is complete under that scoped acceptance. Draft PR #76 remains draft, unmerged, and undeployed.
• files edited/created: apps/wiki/content/docs/project/specs/cli/IP-319-establish-one-comprehensive-behavior-contract/{PLAN.md,IMPLEMENTATION-NOTES.md,SPEC.md,PHASE-HANDOFF.md}; apps/wiki/content/docs/cli/validation/behavior-contract-validation.mdx; apps/wiki/content/docs/cli/validation/meta.json; apps/wiki/content/docs/harness/validation-and-tools/validation-gates.mdx; apps/wiki/index.md; apps/wiki/log.md; docs/README.md
• backlog_item_id: IP-331
• backlog_item_url: https://linear.app/devpunks/issue/IP-331/run-one-comprehensive-high-signal-repository-suite
• relation_mode: native
• assigned_skills: [docs-ingest-phase, review-phase, simplify]
• tdd_status: not_applicable
• tdd_target: Durable execution, review, measurement, docs, and tracker evidence is complete.
• red_command: not_applicable
• expected_red_failure: not_applicable
• green_command: bun run test -- --force --output-logs=errors-only && bun run check && bun run check-types && bun run build && bun run --cwd apps/cli build && bun run behavior:cleanup && git diff --check
• reason_not_testable: Evidence and documentation closeout does not change runtime behavior.
• red_evidence:
• green_evidence: Private/internal docs artifacts are written and final findings-first review returned PASS. Existing T9 evidence records two identical successful 14/14 runs, valid internal and standalone cleanup, and threshold-free timing evidence. The last pushed-head behavior-contract CI at fabd4b23 was red from bounded clean-checkout assumptions plus unrelated or stale scaffold baseline/hash drift. The assigned clean-checkout corrections are included in the closeout diff; unrelated scaffold drift is outside this closeout. Per maintainer direction, no further investigation or global/CI gate was run. Targeted formatting and git diff --check are the closeout validation for this documentation pass.
• codebase_design_notes: not_applicable
• review_mode: mixed
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

Testing Strategy

• Execute vertical RED-to-GREEN tracer bullets per task.
• Assert exact bytes only for stable managed assets and public JSON.
• Assert semantic equality for context outcomes and meaningful ordering.
• Exercise real domain policy with deterministic boundary Layers.
• Run one family contract against deterministic and real implementations.
• Keep mutable state run-owned and clean by provenance.
• Run the same root command locally and in CI.
• Record comparable forced-uncached runs per optimization slice without thresholds.

Validation Gates

1. T1 proves the schema and validator rules independently.
2. T2-T4, T6, and T7 own disjoint family fragments and capture real RED/GREEN evidence at public seams.
3. T5 proves and cleans one supported public runtime-product scenario.
4. T8 reports all 12 workspaces through one local-and-CI command with explicit inputs.
5. T9 proves serial/normal concurrency, Vitest seeded order, repetition, cleanup, and comparable measurements.
6. T10 records mandatory review, docs ingest, PR evidence, and the maintainer-accepted closeout deviation. The planned packaged build and repo check/types/build were not rerun.

Risks and Mitigations

• Exact snapshots can freeze incidental output: byte-lock only managed assets and public JSON.
• Real adapters can be slow/flaky: one focused contract, run-id resources, local services, typed failures, cleanup.
• Browser tests can duplicate component tests: browser proof at workflows, component proof at shared UI seams.
• Parallel tasks can overlap root config: T2-T4, T6, and T7 own separate fragments and workspaces; T8 alone owns root integration.
• Current Effect guidance is v3-era: characterize without choosing v4; IP-320 owns the pin.
• Two plan writers stalled under thread limits: require independent plan-reviewer approval before implementation.

Unresolved Questions

None. Q1-Q58, Linear scope, single-branch constraints, and repository evidence close planning decisions.

Planned Review and Docs Ingest

• Independent plan-reviewer passed after checking dependencies, overlap, RED targets, commands, runtime proof, and skill routing.
• Final findings-first implementation review returned PASS.
• Private/internal docs ingest routed the operational flow before updating the validation-gates concept, source bookkeeping, navigation, and root docs. No public-doc path was required.
• T10 is complete from the recorded T1-T9 evidence, final findings-first review, routed docs, and explicit maintainer acceptance. The normal future local-and-CI policy remains documented in the validation flow.