Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .github/workflows/guards.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ name: Guards
# The deterministic replacements for the Claude-session-only PostToolUse hooks
# (D6): these hold for Codex, Claude, a human, or a bot, because CI
# is the one layer nothing bypasses. Jobs:
# root-allowlist - every repository-root file must be a deliberate architecture addition
# dashes - the cross-repo dash ban: changed files, the shrink-only baseline, and the PR title/body
# copy - AI-cliche / placeholder / typed-uppercase locale values + hardcoded brand colors
# ratchet - the eslint-suppressions.json baselines may only shrink
Expand All @@ -27,6 +28,16 @@ permissions:
pull-requests: read

jobs:
root-allowlist:
name: Root Allowlist
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 22
- run: node tools/check-root-allowlist.mjs

dashes:
name: Dash Ban
runs-on: ubuntu-latest
Expand Down
6 changes: 2 additions & 4 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -99,10 +99,8 @@ yarn-error.log*
# foglamp scan (edit token in scan.lock.json is a secret)
.foglamp/

# Agent scratch. A throwaway script belongs in the session scratchpad, never in a repo, and the
# rule is stated in tools/README.md. It was not enforced, so seven session-transcript parsers
# accumulated at the root on 2026-08-04 and one earlier case was patched by name rather than by
# pattern (.tmp_session_text.txt). Ignoring the shape is the gate; the rule alone was not.
# Agent scratch. The patterns keep local git status quiet, but they are not the gate: the closed
# root allowlist in tools/root-allowlist.json rejects every undeclared root file regardless of name.
.tmp-*
.tmp_*
.sess-*
Expand Down
2 changes: 2 additions & 0 deletions lefthook.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
min_version: "2.1.10"
pre-commit:
commands:
root-allowlist:
run: node tools/check-root-allowlist.mjs

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Exempt local env files from the pre-commit gate

When a developer has a legitimate local root .env/.env.local file (patterns this repo still ignores in .gitignore), this new pre-commit command runs check-root-allowlist, whose readdirSync scan includes ignored and untracked root files, so every commit is blocked even when nothing root-related is staged. Because contributors are also told not to bypass git hooks, this breaks the local secret/env workflow; either skip known local-only ignored files in the hook or run the closed allowlist against tracked/CI contents only.

AGENTS.md reference: AGENTS.md:L78-L80

Useful? React with 👍 / 👎.

web-eslint:
root: "apps/web/"
glob: "*.{ts,tsx,js,jsx,mjs,cjs}"
Expand Down
6 changes: 4 additions & 2 deletions tools/README.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,16 @@
# tools/

> **At a glance** - reusable, agent-callable scripts for the Orbit harness, versioned with the repo.
> - A script lives here when it is worth running more than once. Throwaways go to the scratchpad, never here.
> - A script lives here when it is worth running more than once. Throwaways go to the scratchpad, never here; `check-root-allowlist.mjs` enforces that boundary.
> - Every tool is non-interactive, supports `--help`, and returns meaningful exit codes (see `CONVENTIONS.md`).
> - `test-tools.mjs` EXECUTES every script here. A new tool with no coverage entry fails it, so coverage lands in the same PR as the tool.
> - Six of these are the orchestration core: `compose-prompt`, `launch-worker`, `verify-delivery`, `teardown-worktree`, `lib/orchestrator-config`, and `test-tools` itself.
> - `verify-delivery.mjs` is the SOLE authority for the word "delivered". A worker's exit code is never evidence.

Reusable scripts an agent (or a human) invokes from the CLI. The bar for landing a file here: it has a
single clear purpose and you will run it again. One-off commands stay in your shell history or the
scratchpad. Read `CONVENTIONS.md` before adding one.
scratchpad. The root allowlist gate rejects any undeclared root file regardless of its name or git
status. Read `CONVENTIONS.md` before adding one.

## The orchestration core

