Plan: Operate through one domain-first Effect v4 architecture

Plan State

• Status: In Progress; T1-T10, T11 docs/review, and Linear closeout are complete; parent final docs commit/push and post-doc stack gate remain
• Mode: parallel: true
• Scope: IP-320 with every IP-332, IP-333, IP-334, IP-335, and IP-336 acceptance signal
• Delivery branch: team/stefan/ip-320-effect-v4-boundaries
• Pull request base: team/stefan/refactor-cli-architecture
• Parent pull request: draft PR #76 remains the unmerged, undeployed M7-M9 delivery vehicle; the IP-320 child PR is created during delivery only
• Merge policy: the child branch and PR target team/stefan/refactor-cli-architecture, never main; keep the child unmerged until T11 hands it back to the parent integration branch

Initial Situation

The repository catalog currently resolves Effect 3 across seven direct consumers: apps/api, apps/cli, apps/backoffice, packages/auth, packages/contract, packages/db, and packages/scaffold. packages/env currently uses Zod-only helpers but must become the reusable Effect v4 configuration-primitive owner required by IP-335. The root catalog uses ranges for effect and the existing @effect/* family, so it does not provide the exact, coordinated generation required by IP-333.

The current code is architecture-shaped but not domain-first as one system. The API is mostly flat under apps/api/src; CLI product behavior is split across core, content, baseline, scaffold, update, control-plane, and command modules; expected failures are inconsistently typed or translated early; application and integration code reads process.env; and packages/contract exports one broad protocol plus a concrete Fetch client Layer. Existing IP-319 behavior-contract evidence protects 20 public seams and must remain the regression authority throughout this refactor.

The approved spec and live Linear hierarchy are complete. IP-320, IP-332, and IP-333 are In Progress; IP-334, IP-335, and IP-336 remain Backlog children. Native relations record IP-333 as blocking IP-332, IP-334, IP-335, and IP-336. Child comments are empty. The IP-320 delivery-start comment records this branch and its PR base.

Issue

The repository cannot safely migrate by changing package versions first and repairing architecture later. Effect v4 consolidates former package surfaces under effect and effect/unstable/*, changes service, schema-error, configuration, CLI, HTTP, and SQL APIs, and requires every participating workspace to move together. A workspace-by-workspace vertical migration would create temporary v3/v4 translation seams and repeat architecture decisions.

Delivery must therefore establish one exact generation first, then migrate breadth-first through deliberate public roots, typed errors, focused configuration, protocol ownership, feature mechanics, and application-root composition. The final repository must preserve classified public behavior while removing all v3 dependencies, imports, runtime leakage, ambient feature configuration, generic buckets, broad protocol barrels, and stale compatibility aliases.

Proposed Solution Shape

Use the root catalog and lockfile as the sole version authority. T1 records and pins the already-selected planning evidence set—effect, @effect/platform-bun, @effect/sql-pg, and @effect/vitest at exactly 4.0.0-beta.98—after checking its peer matrix and selected source. T1 changes manifests and lock resolution only. It does not migrate production imports, claim zero-v3 source closure, or close IP-333; those outcomes converge later after every production slice moves.

Then migrate breadth-first:

1. Establish deliberate public roots and an import-boundary contract across CLI, API, and coherent shared-package domains.
2. Preserve expected failures through schema-backed domain errors and normalize raw failures only in integrations.
3. Move environment decoding to root configuration and inject focused services or providers.
4. Split shared protocol into baseline, telemetry, reports, backoffice, and narrowly shared common surfaces while returning runtime ownership to consumers.
5. Complete CLI, API/shared backend, and backoffice/scaffold migrations in parallel only after the shared architecture levels are green.
6. Close with repository-wide static, contract, packaged, runtime-product, consumer, and behavior-classification gates.

Design-it-twice result:

1. Workspace-first migration: finish CLI, then API, then packages. This reduces local write overlap but creates temporary translation layers, encourages duplicated service/config/error choices, and violates the accepted breadth-first migration.
2. Architecture-level migration: establish each system-wide boundary before completing peer product surfaces. This keeps one generation and one dependency direction visible, allows later app completion in disjoint write scopes, and matches the accepted Q57 ordering.

Choose option 2. Each T2-T8 architecture level is divided into specialist-owned workspace/package slices. Slices at one level may run in parallel only when their write scopes are disjoint; the explicit level convergence gate must pass before the next breadth-first level starts. T2-T4 convergence is deliberately focused on the architecture level each wave owns, so later same-epic v4 work cannot deadlock an earlier level. T5-CONTRACT is the first isolated full-package gate. T6, T7, and T8 own the first full CLI, API/auth/db, and backoffice/scaffold surface gates respectively; T9 owns repository-wide convergence.

Locked Decision Ledger

Branch/Base Intent

• Status: Branch/Base Intent
• Dependency: IP-330, Classify and characterize every public behavior seam
• Evidence: draft PR #76 and apps/wiki/content/docs/project/specs/cli/IP-319-establish-one-comprehensive-behavior-contract/IMPLEMENTATION-NOTES.md record accepted IP-330 characterization evidence.
• Child branch: team/stefan/ip-320-effect-v4-boundaries
• Parent base: team/stefan/refactor-cli-architecture
• Reason: IP-330 readiness is proven on the parent branch. The child PR targets the parent branch, never main; task dependencies remain implementation order inside that child PR.

Research and Codebase Findings

• The bounded selected evidence set is exact: effect@4.0.0-beta.98, @effect/platform-bun@4.0.0-beta.98, @effect/sql-pg@4.0.0-beta.98, and @effect/vitest@4.0.0-beta.98. T1 verifies their peers and locks this set; it does not substitute a newer beta implicitly.
• The current v4 package exports CLI, HTTP, HttpApi, SQL, process, and other APIs from effect/unstable/*. Several v3-era standalone catalog packages have no corresponding v4 beta tag and must be audited for removal or replacement rather than mechanically version-bumped.
• Current v4 source uses Context.Service, Schema.TaggedErrorClass, Config, ConfigProvider, and feature-specific unstable exports. Exact APIs must follow the selected numeric beta source, not local v3-era skill spellings.
• opensrc path --cwd . effect currently resolves the repository's locked Effect 3.22 source. Executors must resolve the selected beta explicitly, for example opensrc path effect@<selected-version>, before authoring v4 code.
• CLI ownership remains local repository scanning, scaffold writing, cache, prompts, skills, hooks, and tools. API owns control-plane behavior. Product logic must not move between them during restructuring.
• apps/api/src/index.ts currently mixes transport, configuration, runtime composition, and handler wiring. Flat feature files contain domain policy plus environment and external-client selection.
• apps/cli/src/index.ts and command modules mix invocation, runtime execution, prompts, rendering, and production dependency selection. Existing runtime filesystem/process contracts are the starting adapter seams.
• packages/contract/src/client.ts supplies concrete Fetch runtime behavior. That behavior must move to CLI/backoffice consumers while protocol definitions remain shared.
• packages/db/src/runtime/db-config.ts is an existing focused config seed, but application and package roots still read ambient environment values elsewhere.
• packages/scaffold is a behavior-free schema package. Its v4 migration must not introduce filesystem, runtime, configuration, or product policy.
• Existing behavior-contract fixtures and root suite provide the final public-seam regression gate. Do not rewrite their classifications to make migration differences pass.

External Research Used

• npm registry metadata and peer dependencies for the exact beta.98 set above, read 2026-07-16.
• Effect-TS/effect-smol only: migration/v3-to-v4.md maps @effect/cli/* to effect/unstable/cli, platform HTTP to effect/unstable/http, HttpApi to effect/unstable/httpapi, and SQL to effect/unstable/sql; its source demonstrates Context.Service and schema-tagged errors.
• sst/opencode only: packages/protocol/src/api.ts and groups/* demonstrate narrow effect/unstable/httpapi protocol areas; packages/protocol/src/errors.ts uses Schema.TaggedErrorClass; services use Context.Service; the server root composes Layers.
• pingdotgg/t3code only: its lint rule rejects manual runPromise/ManagedRuntime.make below intended roots; infra/relay/src/worker.ts composes Layers at the root; configuration and errors use Context.Service and Schema.TaggedErrorClass.
• These three repositories are bounded pattern evidence, not sources for copied product logic or frozen incidental symbol names. No skill rename, skill edit, or skill sync belongs to this epic.
• Completed CLI context architecture grill Q1-Q58 and its status artifact, which lock domain-first roots, root-only runtime/config composition, typed failures, protocol ownership, exact-version timing, and breadth-first migration.
• Existing IP-319 plan and implementation notes, used as the public-behavior and runtime-proof foundation.

Dependency Graph

T1
 -> T2{CLI,API,AUTH,CONTRACT,DB,SCAFFOLD} -> T2-CONTRACT-TEST -> T2-GATE(focused)
 -> T3{CLI,API,AUTH,CONTRACT,DB} -> T3-CONTRACT-TEST -> T3-GATE(focused)
 -> T4-ENV -> T4{CLI,API,BACKOFFICE,AUTH,DB} -> T4-CONTRACT-TEST -> T4-GATE(focused)
 -> T5-CONTRACT(full) -> T5{CLI,API,BACKOFFICE} -> T5-GATE(focused)
 -> [T6-CLI, T7-DB -> T7-AUTH -> T7-API, T8{BACKOFFICE,SCAFFOLD}]
 -> T6-8-GATE -> T9-CLOSEOUT-TEST -> T9 -> T10 -> T11

Parallel Execution Waves

Atomic Specialist Slice Contract

Every hyphenated workspace/package slice below is a stable implementation task, not an informal substep and not permission for one worker to edit multiple workspaces. Each behavior-changing workspace/package slice inherits its family task's description, backlog item, relation mode, review mode, runtime fields, and blank execution-evidence fields, while its location, exact RED/GREEN command, owner, assigned_skills, and dependency are narrowed below. T3, T4, the T5 consumer slices, and T7-AUTH/T7-DB use their explicit slice-level TDD overrides below instead of inheriting a family target. New slices start with status: Planned, log:, one files edited/created: field, red_evidence:, and green_evidence: blank; completed T2 slice state and evidence are recorded in their execution blocks.

T2-CONTRACT-TEST, T3-CONTRACT-TEST, T4-CONTRACT-TEST, and T9-CLOSEOUT-TEST are post-wave validation-only implementation-worker slices. Each owns only its named root test file and overrides inherited TDD fields with tdd_status: not_applicable, red_command: not_applicable, expected_red_failure: not_applicable, no RED claim or evidence, its exact GREEN command below, and reason_not_testable: per-workspace concrete RED/GREEN owns TDD; this slice authors post-wave convergence validation. The named *-GATE tasks are parent-owned strictly readonly convergence checks with the same not-applicable RED fields, green_command equal to the declared aggregate, reason_not_testable: validation-only convergence, and no production or test writes; findings route back to the exact owning slice.

Every behavior-changing workspace/package slice has an executable command with a concrete public test path. RED records the pre-slice public mismatch. T2-T4 GREEN reruns the owned focused test; those architecture-level slices do not claim a full workspace compile while later same-epic migration remains intentionally incomplete. T5-CONTRACT owns the first isolated full-package gate. T5 consumer slices remain focused. T6, T7, and T8 own full CLI, API/auth/db, and backoffice/scaffold tests, typechecks, and builds respectively. T9 owns the repository-wide aggregate. Post-wave validation-only contract slices have no RED and retain their exact focused GREEN contract command.

Readonly Intermediate Gate Contracts

These are concrete parent-owned task ids. Each gate has no write scope, relation_mode: native, tdd_status: not_applicable, red_command: not_applicable, expected_red_failure: not_applicable, reason_not_testable: validation-only convergence, red_evidence: blank, review_mode: cli, runtime_validation: not_required, and runtime_target, runtime_evidence, and runtime_cleanup: not_applicable. Findings route to an owning implementation slice; the gate never patches code or tests.

All four gates use backlog item IP-320, the exact epic URL, assigned_skills: [autoreview, codebase-design, effect-authoring, effect-best-practices, improve-codebase-architecture, parallel-research, quality-types, simplify, tdd, turborepo], and codebase_design_notes: readonly convergence only; public seams remain owned by the implementation slices. Planned gates retain blank log, files edited/created, and evidence fields; completed gates record their readonly result in the table.

Tasks

T1: Pin and record the exact Effect v4 manifest generation

• depends_on: []
• location: package.json; bun.lock; apps/{api,backoffice,cli}/package.json; packages/{auth,contract,db,env,scaffold}/package.json; scripts/effect-v4/dependency-manifest.contract.test.ts; {PLAN.md,IMPLEMENTATION-NOTES.md,meta.json}; apps/wiki/{index.md,log.md}
• description: Verify peer compatibility and selected source for effect, @effect/platform-bun, @effect/sql-pg, and @effect/vitest at exactly 4.0.0-beta.98; pin only the required root catalog, participating manifests, and lock resolution; record the peer/source matrix. This task is manifest/lock/peer/source-selection work only: do not rewrite production imports, remove v3 production code, add compatibility shims, or claim story closure.
• validation: The manifest-only contract reports the exact beta.98 set with no ranges or manifest/lock divergence, a frozen install succeeds, and evidence records the peer/source matrix. IP-333 remains open pending T9 production-source convergence.
• owner: one repository-config implementation worker with exclusive ownership of the named root catalog, lockfile, participating manifests, and dependency-manifest contract test; parent validation is readonly
• status: Completed
• log: Authored the manifest contract first; captured ranged Effect 3 RED; verified npm peer metadata and the matching effect-smol beta.98 source; pinned the four selected root catalog entries; added packages/env to Effect/vitest catalog participation; regenerated and froze bun.lock; repaired the routed page tree so PLAN and IMPLEMENTATION-NOTES appear between SPEC and PHASE-HANDOFF; indexed the in-progress epic and recorded the bounded T1 ingest. No production source or compatibility path changed. IP-333 remains open for T9.
• files edited/created: package.json; packages/env/package.json; bun.lock; scripts/effect-v4/dependency-manifest.contract.test.ts; apps/wiki/content/docs/project/specs/cli/IP-320-domain-first-effect-v4-architecture/{PLAN.md,IMPLEMENTATION-NOTES.md,meta.json}; apps/wiki/{index.md,log.md}
• backlog_item_id: IP-333
• backlog_item_url: https://linear.app/devpunks/issue/IP-333/use-one-exact-effect-v4-generation-repository-wide
• relation_mode: native
• assigned_skills: [agent-browser, async-react-patterns, autoreview, backend-domain-structure, backend-recoverable-actions, 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, logging-best-practices, next-best-practices, next-cache-components, parallel-research, quality-types, react-doctor, simplify, swarm-planner, tdd, turborepo, vercel-composition-patterns, vercel-react-best-practices]
• tdd_status: required
• tdd_target: The manifest/lock contract accepts a range, a non-beta.98 coordinated package, an incompatible peer, or a participating manifest outside the root authority.
• red_command: bun test ./scripts/effect-v4/dependency-manifest.contract.test.ts
• expected_red_failure: The contract is absent or reports ranged Effect 3 catalog entries and no exact beta.98 peer/source record.
• green_command: bun test ./scripts/effect-v4/dependency-manifest.contract.test.ts && bun install --frozen-lockfile
• reason_not_testable:
• red_evidence: bun test ./scripts/effect-v4/dependency-manifest.contract.test.ts failed with root effect catalog ^3.21.2 vs expected 4.0.0-beta.98, lock catalog ^3.21.2 vs expected beta.98, and missing packages/env Effect catalog participation.
• green_evidence: bun test ./scripts/effect-v4/dependency-manifest.contract.test.ts passed 5 tests / 73 assertions; bun install --frozen-lockfile checked 981 installs across 1225 packages with no changes; the focused wiki bookkeeping contract confirmed SPEC -> PLAN -> IMPLEMENTATION-NOTES -> PHASE-HANDOFF, the in-progress index entry, and the bounded T1 log entry; bun run --cwd apps/wiki postinstall generated Fumadocs content successfully.
• codebase_design_notes: The root catalog is the version-authority interface. This slice intentionally leaves production source migration and zero-v3 closure to later breadth-first slices and T9.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T2: Establish deliberate public domain roots and dependency direction

• depends_on: [T1]

• location: Six disjoint slices below plus scripts/effect-v4/domain-boundaries.contract.test.ts at convergence

• description: Run the following as separate implementation-worker tasks at the same breadth-first level. Each workspace worker edits only its owned workspace/package. After those slices are green, T2-CONTRACT-TEST is a separate implementation worker that creates or reconciles only scripts/effect-v4/domain-boundaries.contract.test.ts. The parent only runs T2-GATE read-only and routes findings; it never edits production or test files. No slice advances into typed-error/config/protocol completion work.

  Slice	Worker role	Exclusive write scope	Exact focused GREEN	Deferred full check owner
  T2-CLI	apps-cli	apps/cli/src/{platform,integrations,features,index.ts}	bun run --cwd apps/cli test -- src/features/public-domain-root-contract.test.ts	T6
  T2-API	apps-api	apps/api/src/{platform,integrations,features,index.ts}	bun run --cwd apps/api test -- src/features/public-domain-root-contract.test.ts	T7
  T2-AUTH	packages-auth	packages/auth/src	bun run --cwd packages/auth test -- src/public-domain-root-contract.test.ts	T7
  T2-CONTRACT	packages-contract	packages/contract/src	bun run --cwd packages/contract test -- src/public-domain-root-contract.test.ts	T5-CONTRACT
  T2-DB	packages-db	packages/db/src	bun run --cwd packages/db test -- src/public-domain-root-contract.test.ts	T7
  T2-SCAFFOLD	packages-scaffold	packages/scaffold/{package.json,src}	bun run --cwd packages/scaffold test -- src/public-domain-root-contract.test.ts	T8
  T2-CONTRACT-TEST	root-contract-test	scripts/effect-v4/domain-boundaries.contract.test.ts only	bun test ./scripts/effect-v4/domain-boundaries.contract.test.ts	T6-8-GATE reruns contract

  Each slice creates a deliberate public root around one real caller-facing workflow, rejects internal cross-domain imports and runtime creation below application entrypoints, and removes replaced generic/compatibility barrels without empty pass-through modules.

• validation: T2-GATE runs only the six focused public-root contracts and T2-CONTRACT-TEST. It rejects private cross-domain imports, generic roots, and sub-root runtime creation while representative public behavior remains classified-equivalent. Full workspace type/build gates are deliberately owned by T5-CONTRACT, T6, T7, T8, and T9 after the same-epic v4 migration reaches those surfaces.

• owner: six workspace implementation workers plus one root-contract-test implementation worker; parent convergence gate is strictly readonly

• status: Completed

• log: All six workspace/package public-root slices passed their owned focused contracts. T2-CONTRACT-TEST then passed 15 tests with 133 assertions. The earlier aggregate incorrectly required full workspace typechecks/builds that are expected to fail until T3-T8 migrate the beta.98 source surface; the corrected graph assigns those full gates to their actual completion owners without changing T2 scope or evidence.

• files edited/created: See the six T2 execution-evidence blocks; scripts/effect-v4/domain-boundaries.contract.test.ts; apps/wiki/content/docs/project/specs/cli/IP-320-domain-first-effect-v4-architecture/{PLAN.md,IMPLEMENTATION-NOTES.md,PHASE-HANDOFF.md}

• backlog_item_id: IP-332

• backlog_item_url: https://linear.app/devpunks/issue/IP-332/compose-domain-behavior-through-deliberate-public-boundaries

• 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, swarm-planner, tdd, turborepo]

• tdd_status: not_applicable

• tdd_target: T2 family aggregation; T2 workspace slices own concrete public-root RED/GREEN evidence.

• red_command: not_applicable

• expected_red_failure: not_applicable

• green_command: bun run --cwd apps/cli test -- src/features/public-domain-root-contract.test.ts && bun run --cwd apps/api test -- src/features/public-domain-root-contract.test.ts && bun run --cwd packages/auth test -- src/public-domain-root-contract.test.ts && bun run --cwd packages/contract test -- src/public-domain-root-contract.test.ts && bun run --cwd packages/db test -- src/public-domain-root-contract.test.ts && bun run --cwd packages/scaffold test -- src/public-domain-root-contract.test.ts && bun test ./scripts/effect-v4/domain-boundaries.contract.test.ts

• reason_not_testable: Per-workspace concrete RED/GREEN owns TDD; T2-CONTRACT-TEST and T2-GATE are post-wave convergence validation.

• red_evidence:

• green_evidence: Every focused T2 public-root contract has recorded GREEN evidence below. T2-CONTRACT-TEST passed 15 tests with 133 assertions. T2-SCAFFOLD additionally passed its full package suite and typecheck, but that extra proof is not required to complete the focused architecture level.

• codebase_design_notes: Public feature roots are the cross-domain seam. Actions own policy; services own reusable mechanics; repositories and integration adapters hide external systems. The deletion test forbids pass-through aliases: each public root must concentrate invariants that would otherwise leak to callers.

• review_mode: cli

• runtime_validation: not_required

• runtime_target: not_applicable

• runtime_evidence: not_applicable

• runtime_cleanup: not_applicable

T2-CLI execution evidence

• depends_on: [T1]
• location: apps/cli/**
• owner: apps-cli
• status: Completed
• log: Added the repository-analysis action/model/port domain and explicit CLI feature root; kept repository scanning behind the Node integration adapter; composed that adapter in platform; and routed the existing scaffold workflow through the platform operation. The action owns scan, repo-shape policy, and pack-resolution orchestration without creating or running an Effect runtime. Existing detection and pack mechanics remain in core for the later T6 deletion rather than introducing a compatibility alias.
• files edited/created: apps/cli/src/features/{index.ts,public-domain-root-contract.test.ts,repository-analysis/{action.ts,index.ts,model.ts,port.ts}}; apps/cli/src/integrations/node-repository-scanner.ts; apps/cli/src/platform/repository-analysis.ts; apps/cli/src/{core/detect.ts,core/resolve-packs.ts,scaffold/run.ts}; apps/wiki/content/docs/project/specs/cli/IP-320-domain-first-effect-v4-architecture/{PLAN.md,IMPLEMENTATION-NOTES.md}
• 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 current caller cannot consume repository evidence, repo-shape policy, and resolved packs through one deliberate CLI feature root with an injected scanner port.
• red_command: bun run --cwd apps/cli test -- src/features/public-domain-root-contract.test.ts
• expected_red_failure: The deliberate repository-analysis public root does not exist.
• green_command: bun run --cwd apps/cli test -- src/features/public-domain-root-contract.test.ts
• red_evidence: The exact command failed before production edits because ./repository-analysis did not exist; Vitest reported one failed suite and no collected tests.
• green_evidence: The focused test passed 1 test in 1 file. The chained GREEN remains blocked at apps/cli check-types by the coordinated same-epic migration state after T1's intentional manifest-only pin: broad v3 source/API errors remain across CLI, packages/contract, and packages/scaffold, including unavailable Schema.TaggedError, removed Effect combinators, BunContext, and beta.98-incompatible shared schemas. apps/cli build independently fails because retained v3 @effect/cli, @effect/platform, and printer packages import removed Effect v3 modules, while beta.98 @effect/platform-bun contributes a Bun-only import to the Node bundle. Those failures lie outside T2-CLI's public-boundary scope and must clear in later IP-320 source slices and the final gate. Focused oxfmt --check and git diff --check passed. Advancing into typed-error, protocol, runtime, or complete dependency migration is reserved for later slices.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T2-API execution evidence

• depends_on: [T1]
• location: apps/api/**
• owner: apps-api
• status: Completed
• log: Added the report-submission action/port domain and explicit API feature root. The action owns authenticated-versus-anonymous report policy and delegates persistence through an injected submitter. The platform operation passes the already compatible report store directly to the action, while the HTTP handler resolves request authentication and calls the platform operation. Review removed an empty identity integration alias and added a contract assertion preventing its return. No sub-root runtime, new error family, configuration service, protocol runtime, compatibility alias, or changed public output was introduced.
• files edited/created: apps/api/src/features/{index.ts,public-domain-root-contract.test.ts,report-submission/{action.ts,index.ts,port.ts}}; apps/api/src/platform/report-submission.ts; apps/api/src/index.ts; apps/wiki/content/docs/project/specs/cli/IP-320-domain-first-effect-v4-architecture/{PLAN.md,IMPLEMENTATION-NOTES.md}
• 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: A current API caller cannot submit a harness report through one deliberate feature root that owns authenticated-versus-anonymous submission policy and delegates persistence through an injected port.
• red_command: bun run --cwd apps/api test -- src/features/public-domain-root-contract.test.ts
• expected_red_failure: The deliberate report-submission public root does not exist.
• green_command: bun run --cwd apps/api test -- src/features/public-domain-root-contract.test.ts
• red_evidence: The exact command failed before production edits because ./index under src/features did not exist; Vitest reported one failed suite and zero collected tests.
• green_evidence: The initial focused test passed 1 test in 1 file. Review then identified the report-store integration as an empty identity adapter. The added regression assertion failed with expected true to be false while that file existed; after deleting it and passing the compatible store directly, the focused suite passed 2 tests in 1 file. The independent API build completed successfully with 16 output files. The chained GREEN remains blocked at apps/api check-types by the coordinated same-epic migration after T1's intentional beta.98 manifest-only pin. Existing v3-era API and sibling contract/database sources still use removed or changed surfaces including Context.Tag, Effect.either, Effect.catchAll, Effect.async, Schema.TaggedError, multi-argument Schema.Literal, and old Layer/platform APIs. The new feature test also receives the currently narrowed HarnessReportInput type from the unmigrated shared schema, and the platform composition consumes the unmigrated HarnessReportStore tag. Resolving those compiler failures belongs to later T3/T5/T7/T9 slices. Focused formatting and git diff --check passed. Scoped Oxlint could not load @effect/eslint-plugin because @typescript-eslint/utils is absent in the coordinated install, so no lint findings were produced. The required autoreview helper could not run because the installed Codex client rejected its configured gpt-5.6-sol reviewer as requiring a newer client.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T2-AUTH execution evidence

• depends_on: [T1]
• location: packages/auth/src
• owner: packages-auth
• status: Completed
• log: Added the operator-authentication action/port domain and deliberate feature root. The action owns verification-code email subject/body policy behind an injected sender port; the Resend integration adapter owns provider delivery; and Better Auth composition invokes the action through its public root. Existing environment, database, singleton, and disposal composition remains for T4/T7 rather than advancing later architecture layers. Accepted P2 review follow-up made the policy contract table-driven across sign-in, email-verification, forget-password, and change-email, then proved exact payload forwarding through both the real Resend adapter and createAuthOptions wiring with an injected fake Resend boundary.
• files edited/created: packages/auth/src/features/operator-authentication/{action.ts,index.ts,port.ts}; packages/auth/src/integrations/resend-verification-email-sender.ts; packages/auth/src/{index.ts,index.test.ts,public-domain-root-contract.test.ts}; apps/wiki/content/docs/project/specs/cli/IP-320-domain-first-effect-v4-architecture/{PLAN.md,IMPLEMENTATION-NOTES.md}
• 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: A current auth caller cannot send an operator verification code through one deliberate feature root that owns subject/body policy and delegates provider delivery through an injected port.
• red_command: bun run --cwd packages/auth test -- src/public-domain-root-contract.test.ts
• expected_red_failure: The deliberate operator-authentication public root does not exist.
• green_command: bun run --cwd packages/auth test -- src/public-domain-root-contract.test.ts
• red_evidence: The exact command failed before production edits because ./features/operator-authentication did not exist; Vitest reported one failed suite and zero collected tests.
• green_evidence: The original focused test passed 1 test in 1 file. Before the accepted P2 test follow-up, bun run --cwd packages/auth test -- src/public-domain-root-contract.test.ts src/index.test.ts passed only 4 tests and exposed the coverage gap: two verification types, no real Resend adapter assertion, and no composed callback invocation. Because production already satisfied the missing contracts, this test-only correction has no fabricated behavioral RED. After the correction, the same command passed 8 tests across both files: four table-driven policy cases, exact real-adapter payload forwarding, and actual createAuthOptions callback wiring through an injected fake Resend boundary, plus the existing index regressions. The chained GREEN remains blocked at packages/auth check-types by the coordinated same-epic migration after T1's beta.98 manifest-only pin: pre-existing auth-email-contract.test.ts still uses removed v3 Schema.TaggedError, Effect.async, and changed acquire/release APIs, while sibling packages/db runtime sources still use removed Effect.Service, Layer.unwrapEffect, and v3 service access. No changed T2-AUTH file remains in the compiler errors. Focused oxfmt --check and git diff --check passed. Scoped Oxlint could not load @effect/eslint-plugin, so no lint findings were produced. The required autoreview helper could not run because the installed Codex client rejected its configured gpt-5.6-sol reviewer as requiring a newer client.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T2-CONTRACT execution evidence

• depends_on: [T1]
• location: packages/contract/src
• owner: packages-contract
• status: Completed
• log: Replaced the generic schema/error buckets with deliberate baseline, telemetry, reports, and backoffice protocol roots. Each root owns its current cross-process schemas, accepted public errors, and typed HttpApi group; api.ts now composes those roots. The small common surface contains only primitives shared by multiple protocol areas. No endpoint, request runtime, configuration, consumer behavior, or later typed-error design was added.
• files edited/created: packages/contract/src/{api.ts,api.test.ts,backoffice.ts,baseline.ts,common.ts,index.ts,public-domain-root-contract.test.ts,reports.ts,telemetry.ts}; deleted packages/contract/src/{errors.ts,schemas.ts}; apps/wiki/content/docs/project/specs/cli/IP-320-domain-first-effect-v4-architecture/{PLAN.md,IMPLEMENTATION-NOTES.md}
• assigned_skills: [autoreview, codebase-design, effect-authoring, effect-backend-structure, effect-best-practices, effect-recoverable-actions, improve-codebase-architecture, parallel-research, quality-types, simplify, tdd]
• tdd_status: required
• tdd_target: The typed contract cannot be composed from deliberate protocol-area roots with one-way dependencies; the broad generic schema/error buckets own every area.
• red_command: bun run --cwd packages/contract test -- src/public-domain-root-contract.test.ts
• expected_red_failure: The deliberate baseline, telemetry, reports, and backoffice roots do not exist.
• green_command: bun run --cwd packages/contract test -- src/public-domain-root-contract.test.ts
• red_evidence: The first pre-production run was intercepted before collection by the coordinated beta.98 blocker because retained @effect/platform@0.96.1 imports removed effect/dist/Either.js. The still-pre-production source-level architecture test then failed one test with ENOENT for absent src/baseline.ts, specifically proving the missing-root target.
• green_evidence: The focused architecture contract passed 1 test in 1 file and proves HarnessApi composes all four deliberate roots, each area avoids sibling-area imports, and the composition no longer imports generic schemas or errors buckets. A read-only export parity check found no lost public schema/error symbols, and the OpenAPI fixture Git object remained exactly 92f817385a2bcc9ebec91032fb8f0dab7a0684c4. The package suite also passed this focused test but could not collect the two existing HttpApi suites because retained @effect/platform@0.96.1 imports beta.98-removed effect/dist/Either.js. The chained GREEN remains blocked at packages/contract check-types by the coordinated same-epic beta.98 migration: the relocated, behavior-preserved v3 contract still uses removed or changed Schema.TaggedError, multi-argument Schema.Literal, Schema.optionalWith, Schema.filter, HttpApi NoContent annotations, and typed-client path inference. Those API migrations belong to T3/T5/T9. Focused oxfmt --check and git diff --check passed. Package lint could not load missing @effect/eslint-plugin. Structured autoreview was attempted, but the installed Codex client rejected configured reviewer gpt-5.6-sol as requiring a newer client, so no structured findings were available.
• codebase_design_notes: The protocol-area modules are the public cross-process seams and now own their endpoint groups, schemas, and accepted errors. api.ts is root composition. Dependencies flow from area roots to a genuinely shared common surface only; no area imports another area. The deletion test holds because removing an area root would return its schema/error/endpoint knowledge to the composition module. Consumer-runtime ownership and package subpath exports remain T5 work.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T2-DB execution evidence

• depends_on: [T1]
• location: packages/db/src
• owner: packages-db
• status: Completed
• log: Moved Drizzle database construction into the deliberate persistence root and kept the existing runtime layer modules as direct package-root exports because a pass-through runtime barrel added no meaningful composition. The public contract proves root export parity/importability and checks dependency direction across every runtime module. No schema migration, typed-error, configuration, or consumer rewiring work was advanced.
• files edited/created: packages/db/src/{index.ts,persistence/index.ts,public-domain-root-contract.test.ts}; deleted packages/db/src/runtime/index.ts; apps/wiki/content/docs/project/specs/cli/IP-320-domain-first-effect-v4-architecture/{PLAN.md,IMPLEMENTATION-NOTES.md}
• 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: Database callers can import persistence/schema roots directly, while the package root exposes named runtime layers and every runtime module avoids runtime-to-persistence inversion. Runtime-to-schema imports remain allowed for schema binding.
• red_command: bun run --cwd packages/db test -- src/public-domain-root-contract.test.ts
• expected_red_failure: The package root directly constructs Drizzle and lacks a verified persistence seam, while runtime export parity/importability and subtree dependency direction are untested.
• green_command: bun run --cwd packages/db test -- src/public-domain-root-contract.test.ts
• red_evidence: The pre-slice root constructed Drizzle directly and had no focused contract proving package-root export parity/importability or runtime subtree dependency direction.
• green_evidence: The focused architecture contract passed 1 test in 1 file and proves persistence/schema importability, explicit package-root runtime exports, and recursively scans every runtime source to reject runtime-to-persistence imports while allowing the required runtime-to-schema binding. A follow-up type-only repair added explicit recursive async return and intermediate result types to that contract; the focused test still passes and packages/db check-types no longer reports its prior TS7023, TS7022, or TS7024 errors. The typecheck remains blocked by 23 coordinated beta.98 migration errors, all in unchanged postgres-contract.test.ts and runtime sources using removed or changed v3 schema, context, service, layer, and test-contract APIs. Those failures belong to later T3/T7/T9 slices. Focused oxfmt --check and git diff --check passed.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T2-SCAFFOLD execution evidence

• depends_on: [T1]
• location: packages/scaffold/{package.json,src}
• owner: packages-scaffold
• status: Completed
• log: Split the behavior-free shared schemas into deliberate, caller-resolvable @punks/scaffold/baseline and @punks/scaffold/catalog roots. baseline owns publication, provenance, artifact, and managed-file contracts; catalog owns pack selection, example-repository, and required-tool contracts. The package root remains as compatibility for current real callers and only composes both domains; later consumer rewiring may remove its flattened exports. Neither domain imports the other or owns runtime/configuration behavior. Migrated this package's multi-literal schemas and IP-319 test annotations to beta.98 so the complete required GREEN is clean.
• files edited/created: packages/scaffold/package.json; packages/scaffold/src/{baseline.ts,catalog.ts,index.ts,public-domain-root-contract.test.ts,public-scaffold-contract.test.ts}; docs/README.md; apps/wiki/content/docs/project/specs/cli/IP-320-domain-first-effect-v4-architecture/{PLAN.md,IMPLEMENTATION-NOTES.md}
• assigned_skills: [autoreview, codebase-design, effect-authoring, effect-backend-structure, effect-best-practices, effect-recoverable-actions, improve-codebase-architecture, parallel-research, quality-types, simplify, tdd]
• tdd_status: required
• tdd_target: Scaffold callers cannot resolve separate baseline-publication and catalog-selection package roots; the broad package root owns every shared schema.
• red_command: bun run --cwd packages/scaffold test -- src/public-domain-root-contract.test.ts
• expected_red_failure: The deliberate baseline and catalog schema roots or their package subpath exports do not exist.
• green_command: bun run --cwd packages/scaffold test -- src/public-domain-root-contract.test.ts
• red_evidence: The initial exact pre-production command failed before collection because ./baseline did not exist. The review-correction TDD loop changed the contract to import @punks/scaffold/baseline and @punks/scaffold/catalog; the same exact command then failed before collection with Missing "./baseline" specifier in "@punks/scaffold" package.
• green_evidence: The exact chained GREEN passed: the focused architecture contract passed 1 test in 1 file, then packages/scaffold check-types exited cleanly. The contract proves both domains resolve through public package subpaths, . preserves the existing combined exports for current callers, the domains avoid cross-imports, and neither owns configuration or filesystem/process integrations. bun run --cwd packages/scaffold test passed all 10 tests across 3 files after the minimal beta.98 Schema.Literals and test-generic migration. Focused formatting and git diff --check passed. The broader package check could not start Oxlint because the repository configuration cannot load missing @effect/eslint-plugin; no lint findings were produced.
• codebase_design_notes: The two caller-visible roots concentrate real schema invariants without introducing behavior, configuration, runtime ownership, generic buckets, or one-symbol pass-through modules. index.ts is compatibility composition for current root-import callers; it contains no schemas. Direct subpaths are now the deliberate domain seams, allowing later consumer rewiring to remove flattened compatibility without another schema move.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T2-CONTRACT-TEST execution evidence

• depends_on: [T2-CLI, T2-API, T2-AUTH, T2-CONTRACT, T2-DB, T2-SCAFFOLD]
• location: scripts/effect-v4/domain-boundaries.contract.test.ts
• owner: root-contract-test
• status: Completed
• log: Added the post-wave repository contract over the six T2 workspace slices. Review repair replaced regex import scanning with Bun.Transpiler.scanImports, expanded consumer coverage across every app and shared package source including backoffice, and canonicalized relative, @/*, and @punks/* references across extensions, explicit index, nested paths, and self-package imports. The contract prevents private feature deep imports without rejecting explicit public roots, rejects owning package/composition-root imports from governed contract/scaffold/database subdomains while leaving outside consumers unaffected, enforces canonical sibling direction, recursively rejects generic feature directories, and tokenizes transpiled executable code to detect direct or aliased Effect runners including callback/exit and *With variants, namespace-imported ManagedRuntime.make, and runners passed as values/callbacks without comment/string false positives. The runtime scan remains bounded to T2-owned roots/composition because the accepted plan assigns remaining legacy CLI/API runtime migration to T6/T7.
• files edited/created: scripts/effect-v4/domain-boundaries.contract.test.ts; apps/wiki/content/docs/project/specs/cli/IP-320-domain-first-effect-v4-architecture/{PLAN.md,IMPLEMENTATION-NOTES.md}
• assigned_skills: [autoreview, codebase-design, effect-authoring, effect-best-practices, improve-codebase-architecture, parallel-research, quality-types, simplify, swarm-planner, tdd, turborepo]
• tdd_status: not_applicable
• tdd_target: Post-wave convergence validation only; each workspace slice owns its concrete public-root RED/GREEN.
• red_command: not_applicable
• expected_red_failure: not_applicable
• green_command: bun test ./scripts/effect-v4/domain-boundaries.contract.test.ts
• reason_not_testable: per-workspace concrete RED/GREEN owns TDD; this slice authors post-wave convergence validation
• red_evidence: Review-repair mutation sentinels produced the intended RED while all 5 original convergence tests remained green. The first exact command reported 5 failing sentinels: regex import scanning admitted three comment/string decoys; @/* resolved beneath the importer instead of the app source root; a nested generic shared directory escaped the exact-file list; comment/string runner decoys produced a false positive; and direct/aliased callback/exit runners produced a false negative. A runtime follow-up RED reported 2 failing sentinels while the prior 10 tests passed: namespace import from effect/ManagedRuntime missed MR.make(layer), and imported runners passed as callback values were ignored. The ownership follow-up RED reported 3 failing sentinels while the prior 12 tests passed: contract, scaffold, and database subdomains could each import their owning package/composition root through package or relative index spellings.
• green_evidence: The exact command passed 15 tests with 133 assertions: 10 mutation sentinels and 5 repository convergence tests. It proves parser-based import edges, canonical app/package/self-package resolution, recursive generic-root detection, comment/string-safe runner detection covering direct/aliased calls, callback/exit and *With variants, namespace-imported ManagedRuntime.make, and runner values/callbacks; owning composition-root rejection inside governed contract/scaffold/database subdomains without blocking outside consumers; all 13 public/composition roots; all 6 workspace focused contracts; every production import across app and shared-package consumers; canonical sibling direction; removed aliases; and every production source in the bounded T2 runtime scan.
• codebase_design_notes: This contract sits one semantic level above the workspace tests. Parsed import edges and canonical source identities keep public/private decisions independent of spelling, aliases, extensions, or index paths. Mutation sentinels protect the auditor itself. Domain policy remains in focused contracts, and the production runtime scan stays limited to T2-owned paths so planned T6/T7 legacy migration is not promoted into an accidental prerequisite.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T3: Preserve expected failures through typed domain and adapter channels

• depends_on: [T2-GATE]
• location: Five disjoint slices below plus scripts/effect-v4/typed-failures.contract.test.ts at convergence
• description: Run T3-CLI (apps-cli, apps/cli/src), T3-API (apps-api, apps/api/src), T3-AUTH (packages-auth, packages/auth/src), T3-CONTRACT (packages-contract, packages/contract/src), and T3-DB (packages-db, packages/db/src) as separate workers with exclusive scopes. Each defines only its domain-owned Schema.TaggedErrorClass families, normalizes expected adapter failures with operation context and diagnostic cause, and updates local callers to handle or propagate typed errors. After those slices are green, T3-CONTRACT-TEST creates or reconciles only scripts/effect-v4/typed-failures.contract.test.ts. Terminal/HTTP/UI translation remains at outer boundaries; no catch-all or cross-workspace error owner is introduced.
• validation: Every workspace slice passes its exact focused failure-path test, then T3-CONTRACT-TEST passes before the parent runs T3-GATE read-only across the typed-failure seams. Full workspace type/build validation remains with T5-CONTRACT and T6-T9 after later source layers are migrated.
• owner: five workspace implementation workers plus one root-contract-test implementation worker; parent convergence gate is strictly readonly
• status: Completed
• log: Five disjoint implementation workers completed the CLI, API, auth, contract, and database typed-failure seams. Each focused contract passed after its recorded RED, and structured review returned zero remaining findings. T3-CONTRACT-TEST then passed 8 repository tests with 168 assertions after review repairs. The readonly aggregate gate passed CLI 1, API 1, auth 4, contract 1, database 3, and repository 8 tests. Expected full-workspace migration failures remain owned by T5-T9 and were not promoted into this focused architecture gate.
• files edited/created: apps/cli/src/{core/{detect.ts,errors.ts},features/{index.ts,repository-analysis/{errors.ts,index.ts,port.ts},typed-failure-contract.test.ts},integrations/node-repository-scanner.ts,scaffold/run.ts}; apps/api/src/{features/{index.ts,report-submission/{adapter.ts,index.ts,port.ts},typed-failure-contract.test.ts},http-adapter-contract.test.ts,http-adapters.ts,index.ts,platform/report-submission.ts,reports.test.ts,reports.ts}; packages/auth/src/{features/operator-authentication/{action.ts,errors.ts,index.ts,port.ts},index.ts,integrations/{auth-persistence-operation.ts,better-auth-operation.ts,resend-verification-email-sender.ts},public-domain-root-contract.test.ts,typed-failure-contract.test.ts}; packages/contract/src/{backoffice.ts,baseline.ts,common.ts,reports.ts,telemetry.ts,typed-failure-contract.test.ts}; packages/db/src/{persistence/{failures.ts,index.ts},typed-failure-contract.test.ts}; scripts/effect-v4/typed-failures.contract.test.ts; apps/wiki/content/docs/project/specs/cli/IP-320-domain-first-effect-v4-architecture/{PLAN.md,IMPLEMENTATION-NOTES.md,PHASE-HANDOFF.md}
• backlog_item_id: IP-334
• backlog_item_url: https://linear.app/devpunks/issue/IP-334/preserve-every-expected-failure-as-typed-product-information
• 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: not_applicable
• tdd_target: T3 family aggregation; T3 workspace slices own concrete typed-failure RED/GREEN evidence.
• red_command: not_applicable
• expected_red_failure: not_applicable
• green_command: bun run --cwd apps/cli test -- src/features/typed-failure-contract.test.ts && bun run --cwd apps/api test -- src/features/typed-failure-contract.test.ts && bun run --cwd packages/auth test -- src/typed-failure-contract.test.ts && bun run --cwd packages/contract test -- src/typed-failure-contract.test.ts && bun run --cwd packages/db test -- src/typed-failure-contract.test.ts && bun test ./scripts/effect-v4/typed-failures.contract.test.ts
• reason_not_testable: Per-workspace concrete RED/GREEN owns TDD; T3-CONTRACT-TEST and T3-GATE are post-wave convergence validation.
• red_evidence:
• green_evidence: The exact aggregate command passed: CLI 1 test, API 1 test, auth 4 tests, contract 1 test, database 3 tests, and the repository contract's 8 tests with 168 assertions. Each slice also passed its owned adjacent regressions and finished with zero structured-review findings.
• codebase_design_notes: Error schemas are part of each public feature interface. Adapters translate unstable external diagnostics to stable domain meaning; outer transports translate domain meaning to protocol or presentation. Expected errors remain typed until that boundary.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T3 slice-level TDD contracts

Each row is a separate completed task with tdd_status: required and the exact RED/GREEN command from the atomic-slice table. T3-CONTRACT-TEST and T3-GATE remain validation-only with tdd_status: not_applicable.

Per-slice files edited/created:

• T3-CLI: apps/cli/src/core/{detect.ts,errors.ts}; apps/cli/src/features/{index.ts,typed-failure-contract.test.ts}; apps/cli/src/features/repository-analysis/{errors.ts,index.ts,port.ts}; apps/cli/src/integrations/node-repository-scanner.ts; apps/cli/src/scaffold/run.ts.
• T3-API: apps/api/src/features/index.ts; apps/api/src/features/report-submission/{adapter.ts,index.ts,port.ts}; apps/api/src/features/typed-failure-contract.test.ts; apps/api/src/{http-adapter-contract.test.ts,http-adapters.ts,index.ts,reports.test.ts,reports.ts}; apps/api/src/platform/report-submission.ts.
• T3-AUTH: packages/auth/src/features/operator-authentication/{action.ts,errors.ts,index.ts,port.ts}; packages/auth/src/index.ts; packages/auth/src/integrations/{auth-persistence-operation.ts,better-auth-operation.ts,resend-verification-email-sender.ts}; packages/auth/src/{public-domain-root-contract.test.ts,typed-failure-contract.test.ts}.
• T3-CONTRACT: packages/contract/src/{backoffice.ts,baseline.ts,common.ts,reports.ts,telemetry.ts,typed-failure-contract.test.ts}.
• T3-DB: packages/db/src/persistence/{failures.ts,index.ts}; packages/db/src/typed-failure-contract.test.ts.

T3-CONTRACT-TEST execution evidence

• depends_on: [T3-CLI, T3-API, T3-AUTH, T3-CONTRACT, T3-DB]
• location: scripts/effect-v4/typed-failures.contract.test.ts
• owner: root-contract-test
• status: Completed
• log: Added the post-wave repository contract only after all five workspace slices were green. Review repairs hardened source classification and failure-owner assertions without changing production code.
• files edited/created: scripts/effect-v4/typed-failures.contract.test.ts
• tdd_status: not_applicable
• red_command: not_applicable
• expected_red_failure: not_applicable
• green_command: bun test ./scripts/effect-v4/typed-failures.contract.test.ts
• reason_not_testable: Per-workspace concrete RED/GREEN owns TDD; this slice authors post-wave convergence validation.
• red_evidence:
• green_evidence: Final review state passed 8 tests with 168 assertions. The earlier 155-assertion run preceded the final review repairs and is superseded by this result.
• codebase_design_notes: The repository contract validates ownership and translation direction across public typed-failure seams; it does not define a shared error owner or modify production behavior.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T4: Provide focused validated configuration from application roots

• depends_on: [T3-GATE]
• location: Six disjoint slices below plus scripts/effect-v4/config-boundaries.contract.test.ts at convergence
• description: Run T4-ENV first (packages-env, reusable decoding/schema/provider primitives only). After it is green, T4-CLI, T4-API, T4-BACKOFFICE, T4-AUTH, and T4-DB fan out as exclusive-scope consumer tasks using that primitive surface. After every consumer is green, T4-CONTRACT-TEST creates or reconciles only scripts/effect-v4/config-boundaries.contract.test.ts. Ambient reads stay at approved roots, startup failures stay typed and secret-redacted, and contract/scaffold remain configuration-free.
• validation: Each workspace slice proves valid/missing/invalid/injected cases with its exact focused test. T4-CONTRACT-TEST then passes before the parent runs T4-GATE read-only to reject ambient reads outside exact roots and dependencies from contract/scaffold. Full surface type/build validation remains with T5-CONTRACT and T6-T9.
• owner: six workspace implementation workers plus one root-contract-test implementation worker; parent convergence gate is strictly readonly
• status: Completed
• log: 2026-07-19 T4 established injected provider/decoder primitives, moved configuration ownership to application roots, preserved typed secret-redacted failures, and made auth/database lifecycles explicit. Accepted review findings repaired root-only configuration ownership, command-environment narrowing and clipboard controls, PostgreSQL URL validation, typed auth-failure preservation, database cleanup, and SIGTERM disposal with preserved termination. The aggregate, frozen install, diff/deletion audits, final spec review, and final standards review are green. IP-335 implementation evidence is complete; T5-CONTRACT is next.
• files edited/created: packages/env/src/{config.ts,public-env-contract.test.ts}; apps/cli/src/runtime/{config.ts,config-contract.test.ts} and migrated CLI consumers; apps/api/src/runtime/{config.ts,auth-lifecycle.ts}, focused API contracts, and API composition/store injection; apps/backoffice/src/lib/{config.ts,config.test.ts}, apps/backoffice/src/modules/{auth,runtime}/**, and the auth route; packages/auth/src/{config.ts,config-contract.test.ts,index.ts,index.test.ts}; packages/db/src/{config-contract.test.ts,index.ts,persistence/index.ts,runtime/**}; participating manifests; bun.lock; scripts/effect-v4/config-boundaries.contract.test.ts; routed implementation evidence and root references.
• backlog_item_id: IP-335
• backlog_item_url: https://linear.app/devpunks/issue/IP-335/provide-focused-validated-configuration-from-application-roots
• relation_mode: native
• assigned_skills: [agent-browser, async-react-patterns, autoreview, backend-domain-structure, backend-recoverable-actions, 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, logging-best-practices, next-best-practices, next-cache-components, parallel-research, quality-types, react-doctor, simplify, swarm-planner, tdd, turborepo, vercel-composition-patterns, vercel-react-best-practices]
• tdd_status: not_applicable
• tdd_target: T4 family aggregation; T4 workspace slices own concrete focused-configuration RED/GREEN evidence.
• red_command: not_applicable
• expected_red_failure: not_applicable
• green_command: bun run --cwd packages/env test -- src/public-env-contract.test.ts && bun run --cwd apps/cli test -- src/runtime/config-contract.test.ts && bun run --cwd apps/api test -- src/runtime/config-contract.test.ts && bun run --cwd apps/backoffice test -- src/lib/config.test.ts && bun run --cwd packages/auth test -- src/config-contract.test.ts && bun run --cwd packages/db test -- src/config-contract.test.ts && bun test ./scripts/effect-v4/config-boundaries.contract.test.ts
• reason_not_testable: Per-workspace concrete RED/GREEN owns TDD; T4-CONTRACT-TEST and T4-GATE are post-wave convergence validation.
• red_evidence: Workspace contracts failed before their owned provider/configuration seams existed. Review REDs caught non-root reads, an over-broad child-process environment, implicit clipboard behavior, non-PostgreSQL URLs, flattened auth failures, incomplete database cleanup, and SIGTERM cleanup without preserved termination.
• green_evidence: Final T4 proof passed ENV 8 tests; CLI focused/adjacent 40; API focused 12; backoffice 8; auth 5; database 4; and repository 9 tests with 30 expectations. bun install --frozen-lockfile, git diff --check, and the tracked-deletion audit were clean. Final independent spec review returned PASS and final standards review returned PASS.
• codebase_design_notes: packages/env is a reusable decoder/provider primitive, not a global config object. Focused services form small per-domain interfaces; roots compose them, and tests replace only the provider or parsed service.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T4 slice-level TDD contracts

Each workspace slice completed its required focused RED/GREEN contract. T4-CONTRACT-TEST and T4-GATE remained validation-only with tdd_status: not_applicable.

T5: Isolate protocol areas from consumer runtime

• depends_on: [T4-GATE]
• location: packages/contract/package.json; packages/contract/src/{common,baseline,telemetry,reports,backoffice}.ts; packages/contract/src/{api.ts,client.ts,errors.ts,index.ts,schemas.ts}; packages/contract/src/public-protocol-contract.test.ts; apps/cli/src/control-plane/client.ts; apps/api/src/index.ts; apps/backoffice/src/lib/api.ts; corresponding consumer tests
• description: Execute four atomic slices: T5-CONTRACT (packages-contract) first creates narrow protocol-only areas; then T5-CLI (apps-cli), T5-API (apps-api), and T5-BACKOFFICE (apps-backoffice) separately move Fetch/auth/retry/handler/session behavior into their exclusive consumer scopes. No worker edits another workspace or adds compatibility re-exports.
• validation: T5-CONTRACT passes its full package test suite and typecheck in isolation. The three consumer slices then pass their exact focused ownership tests before T5-GATE proves OpenAPI equivalence, narrow imports, and no contract runtime. Full CLI, API, and backoffice surface gates belong to T6, T7, and T8 respectively.
• owner: packages-contract, then parallel apps-cli, apps-api, and apps-backoffice workers; parent convergence gate
• status: Completed
• log: T5-CONTRACT removed the shared concrete client/runtime, preserved public-protocol-contract.openapi.json unchanged, and recorded the complete old-v3 semantic snapshot. The three app consumers then took ownership of request execution in disjoint scopes. Independent review passed all four slices, and T5-GATE passed. Full app migrations remain assigned to T6-T8; IP-336 remains In Progress until its later T8/closeout scope completes.
• files edited/created: f57b1efb changed bun.lock, packages/contract/package.json, and the contract protocol sources/tests/fixture recorded in IMPLEMENTATION-NOTES.md; a14bea27 changed the CLI control-plane consumers/tests, API protocol adapters/consumers/tests, and backoffice API consumers/tests recorded there.
• backlog_item_id: IP-336
• backlog_item_url: https://linear.app/devpunks/issue/IP-336/isolate-shared-protocol-areas-from-consumer-runtime
• relation_mode: native
• assigned_skills: [agent-browser, async-react-patterns, autoreview, backend-domain-structure, backend-recoverable-actions, 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, logging-best-practices, next-best-practices, next-cache-components, parallel-research, quality-types, react-doctor, simplify, swarm-planner, tdd, turborepo, vercel-composition-patterns, vercel-react-best-practices]
• tdd_status: required
• tdd_target: A consumer can import every protocol domain from the shared root or obtain a concrete Fetch runtime from packages/contract.
• red_command: bun run --cwd packages/contract test -- src/public-protocol-contract.test.ts
• expected_red_failure: Current root exports and client.ts expose broad protocol/runtime behavior and consumers depend on it.
• green_command: bun run --cwd packages/contract test && bun run --cwd packages/contract check-types && bun run --cwd apps/cli test -- src/control-plane/client.test.ts && bun run --cwd apps/api test -- src/http-adapter-contract.test.ts && bun run --cwd apps/backoffice test -- src/lib/api.test.ts
• reason_not_testable:
• red_evidence: The focused contract proved the broad package root and concrete client.ts runtime were still public and consumer-owned request seams were absent.
• green_evidence: Contract passed 22/22 tests plus typecheck, retained public-protocol-contract.openapi.json unchanged, and matched the complete old-v3 semantic snapshot. CLI passed 2/2 focused tests, API passed 3/3 focused tests plus 8/8 mapped protocol cases, and backoffice passed its 52/52 suite plus typecheck. The aggregate gate passed contract 22, CLI 2, API 3, and backoffice 8 focused tests. Remaining CLI, API/auth/database, backoffice/scaffold, and database-backed build failures are owned by T6-T8.
• codebase_design_notes: Each protocol submodule is a deep cross-process seam. Request execution is a consumer adapter. The common module admits a primitive only when at least two protocol areas genuinely share it.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T5 consumer-slice TDD overrides

The T5 family RED/GREEN fields above apply to T5-CONTRACT. Each consumer row is a separate completed task, uses its exact command from the atomic-slice table, has tdd_status: required, recorded evidence below, and an empty reason_not_testable.

T6: Complete the CLI domain, integration, and single-runtime migration

• depends_on: [T5-GATE]
• location: apps/cli/src/{features,integrations,platform,cli,baseline,context,control-plane,core,github,runtime,scaffold,telemetry,update}; apps/cli/src/index.ts; apps/cli/package.json; apps/cli/src/**/*.test.ts
• description: Move remaining CLI workflows and policy into feature actions, reusable mechanics into feature services, and filesystem/process/network/GitHub/Skills/control-plane work into integrations. Make commands parse inputs, call one application operation, and render/translate only at the CLI boundary. Compose production Layers and run Effect once in index.ts; prohibit commands and domains from constructing runtimes or choosing real implementations. Delete replaced generic buckets and aliases rather than retaining dual paths. Preserve packaged command, JSON, managed-asset, context, scaffold, update, operator, telemetry, and report behavior according to IP-319 classifications.
• owner: one apps-cli worker; exclusive apps/cli write scope
• validation: CLI unit/contract tests, typecheck, packaged build, public-output contract, context semantic fixture, managed-byte fixtures, and adapter contracts pass with no v3 imports or compatibility paths. Cross-repository domain-boundary validation belongs only to T6-8-GATE.
• status: Completed
• log: The CLI migrated the remaining command workflows into feature actions, integrations, platform capabilities, and presenters while keeping one entrypoint-owned runtime. Review removed the command-feature dependency inversion and retained every classified public seam.
• files edited/created:
• backlog_item_id: IP-332
• backlog_item_url: https://linear.app/devpunks/issue/IP-332/compose-domain-behavior-through-deliberate-public-boundaries
• 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: One representative command still creates production runtime/integration behavior or changes a classified public JSON, context, or managed-output result during migration.
• red_command: bun run --cwd apps/cli test -- src/cli/public-output-contract.test.ts src/context/public-context-contract.test.ts
• expected_red_failure: The v4 public operation seam is absent or a representative command/output contract diverges while old runtime ownership remains.
• green_command: bun run --cwd apps/cli test && bun run --cwd apps/cli check-types && bun run --cwd apps/cli build
• reason_not_testable:
• red_evidence: The focused command-boundary contract initially found commands coupled to concrete implementations and legacy generic core ownership.
• green_evidence: The full CLI gate passed 258/258 tests, check-types, and a packaged build of 461 modules. Public-output and context fixtures retained their accepted bytes/semantics, declared protocol errors remain typed through the generated baseline and telemetry endpoints, report/pack/tool failures remain typed, and one repository-check capability port owns that integration. Production source contains no Effect v3 import or compatibility path.
• codebase_design_notes: CLI feature operations are presentation-neutral public seams. The entrypoint owns Layer composition and execution; commands are transport/presentation adapters; filesystem, process, GitHub, Skills, and control-plane implementations remain replaceable integrations.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T7: Complete API, auth, and database domain composition

