porch: make gate artifact auto-open configurable

[mohidmakhdoomi]

Summary

Adds porch.autoOpenArtifacts as a backward-compatible, producer-side opt-out for Porch's automatic specification, plan, and review artifact opens. Setting it to false prevents Porch from invoking afx open while preserving gate state, artifact output, approval instructions, manual file opens, and Tower's normal tab-focus behavior.

Agent Farm also propagates the main workspace's personal .codev/config.local.json preference into builders as an atomically refreshed regular-file snapshot, avoiding write-through mutation of the main personal configuration.

Closes #1216

Changes

• Add the optional porch.autoOpenArtifacts configuration key; unset and true preserve existing behavior, while explicit false suppresses the automatic afx open child process.
• Cover specification, plan, review, missing-artifact, and unmapped-artifact gate paths while verifying that pending gate state and approval output remain unchanged.
• Snapshot .codev/config.local.json into builder worktrees during both spawn paths and afx setup, refreshing it before post-spawn hooks without using a symlink or deleting builder-local preferences when the main source is absent.
• Add config-precedence, gate-boundary, spawn/setup-ordering, filesystem, refresh, idempotency, and source-immutability regression tests.
• Isolate tower-utils.test.ts’s HOME so developer-global architect-harness configuration cannot affect Agent Farm/Tower default-harness assertions.
• Document the setting, precedence, manual-open behavior, and builder snapshot ownership model in both project and shipped skeleton references.

Testing

• Focused config, gate, spawn, setup, and snapshot suites: 140 passed.
• Full @cluesmith/codev Vitest suite: 3,638 passed, 48 existing skips, 0 failed.
• Root pnpm build: passed.
• Porch build and test checks: passed.
• Headless Tower flow: a disabled gate created 0 file tabs and left the existing Work tab active; manual afx open still created and focused the expected file tab.

Spec

Link: codev/specs/1216-configurable-porch-gate-artifact-auto-open.md

Review

Link: codev/reviews/1216-configurable-porch-gate-artifact-auto-open.md

[mohidmakhdoomi]

Architect Integration Review

Risk: High — 1,654 additions across 21 files, touching Porch orchestration and Agent Farm worktree setup.

Three-way integration review (Gemini, Codex, Claude) returned unanimous APPROVE with high confidence and no key issues.

I independently reviewed the producer guard, config precedence, snapshot/setup paths, tests, documentation, and governance updates. The design fits the architecture: porch.autoOpenArtifacts is enforced at the sole producer, defaults remain backward-compatible, and personal config reaches builders as a managed regular-file snapshot rather than a write-through symlink.

Local verification passed:

• 190 focused tests across config, Porch gate behavior, spawn/setup, snapshot, and test isolation
• repository build
• recorded headless Tower UX flow confirms disabled gates create no tab/focus change while manual afx open remains unchanged

Before the Porch PR gate is approved, please include the remaining untracked project protocol artifacts under codev/projects/1216-* and push the resulting commits to the fork. Do not include builder harness files.

No implementation changes requested.

---

Architect integration review

[waleedkadous]

Excellent implementation — thank you for the careful, patient iteration on this, especially the multiple rounds on the snapshot-vs-symlink ownership question. The result is a narrow core diff (a ~10-line producer-side guard plus a ~30-line atomic snapshot helper) with a thorough test and documentation surround.

Independent verification from the main workspace, on top of the unanimous 3-way CMAP already recorded:

• Sole-producer claim holds: the only afx open spawn in porch is the now-gated one in packages/codev/src/commands/porch/index.ts — nothing else produces gate artifact opens.
• The snapshot propagates a real config layer: .codev/config.local.json is the pre-existing tier-5 (per-engineer, highest-precedence) layer that loadConfig already merges, and it's covered by the repo .gitignore, so a builder can't accidentally commit an engineer's personal config from the snapshot.
• Ownership model is the right call: a symlink would be write-through (builder edits mutating the human's personal file); the regular-file snapshot trades that for staleness, and the staleness is honestly documented with afx setup as the refresh path.
• Docs are mirrored in both codev/resources/ and codev-skeleton/resources/ per the dual-tree rule, and the arch update was correctly routed to the COLD tier only.
• All 6 CI checks are green and the branch is mergeable.

Approving.