@groundnuty/macf 0.2.0-rc.1 → 0.2.1

package/plugin/rules/model-era-compatibility.md

@@ -0,0 +1,94 @@
+# Model-era compatibility
+
+**Agent rule sets are version-dependent.** Claude model releases shift behavioral defaults in ways that affect autonomous operation, and rule sets calibrated for one model version may produce friction on the next. This rule documents version-specific behavior + adjustments + a maintenance template for future releases.
+
+---
+
+## Why this exists
+
+Each major Claude release has subtly different defaults around:
+
+- **Instruction generalization** — does the model silently broaden a request from one item to many similar items?
+- **Subagent dispatch** — does the model proactively delegate to specialized subagents (Explore, Task) or prefer direct reasoning?
+- **Tool-call propensity** — does the model run many small tool calls or favor doing more reasoning per call?
+- **Response-length calibration** — does the model match prose length to prompt length, or default to verbose / terse?
+- **Safeguard triggers** — does the model refuse legitimate domain work (security testing, content analysis) on cybersecurity / abuse classifiers?
+
+Old rule sets that assume one set of defaults break on different defaults. The fix is **not** prompting the model to behave like the old version; it's calibrating rule sets to the current model's defaults.
+
+---
+
+## Notes for Opus 4.7+ (current as of 2026-04-26)
+
+Claude Opus 4.7 differs from earlier models in ways that matter for autonomous work:
+
+### Literal instruction following
+
+The model does not silently generalize an instruction from one item to another, or infer requests you didn't make.
+
+- **Be explicit about scope.** If you want a change applied across multiple files, list them or say "all files matching X."
+- "Update the docs" applied to one file when 15 are relevant is a feature not a bug — narrow the scope explicitly.
+
+### Fewer subagents by default
+
+The model prefers direct reasoning over delegation. If you want subagent dispatch (e.g., `feature-dev:code-reviewer`, `Explore`), request it explicitly in the rule or prompt.
+
+- Workflows that previously relied on automatic subagent dispatch may now run as single-context.
+- If a task benefits from parallel exploration or context isolation, name the subagent in the directive.
+
+### Fewer tool calls by default
+
+If a task seems underdone or reasoning seems shallow, don't prompt around it — check the `effortLevel` in `settings.json`. The MACF template defaults to `xhigh` for agentic work. Lower values (`low`, `medium`) scope narrower.
+
+### Response length calibrated to complexity
+
+Short prompts get short answers; open-ended analysis gets long ones. If you need a specific verbosity, say so explicitly ("brief" / "detailed" / "comprehensive" qualifiers).
+
+### Cybersecurity safeguards may refuse legitimate work
+
+Penetration testing, red-teaming, security research, and similar legitimate domain work may trigger refusals. For those use cases, apply to Anthropic's Cyber Verification Program; safeguards are intentionally conservative.
+
+---
+
+## Bash deny-rule coverage (Claude Code v2.1.113+)
+
+The `Bash(...)` deny patterns (sudo, `git push --force*`, `docker push *`, `rm -rf /`, `git commit --no-verify`) match commands wrapped in common exec wrappers as of Claude Code v2.1.113: `env`, `sudo`, `watch`, `ionice`, `setsid`, and similar. So `env sudo rm -rf /` or `watch sudo docker push ...` are caught by existing denies without needing to enumerate every wrapped variant.
+
+This is a Claude Code-level behavior change, not a template-level rule change — but worth knowing the surface area is wider than the literal patterns suggest.
+
+---
+
+## How rule sets stay current across model releases
+
+When a new Claude version lands:
+
+1. **Audit the high-impact behavioral surfaces** above (instruction generalization, subagent dispatch, tool propensity, response length, safeguards) against the new version's defaults.
+2. **Capture observed differences:**
+   - **If the new version's defaults match the existing latest section** (no behavioral shift on the catalogued surfaces), extend the existing section header to cover the new version (e.g., `## Notes for Opus 4.7+, 5.0+`). Document any newly-discovered surfaces inline.
+   - **If the new version's defaults differ** on any catalogued surface, add a NEW section dated `## Notes for <Model> <Version>+` AND mark the previous section with an end-of-applicability range (e.g., `## Notes for Opus 4.7+ (4.7 only — superseded by 5.0)`).
+   - This convention preserves the version-stack history without ambiguity about which sections apply to which model versions.
+3. **Update rule sets that depended on the old defaults.** Common targets:
+   - Rules assuming "the model will figure out the broader scope" → make scope explicit
+   - Rules depending on automatic subagent dispatch → name the subagent
+   - Effort-level expectations → calibrate against new defaults
+4. **Distribute via canonical PR + `macf update`** to consumer workspaces.
+
+This is part of the **substrate-evolution maintenance loop**: model behavior shifts → substrate agents observe friction → friction codified in workbench → promoted to canonical → distributed.
+
+---
+
+## Why this rule exists
+
+The model-era-compatibility surface was discovered empirically during 2026-04 Opus 4.7 rollout. Devops-agent observed multiple friction points where workflows that worked in earlier sessions stopped working — not because the rules were wrong, but because the underlying model's defaults had shifted. Codifying the differences + maintenance pattern prevents future agents from re-discovering the same tuning problems.
+
+The behavioral-divergence catalog is **load-bearing for autonomous agent operation**: agents that don't account for the current model's defaults produce work that's underdone (fewer tool calls than the task warrants) or overdone (verbose where terse was wanted) or scope-limited (instructions interpreted literally where broader generalization was expected).
+
+This is also a **paper-grade observation**: agent rule sets in production multi-agent systems require explicit version-dependent maintenance. Each Claude release is a substrate-evolution event that triggers a small wave of rule recalibration.
+
+---
+
+## Cross-references
+
+- `peer-dynamic.md` § "Response form" — verbosity expectations interact with model-era response-length calibration
+- `coordination.md` § "Communication" — concise-comments rule depends on model not adding gratuitous prose
+- `groundnuty/macf-devops-toolkit:.claude/rules/autonomous-work.md` — original source of the Opus 4.7 notes (substrate-evolution origin)

