@rubytech/create-maxy-code 0.1.501 → 0.1.503

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.501",
+  "version": "0.1.503",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

package/payload/platform/docs/superpowers/plans/2026-07-25-task-1974-uploads-intake-inbox.md

@@ -0,0 +1,235 @@
+# Task 1974 — uploads/ intake inbox 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:** Reclassify the account `uploads/` directory from tool-owned scratch to a temporary intake inbox, and add a `stranded-intake` reconcile count so a node file-reference left pointing into `uploads/` is visible.
+
+**Architecture:** Doctrine plus audit change, no code path change. Three prose files are edited (`SCHEMA.md`, `data-manager.md`, `internals.md`), then the `platform-architecture` SKILL.md twin is regenerated from the docs corpus so the no-drift gate passes. Detection-only, mirroring the outbound `output/` rule landed by task 1930.
+
+**Tech Stack:** Markdown doctrine files; Node regen scripts (`docs/scripts/copy-docs.mjs`, `maxy-code/scripts/assemble-architecture-skill.mjs`); the drift gate `maxy-code/platform/scripts/check-architecture-skill-no-drift.mjs`; the bash test `fs-schema-guard.test.sh`.
+
+## Global Constraints
+
+- Zero em-dashes in all shipped prose.
+- The 1930 outbound rule must survive intact: the `output/` promote-out sentence and the `scratch-refs` / `stranded` counts stay present. `stranded-intake` is appended to the output contract, never a rename of `stranded`.
+- `uploads` stays in the `allowed-top-level` block of SCHEMA.md (files still land there).
+- The write-path guard, the admin-UI upload handler, and `memory-ingest` `sourcePath` behaviour are unchanged.
+- Reconcile output contract after this task: `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R`.
+- Paths are relative to the `maxy-code/` subtree root inside the worktree.
+
+---
+
+### Task 1: SCHEMA.md — reclassify uploads/ as intake inbox
+
+**Files:**
+- Modify: `platform/templates/account-schema/SCHEMA.md:31-39`
+
+**Interfaces:**
+- Produces: the doctrine text data-manager.md and internals.md refer to. No code symbols.
+
+- [ ] **Step 1: Remove `uploads/` from the "recreated on the next write" list.**
+
+At `SCHEMA.md:36-39`, change the list so `uploads/` is no longer among tool-owned rebuilt dirs:
+
+```
+The internal structure of these is owned by the writing tool and is recreated on
+the next write: `url-get/`, `output/`, `generated/`, `extracted/`,
+any published/served tree (`sites/`, `public/`), `agents/`, `specialists/`, and
+platform-internal areas (`cache/`, `secrets/`, `state/`, `logs/`, `tmp/`).
+```
+
+- [ ] **Step 2: Add the intake-inbox rule paragraph.**
+
+Immediately after the `output/` promote-out paragraph (ends at `SCHEMA.md:34`), insert a new paragraph. It states uploads is a temporary intake inbox, a file is promoted to its canonical bucket when its node is created, no persisted graph reference points into `uploads/`, and the per-`<attachmentId>` reason it is safe to move out of (unlike `output/`):
+
+```
+`uploads/` is a temporary intake inbox, not rebuilt scratch. A file lands at
+`uploads/<attachmentId>/` on upload and is promoted to its canonical entity
+bucket when its graph node is created: a Person or Organization file to
+`contacts/<name>/`, a Project file to `projects/<name>/`, anything else to
+`documents/`. A persisted graph reference must never point into `uploads/`.
+Unlike `output/`, each upload writes its own `uploads/<attachmentId>/` dir and no
+tool walks or rebuilds the subtree, so promoting a file out of it through the
+`data-manager` specialist is safe.
+```
+
+- [ ] **Step 3: Verify the edit.**
+
+Run:
+```bash
+cd platform/templates/account-schema
+# uploads no longer in the recreated-on-next-write list
+awk '/recreated on/,/logs.*tmp/' SCHEMA.md | grep -c 'uploads/' | grep -qx 0 && echo "OK: uploads removed from scratch list"
+# intake-inbox rule present
+grep -q 'temporary intake inbox' SCHEMA.md && echo "OK: intake rule present"
+# uploads still allowed-top-level
+grep -A40 'allowed-top-level' SCHEMA.md | grep -qx 'uploads' && echo "OK: uploads still allowed-top-level"
+# 1930 output/ rule survives
+grep -q 'promoted out of `output/`' SCHEMA.md && echo "OK: 1930 output rule intact"
+# zero em-dashes in this file
+! grep -q '—' SCHEMA.md && echo "OK: no em-dash"
+```
+Expected: all five OK lines.
+
+- [ ] **Step 4: Commit.**
+
+```bash
+git add platform/templates/account-schema/SCHEMA.md
+git commit -m "task: reclassify uploads/ as intake inbox in account SCHEMA.md (1974)"
+```
+
+---
+
+### Task 2: data-manager.md — reconcile case (e), walk uploads/, promotion permission, output contract
+
+**Files:**
+- Modify: `platform/templates/specialists/agents/data-manager.md:24` (reconcile brief), `:30` (output contract), and the "What success looks like" area for the promotion permission.
+
+**Interfaces:**
+- Consumes: the SCHEMA.md intake-inbox rule from Task 1.
+- Produces: the `stranded-intake=R` field that internals.md documents in Task 3.
+
+- [ ] **Step 1: Add reconcile case (e) and include uploads/ in the walk.**
+
+At `data-manager.md:24`, extend the counted list. After case (d), add case (e): a graph file-reference that resolves into `uploads/`, the inbound intake mirror of the `output/` scratch case. State that the walk now includes `uploads/` (a file under `uploads/` with no referencing node folds into `unreachable`). Exact appended clause inside the sentence that enumerates (a) to (d):
+
+```
+, and (e) graph file-references that resolve into the `uploads/` intake inbox,
+which is a temporary landing area a file should have been promoted out of when
+its node was created. The walk now includes `uploads/`; a file under `uploads/`
+that no node references counts under (a) unreachable.
+```
+
+- [ ] **Step 2: Add the stewardship promotion permission for uploads/.**
+
+In "## What success looks like" (after `data-manager.md:16`, the paired-move paragraph), add a sentence permitting promotion out of `uploads/`:
+
+```
+- A file in the `uploads/` intake inbox whose graph node exists is promoted to
+  its canonical bucket (Person or Organization to `contacts/<name>/`, Project to
+  `projects/<name>/`, else `documents/`), paired with a `database-operator`
+  `sourcePath` update in the same pass, exactly as any other move.
+```
+
+- [ ] **Step 3: Change the output contract.**
+
+At `data-manager.md:30`, change the reconcile summary line:
+
+```
+For the reconcile audit: `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R`.
+```
+
+- [ ] **Step 4: Verify the edit.**
+
+Run:
+```bash
+cd platform/templates/specialists/agents
+grep -q 'stranded-intake=R' data-manager.md && echo "OK: contract has stranded-intake"
+grep -q 'scratch-refs=P stranded=Q' data-manager.md && echo "OK: 1930 fields survive"
+grep -q '(e) graph file-references that resolve into the `uploads/`' data-manager.md && echo "OK: case e present"
+grep -q 'promoted to' data-manager.md && grep -q 'sourcePath` update' data-manager.md && echo "OK: promotion permission present"
+! grep -q '—' data-manager.md && echo "OK: no em-dash"
+```
+Expected: five OK lines.
+
+- [ ] **Step 5: Commit.**
+
+```bash
+git add platform/templates/specialists/agents/data-manager.md
+git commit -m "task: data-manager reconcile counts uploads/ intake drift as stranded-intake (1974)"
+```
+
+---
+
+### Task 3: internals.md — document the reclassification and the stranded-intake count
+
+**Files:**
+- Modify: `platform/plugins/docs/references/internals.md:411`
+
+**Interfaces:**
+- Consumes: the reconcile contract from Task 2.
+- Produces: the corpus text the architecture SKILL.md twin regenerates from in Task 4.
+
+- [ ] **Step 1: Append the intake-inbox rule to the placement paragraph.**
+
+At `internals.md:411`, the sentence currently ends: "...is counted by the `data-manager` reconcile audit (`scratch-refs`, `stranded`); making that audit run on a standing periodic cadence is a filed follow-up." Extend it with the inbound mirror. Append after the `scratch-refs`/`stranded` clause:
+
+```
+The inbound mirror is the `uploads/` intake inbox: an uploaded file lands at `uploads/<attachmentId>/` and is promoted to its canonical entity bucket when its graph node is created, so a persisted node reference resolving into `uploads/` is intake drift, counted by the same reconcile audit as `stranded-intake`. Unlike `output/`, `uploads/` is never rebuilt by a tool, so the `data-manager` may promote a file out of it. The reconcile output contract is `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R`.
+```
+
+- [ ] **Step 2: Verify the edit.**
+
+Run:
+```bash
+grep -q 'stranded-intake' platform/plugins/docs/references/internals.md && echo "OK: internals mentions count"
+grep -q 'intake inbox' platform/plugins/docs/references/internals.md && echo "OK: internals mentions reclassification"
+! grep -q '—' platform/plugins/docs/references/internals.md && echo "OK: no em-dash added"
+```
+Expected: three OK lines. (The last check should already pass before the edit; keep the added prose em-dash-free.)
+
+- [ ] **Step 3: Commit.**
+
+```bash
+git add platform/plugins/docs/references/internals.md
+git commit -m "task: internals.md documents uploads/ intake inbox and stranded-intake count (1974)"
+```
+
+---
+
+### Task 4: Regenerate the architecture skill twin and pass the gates
+
+**Files:**
+- Modify (generated): `platform/plugins/admin/skills/platform-architecture/SKILL.md`
+- Run: `docs/scripts/copy-docs.mjs`, `maxy-code/scripts/assemble-architecture-skill.mjs`, `platform/scripts/check-architecture-skill-no-drift.mjs`, `platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh`
+
+**Interfaces:**
+- Consumes: the edited internals.md from Task 3.
+- Produces: a SKILL.md byte-equal to what the gate regenerates.
+
+- [ ] **Step 1: Regenerate the corpus and the skill twin.**
+
+Run from the worktree repo root:
+```bash
+node docs/scripts/copy-docs.mjs
+node maxy-code/scripts/assemble-architecture-skill.mjs --brand maxy-code
+```
+Expected: `[copy-docs]` and `[platform-arch-assemble] op=write` lines, no error.
+
+- [ ] **Step 2: Run the drift gate.**
+
+Run:
+```bash
+node maxy-code/platform/scripts/check-architecture-skill-no-drift.mjs --brand maxy-code
+```
+Expected: exit 0, no drift reported. If it reports drift, the regen in Step 1 did not run or the SKILL.md was not re-written; re-run Step 1.
+
+- [ ] **Step 3: Run the write-guard test (regression boundary).**
+
+Run:
+```bash
+bash maxy-code/platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh
+```
+Expected: all assertions pass. The guard is unchanged; `uploads/` is still an allowed write, so this stays green.
+
+- [ ] **Step 4: Commit the regenerated twin (and any corpus artefact the gate expects committed).**
+
+```bash
+git add platform/plugins/admin/skills/platform-architecture/SKILL.md
+git status --porcelain docs/public
+# stage docs/public/llms-full.*.txt only if it is a tracked artefact that changed
+git commit -m "task: regenerate platform-architecture skill twin for 1974"
+```
+
+---
+
+## Land (Phase 6 handles this — not an implementation task)
+
+LANES.md and task-file archival are done in Phase 6c of the sprint, not here. The task's "LANES Ready row" line describes the pre-implementation state; because this sprint implements and archives in one motion, the end state is: task file under `.tasks/archive/`, no Ready row referencing 1974, and the archive sentence naming 1974. This is a deliberate deviation from the task's literal LANES line, recorded in Plan Conformity.
+
+## Self-Review
+
+- **Spec coverage:** SCHEMA.md reclassification (Task 1), data-manager.md case (e) + walk + promotion + contract (Task 2), internals.md + twin regen (Tasks 3-4), LANES (Phase 6c). Every in-scope item maps to a task.
+- **Out of scope confirmed untouched:** no auto-promotion hook, no cadence (1931), no CC-native uploads reach, no write-guard edit, no ingest-path edit.
+- **Type consistency:** the single shared token is the output-contract string; it reads `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R` identically in Tasks 2 and 3.
+- **Placeholder scan:** none; every edit carries its literal text.

package/payload/platform/docs/superpowers/plans/2026-07-25-task-1976-intra-folder-hygiene.md

@@ -0,0 +1,215 @@
+# Task 1976 Intra-folder Filing Hygiene 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:** Teach the `data-manager` reconcile audit to count three intra-folder drift kinds (superseded versions, format twins, stray subfolders) and state the three governing rules in `SCHEMA.md`, `data-manager.md`, and `internals.md`, so version and format sprawl becomes visible before a cleanup is asked for.
+
+**Architecture:** Detection-and-doctrine only, matching the 1930/1974 precedent. Three markdown source files gain the rules and counts; the `platform-architecture/SKILL.md` twin is regenerated from `internals.md` by the assembler, never hand-edited. No new write-time guard, no automatic deletion.
+
+**Tech Stack:** Markdown templates, Node ESM regen scripts (`docs/scripts/copy-docs.mjs`, `maxy-code/scripts/assemble-architecture-skill.mjs`), Bash test harness (`fs-schema-guard.test.sh`), drift gate (`check-architecture-skill-no-drift.mjs`).
+
+## Global Constraints
+
+- Zero em-dashes in shipped prose (use commas, colons, or full stops).
+- Detection-only: the reconcile audit counts, it never removes. Removal is a stewardship dispatch under operator direction (deletion is destructive).
+- The three new fields are **appended** to the output contract, never substituted: `scratch-refs`, `stranded`, and `stranded-intake` all survive.
+- The no-subfolder rule is scoped to `projects/<name>/` and `contacts/<name>/` only. `documents/` is allowed one document-folder deep (`documents/<doc>/file`) and is out of scope for the subfolder rule.
+- Version-group definition: `<base>.ext` and `<base>-vN.ext` sharing basename stem and extension are versions of one deliverable.
+- Format-twin definition: same basename where a delivered `.pdf` sits beside its source render `.html`/`.md`; count the source renders whose delivered twin exists.
+- The reconcile has no automated harness (it runs as a Sonnet agent). Verification of the counts is manual on a seeded folder; the automated gates that must stay green are `fs-schema-guard.test.sh` and `check-architecture-skill-no-drift.mjs`.
+
+---
+
+### Task 1: SCHEMA.md — Intra-folder hygiene section
+
+**Files:**
+- Modify: `platform/templates/account-schema/SCHEMA.md` (insert a new `## Intra-folder hygiene` section between `## Naming convention` and `## Tool-owned`)
+
+**Interfaces:**
+- Produces: the three named rules (current-version-only, one-canonical-format, no-subfolder) that Task 2 and Task 3 reference by name.
+
+- [ ] **Step 1: Insert the section** after the Naming convention section (currently ending at line 27), before `## Tool-owned`:
+
+```markdown
+## Intra-folder hygiene
+
+The operator-data buckets hold one current copy of each deliverable, in one
+canonical format, with no subtree. Three rules keep them that way; the standing
+reconcile counts any that predate them, and `data-manager` clears them on a
+stewardship dispatch.
+
+- **Current version only.** `<base>.ext` and `<base>-vN.ext` (for example
+  `charlotte-deck.pdf` and `charlotte-deck-v2.pdf` through
+  `charlotte-deck-v6.pdf`) are versions of one deliverable, not separate files.
+  Keep the newest; the superseded copies are removed through `data-manager`.
+- **One canonical format.** A delivered `.pdf` and its source render sharing the
+  same basename (`charlotte-deck.html` beside `charlotte-deck.pdf`,
+  `invoice-rbt-2026-005.html` beside `invoice-rbt-2026-005.pdf`) are one
+  deliverable in two formats. The pdf is the deliverable; the `.html` or `.md`
+  render that produced it is not a second one and is removed through
+  `data-manager`.
+- **No subfolder.** No folder nests under `projects/<name>/` or
+  `contacts/<name>/`; files live directly inside the entity folder. This is the
+  flat rule from the buckets above, restated as a standing invariant: the write
+  guard blocks the depth as you create it, and the reconcile counts any subtree
+  that predates the guard or was created off-path.
+```
+
+- [ ] **Step 2: Verify the section reads and has no em-dashes**
+
+Run: `grep -n 'Intra-folder hygiene' platform/templates/account-schema/SCHEMA.md && ! grep -n '—' platform/templates/account-schema/SCHEMA.md && echo "no em-dash"`
+Expected: the heading line prints, then `no em-dash`.
+
+- [ ] **Step 3: Verify the write guard is untouched (green baseline holds)**
+
+Run: `bash platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh 2>&1 | tail -1`
+Expected: `----- 22 passed, 0 failed -----`
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add platform/templates/account-schema/SCHEMA.md
+git commit -m "task: SCHEMA.md states intra-folder hygiene rules (1976)"
+```
+
+---
+
+### Task 2: data-manager.md — three counts, output contract, stewardship
+
+**Files:**
+- Modify: `platform/templates/specialists/agents/data-manager.md` (reconcile brief at line 25, output contract at line 31, "What success looks like" at line 17)
+
+**Interfaces:**
+- Consumes: the three rule names from Task 1.
+- Produces: the output-contract line `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R versioned=S format-twins=T stray-subdir=U` that Task 3 mirrors verbatim.
+
+- [ ] **Step 1: Extend the reconcile brief** (line 25). Insert immediately before `Move nothing, dispatch nothing.`:
+
+```
+Then, per operator-data entity folder (`projects/<name>/`, `contacts/<name>/`), count three intra-folder drifts from disk structure alone, no graph resolution needed: (f) files in a version group, where `<base>.ext` and `<base>-vN.ext` share a basename stem and extension and all but the newest are superseded, counting every superseded copy as `versioned`; (g) format twins, a source-render file (`.html`, `.md`) whose delivered `.pdf` twin of the same basename sits in the same folder, counting each such render as `format-twins`; (h) stray subfolders nested under an entity folder, which the flat rule forbids, counting each subfolder as `stray-subdir`.
+```
+
+- [ ] **Step 2: Extend the output contract** (line 31). Change the reconcile-audit string from:
+
+```
+`unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R`
+```
+
+to:
+
+```
+`unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R versioned=S format-twins=T stray-subdir=U`
+```
+
+- [ ] **Step 3: Add the stewardship bullet** to "What success looks like", immediately after the `uploads/` promotion bullet (line 17):
+
+```
+- Superseded versions and redundant format twins are removed, and a subfolder nested under `projects/<name>/` or `contacts/<name>/` is flattened or re-filed, when a stewardship brief asks for it. Each removal or move pairs with a `database-operator` reference update in the same pass, exactly as any other move: the surviving current render keeps the node reference, and a removed file's node is repointed or its reference dropped. Removal is destructive, so it happens only on an explicit stewardship dispatch, never in the read-only reconcile audit.
+```
+
+- [ ] **Step 4: Verify the contract line and no em-dashes**
+
+Run: `grep -c 'versioned=S format-twins=T stray-subdir=U' platform/templates/specialists/agents/data-manager.md && grep -o 'scratch-refs=P stranded=Q stranded-intake=R' platform/templates/specialists/agents/data-manager.md && ! grep '—' platform/templates/specialists/agents/data-manager.md && echo "no em-dash"`
+Expected: `1`, then the preserved `scratch-refs=P stranded=Q stranded-intake=R` fragment, then `no em-dash`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add platform/templates/specialists/agents/data-manager.md
+git commit -m "task: data-manager reconcile counts versioned/format-twins/stray-subdir (1976)"
+```
+
+---
+
+### Task 3: internals.md — reconcile rules and contract string
+
+**Files:**
+- Modify: `platform/plugins/docs/references/internals.md` (the reconcile paragraph at line 411)
+
+**Interfaces:**
+- Consumes: the output-contract line from Task 2 (must match verbatim).
+- Produces: the corpus source the assembler reads to regenerate the SKILL.md twin in Task 4.
+
+- [ ] **Step 1: Insert the intra-folder description** into line 411, immediately before the final sentence `The reconcile output contract is ...`:
+
+```
+Beyond placement and intake, the same audit counts intra-folder sprawl inside each operator-data entity folder from disk structure alone: superseded version copies (`<base>.ext` and `<base>-vN.ext` are one deliverable, all but the newest counted `versioned`), format twins (a source `.html`/`.md` render kept beside its delivered `.pdf` of the same basename, counted `format-twins`), and subfolders nested under `projects/<name>/` or `contacts/<name>/` that the flat rule forbids (counted `stray-subdir`). These are read-only counts; removal or flattening happens only on a `data-manager` stewardship dispatch, each paired with a `database-operator` reference update.
+```
+
+- [ ] **Step 2: Update the contract string** in the same paragraph, from:
+
+```
+The reconcile output contract is `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R`.
+```
+
+to:
+
+```
+The reconcile output contract is `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R versioned=S format-twins=T stray-subdir=U`.
+```
+
+- [ ] **Step 3: Verify the string matches Task 2 and no em-dashes in the changed region**
+
+Run: `grep -c 'versioned=S format-twins=T stray-subdir=U' platform/plugins/docs/references/internals.md && grep -o 'counted `stray-subdir`' platform/plugins/docs/references/internals.md`
+Expected: `1`, then `counted `stray-subdir``.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add platform/plugins/docs/references/internals.md
+git commit -m "task: internals.md documents intra-folder hygiene counts (1976)"
+```
+
+---
+
+### Task 4: Regenerate the platform-architecture SKILL.md twin and gate it
+
+**Files:**
+- Regenerate (do not hand-edit): `platform/plugins/admin/skills/platform-architecture/SKILL.md`
+
+**Interfaces:**
+- Consumes: the edited `internals.md` from Task 3 (via the docs corpus).
+
+- [ ] **Step 1: Rebuild the docs corpus** (mirrors internals.md into `docs/public/llms-full.<brand>.txt`). From the repo root:
+
+Run: `cd "$(git rev-parse --show-toplevel)" && node docs/scripts/copy-docs.mjs 2>&1 | tail -2`
+Expected: no error.
+
+- [ ] **Step 2: Assemble both brand skills** (the maxy-code run writes SKILL.md):
+
+Run: `cd "$(git rev-parse --show-toplevel)" && node maxy-code/scripts/assemble-architecture-skill.mjs --brand maxy-code && node maxy-code/scripts/assemble-architecture-skill.mjs --brand realagent-code`
+Expected: `[platform-arch-assemble] op=write brand=maxy-code path=.../SKILL.md ...`.
+
+- [ ] **Step 3: Run the drift gate**
+
+Run: `cd maxy-code && node platform/scripts/check-architecture-skill-no-drift.mjs 2>&1 | tail -3`
+Expected: `[check-architecture-skill-no-drift] ok brand=maxy-code (...)` and `... ok brand=realagent-code (...)`.
+
+- [ ] **Step 4: Confirm the new fields reached the regenerated twin**
+
+Run: `grep -c 'versioned=S format-twins=T stray-subdir=U' maxy-code/platform/plugins/admin/skills/platform-architecture/SKILL.md`
+Expected: `1` (or more).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add maxy-code/platform/plugins/admin/skills/platform-architecture/SKILL.md maxy-code/docs docs/public 2>/dev/null; git add -A
+git commit -m "task: regenerate platform-architecture skill twin for 1976"
+```
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- SCHEMA.md three rules → Task 1. ✓
+- data-manager three counts + contract + stewardship → Task 2. ✓
+- internals.md rules + counts → Task 3. ✓
+- SKILL.md regenerated twin → Task 4. ✓
+- LANES.md Ready row + archive → Phase 6 of the sprint (not a plan task; the sprint owns archive/LANES). ✓
+
+**Placeholder scan:** every edit shows verbatim insert text. No TBD/TODO. ✓
+
+**Type consistency:** the output-contract string is byte-identical in Task 2, Task 3, and the Task 4 grep: `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R versioned=S format-twins=T stray-subdir=U`. ✓
+
+**Out of scope (deferred, no task needed here):** automatic deletion, a write-time guard for versions/twins, per-vertical canonical-format policy, the `uploads/` intake (1974, landed), the `/data` 524 (1975, archived), the `output/` promote-out counts (1930, landed). These are stated out-of-scope in the task brief, not dropped work.

