feat(autonomy): human-authorized corrective-PR exception for Heart RED

[Jammy2211]

Overview

Heart RED currently forbids commit, push, and PR-open at every autonomy level, yet Heart cannot clear a RED until the fixing source reaches main, wheels rebuild, and release-integration validation passes. So a source fix that directly repairs the exact defect named by the RED reason cannot be shipped — a deadlock (live example: PyAutoMind/active.md:6). This task adds a narrow, auditable, human-authorized corrective-PR exception permitting only commit/push/PR-open of one pending-release feature PR that repairs the named RED reason, while merge and every release stay separate human acts and Heart's release gate stays intact.

Plan

• Add a "Corrective-PR exception for Heart RED (human-authorized)" section to PyAutoBrain/AUTONOMY.md defining trigger, authorization, permitted/forbidden actions, record sinks, multiple-reason handling, park-without-shipping failures, and the recovery sequence.
• Make it strictly human-only: never reachable under --auto; the invariant "Heart RED is never acknowledged autonomously" stays verbatim.
• Name-one-of-several: authorization names exactly one RED reason; PR body states which it clears and that siblings remain, so release stays blocked until all clear.
• Point the ship skills (ship_library, ship_workspace, WORKFLOW.md) at the exception — link, no policy duplication.
• Add a deterministic doc-contract test pinning the guardrails and a no-duplication seam.
• Document the optional - corrective-red: active.md block in PyAutoMind/README.md.

Detailed implementation plan

Affected Repositories

• PyAutoBrain (primary)
• PyAutoMind (one-line registry note)

Branch Survey

Repository	Current Branch	Dirty?
./PyAutoBrain	main	clean
./PyAutoMind	main	clean

Suggested branch: feature/corrective-pr-heart-red

Design decisions (confirmed with the human)

• Human-only — never reachable under --auto; an unattended --auto run on RED still stops+reports. The corrective path is a separate, contemporaneous human act.
• Name-one-of-several — authorization names exactly one RED reason; the PR body scopes it honestly (siblings remain, release blocked until all clear).

Implementation Steps

1. PyAutoBrain/AUTONOMY.md — new section after "The autonomous-ship gate", before "Calibration log", covering:
   • Trigger: Heart RED + a source fix that directly repairs a named RED reason.
   • Authorization: explicit, contemporaneous human authorization quoting the exact RED reason string and approving the specific corrective issue (a human comment on the issue).
   • Permitted: commit, push, open one pending-release feature PR whose issue+plan+diff map to that reason. Nothing else.
   • Forbidden: automatic merge, issue close, release, release rehearsal, unrelated scope. Merge stays a separate human act; every release stays blocked while RED.
   • Four record sinks: GitHub issue, PR body, PyAutoMind active.md (- corrective-red: block), autonomy_log.md row tagged corrective — each carrying authorization, exact RED reason, causal mapping, tests, validation plan.
   • Multiple reasons: name one; PR body states which reason it clears and that siblings remain.
   • Failure → park without shipping: mixed-scope diff; stale/changed RED reason (re-read Heart at ship); missing evidence (no causal mapping/tests/validation plan); review finds patch not causal.
   • Recovery sequence: PR opened → human merges → fresh post-merge wheel build + release-integration validation → new Heart verdict → release work resumes only on that verdict. Release stays human-required throughout.
   • Plus: Levels×checkpoints Heart RED row pointer; Hard-invariants bullet (keep "never acknowledged autonomously" verbatim); Consumers note.
2. Ship skills — one linking sentence each at the RED-handling step: skills/ship_library/ship_library.md, skills/ship_workspace/ship_workspace.md, skills/WORKFLOW.md.
3. PyAutoBrain/tests/test_corrective_red_exception.py (new) — doc-invariant tests (style of test_policy_seams.py): section exists; permitted/forbidden sets; four record sinks; park cases; human-only + verbatim invariant; no-duplication seam over the ship skills.
4. PyAutoMind/README.md — one-line - corrective-red: active.md block note.