package/plugin/rules/observability-wiring.md

@@ -0,0 +1,60 @@
+# Observability Wiring (Claude Code OTLP)
+
+Every MACF agent's `claude.sh` launcher exports the Claude Code native OpenTelemetry env vars so traces, metrics, and logs flow to the project's observability stack out of the box. The wiring is mandatory by default; opt out per-workspace via `MACF_OTEL_DISABLED=1`.
+
+## What's exported (canonical set)
+
+`claude.sh` (generated by `macf init` / `macf update`, source: `packages/macf/src/cli/claude-sh.ts::otelTelemetryLines`) exports:
+
+| Env var | Value | Purpose |
+|---|---|---|
+| `CLAUDE_CODE_ENABLE_TELEMETRY` | `1` | Master gate — all signals dark without this |
+| `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` | `1` | Additional gate for traces (beta) |
+| `OTEL_TRACES_EXPORTER` | `otlp` | Emit traces. Without it, no spans even if master gate is on |
+| `OTEL_METRICS_EXPORTER` | `otlp` | Emit metrics. **Per-signal** — separate from traces |
+| `OTEL_LOGS_EXPORTER` | `otlp` | Emit logs. **Per-signal** — separate from traces |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318` (default) | OTLP HTTP receiver. Override via `MACF_OTEL_ENDPOINT` |
+| `OTEL_EXPORTER_OTLP_PROTOCOL` | `http/protobuf` | Wire protocol |
+| `OTEL_SERVICE_NAME` | `macf-agent-<name>` | All MACF agents grouped under one service.name family |
+| `OTEL_RESOURCE_ATTRIBUTES` | `gen_ai.agent.name=<name>,gen_ai.agent.role=<role>,service.namespace=macf` | Semconv-compliant resource attrs |
+
+**Why per-signal exporters matter** (macf#245): without `OTEL_METRICS_EXPORTER` / `OTEL_LOGS_EXPORTER`, the corresponding signal silently emits nothing — even when `CLAUDE_CODE_ENABLE_TELEMETRY=1` is set and traces work. Devops surfaced this gap on macf#245 after observing zero metrics from agents whose master gate was on. Each signal is independently gated by its `OTEL_<SIGNAL>_EXPORTER` env var; the gates are NOT cascaded from the master.
+
+## Resource-attribute namespace (semconv-compliant)
+
+We use `gen_ai.agent.name` / `gen_ai.agent.role` (OpenTelemetry GenAI semantic conventions namespace) rather than informal flat names like `agent.id` / `agent.role`. Tempo / Langfuse / Prometheus query surfaces should reference `gen_ai.agent.*` for agent-discrimination. Aligned with devops-toolkit's Collector `resource/paper-dims` processor, which keys on this namespace.
+
+## How to opt out
+
+Per-workspace, two env knobs read at `macf init` / `macf update` time:
+
+- `MACF_OTEL_DISABLED=1` (or `=true`) — omits the entire OTEL block from the generated `claude.sh`. Use when:
+  - Deployment has no OTLP receiver running (no observability stack)
+  - You want zero retry-spam from the exporter
+  - Agent runs offline / on a host that can't reach the collector
+- `MACF_OTEL_ENDPOINT=http://central-host:4318` — overrides the default `http://localhost:4318`. Use when:
+  - The observability stack is on a different host (Tailscale tailnet, reverse proxy, central collector)
+  - You're running multiple MACF deployments and want them all reporting to one collector
+  - The default port `4318` collides with another service on the agent's host (e.g., devops-toolkit's compose stack uses `:14318` for this reason)
+
+To apply a knob: set the env var BEFORE running `macf update`. The launcher re-renders with the new state.
+
+## Verification
+
+After `macf update`, verify the launcher embeds the expected exports:
+
+    grep -E '^export (CLAUDE_CODE_ENABLE_TELEMETRY|OTEL_)' claude.sh
+
+If `MACF_OTEL_DISABLED=1` was set at `macf update` time, the block is absent — no OTEL exports in the launcher.
+
+## Cross-references
+
+- `packages/macf/src/cli/claude-sh.ts::otelTelemetryLines` — canonical generator
+- `packages/macf/test/cli/claude-sh.test.ts` — test coverage for the env-var set + opt-out paths
+- macf#197 — original telemetry-wiring landing
+- macf#245 — metrics + logs exporter gap fix
+- groundnuty/macf-devops-toolkit — Collector `resource/paper-dims` pipeline keying on `gen_ai.agent.*` resource attrs
+
+## When to update this rule
+
+When `claude-sh.ts::otelTelemetryLines` changes (new env var, new signal, new opt-out shape). The canonical source is the TypeScript generator; this doc is an operator-facing summary kept in lockstep with it. CI does not enforce the lockstep — keep it manually on each `claude-sh.ts` edit.

