docs: ADR-0012 Decision 6 (agent-supervised re-record repair)#1226
Merged
Conversation
Adds "heal-by-doing": when replay diverges on selector drift, the agent performs the failed step's intent with ordinary interactive commands against blessed refs, and the CLI emits the healed .ad from the session's actual successful execution path (session.actions) instead of hand-edited selector text. Folds in five normative protocol rules (R1-R5) from an external design review (verdict: SOUND-WITH-FIXES) covering record-arming timing, --from continuation semantics, mechanical repairHint routing, the writer's bare-@ref fail-close, and the recorded-open requirement. Makes explicit that this reintroduces an EXPLICIT, opt-in heal and is therefore consistent with (not a reversal of) decision 1's retirement of --update's SILENT auto-rewrite.
…ry router - Rename 'Decision 7' -> 'Decision 6' (ADR has decisions 1-5; new one is the 6th, placed after 5. Mandatory validation; existing decisions unchanged). - Reframe the two-sub-flows router: the CLI-computed repairHint (mechanical, in-scope, ships with this decision per R3) is the PRIMARY router; the agent follows the hint and uses screen.refs only as an ambiguity override, not as the default router. Removes the agent-judgment-vs-R3 contradiction.
…-run boundary (R6) Addresses two P1 review gaps: - P1-A: state that repairHint is computed daemon-side at divergence time from the recorded targetEvidence + the daemon's own full pre-action capture (only the enum crosses the wire, so the flat/capped screen.refs never gate routing); define repairHint for all four divergence kinds (selector-miss, identity- mismatch, identity-unverifiable, action-failure) with the sparse-capture fail-safe to manual. - P1-B: add R6 — --save-script records a boundary watermark (session.actions. length at invocation); the healed script serializes only the post-watermark slice, so a reused session's earlier actions don't pollute it. Clarifications: R4 fails loudly (non-zero exit, never swallowed); exact default output path = <original-stem>.healed.ad sibling; arming sets recordSession AND the watermark before step 1.
thymikee
changed the title
Member
Author
|
Re-review at 2a33e38: R6 resolves prior-session pollution, and R4 and default output behavior are now explicit. Remaining protocol blockers:
Not ready yet. No fixer dispatched. |
Addresses three protocol blockers: - Blocker 1: add repairHint to Decision 4's details.divergence field list and spec it as a single bounded enum (record-and-heal|state-repair|caution|manual), present on every divergence, carried at every level, surviving all four projections (text/JSON/client/MCP). - Blocker 2: make R3's mapping total — no recorded targetEvidence (reachable for unannotated action-failure per #1223, or any kind on a legacy script) => manual, generalizing the sparse-capture fail-safe. - Blocker 3: correct capture-timing — target-binding kinds use their PRE-action tree; action-failure uses its POST-response tree (adequate for the container presence test); no new pre-action tree is stored for action-failure. Validation extended for the projection-survival and no-evidence/post-response cases.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
@refsthe divergence report already hands it, and the CLI emits a healed.adequal to the session's actual successful execution path — no.adtext editing, no silent similarity-heal.repairHint). The enum is computed daemon-side at divergence time from two inputs the daemon already holds — the recordedtargetEvidenceannotation and the divergence's own full pre-action capture (the whole tree, not the flat/20-cappedscreen.refson the wire) — so only the enum value crosses the wire and the agent never computes it. Defined for all four divergence kinds:selector-miss→record-and-heal/state-repairby recorded-container presence;identity-mismatch→caution;identity-unverifiable→manual;action-failure→ same container-presence test (dispatch-thrown selector-miss now surfaces here per PR fix: wrap replay selector-miss as REPLAY_DIVERGENCE (repair-loop regression) #1223); sparse/unavailable capture →manual(fail-safe).--from-continuation-only; R3 mechanical daemon-siderepairHintgating; R4 selector-materialization with a loud fail (non-zero exit, never a swallowed/dropped line) on a bare@ref; R5 recorded-openrequirement; R6 repair-run boundary watermark =session.actions.lengthat invocation, so the healed script serializes only the post-watermark slice and a reused session's earlier actions never pollute it (no fresh session required for the repair).replay --save-script[=<out>]; default output is the<original-stem>.healed.adsibling; the original is never overwritten without an explicit path. Digest/resume reuses decision 4's live--from/--plan-digestloop unchanged.--update's silent auto-rewrite; decision 6 adds an explicit, agent-driven, opt-in re-record.repairHintframing + the R6 boundary watermark).Test plan
lint/formatscripts (oxlint/oxfmt) do not coverdocs/**, so no markdown lint gate applies.mainsource.repairHintmapping covers all four kinds + fail-safe; R1-R6 present and mutually consistent (R6 bounds prior-session pollution, R2 bounds within-run re-run duplication); R4 fails loud; no residual "future enhancement / agent-judgment routes" language contradicting R3.