Key Files

• PyAutoBrain/AUTONOMY.md — canonical doctrine (new section + 3 small edits)
• PyAutoBrain/skills/ship_library/ship_library.md, .../ship_workspace/ship_workspace.md, skills/WORKFLOW.md — link the exception
• PyAutoBrain/tests/test_corrective_red_exception.py — new deterministic contract test
• PyAutoMind/README.md — registry-format note

Verification

• cd PyAutoBrain && python -m pytest tests/ -x — new test green, no regressions.
• Manual read: the AUTONOMY.md section is executable from the doc alone.

Original Prompt

Click to expand starting prompt

This is a workflow deadlock bug in PyAutoBrain/AUTONOMY.md and the ship_library / ship_workspace workflow: Heart RED currently forbids commit, push, and PR-open at every autonomy level, even when the proposed source fix directly repairs the exact defect named by the RED reason. Heart cannot clear that RED until the fix reaches main, fresh wheels are built, and release integration validation succeeds, so the gate makes recovery impossible without violating policy. Design and implement a narrow, auditable corrective-PR exception. It must require explicit, contemporaneous human authorization naming the Heart RED reason and approving the specific corrective task. It may permit only commit, push, and opening a pending-release feature PR whose issue, plan, and diff directly address that named reason. It must not permit automatic merge, issue close, release, release rehearsal, or unrelated scope; merge remains a separate human act and every release stays blocked while Heart is RED. Record the authorization, exact RED reason, causal mapping, tests, and validation plan in the GitHub issue, PR body, PyAutoMind active state, and autonomy calibration log. Require fresh post-merge wheel and release integration validation, followed by a new Heart verdict, before release work resumes. Define failure behavior for mixed-scope diffs, stale or changed RED reasons, multiple RED reasons, missing evidence, and a review finding that the patch is not causal: park without shipping. Update the canonical autonomy doctrine and affected ship skills without duplicating policy, add deterministic contract tests, and document the recovery sequence. This changes a hard invariant and therefore needs supervised human judgment despite being mechanically small.

Original user request verbatim: "ok, use intake to make prompt IO can run to address circular hole"

[Jammy2211]

Shipped — PRs open (awaiting human merge)

Implementation complete and shipped behind the ship gate.

• PyAutoBrain PR: feat(autonomy): human-authorized corrective-PR exception for Heart RED #113 — AUTONOMY.md corrective-PR exception + ship-skill links + tests/test_corrective_red_exception.py (12 tests)
• PyAutoMind PR: docs(reference): document the corrective-red active.md block PyAutoMind#78 — - corrective-red: active.md schema note

Tests: python -m pytest tests/ -q → 58 passed (46 pre-existing + 12 new).

Heart at ship: organism-scoped RED, human-authorized ship (nothing branch-related). Reasons — release validation FAILED (stage integrate), workspace validation not passing (2026-07-09), 58 stale parked scripts, PyAutoMind open PR 14d old, install verification not run — are all organism-scope; this doc-only branch touches none of them. This PR creates the corrective-exception mechanism but does not itself qualify for it.

Design decisions (confirmed): human-only path (never under --auto; the "Heart RED is never acknowledged autonomously" invariant stays verbatim) + name-one-of-several RED reasons.

Merge stays a human act — the run stops at PR-open.

[Jammy2211]

Follow-up (pushed to PR#113, commit 23ac901)

Closed a usability gap: the exception requires the human to quote the exact RED reason, but a human can only quote what they're shown. Made the agent responsible for providing the quote — when the circumstance arises it surfaces the exact RED reason string(s) verbatim from pyauto-heart readiness plus the specific corrective request, so the human authorizes what's put in front of them rather than reconstructing the wording.

Updated the AUTONOMY.md Authorization clause + the RED-handling step of ship_library/ship_workspace/WORKFLOW, and added a contract test. 59 tests pass.

[Jammy2211]

Both PRs merged (PyAutoBrain#113 → 1ae5ec8, PyAutoMind#78 → 66eb361). Closing.