• depends_on: [T5-GATE]
• location: apps/api/src/{features,integrations,platform}; apps/api/src/{backoffice-access.ts,backoffice.ts,baseline-registry.ts,http-adapters.ts,index.ts,memory-state.ts,reports.ts,telemetry.ts}; packages/auth/src; packages/db/src; corresponding tests and package manifests
• description: Execute three exclusive-scope workers serially because their real package graph is DB -> auth -> API. T7-DB completes the database package first; T7-AUTH then consumes the completed database surface; T7-API finally consumes both completed package surfaces and finishes actions/integrations/transport/root composition. Each worker reconciles call sites only inside its workspace before its GREEN command. The parent performs no convergence patch.
• validation: T7-DB passes its full package gate, then T7-AUTH passes its full package gate, then T7-API passes tests/typecheck/build. T6-8-GATE owns cross-repository public API, transport-free, ambient-config, typed-failure, and runtime-placement convergence.
• owner: apps-api, packages-auth, and packages-db workers; parent convergence gate
• status: Completed
• log: The serial T7-DB -> T7-AUTH -> T7-API chain completed package-owned Layers, injected focused configuration, typed persistence/auth/transport failures, API-owned handler composition, and deterministic disposal. Review restored the immutable auth harness by moving v4-only proof into package testing support.
• files edited/created:
• backlog_item_id: IP-332
• backlog_item_url: https://linear.app/devpunks/issue/IP-332/compose-domain-behavior-through-deliberate-public-boundaries
• 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: A representative API operation still reads environment or chooses a GitHub/database/auth implementation inside feature policy, or transport owns a product decision.
• red_command: bun run --cwd apps/api test -- src/http-adapter-contract.test.ts src/public-api-contract.test.ts
• expected_red_failure: The v4 feature/adapter/config seams are absent or current transport/feature coupling violates the domain contract.
• green_command: bun run --cwd packages/db test && bun run --cwd packages/db check-types && bun run --cwd packages/auth test && bun run --cwd packages/auth check-types && bun run --cwd apps/api test && bun run --cwd apps/api check-types && bun run --cwd apps/api build
• reason_not_testable:
• red_evidence: Composition contracts exposed v3 service/schema APIs, ambient production selection, raw adapter failures, and incomplete root-owned lifecycle composition across the serial package graph.
• green_evidence: Database passed 15 tests plus typecheck and removed the merged dual-pool DatabaseLive; auth passed 22 tests plus typecheck; API passed 82/82 tests, typecheck, build, and the runtime-product validator. A real built start handles SIGINT and SIGTERM with exactly-once disposal, importing the built entrypoint installs zero listeners, and the dead StoreLive adapters and their callers are removed. TypeScript results match the live parent baseline where inherited diagnostics exist, while every T7-owned changed surface compiles.
• codebase_design_notes: API actions own policy and return typed results; repositories and integrations own mechanics; Effect HTTP transport maps only at the boundary. Auth and db expose coherent package-domain interfaces and production Layers without importing application internals.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T7 auth/database slice TDD overrides

