Add worktree setup contract

[VincentShipsIt]

---

name: worktree-setup-contract
description: Declare fresh-worktree setup, env hydration, and verification commands per repo.
status: backlog
estimated_complexity: high
blast_radius: cross-app

PRD: worktree-setup-contract

Executive Summary

A git worktree isolates code, but it does not guarantee a runnable development environment. Fresh worktrees can still fail because env files are missing, codegen was never run, databases are not bootstrapped, or the repo's setup contract only exists in a human's head. ShipCode should add an explicit repo-scoped dev setup contract so execution and verification happen in environments that are reproducible instead of lucky.

Problem Statement

Today ShipCode knows how to create a worktree and run commands, but not how to make that worktree ready. That creates avoidable failures: agents can write valid code and still fail verification because the workspace lacks required setup, secrets, generated artifacts, or declared commands. The result is noisy verifier failures, wasted retries, and lower trust in autonomous runs.

Goals

• A project can declare the setup commands and verification commands ShipCode should use for a fresh worktree.
• A project can declare how local env inputs should be made available to the worktree without ad hoc manual steps.
• ShipCode runs a clear preflight/setup step before execution or verification and fails fast with actionable output when setup is incomplete.
• The same contract works across desktop and CLI entry points.

Non-Goals

• Remote execution or hosted ephemeral environments.
• Secret management platforms, vault integration, or cloud secret syncing.
• Fully automatic language/framework inference without an explicit project contract.
• Replacing the user's normal local development workflow.

User Stories

• As a user starting a pipeline in a fresh worktree, I want ShipCode to prepare the workspace predictably so the agent does not burn retries on missing setup.
  Acceptance:
  • A newly created worktree runs a declared setup/preflight flow before execution starts.
  • Setup failures stop the run with an actionable reason.
• As a repo owner, I want to declare env and command expectations once so desktop and CLI behave the same way.
  Acceptance:
  • One repo-scoped contract is used by both entry points.
• As a verifier, I want to run the same declared commands every time so pass/fail reflects code quality, not environment drift.
  Acceptance:
  • Verification uses project-declared commands instead of hidden assumptions.

Functional Requirements

1. The system must allow a repo to declare setup, build, test, and verification commands for fresh worktrees.
2. The system must allow a repo to declare which local env files or env inputs should be propagated into the worktree and under what rules.
3. The system must run the declared setup / preflight stage before execution and before verification when required.
4. The system must surface setup progress and setup failure reasons in the same task surfaces used for pipeline progress.
5. The system must use the repo-scoped contract consistently from desktop and CLI flows.
6. The system must distinguish setup failures from code failures so retries and triage stay honest.
7. The system must support repos that choose not to declare optional setup steps by falling back to current behavior with clear messaging.

Non-Functional Requirements

• Setup semantics must be explicit and deterministic rather than inferred from incidental files.
• Failure messages must be short and actionable so users know whether the fix belongs in repo config, local env, or generated artifacts.
• The contract must be simple enough for single-repo adoption without turning into a full CI platform.

Success Criteria

• A repo can declare fresh-worktree setup and verification commands in one place.
• A new worktree either becomes runnable through the declared setup flow or fails with an explicit setup-state error before execution begins.
• Desktop and CLI use the same repo-scoped setup contract for the same repo.
• Verification failures caused by missing env/setup can be distinguished from failures caused by the code diff.

Out of Scope

• SSH / remote runners.
• Cross-machine secret distribution.
• Automatic Docker/devcontainer management.
• General-purpose task runner replacement.

Dependencies

• Existing worktree creation and cleanup flow.
• Existing settings for build/test commands where applicable.
• Repo-scoped file-backed configuration / skill-loading infrastructure.

Verification Plan

• tests: unit tests for repo contract loading and env propagation rules; pipeline tests covering setup-success, setup-fail, and verify-after-setup paths.
• manual: configure a repo that requires env + setup, start a fresh pipeline, verify setup runs before execution; break setup intentionally and confirm the task fails with setup-specific diagnostics.

Risks & Open Questions

• Env propagation is easy to make unsafe or too magical; the contract needs explicit rules.
• Some repos require generated assets or services that may not fit a minimal first version.
• Backward compatibility with existing per-setting commands needs a clear precedence rule.

[VincentShipsIt]

Closing as implemented on develop. Repos can define .shipcode/setup.json with setupCommands, verifyCommands, envFiles, setupBeforeVerify, and testingContext; desktop project settings can detect/save the contract; pipeline runtime loads it, copies env files, runs setup before execute/verify as configured, and uses declared verification commands.