@rubytech/create-sitedesk-code 0.1.511 → 0.1.513

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-sitedesk-code",
-  "version": "0.1.511",
+  "version": "0.1.513",
   "description": "Install SiteDesk — automated back office for independent building contractors",
   "bin": {
     "create-sitedesk-code": "./dist/index.js"

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

@@ -0,0 +1,303 @@
+# Task 2028 — declared-file write deny: implementation plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** The write guard blocks an agent `Write`/`Edit`/`NotebookEdit` to a plugin-declared account-root file, naming the owning plugin, while an operator bucket in the same fence still passes.
+
+**Architecture:** The merge emits a third generated region carrying `name<TAB>owning-plugin` inside a ```` ```declared-files ```` fence. The guard parses that fence with the same one-line awk it already uses for `allowed-top-level`, and denies after the top-level check passes. `allowed-top-level` itself is untouched, so the standing reconcile is unaffected.
+
+**Tech Stack:** bash (PreToolUse/PostToolUse hooks), python3 (schema merge), bash test suites.
+
+## Global Constraints
+
+- No task numbers or internal refs in any operator-visible string (existing hook rule, stated in both hook headers).
+- The guard never hard-codes a file list; the account's own `SCHEMA.md` is the only source.
+- Fail-open posture is preserved: no `declared-files` fence means nothing to deny.
+- The block log keeps the existing shape: `[fs-guard] blocked path=<rel> reason=<...>`.
+- Spec: `platform/docs/superpowers/specs/2026-07-27-task-2028-declared-file-write-deny-design.md`.
+
+---
+
+### Task 1: The merge emits the declared-files region
+
+**Files:**
+- Modify: `platform/scripts/lib/account-schema-owned-dirs.py` (module constants; `merge()`)
+- Test: `platform/scripts/__tests__/account-schema-owned-dirs.test.sh`
+
+**Interfaces:**
+- Produces: a region delimited by `<!-- declared-files:start -->` / `<!-- declared-files:end -->` containing a ```` ```declared-files ```` fence, one `name<TAB>plugin` line per declared file in `resolve()` order. Task 2's guard consumes exactly that fence.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `platform/scripts/__tests__/account-schema-owned-dirs.test.sh`, after the existing platform-plugin declarations block:
+
+```bash
+# --- declared-files fence: one name<TAB>plugin line per declared file -------
+DECL="$(awk '/^```declared-files$/{f=1;next} /^```$/{f=0} f' "$A_MX/SCHEMA.md")"
+assert_grep "$(printf 'wa-channel-bindings.json\tadmin')" "$DECL" "mx-decl-wa"
+assert_grep "$(printf 'agents-disabled.json\tadmin')" "$DECL" "mx-decl-agents-disabled"
+assert_grep "$(printf 'data-portal.json\tcloudflare')" "$DECL" "mx-decl-portal"
+assert_grep "$(printf 'calendar-availability.json\tscheduling')" "$DECL" "mx-decl-availability"
+assert_nogrep "e-sign" "$DECL" "mx-decl-excludes-dirs"
+assert_grep "declared-files:start" "$(cat "$A_MX/SCHEMA.md")" "mx-decl-marker"
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `bash platform/scripts/__tests__/account-schema-owned-dirs.test.sh`
+Expected: FAIL on `mx-decl-wa` and the other new assertions (no such fence yet).
+
+- [ ] **Step 3: Write the implementation**
+
+In `platform/scripts/lib/account-schema-owned-dirs.py`, beside the existing marker constants:
+
+```python
+DECL_START = "<!-- declared-files:start -->"
+DECL_END = "<!-- declared-files:end -->"
+```
+
+In `merge()`, add the strip beside the two existing strips:
+
+```python
+    text = _strip_region(text, DECL_START, DECL_END)
+```
+
+and append the region after the ontology region is appended:
+
+```python
+    declared = [e for e in owned if e["kind"] == "file"]
+    if declared:
+        region = [DECL_START, "## Declared files (written by their owning plugin)", "",
+                  "Each file below is written whole by the plugin named beside it. It is",
+                  "control-plane state, not operator data, and is not hand-edited: change",
+                  "it through the owning plugin's own tool. The write guard reads this",
+                  "block and blocks a write whose first path segment is one of these",
+                  "names, which the allowed-top-level set above cannot express — that set",
+                  "lists what may exist at the root, not what may be authored by hand.", "",
+                  "```declared-files"]
+        for e in declared:
+            region.append(f"{e['name']}\t{e['plugin']}")
+        region.append("```")
+        region.append(DECL_END)
+        text = text.rstrip("\n") + "\n\n" + "\n".join(region) + "\n"
+```
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `bash platform/scripts/__tests__/account-schema-owned-dirs.test.sh`
+Expected: PASS, including the pre-existing `idempotent-second-merge` assertion.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add platform/scripts/lib/account-schema-owned-dirs.py platform/scripts/__tests__/account-schema-owned-dirs.test.sh
+git commit -m "feat(2028): merge emits a declared-files fence carrying each file's owning plugin"
+```
+
+---
+
+### Task 2: The guard denies a write to a declared file
+
+**Files:**
+- Modify: `platform/plugins/admin/hooks/fs-schema-guard.sh` (header comment; new check after the top-level check)
+- Test: `platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh`
+
+**Interfaces:**
+- Consumes: the ```` ```declared-files ```` fence from Task 1, lines `name<TAB>plugin`.
+- Produces: `[fs-guard] blocked path=<rel> reason=declared-file` on stderr, exit 2.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh`, after the `ACCT_D` setup:
+
+```bash
+# A third account modelling a merged schema: the eight declared files are in the
+# allowed set (as the merge unions them) AND in the declared-files fence.
+ACCT_F=$(mktemp -d)
+trap 'rm -rf "$ACCT" "$ACCT_D" "$ACCT_F" "$ACCT_L"' EXIT
+DECLARED_FILES="webchat-channel-bindings.json wa-channel-bindings.json telegram-channel-bindings.json canonical-webchat-session.json session-titles.json agents-disabled.json data-portal.json calendar-availability.json"
+seed_declared() { # $1=acct  $2=with-fence(yes|no)
+  cp "$TEMPLATE" "$1/SCHEMA.md"
+  for f in $DECLARED_FILES; do
+    awk -v n="$f" '1; /^```allowed-top-level$/{print n}' "$1/SCHEMA.md" > "$1/SCHEMA.md.tmp" && mv "$1/SCHEMA.md.tmp" "$1/SCHEMA.md"
+  done
+  [ "$2" = "yes" ] || return 0
+  { echo; echo '<!-- declared-files:start -->'; echo '```declared-files'
+    for f in $DECLARED_FILES; do
+      case "$f" in
+        data-portal.json) printf '%s\tcloudflare\n' "$f" ;;
+        calendar-availability.json) printf '%s\tscheduling\n' "$f" ;;
+        *) printf '%s\tadmin\n' "$f" ;;
+      esac
+    done
+    echo '```'; echo '<!-- declared-files:end -->'; } >> "$1/SCHEMA.md"
+}
+seed_declared "$ACCT_F" yes
+mkdir -p "$ACCT_F/projects/acme"
+
+# A fourth account in the pre-2028 state: the names are in the allowed set, but
+# no declared-files fence exists. Pins that the deny comes from the fence and
+# not from a list baked into the hook.
+ACCT_L=$(mktemp -d)
+seed_declared "$ACCT_L" no
+
+for f in $DECLARED_FILES; do
+  case "$f" in
+    data-portal.json) owner=cloudflare ;;
+    calendar-availability.json) owner=scheduling ;;
+    *) owner=admin ;;
+  esac
+  run_case "declared block $f" "$(mkenv Write file_path "$f")" 2 "fs-guard. blocked path=$f reason=declared-file" "$ACCT_F"
+  run_case "declared owner $f" "$(mkenv Write file_path "$f")" 2 "$owner plugin"                                  "$ACCT_F"
+done
+run_case "operator bucket allow"  "$(mkenv Write file_path 'projects/acme/a.txt')"       0 "" "$ACCT_F"
+run_case "declared edit block"    "$(mkenv Edit file_path 'wa-channel-bindings.json')"   2 "reason=declared-file" "$ACCT_F"
+run_case "no fence no deny"       "$(mkenv Write file_path 'wa-channel-bindings.json')"  0 "" "$ACCT_L"
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `bash platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh`
+Expected: FAIL on every `declared block`/`declared owner` case with `exit=0, want 2`; `no fence no deny` already passes.
+
+- [ ] **Step 3: Write the implementation**
+
+In `platform/plugins/admin/hooks/fs-schema-guard.sh`, immediately after the top-level check block:
+
+```bash
+# Declared-file check. A file a plugin declares in its PLUGIN.md is written
+# whole by that plugin, so an agent write to it is blocked even though its name
+# is in the allowed set: that set lists what may exist at the account root, not
+# what may be authored by hand. The set and its owner come from the account's
+# own SCHEMA.md — the hook hard-codes no list. No fence (a brand declaring no
+# files, or a schema predating the block) means nothing to deny, the same
+# fail-open posture as the missing-schema case above.
+DECLARED=""
+if [ -f "$ACCOUNT_DIR/SCHEMA.md" ]; then
+  DECLARED=$(awk '/^```declared-files$/{f=1;next} /^```$/{f=0} f' "$ACCOUNT_DIR/SCHEMA.md")
+fi
+if [ -n "$DECLARED" ] && printf '%s\n' "$DECLARED" | awk -F'\t' -v n="$SEG0" '$1==n{found=1} END{exit !found}'; then
+  OWNER=$(printf '%s\n' "$DECLARED" | awk -F'\t' -v n="$SEG0" '$1==n{print $2; exit}')
+  [ -z "$OWNER" ] && OWNER="owning"
+  echo "[fs-guard] blocked path=$REL reason=declared-file" >&2
+  echo "Blocked: '$SEG0' is written whole by the $OWNER plugin. It is control-plane state, not operator data, and a hand-written copy is overwritten by its owner's next write. Change it through the $OWNER plugin's own tool." >&2
+  exit 2
+fi
+```
+
+Update the header comment's reason list to `reason=<top-level|declared-file|over-deep|bad-name>` and add one line to the enforcement summary: a target whose first segment is a declared file is blocked.
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `bash platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh`
+Expected: PASS on all cases, including the pre-existing ten.
+
+- [ ] **Step 5: Mutation check**
+
+Comment out the `exit 2` inside the new block, re-run the suite, confirm the 16 declared cases fail, then restore.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add platform/plugins/admin/hooks/fs-schema-guard.sh platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh
+git commit -m "feat(2028): the write guard denies a write to a plugin-declared file"
+```
+
+---
+
+### Task 3: The Bash post-hook decision is stated and pinned
+
+**Files:**
+- Modify: `platform/plugins/admin/hooks/fs-schema-guard-bash-post.sh` (header comment only)
+- Test: `platform/plugins/admin/hooks/__tests__/fs-schema-guard-bash.test.sh`
+
+**Interfaces:**
+- Consumes: nothing new. The behaviour under test is the existing allowed-set diff.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `platform/plugins/admin/hooks/__tests__/fs-schema-guard-bash.test.sh`:
+
+```bash
+# --- 10. Bash creating a declared file -> silent, by decision ---------------
+# A declared file is in the allowed set, so the diff never flags it. Kept
+# deliberately: this hook sees only names that appeared during the command and
+# cannot tell a hand-written copy from the owner's own script creating it.
+D=$(new_acct)
+awk '1; /^```allowed-top-level$/{print "wa-channel-bindings.json"}' "$D/SCHEMA.md" > "$D/SCHEMA.md.tmp" && mv "$D/SCHEMA.md.tmp" "$D/SCHEMA.md"
+run_pre "$D" "$(env_json PreToolUse Bash "$SID")" "$ef"
+printf '{}' > "$D/wa-channel-bindings.json"
+run_post "$D" "$(env_json PostToolUse Bash "$SID")" "$ef"
+check "post silent on declared file" 0 $? "" "$(cat "$ef")"
+```
+
+- [ ] **Step 2: Run the test**
+
+Run: `bash platform/plugins/admin/hooks/__tests__/fs-schema-guard-bash.test.sh`
+Expected: PASS. This test pins existing behaviour rather than driving a change; it fails only if a future edit makes the post hook flag declared files.
+
+- [ ] **Step 3: State the decision in the hook**
+
+Add to the header comment of `platform/plugins/admin/hooks/fs-schema-guard-bash-post.sh`:
+
+```
+# A declared file (a name a plugin declares as its own in PLUGIN.md) is in the
+# allowed set, so this hook never flags one. That silence is a decision, not an
+# accident: the diff sees only names that appeared during this command, so it
+# cannot tell the agent hand-writing the file from the agent running the owner's
+# own script (the portal index push, the availability publish), and feedback
+# would fire on the legitimate path. The Write/Edit guard blocks the hand-write
+# it can actually identify; this hook stays quiet. A test pins the silence.
+```
+
+- [ ] **Step 4: Re-run both hook suites**
+
+Run: `bash platform/plugins/admin/hooks/__tests__/fs-schema-guard-bash.test.sh && bash platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh`
+Expected: PASS on both.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add platform/plugins/admin/hooks/fs-schema-guard-bash-post.sh platform/plugins/admin/hooks/__tests__/fs-schema-guard-bash.test.sh
+git commit -m "docs(2028): state and pin the Bash post-hook's silence on declared files"
+```
+
+---
+
+### Task 4: End-to-end against the real brand tree
+
+**Files:** none modified. Verification only.
+
+- [ ] **Step 1: Merge a real schema and read the fence**
+
+```bash
+ACCT=$(mktemp -d) && cp platform/templates/account-schema/SCHEMA.md "$ACCT/SCHEMA.md"
+PROJECT_DIR="$PWD/platform" python3 platform/scripts/lib/account-schema-owned-dirs.py merge "$ACCT"
+awk '/^```declared-files$/{f=1;next} /^```$/{f=0} f' "$ACCT/SCHEMA.md"
+```
+
+Expected: eight `name<TAB>plugin` lines.
+
+- [ ] **Step 2: Drive the real hook against that merged account**
+
+```bash
+( cd "$ACCT" && printf '{"tool_name":"Write","tool_input":{"file_path":"wa-channel-bindings.json"}}' \
+  | bash "$OLDPWD/platform/plugins/admin/hooks/fs-schema-guard.sh"; echo "exit=$?" )
+```
+
+Expected: `reason=declared-file` on stderr and `exit=2`, against the same envelope that returned exit 0 before this change.
+
+- [ ] **Step 3: Confirm the reconcile still names no declared file as a stray**
+
+```bash
+PROJECT_DIR="$PWD/platform" python3 platform/scripts/lib/account-schema-owned-dirs.py reconcile "$ACCT" | grep ownedFile
+```
+
+Expected: `present=true` on every line.
+
+---
+
+## Self-review
+
+- Spec coverage: emission (Task 1), deny (Task 2), Bash decision (Task 3), the spec's testing section (Tasks 1-3 plus the mutation check in Task 2 and the end-to-end in Task 4).
+- One spec sentence is tightened here: the "no fence" case uses an account whose allowed set already carries the names, because under the pristine template those names block as `top-level` and would not prove anything about the new branch.

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