package/payload/platform/plugins/admin/PLUGIN.md

@@ -189,6 +189,7 @@ Tools are available via the `admin` MCP server.
 ## Hooks
 
 - `hooks/quote-render-gate.sh` — **PreToolUse matcher=`mcp__plugin_browser_browser__browser-pdf-save`.** Makes the deterministic quote-render path the only route a client-facing quote PDF can reach a customer. Blocks (exit 2) a `browser-pdf-save` whose output path is a client-quote artefact (`memory/users/<phone>/documents/quote-<jobId>.pdf` or `…-breakdown.pdf`) when no render receipt exists at `quoting/jobs/<jobId>/render-receipt.json` — the receipt `quote-render` writes only after its reconcile / margin-leak / link-liveness gates all pass. A hand-authored quote (the SiteDesk 2026-07-14 bypass: `Write` HTML → `browser-pdf-save`, `quote-render` never called, an internal back-test caveat naming another client folded into the free-text region) has no receipt, so the print is refused rather than delivered. **Block message:** `Blocked: this client quote was not produced by the quote-render tool, so its fixed layout and the reconcile, margin-leak and link-liveness gates never ran. Run quote-render for this job (it files the document and its receipt), then print the client HTML path it returns to PDF.` **Log line** (stderr, on a block): `[quote-render] op=bypass jobId=<jobId> detail=client quote PDF has no render receipt` (or `reason=bad-jobid` when the filename does not resolve to a job). Every non-quote PDF — brochures, invoices, the admin-scope internal view — and the deterministic path itself (receipt present) pass at exit 0. **Fail-open** on an uninspectable call (tty / empty stdin / no `python3`): `browser-pdf-save` is a general-purpose tool and the agent never controls this hook's stdin, so failing open opens no bypass while never bricking unrelated PDFs.
