From the #4376 post-mortem (44-day PR superseded by a 5-day duplicate
merged with zero comments): the reviewer of any PR owns the prior-art
check against older open PRs — merge automation runs no dupe scan; and
a rebase-only ask is a fix-merge maintainers do themselves via
maintainer edits, never a contributor round-trip.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
Claude-Session: https://claude.ai/code/session_01Trd6FQKKLF8sXAXG7VQs5b
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Relocate contributor- and maintainer-facing material out of docs/ so the
directory can become the user-facing Mintlify site. Moves preserve subpaths
(adr/, design/, staged-for-removal/ intact). messaging.md, UI_PHILOSOPHY.md,
and AGENT_SIGNING.md move per their DOC_INVENTORY dispositions (design doc,
design philosophy, maintainer convention).
Inbound links updated repo-wide: root guides, CONTRIBUTING, AGENTS,
workflows, lint config, scripts (check-doc-freshness now resolves the
inventory at engdocs/DOC_INVENTORY.md), Go comments, and the synced website
metadata page (regenerated via sync-website-docs.sh + generate-llms-full.sh).
The emitted help text in cmd/bd/init_safety_help.go still references
docs/adr/0002-init-safety-invariants.md; changing it would change bd's
runtime output, which is out of scope for this branch (flagged in the PR).
* docs: align agent maintainer conventions
Agent-Signature: codex-gpt-5.5-medium on behalf of matt wilkie
* docs: refresh checked-in AGENTS.md managed block to generated content
The PR self-review flagged the execution metadata key rename (item 4) as a
local experiment; that content was already dropped from this branch. Upstream
PR #4358 has since documented the existing execution_* model/effort keys as
portable hints in docs/METADATA.md, which remains the canonical reference.
Refresh the checked-in AGENTS.md managed Beads block to the current rendered
full-profile section so the marker hash is truthful. This drops the
experimental "read execution metadata first" workflow step from the managed
block (execution hints stay documented in docs/METADATA.md and
AGENT_INSTRUCTIONS.md) and picks up the conservative agent context profiles
from #4220.
Agent-Signature: claude-unknown-model-high on behalf of matt wilkie
Encodes the five cross-cutting process findings from the June 2026 audit of
440 merged PRs (epic bd-6dnrw) as enforceable rules: no self-merge of
nontrivial PRs and no merge over an unresolved CHANGES_REQUESTED; PR body must
match the diff (no grab-bags hidden under docs/test titles); review must be
real and accountable (agent reviews self-disclose, unestablished-account
approvals do not count); schema/migration/sync paths require a filled template
plus human review, branch-protection-enforced; and a revert ping-pong
cooling-off rule.
Owner-only follow-ups split out as children of bd-6dnrw: bd-qiw9i (configure
branch protection), bd-2dp2w (identify the Ari4ka approver), bd-un6np (define
agent merge permissions).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Make in-place maintainer edits on contributor PR branches the default path and document replacement PRs as the exception.
_codex-gpt-5.5-medium on behalf of matt wilkie_
agents are often only reading the opening post and the code, missing the follow-on comments and review recommendations. this is an attempt to fix that.