Loop Automation Report Format

Superseded layout: Loop automation skills no longer sync shared common-loop-*.md into references/. Each skill owns its contract locally.

Where rules live now

Concern	Location	When loaded
Survey/apply report shapes	references/common-output-format.md (+ common-output-format-automation.md when split)	Every run
Automation constraints + PR body rules	references/category-automation-envelope.md	Automation path only (## Constraints with may_edit)
PR synthesis templates	assets/pr-body-template-survey.md, assets/pr-body-template.md	Automation synthesis
PR body link rules	references/category-pr-body-links.md per skill	Synthesis; see loop-pr-body-skill-contract.md
Loop PR body drift checks	bash scripts/self/apm/check_loop_pr_body_contract.sh (via sync_apm_artifacts.sh loop-contract)	After editing loop skill templates/envelopes/link rules
Loop engineering doc placement	documentation-maintenance.md (repo canonical map)	When editing loop workflows/actions
Platform PR composition	loop-pr-body-skill-contract.md	Workflow / maintainers

Edit gate

Automation runs branch on may_edit from ## Constraints (injected by loop-detect during prompt assembly):

may_edit	Behavior
false	Survey — emit ### Candidates; no file edits
true	Apply — edit within allowlist; emit ### Changes / deferrals + ## Verification

Interactive runs resolve may_edit from natural language (default survey; explicit fix language → apply). See each skill's SKILL.md Workflow.

Four-plane contract (caller vs skill)

Loop callers configure four independent planes. Skills branch only on planes 2–3 from ## Constraints; they must not read level or delivery.

Plane	Caller inputs	Visible to skill?
Autonomy	level (L1/L2/L3)	No — platform job routing
Edit gate	may_edit	Yes
Artifact	write_target (fix | report), report_file when report	Yes
Delivery	delivery (open_pr, issue, log, …)	No — loop-finalize only

Spec: Loop write target & delivery design. Caller reference: loop-caller-inputs-reference.md.

When may_edit: true:

write_target	Agent persists
fix	Source/docs/manifests within allowlist
report	Structured file at report_file within allowlist

Skills using this pattern

Skill	Survey primary	Apply primary	Skip / defer subsection
changelog	### Candidates	### Changes	### Skipped
ci-sweeper	### Candidates	### Changes	### Deferred (+ ### Watch on survey)
docs-updater	### Candidates	### Changes	### Deferred
refactor	### Candidates	### Changes	### Deferred
tech-debt	### Candidates	### Changes	### Deferred

Overview contract

Every run emits ## Overview first. Write a complete plain-language summary — prefer useful detail over brevity.

Element	Include
Trigger	Scan scope, workflow/job, or commit range
Substance	Dominant categories, named files, or failure types; add scope when many
Action	Recorded, fixed, deferred, or no edits
Links	Link URLs from detect JSON when they aid navigation; file paths in Summary use blob/{fix_branch}/{path} — rules in references/category-pr-body-links.md

Per-skill examples live in each skill's common-output-format.md and assets/pr-body-template*.md.

Session metrics

Automation runs append ## Session Metrics per each skill's category-automation-envelope.md. Session metrics are checker/log output — not copied into PR body.