Skip to content

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.

Add an authority axis to the surface map

Claude9f3436ca70a8
diff --git a/docs/AGENT-SURFACES.md b/docs/AGENT-SURFACES.md
index 507518c..d39bdfc 100644
--- a/docs/AGENT-SURFACES.md
+++ b/docs/AGENT-SURFACES.md
@@ -14,34 +14,62 @@ and "UI" both end up in the same token file, and neither is wrong.
The orchestrator is neither: it owns no surface and is the sole committer.
+## Authority
+
+The class and the surface together answer *where* an agent may write. They have never answered
+whether that write may land without a decision, so in practice that was settled per dispatch, from
+memory, by whoever was driving. Authority states it once, in the same row, and `check` verifies it.
+
+- **autonomous** — dispatch it and take the result. The surface is the only gate needed.
+- **proposes** — it may do the work; the orchestrator surfaces the diff before landing it.
+- **escalates** — do not dispatch it unasked. The work itself is the decision.
+
+Two things the check enforces, both because the row would otherwise read as governed while
+governing nothing: a reviewer may not be gated, because it holds no write surface to gate; and a
+gated builder must actually own a surface.
+
+Almost every row here is `autonomous`, and that is the honest answer rather than a placeholder — a
+department writes only inside its own plugin directory, where the worst case is a bad skill in one
+department. The column exists because the one exception is real, and because a repository adopting
+this map will have more of them than this one does.
+
## Roster
```roster
-# id class status
-executive builder installed
-technology builder installed
-product builder installed
-marketing builder installed
-demand-generation builder installed
-revenue builder installed
-finance builder installed
-operations builder installed
-people builder installed
-legal-risk builder installed
-customer-experience builder installed
-data-analytics builder installed
-corporate-strategy builder installed
-security builder installed
-it-operations builder installed
-pmo builder installed
-repo-meta builder installed
-legal-risk-review reviewer installed
-security-review reviewer installed
-```
+# id class status authority
+executive builder installed autonomous
+technology builder installed autonomous
+product builder installed autonomous
+marketing builder installed autonomous
+demand-generation builder installed autonomous
+revenue builder installed autonomous
+finance builder installed autonomous
+operations builder installed autonomous
+people builder installed autonomous
+legal-risk builder installed autonomous
+customer-experience builder installed autonomous
+data-analytics builder installed autonomous
+corporate-strategy builder installed autonomous
+security builder installed autonomous
+it-operations builder installed autonomous
+pmo builder installed autonomous
+repo-meta builder installed proposes
+legal-risk-review reviewer installed autonomous
+security-review reviewer installed autonomous
+```
+
+`repo-meta` is the exception because of what it owns: the CI workflows, the check scripts, the
+generators every document is built from, and this map. A change inside `plugins/finance/**` is
+wrong in one department. A change to `scripts/check-all.sh` can make every other check stop
+reporting, and nothing downstream would fail to say so.
Charters live in `.claude/agents/`, one per installed row. A row marked `installed` without a
charter, or a charter without a row, fails the check — the two cannot drift apart silently.
+The column may be omitted; an omitted authority means `autonomous`, and `check` reports which rows
+defaulted so that a map which never considered the question is distinguishable from one that
+answered it.
+
## Surfaces
```surface:executive
diff --git a/docs/DECISION-LOG.md b/docs/DECISION-LOG.md
index 61dc2a5..f328487 100644
--- a/docs/DECISION-LOG.md
+++ b/docs/DECISION-LOG.md
@@ -952,3 +952,45 @@ toward manufacturing, logistics and retail, so they go to the verticals too.
**Remaining Tier 1**, recorded in the org chart's gaps section: customer experience depth, legal
depth, corporate strategy depth, and product discovery and prioritization. None is a missing
function; all are thin coverage of a function already present.
+
+---
+
+## D31. Authority as a second axis on the surface map — ✅ Resolved
+
+The surface map answers where an agent may write. It has never answered whether that write may
+land without a decision, and the two are not the same question. In practice the second one was
+settled per dispatch, from memory, by whoever happened to be driving — which is the condition the
+surface map itself exists to eliminate.
+
+- **(a) A fourth roster column, checked by the guard.** ← **chosen**
+- (b) State it in each charter. Prose inside the agent being governed; nothing checks it, and it is
+ invisible at the moment it matters, which is the dispatch.
+- (c) Infer it from class. Conflates "cannot write" with "may not land unreviewed" — a reviewer is
+ ungated precisely because it cannot write, and a builder's blast radius has nothing to do with
+ its class.
+- (d) Leave it implicit. The status quo, and the reason this was raised.
+
+**Resolution:** (a). Three values — `autonomous` (dispatch it and take the result), `proposes` (the
+orchestrator surfaces the diff before landing it), `escalates` (do not dispatch it unasked; the
+work itself is the decision).
+
+**Eighteen of nineteen rows are `autonomous`, and that is the honest answer rather than a
+placeholder.** A department writes only inside its own plugin directory, where the worst outcome is
+a bad skill in one department. Marking rows gated to make the column look load-bearing would be the
+decoration this repository rejects everywhere else.
+
+**The one exception is `repo-meta`, and it is a real one.** It owns the CI workflows, the check
+scripts, every generator the documents are built from, and the surface map itself. A wrong change
+under `plugins/finance/**` is wrong in one department. A wrong change to `scripts/check-all.sh` can
+make every other check stop reporting, and nothing downstream would fail to say so. That is the
+shape of thing worth a checkpoint.
+
+**Two invariants are enforced rather than described**, both catching a row that reads as governed
+while governing nothing: a reviewer may not be gated, because it holds no write surface to gate;
+and a gated builder must own a surface. Both were verified against deliberately broken maps rather
+than assumed — an unproven guard is a comment claiming to be a guard.
+
+**Existing maps keep working.** The column is optional and omission means `autonomous`, but `check`
+reports which rows defaulted, so a map that never considered the question stays distinguishable
+from one that answered it. The value here is not the single gated row; it is that the axis is now
+expressible and checked instead of remembered — the same argument that justified the surface map.
diff --git a/plugins/executive/skills/agent-hierarchy/SKILL.md b/plugins/executive/skills/agent-hierarchy/SKILL.md
index 14eefd4..561eaed 100644
--- a/plugins/executive/skills/agent-hierarchy/SKILL.md
+++ b/plugins/executive/skills/agent-hierarchy/SKILL.md
@@ -14,7 +14,10 @@ Split agents by **write surface, not by topic**. Two classes only: **builders**,
inside exactly one exclusive surface and never commit, and **reviewers**, which are permanently
read-only and can always run in parallel. The orchestrator — the main chat — is the sole
committer. Write the surface map **before** any charters, keep it in one Markdown file, and
-enforce it with a script that runs in CI. Producer and auditor are never the same agent. For
+enforce it with a script that runs in CI. Each row also carries an **authority** — `autonomous`,
+`proposes`, or `escalates` — which answers the separate question of whether that agent's work may
+land without a decision; most rows are `autonomous`, and gating everything makes the gate
+meaningless. Producer and auditor are never the same agent. For
each class of fact, exactly one file owns it and everyone else derives.
## Why topic splits fail
diff --git a/plugins/executive/skills/agent-hierarchy/references/playbook.md b/plugins/executive/skills/agent-hierarchy/references/playbook.md
index 735de5e..5225c71 100644
--- a/plugins/executive/skills/agent-hierarchy/references/playbook.md
+++ b/plugins/executive/skills/agent-hierarchy/references/playbook.md
@@ -73,11 +73,11 @@ trying to prevent.
````markdown
```roster
-# id class status
-core-owner builder installed
-ios-builder builder installed
-store-compliance reviewer installed
-telemetry reviewer planned
+# id class status authority
+core-owner builder installed proposes
+ios-builder builder installed autonomous
+store-compliance reviewer installed autonomous
+telemetry reviewer planned autonomous
```
```surface:ios-builder
@@ -94,6 +94,24 @@ apps/ios/**
**Semantics.** One glob per line. Leading `!` excludes. **Later lines win over earlier
ones.** A path may be claimed by exactly one owner.
+**The fourth roster column is authority**, and it answers the question the surface cannot:
+not *where* the agent may write, but whether that write may land without a decision.
+
+| Authority | Meaning |
+|---|---|
+| `autonomous` | Dispatch it and take the result. The surface is the only gate needed. |
+| `proposes` | It may do the work; the orchestrator surfaces the diff before landing it. |
+| `escalates` | Do not dispatch it unasked. The work itself is the decision. |
+
+Most rows are `autonomous` and should be — gate everything and the gate stops meaning
+anything. Reserve it for surfaces where the blast radius escapes the surface: the build and
+release path, dependency manifests, anything the other agents' checks run through. In the
+example above `core-owner` is gated because every consumer compiles against what it changes.
+
+Omitting the column means `autonomous`, so existing maps keep working; `check` reports which
+rows defaulted, because a map that never asked the question should be distinguishable from
+one that answered it.
+
| Pattern | Matches |
|---|---|
| `**/` | any number of leading segments, including none |
@@ -135,7 +153,10 @@ So: every claim in the map is checked against `git ls-files` on every PR.
write anywhere; a row still marked `planned` whose charter has landed is a lie about
what is dispatchable.
4. **A reviewer declares no write surface.**
-5. **Decision numbers are unique.** Two concurrent sessions both claiming `D14` merges
+5. **Authority matches the surface the row holds.** A gated reviewer reads as governed while
+ being the one row that never needed governing — it cannot write at all. A gated builder
+ owning no surface has a checkpoint on an empty set. Both fail.
+6. **Decision numbers are unique.** Two concurrent sessions both claiming `D14` merges
cleanly in git and fails nothing — which is precisely why it needs a guard and not a
convention. *(Tune this assertion's regex to your own log format; the shipped one
matches `### D<number>` headings.)*
diff --git a/plugins/executive/skills/agent-hierarchy/scripts/agent-guard.mjs b/plugins/executive/skills/agent-hierarchy/scripts/agent-guard.mjs
index c76afd6..d88a4d0 100644
--- a/plugins/executive/skills/agent-hierarchy/scripts/agent-guard.mjs
+++ b/plugins/executive/skills/agent-hierarchy/scripts/agent-guard.mjs
@@ -28,6 +28,26 @@ 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.
@@ -82,7 +102,7 @@ const ownersOf = (owners, file) => owners.filter((o) => claims(o, file)).map((o)
* 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>
+ * ```roster <id> <builder|reviewer> <installed|planned> [authority]
* ```surface:<id> one glob per line; `!` prefix excludes
*/
function fencedBlocks(src) {
@@ -105,12 +125,24 @@ export function parseSurfaceMap(src) {
for (const { info, body } of fencedBlocks(src)) {
if (info === 'roster') {
for (const line of significant(body)) {
- const [id, klass, status] = line.split(/\s+/);
+ 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 });
+ roster.push({
+ id,
+ klass,
+ status,
+ authority: authority ?? DEFAULT_AUTHORITY,
+ authorityStated: authority !== undefined,
+ });
}
} else if (info.startsWith('surface:')) {
const id = info.slice('surface:'.length).trim();
@@ -197,7 +229,30 @@ function check() {
}
}
- // 4. Decision numbers are unique. Two concurrent sessions both claiming D14 merges
+ // 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)) {
@@ -217,8 +272,12 @@ function check() {
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):`);
@@ -268,6 +327,11 @@ function diff(agentId, base) {
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:`);