Implement canonical issue checkout contract and worktree lifecycle enforcement

[fujiwaranosai850]

From research #173

Overview

Make DevClaw treat checkout identity as a first-class contract instead of loose prompt guidance.

Under the revised local branch model:

• devclaw-local-dev is the normal DevClaw project branch for day-to-day implementation work
• normal issue work should create a persisted canonical issue/<issue-id>-<slug> branch/worktree derived from devclaw-local-dev
• developers should PR issue/* back into devclaw-local-dev
• the operator/orchestrator manages the release cycle from devclaw-local-dev into devclaw-local-current
• devclaw-local-current remains the operator-managed local-truth / release branch, not the normal implementation base

The implementation must preserve intentional exceptions for local review (review/*), upstream export (pr/*), and live self-hosting / release flows that operate outside ordinary issue worktrees.

Implementation Checklist

Phase 1: Model the canonical checkout contract in state and dispatch (~1.5 days)

• Extend the worker/project state schema in lib/projects/types.ts and any related IO/migration code to persist per-issue checkout contract data: mode, repo path, canonical branch, canonical worktree path, base branch/base worktree, target ref, target SHA, cleanliness requirements, status, and last verified provenance.
• Add a helper/service layer for resolving the expected normal-issue contract from devclaw-local-dev into issue/<issue-id>-<slug> branches, while allowing explicit alternate modes for review/*, pr/*, and live self-hosting / release flows.
• Update lib/dispatch/index.ts so dispatch creates or attaches the issue checkout contract before sending work, and passes the canonical path/branch metadata into worker task context rather than only targetRef/targetSha.
• Update lib/dispatch/message-builder.ts and its tests in lib/dispatch/message-builder.test.ts to render the canonical checkout details and the distinction between required canonical checkout and allowed derived validation checkout.

Phase 2: Enforce checkout identity at worker startup and completion (~2 days)

• Add worker-start validation in the dispatch/bootstrap path, likely via lib/dispatch/bootstrap-hook.ts plus a new checkout-validation helper, so normal developer tasks must adopt or create the canonical issue/* worktree before proceeding.
• Add decisive-verdict validation for reviewer/tester and developer completion in lib/tools/worker/work-finish.ts: reject definitive done / approve / reject / pass / fail if recorded provenance does not match the expected contract or cleanliness rules.
• Align developer completion with the revised branch model: for DevClaw implementation work, work_finish(done) should be satisfied by a clean pushed implementation branch plus an open PR into devclaw-local-dev, while release/promotion PRs into devclaw-local-current remain orchestrator-owned.
• Add a clear recoverable failure mode for missing/dirty/mismatched normal issue worktrees: deterministic repair when safe, otherwise explicit blocked guidance rather than silent drift into the shared checkout.
• Ensure PR-feedback flows in lib/dispatch/pr-context.ts and related dispatch code preserve canonical checkout identity instead of relying on PR branch name alone.

Phase 3: Surface observability and align docs/prompts with the local policy (~1.5 days)

• Expose checkout-contract status in operator-facing state/health surfaces so the orchestrator can see whether an issue worktree is planned, created, adopted, missing, dirty, mismatched, or verified.
• Align prompt coverage: update defaults/devclaw/prompts/developer.md, defaults/devclaw/prompts/reviewer.md, and defaults/devclaw/prompts/tester.md, and add/adjust DevClaw project-specific overrides under /home/sai/.openclaw/workspace/devclaw/projects/devclaw/prompts/ so all worker roles share the same branch/worktree contract.
• Resolve naming/documentation drift between generic feature/* examples and DevClaw’s required issue/* local policy, and update local branch-role docs to distinguish clearly between devclaw-local-dev (project branch) and devclaw-local-current (operator-managed release branch).
• Update docs/devclaw-self-hosting.md and dev/runbooks/developing-devclaw-with-openclaw.md to document the enforcement boundary: ordinary issue work from devclaw-local-dev vs. release/promotion flows into devclaw-local-current, plus the review/*, pr/*, and live self-hosting exception modes.
• Add tests covering schema migration, dispatch contract generation, worker-start enforcement, completion rejection on mismatched provenance, completion acceptance for the DevClaw implementation-PR path, and exception-mode compatibility.

Dependencies & Blockers

• Must preserve DevClaw’s intentional separation between devclaw-local-dev for implementation work and devclaw-local-current for operator-managed release/local truth.
• Must keep release/promotion ownership with the operator/orchestrator: developers target devclaw-local-dev; release packaging into devclaw-local-current stays outside the normal implementation lane.
• Must not force live self-hosting or release/promotion tasks into the ordinary issue-worktree contract; those need explicit alternate modes.
• Existing live prompt/config overrides under /home/sai/.openclaw/workspace/devclaw/projects/devclaw/prompts/ need to be treated as real runtime inputs, not assumed to match repo defaults.

Estimated Total: 4-6 days

[fujiwaranosai850]

Family tracking note:

• Root family issue: Workers can validate different checkouts and silently disagree on build/test results #171 Workers can validate different checkouts and silently disagree on build/test results
• Research predecessor: Research: canonical issue worktree and checkout contract hardening for DevClaw #173 Research: canonical issue worktree and checkout contract hardening for DevClaw
• This issue (Implement canonical issue checkout contract and worktree lifecycle enforcement #174) is the implementation child for that root bug family

Use #171 as the canonical problem tracker. Keep #174 focused on implementation of the agreed hardening plan.