Expand All @@ -31,6 +32,7 @@ These back required CI checks. They fail a merge.
| `check-copy.mjs` | Enforces the copy register. Backs `Copy Register`. | `node tools/check-copy.mjs --check` |
| `check-suppressions-ratchet.mjs` | Fails when the lint-suppression count grows. Backs `Suppressions Ratchet` (escape hatch: the `ratchet:reseed` label). | `node tools/check-suppressions-ratchet.mjs` |
| `check-push-target.mjs` | Refuses a push whose target is a protected branch. | `node tools/check-push-target.mjs` |
| `check-root-allowlist.mjs` | Fails when an undeclared file exists at the repository root, including ignored and untracked files. Backs `Root Allowlist`; declarations live in `root-allowlist.json`. | `node tools/check-root-allowlist.mjs` |

## Architecture map and visual evidence

Expand Down
67 changes: 67 additions & 0 deletions tools/__tests__/check-root-allowlist.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
import { spawnSync } from "node:child_process"
import { cpSync, mkdirSync, writeFileSync } from "node:fs"
import { join } from "node:path"

import { T, check, root, toolPath } from "./_harness.mjs"

const stageRepository = (label, allowedFiles = []) => {
const repository = join(root, "root-allowlist", label)
const tools = join(repository, "tools")
mkdirSync(tools, { recursive: true })
cpSync(toolPath("check-root-allowlist.mjs"), join(tools, "check-root-allowlist.mjs"))
writeFileSync(join(tools, "root-allowlist.json"), `${JSON.stringify(allowedFiles, null, 2)}\n`)
return { repository, script: join(tools, "check-root-allowlist.mjs") }
}

const checkUndeclaredFile = (name) => {
const fixture = stageRepository(name.replaceAll(/[^a-z]/g, "-"))
writeFileSync(join(fixture.repository, name), "throwaway\n")
check(
"check-root-allowlist.mjs",
`rejects undeclared root file ${name}`,
[],
{ status: 1, stderr: new RegExp(name.replaceAll(".", "\\.")) },
{ path: fixture.script, cwd: fixture.repository },
)
}

export const cases = () => {
const clean = stageRepository("clean-linked-worktree")
writeFileSync(join(clean.repository, ".git"), "gitdir: elsewhere\n")
check(
"check-root-allowlist.mjs",
"accepts a clean linked worktree where .git is a file",
[],
{ status: 0 },
{ path: clean.script, cwd: clean.repository },
)

checkUndeclaredFile(".agent-scratch-extract.mjs")
checkUndeclaredFile(".tmp-extract.mjs")
checkUndeclaredFile("extract-tmp.mjs")

const ignored = stageRepository("ignored-untracked", [".gitignore"])
writeFileSync(join(ignored.repository, ".gitignore"), ".tmp-*\n")
writeFileSync(join(ignored.repository, ".tmp-extract.mjs"), "throwaway\n")
spawnSync("git", ["init", "-q"], { cwd: ignored.repository })
const checkIgnored = spawnSync("git", ["check-ignore", ".tmp-extract.mjs"], { cwd: ignored.repository })
const checkUntracked = spawnSync("git", ["ls-files", "--error-unmatch", ".tmp-extract.mjs"], { cwd: ignored.repository })
T("check-root-allowlist.mjs: fixture is gitignored and untracked", checkIgnored.status === 0 && checkUntracked.status !== 0)
check(
"check-root-allowlist.mjs",
"rejects a gitignored and untracked root file",
[],
{ status: 1, stderr: /\.tmp-extract\.mjs/ },
{ path: ignored.script, cwd: ignored.repository },
)

const declared = stageRepository("declared", ["deliberate-root-file.md"])
writeFileSync(join(declared.repository, "deliberate-root-file.md"), "architecture\n")
check(
"check-root-allowlist.mjs",
"accepts a root file named in the allowlist data",
[],
{ status: 0 },
{ path: declared.script, cwd: declared.repository },
)
}
65 changes: 65 additions & 0 deletions tools/check-root-allowlist.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
#!/usr/bin/env node
/**
* Gate repository-root files by location, not by guessed filename patterns.
*
* The allowlist is deliberately a closed set: every unlisted root file fails regardless of its
* name, extension, or leading dot. Adding a legitimate root file therefore requires a visible
* data change instead of another pattern that only recognizes shapes already seen.
*/

