design-strong-agent — WorksGood live mirror

Metadata

Status	done
Assigned	`agent-900`
Created	2026-07-26T11:59:55.017774827+00:00
Started	2026-07-26T21:01:07.043280971+00:00
Completed	2026-07-26T21:21:01.647298170+00:00
Tokens	2421315 in / 23058 out

Description

Objective

Produce the implementation-ready design for the escalation seam between immutable candidate finalization and central merge acceptance. WG performs only a provably mechanical integration. Every real textual or semantic integration conflict is either resolved by one explicitly routed full strong coding agent or stopped for a content-bound human decision; the coordinator, evaluator, and weak tier never guess. Explain the rationale for every authority and classifier boundary.

Produce docs/design-strong-agent-merge-resolution.md; no production code changes.

Inputs, ownership, and non-overlap

Consume docs/design-candidate-finalization-transaction.md and docs/design-pi-evaluation-plane.md rather than defining parallel candidate, lifecycle, evaluator, or merge authorities. The input is an immutable CandidateDescriptor plus accepted validation/evaluation evidence, an immutable target-head snapshot, and the candidate finalizer's merge-attempt receipt. The source candidate/worktree and canonical main ref remain immutable throughout resolution. The lifecycle kernel remains the only status authority, the finalizer owns candidate versions, evaluators remain read-only, and only the central merge authority may CAS main after acceptance.

Normative decision table

Define stable reason codes and mutually exclusive evidence requirements for at least these outcomes:

MechanicalMerge: a credential-free dry run at the pinned candidate/base/target commits produces one deterministic conflict-free merge tree; neither side introduces unresolved markers, generated/policy ownership ambiguity, or an unaccepted content-safety finding; all required integration checks pass; and the target head still matches the snapshot. This path makes zero model calls.
CandidateRepairRequired: the immutable candidate fails its own pre-integration deterministic validation. This is source repair, not merge resolution and not a semantic conflict.
MergeResolutionRequired::TextualConflict: Git overlap, add/add, rename/delete, modify/delete, submodule/dependency-lock interaction, or another non-clean textual merge. No coordinator-side conflict-marker edit is allowed.
MergeResolutionRequired::SemanticIntegrationConflict: candidate and target pass their pinned checks independently, a textual merge is clean, but the combined tree fails a required compile/test/schema/API/invariant check. Preserve the failing command and both independent baselines so ordinary candidate breakage cannot be mislabeled semantic integration.
MergeResolutionRequired::GeneratedArtifactConflict only when source-of-truth ownership and a deterministic, pinned regeneration command/toolchain are known. The merger edits source inputs and regenerates; it never hand-edits generated output. Missing ownership, nondeterministic/unavailable generation, or disagreement about which generated form is authoritative becomes NeedsHumanMergeDecision::GeneratedIntentAmbiguous.
NeedsHumanMergeDecision: product/user intent is ambiguous, both behaviors are plausible, requirements conflict, a policy-sensitive choice requires human authority, or the merger reports insufficient evidence. A model may identify ambiguity but may not invent the decision.
SecurityReviewBlocked / ResolutionRejected: untrusted or malicious diff/conflict text is data, never instruction. Deterministic lint and the canonical inbound-content review gate run before agent exposure; reject/quarantine/hard findings do not launch a merger. Accepted-but-untrusted material is spotlighted and least-privilege framed, cannot change route/tools/policy, and the merger output is scanned again. Neither merger nor evaluator can downgrade a safety verdict.

Specify precedence: safety block and candidate-invalid outcomes win before resolution; human-required policy/intent ambiguity wins over model resolution; only the fully proven clean case is mechanical; all unknown/unlabeled classifier states fail closed without mutating main. Policy-only integration failures must not be disguised as Git cleanliness.

Explicit strong route and capability contract

