Plan: restore Effect backend internal-module guidance

Plan State

• specification: immutable agent-ready SPEC
• source issue: GitHub #205
• provider Story: IP-474
• provider Task: IP-475
• milestone: V4.3 Delivery Flow and Scaffold Reliability
• architecture_applicability: local. The change restores one bounded documentation responsibility and updates its existing synchronization pin. It does not move a runtime owner, public code seam, or cross-domain dependency.

Initial Situation

The canonical effect-backend-structure skill retains Layer ownership and test placement but omits the concrete internal-module and repository rules recorded by issue #205. effect-service-design owns authority seams and application policy and must not absorb the missing topology. Harness currently pins the public skills repository at 41f0a00af67df9d3a64213db15096a513f8db263.

The canonical source checkout is /home/stefan/repos/skills on main. Concurrent issue-#206/#207 work currently owns modified skills/agnostic/planning/verify-behavior/SKILL.md, skills/agnostic/quality/tdd/SKILL.md, skills/frameworks/react/react-doctor/SKILL.md, skills/frameworks/react/react-doctor/references/explain.md, and tests/verify-behavior.contract.test.mjs, plus untracked tests/skill-activation-boundaries.contract.test.mjs and tests/fixtures/v43/IP-453/skills/; #205 must leave those paths untouched and out of its commit. Harness branch team/stefan/issue-205-effect-backend-structure is stacked on team/stefan/issue-204-portable-commit-gates; final PR creation waits for the predecessor's published head and PR.

Locked Decisions

• effect-backend-structure owns concrete Effect internal-module topology, privacy, imports, repositories, mappers, and colocated tests.
• effect-service-design keeps service qualification, authority seams, application policy, Layers, and reusable test substitutes.
• Cross-pointers connect the two authorities without copying either rule set.
• Canonical source is edited, tested, committed, pushed, and read back before Harness changes.
• Harness updates the tested default source pin, runs bun run sync:skills, and accepts only generated skill assets plus the exact sync receipt.
• When main advances after the #205 source commit, #205 synchronizes its immutable sync/issue-205-effect-backend-structure-4e2496c5982c tag rather than incorporating the later source commit.
• Baseline-facing change notes go in BASELINE_CHANGELOG.md; npm publication and CHANGELOG.md are outside this issue unless release classification proves otherwise.
• No Astra subagents are used.

Findings and Solution Shape

The existing source contract test already distinguishes agnostic backend structure from Effect-specific Layer mechanics. Extend that public artifact contract with the missing module-boundary outcomes, then update the two canonical skills. After the source commit is public, update the Harness sync-pin test before changing the pin, synchronize, and inspect the generated delta. Update docs/README.md and both scaffolding runbooks so every documented source pin and receipt example equals the new canonical commit, and update their Effect pack ownership guidance.

writing-for-agents shapes all skill and agent-facing text: preserve a small workflow at the entrypoint, disclose detailed topology in references/layout.md, keep one source of truth per rule, and use precise completion criteria.

Dependency Graph and Wave

W1
└── T1 / IP-475
    source contract RED → canonical skills GREEN → source commit/push
      → Harness pin RED/GREEN → sync receipt → docs/changelog → validation

One worker wave is required because the provider graph contains one Task. The source commit SHA is also an input to the downstream pin and sync, so these slices cannot be safely parallelized.

Task

T1: Restore and synchronize Effect internal-module guidance

