cluesmith/codev/porch

porch - Protocol Orchestrator

Porch manages the state machine behind development protocols. It tracks phases, gates, consultations, and transitions.

Commands

porch status [id]              Show current project state and phase
porch run [id]                 Run the protocol loop (strict mode)
porch next [id]                Get next tasks as JSON
porch done [id]                Signal current phase is complete
porch check [id]               Run checks for current phase
porch gate [id]                Request human approval at a gate
porch approve <id> <gate> --a-human-explicitly-approved-this
porch rollback <id> <phase>    Rewind to an earlier phase
porch init <protocol> <id> <name>   Initialize a new project

Project ID auto-detects from worktree path when inside a builder worktree.

Gate approvals

Gates are human-only approval checkpoints. The --a-human-explicitly-approved-this flag is required — it exists to prevent AI agents from auto-approving.

porch approve 42 spec-approval --a-human-explicitly-approved-this
porch approve 42 plan-approval --a-human-explicitly-approved-this
porch approve 42 pr --a-human-explicitly-approved-this

ASPIR and BUGFIX have no spec/plan gates — they run autonomously through those phases.

Checking pending gates

porch pending                  # List all gates waiting for approval
porch pending --all            # Include stale records on finished/advanced projects (hidden by default)

Critical rules

• Builders must NEVER call `porch approve` — only humans approve gates
• Never edit `status.yaml` directly — porch manages all state
• Builders signal completion with porch done, not porch approve
• porch run is for strict mode only — soft mode builders follow the protocol document manually
• When running porch approve from the architect, use a subshell if you need worktree context: (cd /path/to/worktree && porch approve ...)

Check overrides and timeouts (porch.checks)

Override a protocol check per name in .codev/config.json under porch.checks instead of forking protocol.json. Each entry takes command (replace), cwd (replace), timeout_ms (replace), and/or skip: true:

{
  "porch": {
    "checks": {
      "tests":     { "command": "uv run pytest", "timeout_ms": 900000 },
      "e2e_tests": { "skip": true }
    }
  }
}

A phase check is killed after 5 minutes unless it sets timeout_ms — in protocol.json or in its porch.checks override. On timeout porch kills the check's whole process tree.

State storage

Project state lives in codev/projects/<id>-<name>/status.yaml, managed automatically by porch. The status file tracks current phase, gate states, consultation results, and timestamps.