+- `hooks/quote-engine-gate.sh` — **PreToolUse matcher=`Bash`** (a third command on the same `Bash` matcher as `archive-ingest-surface-gate` and `fs-schema-guard-bash-pre`, any exit 2 blocks). Makes the deterministic `quote-engine-run` / `quote-render` tools the only route the account's persisted quoting scripts can run. Blocks (exit 2) a `Bash` `command` that executes `quoting/engine.mjs` or `quoting/render.mjs` directly — the pricing and render scripts must run through their MCP tools, which apply the reconcile / margin-leak / link-liveness gates and write the figures and render receipts. A hand-run `node quoting/engine.mjs` (the SiteDesk 2026-07-25 bypass: a repricing dispatched to content-producer that ran the engine by hand and re-rendered off the deterministic path) skips all of that, so it is refused. It fires only on an execution (a JS runtime invoking the script, or the script run at command position); a read or inspect of the file (`cat`/`grep`/`git diff quoting/engine.mjs`) and every unrelated `Bash` command pass at exit 0. A `mode=verify` reproduction is gated too — it must also run through `quote-engine-run`, so a hand-run `node quoting/engine.mjs mode=verify` is refused. Known fail-open gap (accepted, consistent with the soft posture): a `cd quoting && node engine.mjs` drops the `quoting/` prefix and is not matched. **Block message:** `Blocked: the quoting engine and render scripts must run through their tools, not directly. Use the quote-engine-run tool to price a job (it files the figures) and the quote-render tool to produce the documents (it files them behind the reconcile, margin-leak and link-liveness gates). Running quoting/engine.mjs or quoting/render.mjs by hand skips those gates and files no receipt.` **Log line** (stderr, on a block): `[quote-engine] op=bypass reason=direct-script-exec`. **Fail-open** on an uninspectable call (tty / empty stdin / no `python3`): `Bash` is a general-purpose tool and the agent never controls this hook's stdin, so failing open opens no bypass while never bricking unrelated commands.
 - `hooks/preference-consult-gate.sh` — **PreToolUse gate on customer-facing document deliverables.** Registered against `mcp__plugin_browser_browser__browser-pdf-save` (a second command on the same matcher as `quote-render-gate`, either exit 2 blocks) and against the email/Outlook send tools plus `SendUserFile`. It fires only in the document-deliverable shape: a `browser-pdf-save` or `SendUserFile` whose path is under `memory/users/<phone>/documents/` (or a `SendUserFile` of a `.pdf`/`.html`/`.docx`), and `email-send`/`email-reply`/`email-draft-send`/`outlook-mail-send`/`outlook-mail-reply`/`outlook-draft-send` carrying a non-empty `attachments`. For a gated call it reads the session transcript (`transcript_path`) and blocks (exit 2) when no `profile-read` tool call ran after the last user message, because the account's layer-2 `Preference` records (signature policy, header, naming, styling) were not consulted this turn, the exact miss that dropped a customer signature on a delivered document. **Block message:** `Blocked: this customer document is about to go out without the account's saved preferences being checked this turn. Those records hold the signature, header, naming and styling rules. Run profile-read for this account, apply anything relevant, then send again.` **Log line** (stderr): `[preference-gate] op=bypass tool=<name> detail=no profile-read this turn` on a block, `op=allow tool=<name> consulted=true` on an allowed document deliverable. Every non-document tool/shape, and every casual channel reply or plain-text email, passes at exit 0. **Fail-open** on an uninspectable call (tty / empty stdin / no `python3` / transcript missing or unreadable). Scope decision: the gate fires on document deliverables only, not on every send, so it never blocks routine chat. The standing reconcile counterpart for stranded `output/` deliverables is filed as a follow-up task.
 - `hooks/quote-render-pdf-conformance.sh` — **PostToolUse matcher=`mcp__plugin_browser_browser__browser-pdf-save`.** The PDF-time companion to the PreToolUse `quote-render-gate`: the HTML gates run inside `quote-render` before the receipt, but the two PDF-only conformance checks cannot, because the PDF does not exist until `browser-pdf-save` runs. For a gated client-quote PDF (`memory/users/<phone>/documents/quote-<jobId>.pdf` or `…-breakdown.pdf`) whose render receipt names the source HTML, it blocks (exit 2) when the printed PDF's `/URI` annotation count is below the source HTML's absolute-link count (a rasterised or flattened print that dropped links) or when an embedded `https://` link does not answer 200 (a Sign-Online link a pending redeploy would 404). The offline `/URI`-count check runs first and short-circuits, so a link-loss regression never depends on the network. **Block message:** `Blocked: the printed quote PDF is missing links the document declared, or an embedded link is not live (…). Do not send it. If a Sign-Online link is not live yet, deploy the signing page first; then re-render and re-print so the PDF carries every link the document declares.` **Log line** (stderr, on a block): `[quote-render] op=bypass jobId=<jobId> reason=pdf-link-conformance detail=<uri-count …|link <url> -> <code>>`. Every non-quote PDF, and any call with no receipt (the PreToolUse gate owns that block), passes at exit 0. **Fail-open** on an uninspectable call (tty / empty stdin / no `python3` / receipt or PDF absent). **Reach on upgrade:** `provision-account-dir.sh` writes this PostToolUse matcher only at account-provision time, so accounts provisioned before it landed keep a stale matcher and need a settings backfill (tracked as a follow-up task), the same reach limit the AskUserQuestion carrier gate hit.
 - `hooks/webfetch-preflight.mjs` — short-circuits WebFetch on JS-SPA shells with a structured `WEBFETCH_CANNOT_READ_JS_SPA` error so the agent surfaces a loud failure to the owner instead of paying the 60s extraction timeout. Fail-open on any internal error.

