Plan: PR #88 Review Remediation

Current Situation

PR #88 remediation implementation, the accepted findings-first review, and final aggregate CI-parity validation are complete. Primary implementation commit f1516f43e51c0c1e4baf4c931408ae8cc3d534d8 and CI follow-up head aabefa39b1a3e63e258f38d4d0ac1af219ee8d2d are current implementation authority. T14 still owns live PR and tracker readback. The planning SHA remains historical evidence, not final authority, and no final docs SHA or GitHub run is claimed.

Goal

Deliver every accepted requirement in SPEC.md, validate the supported CLI/API products and exact CI path, resolve the resulting review threads, and leave PR #88 open, unmerged, correctly based, pushed, and ready for review.

Branch and PR Constraints

Branch: team/stefan/refactor-cli-architecture
Base: main
PR: #88
Final state: open, unmerged, ready for review
Forbidden: merge, deploy, retarget, rebase, or force-push

Dependency Readiness

No stack is required. PR #88 is the single main-based core PR. Do not run stack status, stack sync --dry-run, stack sync, or stack track.

Constraints

Exact installed Effect authority is 4.0.0-beta.101.
Provider I/O stays outside DB transactions; pending/claim/finalize/release recovery semantics remain intact.
No compatibility aliases, second authorities, or speculative generic adapters.
Every behavior-changing task records real public-seam RED/GREEN evidence.
Shared hot files have one owner. Parent owns aggregate validation and evidence.
The mutating wiki sync wrapper is forbidden for this remediation.

Decision Ledger

Decision	Outcome	Reason
Report interface	`ReportSubmission.Service.submit(command)` with repository, metadata, and issue-tracker ports	Highest depth/locality; requirements stay visible to Effect Layers.
Constructor aggregate alternative	Rejected	Simpler setup but hides runtime requirements and weakens the repo's accepted Effect architecture.
API migration	Clean replacement	Compatibility aliases would preserve two authorities.
Skills process seam	Adapter-local interruptible async child	Cleanup is required, but no generic process framework is justified.
Evidence authority	PR #88 final implementation SHA plus final docs SHA	Old PR #87 evidence remains labeled historical only.

Implemented Architecture

Scaffold performs a governed settings preflight, then applies one atomic domain change containing calculated tools and managed versions.
Changelog reads are typed Effect I/O. Missing files retain fallback behavior; other filesystem failures keep the read-changelog operation and raw cause.
ReportSubmission.Service.submit is the sole report-use-case seam. It hashes identity through an injected service, preserves raw report identity for retry, releases claims on interruption, and lets the Drizzle adapter retry only unfinished deliveries.
The API process root is 32 lines. Runtime resources, lifecycle, HTTP composition, baseline delivery, report policy, provider access, and persistence live in extracted feature, platform, and integration modules.
Skills CLI execution owns an interruptible process tree. POSIX uses a dedicated process group; Windows uses the owned tree-termination path. Cleanup failure retains its underlying cause instead of reporting false success.

Codebase Findings

apps/api/src/index.ts combines HTTP groups, resource acquisition, artifact verification, runtime lifecycle, config selection, dispatch, and process signals.
apps/api/src/reports.ts combines product policy, GitHub/OpenRouter mechanics, identity, memory persistence, and the durable DB delivery state machine.
runScaffold bypasses the existing ProjectSettingsService.
Repository-check advertises changelog reads as infallible although readFileSync defects on inputs such as a directory at CHANGELOG.md.
skills-cli.ts runs spawnSync in Effect.sync, preventing prompt interruption.
update/run.ts fabricates managed summaries and widens projection actions with unsafe assertions.

Research Evidence

effect-solutions show services-and-layers testing error-handling cli confirms visible service requirements, Layer-based test doubles, typed failures, and deterministic concurrency tests.
Repo opensrc/effect.md was consulted.
opensrc path --cwd . effect could not refresh because registry access was unavailable; execution must use installed beta.101 source and declarations.
Installed Effect.callback supports an interruption cleanup registration; the pinned platform Node child-process spawner demonstrates scoped child cleanup.

Risks and Mitigations

Risk	Mitigation
Provider write becomes orphaned	Preserve pending-before-I/O plus claim/release/finalize tests.
Parallel workers collide	Exact path ownership and dependency barriers below.
Architecture-only tests give false RED	Each extraction adds a failing public-root or forbidden-dependency assertion before movement.
Runtime mocks hide integration defects	T11 owns API runtime-product and exact CI parity after all convergence.
Evidence overwrites history	Append current authority; label old SHAs/runs historical.
Wiki wrapper mutates unrelated paths	Edit required source/routed artifacts directly and validate exact parity.

Unresolved Questions

None. The user accepted all findings, selected full parallelism, authorized PR updates, and prohibited merging.

Interface Decision

ReportSubmission.Service.submit({ report, operator });

