Skip to content

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

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

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

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.

Findings marked 🟡 are optional suggestions and need no follow-up push.

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.

🔴 Maintainers get a Copilot instructions file that GitHub Copilot never actually loads, despite the PR claiming it adds 'Lightweight version for GitHub Copilot'. GitHub Copilot's repository custom instructions feature only reads from .github/copilot-instructions.md; this file is committed at the repo root (copilot-instructions.md), and no .github/copilot-instructions.md exists (confirmed: only .github/workflows/ is present under .github/). Fix: move/symlink the content to .github/copilot-instructions.md (mirroring the CLAUDE.md -> AGENTS.md symlink pattern already used) so Copilot's automatic instruction loading actually picks it up.

Why this was flagged

Any Copilot user working in this repo triggers Copilot Chat/code review with no repository custom instructions applied, because GitHub Copilot only auto-loads .github/copilot-instructions.md. The file added by this PR lives at the repo root (copilot-instructions.md, confirmed via ls), not under .github/, and find . -iname copilot-instructions.md shows only that one path. On base branch there was no such file either, so behavior is unchanged from before, but the PR's stated purpose (giving Copilot org-wide guardrails: tenant isolation, PHI, approved-tech checks) silently fails to take effect. Nothing in the repo enforces or validates the file's location, so the gap goes unnoticed. Line 28 of the file itself even instructs readers to check .github/copilot-instructions.md for repo-specific extensions, while the file granting org-wide baseline instructions is not there itself.

Verification: nit — The file is added at repo root as copilot-instructions.md (verified: ls copilot-instructions.md present; .github/ holds only workflows/, and find . -iname copilot-instructions.md returns only ./copilot-instructions.md). GitHub Copilot's repository custom-instructions feature auto-loads .github/copilot-instructions.md; a root-level file is not on that path, so it is not picked…

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.