@@ -0,0 +1,126 @@
+# Task 2028 — the write guard tells a declared file from an operator bucket
+
+Design, 2026-07-27. Lane: Platform / account schema · write guard.
+
+## The fault
+
+`fs-schema-guard.sh` is the PreToolUse guard for `Write`, `Edit` and `NotebookEdit`.
+It parses the account's ```` ```allowed-top-level ```` fence and blocks a write whose
+first path segment is absent from it. The standing reconcile parses the same fence
+to decide what is not a stray. One list, two meanings.
+
+Task 1902 declared eight control-plane files so the reconcile would stop naming
+them. Because names union into that one fence, the guard began allowing
+agent writes to them: measured, the same envelope returns exit 2 against the
+pre-merge schema and exit 0 against the merged one for `wa-channel-bindings.json`,
+`telegram-channel-bindings.json`, `webchat-channel-bindings.json`,
+`canonical-webchat-session.json`, `session-titles.json`, `agents-disabled.json`,
+`calendar-availability.json` and `data-portal.json`.
+
+The fence already permits `account.json`, `SCHEMA.md`, `secrets/` and `.claude/` on
+the untouched shipped template, so it is a layout guard, not a trust boundary. This
+task makes the guard enforce the intent the generated region already states: a
+declared file "is written whole by its owner. Neither is operator data."
+
+## Design
+
+### 1. A second fence, emitted by the merge
+
+`account-schema-owned-dirs.py` `merge()` gains a third generated region, written
+with the same strip-then-append shape as the two that exist, so a re-merge is
+idempotent:
+
+```
+<!-- declared-files:start -->
+## Declared files (written by platform code, owned by a plugin)
+
+...one paragraph of prose...
+
+```declared-files
+webchat-channel-bindings.json	admin
+wa-channel-bindings.json	admin
+data-portal.json	cloudflare
+```
+<!-- declared-files:end -->
+```
+
+One line per platform-written declared file, in `resolve()` order, as
+`name<TAB>owning-plugin`. The region is emitted only when at least one such file
+is declared.
+
+**Two of the eight declared files are agent-written, and are excluded.** The
+review established that `calendar-availability.json` and `data-portal.json` have
+no writer in platform code: `publish-availability.ts:151` and
+`portal-index-push.mjs:52,380` only read them, and the `calendar-site` and
+`data-portal` skills instruct the agent to author them with `Write`
+("there is no separate editor"). Denying them would break the only path that
+creates them. A file declaration may therefore carry `"writtenBy": "agent"`,
+which keeps the name in `allowed-top-level` (so the reconcile still never calls
+it a stray) and out of the declared-files fence (so the guard never denies it).
+The two declarations gain that key, and their descriptions are corrected: both
+named a writer that only reads.
+
+The owner column names the *declaring* plugin, which is where the declaration
+lives rather than necessarily the module that writes the file — Task 1902 moved
+declarations onto plugins no brand excludes for reach, so a shared service may
+write a file declared on `admin`. The block message therefore points at the
+owning code and does not promise a plugin tool. `allowed-top-level` is
+not touched, so the reconcile keeps reading exactly what it reads today, and the two
+existing region readers (`platform/lib/account-schema-regions`, the cloudflare
+`schema-exposed-dirs.mjs` copy) both anchor on their own markers and on the
+`allowed-top-level` fence by name, so an appended region is invisible to them.
+
+The owning-plugin column exists because the block message has to name the owner,
+and the descriptive region carries the plugin's own description, not its name.
+
+### 2. The guard denies
+
+`fs-schema-guard.sh` parses the new fence with one awk expression, the same shape it
+already uses for the allowed set. After the top-level check passes and before the
+depth check, a target whose first path segment matches a declared name is blocked:
+
+```
+[fs-guard] blocked path=<rel> reason=declared-file
+```
+
+plus an operator-visible line naming the owning plugin and pointing the agent at it.
+An account whose SCHEMA.md carries no `declared-files` fence denies nothing, which is
+the same fail-open posture the guard already takes on a missing or empty schema.
+
+The match is on the first path segment, not on the whole relative path, so a write to
+`wa-channel-bindings.json/anything` is blocked for the same reason.
+
+### 3. The Bash post-hook stays quiet
+
+A Bash command that creates a declared file emits no stray feedback. That is the
+behaviour Task 1902 produced and it is kept deliberately, not inherited: the post
+hook fires only on a name that appeared during the command, and a declared file
+already exists on any live account, so a Bash edit to one is invisible there
+regardless of the allowed set. A signal that catches only the first creation and
+misses every subsequent edit is not a boundary. The decision is written into the
+hook's header comment and pinned by a test, so a future edit has to argue with it
+rather than flip it silently.
+
+## Testing
+
+- `fs-schema-guard.test.sh`: one case per declared file asserting exit 2 with
+  `reason=declared-file` and the owner name in the message; an operator bucket write
+  under the same schema asserting exit 0; a declared name under an account that
+  carries it in `allowed-top-level` but has no `declared-files` fence asserting
+  exit 0, which pins the deny to the fence rather than to a list baked into the
+  hook.
+- `fs-schema-guard-bash.test.sh`: a Bash command that creates a declared file
+  asserting exit 0 and no `[fs-guard-bash]` line.
+- `account-schema-owned-dirs.test.sh`: the merge emits the fence with
+  `name<TAB>plugin` for each declared file, emits nothing when no file is declared,
+  and a second merge leaves the file byte-identical.
+- Mutation check: remove the guard's deny branch and confirm the per-file cases fail.
+- The reconcile's own suite still reports no declared file as a stray.
+
+## Out of scope
+
+- 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`.
+- The reconcile. It reads the fence correctly and needs no change.
+- Adding or removing declarations. Task 1902 settled the set.

package/payload/platform/lib/account-schema-regions/dist/index.d.ts

@@ -15,6 +15,11 @@
  *   ontology roots:  - `jobs/` - one folder per Job record.      (ASCII hyphen)
  *   plugin-owned:    - `pages/` — Owned by the … plugin.         (em dash)
  *
+ * merge() writes a fourth structure, the ```declared-files fence, which is not
+ * parsed here: its only reader is the write guard (fs-schema-guard.sh), which
+ * needs the declared-FILE set apart from the bucket set. Both consumers of this
+ * module group and audit directories, so the fence is deliberately out of scope.
+ *
  * .docs/data-portal-folder-index.md records that parsing the ontology region on
  * the wrong separator matches nothing and reads as "this account has no
  * deliverables". This parser sidesteps that failure entirely by anchoring on the

