Autonomy contract: make the Autonomy: header load-bearing (AUTONOMY.md)

[Jammy2211]

Overview

The Mind prompt header blesses Autonomy: safe | supervised | human-required and the Intake Agent persists it — but nothing consumes it: every workflow run stops at the same human checkpoints regardless. This task writes the canonical autonomy contract (PyAutoBrain/AUTONOMY.md) that defines what each level means at each checkpoint, plus the guardrails (work-type caps, explicit --auto activation, calibration log). Doctrine only — skill behaviour changes land in the follow-up series (PyAutoMind/feature/autonomy/, task 4). First task of the 10-task autonomy series.

Plan

• Write PyAutoBrain/AUTONOMY.md — one canonical page: checkpoint inventory, per-level behaviour table, per-work-type caps, activation rule, calibration-log spec, hard invariants.
• Update PyAutoBrain/skills/WORKFLOW.md — link checkpoints to the contract; refresh the model doctrine from "Opus plans, Sonnet executes" to model-agnostic tiers (Fable-era judgment tier, stated so nothing breaks if access lapses).
• Add a single pointer line in PyAutoBrain/AGENTS.md (no duplicated prose).
• PyAutoMind: pointer from the README Autonomy: key to the contract; seed autonomy_log.md (append-only calibration log) with its column schema.
• No skill behaviour changes in this task.

Detailed implementation plan

Affected Repositories

• PyAutoBrain (primary)
• PyAutoMind (pointer + calibration-log seed)

Branch Survey

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

Suggested branch: feature/autonomy-contract
Work Classification: Library (organism repos)
Worktree root: ~/Code/PyAutoLabs-wt/autonomy-contract/

Implementation Steps

1. PyAutoBrain/AUTONOMY.md with sections:
   • Checkpoint inventory — Plan-Mode approval (start_dev), ship PR sign-off (## API Changes / ## Scripts Changed), Heart YELLOW acknowledgement, merge/close prompt, pre_build minor-version ask, post-merge cleanup confirmation.
   • Per-level behaviour table — safe (proceed + log; plan written to the issue), supervised (proceed; batch questions to the issue — checkpoint-and-continue, defined fully in series task 5), human-required (today's behaviour) × each checkpoint.
   • Per-work-type caps — refactor/test/maintenance may run safe; feature/bug capped at supervised until the calibration log justifies raising; release always human-required. A prompt header never exceeds its cap.
   • Activation rule — levels bind only under an explicit --auto launch; default runs are unchanged. Autonomy is opt-in per invocation, never ambient.
   • Calibration log spec — PyAutoMind/autonomy_log.md, append-only rows: date, task, level, gate results, outcome (merged-unchanged / amended / rejected).
   • Hard invariants — merge/close always human; never modify code to make tests pass; autonomous runs end at PR-open; Heart YELLOW/RED is a human checkpoint at every level.
2. PyAutoBrain/skills/WORKFLOW.md — replace checkpoint prose with links into AUTONOMY.md; rewrite "Model delegation" as strongest-available (judgment/orchestration/tutorial prose) / mid (planning fallback) / fast (mechanical execution) tiers, naming Fable as the current strongest tier.
3. PyAutoBrain/AGENTS.md — one pointer line to AUTONOMY.md.
4. PyAutoMind/README.md — the Autonomy: key bullet gains a pointer to the contract; create seeded PyAutoMind/autonomy_log.md.
5. Re-read WORKFLOW.md/AGENTS.md current state in the worktree before editing — intake formalise (PyAutoBrain#33) merged today, after the series prompts were written.

Key Files

• PyAutoBrain/AUTONOMY.md — new canonical contract page
• PyAutoBrain/skills/WORKFLOW.md — checkpoint links + model-tier doctrine
• PyAutoBrain/AGENTS.md — pointer line
• PyAutoMind/README.md — Autonomy: key pointer
• PyAutoMind/autonomy_log.md — new, seeded calibration log

Verification

Doc-only: link resolution across the edited pages, no duplicated doctrine (ORGANISM.md single-source rule), python3 PyAutoMind/scripts/repos_sync.py --check still clean.

Adversarial constraints (from the series review — keep these)

• Sizing is a model's own estimate: caps + explicit --auto + calibration log are mitigations, not extras.
• Feature Agent sized this large/split-into-phases; overridden to medium/no-phasing — the series is the phasing. Recorded divergence.

Original Prompt

Click to expand starting prompt

See PyAutoMind/issued/1_autonomy_contract.md (moved from feature/autonomy/1_autonomy_contract.md on issue creation) — filed 2026-07-08 as task 1 of the autonomy series with header Type: feature / Target: autonomy / Difficulty: medium / Autonomy: human-required / Priority: high.

[Jammy2211]

Library PR created: #35 (pending-release)

Doctrine shipped: AUTONOMY.md (checkpoint inventory, level table, work-type caps, --auto activation rule, calibration-log spec, hard invariants), tier-based model doctrine in WORKFLOW.md, pointer in AGENTS.md. Mind side is live on main: README Autonomy: key now points at the contract and autonomy_log.md is seeded.

Heart was YELLOW (pre-existing organism staleness, unrelated to this doc-only change) — acknowledged by the user at ship sign-off. No workspace impact (organism doc; ## API Changes: None). Next: merge on approval, then series task 2 (review faculty).