import { readdirSync, readFileSync } from "node:fs"
import { dirname, join, resolve } from "node:path"
import { fileURLToPath } from "node:url"

const USAGE = `usage: check-root-allowlist.mjs

Fails when the repository root contains a file not named in root-allowlist.json.
Directories are outside this gate. The .git worktree pointer is always ignored.

--help, -h print this usage and exit 0

exit codes: 0 every root file is declared, 1 undeclared root files exist, 2 usage or configuration error`

if (process.argv.includes("--help") || process.argv.includes("-h")) {
console.log(USAGE)
process.exit(0)
}

if (process.argv.length > 2) {
console.error(`check-root-allowlist: takes no arguments, got: ${process.argv.slice(2).join(" ")}\n`)
console.error(USAGE)
process.exit(2)
}

const toolsDirectory = dirname(fileURLToPath(import.meta.url))
const allowlistPath = join(toolsDirectory, "root-allowlist.json")
const repositoryRoot = resolve(toolsDirectory, "..")

let allowedNames
try {
allowedNames = JSON.parse(readFileSync(allowlistPath, "utf8"))
} catch (error) {
console.error(`check-root-allowlist: cannot read ${allowlistPath}: ${error.message}`)
process.exit(2)
}

if (
!Array.isArray(allowedNames) ||
allowedNames.some((name) => typeof name !== "string" || name.length === 0) ||
new Set(allowedNames).size !== allowedNames.length
) {
console.error("check-root-allowlist: root-allowlist.json must be an array of unique, non-empty filenames")
process.exit(2)
}

const allowed = new Set(allowedNames)
const undeclared = readdirSync(repositoryRoot, { withFileTypes: true })
.filter((entry) => entry.name !== ".git" && !entry.isDirectory() && !allowed.has(entry.name))
.map((entry) => entry.name)
.sort()

if (undeclared.length > 0) {
console.error("Root allowlist violation: declare or remove these repository-root files:")
for (const name of undeclared) console.error(` ${name}`)
process.exit(1)
}
23 changes: 23 additions & 0 deletions tools/root-allowlist.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
[
".claudeignore",
".gitattributes",
".gitignore",
".npmrc",
"AGENTS.md",
"CLAUDE.md",
"DESIGN.md",
"FEATURES.md",
"README.md",
"RENDER-CORRECTNESS.md",
"TESTING.md",
"app.json",
"architecture.html",
"architecture.json",
"lefthook.yml",
"package-lock.json",
"package.json",
"sonar-project.properties",
"tsconfig.base.json",
"tsconfig.json",
"turbo.json"
]
2 changes: 2 additions & 0 deletions tools/test-tools.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,7 @@ const CASE_MODULES = [
["capture-surfaces.mjs", "capture-surfaces"],
["check-dashes.mjs", "check-dashes"],
["check-push-target.mjs", "check-push-target"],
["check-root-allowlist.mjs", "check-root-allowlist"],
["compose-prompt.mjs", "compose-prompt"],
["launch-worker.mjs", "launch-worker"],
["lib/orchestrator-config.mjs", "orchestrator-config"],
Expand All @@ -98,6 +99,7 @@ const INVALID_INPUT = {
"check-copy.mjs": { argv: ["--orbit-not-a-flag"], status: 2 },
"check-dashes.mjs": { argv: ["--orbit-not-a-flag"], status: 2 },
"check-push-target.mjs": { argv: ["--orbit-not-a-flag"], status: 2 },
"check-root-allowlist.mjs": { argv: ["--orbit-not-a-flag"], status: 2 },
"check-suppressions-ratchet.mjs": { argv: ["--orbit-not-a-flag"], status: 2 },
"compose-prompt.mjs": { argv: ["--orbit-not-a-flag"], status: 2 },
"launch-worker.mjs": { argv: ["--orbit-not-a-flag"], status: 2 },
Expand Down
Loading