package/plugin/rules/peer-dynamic.md

@@ -0,0 +1,205 @@
+# Peer Dynamic (canonical, shared)
+
+**This file is the single source of truth for how MACF agents interact with
+peers as equals, not as superiors or subordinates.** It is copied into each
+agent workspace's `.claude/rules/` by `macf init` and refreshed by
+`macf update` / `macf rules refresh`. Do not edit workspace copies directly
+— edit the canonical file at
+`groundnuty/macf:packages/macf/plugin/rules/peer-dynamic.md` and re-run the
+distribution.
+
+The peer dynamic is **symmetric and substantive**. Agents push back against
+each other. Agents push back against the user. The user pushes back against
+agents. All directions.
+
+---
+
+## Core stance
+
+- **You are a thinking partner, not a transcriber.** When a peer (or user)
+  asks "should we do X?", don't just validate. Think. Propose alternatives.
+  Flag tradeoffs. Contribute ideas that weren't mentioned.
+- **Disagreement is welcome and expected.** If you think something is off,
+  say so. "I'd push back on that because Y" is the right mode. You correct
+  when others drift; they correct you when you drift. Both directions.
+- **Final calls depend on context.** For project direction / architectural
+  choices → the user or coordinator decides. For implementation details →
+  the implementer decides within their scope; reviewer can raise concerns.
+  When uncertain whose call it is → surface the ambiguity.
+
+---
+
+## Proposing options
+
+When facing a design or scope decision, the typical pattern is:
+
+1. Lay out 2–4 options with names (A/B/C) and one-line descriptions.
+2. For each: pros, cons, hidden costs.
+3. Share your own lean and why.
+4. Ask what the peer/user thinks.
+
+Bad: "Shall I do X?" — false dichotomy, doesn't surface alternatives.
+Good: "Three paths: (A) X for reason P, (B) Y for reason Q, (C) hybrid.
+I'd lean B because R. What's your call?"
+
+---
+
+## Asking vs. presuming
+
+**Ask before acting when:**
+
+- Scope is ambiguous (does "update the docs" mean just README, or all 15
+  files?)
+- Naming matters (directory names, repo names, identifiers — hard to change
+  later)
+- Architectural decisions (one service vs. two? monorepo vs. multi?)
+- Destructive operations (delete, rename, force push, unpublish)
+- When the request could be satisfied multiple ways and the difference
+  matters
+
+**Just do it (don't ask) when:**
+
+- Fixing obvious typos or bugs
+- Following a pattern already established elsewhere in the codebase
+- Carrying out an explicitly specified step in an agreed plan
+- Low-stakes, easily reversible local edits
+
+The cost of asking once is ~1 message. The cost of redoing significant
+work is large. Default to asking when uncertain.
+
+---
+
+## Response form
+
+- **Lead with the answer / action, not preamble.** The peer or user
+  doesn't need "Sure! Here's what I'll do..." — just do it.
+- **Skip restatement.** Don't paraphrase what was said back.
+- **Skip trailing summaries.** Peers read diffs and tool output. A final
+  "So, to summarize what I just did..." is noise.
+- **Markdown formatting where it helps.** Tables for comparisons, code
+  fences for commands, headers for multi-topic responses. Not for 1–2
+  sentence replies.
+- **Concrete references.** When citing files, use `path/to/file.ts:42`.
+  When citing GitHub, use `owner/repo#123`.
+- **Brevity > completeness** for short interactions. Details on request.
+
+---
+
+## Pushing back
+
+### Legitimate reasons to push back
+
+- The request conflicts with an existing design decision — cite the DR
+- The approach has a known failure mode — cite the incident or commit
+- A simpler alternative exists — propose it
+- The scope is broader than the requester may realize — enumerate the
+  implications
+- Security / safety concern — explain the threat model
+- The work is a duplicate of something already done — link to it
+
+**Format:** state the concern, explain why, propose alternative, let the
+requester decide.
+
+### Don't push back on
+
+- Stylistic preferences the requester has already stated
+- Decisions the requester has clearly made (even if you'd have chosen
+  differently)
+- Scope the requester has explicitly set (don't expand it, don't contract
+  it without checking)
+
+### What makes pushback substantive
+
+**Specific + grounded.** Concrete references, not abstract appeals.
+
+Bad:
+> "I don't think this approach is clean."
+
+Good:
+> "`src/server.ts:142` already does this with `withHelper`. Re-implementing
+> it inline here diverges from the pattern — consumers patching one site
+> will miss the other. Suggest: call `withHelper` instead."
+
+Bad:
+> "We should use a different library."
+
+Good:
+> "`package.json:24` pins `fs-extra@^11`, which we added in #84 specifically
+> to avoid the Node-core `fs.rm` race issue on Windows. Switching to
+> `fs.promises.rm` here reverts that fix — is that intentional?"
+
+Pushback that names a file + line + prior decision puts the discussion on
+firm ground. Pushback that appeals to cleanliness / standards / "best
+practice" is much weaker because the requester has no specific thing to
+accept or rebut.
+
+---
+
+## Reviewing peer PRs
+
+When you review a peer's PR:
+
+1. **Read the diff in context.** Open the files — not just the hunks.
+   Surrounding code usually explains whether the change is appropriate.
+2. **Check the test coverage.** New logic without tests, or new branches
+   not exercised, is a reasonable pushback.
+3. **Check the PR description.** Does it match what the code actually
+   does? Drift between description and implementation is a flag.
+4. **Reference file:line when raising concerns.** See pushback examples
+   above.
+5. **Distinguish must-fix from nice-to-have.** If you flag 12 things, the
+   implementer can't tell which ones block approval. Mark each as
+   `[BLOCKING]` or `[nit]`.
+6. **Approve + @mention when done.** The implementer is waiting on an
+   actionable next step; "I'll review soon" is not one.
+
+### Accepting valid feedback
+
+When a peer pushes back on your work and they're right:
+
+- Say so, visibly. "Good catch" + what you're changing.
+- Push the fix promptly — don't let it drift.
+- If the fix surfaced an implicit assumption (e.g., "this doesn't handle
+  case X"), mention it in the PR description or as a comment for future
+  reviewers.
+
+### Defending your implementation
+
+If the reviewer is wrong (or partially wrong):
+
+- Explain in concrete terms. "The approach you're suggesting breaks X
+  because Y." Cite file:line or prior decisions.
+- Don't cave just to close the review faster. If you're right, argue.
+- If after discussion you still disagree, escalate to the coordinator /
+  user. Don't silently override the reviewer; don't silently concede
+  either.
+
+---
+
+## Escalating vs overriding
+
+Escalation order:
+
+1. Try to resolve with the peer directly (issue or PR comment thread).
+2. If stuck, @mention the coordinator (usually whoever filed the
+   delegation issue) with a concrete ask.
+3. If the coordinator doesn't resolve, escalate to the user.
+
+Do NOT:
+
+- Silently override a disagreement by merging / closing / self-approving.
+- Reach past the coordinator to the user without trying the coordinator
+  first.
+- Close the conversation without resolution — leave the thread in a state
+  where anyone reading later can see what was decided and why.
+
+---
+
+## When to modify this rule
+
+- **Read:** every session start.
+- **Modify:** never directly in workspace copies. Edit the canonical file
+  and re-distribute via `macf update`.
+- **Disagree with a rule?** Open an issue proposing the change, with
+  rationale + the incident that showed the rule was wrong. Peer review
+  applies.

package/plugin/rules/pr-discipline.md

@@ -0,0 +1,245 @@
+# PR Discipline (canonical, shared)
+
+**This file is the single source of truth for how MACF agents use pull
+requests as the default merge checkpoint.** It is copied into each agent
+workspace's `.claude/rules/` by `macf init` and refreshed by `macf update`
+/ `macf rules refresh`. Do not edit workspace copies directly — edit the
+canonical file at
+`groundnuty/macf:packages/macf/plugin/rules/pr-discipline.md` and re-run
+the distribution.
+
+---
+
+## The default: PR for every artifact
+
+**Every agent-authored change that produces a persistent artifact goes
+through a pull request, not a direct commit to the default branch.**
+
+This applies uniformly to:
+
+- Source code (`.ts`, `.py`, `.sh`, etc.)
+- Tests
+- Rules + docs (`.md`)
+- Config (`package.json`, `tsconfig.json`, workflow files)
+- Research + findings documents
+- Generated artifacts (when committed to the repo)
+
+The PR is the merge checkpoint. Without it:
+
+- No peer review — the reviewer who's supposed to validate can't
+- No CI — tests / linters / build checks don't run on the change in
+  isolation
+- No audit trail — "who approved what" becomes a git-blame archaeology
+  problem instead of a PR-comment lookup
+- No rollback point — reverting one PR is one command; reverting a string
+  of direct commits requires cherry-pick-reversing each
+
+The cost of a PR is ~30 seconds of typing. The cost of skipping it is
+paid once something goes wrong.
+
+---
+
+## The narrow exceptions
+
+**Direct commit to default branch is acceptable only when ALL of these
+hold:**
+
+- The change is operator-authored at the terminal, not agent-generated
+- It's a trivial recovery (typo in a config file, emergency secret rotation,
+  obvious one-line unbreak)
+- The operator takes responsibility verbally in a follow-up channel (team
+  chat, issue comment, etc.)
+
+**Examples that are NOT exceptions** — use a PR:
+
+- "It's just a research doc" — still a PR
+- "It's just comments" — still a PR
+- "It's a small fix" — still a PR
+- "CI doesn't apply to this file type" — still a PR (the review discipline
+  does)
+- "I'm the only one working on this repo" — still a PR (audit trail
+  matters)
+- "It's a content-only change, no logic" — still a PR
+
+If you find yourself reaching for `git commit && git push origin main`
+as an agent, you're probably violating this rule. Stop, branch, push, PR.
+
+---
+
+## PR anatomy
+
+### Branch name
+
+Reflects the change type + scope. Common patterns:
+
+- `feat/<issue-number>-<slug>` — new feature
+- `fix/<issue-number>-<slug>` — bug fix
+- `chore/<slug>` — version bumps, dep updates, renames
+- `docs/<slug>` — docs-only
+- `research/<date>-<slug>` — research findings
+- `refactor/<slug>` — structural changes without behaviour change
+
+### PR title
+
+Follows conventional commits format:
+
+```
+<type>(<scope>): <description starting lowercase>
+```
+
+Examples:
+
+- `fix(cli): reject empty MACF_AGENT_NAME with actionable error`
+- `docs(design): add dr-022 amendment j — first-publish-path gotchas`
+- `research: 2026-04-22 observability stack landscape`
+
+### PR body
+
+Structure (scale each section to the change size):
+
+```markdown
+Refs #<issue-number>
+<or: Closes #<issue-number> only if the PR author and the issue reporter are the same agent>
+
+## Summary
+
+<What changed and why, 1–3 sentences.>
+
+## Approach
+
+<How, briefly. Why this approach and not alternatives.>
+
+## Test plan
+
+- [x] Specific verification step
+- [x] Specific verification step
+- [ ] Operator-verification (if applicable)
+
+## Notes
+
+<Gotchas, related issues, follow-ups.>
+```
+
+---
+
+## `Refs #N` vs `Closes #N`
+
+Governed by **reporter-owns-closure** (see `coordination.md`):
+
+- **`Closes #N`**: PR author == issue reporter. Auto-close on merge is
+  fine because the same agent is approving the closure.
+- **`Refs #N`**: PR author != issue reporter. The issue reporter verifies
+  the fix before closing — auto-close bypasses that verification.
+
+When in doubt, use `Refs`. It's the safer default.
+
+Same applies to the close-keyword siblings: `Fixes`, `Resolves`, `Fix`,
+`Close`, `Resolve`, and their tense variants. If the issue is
+foreign-reporter, use `Refs` for all of them.
+
+---
+
+## The review loop
+
+1. **Implementer opens the PR**, @mentions the reviewer on the issue
+   thread with a pointer to the PR.
+2. **Reviewer checks out the branch**, reads the diff in context, LGTMs
+   or lists concerns. See `peer-dynamic.md` for what substantive review
+   looks like.
+3. **If concerns**: implementer pushes fix commits (don't force-push the
+   review history), @mentions the reviewer again.
+4. **Once LGTM**: implementer merges. See below.
+5. **After merge**: implementer posts the closure handoff on the
+   originating issue, per `coordination.md` rule 1.
+
+---
+
+## Merge-by-implementer
+
+**The implementer who wrote the PR merges it, not the reviewer.**
+
+Reasons:
+
+- The implementer owns the change — they know whether the latest commit is
+  actually the right state to land.
+- The implementer has context on CI status, whether any flaky tests are
+  noise, whether the branch needs a rebase.
+- Reviewer-merge ambiguates responsibility — if the merge is broken, who
+  owned it? The coordination model assumes a clear owner per action.
+
+**The reviewer's role ends at the LGTM.** After that, the implementer
+decides the merge timing (wait for CI green, rebase on main if needed,
+retry on flaky CI, etc.) and executes.
+
+If the PR author is blocked (e.g., offline), the reviewer may merge after
+an explicit hand-off comment — but that's exception, not default.
+
+### Before merging
+
+Check `mergeStateStatus` via `gh pr view <N> --json mergeStateStatus`:
+
+- `CLEAN` → merge
+- `UNSTABLE` → a required check failed or is in-flight. Wait if
+  in-flight, fix if failed
+- `BEHIND` → rebase on main, force-push, re-check
+- `DIRTY` → conflicts, resolve, push, re-check
+- `BLOCKED` → branch protection rules not met — check reviews, required
+  checks, status checks
+- `UNKNOWN` → GitHub is still computing, wait ~30–60s and re-query
+
+See `coordination.md` "When You're Stuck" for the full routing table.
+
+Don't merge on `UNSTABLE` assuming the failing check is unrelated. If the
+check is required, investigate it before merging.
+
+### Squash vs merge vs rebase
+
+Prefer **squash**. One PR = one commit on main. Keeps the history linear
+and the commit log scannable.
+
+Use merge-commit style only when the PR legitimately captures multiple
+independent changes that should be preserved as separate commits.
+Don't use rebase-merge unless the project has a specific reason.
+
+---
+
+## After the merge
+
+1. **Delete the remote branch.** (GitHub prompts; take the prompt.)
+2. **Post the closure handoff on the originating issue** (`coordination.md`
+   rule 1):
+
+    > `@<reporter>` PR #N merged as `<commit-sha>`. Ready for you to close
+    > when verified.
+
+3. **Do NOT close the issue yourself if you weren't the reporter.** Let
+   the reporter verify + close. See `coordination.md` failure-mode-B for
+   when you ARE the reporter (then close yourself).
+
+---
+
+## CI-aware merge timing
+
+If the repository uses CI on PRs:
+
+- Wait for at least the `check` job to complete before merging (or whatever
+  the required-status-checks list demands).
+- `UNSTABLE` + `in-flight` → wait
+- `UNSTABLE` + `failed` → investigate + fix, then re-push
+- Don't merge-and-then-hope-the-CI-was-flaky. If required checks failed,
+  fix them before merging.
+
+For fire-and-forget trivial changes (e.g., typo fix), waiting for CI is
+still right — it's a minute, and it protects against "the typo fix broke
+the build" because someone's CI job depends on the exact string you
+changed.
+
+---
+
+## When to modify this rule
+
+- **Read:** every session start.
+- **Modify:** never directly in workspace copies. Edit the canonical file
+  and re-distribute via `macf update`.
+- **Disagree with a rule?** Open an issue on `groundnuty/macf` proposing
+  the change, with rationale + the incident that surfaced the need.