docs(agents): point to the org architecture repo

[kyle-sexton]

No related issue: org-wide pointer rollout (owner-approved 2026-10-09)

Summary

Adds one fixed pointer line, under a short ## Org architecture heading in the agent instructions file, to the private melodic-software/architecture repo (cross-repo decisions, glossary, why each trust link exists, repo map).

Fix

The same line goes into every governed, non-archived repo so an agent in any of them finds the org context and knows to stop if access is denied. The section sits before ## Code Review Rules so that section stays last. A follow-up in melodic-software/standards adds a repo-policy check that fails a repo whose AGENTS.md or CLAUDE.md lacks melodic-software/architecture.

Verification

• The added line is byte-identical to the approved text across the rollout.
• The file diff is the new section only; no existing line changed.
• Repo hooks and checks ran on commit and in CI.

Related

• Owner-approved org-wide rollout, 2026-10-09.
• Standards check: see the linked melodic-software/standards PR from this rollout.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-09T21:42:40.003354Z	3ed35c6	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[claude]

Claude finished @kyle-sexton's task in 1m 39s —— View job

---

Code review — no findings

Scope: 1 file changed, AGENTS.md (+4/-0) — a new ## Org architecture section inserted before ## Code Review Rules.

• Gather context (PR diff, changed files)
• Understand request (CI code-review lane invocation)
• Review changes against criteria
• Post findings

Assessment: This is a trivial, docs-only pointer addition with no executable logic, no tests, and no interaction with other files in this repo — CLAUDE.md is empty and README.md has no conflicting "architecture" references, so nothing here contradicts existing guidance. The new paragraph's instructions (gh api orgs/melodic-software/properties/values for the repo map, gh api repos/melodic-software/architecture/contents/<path> to read files, attach-at-session-start on the web, read-only App token checkout in CI) are internally consistent and placed correctly so ## Code Review Rules stays the last section, matching the PR's stated intent. MD013 (line length) is disabled in .markdownlint-cli2.jsonc, so the long single-paragraph sentence isn't a lint issue, and it's a style/prose nit rather than a correctness concern, so it's out of scope for this lane's high-signal bar.

No correctness, maintainability, or architecture issues found on the changed lines. Nothing to report inline.

Note: the PR body's verification claims ("byte-identical to the approved text across the rollout", hooks/CI ran) are author-asserted and not independently verified here — this review only covers correctness/maintainability of the diff itself.

[claude]

Claude finished @kyle-sexton's task in 36s —— View job

---

Security review — PR #722

• Gather context (diff, AGENTS.md, pr-body-contract rule)
• Apply skip gate
• Report result

Skip gate triggered: this PR's only change is a purely additive documentation edit to AGENTS.md — a 4-line ## Org architecture section inserted before ## Code Review Rules (diff). Nothing is deleted, narrowed, or softened — no existing line changed (+4/-0), so the instruction-surface-deletion lens doesn't apply here. No workflow, script, or executable code is touched; this is prose guidance for future agent sessions, not a change in CI behavior itself.

No security-relevant surface in this diff. No findings.

[github-actions]

claude-security-review has reviewed this pull request through fd85f10; a later push is reviewed from there.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3ed35c6036

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

claude-review has reviewed this pull request through fd85f10; a later push is reviewed from there.

[claude]

Claude finished @kyle-sexton's task in 1m 6s —— View job

---

Code review — no findings

Scope (incremental): AGENTS.md, wording-only revision to the ## Org architecture paragraph added in the prior reviewed commit (3ed35c6 → fd85f10). See .claude-lane/incremental.diff.

• Gather context (incremental diff, PR data)
• Understand request (CI code-review lane, incremental scope: AGENTS.md)
• Review changes against criteria
• Post findings

What changed in this increment:

1. Adds a trigger condition — "Read it before cross-repo or infrastructure changes" — scoping when an agent should consult the architecture repo, where the prior wording implied always.
2. Adds -H 'Accept: application/vnd.github.raw' to the gh api call for reading a file from repos/melodic-software/architecture/contents/<path>. This is a real fix: without the raw media type, the Contents API returns base64-encoded JSON, which is awkward for an agent to consume directly; the header makes the response plain file content.
3. Replaces the unconditional "If access is denied, stop and tell the user" with "If you need it and cannot read it, say so instead of guessing its contents; tasks that don't need it continue." This directly resolves the Codex P1 comment from the prior commit (the old wording would block every task — even ones with no cross-repo/infra surface — if gh api had no token available).

Assessment: This is a prose-only tightening of guidance already reviewed with no findings. The three changes are internally consistent with each other and with the rest of the paragraph (the CI/web attach-at-session-start guidance is untouched), and the softened stop condition is consistent with this increment's own new "before cross-repo or infrastructure changes" trigger. No correctness or maintainability issues on the changed line.

[claude]

Claude finished @kyle-sexton's task in 1m 40s —— View job

---

Security review — PR #722 (incremental, through fd85f10)

• Gather context (.claude-lane/incremental.diff, prior review state at 3ed35c6)
• Apply skip gate
• Apply instruction-surface lens (this diff touches a standing-instruction file, AGENTS.md)
• Report result

Scope: only what changed since 3ed35c6 — a rewording of the ## Org architecture paragraph in AGENTS.md (blob). No other file in this PR changed.

Instruction-surface check. The paragraph softens its stop condition: the prior text ("If access is denied, stop and tell the user.") was an unconditional stop on any access failure; the new text ("If you need it and cannot read it, say so instead of guessing its contents; tasks that don't need it continue.") scopes that to only tasks that actually need the architecture doc, and by contrast keeps the implicit stop/no-guessing behavior for tasks that do need it (e.g. the newly-added "before cross-repo or infrastructure changes" trigger). Read by consequence rather than phrasing: the change narrows an overly broad stop condition (which previously fired even for work unrelated to cross-repo/architecture context) rather than removing the guard for the case it was written for — an agent making a cross-repo or infrastructure change still can't silently fabricate architecture content when access fails, it must say so.

The repo-local docs/conventions/instruction-exception-register/README.md is absent from this checkout, so the protected-class list itself was not consulted — per the skill's fallback, this assessment relies on consequence-based recognition only, not a register lookup.

The other hunk change — adding -H 'Accept: application/vnd.github.raw' to the gh api call for reading repo contents — is a response-format detail (raw bytes vs. base64-wrapped JSON) with no security implication.

No security findings on this incremental diff.

Branch: docs/org-architecture-pointer