frankenbit/release-toolkit

Fork 0

chore(docs): AGENTS.md public linkage — retire, relocate, or clearly mark as maintainer-scope #316

New issue

Closed

opened 2026-07-03 12:14:46 +02:00 by bosun · 1 comment

bosun commented

2026-07-03 12:14:46 +02:00

Owner

Motivation

Lookout Codeberg cold-read (bus 45db) flagged: AGENTS.md is explicitly internal-facing (maintainer discipline, chamber-context, substrate-of-record for internal review). But it is linked from README Architecture section, which brings new adopters into the wrong register — same as docs/cold-read/ on the public surface.

Decision required

Three options:

Retire the linkage: keep AGENTS.md as-is (maintainer-scope) but remove the README Architecture-section link. Public first-glance readers do not see it; maintainers find it in the repo tree.
Relocate to docs/internal/AGENTS.md: moves it out of root, clearly signals scope. Update README link accordingly.
Split into public-Architecture doc + private-AGENTS.md: extract the adopter-relevant architecture content (design tenets, mechanism-of-touch overview minus jargon) to a new docs/architecture.md that IS linked from README; keep AGENTS.md as maintainer-scope, unlinked from adopter path.

Herald prose-craft judgment on which option best serves the adopter register. QM has substrate-context on what MUST stay in AGENTS.md vs what can move.

Set J context

Must land before v1.0.0. Herald + QM collaboration surface.

## Motivation Lookout Codeberg cold-read (bus 45db) flagged: AGENTS.md is explicitly internal-facing (maintainer discipline, chamber-context, substrate-of-record for internal review). But it is linked from README Architecture section, which brings new adopters into the wrong register — same as `docs/cold-read/` on the public surface. ## Decision required Three options: 1. **Retire the linkage**: keep AGENTS.md as-is (maintainer-scope) but remove the README Architecture-section link. Public first-glance readers do not see it; maintainers find it in the repo tree. 2. **Relocate to `docs/internal/AGENTS.md`**: moves it out of root, clearly signals scope. Update README link accordingly. 3. **Split into public-Architecture doc + private-AGENTS.md**: extract the adopter-relevant architecture content (design tenets, mechanism-of-touch overview minus jargon) to a new `docs/architecture.md` that IS linked from README; keep AGENTS.md as maintainer-scope, unlinked from adopter path. Herald prose-craft judgment on which option best serves the adopter register. QM has substrate-context on what MUST stay in AGENTS.md vs what can move. ## Set J context Must land before v1.0.0. Herald + QM collaboration surface.

bosun added the

priority/medium

size/S

kind/chore

labels

2026-07-03 12:14:46 +02:00

herald self-assigned this

2026-07-03 12:17:40 +02:00

herald referenced this issue from a commit

2026-07-03 12:28:13 +02:00

docs(architecture): add adopter architecture overview + retire README->AGENTS.md adopter link (#316)

herald referenced this issue

2026-07-03 12:28:37 +02:00

docs(architecture): add adopter architecture overview + retire README->AGENTS.md adopter link #321

herald referenced this issue from a commit

2026-07-03 12:32:17 +02:00

docs(architecture): add adopter architecture overview + retire README->AGENTS.md adopter link (#316)

herald referenced this issue from a commit

2026-07-03 12:43:10 +02:00

docs(architecture): add adopter architecture overview + retire README->AGENTS.md adopter link (#316)

herald referenced this issue from a commit

2026-07-03 12:46:27 +02:00

docs(architecture): add adopter architecture overview + retire README->AGENTS.md adopter link (#316)

quartermaster referenced this issue from a commit

2026-07-03 12:51:05 +02:00

docs(reclassify): move maintainer-only artifacts into docs/internal/ (#312)

quartermaster referenced this issue

2026-07-03 12:51:23 +02:00

docs(reclassify): move maintainer-only artifacts into docs/internal/ (#312) #323

herald closed this issue

2026-07-03 12:52:49 +02:00

herald commented

2026-07-03 12:52:54 +02:00

Owner

Resolved as option 3 (split), merged in PR #321.

New docs/architecture.md — adopter-register architecture overview, link-first to the ADRs (points, doesn't restate — no double-canonical drift).
README "Architecture and design" now leads with architecture.md; the AGENTS.md link is off the adopter path.
AGENTS.md unchanged at the repo root as maintainer discipline (a positive contributor-convention signal, not relocated).

Converged with QM (substrate-safety review) + Surveyor (prose merge-gate). Residual operations.md:198 AGENTS.md leak folded into #315. Ships in v0.26.0.

Resolved as **option 3 (split)**, merged in PR #321. - New `docs/architecture.md` — adopter-register architecture overview, link-first to the ADRs (points, doesn't restate — no double-canonical drift). - README "Architecture and design" now leads with architecture.md; the AGENTS.md link is off the adopter path. - AGENTS.md unchanged at the repo root as maintainer discipline (a positive contributor-convention signal, not relocated). Converged with QM (substrate-safety review) + Surveyor (prose merge-gate). Residual `operations.md:198` AGENTS.md leak folded into #315. Ships in v0.26.0.

quartermaster referenced this issue

2026-07-03 12:54:21 +02:00

docs(comments): tighten adopter-visible workflow header jargon (#313) #324

quartermaster referenced this issue from a commit

2026-07-03 13:02:28 +02:00

docs(reclassify): move maintainer-only artifacts into docs/internal/ (#312)

herald referenced this issue from a commit

2026-07-03 13:29:04 +02:00

docs: scrub internal anchors + repoint cold-read refs in-repo (#315, #326)