package/payload/platform/lib/account-schema-regions/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,UAAU,EAAE,SAAS,MAAM,EAEtC,CAAA;AAiBF,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,iEAAiE;IACjE,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,gEAAgE;IAChE,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB;;;;;;;OAOG;IACH,MAAM,EAAE,OAAO,CAAA;IACf;;;;OAIG;IACH,MAAM,EAAE,IAAI,GAAG,eAAe,GAAG,cAAc,CAAA;CAChD;AAiCD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,aAAa,CAazE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,UAAU,EAAE,SAAS,MAAM,EAEtC,CAAA;AAiBF,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,iEAAiE;IACjE,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,gEAAgE;IAChE,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB;;;;;;;OAOG;IACH,MAAM,EAAE,OAAO,CAAA;IACf;;;;OAIG;IACH,MAAM,EAAE,IAAI,GAAG,eAAe,GAAG,cAAc,CAAA;CAChD;AAiCD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,aAAa,CAazE"}

package/payload/platform/lib/account-schema-regions/dist/index.js

@@ -16,6 +16,11 @@
  *   ontology roots:  - `jobs/` - one folder per Job record.      (ASCII hyphen)
  *   plugin-owned:    - `pages/` — Owned by the … plugin.         (em dash)
  *
+ * merge() writes a fourth structure, the ```declared-files fence, which is not
+ * parsed here: its only reader is the write guard (fs-schema-guard.sh), which
+ * needs the declared-FILE set apart from the bucket set. Both consumers of this
+ * module group and audit directories, so the fence is deliberately out of scope.
+ *
  * .docs/data-portal-folder-index.md records that parsing the ontology region on
  * the wrong separator matches nothing and reads as "this account has no
  * deliverables". This parser sidesteps that failure entirely by anchoring on the

package/payload/platform/lib/account-schema-regions/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/payload/platform/lib/account-schema-regions/src/index.ts

@@ -15,6 +15,11 @@
  *   ontology roots:  - `jobs/` - one folder per Job record.      (ASCII hyphen)
  *   plugin-owned:    - `pages/` — Owned by the … plugin.         (em dash)
  *
+ * merge() writes a fourth structure, the ```declared-files fence, which is not
+ * parsed here: its only reader is the write guard (fs-schema-guard.sh), which
+ * needs the declared-FILE set apart from the bucket set. Both consumers of this
+ * module group and audit directories, so the fence is deliberately out of scope.
+ *
  * .docs/data-portal-folder-index.md records that parsing the ontology region on
  * the wrong separator matches nothing and reads as "this account has no
  * deliverables". This parser sidesteps that failure entirely by anchoring on the