The T7 family TDD fields above apply to T7-API. Each row below is a separate completed task, uses its exact command from the atomic-slice table, has tdd_status: required, recorded RED/GREEN evidence, and an empty reason_not_testable.

T8: Complete backoffice consumer runtime and config-free scaffold migration

• depends_on: [T5-GATE]
• location: apps/backoffice/src/lib/{api.ts,authz.ts,actions.ts,config.ts}; apps/backoffice/src/app; apps/backoffice/src/features; corresponding tests; apps/backoffice/package.json; packages/scaffold/src/{index.ts,index.test.ts,public-scaffold-contract.test.ts}; packages/scaffold/package.json
• description: Execute T8-BACKOFFICE (apps-backoffice) and T8-SCAFFOLD (packages-scaffold) as separate workers with exclusive scopes. Backoffice owns request/auth/session/retry/config translation without visual redesign; scaffold migrates schemas only and remains behavior-free. Required browser execution is deferred to T10.
• validation: Backoffice unit/type/build and scaffold test/typecheck checks pass. T6-8-GATE proves narrow protocol imports and config-free scaffold; T10 alone proves browser runtime behavior.
• owner: apps-backoffice and packages-scaffold workers; parent convergence gate
• status: Completed
• log: Backoffice owns request/session/config translation through its local feature boundary and no longer exposes the stale shell pass-through alias. Scaffold is split into deliberate baseline and catalog roots, remains configuration-free, and preserves byte-locked schema behavior.
• files edited/created:
• backlog_item_id: IP-336
• backlog_item_url: https://linear.app/devpunks/issue/IP-336/isolate-shared-protocol-areas-from-consumer-runtime
• 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 relies on a shared concrete request Layer or scaffold accepts runtime/configuration ownership after the v4 migration.
• red_command: bun run --cwd apps/backoffice test -- src/lib/api.test.ts src/lib/actions.test.ts && bun run --cwd packages/scaffold test
• expected_red_failure: Consumer-owned request/config seams or v4 scaffold schema compatibility are absent, or current shared-client ownership violates the contract.
• green_command: bun run --cwd apps/backoffice test && bun run --cwd apps/backoffice check-types && bun run --cwd apps/backoffice build && bun run --cwd packages/scaffold test && bun run --cwd packages/scaffold check-types
• reason_not_testable:
• red_evidence: The backoffice contract found the stale shared-request/pass-through boundary, while scaffold still exposed a broad compatibility root instead of the two intended schema domains.
• green_evidence: Backoffice passed 53 tests, typecheck, build, and 8 browser contract cases. Scaffold passed 10 tests plus typecheck; exact managed/public scaffold bytes remained unchanged.
• codebase_design_notes: Backoffice request execution is an app-owned adapter behind its local API seam. Shared scaffold remains a deep schema model only; explicit inputs replace ambient configuration.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T6-8-GATE: Prove completed surfaces converge before closeout-test authorship