Define a persisted ResolutionRouteSnapshot containing a fully qualified handler-first model spec, provider/model identity, declared strong/premium class, high or xhigh reasoning, config/profile revision, budget, tool policy, and route provenance. models.merger should name the exact route; if policy permits a named strong/premium tier alias, resolve it once to one exact spec before enqueue and persist it. Missing/weak/invalid routes, unavailable executors, auth errors, unsupported reasoning, timeout, or budget exhaustion enter a visible StrongRouteUnavailable/operator hold. There is no weak-tier downgrade, no provider/model substitution, no cross-executor fallback, and no conversion to a mechanical merge. An operator route change creates a new snapshotted run generation and audit event rather than mutating an in-flight request.

The strong merger has full coding/test capability only inside a dedicated isolated integration clone/worktree materialized from the exact target snapshot and candidate objects. It has no canonical repository .git/main path, ref-update socket, push credential, graph/lifecycle mutation tool, evaluator authority, or source-candidate write capability. Repository tools, dependency installation, and tests are allowed under bounded policy inside that workspace. Explain why an ordinary linked worktree with writable shared refs is insufficient unless ref mutation is mechanically sandboxed.

Content-bound resolution transaction

Specify a replayable, append-only state/outbox protocol such as: Classifying -> MechanicalPending | ResolutionRequired | HumanDecisionRequired | SecurityBlocked -> StrongRouteResolved -> IntegrationWorkspaceReady -> Resolving -> ResolutionCandidateSealed -> SafetyReview -> Revalidating -> Reevaluating -> AcceptancePending -> Merged | ResolutionRejected | HumanDecisionRequired | RouteUnavailable. Map every projection to the authoritative lifecycle/finalizer states; do not add a second task-status writer.

Derive a stable request/idempotency key from candidate commit/tree/manifest CID, base, target-head commit/tree, conflict/evidence bundle digest, policy snapshot, and route snapshot. Lazily create exactly one run only after a real conflict classification; clean merges create no resolution work or graph clutter.
Give the merger a content-addressed, spotlighted bundle containing original task/user intent, immutable source candidate, merge base, target snapshot, both diffs, dependency/generated-file metadata, validation/evaluation evidence, conflict map, applicable policies, and repository tools. Pin every referenced object; paths/branch names alone are not identity.
Seal merger output as a new immutable ResolutionCandidateDescriptor: request/run/session and route provenance; parent candidate/base/target IDs; commit/tree and canonical manifest CID; changed-file/conflict disposition; generator commands/toolchain/output digests; tests/tool evidence; safety evidence; explanation; and explicit resolved, reject, or needs_human outcome. It never rewrites or retags the source candidate.
Treat all modified/resolved bytes as new untrusted candidate bytes. Run canonical safety review, deterministic validation, and the policy-selected bounded evaluation/deep-readonly FLIP anew against the resolution descriptor. Original-candidate verdicts are evidence only and cannot authorize changed bytes. Rejection retains both candidates and creates a linked repair/new version.
The central merge authority alone accepts. It verifies all bindings, requires canonical target head to equal the snapshotted target, imports/applies exactly the accepted resolution tree, atomically CASes the main ref, and records one merge receipt keyed by request/resolution CID/target with input and resulting tree digests. The merged tree must equal the accepted resolution tree under the design's documented tree comparison; duplicate delivery/restart returns the same receipt. Target movement makes the resolution stale and triggers reclassification against a new target snapshot, never an automatic rebase or stale merge.
Define crash barriers and replay at classify, route resolution, workspace creation, process start/exit, candidate seal, each safety/validation/evaluation request/result, acceptance, CAS, receipt, and cleanup. Workspace cleanup is ancillary; unknown/source-bearing/unaccepted objects are retained fail closed.

Human decision, rejection, rollback, and operations

A human decision record is bound to the candidate/target/evidence digests and records author, decision, rationale, and constraints. resume creates a new resolution generation/candidate; human approval does not bypass safety, validation, fresh evaluation, target-head CAS, or content equality. Budget exhaustion, repeated invalid output, unresolved generated ownership, route unavailability, and ambiguous intent expose explicit inspect/retry/change-route/reject/escalate actions.