The feature owns validation, classification, duplicate policy, issue content, and prepare -> claim -> provider -> complete/release ordering. Integrations implement ReportRepository, ReportMetadata, and ReportIssueTracker. HTTP only decodes, calls the feature, and maps typed failures. Runtime composition selects live adapters.

Execution Waves

Zero-dependency work is one logical first wave. Because the runtime exposes three implementation-worker slots, the orchestrator schedules it in capacity-bounded batches while keeping every available slot busy; it does not advance to dependent work until all logical-wave tasks are green.

Logical Wave A:
  T1 report feature contract
  T2 runtime lifecycle modules
  T3 governed scaffold settings
  T4 typed changelog I/O
  T5 cast-free reconciliation
  T8 interruptible Skills CLI

Wave B:
  T6 report adapters <- T1
  T7 baseline and HTTP modules <- T1,T2

Wave C:
  T9 reports convergence <- T1,T6,T7

Wave D:
  T10 entrypoint convergence <- T1,T2,T6,T7,T9

Wave E:
  T11 aggregate/runtime/CI validation <- T3,T4,T5,T8,T9,T10
  T12 mandatory review and repair <- T11
  T13 docs and evidence <- T12
  T14 live PR/Linear closeout <- T13

Task Graph

T1: Define the report-submission feature contract

