Define Deployer operator contract and documentation for policy-controlled lane-aware promotion, acceptance, and proof of release

[fujiwaranosai850]

We have aligned on a clearer contract for making the DevClaw Deployer actually usable, starting from DevClaw itself as the first concrete project.

This issue tracks the operator-facing documentation/manual layer for that contract.

Leaf relationship:

• leaf of Implement first-class delivery phases for candidate promotion, acceptance, and demotion semantics #218 for operator-manual documentation and contract clarification work
• remains under root delivery-phase effort Design and implement first-class delivery phases for promoted candidates, acceptance, and rollback semantics #216
• informed by architect/design work in Research: #216 first-class delivery phases for promoted candidates, acceptance, and rollback semantics #217

Why this issue exists

The architect/design work in #217 and the delivery-phase implementation work in #218 established important structure:

• release/delivery is not just more testing
• promotion, acceptance, and rollback/demotion are first-class concepts
• project-specific deploy mechanics should not be hardcoded into core

What this issue adds is the operator-facing manual for how the Deployer works and is configured.

Operator contract

1. Release initiation is policy-controlled

Release must not automatically begin just because implementation/review completed.

Like PR handling, promotion may be human-initiated or agent-initiated depending on project policy.

2. Promotion is lane-aware, not a generic "release now"

Promotion means moving a candidate from one named lane/environment to another.

Important:

• lane/environment names are operator-configurable per project
• this lives in project definition/config, not only in prompts
• DevClaw core must not hardcode names like dev, staging, or production

3. Projects define release lanes/environments structurally

The Deployer reads project-defined lanes/environments from config.

Prompts can explain behavior, but prompts are not the sole source of truth for:

• available lanes/environments
• allowed promotion paths
• release semantics

4. Prompt surface for release work

Release work uses a dedicated deployer.md prompt surface:

• workspace default: devclaw/prompts/deployer.md
• project override: devclaw/projects/<project>/prompts/deployer.md

That prompt carries release-execution behavior. It does not replace workflow/config and runbooks as the source of truth for:

• lane definitions
• routing policy
• allowed promotion paths
• proof requirements

5. Candidate identity is explicit

A promotion is tied to an exact candidate identity, such as:

• commit SHA
• PR URL
• branch
• tag/version/build identifier if relevant

6. Proof of release is part of the contract

The Deployer proves that it released the intended version.

Minimum proof includes:

• source candidate identity
• source lane
• target lane
• resulting target identity/state
• verification evidence that destination matches the intended candidate

Core principle:
prove source identity, prove destination identity, prove they match the intended promotion.

7. Acceptance has its own contract

Acceptance defines:

• who accepts a promoted candidate
• what acceptance means
• what evidence is required
• what outcomes are possible

8. Rollback/demotion is explicit

The contract defines behavior for:

• invalidating a promoted candidate
• moving work back when acceptance fails
• preserving evidence that the candidate was demoted/rolled back

9. Preconditions and repeat behavior matter

The contract defines:

• what must already be true before promotion is allowed
• what should happen on repeated promotion attempts
  • no-op
  • retry
  • replace candidate
  • require override

Documentation sweep scope

This pass explicitly walked the repo Markdown documentation set, including root docs, docs/, docs/exploratory/, dev/, and defaults docs/templates, then patched the places that define or imply the final worker, prompt, and Deployer shape.

Documentation updated under this issue

The following docs were updated on devclaw-local-dev as part of this documentation pass:

• README.md
• defaults/AGENTS.md
• dev/design/deployer-contract.md
• dev/runbooks/developing-devclaw-with-openclaw.md
• docs/ARCHITECTURE.md
• docs/CONFIGURATION.md
• docs/ONBOARDING.md
• docs/REQUIREMENTS.md
• docs/WORKFLOW.md
• docs/exploratory/CONTROL-LAYER.md
• lib/tools/admin/workflow-guide.ts

Working checklist