• depends_on: [T6-CLI, T7-API, T8-BACKOFFICE, T8-SCAFFOLD]
• location: Read-only validation of scripts/effect-v4/{dependency-manifest,domain-boundaries,typed-failures,config-boundaries}.contract.test.ts and the completed T6-T8 worktrees; no owned write paths
• description: After every T6, T7, and T8 specialist slice passes its full owning-surface gate, the parent reruns the four existing repository architecture contracts together. This gate does not patch production or tests. Findings route back to the exact T6-T8 owner before T9-CLOSEOUT-TEST may start.
• validation: The exact aggregate command passes without modifying the worktree and records the four contract files, exit status, and assertion output in green_evidence.
• owner: parent, strictly readonly
• status: Completed
• log: The parent reran the four dependency/domain/error/config contracts only after every T6-T8 owning surface was green; no convergence patch was required.
• files edited/created:
• backlog_item_id: IP-320
• backlog_item_url: https://linear.app/devpunks/issue/IP-320/operate-through-one-domain-first-effect-v4-architecture
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, effect-authoring, effect-best-practices, improve-codebase-architecture, parallel-research, quality-types, simplify, tdd, turborepo]
• tdd_status: not_applicable
• tdd_target: Read-only convergence of the already-authored dependency, domain, typed-failure, and configuration contracts after full surface completion.
• red_command: not_applicable
• expected_red_failure: not_applicable
• green_command: bun test ./scripts/effect-v4/dependency-manifest.contract.test.ts ./scripts/effect-v4/domain-boundaries.contract.test.ts ./scripts/effect-v4/typed-failures.contract.test.ts ./scripts/effect-v4/config-boundaries.contract.test.ts
• reason_not_testable: Validation-only convergence; T1-T8 implementation slices own behavioral RED/GREEN.
• red_evidence:
• green_evidence: The four-contract aggregate passed. After closeout-test authorship and final fixes, the final five-contract aggregate passed 55/55 tests and 622 assertions.
• codebase_design_notes: The gate verifies cross-surface dependency direction without becoming an integration writer or a second architecture owner.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T9-CLOSEOUT-TEST: Author the final static migration contract

