XY-875 Align loop engineering docs and skills

docs/runbook/research-to-execution-loop.md

@@ -62,8 +62,12 @@ evidence.
 5. Follow review and guardrail outcomes.
 
    Accepted independent-review findings route to repair. Three non-clean review
-   rounds, `needs_architecture_review`, or `blocked` escalates instead of continuing
-   patch churn. Repeated validation failures stop after the configured threshold.
+   rounds stop the current repair strategy instead of continuing patch churn.
+   Repeated validation failures do the same. Engineering convergence failures may
+   continue only through autonomous architecture recovery after the Authority
+   Boundary Check is `within_authority` and recovery budget remains; `blocked`,
+   `needs_architecture_review`, external blockers, insufficient evidence, or exhausted
+   recovery budget become human-required stops.
 
 6. Preserve uncovered direction as research feedback.
 

docs/spec/lane-control.md

@@ -213,15 +213,22 @@ the next lane action from authoritative signals. It is also the correct route wh
 requested control would overwrite useful partial work, hide a blocker, or require
 guessing human intent.
 
-Loop guardrail outcomes are manual-attention stop reasons, not active-lane controls.
+Loop guardrail outcomes are not active-lane controls. They first stop the current
+ineffective strategy. Engineering convergence reasons such as `validation_repeat`,
+`no_effective_diff`, `remaining_delta_unchanged`, or `review_churn` may then enter
+autonomous architecture recovery only after an Architecture Recovery Packet and
+Authority Boundary Check prove the next strategy is inside the Authority Envelope and
+recovery budget remains. Boundary, dependency, uncovered-direction, ownership, and
+exhausted-recovery outcomes become manual-attention stops.
+
 When status or failure writeback reports `validation_repeat`, `no_effective_diff`,
 `remaining_delta_unchanged`, `review_churn`, `dependency_program_stale`,
 `uncovered_direction`, or `ambiguous_retained_progress`, operators must inspect the
-retained worktree, private evidence, blocker state, or review findings named by that
-reason before clearing `decodex:needs-attention`. Do not use steer, retry, label
-cleanup, or hard interrupt to bypass the guardrail without changing the underlying
-repair strategy, dependency readiness, research contract, or retained-progress
-ownership decision.
+retained worktree, private evidence, blocker state, recovery packet, boundary check,
+or review findings named by that reason before clearing `decodex:needs-attention`.
+Do not use steer, retry, label cleanup, or hard interrupt to bypass the guardrail
+without changing the underlying repair strategy, dependency readiness, research
+contract, authority decision, or retained-progress ownership decision.
 
 Agents must not simulate manual attention by editing tracker state directly. The valid
 agent path is:

docs/spec/linear-execution-ledger.md

@@ -233,15 +233,18 @@ worktree changes and must not be emitted as `terminal_failure`. If the retained
 disposition absorbs a later runtime failure, the producer should preserve the source
 failure class in `evidence` instead of changing the event type or terminal path.
 
-Loop guardrail stops are public `needs_attention` or `terminal_failure` records with
-the runtime-owned `terminal_path = "manual_attention"` unless retained partial
-progress has already taken precedence. The public record may use these normalized
+Loop guardrail observations are private runtime evidence while autonomous architecture
+recovery is still available. A public Linear record is written only when the guardrail
+has terminalized into a human-required or terminal-failure outcome, with the
+runtime-owned `terminal_path = "manual_attention"` unless retained partial progress
+has already taken precedence. The public record may use these normalized
 `error_class` values: `validation_repeat`, `no_effective_diff`,
 `remaining_delta_unchanged`, `review_churn`, `dependency_program_stale`,
 `uncovered_direction`, or `ambiguous_retained_progress`. The Linear record must carry
-only the public reason and next action; fingerprints, full checkpoint payloads,
-review details, and worktree diagnostics remain in runtime SQLite private execution
-events and `loop_guardrail_checkpoints`.
+only the public reason and next action; architecture recovery packets, Authority
+Boundary Checks, fingerprints, full checkpoint payloads, review details, and worktree
+diagnostics remain in runtime SQLite private execution events and
+`loop_guardrail_checkpoints`.
 
 `failed_command` and `raw_error` are public-summary fields, not private evidence
 escape hatches. Producers must validate those values before writing a Linear comment.

docs/spec/owned-lane-policy.md