• Write operator-manual Deployer contract doc
• Update workflow doc with delivery/release graph
• Update configuration doc with Deployer config framing
• Update workflow-guide text to match the Deployer contract
• Update control-layer doc with delivery controls
• Point the DevClaw local runbook at the generic Deployer contract doc
• Document deployer.md as a first-class prompt file in the prompt trees and role surfaces
• Sweep operator docs for places that define role prompts or worker roles and align them with the intended Deployer prompt surface
• Correct stale prompt-loading wording where docs still implied task-message appends instead of bootstrap-hook injection
• Review docs for remaining wording mismatches
• Implement code to conform fully to the documented operator manual

Relationship to existing issues

• Design and implement first-class delivery phases for promoted candidates, acceptance, and rollback semantics #216 root delivery-phase effort
• Research: #216 first-class delivery phases for promoted candidates, acceptance, and rollback semantics #217 architect/design guidance
• Implement first-class delivery phases for candidate promotion, acceptance, and demotion semantics #218 first-class delivery-phase implementation and immediate parent/leaf anchor for this operator-doc follow-up

This issue is specifically about the operator-usable Deployer contract and documentation needed to make those delivery phases practical.

[fujiwaranosai850]

🎛️ ORCHESTRATOR: We aligned further on the acceptance contract for the release agent.

Agreed direction

Acceptance should be candidate-specific

Acceptance should apply to a specific promoted candidate, not to the issue in general.

Acceptance authority should be configurable

Who can accept should be configurable per project and/or per lane.

Acceptance should require evidence

Acceptance should require proof/evidence rather than being a vague state change.

Acceptance outcomes should be explicit

We want explicit outcomes such as:

• accept
• reject
• refine
• blocked

Reject should invalidate the candidate

Rejecting acceptance should invalidate the specific promoted candidate, not just vaguely reopen the issue.

Acceptance should record provenance

Acceptance records should capture:

• who accepted what
• where
• based on what evidence

Default-vs-configurable decision

We want the same strong defaults across projects, while making them easy to override per project.

Suggested default acceptance criteria

Default acceptance criteria should include:

• candidate identity present
• source lane and target lane recorded
• proof of target state present
• required checks/evidence attached
• accepter identity recorded
• explicit outcome recorded

Project-configurable overrides

Projects should be able to override:

• who can accept
• required evidence
• required checks
• allowed outcomes
• per-lane rules

Summary

The guiding principle is:
strong shared defaults, easy per-project overrides.

[fujiwaranosai850]

📝 Issue updated at 2026-05-09T06:53:07.613Z

• Title updated
• Description updated
• Reason: Track the actual documentation updates, correct initiation semantics, and make the leaf relationship to Implement first-class delivery phases for candidate promotion, acceptance, and demotion semantics #218 explicit.

[fujiwaranosai850]

📝 Issue updated at 2026-05-09T07:02:43.156Z

• Description updated
• Reason: Add the missing release-agent prompt mapping and include all operator docs updated in this documentation sweep.

[fujiwaranosai850]

📝 Issue updated at 2026-05-09T07:07:44.878Z

• Description updated
• Reason: Record that the sweep covered the full repo Markdown docs and include the final prompt-surface fixes.

[fujiwaranosai850]

📝 Issue updated at 2026-05-09T07:24:35.058Z

• Description updated
• Reason: Correct the design direction so the docs and tracking issue target a dedicated release.md prompt surface.

[fujiwaranosai850]

📝 Issue updated at 2026-05-09T07:30:04.038Z

• Description updated
• Reason: Replace vague release prompt wording with the actual final release.md tree and override paths.

[fujiwaranosai850]

📝 Issue updated at 2026-05-09T07:33:58.491Z

• Title updated
• Description updated
• Reason: Rename the release agent to Deployer across the tracking issue and prompt-file paths.

[fujiwaranosai850]

🎛️ ORCHESTRATOR: Added the actual default Deployer prompt implementation artifact on devclaw-local-dev:

• defaults/devclaw/prompts/deployer.md
• lib/setup/templates.ts updated to load and expose the default Deployer prompt

This brings the repo closer to the documented final shape where deployer.md exists as a first-class default prompt file.