• depends_on: []
• location: /home/stefan/repos/skills; apps/cli; docs; apps/wiki/content/docs/project
• owned_paths:
  • /home/stefan/repos/skills/skills/frameworks/effect/effect-backend-structure/SKILL.md
  • /home/stefan/repos/skills/skills/frameworks/effect/effect-backend-structure/references/layout.md
  • /home/stefan/repos/skills/skills/frameworks/effect/effect-service-design/SKILL.md
  • /home/stefan/repos/skills/tests/backend-structure-composition.contract.test.mjs
  • apps/cli/scripts/sync-skills-repo.mjs
  • apps/cli/src/scripts/sync-skills-repo.test.ts
  • apps/cli/skills/**
  • apps/cli/.devpunks-cache/skills-sync.json
  • docs/README.md
  • docs/runbooks/hi-cli-scaffolding.md
  • apps/wiki/content/docs/project/runbooks/hi-cli-scaffolding.md
  • BASELINE_CHANGELOG.md
  • apps/wiki/content/docs/project/specs/cli/issue-205-effect-backend-internal-modules/PLAN.md
  • apps/wiki/content/docs/project/specs/cli/issue-205-effect-backend-internal-modules/IMPLEMENTATION-NOTES.md
  • apps/wiki/content/docs/project/specs/cli/issue-205-effect-backend-internal-modules/meta.json
• wave_boundary: W1
• description: First assert that canonical source main has no staged changes and that every unstaged/untracked path is either T1-owned or one of the exact concurrent issue-#206/#207 paths named in Initial Situation; repeat immediately before commit. Extend the canonical artifact contract with the required internal-module, import, privacy, repository, mapper, data-type, and cross-pointer outcomes and capture RED. Make the minimum canonical skill edits under writing-for-agents, reach GREEN, simplify the text, stage only T1-owned source paths, and assert git diff --cached --name-only contains exactly those paths. Commit and push main, verify the commit changed no foreign path, and read back the remote SHA. Then update the Harness sync-pin test to the exact source SHA and capture RED with bun run --cwd apps/cli test src/scripts/sync-skills-repo.test.ts; the test must report the old script pin where the new commit is expected. Change defaultRepositoryCommit, rerun the same command to GREEN, run bun run sync:skills, verify receipt equality and generated-source parity, update every documented source pin in docs/README.md and both scaffolding runbooks, add baseline notes, and retain focused/full validation evidence. Preserve unrelated source-repository files and all stack-parent changes.
• validation:
  • Canonical contract test passes and source diff has no formatting errors.
  • origin/main in wearedevpunks/skills resolves to the exact local source commit and changed source files match remote blobs.
  • Harness pin test passes against that exact SHA.
  • bun run sync:skills succeeds; apps/cli/.devpunks-cache/skills-sync.json.commit equals the source commit; synchronized effect-backend-structure and effect-service-design files equal canonical source.
  • docs/README.md, docs/runbooks/hi-cli-scaffolding.md, and apps/wiki/content/docs/project/runbooks/hi-cli-scaffolding.md contain the new source/receipt SHA and no stale 41f0a00af67df9d3a64213db15096a513f8db263 pin.
  • Focused CLI tests, managed-asset checks, wiki content check, formatting, release classification, and hi check pass or retain exact unrelated blocker evidence.
  • Final branch ancestry and PR base equal issue #204's published branch head/base contract.
• status: Implemented; Harness commit/review remain with the parent.
• log:
  • 2026-09-15: Added the source artifact contract, captured RED, restored the Effect internal-module reference and reciprocal authority pointers, then captured GREEN.
  • 2026-09-15: Committed and pushed 4e2496c5982caf6e53c526d5ecc0acf031e4853a (docs(skills): restore Effect internal module guidance) with exactly the four owned source paths; remote commit and all four blobs read back exactly.
  • 2026-09-15: #206 advanced source main to 57c4d7e4661c797cdd7995487ad3e289f740a0cd after the #205 source readback. Published immutable tag sync/issue-205-effect-backend-structure-4e2496c5982c at 4e2496c5982caf6e53c526d5ecc0acf031e4853a; final sync uses that tag and excludes #206-only generated paths.
  • 2026-09-15: Final receipt records requested ref refs/tags/sync/issue-205-effect-backend-structure-4e2496c5982c and commit 4e2496c5982caf6e53c526d5ecc0acf031e4853a; both Effect skill directories have byte parity.
  • 2026-09-15: Retained review pass 1 found that the fixed commit still paired with moving default ref main. Repair 1 made the immutable #205 tag the default, peeled annotated FETCH_HEAD to its commit before pin verification, and proved plain bun run sync:skills succeeds at the exact receipt.
• files edited/created:
  • /home/stefan/repos/skills/skills/frameworks/effect/effect-backend-structure/SKILL.md
  • /home/stefan/repos/skills/skills/frameworks/effect/effect-backend-structure/references/layout.md
  • /home/stefan/repos/skills/skills/frameworks/effect/effect-service-design/SKILL.md
  • /home/stefan/repos/skills/tests/backend-structure-composition.contract.test.mjs
  • apps/cli/scripts/sync-skills-repo.mjs
  • apps/cli/src/scripts/sync-skills-repo.test.ts
  • apps/cli/skills/**
  • apps/cli/.devpunks-cache/skills-sync.json
  • docs/README.md
  • docs/runbooks/hi-cli-scaffolding.md
  • apps/wiki/content/docs/project/runbooks/hi-cli-scaffolding.md
  • BASELINE_CHANGELOG.md
  • apps/wiki/content/docs/project/specs/cli/issue-205-effect-backend-internal-modules/PLAN.md
  • apps/wiki/content/docs/project/specs/cli/issue-205-effect-backend-internal-modules/IMPLEMENTATION-NOTES.md
• task_identity_mode: provider-task
• backlog_item_id: IP-475
• backlog_item_url: https://linear.app/devpunks/issue/IP-475/restore-and-synchronize-effect-internal-module-guidance
• relation_mode: native
• backlog_sync_skip_reason:
• assigned_skills: [codebase-design, quality-types, simplify, tdd, writing-for-agents]
• implementation_skill_guidance:
  • skill: codebase-design applicable_behavior: Keep canonical skill ownership deep and singular; treat the sync script as an adapter from the public source seam.
  • skill: quality-types applicable_behavior: Keep the TypeScript pin test derived from the one canonical commit constant and verify observable selection behavior.
  • skill: simplify applicable_behavior: Remove duplicated or no-op guidance after GREEN without changing the required ownership contract.
  • skill: tdd applicable_behavior: Capture the source artifact-contract RED before skill edits and the sync-pin RED before changing the Harness pin; retain both GREEN results.
  • skill: writing-for-agents applicable_behavior: Keep workflow steps visible, disclose branch-only topology in the layout reference, use strong pointers and checkable completion criteria, and avoid duplicated authority.
• tdd_status: required
• tdd_target: The canonical artifact contract rejects the current skills because concrete internal-module and repository-boundary guidance and reciprocal authority pointers are missing.
• red_command: cd /home/stefan/repos/skills && node --test tests/backend-structure-composition.contract.test.mjs
• expected_red_failure: New assertions for public/private module paths, import/privacy rules, repository/mapper/data constraints, and reciprocal ownership pointers fail against current main.
• green_command: cd /home/stefan/repos/skills && node --test tests/backend-structure-composition.contract.test.mjs && git diff --check
• reason_not_testable:
• red_evidence: node --test tests/backend-structure-composition.contract.test.mjs failed the new Effect skills keep internal-module topology distinct from service authority public artifact assertion because services/<capability>/service.ts topology was absent. bun run --cwd apps/cli test src/scripts/sync-skills-repo.test.ts then failed with expected 4e2496c5982caf6e53c526d5ecc0acf031e4853a and received the old pin (41f0a00af67df9d3a64213db15096a513f8db263); after #206 advanced main, the final tag-scoped retry correctly failed with expected 4e2496c5982caf6e53c526d5ecc0acf031e4853a and received 57c4d7e4661c797cdd7995487ad3e289f740a0cd.
• green_evidence: Source contract passed 3/3 with git diff --check. Final bun run --cwd apps/cli test src/scripts/sync-skills-repo.test.ts passed 1/1. After repair 1, plain bun run sync:skills fetched the default annotated tag, peeled it to commit 4e2496c5982caf6e53c526d5ecc0acf031e4853a, and produced exact receipt and Effect-directory byte parity.
• codebase_design_notes: The public skills repository is the authority seam. effect-backend-structure/SKILL.md stays a compact entrypoint, its layout reference owns detailed topology, effect-service-design owns service authority, and Harness synchronization remains a one-way adapter with an immutable source pin.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

Testing Strategy

Use two sequential public-result tracer bullets inside T1. The first proves canonical documentation behavior through the repository's artifact contract. The second updates canonicalCommit in apps/cli/src/scripts/sync-skills-repo.test.ts, runs bun run --cwd apps/cli test src/scripts/sync-skills-repo.test.ts, and records the old-script/new-test commit mismatch as RED. After defaultRepositoryCommit changes, the same command must pass as GREEN. Generated files are verified by byte parity and receipt identity rather than hand-edited tests.

Validation Gates

1. Source gate: source contract GREEN, git diff --check, source commit/push, exact remote SHA/blob readback.
2. Sync gate: pin-test RED/GREEN, bun run sync:skills, exact receipt SHA, canonical/generated byte parity, intended generated-diff audit.
3. Repository gate: focused CLI test, managed-asset checks selected by the sync diff, wiki content sync/check, changed-file formatting, hi check with exact blocker capture.
4. Release gate: non-empty reviewed baseline Unreleased note and bun run release:classify -- --base <issue-204-head> --head HEAD; no publication without separate authorization.
5. Review gate: retained review report against the final stacked diff; repair within the delivery review budget before docs ingest and closeout.
6. Docs-ingest gate: after review is clean, invoke docs-ingest-phase, write IMPLEMENTATION-NOTES.md, record whether routed concept/flow changes were needed or a verified no-op, run node apps/wiki/scripts/sync-content.mjs --check, and retain the result before closeout.

Docs Ingest Expectation

Update docs/README.md, both scaffolding runbooks, this spec package, and implementation notes because the change alters AI scaffolding guidance and distributed baseline behavior. Docs ingest may record a no-op for new conceptual pages if the existing skill reference and scaffolding runbook remain the canonical surfaces.

Risks and Mitigations

• Source repository has concurrent #206/#207 edits: permit only the exact foreign paths named in Initial Situation, stage only the four T1-owned source paths, verify the staged path set and commit path set exactly, and stop on overlap or any additional foreign change.
• Canonical main advances concurrently: pull with fast-forward only before edits; re-run source tests before commit and verify pushed SHA.
• Sync introduces unrelated upstream drift: compare the fetched source SHA and generated diff; stop if files outside expected skill mirrors, pin, receipt, docs, or baseline notes change without explanation.
• Issue #204 changes after this plan: rebase/update only after its published head is available, then rerun affected checks and verify PR base/ancestry.
• Inherited commit/pre-push gates fail outside changed paths: retain exact evidence, run the narrow applicable commands directly, and use repository-documented bypass only when the wrapper itself is malformed or failures are proven pre-existing.

Unresolved Questions

None. The issue, retained spec, provider readback, repository state, and stack constraint close the planning frontier.