package/payload/platform/package.json

@@ -5,6 +5,9 @@
     "plugins/*/mcp",
     "services/*"
   ],
+  "dependencies": {
+    "pdf-lib": "^1.17.1"
+  },
   "scripts": {
     "build": "tsc -p lib/account-schema-regions/tsconfig.json && tsc -p lib/models/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-lifeline/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/account-scope/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/ledger-core/tsconfig.json && tsc -p lib/embed-client/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/active-rules/tsconfig.json && tsc -p lib/admin-conversation-purge/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-style/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/admin-access-password/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p lib/aeo-llms-txt-writer/tsconfig.json && tsc -p lib/obsidian-parser/tsconfig.json && tsc -p lib/storage-broker/tsconfig.json && tsc -p services/claude-session-manager/tsconfig.json && tsc -p services/whatsapp-channel/tsconfig.json && tsc -p services/webchat-channel/tsconfig.json && tsc -p services/telegram-channel/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
     "build:lib": "tsc -p lib/account-schema-regions/tsconfig.json && tsc -p lib/models/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-lifeline/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/account-scope/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/ledger-core/tsconfig.json && tsc -p lib/embed-client/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/active-rules/tsconfig.json && tsc -p lib/admin-conversation-purge/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-style/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/admin-access-password/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p lib/aeo-llms-txt-writer/tsconfig.json && tsc -p lib/obsidian-parser/tsconfig.json && tsc -p lib/storage-broker/tsconfig.json",

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

@@ -154,6 +154,20 @@ mkdir -p "$K/contacts/acme"; : > "$K/contacts/.DS_Store"
 run_post "$K" "$(env_json PostToolUse Bash "$SID")" "$ef"
 check "post ignores dot-prefixed new-bucket child" 0 $? "" "$(cat "$ef")"
 
+# --- 14. Bash creating a plugin-declared file -> silent, by decision ---------
+# A declared file is in the allowed set, so the diff never flags it. That is
+# deliberate, not inherited: this hook fires only on a name that APPEARED during
+# the command, and a declared file already exists on any live account, so a Bash
+# edit to one is invisible here regardless. Catching only the first creation and
+# missing every edit is not a boundary. The Write/Edit guard blocks the writes it
+# can actually identify; this hook stays quiet. This case pins the silence.
+L=$(new_acct)
+awk '1; /^```allowed-top-level$/{print "wa-channel-bindings.json"}' "$L/SCHEMA.md" > "$L/SCHEMA.md.tmp" && mv "$L/SCHEMA.md.tmp" "$L/SCHEMA.md"
+run_pre "$L" "$(env_json PreToolUse Bash "$SID")" "$ef"
+printf '{}' > "$L/wa-channel-bindings.json"
+run_post "$L" "$(env_json PostToolUse Bash "$SID")" "$ef"
+check "post silent on declared file" 0 $? "" "$(cat "$ef")"
+
 rm -f "$ef"
 echo "----- $PASS passed, $FAIL failed -----"
 [ $FAIL -eq 0 ]

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

@@ -87,6 +87,44 @@ run_case "domain bucket deep allow" "$(mkenv Write file_path 'jobs/5-oaktree/Quo
 run_case "domain bucket file allow"  "$(mkenv Write file_path 'jobs/5-oaktree/notes.md')"           0 "" "$ACCT_D"
 run_case "undeclared still blocks"   "$(mkenv Write file_path 'invoices/x.pdf')"                     2 "reason=top-level" "$ACCT_D"
 
+# Declared files: a plugin-declared account-root file is written whole by its
+# owner, so an agent write to it blocks even though the merge unions its name
+# into the allowed set. $ACCT_F models a merged schema (names in the allowed set
+# AND in the declared-files fence); $ACCT_L models the state before this guard
+# existed (names in the allowed set, no fence), which pins the deny to the fence
+# rather than to a list baked into the hook.
+DECLARED_FILES="webchat-channel-bindings.json wa-channel-bindings.json telegram-channel-bindings.json canonical-webchat-session.json session-titles.json agents-disabled.json"
+# Declared but AGENT-written: the calendar-site and data-portal skills author
+# these two with Write and there is no other writer, so they are in the allowed
+# set (and out of the reconcile's stray report) but never in the deny fence.
+AGENT_WRITTEN_FILES="data-portal.json calendar-availability.json"
+owner_of() { echo admin; }
+seed_declared() { # $1=acct  $2=emit fence (yes|no)
+  cp "$TEMPLATE" "$1/SCHEMA.md"
+  for f in $DECLARED_FILES $AGENT_WRITTEN_FILES; do
+    awk -v n="$f" '1; /^```allowed-top-level$/{print n}' "$1/SCHEMA.md" > "$1/SCHEMA.md.tmp" && mv "$1/SCHEMA.md.tmp" "$1/SCHEMA.md"
+  done
+  [ "$2" = "yes" ] || return 0
+  { echo; echo '<!-- declared-files:start -->'; echo '```declared-files'
+    for f in $DECLARED_FILES; do printf '%s\t%s\n' "$f" "$(owner_of "$f")"; done
+    echo '```'; echo '<!-- declared-files:end -->'; } >> "$1/SCHEMA.md"
+}
+ACCT_F=$(mktemp -d); ACCT_L=$(mktemp -d)
+trap 'rm -rf "$ACCT" "$ACCT_D" "$ACCT_F" "$ACCT_L"' EXIT
+seed_declared "$ACCT_F" yes
+seed_declared "$ACCT_L" no
+mkdir -p "$ACCT_F/projects/acme"
+for f in $DECLARED_FILES; do
+  run_case "declared block $f" "$(mkenv Write file_path "$f")" 2 "fs-guard. blocked path=$f reason=declared-file" "$ACCT_F"
+  run_case "declared owner $f" "$(mkenv Write file_path "$f")" 2 "$(owner_of "$f") plugin"                        "$ACCT_F"
+done
+for f in $AGENT_WRITTEN_FILES; do
+  run_case "agent-written allow $f" "$(mkenv Write file_path "$f")" 0 "" "$ACCT_F"
+done
+run_case "declared edit blocks"   "$(mkenv Edit file_path 'wa-channel-bindings.json')"  2 "reason=declared-file" "$ACCT_F"
+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"
+
 # 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/ *$//')

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

@@ -17,6 +17,17 @@
 # Diffing against the pre-snapshot (not flagging every non-allowed entry) is what
 # keeps the hook from firing on the legacy backlog on every unrelated Bash call.
 #
+# A plugin-declared file (a name a plugin claims as its own in its PLUGIN.md) is
+# in the allowed set, so this hook never flags one. That silence is a decision,
+# not an accident. This hook fires only on a name that APPEARED during the
+# command: a declared file already exists on any live account, so a Bash edit to
+# one is invisible here no matter what the allowed set says. A signal that catches
+# only the first creation and misses every subsequent edit is not a boundary, and
+# paying for it in feedback noise buys nothing. The Write/Edit guard
+# (fs-schema-guard.sh) blocks the writes it can actually identify, on the
+# declared-files fence; this hook stays quiet, and a case in the test suite pins
+# the silence.
+#
 # 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>

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

@@ -5,6 +5,10 @@
 #   - the target's first path segment must be in the allowed top-level set
 #     (parsed from the fenced ```allowed-top-level block of the account's
 #     SCHEMA.md — our own structured data, not CLI prose);
+#   - a target whose first path segment is a plugin-declared file (parsed from
+#     the fenced ```declared-files block of the same SCHEMA.md) is blocked even
+#     though that name is in the allowed set: the allowed set is a layout list,
+#     and a declared file is written whole by its owning plugin;
 #   - a target under an operator-data bucket (projects/ contacts/) may be at
 #     most <bucket>/<entity>/<file> deep; documents/ may be at most
 #     <bucket>/<folder>/<file> deep. Tool-owned dirs pass at any depth.
@@ -14,7 +18,7 @@
 #
 # Exit codes: 0 = allow, 2 = block (stderr shown to the agent). Fail closed when
 # the tool call cannot be inspected (tty or empty stdin). Every block logs
-#   [fs-guard] blocked path=<rel> reason=<top-level|over-deep|bad-name>
+#   [fs-guard] blocked path=<rel> reason=<top-level|declared-file|over-deep|bad-name>
 # No task numbers / internal refs in any operator-visible string.
 
 set -uo pipefail
@@ -84,6 +88,26 @@ if ! printf '%s\n' "$ALLOWED" | grep -qxF "$SEG0"; then
   exit 2
 fi
 
+# Declared-file check. A file declared in the fence is written whole by platform
+# code, so an agent write to it is blocked even though the name is in the allowed
+# set: that set says which names may exist at the account root, not which an
+# agent may author. The owner column names the declaring plugin, which is where
+# the declaration lives, not necessarily the module that does the writing (a
+# shared service may write a file declared on the plugin that no brand excludes),
+# so the message points at the owning code rather than promising a plugin tool.
+# A file the merge marks as agent-written is not in this fence at all. The set
+# comes from the account's own SCHEMA.md, so the hook hard-codes no list. No
+# fence (a brand declaring no owned file, or a schema written before the fence
+# existed) means nothing to deny — the same fail-open posture as the
+# missing-schema case above.
+DECLARED=$(awk '/^```declared-files$/{f=1;next} /^```$/{f=0} f' "$ACCOUNT_DIR/SCHEMA.md")
+if [ -n "$DECLARED" ] && printf '%s\n' "$DECLARED" | awk -F'\t' -v n="$SEG0" '$1==n{found=1} END{exit !found}'; then
+  OWNER=$(printf '%s\n' "$DECLARED" | awk -F'\t' -v n="$SEG0" '$1==n{print $2; exit}')
+  echo "[fs-guard] blocked path=$REL reason=declared-file" >&2
+  echo "Blocked: '$SEG0' is a declared file owned by the $OWNER plugin. The platform writes it whole, so it is control-plane state, not operator data, and a hand-written copy is overwritten by the next platform write. Change it through the code that owns it, never by hand." >&2
+  exit 2
+fi
+
 # Over-deep check for operator-data buckets. Count path segments.
 depth=$(printf '%s' "$REL" | awk -F/ '{print NF}')
 case "$SEG0" in