docs: AGENTS.md — repo runbook for orchestrator/Codex/3+3 reviewers #43

Merged

pdurlej merged 2 commits from claude/docs/agents-md into main

2026-05-04 00:55:03 +02:00

claude commented

2026-05-03 23:24:00 +02:00

Collaborator

Canary status: missing — fire canary 3+3 before merge

Canary Context Pack

Product story

Reduce low-quality canary iterations from missing context. Per operator amendment 15 (PR #42 review 2026-05-03). Future agents reviewing PRs / executing master prompts read this file first; standardizes terminology, conventions, and identity-isolation discipline.

What changed

New file AGENTS.md at repo root (340 lines). No code changes.

Why it changed

Operator review of STATE_OF_PLATFORM v1 surfaced that reviewers were operating with insufficient context (caused some canary findings to be tangential). Glossary + conventions + anti-patterns codification reduces this.

Files touched

AGENTS.md (new file at repo root)

Relevant context

ADR 0001 (PR #41) — canary 3+3 mandatory + PM cadence; AGENTS.md codifies the operational details
PR #42 STATE_OF_PLATFORM v2 — operator amendment 15 explicitly named this follow-up
Charter §3 (deploy flow), §6 (cognition rule)
state/CLAUDE_SELF_INSTRUCTIONS.md §11 (Pattern D'), §12 (PR retro lessons), §13 (wakeup honesty)

Runtime evidence

N/A — governance/process doc; no runtime change.

Known constraints

Document is canary-required per ADR 0001 Rule 1 (touches no module/schema but is governance-equivalent; per AGENTS.md own definition of medium-size PR)
Identity-isolation section codifies fix from PR #42 (claude PAT in BW custom field, git config in worktree, push via http.extraheader)

Explicit out-of-scope

Forgejo Issues setup (separate TASK)
ADR 0002 CI enforcement (separate PR)
Smoke.sh rewrite (separate PR)
Per-actor MCP wiring (open question for ADR 0003 candidate)

Requested decision

approve_merge after canary 3+3 passes. PR size: Medium. Canary iter cap: 3 hard.

Merge blockers

Canary 3+3 not yet fired
If reviewer cites ambiguity in glossary or anti-patterns sections — iterate (within 3-cap)

Test plan

bash -n not applicable (markdown)
Operator readback: glossary entries match operator's mental model
Canary 3+3 fires; iter cap 3; terminal action determined
After merge: future PR descriptions / canary contexts can reference AGENTS.md sections (e.g., 'see AGENTS.md §Canary Context Pack')

Canary status: missing — fire canary 3+3 before merge ## Canary Context Pack ### Product story Reduce low-quality canary iterations from missing context. Per operator amendment 15 (PR #42 review 2026-05-03). Future agents reviewing PRs / executing master prompts read this file first; standardizes terminology, conventions, and identity-isolation discipline. ### What changed New file `AGENTS.md` at repo root (340 lines). No code changes. ### Why it changed Operator review of STATE_OF_PLATFORM v1 surfaced that reviewers were operating with insufficient context (caused some canary findings to be tangential). Glossary + conventions + anti-patterns codification reduces this. ### Files touched - `AGENTS.md` (new file at repo root) ### Relevant context - ADR 0001 (PR #41) — canary 3+3 mandatory + PM cadence; AGENTS.md codifies the operational details - PR #42 STATE_OF_PLATFORM v2 — operator amendment 15 explicitly named this follow-up - Charter §3 (deploy flow), §6 (cognition rule) - `state/CLAUDE_SELF_INSTRUCTIONS.md` §11 (Pattern D'), §12 (PR retro lessons), §13 (wakeup honesty) ### Runtime evidence N/A — governance/process doc; no runtime change. ### Known constraints - Document is canary-required per ADR 0001 Rule 1 (touches no module/schema but is governance-equivalent; per AGENTS.md own definition of medium-size PR) - Identity-isolation section codifies fix from PR #42 (claude PAT in BW custom field, git config in worktree, push via http.extraheader) ### Explicit out-of-scope - Forgejo Issues setup (separate TASK) - ADR 0002 CI enforcement (separate PR) - Smoke.sh rewrite (separate PR) - Per-actor MCP wiring (open question for ADR 0003 candidate) ### Requested decision approve_merge after canary 3+3 passes. PR size: Medium. Canary iter cap: 3 hard. ### Merge blockers - Canary 3+3 not yet fired - If reviewer cites ambiguity in glossary or anti-patterns sections — iterate (within 3-cap) ## Test plan - [ ] `bash -n` not applicable (markdown) - [ ] Operator readback: glossary entries match operator's mental model - [ ] Canary 3+3 fires; iter cap 3; terminal action determined - [ ] After merge: future PR descriptions / canary contexts can reference AGENTS.md sections (e.g., 'see AGENTS.md §Canary Context Pack')

claude added 1 commit

2026-05-03 23:24:00 +02:00

docs: AGENTS.md — repo runbook for orchestrator/Codex/3+3 reviewers 5d2efc6c26

Per operator amendment 15 (PR #42 review 2026-05-03). Reduces low-quality
canary iterations from missing context.

Sections:
- What this repo is (canonical desired-state spec for piotr's homelab platform)
- Current phase (Phase 02 cataloging at ~10%)
- Conventions: identity-isolation, canary 3+3, PR size classes, Canary
  Context Pack, reviewer escalation, Night Review, 4-class risk taxonomy,
  Owner Action Board, Model signal note, effort estimates per attention-unit
- Glossary: Phase 02 v2, Wave, Master prompt, Owner, Orchestrator, Producer,
  3+3 ensemble, Drift, Acknowledged risk, Canary status line, Strategic stop,
  Open loop, Pattern D', Sacred path, Iskra
- What agents must NOT infer without runtime evidence (container names,
  image digests, exposure classification, compose project, service identity,
  canary scope)
- How to request more context (escalation chain + approve_with_evidence_gap
  semantics)
- When-in-doubt defaults (propose+consequence+issue+gap+move-within-cap)
- Anti-patterns from cycles up to 2026-05-03 (pushing as operator, producer-
  mode, manual-state-in-prose, calendar-first, truncated digests, silent
  drift fixes, self-referential ADRs without enforcement)

Length: 250+ lines. Authored as claude (identity-isolation per ADR 0001 +
PR #42 v2 fix).

PR size class: Medium (governance doc, not module manifest; no security
boundary or runtime change). Canary 3+3 required.

claude referenced this pull request

2026-05-03 23:28:10 +02:00

docs(decisions): ADR 0002 — CI enforcement of canary 3+3 + hard iteration cap #44

claude referenced this pull request from a commit

2026-05-04 00:25:32 +02:00

docs: AGENTS.md — Oracle review amendments (5 fixes) + Oracle escalation discipline

claude added 1 commit

2026-05-04 00:25:32 +02:00

docs: AGENTS.md — Oracle review amendments (5 fixes) + Oracle escalation discipline 24623620d5

Per Oracle (GPT-5.5 Pro) review on PR #43 batch 2026-05-04, applies 5
amendments + adds Oracle escalation discipline section per operator's
2026-05-04 principle.

Amendments per Oracle:

1. "independent quality voices" → "diverse model-based review voices
   (independent in role/perspective, not in evidence base — all six are
   LLMs sharing training-data lineage; runtime evidence remains mandatory
   where relevant)". Honest framing: 6 LLMs from shared training lineage
   is not "independent" in evidence-base sense.
2. Removed calendar-first "~3 weeks at current pace" language. Replaced
   with owner-attention-bounded sequencing reference + pointer to
   STATE_OF_PLATFORM v2 §8 effort estimates.
3. Canary status state set aligned with ADR 0002 Rule 2 terminal actions:
   {approve_merge, approve_with_evidence_gap, operator_override,
   defer_to_issue, rewrite, split_pr} + missing (pre-canary). Removed
   inconsistent {approve_merge, defer, operator_override, missing} that
   conflicted with ADR 0002.
4. "Surface to operator BEFORE acting on assumption" → "surface
   ambiguity with proposed default + consequence + fallback. Don't
   silently default, don't block on operator without showing reasoning."
   Format-explicit so agent doesn't stall while looking responsible.
5. "Canary scope: don't assume PR is canary-required if line missing —
   ASK operator" → "classify by changed paths + size class, propose
   appropriate canary path as default. Don't ask operator unless
   genuinely ambiguous." Defaulting is the right move; asking is the
   exception.

Plus Oracle escalation discipline section (new) per operator principle
2026-05-04: Oracle is LAST RESORT, NOT primary review. Codifies:
- When Oracle escalation IS appropriate (iter-3 cap reached + no clear
  terminal; cross-cutting architectural decisions; canary systemic
  failure)
- When Oracle escalation is NOT appropriate (routine PRs, "want second
  opinion", "feels hard")
- Why discipline matters (canary is the safety net for non-technical
  owner; Oracle quota burn; outsource-thinking trap; unsustainable
  pattern)
- Format if escalating (.sisyphus/oracle-paste/ doc + decision-relevant
  question + audit log entry post-response)

Authored as claude. Self-test: this PR amendment cycle counts as iter 2
under ADR 0001 hard 3-iter cap; further iteration (iter 3) requires
terminal action choice per ADR 0002 Rule 2.

claude commented

2026-05-04 00:31:07 +02:00

Author

Collaborator

Amendment iter 2 (commit 2462362) per Oracle review 2026-05-04. Authored as claude.

5 Oracle amendments + Oracle escalation discipline section. Amendments: independent-quality-voices phrasing aligned with #42; calendar-first "~3 weeks" removed (replaced with attention-bounded sequencing); Canary status state set aligned with ADR 0002 6 terminal actions; "surface to operator BEFORE acting" → "surface ambiguity with proposed default + consequence + fallback"; canary-scope-when-missing → classify by paths+size and propose default. Plus new section: Oracle is LAST RESORT (not primary review); when YES (iter-3 cap reached + no clear terminal; cross-cutting arch decisions); when NO (routine PRs, "want second opinion", "feels hard"); why discipline matters; format for legitimate escalation.

Ready for operator review. Per ADR 0001 hard 3-iter cap: this is iter 2 of 3. If canary re-fired and finds new issues, iter 3 forces terminal action choice per ADR 0002 Rule 2.

**Amendment iter 2 (commit 2462362)** per Oracle review 2026-05-04. Authored as `claude`. 5 Oracle amendments + Oracle escalation discipline section. Amendments: independent-quality-voices phrasing aligned with #42; calendar-first "~3 weeks" removed (replaced with attention-bounded sequencing); Canary status state set aligned with ADR 0002 6 terminal actions; "surface to operator BEFORE acting" → "surface ambiguity with proposed default + consequence + fallback"; canary-scope-when-missing → classify by paths+size and propose default. Plus new section: Oracle is LAST RESORT (not primary review); when YES (iter-3 cap reached + no clear terminal; cross-cutting arch decisions); when NO (routine PRs, "want second opinion", "feels hard"); why discipline matters; format for legitimate escalation. Ready for operator review. Per ADR 0001 hard 3-iter cap: this is iter 2 of 3. If canary re-fired and finds new issues, iter 3 forces terminal action choice per ADR 0002 Rule 2.