Skip to content

docs(agents): fix the org architecture pointer wording - #100

Merged
kyle-sexton merged 1 commit into
mainfrom
docs/fix-org-architecture-pointer-wording
Oct 9, 2026
Merged

kyle-sexton merged 1 commit into
mainfrom
docs/fix-org-architecture-pointer-wording

Conversation

@kyle-sexton

Copy link
Copy Markdown
Member

No related issue: wording fix to the org architecture pointer merged earlier on 2026-10-09

Summary

Replaces the ## Org architecture pointer paragraph in AGENTS.md with the corrected wording: it names the raw media type for the file read, says to read the architecture repo before cross-repo or infrastructure changes, and says to report an unreadable repo instead of guessing its contents while tasks that don't need it continue.

Fix

The paragraph is replaced with the exact org-approved text. The melodic-software/architecture substring that the standards pointer check matches is unchanged.

Verification

  • The diff is the one pointer paragraph; no other line changed.
  • The new text is byte-identical to the text used in the other org repos.
  • Repo hooks ran on commit; CI runs on the ready PR.

Related

  • Follows the org architecture pointer rollout (owner-approved 2026-10-09).

🤖 Generated with Claude Code

Name the raw media type so the file read returns text, say when to read
the architecture repo, and replace "stop and tell the user" with a rule
that lets tasks not needing it continue.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EFqTQRnCGywRxhv4nw4o4V
@kyle-sexton
kyle-sexton marked this pull request as ready for review October 9, 2026 22:00
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 9, 2026 •

Copy link
Copy Markdown

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-09T22:02:25.495515Z c610741 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 Bot commented Oct 9, 2026 •

Copy link
Copy Markdown

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


Security review — /review:security-review

  • Gather context (diff, AGENTS.md, instruction-exception register)
  • Apply instruction-surface lens (diff touches a standing instruction file)
  • Report findings

Diff scope: 1 file, AGENTS.md, +1/-1 (the ## Org architecture pointer paragraph only).

Instruction-surface check: This diff rewords a standing instruction (AGENTS.md), so I checked it under the instruction-surface-deletion lens rather than skipping. Old vs. new:

  • Old: gh api repos/melodic-software/architecture/contents/<path> ... "If access is denied, stop and tell the user."
  • New: gh api -H 'Accept: application/vnd.github.raw' repos/melodic-software/architecture/contents/<path> ... "Read it before cross-repo or infrastructure changes" ... "If you need it and cannot read it, say so instead of guessing its contents; tasks that don't need it continue."

The change narrows "stop on any access denial" to "don't guess when the task needs it; unrelated tasks may continue." The safety-relevant clause — never fabricate the private repo's contents (cross-repo trust decisions) — is preserved and made more explicit, not removed. The new text also adds the Accept: application/vnd.github.raw header, a correctness fix (raw file content vs. a base64-wrapped JSON envelope), not a security-relevant change. No new exploit path (guessing trust-link contents, bypassing a check) opens up here: the one clause that mattered for that risk is still present and arguably strengthened.

Note: docs/conventions/instruction-exception-register/README.md is not present in this repo, so the protected-class list was not consulted directly — this assessment relies on consequence-based recognition only, per the skill's fallback.

Findings: none. This is a documentation-only wording fix with no executable code, workflow, or permission change. No CRITICAL/IMPORTANT/SUGGESTION issues identified.

@claude

claude Bot commented Oct 9, 2026 •

Copy link
Copy Markdown

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


Claude's review

  • Gather context (diff, CLAUDE.md/AGENTS.md, REVIEW.md)
  • Apply skip gate
  • Review changed lines in AGENTS.md
  • Post findings / summary

Summary

This PR changes a single line in the ## Org architecture paragraph of AGENTS.md
(diff):

  • Adds -H 'Accept: application/vnd.github.raw' to the gh api ... contents/<path> call. This is correct: without that header gh api on a contents endpoint returns the file base64-encoded inside a JSON envelope, not raw text — the header is needed for the read to return usable text.
  • Adds "Read it before cross-repo or infrastructure changes" as explicit guidance on when to consult the architecture repo.
  • Replaces "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" — a materially different (and more permissive) policy: previously any access failure halted, now only tasks that actually need the repo are blocked by an unreadable repo, and others proceed.
  • The melodic-software/architecture substring the standards pointer check matches is preserved, as the PR description claims.

I applied this skill's skip gate: this is a single-line, trivial documentation wording fix with no functional code, no tests, and no behavior outside of the instruction text itself. I read the changed line carefully and found no correctness issues — the gh api flag ordering and syntax are valid, the substring the pointer check relies on is untouched, and the new policy text is internally consistent (it still tells the agent to report rather than silently guess, just without an unconditional stop).

No findings to report. This is a clean, low-risk docs wording fix.

Note: per this lane's scope, I did not assess the PR title/body's Conventional Commits compliance or issue-linkage format — that's enforced by ci-status, not this review lane.

@github-actions

github-actions Bot commented Oct 9, 2026

Copy link
Copy Markdown

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

@github-actions

github-actions Bot commented Oct 9, 2026

Copy link
Copy Markdown

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

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c610741abf

ℹ️ 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".

Comment thread AGENTS.md Resolved
@kyle-sexton
kyle-sexton merged commit 163cd24 into main Oct 9, 2026
13 checks passed
@kyle-sexton
kyle-sexton deleted the docs/fix-org-architecture-pointer-wording branch October 9, 2026 22:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant