Skip to content

EA-2136 sync architecture instruction files from org baseline - #58

Closed
bwell-dev wants to merge 1 commit into
mainfrom
sync/architecture-instructions-20260922-051612
Closed

bwell-dev wants to merge 1 commit into
mainfrom
sync/architecture-instructions-20260922-051612

Conversation

@bwell-dev

Copy link
Copy Markdown

Architecture Instruction File Sync

This PR updates the organization-wide AI agent instruction baseline files from icanbwell/.github.

Changes

  • AGENTS.md: Organization-wide baseline codifying b.well architecture standards
  • CLAUDE.md: Symlink to AGENTS.md for Claude Code compatibility
  • copilot-instructions.md: Lightweight version for GitHub Copilot
  • policies/approved-tech.yaml: Technology approval list
  • .github/workflows: PR architecture review and commit message validation
  • .claude/rules: Path-scoped rules (OOAD/SOLID, testing, event contracts, operational) that load only when Claude touches a matching file
  • CODEOWNERS: EA ownership of instruction files

Source commit: 06e1efaab2c5167f50fe7749d1b01980339388f7

Review Notes

Review and merge when ready. These are org-wide architecture instruction updates from EA team. These files are purely additive and don't modify existing code.

Related: EA-2130

runs-on: ubuntu-latest
steps:
- name: Check For Issue Key
uses: gsactions/commit-message-checker@v2

@aikido-pr-checks aikido-pr-checks Bot Sep 22, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

3rd party Github Actions should be pinned - high severity
A third-party GitHub Action was imported, and is not pinned via a hash. This leaves your CI/CD at risk for potential supply chain attacks, if the affected GitHub Action is compromised.

Suggested change
uses: gsactions/commit-message-checker@v2
uses: gsactions/commit-message-checker@16fa2d5de096ae0d35626443bcd24f1e756cafee # v2.0.0

Reply @AikidoSec ignore: [REASON] to ignore this issue.
More info

Comment on lines +4 to +5
pull_request_target:
types: [opened, synchronize, reopened]

@aikido-pr-checks aikido-pr-checks Bot Sep 22, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Using unsafe GitHub Actions trigger may allow privilege escalation via CI/CD - medium severity
Using pull_request_target or workflow_run as a trigger is not recommended, as it may allow an attacker to elevate its privileges via the CI/CD pipeline by exfiltrating secrets (e.g. by reading out the caches of the GitHub Actions pipeline or listing loaded secrets in the environment). If the affected repository is open source, the attacker doesn't have to be an insider but could be any GitHub user.

Suggested change
pull_request_target:
types: [opened, synchronize, reopened]
pull_request:
types: [opened, synchronize, reopened]

Reply @AikidoSec ignore: [REASON] to ignore this issue.
More info

@claude claude 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.

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

Comment on lines +9 to +11
check-commit-message:
name: Check Commit Message
runs-on: ubuntu-latest

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🟡 (optional) The commit-message check can be satisfied by a JIRA key anywhere in the body, so non-compliant subject lines merge without being caught. pattern is anchored with ^...\s+.+ but run with flags 'gm', so ^ matches the start of ANY line, not just the first. A commit like "misc cleanup\n\nEA-2130 also fixes flaky test" passes even though the subject line has no ticket key. Fix: anchor the check to the first line only (drop the m flag and/or match against just the subject, e.g. ^(...)\s+.+ without multiline, or split on \n and test line 0).

Why this was flagged

gsactions/commit-message-checker@ v2 runs with pattern anchored ^(...)\s+.+ and flags: 'gm' at .github/workflows/check-commit-message.yml:9-11. The 'm' flag makes ^ match the start of every line in the commit message, not only the subject. A commit whose subject has no ticket key but whose body contains a line starting with a JIRA key (e.g. a trailer like "EA-2130 fixes flaky test") passes the check. This lets CLAUDE.md's rule 'every commit starts with a JIRA issue key' be silently bypassed for real merges, which the base repo (no such check existed before) never enforced either way, but the new check's own stated purpose is to guarantee the subject-line convention and it does not.

Verification: nit. The gap is real: at .github/workflows/check-commit-message.yml:10-11 the pattern is anchored ^(...|([A-Z]+-[0-9]+))\s+.+ and run with flags: 'gm'. gsactions/commit-message-checker@ v2 tests the regex against the whole commit message; the m flag makes ^ match the start of every line, so a commit whose subject has no ticket key but whose body contains a line beginning with a JIRA key…

Comment on lines +49 to +64
} else if (context.eventName === 'push') {
// The push webhook payload's `commits` array is capped at 20 entries by GitHub,
// regardless of how many commits were actually pushed — resolve the full range
// via the compare API instead, keyed off before/after SHAs.
const before = context.payload.before;
const after = context.payload.after;
if (before && after && !/^0+$/.test(before)) {
const { data: comparison } = await github.rest.repos.compareCommitsWithBasehead({
owner: context.repo.owner,
repo: context.repo.repo,
basehead: `${before}...${after}`,
});
messages = comparison.commits.map(c => ({ ref: c.sha.slice(0, 7), text: c.commit.message }));
} else if (context.payload.commits) {
messages = context.payload.commits.map(c => ({ ref: c.id.slice(0, 7), text: c.message }));
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🟡 (optional) The new AI-attribution check silently skips commits beyond the first 20 when a brand-new branch (main or releases/*) is pushed with more than 20 commits. The compare-API path (line 56-61) only runs when before is non-zero; for a new branch it falls back at lines 62-64 to context.payload.commits, the exact array the comment at lines 50-51 says GitHub caps at 20 entries regardless of push size. So AI-attribution text in commit 21+ passes unchecked and the job reports success. Fix: resolve the full commit range for the new-branch case too (e.g. diff against the branch's parent/first commit via the API) instead of trusting the capped payload array.

Why this was flagged

Trigger: a push creates a new branch matching main or releases/* (payload.before is all-zero) containing more than 20 commits, e.g. cutting a release branch from a long-lived feature branch. Entry point: the push handler at .github/workflows/check-commit-message.yml:49. At line 62-64 the code takes context.payload.commits, which the author's own comment at lines 50-51 states GitHub caps at 20 entries regardless of actual push size. Commits beyond the 20th are never scanned by BAD_PATTERN, so an AI-attribution line in commit 21+ is missed and core.setFailed is never called. The compare-API fix at lines 56-61 exists specifically to avoid this cap but is gated on before being non-zero, so it does not cover the new-branch path.

Verification: nit. The described gap is real. On a push that creates a new branch (main or releases/*, the trigger at line 6), context.payload.before is the all-zero SHA, so at line 55 !/^0+$/.test(before) is !true=false and the compare-API path (lines 56-61) is skipped. Execution falls to line 62 else if (context.payload.commits), using context.payload.commits — which the author's own comment…

Comment thread CODEOWNERS
@@ -0,0 +1,3 @@
# Architecture instruction files owned by Enterprise Architecture
/AGENTS.md @icanbwell/enterprise-architecture
/CLAUDE.md @icanbwell/enterprise-architecture

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🟡 (optional) CODEOWNERS only requires EA review for AGENTS.md and CLAUDE.md, so contributors can now change policies/approved-tech.yaml, .claude/rules/.md, copilot-instructions.md, and the new .github/workflows/.yml without any EA owner review. The PR's own goal is 'EA ownership of instruction files,' but the tech-approval list and CI enforcement workflows it just added are excluded. Fix: add CODEOWNERS entries for /policies/, /.claude/rules/, /copilot-instructions.md, and /.github/workflows/ so all newly-added governance files require EA sign-off, not just the two top-level files.

Why this was flagged

A non-EA contributor edits policies/approved-tech.yaml or .github/workflows/pr-architecture-review.yml or check-commit-message.yml; CODEOWNERS (lines 1-3) lists only /AGENTS.md and /CLAUDE.md, so no EA review is required to merge that change. This lets the tech-approval list or the CI security/architecture gates themselves be altered without the EA gatekeeping the PR describes as the point of adding CODEOWNERS. Base branch had no CODEOWNERS file at all covering any of these paths, so this is a partial, self-defeating fix rather than a pre-existing gap.

Verification: nit. Factually accurate: CODEOWNERS is only 3 lines — a comment plus /AGENTS.md @ icanbwell/enterprise-architecture and /CLAUDE.md @ icanbwell/enterprise-architecture. The same PR adds (git diff --name-status, all status A) policies/approved-tech.yaml, .claude/rules/{event-contracts,ooad-solid,operational,testing}.md, copilot-instructions.md, and… | pre-existing (governance completeness).…

Comment thread CLAUDE.md
@@ -0,0 +1 @@
AGENTS.md No newline at end of file

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🟡 (optional) Contributors on checkouts that don't materialize symlinks (Windows without core.symlinks, or GitHub's Download ZIP) silently get no org baseline loaded at all. CLAUDE.md is added as a git symlink (mode 120000) whose entire content is the literal 9-byte string AGENTS.md; on such checkouts git writes that string as CLAUDE.md's plain-text content instead of following the link. Claude Code then loads that literal text as the whole instruction file instead of the real 113-line AGENTS.md, so none of the Hard Non-Negotiables (tenant isolation, PHI, event-driven-first, etc.) apply that session. Fix: don't rely solely on a symlink for CLAUDE.md — ship it as a real file (or generate it in CI from AGENTS.md) so non-symlink checkouts still get the full baseline.

Why this was flagged

CLAUDE.md (new file, mode 120000) points at AGENTS.md and its raw git blob content is just the text AGENTS.md with no trailing newline. On a checkout that doesn't materialize symlinks — Windows with core.symlinks unset/false (the common non-admin default), or a GitHub 'Download ZIP' export, both of which convert git symlinks to plain files containing the link-target text — CLAUDE.md becomes a regular file whose only content is that literal string. Claude Code then reads AGENTS.md as the complete org baseline instead of the actual AGENTS.md content, so every Hard Non-Negotiable in the real policy (tenant isolation, PHI, FHIR-native modeling, approved-tech checks) goes unenforced for that session, with no error or fallback in this PR to detect it.

Verification: nit — CONFIRMED. git ls-files -s CLAUDE.md = 120000 47dc3e3 0 CLAUDE.md (git symlink); git cat-file -p HEAD:CLAUDE.md yields exactly the 9-byte string AGENTS.md with no trailing newline (wc -c = 9); AGENTS.md is a real regular file (mode 100644, 112+ lines). On a checkout that does not materialize symlinks — Windows with core.symlinks unset/false, or a GitHub "Download ZIP" export —…

Comment thread copilot-instructions.md
@@ -0,0 +1,28 @@
# icanbwell - Copilot Instructions

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🟡 (optional) Developers relying on GitHub Copilot to enforce these HIPAA/tenant-isolation guardrails get none, because Copilot never auto-loads this file. GitHub Copilot only reads repository custom instructions from .github/copilot-instructions.md; this PR adds the content at the repo root instead, so it is inert. Line 28 of this very file even tells readers to check .github/copilot-instructions.md for repo-level context, confirming the correct path exists and this file isn't it. Fix: place the org-baseline Copilot content at .github/copilot-instructions.md (move or have the sync write it there) so Copilot actually loads it, while still letting repos add repo-specific instructions there per line 28's existing convention.

Why this was flagged

The PR adds copilot-instructions.md at the repo root (new file, confirmed absent at c7264fb). GitHub Copilot's repository custom-instructions feature only auto-loads from .github/copilot-instructions.md; a root-level file of the same name is not read by Copilot at all. No .github/copilot-instructions.md exists in this repo (only .github/workflows/). Anyone using Copilot in this repo gets zero enforcement of the tenant-isolation, PHI, approved-tech, and gateway-only rules the file claims to provide, unlike the base branch's total absence being at least visibly obvious. Line 28 references .github/copilot-instructions.md as the real repo-level path, showing the authors know the correct location but didn't use it for this file itself.

Verification: nit. Factually correct: the new copilot-instructions.md is placed at repo root (ls confirmed), and .github/ contains only workflows/ — there is no .github/copilot-instructions.md. GitHub Copilot's repository custom-instructions feature auto-loads only from .github/copilot-instructions.md, not a root-level file, so as placed the file will not be picked up by Copilot. Line 28 of the file…

Updates from icanbwell/.github:
- AGENTS.md: Organization-wide AI agent instruction baseline
- CLAUDE.md: Symlink for Claude Code compatibility
- copilot-instructions.md: Lightweight instructions for GitHub Copilot
- policies/approved-tech.yaml: Technology approval list
- .github/workflows: PR architecture review and commit message validation
- .claude/rules: Path-scoped Claude Code rules (OOAD/SOLID, testing, event contracts, operational)
- CODEOWNERS: EA ownership of instruction files

Source commit: b3dd8dad6e65c55f86b1766bc02590e41f9e6d59
@bwell-dev
bwell-dev force-pushed the sync/architecture-instructions-20260922-051612 branch from e8b433f to b0b2c7b Compare October 1, 2026 21:06
@wfieldx

wfieldx commented Oct 28, 2026

Copy link
Copy Markdown

Closing this. Org AI-agent standards now reach every Claude Code session through the b.well Claude org's managed settings, so the copied org instruction files are no longer needed and this sync is retired. If this repo still carries an org copy of AGENTS.md, CLAUDE.md or .claude/rules, a separate cleanup PR or issue will follow. Your team's own instructions stay yours. The background is in https://github.com/icanbwell/.github/tree/main/policies/claude (EA-2774).

@wfieldx wfieldx closed this Oct 28, 2026
@wfieldx
wfieldx deleted the sync/architecture-instructions-20260922-051612 branch October 28, 2026 20:37
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.

2 participants