Before acceptance, abort/reject only releases the integration workspace after immutable evidence retention and leaves main/source untouched. After acceptance, rollback is a new auditable compensating candidate/commit through the same validation/evaluation/merge authority; never silently reset main or erase the original receipt. Specify CLI/TUI status showing classifier reason/evidence, candidate+target IDs, route strength/provenance, session/run, workspace isolation, resolution CID, gates, receipt, retained artifacts, and safe next action.

RED-first and live-flow design

Design credential-free tests before implementation, including a deterministic fake strong-merger adapter that asserts the exact strong route/reasoning/tool policy and records call count.

Unit/model/property fixtures distinguish clean merge (zero calls), candidate-invalid, textual conflict (one call), clean semantic integration failure where each side passes alone (one call), deterministic generated regeneration, ambiguous generated ownership (human), ambiguous intent (human), and malicious/untrusted conflict text (review block or contained data, never route/tool override).
Failure/replay fixtures cover route absent/weak/unavailable with no fallback, malformed/timeout/budgeted merger output, rejection and repair, duplicate requests/verdicts, daemon restart at every boundary, concurrent target movement, stale route/config, attempted source/main/ref mutation, and post-checkpoint workspace mutation.
A real installed-wg + real daemon/service + real source and isolated integration worktree terminal flow (fake merger only for credentials) must first fail before implementation and demonstrate: clean merge with zero LLM calls; conflict -> explicit strong route -> resolution -> safety review -> deterministic revalidation -> fresh evaluation -> exactly-once merge of identical bytes; conflict -> human stop; rejection/repair; restart; target movement; explicit compensating rollback. Require a grow-only smoke scenario owned by implement-strong-agent, not a helper/library-only substitute.

File-level seams and rollout

Name the exact Rust modules/types, persistence schema/migration, outbox keys, handler/route resolver, sandbox/worktree boundary, validator/evaluator hooks, merge-authority CAS, CLI/TUI surfaces, fake adapter, tests, and smoke manifest entry to change. Roll out disabled, then observe classifier-only/advisory metrics before enabling strong runs; the mechanical path must remain byte-for-byte independent of model availability. Identify schema compatibility and recovery for partially recorded legacy conflicts.

Validation

Decision table deterministically distinguishes clean merge, candidate-invalid, textual conflict, semantic integration failure, generated-file conflict/ambiguity, product ambiguity, policy-sensitive choice, and malicious/untrusted diff.
Clean merges make zero model calls; only one fully qualified snapshotted strong route may run, and missing/unavailable/weak routes hold visibly with no fallback.
Merger capabilities are confined to an isolated integration worktree; canonical main, source candidate/worktree, graph, and shared refs remain immutable until central acceptance.
Resolution bytes receive a new immutable descriptor and fresh safety review, deterministic validation, and policy-selected evaluation/FLIP; accepted descriptor tree equals the exactly-once merged tree.
Target movement, crash/replay, duplicate delivery, rejection/repair, human escalation, retention, and compensating rollback are explicit and content bound.
RED-first credential-free fake-merger fixtures and the real installed-binary daemon/integration-worktree human flow are implementation-ready; file seams, migration, rollout, and permanent smoke ownership are explicit.

## Objective
Produce the implementation-ready design for the escalation seam between immutable candidate finalization and central merge acceptance. WG performs only a provably mechanical integration. Every real textual or semantic integration conflict is either resolved by one explicitly routed full strong coding agent or stopped for a content-bound human decision; the coordinator, evaluator, and weak tier never guess. Explain the rationale for every authority and classifier boundary.

Produce `docs/design-strong-agent-merge-resolution.md`; no production code changes.

## Inputs, ownership, and non-overlap
Consume `docs/design-candidate-finalization-transaction.md` and `docs/design-pi-evaluation-plane.md` rather than defining parallel candidate, lifecycle, evaluator, or merge authorities. The input is an immutable `CandidateDescriptor` plus accepted validation/evaluation evidence, an immutable target-head snapshot, and the candidate finalizer's merge-attempt receipt. The source candidate/worktree and canonical main ref remain immutable throughout resolution. The lifecycle kernel remains the only status authority, the finalizer owns candidate versions, evaluators remain read-only, and only the central merge authority may CAS main after acceptance.

## Normative decision table
Define stable reason codes and mutually exclusive evidence requirements for at least these outcomes:

1. **`MechanicalMerge`**: a credential-free dry run at the pinned candidate/base/target commits produces one deterministic conflict-free merge tree; neither side introduces unresolved markers, generated/policy ownership ambiguity, or an unaccepted content-safety finding; all required integration checks pass; and the target head still matches the snapshot. This path makes **zero model calls**.
2. **`CandidateRepairRequired`**: the immutable candidate fails its own pre-integration deterministic validation. This is source repair, not merge resolution and not a semantic conflict.
3. **`MergeResolutionRequired::TextualConflict`**: Git overlap, add/add, rename/delete, modify/delete, submodule/dependency-lock interaction, or another non-clean textual merge. No coordinator-side conflict-marker edit is allowed.
4. **`MergeResolutionRequired::SemanticIntegrationConflict`**: candidate and target pass their pinned checks independently, a textual merge is clean, but the combined tree fails a required compile/test/schema/API/invariant check. Preserve the failing command and both independent baselines so ordinary candidate breakage cannot be mislabeled semantic integration.
5. **`MergeResolutionRequired::GeneratedArtifactConflict`** only when source-of-truth ownership and a deterministic, pinned regeneration command/toolchain are known. The merger edits source inputs and regenerates; it never hand-edits generated output. Missing ownership, nondeterministic/unavailable generation, or disagreement about which generated form is authoritative becomes `NeedsHumanMergeDecision::GeneratedIntentAmbiguous`.
6. **`NeedsHumanMergeDecision`**: product/user intent is ambiguous, both behaviors are plausible, requirements conflict, a policy-sensitive choice requires human authority, or the merger reports insufficient evidence. A model may identify ambiguity but may not invent the decision.
7. **`SecurityReviewBlocked` / `ResolutionRejected`**: untrusted or malicious diff/conflict text is data, never instruction. Deterministic lint and the canonical inbound-content review gate run before agent exposure; reject/quarantine/hard findings do not launch a merger. Accepted-but-untrusted material is spotlighted and least-privilege framed, cannot change route/tools/policy, and the merger output is scanned again. Neither merger nor evaluator can downgrade a safety verdict.

## Explicit strong route and capability contract
Define a persisted `ResolutionRouteSnapshot` containing a fully qualified handler-first model spec, provider/model identity, declared strong/premium class, high or xhigh reasoning, config/profile revision, budget, tool policy, and route provenance. `models.merger` should name the exact route; if policy permits a named strong/premium tier alias, resolve it once to one exact spec before enqueue and persist it. Missing/weak/invalid routes, unavailable executors, auth errors, unsupported reasoning, timeout, or budget exhaustion enter a visible `StrongRouteUnavailable`/operator hold. There is no weak-tier downgrade, no provider/model substitution, no cross-executor fallback, and no conversion to a mechanical merge. An operator route change creates a new snapshotted run generation and audit event rather than mutating an in-flight request.

The strong merger has full coding/test capability only inside a dedicated **isolated integration clone/worktree** materialized from the exact target snapshot and candidate objects. It has no canonical repository `.git`/main path, ref-update socket, push credential, graph/lifecycle mutation tool, evaluator authority, or source-candidate write capability. Repository tools, dependency installation, and tests are allowed under bounded policy inside that workspace. Explain why an ordinary linked worktree with writable shared refs is insufficient unless ref mutation is mechanically sandboxed.

## Content-bound resolution transaction
Specify a replayable, append-only state/outbox protocol such as:
`Classifying -> MechanicalPending | ResolutionRequired | HumanDecisionRequired | SecurityBlocked -> StrongRouteResolved -> IntegrationWorkspaceReady -> Resolving -> ResolutionCandidateSealed -> SafetyReview -> Revalidating -> Reevaluating -> AcceptancePending -> Merged | ResolutionRejected | HumanDecisionRequired | RouteUnavailable`.
Map every projection to the authoritative lifecycle/finalizer states; do not add a second task-status writer.