package/payload/platform/plugins/admin/hooks/__tests__/quote-engine-gate.test.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# Regression test for quote-engine-gate.sh.
+#
+# The gate is a PreToolUse hook on Bash. It refuses a Bash command that runs the
+# persisted quoting engine or render script directly (quoting/engine.mjs or
+# quoting/render.mjs), because those scripts must run only through the
+# deterministic quote-engine-run / quote-render MCP tools (which apply the gates
+# and write receipts). A mode=verify engine run and every unrelated command pass.
+#
+# Covers:
+#   A. Bash running quoting/engine.mjs            → BLOCKED (exit 2)
+#   B. Bash running quoting/render.mjs            → BLOCKED
+#   C. engine.mjs run with mode=verify by hand    → BLOCKED (verify runs through the tool too)
+#   D. engine.mjs run with a `# mode=verify` tail → BLOCKED (no token-anywhere escape)
+#   E. unrelated Bash (ls quoting)                → ALLOWED
+#   F. a quote-engine-run MCP tool call           → ALLOWED (not Bash)
+#   G. empty stdin                                → ALLOWED (fail-open)
+#   H. a non-Bash tool                            → ALLOWED (matcher defence-in-depth)
+#   I. a block emits the op=bypass fault line
+#   J. reading the script (cat) is not execution  → ALLOWED
+#   K. grepping the script is not execution       → ALLOWED
+#   L. the script run at command position         → BLOCKED
+
+set -u
+
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/quote-engine-gate.sh"
+if [[ ! -x "$HOOK" ]]; then
+  echo "FAIL: $HOOK not executable" >&2
+  exit 1
+fi
+
+PASS=0
+FAIL=0
+
+run_case() {
+  local name="$1" stdin="$2" expected_exit="$3"
+  local actual_exit
+  ( printf '%s' "$stdin" | bash "$HOOK" >/dev/null 2>/dev/null )
+  actual_exit=$?
+  if [[ "$actual_exit" -eq "$expected_exit" ]]; then
+    echo "PASS: $name (exit=$actual_exit)"
+    PASS=$((PASS + 1))
+  else
+    echo "FAIL: $name (expected exit=$expected_exit, got=$actual_exit)" >&2
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+bash_env() { # command string (JSON-escaped by caller)
+  printf '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"%s"}}' "$1"
+}
+
+run_case "A: Bash runs quoting/engine.mjs → BLOCKED" \
+  "$(bash_env "node quoting/engine.mjs < quoting/job-1854.json")" 2
+
+run_case "B: Bash runs quoting/render.mjs → BLOCKED" \
+  "$(bash_env "node quoting/render.mjs")" 2
+
+run_case "C: engine.mjs mode=verify by hand → BLOCKED" \
+  "$(bash_env "node quoting/engine.mjs mode=verify")" 2
+
+run_case "D: engine.mjs with # mode=verify tail → BLOCKED" \
+  "$(bash_env "node quoting/engine.mjs < job.json # mode=verify")" 2
+
+run_case "E: unrelated Bash → ALLOWED" \
+  "$(bash_env "ls quoting")" 0
+
+run_case "J: reading the script (cat) → ALLOWED" \
+  "$(bash_env "cat quoting/engine.mjs")" 0
+
+run_case "K: grepping the script → ALLOWED" \
+  "$(bash_env "grep foo quoting/render.mjs")" 0
+
+run_case "L: script at command position → BLOCKED" \
+  "$(bash_env "./quoting/engine.mjs < job.json")" 2
+
+run_case "F: quote-engine-run MCP call → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"mcp__plugin_sitedesk-job_sitedesk-job__quote-engine-run","tool_input":{"job":"1854","mode":"quote"}}' 0
+
+run_case "G: empty stdin → ALLOWED (fail-open)" \
+  "" 0
+
+run_case "H: non-Bash tool → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Write","tool_input":{"file_path":"/x/quoting/engine.mjs"}}' 0
+
+# I: a block emits the op=bypass fault line on stderr.
+STDERR=$( printf '%s' "$(bash_env "node quoting/engine.mjs")" | bash "$HOOK" 2>&1 >/dev/null )
+if printf '%s' "$STDERR" | grep -q '\[quote-engine\] op=bypass reason=direct-script-exec'; then
+  echo "PASS: I: block emits op=bypass reason=direct-script-exec"
+  PASS=$((PASS + 1))
+else
+  echo "FAIL: I: op=bypass line absent (got: $STDERR)" >&2
+  FAIL=$((FAIL + 1))
+fi
+
+echo "──────── quote-engine-gate test summary ────────"
+echo "PASS=$PASS FAIL=$FAIL"
+[[ "$FAIL" -eq 0 ]]

