Effect backend internal-module guidance

Context

Effect backend users lost concrete internal-module topology and repository-boundary guidance when effect-backend-structure was simplified. The neighboring effect-service-design skill still owns service authority and application-policy decisions, but it does not replace rules for public capabilities, private orchestration and binding seams, imports, repositories, mappers, or data types.

Non-Goals

Do not move Effect-specific topology into the agnostic backend-domain-structure skill, duplicate service authority guidance, redesign unrelated Effect skills, or change runtime product behavior.

Requirements Outcomes

OUT-001: Internal Effect modules have one concrete topology

Agents can place public Context.Service capabilities, private Effect.fn orchestration, private binding seams, repositories, models, mappers, and tests in a predictable module structure.

OUT-002: Module boundaries preserve ownership

Agents keep internals private, avoid pass-through barrels, use relative imports within a module and source aliases across module boundaries, expose narrow repository capabilities, and reject spread-only mappers or structurally identical duplicate *Data types.

OUT-003: Neighboring Effect skills cross-reference distinct authorities

effect-backend-structure owns concrete topology and repository boundaries. effect-service-design owns service qualification, authority seams, application policy, service modules, Layers, and test substitutes. Their pointers connect applicable work without duplicating either authority.

Acceptance Criteria

• AC-001: effect-backend-structure and its layout reference define public services/<capability>/service.ts, private operations/<use-case>/operation.ts, and private services/<capability>/binding.ts roles, with bindings beside their public service. Covers: OUT-001.
• AC-002: The guidance defines model, repository, mapper, and colocated test placement for an internal module. Covers: OUT-001.
• AC-003: The guidance prohibits pass-through barrels, requires relative intra-module imports and source-alias cross-module imports, and keeps module internals private. Covers: OUT-002.
• AC-004: Repository guidance favors narrow capabilities and rejects spread-only mappers and structurally identical duplicate *Data types. Covers: OUT-002.
• AC-005: Both Effect skills point to one another only at their ownership boundary, with service authority and application policy remaining in effect-service-design. Covers: OUT-003.
• AC-006: Canonical skill validation, Harness sync receipt verification, focused repository checks, and hi check complete or report exact unrelated blockers. Covers: OUT-001, OUT-002, OUT-003.

AC-001 review reconciliation

The original AC-001 named composition/<capability>/service.ts. The accepted #205 review-feedback repair places those private seams in services/<capability>/binding.ts beside the public service, with no separate composition/ directory. Implementation notes retain the source and repair commit evidence.

Constraints

Edit reusable skill source only in /home/stefan/repos/skills on checked-out main, commit and push it there, then run bun run sync:skills in Harness and verify the exact source receipt SHA. Apply writing-for-agents to every skill or prompt edit. Preserve unrelated untracked files in the skills repository. Use no Astra subagents.

Dependency Readiness

Ready: stack parent team/stefan/issue-204-portable-commit-gates exists at 7357f43b686f4866e45925f875e458e8c29ef6f3, itself based on fix/issue-203-scaffold-convergence. Final closeout must update this branch to the published issue-#204 head.

Branch/Base Intent

Implement on team/stefan/issue-205-effect-backend-structure; publish its pull request with base team/stefan/issue-204-portable-commit-gates after verifying ancestry against the predecessor's final remote head.

Accepted Technical Decisions

Keep the current agnostic layer model and three-level Layer ownership classifier. Restore the missing Effect-specific module and repository rules in effect-backend-structure and its layout reference. Use concise cross-pointers so each skill remains the single source of truth for its authority.

Accepted Testing Decisions

Validate skill package structure and links in the canonical skills repository. After synchronization, verify the receipt SHA and generated Harness surfaces, run focused checks for changed skill/scaffold assets, and run hi check where available.

Verification Seams

Canonical skill files and their validation commands, the skills repository commit and remote readback, bun run sync:skills, the Harness source receipt, focused Harness checks, and hi check output.

Decision Log