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:44.243531Z	85f4f0e	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 11s —— View job

---

Code review complete

• Gather context (PR diff, AGENTS.md)
• Understand request (invoke /review:code-review lane for this PR)
• Review changed content for correctness
• Post findings / summary

Diff reviewed (AGENTS.md, +4/-0):

+## Org architecture
+
+Org architecture (cross-repo decisions, glossary, why each trust link exists): private repo `melodic-software/architecture`. Repo map: `gh api orgs/melodic-software/properties/values` (system and role per repo). Read it with `gh api repos/melodic-software/architecture/contents/<path>`; on Claude Code on the web, attach it at session start; in CI, check it out with a read-only App token. If access is denied, stop and tell the user.

Findings

None. This is a pure documentation addition, and it checks out on every axis I verified:

• Placement matches the PR's own claim — it sits directly before ## Code Review Rules, keeping that section last.
• Both gh api paths are real, correctly-shaped GitHub REST endpoints: orgs/{org}/properties/values (list custom property values for org repos) and repos/{owner}/{repo}/contents/{path} (repo contents).
• No existing section in AGENTS.md already covers org architecture, so there's no duplication/contradiction introduced.
• No code, tests, or CI config touched — nothing else in the repo depends on this text.

Nothing here rises to a block/flag-worthy correctness issue. No inline comments filed.

Note: the PR body's "Verification" section (byte-identical rollout text, hooks/CI ran) is author-claimed; I did not independently re-run hooks or diff against the other rollout repos.

[claude]

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

---

Security review (/review:security-review)

• Gather context (PR docs(agents): point to the org architecture repo #84, diff, custom instructions)
• Invoke /review:security-review
• Post findings

Scope: AGENTS.md — the only changed file, +4/-0.

Result: no security issues found.

The diff is purely additive: it inserts a new ## Org architecture section (4 lines) between the existing ## Pull requests and ## Code Review Rules sections. No existing line is modified, deleted, narrowed, or softened, so the instruction-surface-deletion lens in this skill doesn't apply here — there's no guardrail being removed for a hostile context to exploit.

Considered and ruled out:

• New cross-repo trust link. The section directs agents to read the private melodic-software/architecture repo via gh api (read-only) and to stop and tell the user if access is denied — a fail-closed instruction, not fail-open. No write capability, no secrets handling, and no code/workflow files are touched.
• Injection via fetched content. The instruction only tells the agent to read another repo for context; it doesn't change how that content would be consumed elsewhere, and this PR doesn't add any execution of untrusted content.
• GitHub Actions surface. No workflow files changed, so zizmor's lane is not implicated.

No inline comments were needed since there are no findings to anchor.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 85f4f0ee26

ℹ️ 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-security-review has reviewed this pull request through dc4fdb3; a later push is reviewed from there.

[github-actions]

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

[claude]

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

---

Code review complete

• Gather context (incremental diff, AGENTS.md, custom instructions)
• Understand request (invoke /review:code-review for this incremental change)
• Review changed content for correctness
• Post findings / summary

Scope: incremental review of AGENTS.md only, covering what changed since 85f4f0e (per .claude-lane/incremental.diff):

-Org architecture (...): private repo `melodic-software/architecture`. Repo map: `gh api orgs/melodic-software/properties/values` (...). Read it with `gh api repos/melodic-software/architecture/contents/<path>`; on Claude Code on the web, attach it at session start; in CI, check it out with a read-only App token. If access is denied, stop and tell the user.
+Org architecture (...): private repo `melodic-software/architecture`; repo map: `gh api orgs/melodic-software/properties/values` (...). Read it before cross-repo or infrastructure changes: `gh api -H 'Accept: application/vnd.github.raw' repos/melodic-software/architecture/contents/<path>`; on Claude Code on the web, attach it at session start; in CI, check it out with a read-only App token. If you need it and cannot read it, say so instead of guessing its contents; tasks that don't need it continue.

Findings

None. This revision is the fix for Codex's P1 finding on the prior commit ("stop before doing any work when private architecture access is unavailable, with no fallback"):

• The unconditional "stop and tell the user" is replaced by a scoped, fail-open rule: the read is now gated to "cross-repo or infrastructure changes," and when access isn't available, the instruction is to say so rather than guess — explicitly letting "tasks that don't need it continue." That resolves the blocking concern without reintroducing it.
• The added -H 'Accept: application/vnd.github.raw' header on the gh api ... contents/<path> call is a real, correctly-shaped GitHub media type for the Contents API — it returns raw file bytes instead of base64-wrapped JSON, which is the right fix for an agent that wants to actually read the file content.
• The .→; punctuation change is cosmetic only.
• No other lines in AGENTS.md changed; this is a pure wording edit with no code, workflow, or test surface.

No inline comments filed — nothing here rises to a block/flag-worthy issue.

[claude]

Claude finished @kyle-sexton's task in 2m 23s —— View job

---

Security review (/review:security-review)

• Gather context (incremental diff since 85f4f0e, PR body, prior Codex/Claude review comments)
• Invoke /review:security-review for the changed lines in AGENTS.md
• Post findings

Scope: incremental — only the wording change to the ## Org architecture paragraph in AGENTS.md made since this lane's last review of 85f4f0e. This edit is the author's direct response to the Codex P1 comment on the prior wording ("stop and tell the user" on any access denial, too broad).

Finding (IMPORTANT) — posted inline

The rewrite fixes the overly-broad stop but, in the same sentence, drops the explicit halt for the one case this section exists to gate: a cross-repo/infrastructure change where the architecture doc is genuinely needed and unreadable.

If you need it and cannot read it, say so instead of guessing its contents; tasks that don't need it continue.

"Say so instead of guessing its contents" is a disclosure instruction, not a halt instruction — the only hint that a needed-but-unreadable case shouldn't proceed is the unstated converse of "tasks that don't need it continue." Nothing else backs this (pure LLM-followed prose, no hook/CI check), so this is a real narrowing of a standing trust-boundary guardrail, not a no-op rewording. An independent review:lane-verifier pass validated this as PLAUSIBLE, leaning confirmed: a realistic failure path is an agent hitting a private-repo access denial on a cross-repo/infra task, disclosing it, and then proceeding on its own assumptions about the trust link rather than halting for owner input — the sentence doesn't forbid that.

Suggested fix (keeps the Codex-requested narrowing, restores the explicit halt only where it's needed):

If you need it and cannot read it, stop and say so instead of guessing its contents; tasks that don't need it continue.

Note: the instruction-exception-register (melodic-software/claude-code-plugins) wasn't reachable from this checkout (no WebFetch, file absent locally), so this was assessed by consequence rather than against the protected-class list.

No other findings — the rest of the diff (the -H 'Accept: application/vnd.github.raw' header addition, the "before cross-repo or infrastructure changes" scoping) is a correctness/scoping improvement with no security implication.