- Derive a stable request/idempotency key from candidate commit/tree/manifest CID, base, target-head commit/tree, conflict/evidence bundle digest, policy snapshot, and route snapshot. Lazily create exactly one run only after a real conflict classification; clean merges create no resolution work or graph clutter.
- Give the merger a content-addressed, spotlighted bundle containing original task/user intent, immutable source candidate, merge base, target snapshot, both diffs, dependency/generated-file metadata, validation/evaluation evidence, conflict map, applicable policies, and repository tools. Pin every referenced object; paths/branch names alone are not identity.
- Seal merger output as a new immutable `ResolutionCandidateDescriptor`: request/run/session and route provenance; parent candidate/base/target IDs; commit/tree and canonical manifest CID; changed-file/conflict disposition; generator commands/toolchain/output digests; tests/tool evidence; safety evidence; explanation; and explicit `resolved`, `reject`, or `needs_human` outcome. It never rewrites or retags the source candidate.
- Treat all modified/resolved bytes as new untrusted candidate bytes. Run canonical safety review, deterministic validation, and the policy-selected bounded evaluation/deep-readonly FLIP anew against the resolution descriptor. Original-candidate verdicts are evidence only and cannot authorize changed bytes. Rejection retains both candidates and creates a linked repair/new version.
- The central merge authority alone accepts. It verifies all bindings, requires canonical target head to equal the snapshotted target, imports/applies exactly the accepted resolution tree, atomically CASes the main ref, and records one merge receipt keyed by request/resolution CID/target with input and resulting tree digests. The merged tree must equal the accepted resolution tree under the design's documented tree comparison; duplicate delivery/restart returns the same receipt. Target movement makes the resolution stale and triggers reclassification against a new target snapshot, never an automatic rebase or stale merge.
- Define crash barriers and replay at classify, route resolution, workspace creation, process start/exit, candidate seal, each safety/validation/evaluation request/result, acceptance, CAS, receipt, and cleanup. Workspace cleanup is ancillary; unknown/source-bearing/unaccepted objects are retained fail closed.

## Human decision, rejection, rollback, and operations
A human decision record is bound to the candidate/target/evidence digests and records author, decision, rationale, and constraints. `resume` creates a new resolution generation/candidate; human approval does not bypass safety, validation, fresh evaluation, target-head CAS, or content equality. Budget exhaustion, repeated invalid output, unresolved generated ownership, route unavailability, and ambiguous intent expose explicit inspect/retry/change-route/reject/escalate actions.

## RED-first and live-flow design
Design credential-free tests before implementation, including a deterministic fake strong-merger adapter that asserts the exact strong route/reasoning/tool policy and records call count.

- Unit/model/property fixtures distinguish clean merge (zero calls), candidate-invalid, textual conflict (one call), clean semantic integration failure where each side passes alone (one call), deterministic generated regeneration, ambiguous generated ownership (human), ambiguous intent (human), and malicious/untrusted conflict text (review block or contained data, never route/tool override).
- Failure/replay fixtures cover route absent/weak/unavailable with no fallback, malformed/timeout/budgeted merger output, rejection and repair, duplicate requests/verdicts, daemon restart at every boundary, concurrent target movement, stale route/config, attempted source/main/ref mutation, and post-checkpoint workspace mutation.
- A real installed-`wg` + real daemon/service + real source and isolated integration worktree terminal flow (fake merger only for credentials) must first fail before implementation and demonstrate: clean merge with zero LLM calls; conflict -> explicit strong route -> resolution -> safety review -> deterministic revalidation -> fresh evaluation -> exactly-once merge of identical bytes; conflict -> human stop; rejection/repair; restart; target movement; explicit compensating rollback. Require a grow-only smoke scenario owned by `implement-strong-agent`, not a helper/library-only substitute.

## File-level seams and rollout
Name the exact Rust modules/types, persistence schema/migration, outbox keys, handler/route resolver, sandbox/worktree boundary, validator/evaluator hooks, merge-authority CAS, CLI/TUI surfaces, fake adapter, tests, and smoke manifest entry to change. Roll out disabled, then observe classifier-only/advisory metrics before enabling strong runs; the mechanical path must remain byte-for-byte independent of model availability. Identify schema compatibility and recovery for partially recorded legacy conflicts.

