@rubytech/create-sitedesk-code 0.1.513 → 0.1.515

package/payload/platform/docs/superpowers/plans/2026-07-27-task-2052-account-machinery-write-fence.md

@@ -0,0 +1,250 @@
+# Account-machinery write fence Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Stop the account agent writing the five entries in the shipped account schema that are the account's own machinery rather than operator data.
+
+**Architecture:** A new fenced `agent-denied-top-level` block in the shipped `SCHEMA.md` template lists the five names with a per-name reason. `fs-schema-guard.sh` parses it with the same awk shape it already uses for the other two fences and blocks a write whose first path segment matches, reporting `reason=account-machinery`. The `allowed-top-level` fence is not touched, so the standing reconcile keeps reading exactly what it reads today.
+
+**Tech Stack:** bash, awk, python3. The hook and its tests are plain bash; no build and no `npm install`.
+
+## Global Constraints
+
+- The deny set and each name's reason come from the account's own `SCHEMA.md`. The hook hard-codes no list.
+- `allowed-top-level` is not modified. All five names stay in it, so the standing reconcile never reports them as strays.
+- No fence means nothing is denied. An account whose `SCHEMA.md` predates this change keeps today's behaviour, matching the guard's existing fail-open posture on a missing schema and on a missing `declared-files` fence.
+- No task numbers or internal refs in any operator-visible string.
+- Block log line shape is fixed: `[fs-guard] blocked path=<rel> reason=account-machinery`.
+- The separator inside the fence is a literal TAB, matching the `declared-files` fence.
+- `fs-schema-guard-bash-post.sh` is not modified.
+- Baseline before any change: `fs-schema-guard.test.sh` is `39 passed, 0 failed`; `fs-schema-guard-bash.test.sh` is `15 passed, 0 failed`.
+
+---
+
+### Task 1: Ship the deny fence in the account schema template
+
+**Files:**
+- Modify: `platform/templates/account-schema/SCHEMA.md` (append a section after the "## Allowed top-level entries" section)
+- Test: `platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh`
+
+**Interfaces:**
+- Consumes: nothing.
+- Produces: a fenced block whose header line is exactly three backticks followed by `agent-denied-top-level`, one line per name as `name<TAB>reason`, in the order `account.json`, `SCHEMA.md`, `secrets`, `.claude`, `.git`. Task 2 parses it.
+
+This task is data only. After it the guard's behaviour is unchanged, and every pre-existing case must still pass — that is the evidence the appended fence disturbs no existing reader.
+
+- [ ] **Step 1: Write the failing assertions**
+
+Append these two assertions to `platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh`, immediately after the existing `allowed-set parse` assertion and before the `echo "----- $PASS passed, $FAIL failed -----"` line:
+
+````bash
+# Deny-fence parse == documented set. The guard reads this fence, so pinning its
+# contents here means a name cannot be added or dropped without a test edit.
+EXPECT_D="account.json SCHEMA.md secrets .claude .git"
+GOT_D=$(awk '/^```agent-denied-top-level$/{f=1;next} /^```$/{f=0} f' "$ACCT/SCHEMA.md" | cut -f1 | tr '\n' ' ' | sed 's/ *$//')
+if [ "$GOT_D" = "$EXPECT_D" ]; then echo "PASS: deny-set parse"; PASS=$((PASS+1));
+else echo "FAIL: deny-set parse: got [$GOT_D]" >&2; FAIL=$((FAIL+1)); fi
+
+# Every deny entry carries a reason column: the block message has no owning
+# plugin to name, so the schema must supply the explanation.
+NOREASON=$(awk '/^```agent-denied-top-level$/{f=1;next} /^```$/{f=0} f' "$ACCT/SCHEMA.md" | awk -F'\t' 'NF<2 || $2==""{print $1}')
+if [ -z "$NOREASON" ]; then echo "PASS: deny-set reasons"; PASS=$((PASS+1));
+else echo "FAIL: deny-set reasons missing for [$NOREASON]" >&2; FAIL=$((FAIL+1)); fi
+````
+
+- [ ] **Step 2: Run the suite to verify the new assertion fails**
+
+Run: `bash platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh`
+
+Expected: `FAIL: deny-set parse: got []` on stderr, and the run ends `----- 40 passed, 1 failed -----` with a non-zero exit. `deny-set reasons` passes at this point only because an absent fence yields no rows; it becomes meaningful after Step 3.
+
+- [ ] **Step 3: Add the fence to the template**
+
+Append this section to the end of `platform/templates/account-schema/SCHEMA.md`, after the closing fence of the `allowed-top-level` block. **The separator between each name and its reason is a literal TAB character, not spaces.**
+
+`````markdown
+## Entries you may not write
+
+Five of the entries above are this account's own machinery rather than operator
+data. Each is listed below with the reason it is off-limits. The write guard
+blocks a write whose first path segment matches one of them and quotes that
+reason back. Change any of them through the code that owns it: platform code
+writes all five, and none is written through an agent file edit.
+
+```agent-denied-top-level
+account.json	the account's identity and settings, changed through the account and admin tools
+SCHEMA.md	the layout rules the write guard itself reads, so editing it widens its own fence
+secrets	provisioned credentials, written by the code that mints each one
+.claude	the agent's own settings and hooks, seeded when the account is provisioned
+.git	the account directory's git internals, managed by git
+```
+`````
+
+- [ ] **Step 4: Verify the tab separator landed**
+
+Run:
+
+````bash
+awk '/^```agent-denied-top-level$/{f=1;next} /^```$/{f=0} f' platform/templates/account-schema/SCHEMA.md | cat -A | head -5
+````
+
+Expected: each of the five lines shows `^I` between the name and the reason, and ends `$`. If any line shows spaces instead, fix it before continuing — the guard splits on TAB and a space-separated line parses as a name with no reason.
+
+- [ ] **Step 5: Run the full guard suite**
+
+Run: `bash platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh`
+
+Expected: `----- 41 passed, 0 failed -----`. Every pre-existing case must still pass, which is the proof the appended fence does not disturb the `allowed-top-level` parse, the `declared-files` parse, or any existing account fixture.
+
+- [ ] **Step 6: Run the neighbouring suites that read the same schema**
+
+Run: `bash platform/plugins/admin/hooks/__tests__/fs-schema-guard-bash.test.sh`
+
+Expected: `----- 15 passed, 0 failed -----`
+
+Run: `bash platform/scripts/__tests__/account-schema-owned-dirs.test.sh`
+
+Expected: the suite's own pass line with zero failures. This is the regression check that the owned-dirs merge still finds and rewrites the `allowed-top-level` fence and its three marker-delimited regions with an extra fence present in the file.
+
+- [ ] **Step 7: Commit**
+
+````bash
+git add maxy-code/platform/templates/account-schema/SCHEMA.md maxy-code/platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh
+git commit -m "feat(2052): ship the agent-denied-top-level fence in the account schema template"
+````
+
+---
+
+### Task 2: The guard denies a write to a fenced name
+
+**Files:**
+- Modify: `platform/plugins/admin/hooks/fs-schema-guard.sh` (header comment block at lines 2-22; new branch inserted after the top-level check's closing `fi` at line 89)
+- Test: `platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh`
+
+**Interfaces:**
+- Consumes: the `agent-denied-top-level` fence from Task 1, `name<TAB>reason` per line.
+- Produces: exit 2 with `[fs-guard] blocked path=<rel> reason=account-machinery` on stderr, plus an operator-visible line quoting that name's reason. Nothing later depends on it.
+
+- [ ] **Step 1: Write the failing tests**
+
+Add this block to `platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh`, immediately after the `run_case "no fence no deny" ...` line and before the `# Allowed-set parse == documented set.` comment:
+
+````bash
+# Account machinery: five entries in the allowed set are the account's own
+# control plane, denied by name in the agent-denied-top-level fence. $ACCT is
+# the pristine template copy, so it carries the fence. $ACCT_M models a schema
+# written before the fence existed (names in the allowed set, fence stripped),
+# which pins the deny to the fence rather than to a list baked into the hook.
+ACCT_M=$(mktemp -d)
+trap 'rm -rf "$ACCT" "$ACCT_D" "$ACCT_F" "$ACCT_L" "$ACCT_M"' EXIT
+awk '/^```agent-denied-top-level$/{skip=1;next} skip && /^```$/{skip=0;next} !skip' "$TEMPLATE" > "$ACCT_M/SCHEMA.md"
+
+DENIED_NAMES="account.json SCHEMA.md secrets .claude .git"
+for n in $DENIED_NAMES; do
+  run_case "machinery block $n" "$(mkenv Write file_path "$n")" 2 "fs-guard. blocked path=$n reason=account-machinery"
+done
+# Segment-0 match: a nested path under a denied entry blocks for the same reason.
+run_case "machinery nested settings" "$(mkenv Write file_path '.claude/settings.json')"      2 "fs-guard. blocked path=.claude/settings.json reason=account-machinery"
+run_case "machinery nested secret"   "$(mkenv Write file_path 'secrets/cloudflare.env')"     2 "reason=account-machinery"
+# Every write tool, not just Write.
+run_case "machinery edit blocks"     "$(mkenv Edit file_path 'account.json')"                2 "reason=account-machinery"
+run_case "machinery notebook blocks" "$(mkenv NotebookEdit notebook_path '.claude/n.ipynb')" 2 "reason=account-machinery"
+# The schema's own reason reaches the operator-visible message.
+run_case "machinery reason text"     "$(mkenv Write file_path 'SCHEMA.md')"                  2 "widens its own fence"
+# An operator bucket under the same schema is unaffected.
+run_case "machinery bucket allow"    "$(mkenv Write file_path 'projects/acme/a.txt')"        0 ""
+# No fence, no deny.
+for n in $DENIED_NAMES; do
+  run_case "no deny fence allows $n" "$(mkenv Write file_path "$n")" 0 "" "$ACCT_M"
+done
+````
+
+- [ ] **Step 2: Run the suite to verify the new cases fail**
+
+Run: `bash platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh`
+
+Expected: the ten `machinery *` cases FAIL with `(exit=0, want 2; ...)`. The five `no deny fence allows *` cases and `machinery bucket allow` already pass. The run ends `----- 47 passed, 10 failed -----` with a non-zero exit.
+
+- [ ] **Step 3: Add the deny branch to the guard**
+
+In `platform/plugins/admin/hooks/fs-schema-guard.sh`, insert this block immediately after the top-level check's closing `fi` (line 89) and before the `# Declared-file check.` comment:
+
+````bash
+# Account-machinery check. Some entries in the allowed set are the account's own
+# control plane rather than operator data: the identity file, the schema this
+# hook parses, the credential store, the agent's own settings and hooks, and the
+# git dir. The allowed set says which names may EXIST at the account root, not
+# which an agent may author, so each of these is named in a second fence together
+# with the reason it is off-limits. Every one of them is written by platform code
+# from bash or Node, never through Write/Edit/NotebookEdit, so denying them costs
+# no legitimate writer. The set and its reasons come from the account's own
+# SCHEMA.md, so the hook hard-codes no list. There is no owning plugin to name
+# here, which is why this fence carries a reason column the declared-files fence
+# does not need. No fence (a schema written before the fence existed) means
+# nothing to deny — the same fail-open posture as the missing-schema case above.
+DENIED=$(awk '/^```agent-denied-top-level$/{f=1;next} /^```$/{f=0} f' "$ACCOUNT_DIR/SCHEMA.md")
+if [ -n "$DENIED" ] && printf '%s\n' "$DENIED" | awk -F'\t' -v n="$SEG0" '$1==n{found=1} END{exit !found}'; then
+  WHY=$(printf '%s\n' "$DENIED" | awk -F'\t' -v n="$SEG0" '$1==n{print $2; exit}')
+  echo "[fs-guard] blocked path=$REL reason=account-machinery" >&2
+  echo "Blocked: '$SEG0' is this account's own machinery, not operator data: $WHY. Change it through the code that owns it, never by hand." >&2
+  exit 2
+fi
+````
+
+- [ ] **Step 4: Update the hook's header comment**
+
+In the same file, in the header comment block, insert this bullet after the `allowed top-level set` bullet and before the `plugin-declared file` bullet, so the header lists all three rules the hook enforces:
+
+````bash
+#   - a target whose first path segment is named in the fenced
+#     ```agent-denied-top-level block is blocked even though that name is in the
+#     allowed set: those entries are the account's own machinery (identity,
+#     schema, credentials, agent settings, git dir), written by platform code
+#     and never by an agent file edit. The block message quotes the reason the
+#     fence carries for that name;
+````
+
+Then extend the exit-codes paragraph's log-line list so it reads:
+
+````bash
+#   [fs-guard] blocked path=<rel> reason=<top-level|account-machinery|declared-file|over-deep|bad-name>
+````
+
+- [ ] **Step 5: Run the suite to verify it passes**
+
+Run: `bash platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh`
+
+Expected: `----- 57 passed, 0 failed -----`
+
+- [ ] **Step 6: Mutation check**
+
+Comment out the `exit 2` inside the new branch and re-run the suite.
+
+Run: `bash platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh`
+
+Expected: the ten `machinery *` cases FAIL. Then restore the line and re-run.
+
+Expected after restore: `----- 57 passed, 0 failed -----`
+
+- [ ] **Step 7: Confirm the untouched surfaces still pass**
+
+Run: `bash platform/plugins/admin/hooks/__tests__/fs-schema-guard-bash.test.sh`
+
+Expected: `----- 15 passed, 0 failed -----`. The Bash post-hook still reads only `allowed-top-level` and `declared-files`, and still stays silent on all five names.
+
+Run: `bash platform/scripts/__tests__/account-schema-owned-dirs.test.sh`
+
+Expected: zero failures.
+
+- [ ] **Step 8: Commit**
+
+````bash
+git add maxy-code/platform/plugins/admin/hooks/fs-schema-guard.sh maxy-code/platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh
+git commit -m "feat(2052): deny agent writes to the account's own machinery"
+````
+
+---
+
+## Reach note for the debrief
+
+`provision-account-dir.sh:40-41` copies the template to `<accountDir>/SCHEMA.md`, and `setup-account.sh:59` calls that for the house account only. The standing all-accounts reconcile merges just the marker-delimited regions, so it never carries the template body. The house account therefore gains the fence on the next install, while a client sub-account, provisioned once at creation, keeps a fence-less schema indefinitely and the guard stays fail-open there. That gap is filed as `.tasks/pending/2056-the-account-machinery-deny-fence-never-reaches-an-existing-sub-account.md`, following the durable-backfill pattern of Task 1683 and Task 1929. Separately, `platform/` ships inside the bundled `create-*-code` payload, so reaching a device at all needs an operator-gated installer publish plus an `npx` upgrade. Both belong in the debrief's known-limitations section.

package/payload/platform/docs/superpowers/specs/2026-07-27-task-2016-disabled-agent-routing-design.md

@@ -0,0 +1,139 @@
+# Task 2016 — a disabled agent must leave the admin's routing table, and read as disabled rather than missing
+
+Design, 2026-07-27. Depends on Task 1996 (landed).
+
+## The defect
+
+Task 1996 stops dispatch by moving an agent file out of `<accountDir>/specialists/agents/`,
+the directory `spawn-context.ts` reads to build the spawn manifest. Two surfaces still
+believe the file is there.
+
+`platform/scripts/lib/agents-md-bootstrap.sh:42-47` only ever appends. A line matching
+`^- \*\*specialists:<name>\*\*:` in `agents/admin/AGENTS.md` is preserved verbatim and a
+missing one is appended; nothing is ever removed. So the admin's routing prose keeps
+advertising a specialist the operator switched off, and dispatch fails inside a turn
+against a file that is gone.
+
+`platform/plugins/admin/mcp/src/index.ts:520-533` walks the AGENTS.md entries against
+`specialists/agents/` and calls a name with no file `missing file`. An operator action is
+rendered as an install fault.
+
+## What the fix delivers
+
+1. A name the operator disabled has no routing line.
+2. Re-enabling restores it.
+3. `system-status` reports `disabled` and `missing file` as different things, and counts
+   them separately.
+
+## Surface 1 — `agents-md-bootstrap.sh` reconciles
+
+The store is `<accountDir>/agents-disabled.json`, `{ "disabled": ["<basename>.md", …] }`,
+written whole at 0600 by `platform/ui/server/routes/admin/agents.ts`. The bootstrap reads
+it with the same python3 extractor `provision-account-dir.sh:264-276` already uses, which
+accepts only strings ending `.md` with no `/` and no `..`.
+
+**The name rule.** A store entry maps to a routing line by stripping `.md`. One rule, no
+branch: all twelve files under `platform/templates/specialists/agents/` have `name:` equal
+to their filename, the disable route keys on `slug` equal to the basename, and the status
+walker at `index.ts:526` already maps a name back to `<name>.md`.
+
+**The reconcile rule.** A name in the store gets no routing line. It applies at both points
+in the script: an existing line for that name is removed, and the append loop skips that
+name. Stating it once and applying it uniformly is what makes the invariant hold in the
+drift state the standing `op=agent-parity` check exists to catch (store names it, file is
+still live) rather than only on the happy path.
+
+**An unreadable store withholds nothing.** `provision-account-dir.sh:293` already prints
+`specialists agents-disabled-store-unreadable — withholding nothing` and carries on, so
+the prose posture matches the file-withholding posture that runs immediately before it.
+
+**Observability.** The existing line stays byte-identical, because the current suite
+asserts its counts:
+
+```
+  [admin-bootstrap] AGENTS.md specialists=<n> appended=<m> existing=<k>
+```
+
+A second line is added:
+
+```
+  [agents-md] op=specialist-lines account=<id8> kept=<n> withheld=<comma-list|none|store-unreadable>
+```
+
+`id8` is the first eight characters of the account directory's basename. `kept` counts the
+`- **specialists:` lines in AGENTS.md after the run. `withheld` names the store's entries,
+sorted, as names rather than basenames; `none` when the store is absent or empty; the
+literal `store-unreadable` when it is present but does not parse.
+
+## Surface 2 — `system-status` separates disabled from missing
+
+The classification at `index.ts:520-533` moves into a new
+`platform/plugins/admin/mcp/src/specialist-registry.ts`, beside `skill-resolution.ts` and
+`store-skill-core.ts`, which are the same shape: a module `index.ts` imports and a
+`node:test` suite covers. It exports one function taking the AGENTS.md text, the
+specialists directory, the account directory and whether Chrome is up, and returning the
+per-name lines plus the two counts.
+
+Status, in order:
+
+- the file exists in `specialists/agents/` → `ok`, except `personal-assistant` with Chrome
+  down, which keeps today's `degraded — chrome not running`;
+- otherwise the name is in the store → `disabled (operator)`;
+- otherwise → `missing file`.
+
+The header becomes `<n> registered, missing=<x> disabled=<y>`. An unreadable store is
+tolerated the same way the bootstrap tolerates it: no names classify as disabled, and the
+absent file stays `missing file`, which is the honest answer when the store cannot be read.
+
+With surface 1 in place a disabled agent has no AGENTS.md line at all, so in the steady
+state `disabled=0`. The classification earns its place in the drift window: an account
+disabled before this change carries the stale line until a provisioning run or a
+disable/enable call reconciles it, and that is exactly when the operator needs the line to
+read `disabled` rather than `missing file`.
+
+## Surface 3 — the disable path reconciles immediately
+
+`agents.ts` currently leaves AGENTS.md untouched, so prose is only correct after the next
+provisioning run. After the file move and the store write, both handlers exec
+`bash <PLATFORM_ROOT>/scripts/lib/agents-md-bootstrap.sh <accountDir>` with a timeout.
+`platform/scripts` ships in the payload (`packages/create-maxy-code/scripts/bundle.js:318`
+copies the whole `platform` tree minus the listed exclusions), and `claude-info.ts:33`
+is the precedent for `execFileSync` in an admin route.
+
+Enable needs no separate restore path. The file is live again by the time the script runs,
+so the append loop puts the line back and the store no longer names it.
+
+**Failure posture.** A failed exec does not turn the request into a 500: the file move and
+the store write already happened, and dispatch is already stopped, so reporting the whole
+disable as failed would be false. The handler logs
+`[admin/agents] op=agents-md-reconcile accountId=<id8> slug=<slug> outcome=failed reason="…"`
+and the response carries `routingReconciled: false`, so no caller is told the prose is
+correct when it is not.
+
+## Tests
+
+**Shell, `platform/scripts/__tests__/agents-md-bootstrap.test.sh`.** Against the existing
+three-specialist temp account: a store naming one of them leaves no line for it and keeps
+the other two, and the `op=specialist-lines` line reports `kept=2 withheld=<that name>`;
+clearing the store restores the line on the next run; a malformed store removes nothing and
+reports `withheld=store-unreadable`. The pre-existing cases run unchanged with no store on
+disk.
+
+**Route, `platform/ui/server/routes/admin/__tests__/agents.test.ts`.** The harness mocks
+`PLATFORM_ROOT` to a temp tree; the real bootstrap script is copied into
+`<platformRoot>/scripts/lib/` so the exec runs the shipped code rather than a stub. A
+disable leaves no `specialists:<name>` line in the account's AGENTS.md; the following
+enable puts it back.
+
+**MCP, `platform/plugins/admin/mcp/src/__tests__/specialist-registry.test.ts`
+(`node:test`).** A temp account with three AGENTS.md entries: one live file, one named by
+the store, one neither. Asserts `ok`, `disabled (operator)`, `missing file`, and
+`missing=1 disabled=1`. A `missing file` line for a name in the store is a failure.
+
+## Out of scope
+
+- The disable mechanism, the quarantine directory, and the store format (Task 1996).
+- What AGENTS.md is for, and its append-only posture for anything that is not a specialist
+  routing line.
+- The `op=agent-parity` check, which already covers store-versus-directory drift.
+- `AGENTS.md` write permissions, which is Task 2057.

package/payload/platform/docs/superpowers/specs/2026-07-27-task-2028-declared-file-write-deny-design.md

@@ -121,6 +121,7 @@ rather than flip it silently.
 
 - The fence's pre-existing permissiveness for `account.json`, `secrets/` and
   `.claude/`. It predates Task 1902 and is a separate decision, filed as
-  `.tasks/pending/2048-the-allowed-fence-permits-agent-writes-to-the-account-s-own-machinery.md`.
+  `.tasks/archive/2052-the-allowed-fence-permits-agent-writes-to-the-account-s-own-machinery.md`
+  (renumbered from 2048; landed 2026-07-27).
 - The reconcile. It reads the fence correctly and needs no change.
 - Adding or removing declarations. Task 1902 settled the set.

package/payload/platform/docs/superpowers/specs/2026-07-27-task-2052-account-machinery-write-fence-design.md

@@ -0,0 +1,150 @@
+# Task 2052 — the write guard denies the account's own machinery
+
+Design, 2026-07-27. Lane: Platform / account schema · write guard.
+
+## The fault
+
+`fs-schema-guard.sh` allows a `Write`, `Edit` or `NotebookEdit` whose first path
+segment is in the account's ```` ```allowed-top-level ```` fence. The shipped
+template lists `account.json`, `SCHEMA.md`, `secrets/`, `.claude/` and `.git`, so
+each is agent-writable. Measured against the untouched shipped template, an
+envelope targeting `account.json` returns exit 0.
+
+None of the five is operator data:
+
+- `account.json` carries the account identity, role, tier and enabled plugins.
+  `admin-user-management/SKILL.md:39` states the position already: "Direct `Edit`
+  or `Write` on `account.json` is forbidden by IDENTITY.md doctrine — there is no
+  server-side gate, so the doctrine line is the only thing standing between an
+  agent slip and a silently corrupted account file." Mutations have dedicated
+  tools (`account-update`, `plugin-toggle-enabled`, `admin-add`, `admin-remove`).
+- `SCHEMA.md` is the schema the guard itself parses. A write to it widens the
+  fence the guard reads on the next call.
+- `.claude/` holds the account's project-level `settings.json`, which is where
+  `provision-account-dir.sh:62,77-143` registers this guard and both Bash hooks. A
+  write to it can delete the guard's own registration.
+- `secrets/` holds provisioned credentials.
+- `.git` is the account directory's git repository, created at
+  `provision-account-dir.sh:59` so Claude Code discovers `.claude/`.
+
+## Decision per name
+
+All five are denied to the agent's write tools. No legitimate agent
+`Write`/`Edit`/`NotebookEdit` path exists for any of them:
+
+| Name | Who writes it |
+|---|---|
+| `account.json` | `provision-account-dir.sh:310-349` and the account MCP tools |
+| `SCHEMA.md` | `provision-account-dir.sh:40-41` and the owned-dirs merge |
+| `secrets/` | the code that mints each credential; the one skill-instructed path is a Bash append (`cloudflare/skills/data-portal/SKILL.md:161`), which this guard never sees |
+| `.claude/` | `provision-account-dir.sh:26,61-143` |
+| `.git` | git itself |
+
+## Design
+
+### 1. A third fence, shipped in the template
+
+`platform/templates/account-schema/SCHEMA.md` gains a fenced block below the
+allowed-top-level section:
+
+````
+```agent-denied-top-level
+account.json	the account's identity and settings, changed through the account and admin tools
+SCHEMA.md	the schema this guard reads, so a hand edit widens the guard's own fence
+secrets	provisioned credentials, written by the code that mints each one
+.claude	the agent's own settings and hooks, seeded when the account is provisioned
+.git	the account directory's git internals
+```
+````
+
+One line per name as `name<TAB>reason`, the same shape as the `declared-files`
+fence. The reason column exists because there is no owning plugin to name here,
+so the block message needs the schema to supply its own explanation.
+
+The block is authored in the template rather than generated. The owned-dirs merge
+(`account-schema-owned-dirs.py`) rewrites only its three marker-delimited regions
+and the `allowed-top-level` fence in place, so a fence in the template body
+survives a re-merge untouched. `allowed-top-level` is not modified, so the
+standing reconcile keeps reading exactly what it reads today and still never
+names any of the five as a stray — the one-list-two-meanings fault Task 2028
+fixed is not reintroduced.
+
+### 2. The guard denies
+
+`fs-schema-guard.sh` parses the new fence with one awk expression, the same shape
+it uses for the other two. The check sits after the top-level check and before
+the declared-file check, and matches on the first path segment, so
+`.claude/settings.json` and `secrets/cloudflare.env` are both blocked. No name is
+in both fences (the declared set is the six platform-written `*.json` files the
+merge emits), so the ordering never changes which reason is reported.
+
+```
+[fs-guard] blocked path=<rel> reason=account-machinery
+```
+
+The operator-visible line names the segment and carries that name's reason from
+the fence, then points at the code that owns it. No task numbers or internal refs
+appear in it, per the guard's existing rule.
+
+An account whose `SCHEMA.md` carries no `agent-denied-top-level` fence denies
+nothing. That is the same fail-open posture the guard already takes on a missing
+schema and on a missing `declared-files` fence.
+
+Which accounts lack it is not uniform, and the split matters. The fence lives in
+the template body, and only `provision_account_dir` copies that body
+(`provision-account-dir.sh:40-41`, an unconditional `cp` of the whole template).
+`setup-account.sh:59` calls it once, for the house account. The standing
+all-accounts reconcile merges only the marker-delimited regions. So the house
+account gains the fence on the next install, and a client sub-account, which is
+provisioned once at creation, keeps a fence-less schema indefinitely. Closing
+that is filed as `.tasks/pending/2056-the-account-machinery-deny-fence-never-reaches-an-existing-sub-account.md`,
+following the durable-backfill pattern Task 1683 and Task 1929 already
+established in `setup-account.sh`.
+
+### 3. Provision and reconcile are unaffected
+
+Both write `SCHEMA.md` and `account.json`, and neither goes through the agent's
+write tools: provisioning is bash (`provision-account-dir.sh`) and the standing
+reconcile is Node (`account-dir-schema-reconcile.ts`). The guard is a PreToolUse
+hook on `Write`/`Edit`/`NotebookEdit` only, so it never sees either writer.
+
+### 4. The Bash post-hook stays unchanged
+
+`fs-schema-guard-bash-post.sh` reads `allowed-top-level` and the `declared-files`
+fence. This change touches neither, and all five names stay in `allowed-top-level`,
+so the post hook keeps not flagging them. That is the deliberate choice, not an
+inherited one: the post hook fires only on a top-level name that appeared during
+the command, and `account.json`, `SCHEMA.md`, `.claude` and `.git` all exist from
+provision onward, so a signal there would catch nothing on a live account.
+
+## Testing
+
+`fs-schema-guard.test.sh` gains:
+
+- one case per name asserting exit 2 with `reason=account-machinery` and that
+  name's reason text present in the message;
+- a nested case for `.claude/settings.json` and `secrets/cloudflare.env`
+  asserting exit 2, pinning the segment-0 match;
+- an operator bucket write under the same schema asserting exit 0;
+- a case under a schema that lists the five in `allowed-top-level` but carries no
+  `agent-denied-top-level` fence asserting exit 0, which pins the deny to the
+  fence rather than to a list baked into the hook;
+- the existing template-parity assertion extended so the shipped fence contents
+  are pinned.
+
+Mutation check: remove the deny branch and confirm the per-name cases fail.
+Revert.
+
+The reconcile suite and `fs-schema-guard-bash.test.sh` must both still pass
+unchanged, which is the evidence that `allowed-top-level` was not disturbed.
+
+## Out of scope
+
+- The `declared-files` fence and the plugin-declaration mechanism. Task 2028
+  settled both.
+- `.quarantine`, which is historical and already documented as never authored
+  into directly.
+- `AGENTS.md`, which is in the allowed fence but outside the five names this task
+  names. The same overwritten-on-provision rationale may apply to it; that
+  decision is filed as
+  `.tasks/backlog/2057-agents-md-is-refreshed-every-provision-but-stays-agent-writable.md`.

package/payload/platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh

@@ -125,11 +125,52 @@ run_case "declared edit blocks"   "$(mkenv Edit file_path 'wa-channel-bindings.j
 run_case "operator bucket allow"  "$(mkenv Write file_path 'projects/acme/a.txt')"      0 ""                     "$ACCT_F"
 run_case "no fence no deny"       "$(mkenv Write file_path 'wa-channel-bindings.json')" 0 ""                     "$ACCT_L"
 
+# Account machinery: five entries in the allowed set are the account's own
+# control plane, denied by name in the agent-denied-top-level fence. $ACCT is
+# the pristine template copy, so it carries the fence. $ACCT_M models a schema
+# written before the fence existed (names in the allowed set, fence stripped),
+# which pins the deny to the fence rather than to a list baked into the hook.
+ACCT_M=$(mktemp -d)
+trap 'rm -rf "$ACCT" "$ACCT_D" "$ACCT_F" "$ACCT_L" "$ACCT_M"' EXIT
+awk '/^```agent-denied-top-level$/{skip=1;next} skip && /^```$/{skip=0;next} !skip' "$TEMPLATE" > "$ACCT_M/SCHEMA.md"
+
+DENIED_NAMES="account.json SCHEMA.md secrets .claude .git"
+for n in $DENIED_NAMES; do
+  run_case "machinery block $n" "$(mkenv Write file_path "$n")" 2 "fs-guard. blocked path=$n reason=account-machinery"
+done
+# Segment-0 match: a nested path under a denied entry blocks for the same reason.
+run_case "machinery nested settings" "$(mkenv Write file_path '.claude/settings.json')"      2 "fs-guard. blocked path=.claude/settings.json reason=account-machinery"
+run_case "machinery nested secret"   "$(mkenv Write file_path 'secrets/cloudflare.env')"     2 "reason=account-machinery"
+# Every write tool, not just Write.
+run_case "machinery edit blocks"     "$(mkenv Edit file_path 'account.json')"                2 "reason=account-machinery"
+run_case "machinery notebook blocks" "$(mkenv NotebookEdit notebook_path '.claude/n.ipynb')" 2 "reason=account-machinery"
+# The schema's own reason reaches the operator-visible message.
+run_case "machinery reason text"     "$(mkenv Write file_path 'SCHEMA.md')"                  2 "widens its own fence"
+# An operator bucket under the same schema is unaffected.
+run_case "machinery bucket allow"    "$(mkenv Write file_path 'projects/acme/a.txt')"        0 ""
+# No fence, no deny.
+for n in $DENIED_NAMES; do
+  run_case "no deny fence allows $n" "$(mkenv Write file_path "$n")" 0 "" "$ACCT_M"
+done
+
 # Allowed-set parse == documented set.
 EXPECT="projects contacts documents url-get output generated extracted uploads agents specialists sites public cache secrets state logs tmp .quarantine SCHEMA.md account.json AGENTS.md .claude .git"
 GOT=$(awk '/^```allowed-top-level$/{f=1;next} /^```$/{f=0} f' "$ACCT/SCHEMA.md" | tr '\n' ' ' | sed 's/ *$//')
 if [ "$GOT" = "$EXPECT" ]; then echo "PASS: allowed-set parse"; PASS=$((PASS+1));
 else echo "FAIL: allowed-set parse: got [$GOT]" >&2; FAIL=$((FAIL+1)); fi
 
+# Deny-fence parse == documented set. The guard reads this fence, so pinning its
+# contents here means a name cannot be added or dropped without a test edit.
+EXPECT_D="account.json SCHEMA.md secrets .claude .git"
+GOT_D=$(awk '/^```agent-denied-top-level$/{f=1;next} /^```$/{f=0} f' "$ACCT/SCHEMA.md" | cut -f1 | tr '\n' ' ' | sed 's/ *$//')
+if [ "$GOT_D" = "$EXPECT_D" ]; then echo "PASS: deny-set parse"; PASS=$((PASS+1));
+else echo "FAIL: deny-set parse: got [$GOT_D]" >&2; FAIL=$((FAIL+1)); fi
+
+# Every deny entry carries a reason column: the block message has no owning
+# plugin to name, so the schema must supply the explanation.
+NOREASON=$(awk '/^```agent-denied-top-level$/{f=1;next} /^```$/{f=0} f' "$ACCT/SCHEMA.md" | awk -F'\t' 'NF<2 || $2==""{print $1}')
+if [ -z "$NOREASON" ]; then echo "PASS: deny-set reasons"; PASS=$((PASS+1));
+else echo "FAIL: deny-set reasons missing for [$NOREASON]" >&2; FAIL=$((FAIL+1)); fi
+
 echo "----- $PASS passed, $FAIL failed -----"
 [ $FAIL -eq 0 ]

package/payload/platform/plugins/admin/hooks/fs-schema-guard-bash-post.sh

@@ -28,6 +28,14 @@
 # declared-files fence; this hook stays quiet, and a case in the test suite pins
 # the silence.
 #
+# The same reasoning covers the ```agent-denied-top-level fence, and for the same
+# reason it needs no code here: those five names are in the allowed set too, and
+# account.json, SCHEMA.md, .claude and .git all exist from provision onward, so
+# they can never APPEAR during a command on a live account. secrets/ can appear
+# once, and is deliberately left alone — the data-portal skill creates it with a
+# shell redirect as its sanctioned path, so flagging that first creation would
+# fire on the one legitimate writer and stay blind to every edit after it.
+#
 # Exit codes: 0 = allow, 2 = feedback to the agent (stderr shown). Fail open
 # (exit 0) when the snapshot is missing or the allowed set is empty. Every block
 # logs: [fs-guard-bash] stray path=<name> reason=<top-level|bad-name>