@@ -155,8 +155,8 @@ This action requires:
 | `In Review` lane has no actionable review yet | PR still belongs to lane; no requested changes that require repair; checks or review are still pending | `wait_for_external_signal` | Yes, when new signal arrives |
 | `In Review` lane now has actionable review repair work | PR still belongs to lane; actionable review feedback is present; retained lane remains reusable | `resume_retained_lane` | Yes |
 | `In Review` lane has green checks, satisfied review, and is mergeable | PR still belongs to lane; approvals satisfied; unresolved blocking review work absent; checks green; mergeable | `ready_to_land` | Yes |
-| Pre-PR independent review or post-review repair churn exceeded the configured convergence budget | Runtime-owned review checkpoints show repeated `findings` in the same phase crossed the configured limit; the lane no longer has a bounded low-risk patch path | `manual_intervention_required` | No |
-| Review-policy stop may need research escalation | Runtime-owned review checkpoints identify `needs_architecture_review` or repeated `findings` exhaustion with matching current head, phase, evidence, and stop class | `manual_intervention_required` | No direct retry; future research escalation may run only through a separate structured adapter contract |
+| Pre-PR independent review or post-review repair churn exceeded the configured convergence budget | Runtime-owned review checkpoints show repeated `findings` in the same phase crossed the configured limit; the current repair strategy no longer has a bounded low-risk patch path | `architecture_recovery_boundary` | Yes, only through a new Architecture Recovery Packet plus Authority Boundary Check when the boundary is `within_authority` and recovery budget remains |
+| Review-policy stop cannot recover autonomously | Runtime-owned review checkpoints identify `needs_architecture_review`, an Authority Boundary Check result outside the lane authority, insufficient recovery evidence, or exhausted recovery budget for the current head, phase, evidence, and stop class | `manual_intervention_required` | No direct retry; future research escalation may run only through a separate structured adapter contract |
 | Merge already happened but closeout or cleanup is incomplete | Merged PR is authoritative; closeout or cleanup evidence is still missing | `continue` | Yes |
 | Signals are contradictory or incomplete in a way that requires guesswork | Tracker, retained lane, review, or cleanup signals disagree materially | `manual_intervention_required` | No |
 
@@ -168,7 +168,9 @@ Automation must stop and require a human when any of these are true:
 - continuing would rewrite or override evidence the operator should inspect first
 - the runtime cannot prove that the retained worktree, PR, and tracker issue still belong to the same owned lane
 - a required failure guard could not be applied cleanly
-- the lane has already crossed the configured retry or repair convergence limit
+- the lane has already crossed the configured retry limit
+- review repair convergence has crossed the architecture recovery boundary and
+  recovery is outside authority, insufficiently evidenced, or exhausted
 
 For review-policy churn, the runtime counts only structured review checkpoints:
 
@@ -183,9 +185,13 @@ For review-policy churn, the runtime counts only structured review checkpoints:
 
 Review-policy stops are also the only review failures eligible for a future
 runtime-owned research escalation path. That path is not an additional action class and
-does not change the current stop decision: the implementation lane still enters
-`manual_intervention_required`, receives the configured human-attention guard, and
-stays ineligible until the blocking signal is materially cleared.
+does not by itself clear the current stop decision. `needs_architecture_review` and
+`blocked` still enter `manual_intervention_required`, receive the configured
+human-attention guard, and stay ineligible until the blocking signal is materially
+cleared. Convergence-budget exhaustion for repeated accepted findings first follows
+the loop-runtime architecture recovery boundary: a materially different engineering
+strategy may continue only when the Authority Boundary Check is `within_authority`
+and recovery budget remains; otherwise the lane enters `manual_intervention_required`.
 
 Any future research escalation must use the same runtime decision class plus a separate
 adapter contract. Free-form terminal comments, skill prose, old review memory, or stale
@@ -214,7 +220,8 @@ Examples of materially cleared signals:
 
 ## Automatic-recovery prerequisites
 
-Automatic recovery is allowed only when all of the following are true:
+Automatic recovery after a human-required or externally blocked stop is allowed only
+when all of the following are true:
 
 - the authoritative blocker was actually cleared, not merely commented on
 - the lane still has a valid owned worktree or a clearly recoverable replacement path

docs/spec/post-review-lifecycle.md