depends_on: []
location: apps/api/src/features/report-submission/**
description: Create one submit facade, explicit repository/metadata/issue tracker ports, typed models/errors, and feature-owned durable ordering. Feature tests use deterministic mock Layers. Do not edit reports.ts or index.ts.
validation: Public feature tests prove auth policy, rejection, duplicate handling, pending-before-provider, completion, and release on provider failure.
status: complete
log: Added the canonical submit service, typed ports/models/errors, feature policy, durable orchestration, and deterministic test Layers. The pre-existing submitter seam remains only until T9/T10 migrate its consumers.
files edited/created: apps/api/src/features/report-submission/{adapter.ts,index.ts,port.ts,models.ts,policy.ts,service.ts,testing.ts,report-issue-tracker.ts,report-metadata.ts,report-repository.ts,report-submission.test.ts} and typed error modules in the same folder.
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, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, improve-codebase-architecture, logging-best-practices, parallel-research, quality-types, simplify, tdd]
tdd_status: required
tdd_target: The feature executes policy with test Layers and preserves durable ordering.
red_command: bun run --cwd apps/api test -- src/features/report-submission
expected_red_failure: The public submit seam and required port contracts do not exist.
green_command: bun run --cwd apps/api test -- src/features/report-submission && bun run --cwd apps/api check-types
reason_not_testable:
red_evidence: Focused Vitest exited 1 at the public root because ReportSubmission.Default was absent.
green_evidence: Feature tests pass 7/7; combined legacy/new feature contracts pass 11/11; API typecheck passes; Effect domain/typed-failure contracts pass 60/60; parent wave validation passes all 13 T1/T2 tests.
codebase_design_notes: One deep use-case root; small port interfaces; feature-local test surface.
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: T11 owns live composition proof.
runtime_cleanup: not_applicable

T2: Extract runtime resource and lifecycle modules

depends_on: []
location: apps/api/src/platform/runtime/{resources,lifecycle}*
description: Add narrow resource/lifecycle modules and focused tests for acquisition, memoized initialization, retry, disposal, and terminal state. index.ts remains untouched until T10.
validation: A new public-root contract first fails because runtime modules do not exist; GREEN proves concurrent single init, retry after failure, no get after disposal, and deterministic cleanup.
status: complete
log: Added independent resource and lifecycle modules without wiring index.ts. They cover initialization concurrency/retry, terminal disposal, late init cleanup, and deterministic dual-failure aggregation.
files edited/created: apps/api/src/platform/runtime/{resources.ts,resources.test.ts,lifecycle.ts,lifecycle.test.ts}
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, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, improve-codebase-architecture, logging-best-practices, parallel-research, quality-types, simplify, tdd]
tdd_status: required
tdd_target: Runtime lifecycle is independently executable through its public seam.
red_command: bun run --cwd apps/api test -- src/platform/runtime
expected_red_failure: Runtime public modules and lifecycle contracts are absent.
green_command: bun run --cwd apps/api test -- src/platform/runtime && bun run --cwd apps/api check-types
reason_not_testable:
red_evidence: Focused Vitest exited 1 during module resolution because both runtime public modules were absent.
green_evidence: Two files and 6 tests pass; API typecheck, targeted lint/format, and parent combined T1/T2 validation pass.
codebase_design_notes: Runtime mechanics are platform modules, never feature dependencies.
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: T10/T11 own wired lifecycle proof.
runtime_cleanup: not_applicable

T3: Route scaffold settings through ProjectSettings

depends_on: []
location: apps/cli/src/scaffold/{run.ts,run.test.ts,capabilities.ts}; apps/cli/src/platform/{scaffold-capabilities.ts,feature-application-operations.ts}
description: Read through ProjectSettingsService and apply calculated-tools and managed-version domain changes. Remove only the scaffold legacy read/write capability.
validation: A public scaffold test injects the governed service and fails at planning head because it receives no calls; GREEN proves read and both mutations.
status: complete
log: runScaffold now performs a governed preflight read, then submits one atomic domain change containing calculated tools and managed versions. Removed the scaffold write-settings capability; retained read-settings only for its separate tool-ensure consumer.
files edited/created: apps/cli/src/scaffold/{run.ts,run.test.ts,capabilities.ts}; apps/cli/src/platform/{scaffold-capabilities.ts,feature-application-operations.ts}
backlog_item_id: IP-327
backlog_item_url: https://linear.app/devpunks/issue/IP-327/preserve-project-setting-authority-across-every-lifecycle-command
relation_mode: native
assigned_skills: [autoreview, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, improve-codebase-architecture, parallel-research, quality-types, simplify, swarm-planner, tdd, turborepo]
tdd_status: required
tdd_target: Scaffold uses the governed settings public service exclusively.
red_command: bun run --cwd apps/cli test src/scaffold/run.test.ts
expected_red_failure: Injected ProjectSettings spy records no read or change.
green_command: bun run --cwd apps/cli test src/scaffold/run.test.ts && bun run --cwd apps/cli check-types
reason_not_testable:
red_evidence: Focused suite failed 1/18; governed settings spy received [] instead of read plus two domain changes.
green_evidence: Scaffold/tools suites pass 23/23; CLI typecheck and targeted format/diff checks pass; parent combined CLI wave passes 83/83.
codebase_design_notes: Reuse one settings authority; delete the scaffold pass-through seam.
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: not_applicable
runtime_cleanup: not_applicable

T4: Make repository-check changelog I/O typed

depends_on: []
location: apps/cli/src/features/repository-check/{application.ts,port.ts,application-boundary.test.ts}; apps/cli/src/platform/repository-check-capabilities.ts; apps/cli/src/cli/check-command.test.ts
description: Make changelog read an Effect with RepositoryCheckOperationFailure. Preserve missing-file fallback; actual read errors remain typed.
validation: An EISDIR fixture fails at planning head as a defect; GREEN fails through the expected typed channel.
status: complete
log: Changelog reads now return an Effect and translate filesystem failures once at the platform adapter. Missing changelog preserves local-summary fallback.
files edited/created: apps/cli/src/cli/check-command.test.ts; apps/cli/src/features/repository-check/{application.ts,port.ts}; apps/cli/src/platform/repository-check-capabilities.ts
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, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, improve-codebase-architecture, parallel-research, quality-types, simplify, swarm-planner, tdd, turborepo]
tdd_status: required
tdd_target: Public hi check exposes changelog read errors as typed product information.
red_command: bun run --cwd apps/cli test src/cli/check-command.test.ts src/features/repository-check/application-boundary.test.ts
expected_red_failure: EISDIR escapes as a defect instead of RepositoryCheckOperationFailure.
green_command: bun run --cwd apps/cli test src/cli/check-command.test.ts src/features/repository-check/application-boundary.test.ts && bun run --cwd apps/cli check-types
reason_not_testable:
red_evidence: Public EISDIR fixture escaped as a raw defect; focused suite reported 1 failed and 15 passed.
green_evidence: Focused suite passes 17/17 with RepositoryCheckOperationFailure operation read-changelog; CLI typecheck, targeted lint/format/diff, and parent combined CLI 83/83 pass.
codebase_design_notes: Filesystem failure is translated once at the platform adapter.
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: not_applicable
runtime_cleanup: not_applicable

T5: Remove unsafe reconciliation assertions

depends_on: []
location: apps/cli/src/update/{run.ts,run-boundary.test.ts}; apps/cli/src/features/scaffold-state/reconcile.test.ts
description: Replace both double assertions with typed object construction and action-wide widening with explicit property narrowing. Do not redesign schemas.
validation: A new architecture boundary test fails on the three accepted source patterns; reconciliation behavior and typecheck remain green after removal.
status: complete
log: Replaced two double assertions with typed construction and the action-wide semantic cast with local type guards. No schema or behavior change.
files edited/created: apps/cli/src/update/{run.ts,run-boundary.test.ts}
backlog_item_id: IP-328
backlog_item_url: https://linear.app/devpunks/issue/IP-328/derive-one-deterministic-scaffold-plan
relation_mode: native
assigned_skills: [autoreview, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, improve-codebase-architecture, parallel-research, quality-types, simplify, swarm-planner, tdd, turborepo]
tdd_status: required
tdd_target: Reconciliation is behaviorally unchanged and the unsafe escape hatches are absent.
red_command: bun run --cwd apps/cli test src/update/run-boundary.test.ts
expected_red_failure: The boundary test finds two double assertions and one action-wide cast.
green_command: bun run --cwd apps/cli test src/update/run-boundary.test.ts src/features/scaffold-state/reconcile.test.ts && bun run --cwd apps/cli check-types
reason_not_testable:
red_evidence: New boundary test exited 1 with exactly three accepted unsafe source matches.
green_evidence: Boundary plus unchanged reconciliation tests pass 28/28; CLI typecheck, format/diff, and parent combined CLI 83/83 pass.
codebase_design_notes: Derive exact types and narrow unknown intent locally.
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: not_applicable
runtime_cleanup: not_applicable

T6: Implement report provider and persistence adapters

depends_on: [T1]
location: apps/api/src/integrations/reports/**; apps/api/src/integrations/persistence/report-repository*
description: Implement GitHub/OpenRouter and memory/Drizzle adapters against T1 ports. Preserve cancellation, label-before-issue, normalization, retry-stable identity, exclusive claim, short transactions, finalization, and release.
validation: Adapter contracts prove every failure point and that no provider callback occurs inside a transaction.
status: complete
log: Added GitHub/OpenRouter adapters and memory/Drizzle report repositories against the T1 ports. The feature preserves raw report identity across retry and uses injected identity hashing. Provider mechanics, typed per-operation failures, short transactions, unfinished-only Drizzle retry, reclaim, finalize, and interruption-safe release remain behind the ports.
files edited/created: apps/api/src/integrations/reports/{github-report-issue-tracker.ts,openrouter-report-metadata.ts,index.ts,provider-adapters.test.ts}; apps/api/src/integrations/persistence/{report-repository-memory.ts,report-repository-drizzle.ts,index.ts,report-repository.test.ts}
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, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, improve-codebase-architecture, logging-best-practices, parallel-research, quality-types, simplify, tdd]
tdd_status: required
tdd_target: Concrete adapters satisfy the public ports and failure/recovery contract.
red_command: bun run --cwd apps/api test -- src/integrations/reports src/integrations/persistence/report-repository
expected_red_failure: T1 ports have no concrete live adapters.
green_command: bun run --cwd apps/api test -- src/integrations/reports src/integrations/persistence/report-repository && bun run --cwd apps/api check-types
reason_not_testable:
red_evidence: Exact focused command failed two suites during module resolution because concrete provider and repository adapters were absent.
green_evidence: Exact focused suite passes 8/8; API typecheck, targeted lint/format, and parent Wave B aggregate pass (8 files, 31 tests).
codebase_design_notes: Integrations translate mechanics only; feature owns ordering.
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: T11 owns real provider-disabled and DB runtime composition proof.
runtime_cleanup: not_applicable

T7: Extract baseline delivery and HTTP modules

depends_on: [T1, T2]
location: apps/api/src/features/baseline-delivery/**; apps/api/src/integrations/baseline-artifact/**; apps/api/src/platform/http/**
description: Add one baseline download feature, artifact adapter, thin route handlers, and HTTP application composition. Preserve auth/access/CORS, exact version, bounded body, digest, cancellation, and response bytes. Do not edit index.ts, reports.ts, or existing root tests.
validation: New public-seam tests fail because modules are absent, then prove baseline verification and feature-only HTTP dependencies.
status: complete
log: Added baseline authority/artifact feature, GitHub artifact integration, thin baseline HTTP route, and minimal CORS/fallback application builder. Modules remain intentionally unwired until T10.
files edited/created: apps/api/src/features/baseline-delivery/{baseline-artifact.ts,baseline-authority.ts,errors.ts,index.ts,model.ts,service.ts,baseline-delivery.test.ts}; apps/api/src/integrations/baseline-artifact/{baseline-artifact.ts,baseline-authority.ts,index.ts,baseline-artifact.test.ts}; apps/api/src/platform/http/{application.ts,baseline-download.ts,index.ts,types.ts,baseline-download.test.ts}
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, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, improve-codebase-architecture, logging-best-practices, parallel-research, quality-types, simplify, tdd]
tdd_status: required
tdd_target: Baseline and transport behavior is independently executable through public seams.
red_command: bun run --cwd apps/api test -- src/features/baseline-delivery src/integrations/baseline-artifact src/platform/http
expected_red_failure: The required public modules do not exist.
green_command: bun run --cwd apps/api test -- src/features/baseline-delivery src/integrations/baseline-artifact src/platform/http && bun run --cwd apps/api check-types
reason_not_testable:
red_evidence: Exact focused command failed three suites because feature, integration, and platform HTTP public modules were absent.
green_evidence: Three focused files pass 10/10; API typecheck and targeted lint/format/diff pass; parent Wave B aggregate passes 31/31.
codebase_design_notes: HTTP maps transport only; artifact mechanics stay in an adapter.
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: T10/T11 own wired HTTP/artifact runtime proof.
runtime_cleanup: not_applicable

T8: Make Skills CLI execution interruptible

depends_on: []
location: apps/cli/src/integrations/{skills-cli.ts,skills-cli.test.ts}
description: Replace blocking spawnSync with an interruptible asynchronous child Effect. Preserve ENOENT, timeout, nonzero, stdout, and stderr semantics; cleanup owns only the spawned child with bounded termination escalation.
validation: Deterministic readiness plus PID evidence proves fiber interruption terminates the child and leaves no residue; no sleep is used.
status: complete
log: Replaced spawnSync with async spawn registered through Effect.callback. Interruption and timeout clean the owned process tree through a dedicated POSIX process group or the Windows tree-termination path. Bounded escalation preserves typed command failures, and cleanup failure retains the raw cause.
files edited/created: apps/cli/src/integrations/{skills-cli.ts,skills-cli.test.ts}
backlog_item_id: IP-322
backlog_item_url: https://linear.app/devpunks/issue/IP-322/make-operator-skill-state-immutable-and-verifiable
relation_mode: native
assigned_skills: [autoreview, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, improve-codebase-architecture, parallel-research, quality-types, simplify, swarm-planner, tdd, turborepo]
tdd_status: required
tdd_target: Fiber interruption promptly terminates the owned Skills CLI process.
red_command: bunx vitest run --config apps/cli/vitest.config.ts apps/cli/src/integrations/skills-cli.test.ts
expected_red_failure: Interruption blocks or the recorded child remains alive.
green_command: bunx vitest run --config apps/cli/vitest.config.ts apps/cli/src/integrations/skills-cli.test.ts && bun run --cwd apps/cli check-types
reason_not_testable:
red_evidence: Public interruption tracer timed out at 15 seconds after child readiness because the blocking fiber/event loop could not resume.
green_evidence: Interruption tracer passes 1/1 in 149ms; full adapter suite passes 20/20; CLI typecheck/lint/format/diff pass; parent combined CLI wave passes 83/83.
codebase_design_notes: Adapter-local child seam; no generic process abstraction.
review_mode: cli
runtime_validation: required
runtime_target: Fake Skills CLI child.
runtime_evidence: Readiness, interruption, child exit, and empty PID residue.
runtime_cleanup: Terminate only the recorded child/process group and wait for close.

T9: Converge reports onto the deep feature

depends_on: [T1, T6, T7]
location: apps/api/src/{reports.ts,reports.test.ts,reports-boundary.test.ts}
description: Sole owner migrates the old report Store and its concentrated tests to T1/T6. Remove old policy/provider/persistence authority without an alias. Do not edit index.ts or platform/http/**.
validation: Before migration, a new boundary test fails on forbidden GitHub/OpenRouter/Drizzle/durable-policy ownership in reports.ts; GREEN plus the full report characterization suite proves behavior preservation.
status: complete
log: Deleted legacy reports.ts with no forwarding alias and migrated 57 meaningful characterizations to ReportSubmission.Service.submit, the sole report-use-case seam. Convergence preserved raw retry identity, injected identity hashing, interruption-safe claim release, and unfinished-only Drizzle retry. Removed a test-facade-only missing-runner case; T10 owns the real composition proof.
files edited/created: deleted apps/api/src/reports.ts; updated apps/api/src/reports.test.ts; added apps/api/src/reports-boundary.test.ts; repair edits in apps/api/src/features/report-submission/{policy.ts,index.ts,report-submission.test.ts}; apps/api/src/integrations/persistence/{report-repository-drizzle.ts,report-repository.test.ts}
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, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, improve-codebase-architecture, logging-best-practices, parallel-research, quality-types, simplify, tdd]
tdd_status: required
tdd_target: Old report authority is absent and all characterized public behavior survives.
red_command: bun run --cwd apps/api test -- src/reports-boundary.test.ts
expected_red_failure: Boundary test finds provider, persistence, or workflow policy in reports.ts.
green_command: bun run --cwd apps/api test -- src/reports-boundary.test.ts src/reports.test.ts src/features/report-submission src/integrations/reports src/integrations/persistence/report-repository && bun run --cwd apps/api check-types
reason_not_testable:
red_evidence: Boundary test exited 1 after finding the legacy HarnessReportStore/store-construction authority. Integration REDs also proved duplicate creation under partial narrative matching and retry delivery content rebuilt from the new request.
green_evidence: Boundary, 57 report characterizations, feature, provider, and repository suites pass 75/75. Duplicate feature suite passes 8/8 and persisted repository suite 4/4. Formatting/lint/diff pass. API typecheck is intentionally deferred to T10 because old root consumers now import the deleted authority.
codebase_design_notes: Clean replacement; public feature is the sole report authority.
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: T11 owns supported runtime proof.
runtime_cleanup: not_applicable

T10: Reduce index to the process adapter

depends_on: [T1, T2, T6, T7, T9]
location: apps/api/src/{index.ts,index.test.ts,index-boundary.test.ts,public-api-contract.test.ts,database-injection-contract.test.ts,auth-lifecycle-contract.test.ts,http-adapter-contract.test.ts,runtime/config-contract.test.ts,production-application-lifecycle-contract.test.ts,production-shutdown-contract.test.ts,runtime-product-contract.test.ts}; apps/api/src/platform/report-submission.ts
description: Sole owner wires extracted feature/platform roots and removes inline resources, handlers, artifact mechanics, and singleton lifecycle. Keep exported handler/dispose/default fetch and process-signal registration. Replace the old report-submission platform adapter and its database-injection contract with the T1 service and T6 live/test Layers.
validation: New boundary RED finds forbidden policy/mechanics in index.ts. GREEN preserves public API, artifact, auth/access, lifecycle, shutdown, build, and the real runtime-product validator.
status: complete
log: Reduced index.ts from 1,113 lines to a 32-line process root. Extracted runtime resources, lifecycle, HTTP composition, baseline delivery, report composition, provider, persistence, and artifact authority into deliberate modules. Runtime validation found and repaired double CORS, eager DB initialization for baseline downloads, and report-ID byte drift.
files edited/created: apps/api/src/{index.ts,index.test.ts,index-boundary.test.ts,public-api-contract.test.ts,database-injection-contract.test.ts,auth-lifecycle-contract.test.ts}; apps/api/src/platform/report-submission.ts; T6 stable-ID repair in apps/api/src/integrations/persistence/{report-repository-drizzle.ts,report-repository.test.ts}
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, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, improve-codebase-architecture, logging-best-practices, parallel-research, quality-types, simplify, tdd]
tdd_status: required
tdd_target: index.ts is process/composition only while supported behavior remains unchanged.
red_command: bun run --cwd apps/api test -- src/index-boundary.test.ts
expected_red_failure: Boundary test finds feature/provider/artifact/persistence/lifecycle implementation in index.ts.
green_command: bun run --cwd apps/api test -- src/index-boundary.test.ts src/index.test.ts src/public-api-contract.test.ts src/production-application-lifecycle-contract.test.ts src/production-shutdown-contract.test.ts src/runtime-product-contract.test.ts && bun run --cwd apps/api check-types && bun run --cwd apps/api build && bun run --cwd apps/api validate:runtime-product
reason_not_testable:
red_evidence: Boundary test failed 1/1 after finding inline artifact, DB/runtime, legacy report-store, provider, and email authority. First runtime run ip319-1c79c41e-5a7d-4ead-8498-c8b2ad34e774 failed immutable bytes because of double CORS and a 43-byte report ID.
green_evidence: Focused gate passes 8 files and 54/54 tests; API typecheck/build, lint/format/diff, and shutdown 2/2 pass. Runtime run ip319-14e0dac4-8cc6-4039-9f63-4d5e231a5ed0 is valid:true in 4,638ms with dist SHA 10f82adcf76655845b423df3d8fbb511c20fba305e4308d5258c868450aedf07; no matching Docker container or run evidence/manifest directories remain.
codebase_design_notes: Entry point is a shallow process adapter over deep modules.
review_mode: cli
runtime_validation: required
runtime_target: Supported packaged API with Postgres and Better Auth fixtures.
runtime_evidence: Public requests, typed startup failure, persistence, lifecycle, and cleanup report.
runtime_cleanup: Existing run-id validator removes only owned rows/processes/files.

T11: Run aggregate, runtime, and exact CI-parity validation

depends_on: [T3, T4, T5, T8, T9, T10]
location: read-only validation
description: Run focused/full CLI and API, runtime product, Effect architecture, static checks/builds, and the exact GitHub workflow command with workflow env and base/head SHAs. This task patches nothing; failures return to owners.
validation: Every command exits zero, runtime cleanup is empty, and worktree changes are exactly implementation artifacts.
status: complete
log: Exact test:ci passed from base starting 402c7dcc to head aabefa39b1a3e63e258f38d4d0ac1af219ee8d2d: Effect aggregate 95 pass, 1 deliberate skip, 0 fail; root behavior contracts 46/46; Turbo full graph 30/30 in 55.392s. Final standalone gates passed CLI 913/913, API 250/250, Effect 96/96, check 12/12, check-types 13/13, build 6/6, and runtime product valid:true. Generated wiki source digest was 6e8fdb01a0f8640a574d2abe36d5920d7fd7c3376854cae9568636971351fd03.
files edited/created:
backlog_item_id: IP-324
backlog_item_url: https://linear.app/devpunks/issue/IP-324/complete-one-v4-only-repository-cutover
relation_mode: native
assigned_skills: [effect, tdd, turborepo]
tdd_status: not_applicable
tdd_target: Read-only convergence proof.
red_command: not_applicable
expected_red_failure: not_applicable
green_command: bun run --cwd apps/cli test && bun run --cwd apps/api test && bun run --cwd apps/api validate:runtime-product && bun test ./scripts/effect-v4/domain-boundaries.contract.test.ts ./scripts/effect-v4/typed-failures.contract.test.ts ./scripts/effect-v4/config-boundaries.contract.test.ts && bun run check && bun run check-types && bun run build && env BACKOFFICE_API_BASE_URL=https://harness-api.localhost BETTER_AUTH_SECRET=ci-only-better-auth-secret-000000000 BETTER_AUTH_URL=https://harness-backoffice.localhost/api/auth CI=true CORS_ORIGIN=https://harness-backoffice.localhost DATABASE_URL=postgresql://ci:ci@127.0.0.1:5432/harness_ci NEXT_TELEMETRY_DISABLED=1 NEXT_PUBLIC_SERVER_URL=https://harness-api.localhost RESEND_API_KEY=ci-only-resend-key RESEND_FROM_EMAIL='Harness CI <ci@devpunks.test>' TZ=UTC TURBO_SCM_BASE="$(git merge-base origin/main HEAD)" TURBO_SCM_HEAD="$(git rev-parse HEAD)" bun run test:ci -- --output-logs=errors-only
reason_not_testable: Validation-only; RED/GREEN belongs to T1-T10.
red_evidence:
green_evidence: Exact CI parity and every standalone aggregate gate passed with the counts recorded above. CI also proved the safe wiki type-generation order in generated consumer scripts and bounded Skills cleanup under load.
codebase_design_notes: not_applicable
review_mode: cli
runtime_validation: required
runtime_target: CLI and API supported runtime products plus CI task selection.
runtime_evidence: Runtime product reported valid:true; exact CI used base starting 402c7dcc and head aabefa39b1a3e63e258f38d4d0ac1af219ee8d2d.
runtime_cleanup: Confirm empty remaining/unknown resource sets.

T12: Perform findings-first review and repair

depends_on: [T11]
location: full PR #88 diff
description: Run independent Effect, architecture, quality-type, TDD, and simplification review. Route actionable findings to disjoint owners and repeat T11.
validation: Reviewer outputs contain no unresolved P0-P2 finding; parent audits each acceptance criterion and changed public seam.
status: complete
log: Completed the accepted findings-first remediation review and repaired the process-tree, settings atomicity, report retry/identity/release, Drizzle retry, and API-root findings. No accepted implementation finding remains; final aggregate evidence stays owned by T11.
files edited/created:
backlog_item_id: IP-324
backlog_item_url: https://linear.app/devpunks/issue/IP-324/complete-one-v4-only-repository-cutover
relation_mode: native
assigned_skills: [autoreview, effect, improve-codebase-architecture, quality-types, review-phase, simplify, tdd]
tdd_status: not_applicable
tdd_target: Readonly review.
red_command: not_applicable
expected_red_failure: not_applicable
green_command: git diff --check
reason_not_testable: Review-only task; closure is reviewer evidence, not a test.
red_evidence:
green_evidence: Accepted remediation review is complete with no accepted implementation finding remaining. The Windows cleanup follow-up and final T11 aggregate proof are green.
codebase_design_notes: Review checks depth, dependency direction, and public test surfaces.
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: not_applicable
runtime_cleanup: not_applicable

T13: Reconcile docs and durable evidence

depends_on: [T12]
location: docs/{README.md,reference/harness-intelligence.md,runbooks/hi-cli-scaffolding.md}; source/routed IP-320 and IP-324 plan/notes/handoff; apps/wiki/specs/cli/PR-88-review-remediation/**; apps/wiki/content/docs/project/specs/cli/PR-88-review-remediation/**
description: Record actual RED/GREEN/runtime evidence, correct IP-320 T9 classification, document process/report architecture, and preserve old SHA evidence as historical. Edit source/routed copies directly.
validation: Relevant source/routed artifacts agree; targeted formatting and diff checks pass; commands and public seams match implementation.
status: complete
log: Private/internal ingest updated the PR-88 source artifacts, routed projection, IP-320/IP-324 historical evidence, and root operator docs. Historical PR #87 SHAs and runs remain labeled history; no final PR #88 SHA or check result was invented.
files edited/created: apps/wiki/specs/cli/PR-88-review-remediation/**; routed projection and metadata under apps/wiki/content/docs/project/specs/cli/PR-88-review-remediation/**; source and routed IP-320/IP-324 plan, implementation-note, and handoff evidence; apps/wiki/{index.md,log.md}; docs/{README.md,reference/harness-intelligence.md,runbooks/hi-cli-scaffolding.md}; routed root-doc projections.
backlog_item_id: IP-324
backlog_item_url: https://linear.app/devpunks/issue/IP-324/complete-one-v4-only-repository-cutover
relation_mode: native
assigned_skills: [docs-ingest-phase, review-phase, tdd]
tdd_status: not_applicable
tdd_target: Durable documentation truth.
red_command: not_applicable
expected_red_failure: not_applicable
green_command: cmp apps/wiki/specs/cli/PR-88-review-remediation/SPEC.md apps/wiki/content/docs/project/specs/cli/PR-88-review-remediation/SPEC.md && cmp apps/wiki/specs/cli/PR-88-review-remediation/PLAN.md apps/wiki/content/docs/project/specs/cli/PR-88-review-remediation/PLAN.md && cmp apps/wiki/specs/cli/PR-88-review-remediation/IMPLEMENTATION-NOTES.md apps/wiki/content/docs/project/specs/cli/PR-88-review-remediation/IMPLEMENTATION-NOTES.md && bunx oxfmt --check docs/README.md docs/reference/harness-intelligence.md docs/runbooks/hi-cli-scaffolding.md apps/wiki/specs/cli/PR-88-review-remediation apps/wiki/specs/cli/IP-320-domain-first-effect-v4-architecture apps/wiki/specs/cli/IP-324-v4-repository-cutover apps/wiki/content/docs/project/specs/cli/PR-88-review-remediation apps/wiki/content/docs/project/specs/cli/IP-320-domain-first-effect-v4-architecture apps/wiki/content/docs/project/specs/cli/IP-324-v4-repository-cutover && git diff --check
reason_not_testable: Docs/evidence only.
red_evidence:
green_evidence: Repository projection completed and node apps/wiki/scripts/sync-content.mjs --check, targeted oxfmt --check, source versus routed cmp, metadata checks, and git diff --check pass.
codebase_design_notes: Docs describe the public authority; they do not duplicate it.
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: not_applicable
runtime_cleanup: not_applicable

T14: Push and verify live PR/Linear authority

depends_on: [T13]
location: Git, GitHub PR #88, Linear IP-320/IP-322/IP-324/IP-327/IP-328/IP-332/IP-334
description: Commit conventionally, push without force, refresh PR body with implementation/docs SHAs and validation, resolve addressed review threads through GraphQL, append concise Linear evidence, and verify live state.
validation: gh pr view, terminal gh pr checks, review-thread GraphQL, and Linear readback prove current head/base/checks, no unresolved addressed thread, truthful tracker links, and open/unmerged/ready-for-review state.
status: pending
log:
files edited/created:
backlog_item_id: IP-324
backlog_item_url: https://linear.app/devpunks/issue/IP-324/complete-one-v4-only-repository-cutover
relation_mode: native
assigned_skills: [review-phase, tdd]
tdd_status: not_applicable
tdd_target: External authority readback.
red_command: not_applicable
expected_red_failure: not_applicable
green_command: gh pr view 88 --json number,state,isDraft,mergeable,baseRefName,headRefName,headRefOid,url && gh pr checks 88 --watch --fail-fast && gh api graphql -F owner=wearedevpunks -F repo=harness-intelligence -F number=88 -f query='query($owner:String!,$repo:String!,$number:Int!){repository(owner:$owner,name:$repo){pullRequest(number:$number){reviewThreads(first:100){nodes{id isResolved comments(first:20){nodes{databaseId body path}}}}}}}' && linear issue view IP-320 && linear issue view IP-322 && linear issue view IP-324 && linear issue view IP-327 && linear issue view IP-328 && linear issue view IP-332 && linear issue view IP-334
reason_not_testable: External closeout verified by live readback.
red_evidence:
green_evidence:
codebase_design_notes: not_applicable
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: not_applicable
runtime_cleanup: not_applicable

Testing Strategy

One public-seam tracer bullet at a time; production follows observed RED.
Effect feature tests replace leaf dependencies with Layers, not module mocks.
Real adapter contracts test boundaries once; downstream feature tests do not retest dependency mechanics.
Interruption tests use deterministic readiness and PID exit, never sleeps.
Focused suites run per task; T11 alone runs expensive aggregate/runtime/CI gates.

Review Strategy

Review the entire PR through Standards and Spec lenses: Effect requirements, typed failure channels, interruption finalizers, transaction/recovery laws, deep-module dependency direction, unsafe assertions, public behavior, and evidence quality.

Documentation Strategy

Update root docs and affected runbooks after GREEN. Update source/routed IP-320 and IP-324 evidence directly. Record current PR #88 authority while retaining old PR #87 data as labeled history.

Backlog Sync

Existing native hierarchy is sufficient; create no new Linear issues. T14 appends current evidence to existing items without rewriting product-facing bodies or changing completed hierarchy unless an acceptance item is genuinely incomplete.

Stop Conditions

Stop only for material user authority or infrastructure blockers. Completion requires all tasks green, no P0-P2 finding, clean pushed branch, live green checks, truthful Linear/evidence, resolved addressed threads, and PR #88 open, unmerged, correctly based, and ready for review.

Plan: PR #88 Review Remediation

On this page