• depends_on: [T6-8-GATE]
• location: scripts/effect-v4/migration-closeout.test.ts only
• description: A root-contract-test implementation worker authors or reconciles only the final static migration closeout contract after completed surfaces pass T6-8-GATE. It checks zero-v3 production state, no shims/dual paths/generic buckets/broad protocol runtime, and byte-locked IP-319 fixture retention. It does not edit production code or existing contract tests.
• validation: The exact closeout-test command passes before the readonly T9 repository-wide aggregate starts.
• owner: root-contract-test implementation worker
• status: Completed
• log: The closeout contract was added after surface convergence and tightened during review to scan production test files semantically, exclude support-only fixtures, and reject runtime construction, generic buckets, broad protocol runtime, and compatibility aliases without identifier-only false positives.
• files edited/created:
• backlog_item_id: IP-320
• backlog_item_url: https://linear.app/devpunks/issue/IP-320/operate-through-one-domain-first-effect-v4-architecture
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, effect-authoring, effect-best-practices, improve-codebase-architecture, parallel-research, quality-types, simplify, swarm-planner, tdd, turborepo]
• tdd_status: not_applicable
• tdd_target: Post-wave closeout validation over completed production sources and retained immutable fixtures.
• red_command: not_applicable
• expected_red_failure: not_applicable
• green_command: bun test ./scripts/effect-v4/migration-closeout.test.ts
• reason_not_testable: This slice authors post-wave validation; behavior-changing slices own concrete RED/GREEN.
• red_evidence:
• green_evidence: The focused closeout suite passed 13 tests and 53 assertions. The final five-contract aggregate passed 55/55 tests and 622 assertions.
• codebase_design_notes: The closeout contract audits the architecture one semantic level above package tests and owns no production behavior.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T9: Prove static repository-wide production-source closure