package/payload/platform/plugins/admin/hooks/quote-engine-gate.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# quote-engine-gate — PreToolUse gate on Bash.
+#
+# The account's quoting method is applied by two persisted scripts,
+# quoting/engine.mjs (pricing) and quoting/render.mjs (documents). They must run
+# ONLY through their MCP tools — quote-engine-run and quote-render — which apply
+# the reconcile / margin-leak / link-liveness gates and write the figures and
+# render receipts. Running either script directly from a Bash command bypasses
+# all of that (the SiteDesk 2026-07-25 bypass: a repricing dispatched to
+# content-producer that ran `node quoting/engine.mjs` and re-rendered by hand).
+# This gate refuses that Bash call and points the agent at the tools. It fires
+# only on an execution of the persisted script (a JS runtime invoking it, or the
+# script run at command position), never on a read like `cat quoting/engine.mjs`.
+# A mode=verify reproduction must also run through the quote-engine-run tool, so
+# a hand-run `node quoting/engine.mjs mode=verify` is gated too.
+#
+# Exit codes: 0 = allow, 2 = block (stderr shown to the agent). Fail OPEN on an
+# uninspectable call (Bash is a general-purpose tool and the agent never controls
+# this hook's stdin, so failing open opens no bypass while never bricking
+# unrelated commands). No task numbers or internal refs in operator-visible text.
+
+set -uo pipefail
+
+# No envelope (tty or empty stdin) → allow: cannot inspect, must not brick Bash.
+if [ -t 0 ]; then exit 0; fi
+INPUT=$(cat)
+[ -z "$INPUT" ] && exit 0
+
+# Print "block" when the Bash command runs a persisted quoting script directly
+# (and is not a mode=verify run), or nothing for any other call.
+DECISION=$(INPUT="$INPUT" python3 - <<'PY' 2>/dev/null || true
+import os, json, re, sys
+try:
+    d = json.loads(os.environ["INPUT"])
+except Exception:
+    sys.exit(0)
+if (d.get("tool_name", "") or "") != "Bash":
+    sys.exit(0)
+cmd = (d.get("tool_input", {}) or {}).get("command", "") or ""
+if not cmd:
+    sys.exit(0)
+script = r'quoting/(engine|render)\.mjs\b'
+# Block only an EXECUTION of the persisted script, not a read/inspect of it:
+#  - a JS runtime invoking it: `node|nodejs|bun|deno|ts-node ... quoting/engine.mjs`
+#  - the script run directly at command position: `./quoting/engine.mjs`, or the
+#    path as a bare command after a separator.
+# A read (`cat|grep|git diff|head|wc quoting/engine.mjs`) leaves the path as an
+# argument, not at command position, so it is not matched and passes.
+# Verify runs are NOT carved out: `mode=verify` must also go through the
+# quote-engine-run tool, never a hand-run of the persisted script.
+executed = (
+    re.search(r'\b(?:node|nodejs|bun|deno|ts-node)\b[^;&|\n]*' + script, cmd)
+    or re.search(r'(?:^|[;&|]\s*)\.?/?' + script, cmd)
+)
+# Known fail-open gap (accepted, consistent with this gate's soft posture): a
+# cd-relative run like `cd quoting && node engine.mjs` drops the `quoting/`
+# prefix and is not matched.
+if not executed:
+    sys.exit(0)
+print("block")
+PY
+)
+
+[ "$DECISION" = "block" ] || exit 0
+
+echo "[quote-engine] op=bypass reason=direct-script-exec" >&2
+echo "Blocked: the quoting engine and render scripts must run through their tools, not directly. Use the quote-engine-run tool to price a job (it files the figures) and the quote-render tool to produce the documents (it files them behind the reconcile, margin-leak and link-liveness gates). Running quoting/engine.mjs or quoting/render.mjs by hand skips those gates and files no receipt." >&2
+exit 2