@@ -142,7 +142,7 @@ stateDiagram-v2
     cleanup --> [*]: lane state clean
 ```
 
-At any phase, contradictory state, exhausted repair budget, or a non-self-healing merge failure must stop the lane in `manual_intervention_required` instead of guessing a next step.
+At any phase, contradictory state or a non-self-healing merge failure must stop the lane in `manual_intervention_required` instead of guessing a next step. Exhausted repair or convergence budget first follows the owning review or loop guardrail policy: only an in-envelope Architecture Recovery Packet may continue autonomously; otherwise the lane stops as human-required.
 
 | Lane phase | Required action class | Entry conditions | Exit conditions |
 | --- | --- | --- | --- |
@@ -200,10 +200,12 @@ in `In Review`; it does not re-run the original `issue_review_handoff` state tra
 When `[codex].review` is `"standard"` or `"strict"`,
 `issue_review_repair_complete` is valid only when the latest retained repair
 checkpoint is `clean` for the current repaired head. If repeated repair checkpoints
-stay in `findings` for three consecutive rounds, or the checkpoint reports
-`needs_architecture_review` / `blocked`, the runtime must stop for human
-intervention instead of patch-on-patch churn. When `[codex].review` is `"off"` or
-`"basic"`, retained repair completion skips that Decodex Review checkpoint
+stay in `findings` for three consecutive rounds, the runtime must stop the current
+patch-on-patch strategy and run the architecture recovery boundary check before
+either retrying with a materially different implementation strategy or routing to
+human intervention. If the checkpoint reports `needs_architecture_review` /
+`blocked`, the runtime must stop for human intervention. When `[codex].review` is
+`"off"` or `"basic"`, retained repair completion skips that Decodex Review checkpoint
 requirement but still requires the repaired head to be pushed and the configured
 repository validation gate to pass.
 The same completion also requires that the PR still belongs to the retained lane, points
@@ -295,7 +297,11 @@ If merge is authoritative but closeout fails due to a deterministic infrastructu
 10. `review_wait`, `review_repair`, or `ready_to_land` may transition directly to `cleanup` when the tracker issue reaches a terminal cancellation state before merge and only deterministic local cleanup remains.
 11. `cleanup -> finished` when the retained worktree and lane branch state are clean.
 
-At any phase, contradictory signals or exhausted repair/convergence budgets force `manual_intervention_required`.
+At any phase, contradictory signals force `manual_intervention_required`. Exhausted
+retry budgets also force the human-attention path. Exhausted repair/convergence
+budgets first follow the owning review or loop guardrail policy: engineering strategy
+changes may continue only through autonomous architecture recovery inside the
+Authority Envelope; otherwise the lane becomes human-required.
 
 ## Failure, retry, and cancellation rules
 
@@ -311,12 +317,13 @@ At any phase, contradictory signals or exhausted repair/convergence budgets forc
 - Watch-level child failures in `review_repair` and deterministic post-review tail stages consume the same `execution.max_attempts` retry budget as normal issue execution. Once that budget is exhausted, the runtime must write the human-attention failure state, remove active automation ownership, and block the lane from further post-review redispatch.
 - Operator status must report an exhausted retained post-review lane as `blocked` with a retry-budget reason instead of continuing to classify it as `needs_review_repair` or `ready_to_land`.
 - If the lane's PR is already merged, exhausted local closeout, default-branch sync, or cleanup retries must be reported as `closeout_blocked` or `cleanup_blocked` with the retained PR URL from the runtime handoff row.
-- Structural churn is not a generic retry case. If repair rounds exceed the configured convergence budget, the runtime must stop for human intervention or architecture rethink rather than patching indefinitely.
+- Structural churn is not a generic retry case. If repair rounds exceed the configured convergence budget, the runtime must stop the current repair strategy and either enter architecture recovery under the Authority Envelope or require human intervention rather than patching indefinitely.
 - Three consecutive non-clean fresh-context review rounds in the same phase are a
   review-churn guardrail. Public writeback may use `review_policy_exhausted` or the
   normalized loop reason `review_churn`, but the recovery rule is the same: inspect the
-  repeated findings for the exact current head and choose a new repair strategy,
-  architecture review, or manual resolution before requeueing.
+  repeated findings for the exact current head, the Architecture Recovery Packet, and
+  the Authority Boundary Check before choosing a new repair strategy, architecture
+  review, or manual resolution before requeueing.
 - A repair batch that changes the head must return to `review_wait` for that new head instead of continuing downstream on stale review state.
 
 ### Landing and closeout failures

docs/spec/review-orchestration.md

@@ -85,10 +85,10 @@ Rules:
 
 - A resend caused by missing acknowledgement is a retry of the current request, not a new review round.
 - A review round does not complete until the lane either requests the next review or stops for escalation.
-- The first three review results from the same review source consume the normal convergence budget.
-- When the fourth review result arrives from the same review source, the lane must request an architecture check:
-  - if the repeated churn is rooted in an architectural defect or root-cause issue that local patching will not converge, stop for `manual_intervention_required`
-  - if the findings are normal and not rooted in architectural churn, continue and reset that review source's three-round budget
+- Each `findings` result from the same review source consumes the normal convergence budget for the current review phase.
+- The third consecutive non-clean result for the same phase stops the current repair strategy as review churn. Further autonomous work requires an Architecture Recovery Packet plus Authority Boundary Check for the current lane head.
+- Recovery may continue only when the Authority Boundary Check is `within_authority` and recovery budget remains. Otherwise the lane stops for `manual_intervention_required`.
+- There is no fourth-result reset path; `clean` is the only review result that clears the non-clean round count.
 
 ## Review levels
 
@@ -259,7 +259,7 @@ The lane must stop for `manual_intervention_required` when any of these occur:
 - GitHub Review pass signals do not match the strict required pair exactly
 - admin merge is unsupported for the repository
 - merged PR visibility does not arrive within the configured polling ceiling
-- architecture check concludes that repeated review churn is rooted in a non-converging architectural defect
+- Authority Boundary Check or architecture recovery outcome concludes repeated review churn is outside the lane authority, insufficiently evidenced, externally blocked, or recovery budget exhausted
 
 ## Review-stop research escalation
 
@@ -268,8 +268,13 @@ does not dispatch research automatically.
 
 Current required behavior:
 
-- `needs_architecture_review`, `blocked`, and convergence-budget exhaustion still
-  terminate through `manual_intervention_required`.
+- `needs_architecture_review` and `blocked` terminate through
+  `manual_intervention_required`.
+- Convergence-budget exhaustion for repeated accepted findings is normalized as
+  `review_churn`. It stops the current repair strategy and may continue only through
+  autonomous architecture recovery when the Authority Boundary Check is
+  `within_authority` and recovery budget remains. Otherwise it terminates through
+  `manual_intervention_required`.
 - The terminal failure path must preserve the normalized review-stop class instead of
   collapsing it into a generic retry failure:
   - `architecture_review_required`

docs/spec/tracker-tools.md

@@ -249,7 +249,9 @@ In either invalid case, `decodex` must fail the attempt rather than infer which
 - If a tracker tool call fails because it targeted the wrong issue or an unsupported operation, treat that as a policy violation, not as a retryable transport error.
 - When `[codex].review` is `"standard"` or `"strict"`, if the latest
   `issue_review_checkpoint` reports `findings` for the third consecutive non-clean
-  round on the same phase, or reports `needs_architecture_review` / `blocked`,
+  round on the same phase, `decodex` must stop the current repair strategy and apply
+  the loop-runtime architecture recovery boundary before any further autonomous
+  repair. If the checkpoint reports `needs_architecture_review` / `blocked`,
   `decodex` must stop the lane through the human-required failure path instead of
   retrying automatically.
 - Review-policy stops do not dispatch research directly. `decodex` may surface

plugins/decodex/skills/automation/SKILL.md

@@ -136,6 +136,12 @@ terminal automation signal.
   enabled, preserve `error_count`, `first_error_path`, and `first_error` as evidence
   but do not stop the lane solely because unrelated installed skill metadata failed to
   scan. Missing cwd coverage or zero enabled skills remain blockers.
+- When status reports loop guardrail reasons, inspect the current recovery state before
+  treating the lane as human-required. Engineering convergence failures may still be
+  autonomous after an Architecture Recovery Packet and Authority Boundary Check prove
+  the next strategy is inside the Authority Envelope. Boundary, external,
+  uncovered-direction, ownership, insufficient evidence, and exhausted-recovery
+  outcomes remain human-required stops.
 - Before assuming a lane is stuck, compare lane phase, wait reason, last run activity,
   protocol activity, active lease state, and child-agent activity when present.