## Validation
- [ ] Decision table deterministically distinguishes clean merge, candidate-invalid, textual conflict, semantic integration failure, generated-file conflict/ambiguity, product ambiguity, policy-sensitive choice, and malicious/untrusted diff.
- [ ] Clean merges make zero model calls; only one fully qualified snapshotted strong route may run, and missing/unavailable/weak routes hold visibly with no fallback.
- [ ] Merger capabilities are confined to an isolated integration worktree; canonical main, source candidate/worktree, graph, and shared refs remain immutable until central acceptance.
- [ ] Resolution bytes receive a new immutable descriptor and fresh safety review, deterministic validation, and policy-selected evaluation/FLIP; accepted descriptor tree equals the exactly-once merged tree.
- [ ] Target movement, crash/replay, duplicate delivery, rejection/repair, human escalation, retention, and compensating rollback are explicit and content bound.
- [ ] RED-first credential-free fake-merger fixtures and the real installed-binary daemon/integration-worktree human flow are implementation-ready; file seams, migration, rollout, and permanent smoke ownership are explicit.

Depends on

Required by

done implement-strong-agent

✉ Messages 2 messages (2 unread)

#1design-pi-evaluation2026-07-26T20:58:47.942495899+00:00delivered

Pi evaluation-plane design is ready at docs/design-pi-evaluation-plane.md (8cce460f). It defines the acceptance/evaluation boundary your merge-resolution design should preserve: one candidate digest/finalization round, evaluation appends evidence only, required gate waits in Finalizing, evaluator never reopens/rescues, and merge/repair must consume the same candidate-bound receipt.

#2design-strong-agent2026-07-26T21:01:15.731673127+00:00read

Acknowledged — I will preserve the Pi evaluation plane's candidate-bound read-only evidence contract and consume its receipt rather than introducing evaluator authority.

Log

2026-07-26T11:59:55.001012564+00:00 Task paused
2026-07-26T12:00:18.623511082+00:00 Task published
2026-07-26T21:00:52.746783758+00:00 Spawn preparation deferred before launch permit; rollback is complete and no circuit-breaker charge was recorded. Repair the reported checkout/configuration condition and retry: spawn transaction for agent-900 rolled back (task remains dispatchable; rollback diagnostics: complete): failed to establish isolated-worktree observer baseline: observer state already exists; use open_at for restart reconciliation
2026-07-26T21:01:07.207124951+00:00 Spawned by coordinator --executor pi --model openai-codex:gpt-5.6-sol --isolation required-worktree
2026-07-26T21:01:15.803331572+00:00 Starting design work; will inspect prior WIP and fully read the candidate-finalization and Pi evaluation-plane inputs before drafting.
2026-07-26T21:01:38.611096457+00:00 Read both normative input designs completely. Staying inline: one tightly coupled design file, and parallel subtasks would collide on the same document.
2026-07-26T21:13:51.636015172+00:00 Drafted implementation-ready design: authority/classifier table, exact strong route/no fallback, isolated standalone integration repository, append-only transaction, fresh descriptor gates, central tree-equality CAS, human/rollback operations, RED fixtures, live smoke, file seams and rollout.
2026-07-26T21:19:32.594331689+00:00 Validated task-specific checklist: mutually exclusive classifier/preference table; zero-call mechanical lane; exact no-fallback strong route; standalone clone isolation; immutable resolution descriptor with fresh review/validation/evaluation; complete-tree exactly-once CAS; target movement/replay/human/rejection/rollback; RED fake and installed-daemon/TUI flow; migrations and rollout all explicit.
2026-07-26T21:19:32.690363063+00:00 Validated documentation integrity: all relative links exist, 30 code fences balanced, keyword/criterion probes pass, git diff --check and cargo fmt --check pass. cargo build --locked passes (existing warnings only); documentation-only change.
2026-07-26T21:19:52.381741047+00:00 Committed: fb5e70ad — pushed to remote
2026-07-26T21:21:01.647298570+00:00 Task marked as done