• depends_on: [T9-CLOSEOUT-TEST]
• location: Read-only validation of scripts/effect-v4/dependency-manifest.contract.test.ts; scripts/effect-v4/domain-boundaries.contract.test.ts; scripts/effect-v4/typed-failures.contract.test.ts; scripts/effect-v4/config-boundaries.contract.test.ts; scripts/effect-v4/migration-closeout.test.ts; package.json; bun.lock; turbo.json; participating manifests and production roots under apps/api, apps/backoffice, apps/cli, packages/auth, packages/contract, packages/db, packages/env, and packages/scaffold; no owned write paths
• description: T6-8-GATE first proves the completed surfaces converge, then T9-CLOSEOUT-TEST authors and passes only scripts/effect-v4/migration-closeout.test.ts. The parent then runs a strictly read-only non-runtime static/workspace/build audit over the exact participating manifests and production-source roots in location. Reject any Effect v3 dependency/import, v3 shim, dual path, generic bucket, broad protocol root, runtime below application roots, ambient feature configuration, or compatibility alias. Exclude immutable IP-319 characterization fixtures from source scanning—apps/cli/test-fixtures/public-output/**, apps/api/test-fixtures/runtime-product/expected.json, apps/backoffice/test-fixtures/browser/expected.json, packages/{auth,db,env,scaffold}/test-fixtures/**, and packages/contract/src/public-protocol-contract.openapi.json—and assert those files remain present and byte-identical. Do not edit tests or production files, and do not start servers, browsers, databases, providers, packaged executables, or operator flows; findings route to T1-T8 or T9-CLOSEOUT-TEST, and T10 is the sole runtime gate.
• validation: Static contracts, all eight workspace tests/typechecks, the three app builds, root lint/check/build, frozen lock audit, and byte-locked fixture-retention assertions pass. This convergence closes IP-333 only when production sources resolve beta.98 with zero v3 state.
• owner: T9-CLOSEOUT-TEST implementation worker owns the closeout test file; parent owns only the strictly read-only static convergence/audit
• status: Completed
• log: Static production-source convergence, immutable IP-319 fixture retention, all participating workspace gates, root typecheck, and root build were audited. The root build required NEXT_PUBLIC_SERVER_URL=https://api.harness.localhost; wiki validation used the direct safe route because the wrapper runs destructive content sync.
• files edited/created:
• backlog_item_id: IP-320
• backlog_item_url: https://linear.app/devpunks/issue/IP-320/operate-through-one-domain-first-effect-v4-architecture
• relation_mode: native
• assigned_skills: [agent-browser, async-react-patterns, autoreview, backend-domain-structure, backend-recoverable-actions, 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, logging-best-practices, next-best-practices, next-cache-components, parallel-research, quality-types, react-doctor, simplify, swarm-planner, tdd, turborepo, vercel-composition-patterns, vercel-react-best-practices]
• tdd_status: not_applicable
• tdd_target: Read-only aggregate validation; T9-CLOSEOUT-TEST owns only the post-wave closeout GREEN validation.
• red_command: not_applicable
• expected_red_failure: not_applicable
• green_command: bun test ./scripts/effect-v4/dependency-manifest.contract.test.ts ./scripts/effect-v4/domain-boundaries.contract.test.ts ./scripts/effect-v4/typed-failures.contract.test.ts ./scripts/effect-v4/config-boundaries.contract.test.ts ./scripts/effect-v4/migration-closeout.test.ts && 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 --cwd apps/api build && bun run --cwd apps/backoffice build && git diff --check
• reason_not_testable: Validation-only convergence; all authored behavior/static tests belong to explicit implementation slices.
• red_evidence:
• green_evidence: The final five-contract gate passed 55/55 tests and 622 assertions; migration closeout passed 13/13 and 53 assertions; forced root behavior tests passed 15/15 tasks. Root check-types passed. Root build passed with NEXT_PUBLIC_SERVER_URL=https://api.harness.localhost and direct wiki generation/type/build validation. All 13 immutable fixtures remained byte-identical to parent, the exact beta.98 manifest/lock state contains no v3 dependency/import/shim, and TypeScript results have parent parity.
• codebase_design_notes: The closeout is an architecture and public-seam validator, not a second implementation layer. Workspace-owned tests remain local; the root audit proves composition and forbidden-state absence.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T10: Validate supported runtime-product boundaries with cleanup

• depends_on: [T9]
• location: apps/api/src/runtime-product-contract.test.ts; apps/api/scripts/validate-runtime-product.mjs; apps/backoffice/test-fixtures/browser/run.ts; apps/cli/src/cli/package-metadata.test.ts; scripts/behavior-contract/{repeat.mjs,cleanup.mjs}; .reports/behavior-contract
• description: Exercise the supported API with real Postgres and Better Auth boundaries, the backoffice authenticated request flow, and the packaged CLI against consumer-owned protocol/runtime configuration. Prove typed startup and adapter failures without leaking secrets. Use unique run identifiers for database rows, temporary roots, processes, ports, browser state, and reports; validate cleanup and leave no owned resource behind. Repeat the comprehensive gate twice to detect generation/config/runtime nondeterminism.
• validation: Runtime-product validator, browser flow, packaged CLI proof, two identical comprehensive runs, and standalone cleanup all pass with durable run-id evidence and no remaining owned resources.
• status: Completed
• log: Supported API, authenticated browser, packaged CLI, repeat, and cleanup boundaries passed. One pre-debug repeat failed because the run started before the clean-checkpoint concurrency gate; instrumented rerun evidence identified that orchestration race, and the final implementation retains no debug instrumentation.
• files edited/created:
• backlog_item_id: IP-320
• backlog_item_url: https://linear.app/devpunks/issue/IP-320/operate-through-one-domain-first-effect-v4-architecture
• relation_mode: native
• assigned_skills: [agent-browser, async-react-patterns, autoreview, backend-domain-structure, backend-recoverable-actions, 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, logging-best-practices, next-best-practices, next-cache-components, parallel-research, quality-types, react-doctor, simplify, swarm-planner, tdd, turborepo, vercel-composition-patterns, vercel-react-best-practices]
• tdd_status: required
• tdd_target: A supported runtime-product path fails under v4 composition, leaks an untyped/redacted config error, or leaves run-owned state after cleanup.
• red_command: bun run --cwd apps/api validate:runtime-product
• expected_red_failure: The migrated runtime composition, consumer-owned client, or focused production configuration is incomplete, or cleanup detects owned resources.
• green_command: bun run --cwd apps/api validate:runtime-product && bun run --cwd apps/backoffice test:browser && bun run --cwd apps/cli build && bun run behavior:repeat -- --runs=2 && bun run behavior:cleanup
• reason_not_testable:
• red_evidence: Pre-debug report repeat-session-a3611091-42af-4b30-a147-9b403fc47f57 was unsuccessful/non-identical when its first run overlapped active clean-checkpoint work. Cleanup remained valid, so the failure was classified as orchestration concurrency rather than product nondeterminism.
• green_evidence: API runtime-product validation passed; backoffice passed 8 browser cases; the CLI package built 461 modules into a 2.16 MB artifact. Instrumented report repeat-session-84db6230-2f47-4e72-a3bf-56c9c473c8e6 passed two identical 15/15 runs and left no debug code. Final report repeat-session-057e8ae7-6030-4b9c-af16-6b6183fc4012 is successful:true and identical:true, with two 15/15 runs and valid cleanup; standalone cleanup found no owned resources.
• codebase_design_notes: Runtime proof crosses only supported public product boundaries. Deterministic Layers cover ordinary tests; this task proves real composition, provider wiring, and lifecycle cleanup without adding test-only product APIs.
• review_mode: mixed
• runtime_validation: required
• runtime_target: Packaged hi CLI, local Effect API with Postgres/Better Auth, and authenticated backoffice flow.
• runtime_evidence: Correlated run-id evidence must show successful public results, expected typed startup/adapter failures, persisted state where applicable, exact Effect generation, and clean handler/database/auth/process teardown.
• runtime_cleanup: Tag every row, temp root, process group, port, browser artifact, and report with one run id; remove only matching resources; require cleanup reports with empty remaining and unknown sets.

T11: Review, document, and hand off the coordinated epic

• depends_on: [T10]
• location: apps/wiki/content/docs/project/specs/cli/IP-320-domain-first-effect-v4-architecture/{PLAN.md,IMPLEMENTATION-NOTES.md,PHASE-HANDOFF.md}; docs/{README.md,reference/harness-intelligence.md,runbooks/hi-cli-scaffolding.md}; apps/wiki/content/docs/cli/control-plane/effect-api-contract-boundary.mdx; apps/wiki/content/docs/cli/validation/behavior-contract-validation.mdx; apps/wiki/content/docs/project/decisions/cli-local-work-control-plane-contract.mdx; apps/wiki/content/docs/project/runbooks/{index.mdx,harness-trust-gate.md,hi-cli-scaffolding.md,meta.json}; apps/wiki/content/docs/{cli,project}/meta.json; apps/wiki/{index.md,log.md}; Linear IP-320 and IP-332 through IP-336
• description: Fill every task's RED/GREEN/runtime evidence and exact files, run findings-first implementation review, simplify only migration-owned complexity, route private docs ingest for the domain/runtime/config/error/protocol architecture, update root documentation and relevant runbooks, and sync durable plan/spec/PR links plus story completion to Linear. Keep the epic branch unmerged and target only the coordinated architecture branch.
• validation: No blocking review finding remains; task evidence is complete; docs flow/concept/bookkeeping surfaces agree with implemented reality; Linear hierarchy and links remain native; targeted format and diff checks pass; handoff names remaining coordinated-branch gates without claiming merge or deployment.
• status: In Progress
• log: Independent final rereviews passed, findings-first review corrections plus private/internal docs ingest are complete, and Linear IP-320/IP-332-IP-336 are Done. The final clean checkpoint preserved the exact #76 parent/#77-#83 sibling fan-out with every PR open, draft, and unmerged. Parent closeout owns the final docs commit/push and one post-doc stack gate.
• files edited/created:
• backlog_item_id: IP-320
• backlog_item_url: https://linear.app/devpunks/issue/IP-320/operate-through-one-domain-first-effect-v4-architecture
• relation_mode: native
• assigned_skills: [agent-browser, async-react-patterns, autoreview, codebase-design, design-taste-frontend, docs-ingest-phase, docs-onboarding, frontend-domain-structure, improve-codebase-architecture, next-best-practices, next-cache-components, parallel-research, quality-types, react-doctor, review-phase, simplify, tdd, vercel-composition-patterns, vercel-react-best-practices, writing-beats, writing-fragments, writing-great-skills, writing-shape]
• tdd_status: not_applicable
• tdd_target: Durable implementation, review, runtime, documentation, PR-base, and tracker evidence is complete and internally consistent.
• red_command: not_applicable
• expected_red_failure: not_applicable
• green_command: bunx oxfmt --check apps/wiki/content/docs/project/specs/cli/IP-320-domain-first-effect-v4-architecture docs/README.md docs/reference/harness-intelligence.md docs/runbooks/hi-cli-scaffolding.md apps/wiki/content/docs/cli/control-plane/effect-api-contract-boundary.mdx apps/wiki/content/docs/cli/validation/behavior-contract-validation.mdx apps/wiki/content/docs/project/decisions/cli-local-work-control-plane-contract.mdx apps/wiki/content/docs/project/runbooks apps/wiki/index.md apps/wiki/log.md && bun run --cwd apps/wiki check-types && bun run --cwd apps/wiki build && git diff --check
• reason_not_testable: Evidence, review, docs ingest, tracker sync, and handoff do not introduce runtime behavior.
• red_evidence:
• green_evidence: Independent final API/database and CLI rereviews returned PASS. Focused docs formatting, JSON metadata parsing, and diff validation passed without running the mutating wiki wrappers. Linear IP-320/IP-332-IP-336 are Done. The final clean stack checkpoint recorded matching local/remote SHAs, exact inferred fan-out, safe failed sync restoration, unchanged children, and clean/open/draft/unmerged post-checks. Parent-owned final docs commit/push and one post-doc stack gate remain.
• codebase_design_notes: Documentation records the implemented public seams and dependency direction; it does not create a second architecture authority.
• review_mode: mixed
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

Testing Strategy

• Use vertical RED-to-GREEN tracer bullets inside every behavior-changing task. Do not author all architecture tests first and defer production migration to a later horizontal phase.
• Test through public feature roots, protocol submodules, application operations, command/API boundaries, and package exports. Static import/config/version contracts supplement public behavior tests; they do not replace them.
• Keep domain policy real. Substitute filesystem, process, HTTP, GitHub, Skills CLI, auth, database, clock, and configuration only at deliberate integration or provider seams.
• Preserve IP-319 classifications: exact bytes for managed assets and public JSON; semantic equality for context and other classified results; intentional changes only where already accepted.
• Run focused tests through T2-T4, the isolated full contract gate at T5, full owning-surface gates at T6-T8, then one forced repository gate and supported runtime-product proof.
• Record actual RED and GREEN output in this plan before marking any task complete.

Validation Gates

1. T1 proves the exact beta.98 manifest/lock/peer/source selection only; IP-333 remains open.
2. T2 proves deliberate public roots and dependency direction through focused contracts without requiring later same-epic source migration.
3. T3 proves expected failures remain typed and adapter-normalized through focused contracts.
4. T4 proves root-only environment/configuration ownership and secret-safe startup failures through focused contracts.
5. T5 fully validates the isolated contract package, then proves protocol-only shared packages and focused consumer-owned runtime seams.
6. T6-T8 complete and fully validate the CLI, API/auth/db, and backoffice/scaffold surfaces with no dual paths; browser/API/package execution remains deferred.
7. T9 statically proves exact participating-root zero-v3 closure, workspace tests/typechecks/builds, and retained byte-locked IP-319 fixtures; IP-333 may close here.
8. T10 is the sole required browser/API/packaged-product runtime gate and proves deterministic repetition plus run-owned cleanup.
9. T11 requires findings-first review, docs ingest, complete evidence, Linear sync, targeted formatting, and an unmerged handoff.

Skill Routing Notes

• create-plan composed grilling, source-backed parallel research, swarm graph shaping, TDD targets, and codebase-design seams in this artifact.
• The completed Q1-Q58 grill resolved all product and architecture decisions; no new user question was required.
• Local v3-era Effect guidance is subordinate to the approved spec and exact selected v4 source. Executors still apply the architecture, error, recovery, quality, and testing checklists from scoped skills.
• Tasks touching API/auth/db use backend-domain, recoverable-action, logging, Effect, quality, and TDD guidance.
• CLI tasks use scoped Effect, architecture, quality, TDD, and Turborepo guidance.
• Backoffice tasks use its Next/React/auth/browser composition guidance only where the request-runtime migration reaches those boundaries; no visual redesign is included.
• Final docs and implementation review are explicit T11 gates rather than incidental cleanup.

Backlog Sync

• IP-320 is the native epic and is In Progress.
• Repository delivery evidence on 2026-07-19 marks IP-335 complete. Live tracker reconciliation remains a later delivery action; IP-333 stays open until T9 proves production-source convergence, and IP-336 begins with T5-CONTRACT.
• Native blockers already express IP-333 blocking IP-332, IP-334, IP-335, and IP-336. No prose fallback or new task-owned backlog items are needed.
• IP-320 retains its native blockedBy: IP-330 history, while accepted branch evidence satisfies dependency readiness for this delivery phase.
• The IP-320 delivery-start comment already records branch team/stefan/ip-320-effect-v4-boundaries, base team/stefan/refactor-cli-architecture, and the required child order.
• This plan-only graph repair makes no Linear mutation; delivery status remains governed by live issue state and implementation evidence.

Risks and Mitigations

• Beta APIs can move: resolve npm metadata and explicit selected-beta source in T1; pin exact versions and do not upgrade again implicitly.
• Former packages may be consolidated: derive the package/export matrix from selected v4 source and peers; do not invent one-for-one version bumps.
• A package-first migration can create translation layers: keep T1 dependency-only, then execute the accepted breadth-first graph; remove dual paths in the same owning slice.
• Architecture roots can become shallow barrels: migrate real behavior with each public root and enforce the deletion test; forbid compatibility aliases.
• Typed-error work can become one catch-all: keep error meaning domain-owned and adapter normalization small; test caller handling and preserved causes.
• Config centralization can become a global object: keep packages/env primitive-only and application config local; static contract rejects shared runtime config leakage.
• Parallel app completion can overlap: T6 owns CLI only; T7 is split among API/auth/db specialists; T8 is split among backoffice/scaffold specialists. Root integration waits for every slice and convergence gate.
• Public behavior can drift during structural moves: retain IP-319 fixtures and classifications as the final authority; do not update fixtures merely to accept refactor output.
• Runtime validation can leak resources: use the existing behavior-contract run-id manifest and fail-closed cleanup rules.
• Local scoped guidance still says Effect v3: the approved spec explicitly supersedes v3 API spelling for this epic; selected v4 source controls APIs while scoped architectural constraints still apply.

Unresolved Questions

None. The approved spec, live Linear parent and all five children, completed Q1-Q58 grill, repository discovery, bounded source evidence, exact beta.98 selection, and child-to-parent branch intent resolve the planning inputs. T1 verifies and records the already-selected peer/source matrix without reopening version selection.

Planned Review and Docs Ingest

• Parent orchestration will run the required independent plan-reviewer against dependency ordering, unsafe overlap, exact paths, RED/GREEN commands, runtime proof, and assigned skills before implementation begins.
• T11 requires final findings-first implementation review and migration-owned simplification.
• Because this epic changes architecture, runtime composition, configuration, shared protocol, and operator-facing CLI internals, T11 routes docs-ingest-phase and updates docs/README.md, relevant wiki concepts/flows/runbooks, wiki bookkeeping, implementation notes, and the phase handoff.
• No implementation, commit, push, PR creation, merge, deployment, skill sync, baseline refresh, or rename work occurs during this plan phase.