From 6b4e27ef940df6b8119271b024b1159c2718c742 Mon Sep 17 00:00:00 2001 From: Cameron Brooks <95648474+CameronBrooks11@users.noreply.github.com> Date: Sat, 17 Oct 2026 11:53:44 -0400 Subject: [PATCH] docs(agents): add AGENTS.md pointing at eng-governance Decision 12 mandates an AGENTS.md per repository. The drift-audit check for it landed in eng-governance on 2026-09-10 and nothing had backfilled the fleet, so 46 of 70 active repos were reported as drifted on that one rule. Refs FlowMatrix-AI/eng-governance#122 --- AGENTS.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c7cf4a8 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,110 @@ +# AGENTS.md + +## Policy + +Org engineering policy is authoritative and lives in +**[`FlowMatrix-AI/eng-governance`](https://github.com/FlowMatrix-AI/eng-governance)**. +Read it rather than inferring the rules from surrounding code: + +| Where | What | +| --- | --- | +| [`DECISIONS.md`](https://github.com/FlowMatrix-AI/eng-governance/blob/main/DECISIONS.md) | Ratified engineering decisions, with the date each was locked | +| [`standards/`](https://github.com/FlowMatrix-AI/eng-governance/tree/main/standards) | Language, testing, security, dependencies, documentation | +| [`process/`](https://github.com/FlowMatrix-AI/eng-governance/tree/main/process) | Ownership, code review, pull requests, releases, design reviews | +| [`principles/`](https://github.com/FlowMatrix-AI/eng-governance/tree/main/principles) | Architecture and engineering principles | + +Anything this file does not state follows those. What it *does* state +**overrides** org defaults for this repo — so say it here, rather than +restating policy that already lives there and will drift from it. + +Cross-cutting technical documentation with no owning repo lives in +[`technical-docs`](https://github.com/FlowMatrix-AI/technical-docs). + +## Project + +Organization-level defaults for the `FlowMatrix-AI` GitHub org, and the org's +shared secret-scanning plant. It holds two reusable workflows +(`gitleaks.yml`, `commit-email.yml`), the org gitleaks ruleset +(`.gitleaks.toml`), the Actions workflow-template entry that seeds new repos, +the shared `.pre-commit-config.yaml`, and the community health files +(`SECURITY.md`, `PULL_REQUEST_TEMPLATE.md`, `ISSUE_TEMPLATE/`) plus +`profile/README.md`. **68 of the org's 70 active repos call `gitleaks.yml`** +from their own `.github/workflows/secret-scan.yml` — every repo but +`lead-intake` and this one, which calls it through a local ref — and the +resulting `gitleaks / gitleaks` status is a required check, so this repo gates +merges fleet-wide. `commit-email.yml` has no caller in the org today. + +## Commands + +```bash +# The only automated test here. CI does NOT run it — ci.yml is a bare `ok`. +# Needs python3 with PyYAML; extracts the workflow's own run: block and +# exercises it against throwaway git repos in a temp dir. +bash tests/commit-email.test.sh + +# Run this repo's own scan (it calls gitleaks.yml through a local ref). +gh workflow run secret-scan.yml + +# Who calls the reusable workflow right now. +gh api -X GET search/code -f per_page=100 \ + -f q='org:FlowMatrix-AI "FlowMatrix-AI/.github/.github/workflows/gitleaks.yml"' \ + --jq '.items[] | select(.path==".github/workflows/secret-scan.yml") | .repository.name' \ + | sort -u +``` + +## Architecture + +| Path | What it is | +| --- | --- | +| `.github/workflows/gitleaks.yml` | Reusable (`workflow_call`). Installs the gitleaks **binary** (MIT, free) and scans. Input `gitleaks-version` defaults to a pinned release. | +| `.github/workflows/commit-email.yml` | Reusable. Checks only the commits a PR/push *adds* carry a `*@flowmatrixai.com` (or allowed bot) author **and** committer. For public repos. No caller yet. | +| `.github/workflows/secret-scan.yml` | This repo's own caller. Uses the local ref `./.github/workflows/gitleaks.yml` on purpose. | +| `.github/workflows/ci.yml` | Trivial always-pass `ok`, so branch protection stays uniform. | +| `.gitleaks.toml` | The org ruleset: `[extend] useDefault = true`, one shared `[allowlist]`, and extra `[[rules]]`. | +| `workflow-templates/` | The Actions "new workflow" template a repo adopts. References `@main`, not a digest. | +| `.pre-commit-config.yaml` | Copied into repos so the local gate runs the same gitleaks as CI. Renovate manages it via `:enablePreCommit`. | +| `profile/`, `SECURITY.md`, `PULL_REQUEST_TEMPLATE.md`, `ISSUE_TEMPLATE/` | Org defaults. They apply only because this repo is public. | +| `renovate.json` | Carries a `customManager` that tracks a version pinned as a `workflow_call` input `default:` annotated with `# renovate:`, plus a rule disabling updates to this repo's references to itself. | + +`gitleaks-version` is visible to Renovate only because of the `# renovate:` +comment sitting directly above `default:` — the manager matches the pair. +Renovate's built-in `customManagers:githubActionsVersions` only matches keys +ending in `_VERSION`, so a workflow input default is invisible to it; that is +how the pin sat on 8.21.2 for a year. + +## What NOT to do + +- **Do not make this repo private.** Three things break, and the third is + silent: the org profile goes dark, the default community health files stop + applying org-wide, and the unauthenticated fetch of `.gitleaks.toml` 404s so + the required `gitleaks / gitleaks` check fails in all 68 callers. +- **Do not read a caller's digest pin as freezing behaviour.** Callers pin + `gitleaks.yml` by commit digest, but the workflow fetches `.gitleaks.toml` + from `main` on **every** run. Merging a change to the ruleset changes what + every repo detects on its next scan, with no PR anywhere else — and a + broadened allowlist **fails open**: checks stay green while detection + shrinks. Treat an allowlist edit as a fleet-wide security change. +- **Do not add a repo-local `.gitleaks.toml` without inheriting.** A local + config *replaces* the org ruleset and the scan still shows green. Use + `[extend] path = ".gitleaks.org.toml"`. Never set `useDefault` alongside + `path`; gitleaks rejects the combination outright. +- **Do not add a fallback to the `curl -f` fetch.** Fail-closed is deliberate: + a scan must never run with a different or empty ruleset. The accepted cost is + that an unreachable `raw.githubusercontent.com` blocks merges org-wide. +- **Do not pin `workflow-templates/gitleaks.yml` to a digest**, and do not + re-enable Renovate for `FlowMatrix-AI/.github` in this repo's + `renovate.json`. The template is copied verbatim into *other* repos, so it + cannot use a local `./` ref, and left managed Renovate chases this repo's own + HEAD every week — 8 of the 11 commits before that rule were that self-chase, + and each one reset `renovate/stability-days` on every downstream digest PR in + the org, stranding five of them for 45–54 days. +- **Do not point `.github/workflows/secret-scan.yml` at the full + `FlowMatrix-AI/.github/...` path.** The local `./` ref exists precisely so + there is no self-digest to bump. +- **Do not switch to `gitleaks/gitleaks-action`.** It requires a paid + `GITLEAKS_LICENSE` for organization repos. The binary is the whole point. +- **Do not bump `.pre-commit-config.yaml`'s `rev` and the workflow's + `gitleaks-version` default separately.** They are the local gate and CI + running the same detection rules; drift between them is invisible. +- **Do not assume CI covers `tests/commit-email.test.sh`.** `ci.yml` only + echoes `ok`. Run the test by hand after touching `commit-email.yml`.