An agent organization structured as a company — 15+ departments, 125+ skills, each independently installable, citing the standards and regulators that settle the question. Runs in Claude Code and ChatGPT.
HTML agent-marketplacechatgpt-pluginchatgpt-skillsclaude-codeclaude-code-pluginclaude-pluginclaude-skillsmcporganization
#!/usr/bin/env node
/**
* agent-guard — the executable half of the agent/subagent hierarchy.
*
* Two guards in one file, because prose rules do not execute. A surface map written
* in Markdown and never checked is a suggestion; checked on every PR it is a control.
*
* node agent-guard.mjs check Is the map coherent?
* node agent-guard.mjs diff <agent> Did this diff obey it?
*
* They are not redundant, and you need both. `check` proves no two agents claim the
* same path and no path is unowned. It cannot prove a change respected the map — once
* the work is committed by the orchestrator, the information about which agent authored
* which hunk is gone. `diff` runs while that authorship is still known.
*
* No dependencies. Node 18+. Drop it anywhere and wire two scripts.
*/
import { execFileSync } from 'node:child_process';
import { existsSync, readFileSync, readdirSync } from 'node:fs';
import { join } from 'node:path';
/* ── Configure these three for your repo ──────────────────────────────────── */
const MAP_FILE = process.env.AGENT_MAP ?? 'docs/AGENT-SURFACES.md';
const AGENT_DIR = process.env.AGENT_DIR ?? '.claude/agents';
const DECISION_LOG = process.env.AGENT_DECISIONS ?? 'docs/DECISION-LOG.md';
/** The orchestrator is not an agent. It owns the context artifacts and commits everything. */
const ORCHESTRATOR = 'orchestrator';
/* ── Authority ────────────────────────────────────────────────────────────────
* The surface map answers *where* an agent may write. It has never answered whether
* that write may land without a human seeing it, so in practice that was decided per
* dispatch, from memory, by whoever was driving. Authority is the second axis, stated
* once in the map and checked like everything else.
*
* autonomous dispatch it and take the result; the surface is the only gate needed
* proposes it may do the work, but the orchestrator surfaces the diff before landing
* escalates do not dispatch it without being asked to; the work itself is the decision
*
* Rows may omit the column. Omission means `autonomous` — the behavior every existing map
* already had — and is reported as a note so a map that never considered the question is
* distinguishable from one that answered it.
*/
const AUTHORITY = ['autonomous', 'proposes', 'escalates'];
const DEFAULT_AUTHORITY = 'autonomous';
/** Gated rows are the ones whose output the orchestrator may not simply take. */
const isGated = (row) => row.authority !== 'autonomous';
/* ── Glob → RegExp ────────────────────────────────────────────────────────────
* Hand-rolled on purpose. A matcher dependency here buys four metacharacters and
* costs you a supply-chain review on the one file whose job is enforcing rules.
*
* **\/ any number of leading segments, including none
* /** this directory and everything below it
* * any run of characters inside one segment; never crosses `/`
* ? exactly one character inside one segment
*/
export function globToRegExp(glob) {
let re = '';
for (let i = 0; i < glob.length; i++) {
const c = glob[i];
if (c === '*') {
if (glob[i + 1] === '*') {
if (glob[i + 2] === '/') {
re += '(?:[^/]*/)*';
i += 2;
} else if (glob[i - 1] === '/') {
re = re.slice(0, -1) + '(?:/.*)?';
i += 1;
} else {
re += '.*';
i += 1;
}
} else {
re += '[^/]*';
}
} else if (c === '?') {
re += '[^/]';
} else {
re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
}
}
return new RegExp(`^${re}$`);
}
/** Owned when some pattern matches and no LATER `!pattern` un-matches. Order is meaningful. */
function claims(owner, file) {
let owned = false;
for (const p of owner.patterns) {
if (!p.re.test(file)) continue;
owned = !p.negated;
p.hits++;
}
return owned;
}
const ownersOf = (owners, file) => owners.filter((o) => claims(o, file)).map((o) => o.id);
/* ── Parse the map ────────────────────────────────────────────────────────────
* Two fenced-block kinds inside an ordinary Markdown file, so the map stays readable
* as documentation and parseable as config. One file, not two that can disagree.
*
* ```roster <id> <builder|reviewer> <installed|planned> [authority]
* ```surface:<id> one glob per line; `!` prefix excludes
*/
function fencedBlocks(src) {
const out = [];
for (const m of src.matchAll(/^```([^\n`]*)\n([\s\S]*?)^```$/gm)) {
out.push({ info: (m[1] ?? '').trim(), body: m[2] ?? '' });
}
return out;
}
const significant = (body) =>
body.split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
export function parseSurfaceMap(src) {
const roster = [];
const owners = [];
const errors = [];
const seenSurface = new Set();
for (const { info, body } of fencedBlocks(src)) {
if (info === 'roster') {
for (const line of significant(body)) {
const cols = line.split(/\s+/);
const [id, klass, status, authority] = cols;
if (!id || !klass || !status) { errors.push(`roster: cannot parse "${line}"`); continue; }
if (cols.length > 4) { errors.push(`roster: ${id} has ${cols.length} columns, expected at most 4 (id, class, status, authority)`); continue; }
if (klass !== 'builder' && klass !== 'reviewer') { errors.push(`roster: ${id} has unknown class "${klass}"`); continue; }
if (status !== 'installed' && status !== 'planned') { errors.push(`roster: ${id} has unknown status "${status}"`); continue; }
if (authority !== undefined && !AUTHORITY.includes(authority)) {
errors.push(`roster: ${id} has unknown authority "${authority}" — one of ${AUTHORITY.join(', ')}`);
continue;
}
if (roster.some((r) => r.id === id)) { errors.push(`roster: ${id} listed twice`); continue; }
roster.push({
id,
klass,
status,
authority: authority ?? DEFAULT_AUTHORITY,
authorityStated: authority !== undefined,
});
}
} else if (info.startsWith('surface:')) {
const id = info.slice('surface:'.length).trim();
if (seenSurface.has(id)) { errors.push(`surface: ${id} declared twice`); continue; }
seenSurface.add(id);
const patterns = significant(body).map((raw) => {
const negated = raw.startsWith('!');
const glob = negated ? raw.slice(1) : raw;
return { glob, negated, re: globToRegExp(glob), hits: 0 };
});
owners.push({ id, patterns });
}
}
return { roster, owners, errors };
}
const trackedFiles = () =>
execFileSync('git', ['ls-files'], { encoding: 'utf8' }).split('\n').filter(Boolean);
function readMap(root = '.') {
const path = join(root, MAP_FILE);
if (!existsSync(path)) {
console.error(`agent-guard: no map at ${MAP_FILE}. Write the map before the charters.`);
process.exit(2);
}
return parseSurfaceMap(readFileSync(path, 'utf8'));
}
const charterIds = () =>
existsSync(AGENT_DIR)
? readdirSync(AGENT_DIR).filter((f) => f.endsWith('.md')).map((f) => f.replace(/\.md$/, ''))
: [];
/* ── check ──────────────────────────────────────────────────────────────────── */
function check() {
const { roster, owners, errors } = readMap();
const problems = [...errors];
const notes = [];
// 1. Every tracked file has EXACTLY ONE owner.
// Two owners is a future conflict: two agents, dispatched weeks apart, both
// correctly believing the path is theirs. Zero owners is worse — whoever touches
// it first becomes its de-facto owner and nobody decided that.
const overlaps = new Map();
const unowned = [];
for (const file of trackedFiles()) {
const os = ownersOf(owners, file);
if (os.length === 0) unowned.push(file);
else if (os.length > 1) {
const key = os.sort().join(' + ');
if (!overlaps.has(key)) overlaps.set(key, []);
overlaps.get(key).push(file);
}
}
for (const [pair, files] of overlaps) {
problems.push(`overlap: ${pair} both claim ${files.length} path(s), e.g. ${files.slice(0, 3).join(', ')}`);
}
if (unowned.length) {
problems.push(`unowned: ${unowned.length} tracked path(s) belong to nobody, e.g. ${unowned.slice(0, 5).join(', ')}`);
}
// 2. Roster and charters agree in BOTH directions.
// A charter with no map row can write anywhere. A row marked `planned` whose
// charter has landed is a lie about what is dispatchable.
const charters = charterIds();
const known = new Set([...roster.map((r) => r.id), ORCHESTRATOR]);
for (const id of charters) {
if (!known.has(id)) problems.push(`charter ${id}.md has no roster row`);
const row = roster.find((r) => r.id === id);
if (row && row.status === 'planned') problems.push(`${id} is marked planned but its charter exists`);
}
for (const r of roster) {
if (r.status === 'installed' && !charters.includes(r.id)) {
problems.push(`${r.id} is marked installed but ${AGENT_DIR}/${r.id}.md does not exist`);
}
}
// 3. A reviewer holds NO write surface. Read-only has to be structural, not a promise
// made in prose inside the charter it would be violating.
for (const r of roster.filter((x) => x.klass === 'reviewer')) {
const o = owners.find((x) => x.id === r.id);
if (o && o.patterns.some((p) => !p.negated)) {
problems.push(`reviewer ${r.id} declares a write surface — reviewers are read-only`);
}
}
// 4. Authority is coherent with the surface the row actually holds.
// A reviewer holds no write surface, so gating its writes gates nothing — and a row
// reading `security-review reviewer installed proposes` looks governed while being
// the one row that never needed governing. Same failure in the other direction: a
// builder marked `proposes` that owns no surface has a checkpoint on an empty set.
for (const r of roster) {
const owned = owners.find((x) => x.id === r.id);
const writes = owned ? owned.patterns.some((p) => !p.negated) : false;
if (r.klass === 'reviewer' && isGated(r)) {
problems.push(`reviewer ${r.id} declares authority "${r.authority}" — reviewers hold no write surface, so there is nothing to gate`);
}
if (r.klass === 'builder' && isGated(r) && !writes) {
problems.push(`${r.id} declares authority "${r.authority}" but holds no write surface — the gate governs nothing`);
}
}
// A row that never stated an authority is not wrong, but it did not answer the question
// either. Say so once, the same way a stale glob is said.
const unstated = roster.filter((r) => !r.authorityStated).map((r) => r.id);
if (unstated.length) {
notes.push(`authority not stated on ${unstated.length} row(s), defaulting to ${DEFAULT_AUTHORITY}: ${unstated.join(', ')}`);
}
// 5. Decision numbers are unique. Two concurrent sessions both claiming D14 merges
// cleanly in git and fails nothing, which is exactly why it needs a guard and not
// a convention.
if (existsSync(DECISION_LOG)) {
const nums = [...readFileSync(DECISION_LOG, 'utf8').matchAll(/^#{1,6}\s+D(\d+)\b/gm)].map((m) => m[1]);
const dupes = nums.filter((n, i) => nums.indexOf(n) !== i);
if (dupes.length) problems.push(`decision log: duplicate number(s) D${[...new Set(dupes)].join(', D')}`);
notes.push(`decision log: ${nums.length} numbered entries, highest D${Math.max(...nums.map(Number), 0)}`);
}
// A pattern matching nothing is usually a rename left behind. A NOTE, not a failure —
// declaring a surface before the directory exists is legitimate.
for (const o of owners) {
for (const p of o.patterns) {
if (p.hits === 0) notes.push(`pattern matches no tracked file (reserved or stale): ${o.id}:${p.negated ? '!' : ''}${p.glob}`);
}
}
const builders = roster.filter((r) => r.klass === 'builder').length;
const reviewers = roster.filter((r) => r.klass === 'reviewer').length;
const gated = roster.filter(isGated);
for (const n of notes) console.log(` ok ${n}`);
console.log(` ok Roster: ${builders} builder(s), ${reviewers} reviewer(s), ${charters.length} charter file(s).`);
console.log(gated.length
? ` ok Authority: ${roster.length - gated.length} autonomous, ${gated.length} gated — ${gated.map((r) => `${r.id} (${r.authority})`).join(', ')}.`
: ` ok Authority: all ${roster.length} row(s) autonomous.`);
if (problems.length) {
console.error(`\nAgent surfaces FAILED — ${problems.length} problem(s):`);
for (const p of problems) console.error(` ✗ ${p}`);
process.exit(1);
}
console.log('\nAgent surfaces passed.');
}
/* ── diff ───────────────────────────────────────────────────────────────────── */
function changedPaths(base) {
// `-z` on both commands. Without it git wraps any path containing a space in literal quotes
// and octal-escapes non-ASCII bytes, so `plugins/finance/skills/a b.md` arrives as
// `"plugins/finance/skills/a b.md"` and fails the prefix test below — the guard then reports
// no violation for a file squarely inside another agent's surface. NUL-delimited output is
// the raw byte path, and it also removes the need to guess where a ` -> ` is a rename arrow
// rather than part of a filename.
if (base) {
return execFileSync('git', ['diff', '--name-only', '-z', `${base}...HEAD`], { encoding: 'utf8' })
.split('\0').filter(Boolean);
}
// Default: the working tree, because a builder has not committed. That is the point
// at which this is worth running.
const records = execFileSync('git', ['status', '--porcelain', '-z'], { encoding: 'utf8' })
.split('\0').filter(Boolean);
const paths = [];
for (let i = 0; i < records.length; i += 1) {
const status = records[i].slice(0, 2);
paths.push(records[i].slice(3));
// A rename or copy writes the destination in this record and the source in the next one.
if (status.includes('R') || status.includes('C')) i += 1;
}
return paths;
}
function diff(agentId, base) {
const { roster, owners } = readMap();
const row = roster.find((r) => r.id === agentId);
if (!row) {
console.error(`agent-guard: "${agentId}" is not in the roster.`);
process.exit(2);
}
if (agentId === ORCHESTRATOR) {
console.error('agent-guard: the orchestrator is not an agent — it legitimately spans surfaces. Nothing to check.');
process.exit(2);
}
const files = changedPaths(base);
if (files.length === 0) { console.log(' ok no changed paths.'); return; }
const mine = owners.find((o) => o.id === agentId) ?? { id: agentId, patterns: [] };
const violations = new Map();
for (const f of files) {
if (row.klass === 'builder' && claims(mine, f)) continue;
// Group by who ACTUALLY owns it — that grouping is the handoff routing information.
const real = ownersOf(owners, f);
const key = real.length ? real.join(' + ') : '(unowned)';
if (!violations.has(key)) violations.set(key, []);
violations.get(key).push(f);
}
if (violations.size === 0) {
console.log(` ok ${files.length} changed path(s), all inside ${agentId}'s surface.`);
// Clean is not the same as landable. This is the only moment the distinction is
// actionable, so it is said here rather than left to whoever remembers the map.
if (isGated(row)) {
console.log(` !! ${agentId} authority is "${row.authority}" — surface this diff for a decision before committing it.`);
}
return;
}
console.error(`\nagents:diff FAILED — ${agentId} changed path(s) outside its surface:`);
if (row.klass === 'reviewer') {
console.error(' (this is a REVIEWER. It holds no write surface, so every changed path is a violation.)');
}
for (const [owner, fs] of violations) {
console.error(`\n → belongs to ${owner} — HANDOFF:`);
for (const f of fs) console.error(` ${f}`);
}
process.exit(1);
}
/* ── main ───────────────────────────────────────────────────────────────────── */
const [mode, ...rest] = process.argv.slice(2);
const baseIdx = rest.indexOf('--base');
const base = baseIdx === -1 ? null : rest[baseIdx + 1];
if (mode === 'check') check();
else if (mode === 'diff') diff(rest[0], base);
else {
console.error('usage: agent-guard.mjs check | diff <agent-id> [--base <ref>]');
process.exit(2);
}