🟡 nit (optional): CODEOWNERS only requires EA review for AGENTS.md and CLAUDE.md, so the enforcement files this same PR adds — .github/workflows/pr-architecture-review.yml, .github/workflows/check-commit-message.yml, policies/approved-tech.yaml, and .claude/rules/*.md — can be changed by anyone without EA sign-off, undercutting the governance model the PR is meant to establish. Fix: add entries for those paths (or a broad /.github/, /policies/, /.claude/rules/ pattern) so the enforcement surface itself requires EA approval.

Why this was flagged

CODEOWNERS (lines 1-3) lists only /AGENTS.md and /CLAUDE.md under @ icanbwell/enterprise-architecture. The PR description states CODEOWNERS gives 'EA ownership of instruction files' (plural), and also adds policies/approved-tech.yaml (the tech-approval gate) and the two new workflow files (the commit-message and architecture-review CI gates). None of those paths are covered, so a non-EA contributor could edit the tech-approval list or disable/weaken the CI gates without triggering mandatory EA review, on repos where branch protection relies on CODEOWNERS for required reviewers.

Verification: nit: The finding is factually correct. CODEOWNERS (the entire 3-line new file) assigns @ icanbwell/enterprise-architecture only to /AGENTS.md (line 2) and /CLAUDE.md (line 3). git diff --name-status confirms this same PR also adds the enforcement surface — .github/workflows/pr-architecture-review.yml, .github/workflows/check-commit-message.yml, policies/approved-tech.yaml,… | nit: The…

Comment on lines +15 to +17
with:
pattern: '^(Bump|Merge|Revert|Reapply|fix\(security\):|\[Aikido\]|build\(deps(-dev)?\): bump|([A-Z]+-[0-9]+))\s+.+'
flags: 'gm'

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) Commit-message enforcement is weaker than AGENTS.md's 'every commit starts with a JIRA issue key' rule: the checker's flags 'gm' (line 17) make the pattern's ^ anchor match the start of any line, not just the subject. A commit whose first line lacks a JIRA key can still pass CI if a later body line happens to start with a matching token, since gsactions/commit-message-checker's regex test returns true on any match anywhere in the message. Fix: drop the 'm' flag (or explicitly test only the first line) so the prefix rule is enforced on the subject, not anywhere in the body.

Why this was flagged

check-commit-message.yml lines 15-18 (new file) configure gsactions/commit-message-checker@ v2 with pattern '^(Bump|Merge|Revert|Reapply|fix(security):|[Aikido]|build(deps(-dev)?): bump|([A-Z]+-[0-9]+))\s+.+' and flags 'gm'. The 'm' flag makes '^' match the start of every line in a multi-line commit message, so the underlying regex test succeeds if any line anywhere matches, not only the first line. AGENTS.md's 'Commit Messages' section states every commit starts with a JIRA key; this check enforces 'contains a matching line somewhere' instead of 'starts with', so a badly-prefixed commit can slip through CI undetected. This is a newly introduced check, so the gap is new, not pre-existing.

Verification: nit. check-commit-message.yml (new file) sets pattern '^(Bump|Merge|Revert|Reapply|fix(security):|[Aikido]|build(deps(-dev)?): bump|([A-Z]+-[0-9]+))\s+.+' with flags 'gm' (lines 16-17). The 'm' flag makes '^' match the start of every line, and gsactions/commit-message-checker@ v2 passes when RegExp.test() matches anywhere in the multi-line message. So a commit with a non-JIRA…

Comment on lines +49 to +61
} 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 }));

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) Maintainers pushing a large batch of commits (branch import, long-lived release rebase) get silent gaps in JIRA-key enforcement that direct pushes to main/releases/* now rely on. The push-event branch (lines 49-65) calls compareCommitsWithBasehead once and maps comparison.commits (line 61) without pagination or checking comparison.total_commits, but GitHub's compare API caps the returned commits list (documented ~250 entries) — commits beyond that cap are never checked, though the comment at lines 50-52 claims this resolves 'the full range'. Fix: page through the compare results (or fall back to the List Commits API keyed off before/after) when total_commits exceeds commits.length, matching the github.paginate approach already used for the pull_request branch at line 39.

Why this was flagged

Trigger: a push to main or releases/* (line 6) whose before..after range spans more than the compare API's commit cap (~250), e.g. importing history into a new release branch or force-pushing a rebased long-lived branch. At line 56-61 the code does a single compareCommitsWithBasehead call and maps comparison.commits directly, with no github.paginate and no check of comparison.total_commits vs commits.length. On the base branch this whole compare path did not exist; the old push handling used context.payload.commits, capped at 20 (per the comment at line 50), so the gap existed but was already flagged there. Here the comment at lines 50-52 claims to 'resolve the full range', giving a false sense that pushes are now fully checked, when commits beyond the API's cap are silently never matched against the JIRA-key pattern and the workflow reports success. The pull_request branch avoids this by using github.paginate (line 39) with an explicit comment noting PRs can exceed 100 commits; the push branch has no equivalent safeguard.

Verification: nit. The mechanism is real: at lines 56-61 the push path does a single github.rest.repos.compareCommitsWithBasehead({ basehead: ${before}...${after} }) call and maps comparison.commits directly (line 61) with no github.paginate and no check of comparison.total_commits against comparison.commits.length. GitHub's compare API caps the returned commits array at 250 entries (documented…

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) Maintainers get incomplete JIRA-key/AI-attribution enforcement on new branch pushes: when before is all-zero (e.g. cutting a new releases/* branch), the code falls back to context.payload.commits, which the comment at lines 50-52 itself says GitHub caps at 20 entries — the very cap this compare-API workaround exists to avoid. Any commits beyond the first 20 on that push skip validation entirely. Fix: for the all-zero-before case, resolve the full commit range via another API (e.g. list commits ahead of the merge-base, or compare against the branch's parent ref) instead of the capped webhook payload, so branch-creation pushes get the same complete coverage as normal pushes.

Why this was flagged

Trigger: a push event to main or releases/* (workflow trigger at lines 5-6) where context.payload.before is all zeros — i.e. branch creation, common when cutting a releases/* branch from main with more than 20 commits. At line 55 the before && !/^0+$/.test(before) check is false, so the compare-API path (lines 56-61) is skipped and code falls to line 62-63, using context.payload.commits, which the adjacent comment (lines 50-52) documents as capped at 20 by GitHub. Result: only the last 20 commits get checked for JIRA-key/AI-attribution violations; earlier commits on the new branch are silently unvalidated, unlike the normal-push path this same diff added to fix exactly that cap.

Verification: nit. The gap is factually real and reachable. Line 55 guards the compare-API path with before && after && !/^0+$/.test(before); on a branch-creation push (before all zeros — e.g. cutting a releases/* branch, which matches the trigger at lines 5-6) this is false, so lines 56-61 are skipped and control reaches line 62-63, which uses context.payload.commits. The adjacent comment (lines…

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-052128 branch from 4644a1b to 95587da Compare October 1, 2026 21:10
@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-052128 branch October 28, 2026 18:05
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