Design deployer config surface so lane/source/target/evidence can be resolved without prompt-specific knowledge

[fujiwaranosai850]

Problem

The Deployer role currently needs too much prompt-specific or repo-specific wording to understand what lane move it is performing.

For example, a deploy target like:

• branch main
• URL https://sai.yaq.rip/firstlight/

may semantically mean:

• production
• dev
• main/dev
• or another project-defined lane name

Right now that meaning can drift between prompts, runbooks, issue comments, and human memory.

The Deployer should be able to resolve the required lane/source/target/evidence information from config, without needing prompt-specific lane lore.

Goal

Define a deployer-facing config surface that lets the Deployer determine, from config alone:

• what source lane/candidate it is deploying from
• what target lane it is deploying to
• what human-readable lane names/aliases should be reported
• what URL/surface is the verification target
• what evidence fields are required
• what transitions are allowed
• what command/runbook entrypoint should be used

Prompts should only say "read config and follow runbook", not encode project-specific lane semantics.

What the Deployer needs from config

1. Source definition

The Deployer needs to know how to interpret the source side of a deployment request.

Possible config fields:

• source selector type
  • defaultBranch
  • branch
  • pr
  • tag
  • directory
  • explicitCandidate
• default branch name
• whether branch-based preview deploys are allowed
• how candidate identity should be rendered in receipts

2. Target lane definition

The Deployer needs a first-class target lane object, not just a URL.

Possible fields per lane:

• machine key, for example dev, preview, staging, production
• display name
• optional aliases, for example:
  • main/dev
  • prod
  • qa
• target public URL
• optional local-served URL/origin
• target kind, for example:
  • preview
  • persistent
  • promotion
  • acceptance

3. Source -> target mapping rules

The Deployer needs to know which source forms map to which lane targets.

Possible fields:

• defaultBranch -> dev
• branch/* -> preview
• tag/* -> production
• allowed transitions list
• optional transition alias, for example:
  • main->dev
  • preview->prod
  • candidate->acceptance

This would let the Deployer report both:

• source lane
• target lane
• lane-pair alias when one exists

4. Command / execution entrypoint

The Deployer should know which canonical command to run for a given transition.

Possible fields:

• script path
• argument template per transition
• whether push is allowed/required
• whether the deploy path is local-first
• whether fallback paths are allowed

Example need:

• defaultBranch -> dev uses tools/project_chat_release.sh --main
• branch -> preview uses tools/project_chat_release.sh --branch <name>

5. Verification surface mapping

The Deployer needs to know what exact surface must be handed back for verification.

Possible fields:

• app surface URL template
• harness surface URL template
• runtime-qualified URL template if applicable
• whether preview or persistent target is expected
• which target is the acceptance surface vs auxiliary surface

6. Evidence / receipt requirements

The Deployer needs a config-declared evidence contract.

Possible fields:

• required output fields to preserve in the receipt
• required proof files
• required gate statuses
• whether exact field names must be preserved verbatim
• whether the lane is considered complete only after certain checks pass

7. Candidate identity contract

The Deployer should know how to describe the candidate being moved.

Possible fields:

• branch name
• commit SHA
• PR number
• tag
• source directory hash or release id
• source lane identity label

This matters because the Deployer should never have to guess what the candidate identity is.

8. Preconditions and policy

The Deployer needs config for the policy side too.

Possible fields:

• approvals required
• review required
• merged-required vs preview-allowed
• test-required before deploy
• whether human initiation is required or policy-controlled
• whether fallback modes are allowed

9. Rollback / demotion support

If Deployer is a real lane actor, config should also describe rollback-capable transitions.

Possible fields:

• allowed rollback targets
• required evidence for rollback
• target identity rules for demotion
• whether rollback uses a different command template

Design options

Option A: extend config/publish.json

Pros:

• closest to current publish surface
• keeps deploy-surface mapping with URLs and script entrypoints

Cons:

• may become overloaded if it also has workflow/policy concepts

Option B: add a dedicated deployer config block in workflow/project config

For example a deployment or releaseLanes section.

Pros:

• cleaner home for lane names, transitions, policy, and evidence rules
• easier to share across projects with different deploy models

Cons:

• may duplicate some publish-surface fields unless references are structured cleanly

Option C: split surface config from lane-policy config

For example:

• config/publish.json for concrete URLs, scripts, and serving surfaces
• workflow/deployer config for lane names, transitions, aliases, policy, and evidence requirements

Pros:

• likely the cleanest long-term separation
• deployer can resolve both semantics and mechanics without prompt-specific wording

Cons:

• slightly more config plumbing

Current recommendation

I think Option C is the strongest shape:

• keep deploy mechanics/surfaces in publish config
• add first-class lane semantics/policy/aliases in deployer/workflow config
• make the Deployer resolve source lane, target lane, transition alias, command template, and evidence contract from config

Minimum capability set I think is needed

At minimum, the Deployer should be able to read from config:

1. source selector type and candidate identity rules
2. target lane key and display name
3. optional target aliases
4. source->target mapping rules
5. canonical command template per mapping
6. verification surface templates
7. required evidence fields
8. preconditions/policy flags
9. rollback/demotion mapping

Why this matters

Without this, the Deployer stays partly prompt-driven.
That means the same deploy target can be described inconsistently across:

• prompts
• runbooks
• issues
• operator comments
• worker receipts

The config should be the single source of truth for deploy lane semantics.