@rubytech/create-sitedesk-code 0.1.523 → 0.1.525

package/payload/platform/docs/superpowers/specs/2026-06-02-task-610-follower-202-retry-design.md

@@ -1,116 +0,0 @@
-# Task 610 — Webchat follower 202 cold-start retry — design
-
-**Date:** 2026-06-02
-**Task:** `maxy-code/.tasks/610-webchat-follower-202-cold-start-race-never-detects-end-turn.md`
-**Status:** Approved, pre-implementation
-
-## Problem
-
-Every public webchat turn returns "Sorry, something went wrong" even when the agent
-completes successfully. Proven live on the realagent-code Pi: session `2a2a6239`
-completed its turn (assistant `text` greeting, `stop_reason:"end_turn"`) at T+52s, yet
-`dispatchOnce` returned `reject reason=turn-timeout` at the 120s `WEBCHAT_TURN_TIMEOUT_MS`.
-
-Root cause, confirmed in code: the JSONL follower's first fetch of
-`GET /:sessionId/log?follow=1` hits the pre-first-JSONL window of a cold-spawned PTY.
-The manager returns `202 {pending:true}` (`http-server.ts:1468-1471`) when the PTY is
-live but no JSONL exists yet. The follower guard is `if (!res.ok || !res.body)`
-(`follower.ts:46`). **`202` satisfies `res.ok`** (200–299), so the follower falls
-through, reads the pending JSON body as one non-event line (`type` undefined → skipped),
-reads stream `done`, `break`s, runs `finally → onClose()`, and **never retries**. No
-`follower-error`, no `fanOut`, no `outbound` — silent death. Public sessions idle-reap,
-so every greeting is the first turn of a fresh spawn → every turn hits the race → every
-turn times out.
-
-## Decision
-
-Fix the follower, not the manager. The follower retries on `202` with a bounded poll
-loop until it gets a `200` stream or the give-up window elapses. The manager's `202`
-branch is left unchanged — `202 {pending:true}` is the correct signal; the follower's
-handling of it was the defect. This matches the task's observability spec, which is
-entirely follower-centric (`follower-connect` / `follower-retry` / `follower-open` /
-`follower-give-up`), and keeps the change in one file with a unit-testable fetch seam.
-
-## The change — `follower.ts`
-
-Wrap the single `fetch` in a bounded retry loop. Per attempt:
-
-- `fetch(managerLogFollowUrl)`, then log `follower-connect sessionId=… status=<code>`.
-- **`status === 202`**: log `follower-retry sessionId=… attempt=N reason=pending`,
-  cancel the pending response body, check `abort.signal.aborted` (return cleanly via
-  `finally → onClose` if aborted), check elapsed against the give-up window. If exceeded:
-  log `follower-give-up sessionId=… reason=pending-timeout attempts=N`, call
-  `onError('follow-pending-timeout')` + `onClose()`, return. Otherwise `sleep(interval)`
-  and retry.
-- **`200` + body**: log `follower-open sessionId=…`, break into the existing
-  read/parse/accumulate/fan-out loop, unchanged.
-- **any other non-ok (404/410/5xx)**: unchanged — `onError('follow-status-<code>')` +
-  `onClose()`. Session-gone respawn is handled by `writeInput`'s 410/404 path in
-  `bridge.ts`, not the follower.
-
-Abort during a retry sleep ends the loop with no `onError` (just `onClose` via the outer
-`finally`), matching today's abort-during-stream behaviour. The retry loop sits inside the
-existing `try/finally`, so `onClose` fires exactly once on every exit path.
-
-## Config
-
-Two env vars, mirroring `CHANNEL_PTY_IDLE_MS` in `bridge.ts`:
-
-- `CHANNEL_PTY_FOLLOWER_PENDING_MAX_MS` — give-up window, default `120_000`. Covers
-  claude cold-boot and matches the webchat 120s turn window. If the follower gives up
-  before the JSONL appears, the turn times out anyway, so the bound need not exceed the
-  turn window.
-- `CHANNEL_PTY_FOLLOWER_RETRY_MS` — poll interval between `202` retries, default `1_000`.
-
-Both read inside `follower.ts` at loop entry.
-
-## No behaviour change elsewhere
-
-- **Warm sessions**: first fetch returns `200`, logs `follower-connect status=200` +
-  `follower-open`, streams as today. The four existing follower tests cover this path
-  unchanged.
-- **whatsapp / email**: same shared follower. They only see new behaviour if they ever
-  cold-start into the `202` window — the same bug, fixed once. No channel-specific code.
-- **Manager**: untouched. `202`/`200`/`404`/`410` contract is unchanged.
-
-## Tests (ephemeral)
-
-In `__tests__/follower.test.ts`, with a small `helpers.ts` extension to script a follow
-response sequence (`202` then `200`-stream) per sessionId:
-
-1. **Repro**: first follow fetch returns `202 {pending:true}`, second returns a `200`
-   stream carrying an `end_turn`+text record → subscriber receives the text. Fails today
-   (silent close, no fan-out).
-2. **Give-up**: follow keeps returning `202` past `CHANNEL_PTY_FOLLOWER_PENDING_MAX_MS`
-   (set small in the test) → `onError` + `onClose` fire, no fan-out.
-3. **Regression**: the four existing follower tests pass unchanged (warm 200 path,
-   user-event reset, malformed-line skip, multi-subscriber fan-out, abort→onClose).
-
-Tests are run to prove the fix during the sprint and discarded unless they belong in the
-existing committed suite — this suite is already tracked, so the new cases stay.
-
-## Observability (per task spec)
-
-- Success signal: `follower-open` + `outbound bytes>0` per webchat turn; the manager's
-  `log-follow-open` for that sessionId now appears (absent today for every timed-out turn).
-- Failure signal: `reject reason=turn-timeout` with no preceding `follower-open` =
-  follower never connected. With the fix, a persistent cold session emits
-  `follower-give-up` instead of dying silently.
-
-## Out of scope (separate tasks)
-
-- Task 609 — fail-open public `--allowed-tools` / `memory-search` strip. Independent.
-- WhatsApp/email turn-timeout tuning — no change beyond incidental shared-follower coverage.
-- Session reuse / idle-reap tuning (why each turn cold-spawns) — separate concern.
-- Manager-side connection hold — explicitly rejected in favour of the follower retry.
-
-## Touches
-
-- `platform/ui/app/lib/channel-pty-bridge/follower.ts`
-- `platform/ui/app/lib/channel-pty-bridge/__tests__/follower.test.ts`
-- `platform/ui/app/lib/channel-pty-bridge/__tests__/helpers.ts`
-- `.docs/` + `platform/plugins/docs/references/` (webchat turn lifecycle + new env vars)
-- `.tasks/LANES.md`, archive task file
-
-Installer publish required — `platform/ui/**` ships in the bundled `create-realagent-code` /
-`create-maxy-code` payload.

package/payload/platform/docs/superpowers/specs/2026-06-23-account-filesystem-schema-design.md

@@ -1,170 +0,0 @@
-# Account filesystem schema: seed it, and enforce file↔graph stewardship — design
-
-Source task: `.tasks/1091-account-filesystem-schema-enforcement.md`. Backstop
-(out of scope here): `.tasks/1092-account-dir-standing-reconcile-and-quarantine.md`.
-
-## Problem (recap)
-
-The account data dir (`data/accounts/<id>/`) should be a consistent projection of
-the graph ontology, but that doctrine lives only inside the `data-manager`
-specialist the main agent often routes around, nothing seeds a canonical file
-layout, and nothing stops an agent inventing folders. The observed failure: an
-agent invented `projects/<name>/deploy|sources|design|archive` with no ontology
-basis, justified as "there was no canonical schema to copy from."
-
-## Resolved gating decision
-
-`provision_account_dir` runs **unprivileged** on the Pi target — at install and
-at runtime when the `account_create` admin tool calls it via `execFileSync`
-inside the `systemctl --user` brand service. `chattr +i` needs root
-(`CAP_LINUX_IMMUTABLE`). So the task's Decision C1 (OS-immutable top level)
-**cannot take effect on the real target**.
-
-**Decision (operator, 2026-06-23): drop C1 entirely.** No `chattr`/`chflags`
-code ships. The PreToolUse Write-hook becomes the sole tool-layer hard guard;
-top-level strays created via bash fall to the Task 1092 reconcile. This also
-removes the chattr observability line and the upgrade/uninstall-unlock risk from
-the task.
-
-## What ships
-
-Three layers, honest about hard-enforceable vs cooperative.
-
-### A. Seeded schema (one standard, every account)
-
-`provision_account_dir` (the function both `setup-account.sh` and the
-`account_create` lifecycle tool call) gains an idempotent seed step:
-
-- **Create the operator-data skeleton:** `projects/`, `contacts/`, `documents/`.
-- **Create the tool-owned skeleton:** `url-get/`, `output/`, `generated/`,
-  `extracted/`, `uploads/` (`agents/`, `specialists/` already created earlier in
-  the function).
-- **Copy `SCHEMA.md`** to the account root from a shipped template
-  (`platform/templates/account-schema/SCHEMA.md`). The template is the **single
-  source of truth** for the allowed top-level set (see below) and the flatness
-  rule.
-- **Log** `[acct-schema] seeded dirs=<n>` once per provision. Idempotent: a
-  re-provision over an existing account re-creates nothing and overwrites
-  `SCHEMA.md` with the shipped version (Rubytech-controlled, like `IDENTITY.md`).
-
-Operator-data buckets are **flat**: files live directly under one entity folder
-(`projects/<name>/file`, `contacts/<name>/file`) or, for `documents/`, directly
-in the bucket or one document-folder deep. Flatness is what makes
-`projects/<name>/deploy/` a machine-detectable violation.
-
-### B. `DATA_STEWARDSHIP` directive (cooperative layer)
-
-A `DATA_STEWARDSHIP` const beside `PLATFORM_BOUNDARY` in
-`platform/services/claude-session-manager/src/system-prompt.ts`, rendered as a
-`<data-stewardship>` section in `renderAppendBlock` next to `<platform-boundary>`
-— joined into `--append-system-prompt` on **every spawn, every role**. It states:
-the account-dir layout is fixed by the seeded `SCHEMA.md`; never author new
-top-level folders or nested subtrees under an entity folder; route
-reorganisation/moves through `data-manager` and non-trivial graph writes through
-`database-operator`; the existing carve-out (a one-line update against an
-in-context, unambiguously-classified node) stays direct.
-
-`runSystemPromptSelfTest` is extended to assert `<data-stewardship>` /
-`</data-stewardship>` appear in the rendered block.
-
-### C. PreToolUse Write-hook (hard guard, no bash removal)
-
-A new hook `platform/plugins/admin/hooks/fs-schema-guard.sh`, seeded into the
-account `.claude/settings.json` as a PreToolUse hook on `Write`, `Edit`, and
-`NotebookEdit` (added alongside the existing `archive-ingest-surface-gate.sh`
-entries on those three matchers).
-
-Behaviour:
-
-1. Read the stdin JSON envelope. Fail **closed** on terminal stdin (no envelope).
-2. Extract the target path: `tool_input.file_path` for Write/Edit,
-   `tool_input.notebook_path` for NotebookEdit (via python3, matching the
-   existing `extract_tool_input_field` pattern — never jq, never command parsing).
-3. Resolve the path against the account dir. If the resolved path is **outside**
-   the account data dir, **allow** (exit 0) — this hook governs the account-dir
-   schema only; platform-source writes are PLATFORM_BOUNDARY's concern.
-4. Compute the path relative to the account dir. Let `seg0` be its first segment.
-5. **Top-level check:** if `seg0` is a single path segment (a top-level file or
-   dir) not in the allowed top-level set → **block** (exit 2),
-   `reason=top-level`.
-6. **Over-deep check:** if `seg0 ∈ {projects, contacts}` and the path has more
-   than `bucket/entity/file` depth (i.e. a directory component beyond the single
-   entity folder), or `seg0 == documents` and the path exceeds
-   `documents/folder/file` → **block** (exit 2), `reason=over-deep`.
-7. Tool-owned dirs (everything in the allowed set except the three operator-data
-   buckets) pass at **any** depth.
-8. Otherwise allow (exit 0).
-9. Every block logs `[fs-guard] blocked path=<rel> reason=<top-level|over-deep>`
-   to stderr (operator-greppable). No task numbers / internal refs in any
-   operator-visible string. The exit-2 stderr message cites the schema in plain
-   terms.
-
-**Allowed top-level set — single source.** The set lives once, as a fenced
-` ```allowed-top-level ` block in `platform/templates/account-schema/SCHEMA.md`
-(newline-delimited). The hook parses that fenced block from the **account's**
-seeded `SCHEMA.md` at runtime (deterministic structured data, not prose control
-flow). Shipped contents:
-
-```
-projects
-contacts
-documents
-url-get
-output
-generated
-extracted
-uploads
-agents
-specialists
-sites
-public
-cache
-secrets
-state
-logs
-tmp
-SCHEMA.md
-account.json
-AGENTS.md
-.claude
-.git
-.quarantine
-```
-
-A unit test asserts the hook's parse of the template equals this documented set,
-so the human doc and the enforcement never drift. Adding a future plugin
-top-level dir is a one-line edit to this block.
-
-## Out of scope (unchanged from task)
-
-- The standing reconcile / quarantine — Task 1092 (named as the backstop here,
-  not built).
-- Removing or narrowing the main agent's `Bash`/`Write`/`Edit` tools — rejected.
-- Auto-repairing drift — `data-manager` fixes on dispatch.
-- Per-account schema variants.
-- Any change to the graph schema or the `database-operator` write path.
-- `chattr`/`chflags` OS-immutability (Decision C1) — dropped per the gating
-  decision above.
-
-## Verification
-
-- **Seed:** a fresh `provision_account_dir` run produces the documented skeleton
-  and `SCHEMA.md`; the seeded allowed-top-level set matches the template exactly.
-  Re-provision is idempotent.
-- **Write-hook:** a `Write` to `projects/Acme/deploy/sources/a.txt` blocks
-  (`over-deep`); `projects/Acme/a.txt` and `documents/a.pdf` allow; a write into
-  `output/` or `generated/` at any depth allows; a write to a novel top-level dir
-  `whim/x` blocks (`top-level`); a write outside the account dir allows.
-- **Directive:** `runSystemPromptSelfTest` asserts the `<data-stewardship>` tag.
-- **No tool regression:** the main agent retains `Bash`/`Write`/`Edit`; existing
-  hook + spawn + specialist tests pass; `platform/ui` (if touched) builds/lints
-  clean. The new hook does not interfere with the existing PreToolUse gate on the
-  same matchers (both run; either can block).
-- **Device:** after publish + upgrade, a real account shows the seeded skeleton,
-  `SCHEMA.md`, and a blocked whim-write in the logs.
-
-## Observability
-
-- `provision_account_dir` logs `[acct-schema] seeded dirs=<n>`.
-- The Write-hook logs `[fs-guard] blocked path=<rel> reason=<top-level|over-deep>`
-  per block.

package/payload/platform/docs/superpowers/specs/2026-07-11-task-1557-operator-on-behalf-preference-attribution-design.md

@@ -1,90 +0,0 @@
-# Task 1557 — preferences an operator states inside a client's sub-account attach to the owner, not the operator
-
-**Date:** 2026-07-11
-**Status:** Approved design, pending plan
-**Scope:** `platform/plugins/memory/mcp/src/` (identity resolution), `platform/plugins/memory/skills/conversational-memory/SKILL.md`, `platform/plugins/memory/PLUGIN.md`, tests.
-
-## The problem, in one line
-
-A house operator working inside a client's sub-account states a preference on the client's behalf. It attaches to the operator, not the client's owner. The operator wants a way to say "this belongs to them, not me."
-
-## What the evidence established (measure-first, now measured)
-
-The attribution is decided in `resolveProfileIdentity` (`platform/plugins/memory/mcp/src/index.ts:153`). Two facts, both confirmed at the code layer, fix the shape of the solution:
-
-1. **Operating a sub-account re-scopes the whole session into it.** The sub-account picker POSTs `/api/admin/session/switch-account`, which calls `createAdminSession(target.accountId, …, operatorUserId)` (`platform/ui/server/routes/admin/session.ts:341-371`). The rc-spawn that follows boots the memory MCP with `ACCOUNT_ID` = the **sub-account**, `USER_ID` = the **house operator**, and **no** `HOUSE_ADMIN_SCOPE` (`buildRcChildEnv`, and `houseAdminScopeFor` returns null for a non-house account). So the preference write is an ordinary own-account write, keyed to the operator's `USER_ID`, landing on `:UserProfile{accountId:sub, userId:operator}` — never the owner.
-
-2. **The tool-layer `targetAccountId` lever is inert in this session.** `resolveEffectiveAccountCore` rejects any `targetAccountId` with `cross-account-denied` when `houseScope` is null (`platform/lib/account-scope/src/index.ts:49`). A sub-account operator session has no house scope, so the agent cannot set `targetAccountId`. **Teaching the skill to pass `targetAccountId` would do nothing** — it would be rejected. This is the branch the task pre-authorised: MCP `src/` changes "only if the operator-surface `targetAccountId` wiring proves absent — measure first." It is absent.
-
-3. **The owner is a distinct, single, resolvable identity.** Each sub-account is seeded with exactly one `:AdminUser{accountId, role:'owner'}` carrying a **fresh per-account `userId`** (`platform/plugins/admin/mcp/src/tools/account-lifecycle.ts:256,279`), deliberately never the operator's. `resolveOwnerUserId(accountId)` already resolves it (`platform/plugins/memory/mcp/src/lib/resolve-owner-userid.ts`).
-
-4. **`AdminUser` nodes are keyed on `userId` alone; `accountId` is a home-account stamp.** `neo4j-store.ts:627-630` MERGEs `:AdminUser {userId}` and sets `accountId` only `ON CREATE`. Each admin therefore has one global `AdminUser` node whose `accountId` is their home account. This makes "is the caller an admin of the account they are operating?" answerable with one query, with the home account fixed at the node's first creation.
-
-## The fix
-
-A preference can only ever attach to an account's owner — that is the only "designated person" the memory model supports, confirmed with the operator. So "attribute this to the designated person" resolves to "attribute this to the owner of the account being operated." The switch that decides it lives in one place: `resolveProfileIdentity`.
-
-### Behaviour
-
-In `resolveProfileIdentity`, the own-account branch (`crossAccount === false`) gains an operator-on-behalf case:
-
-- Resolve the caller's home account: the `accountId` on their `:AdminUser {userId: callerUserId}` node.
-- **Caller is operating their home account** (home `accountId` == the session's resolved `accountId`): attribute to `callerUserId`. Unchanged — this is the owner-is-speaker path and the genuine second-admin path.
-- **Caller is a foreign operator** (home `accountId` != the session's resolved `accountId`, i.e. a house operator working inside a client's sub-account): resolve the session account's owner via `resolveOwnerUserId`.
-  - Owner exists → attribute the preference to the **owner**, and bootstrap the owner's `UserProfile`/`Person` the same way the cross-account path already does. Emit `[xacct] op=identity tool=… mode=operator-on-behalf target=<acct8> caller=<caller8> resolved-userId=<owner8>`.
-  - No owner on record → **loud reject** (identical message class to the cross-account no-owner rejection). Never a silent fall-through to the operator's own profile.
-- Caller `userId` absent → existing "requires an authenticated admin session with userId" reject, unchanged.
-
-The cross-account branch (`crossAccount === true`, a house session that set `targetAccountId`) is unchanged.
-
-### Discriminator — why it is correct and regression-safe
-
-The condition "caller's `AdminUser.accountId` != the session's `accountId`" is equivalent to "no `:AdminUser {accountId: <session>, userId: <caller>}` exists," because there is exactly one `AdminUser` node per `userId`. Case-by-case:
-
-| Caller | Session account | Home `accountId` | Result |
-|---|---|---|---|
-| Owner (home = own account) | own | own | attribute self — unchanged |
-| Second admin of an account | that account | that account | attribute self — no regression |
-| House operator | a client sub-account | house | attribute the sub-account **owner** — the fix |
-| House operator | the house account | house | attribute self — unchanged |
-
-A sub-account subgraph never contains an `AdminUser` node for the operator (their node carries `accountId=house`), so the foreign-operator branch fires for exactly the reported case and no other.
-
-### Bootstrap generalisation
-
-Today the handlers set `bootstrapProfile`/`bootstrapPerson` `= crossAccount`. After the fix, a foreign-operator own-account write also attributes to an owner whose `UserProfile` may not yet exist, so the bootstrap flags must be true whenever the resolved identity is a **foreign owner**, not only when `crossAccount`. `resolveProfileIdentity` will return whether the attribution is to a foreign owner, and the three handlers derive the bootstrap flags from that rather than from `crossAccount` directly. This keeps a single meaning: "we resolved to an owner who is not the caller → bootstrap their profile if absent."
-
-### Skill
-
-`conversational-memory/SKILL.md` currently says "the owner" throughout and assumes the person conversing **is** the owner. It gains the operator-on-behalf case: when the session is a house operator working inside a client's account, preferences captured there belong to that client (the account's owner), not to the operator; the operator's own preferences live on their own (house) session. "What does this owner prefer?" reads the owner's list. The skill also states the loud refusal when the client account has no owner on record, pointing at the rootless-account remedy. No new tool argument is introduced — attribution is decided by who is driving the session, deterministically, so the skill describes the model rather than instructing a per-call lever.
-
-### Docs
-
-`PLUGIN.md`'s preference section records the operator/owner attribution model: in a client sub-account session, preference reads and writes resolve to the account's owner, and a no-owner account rejects loudly. This sits alongside the existing cross-account `targetAccountId` note (lines 189-193), which documents the house-session path; the two paths resolve to the same owner identity.
-
-## What success looks like
-
-- A preference an operator states while operating a client's sub-account is stored as a `:Preference` attributed to that sub-account's **owner** `userId`, not the operator's.
-- "What does the owner prefer?" on the sub-account returns the owner's preferences, not the operator's.
-- A sub-account with no seeded owner rejects the write out loud, never silently attributing to the operator.
-- The own-account owner-is-speaker path and the genuine second-admin path are byte-for-byte unchanged.
-
-## Testing
-
-Unit tests over `resolveProfileIdentity` / the profile handlers:
-
-- **Operator-on-behalf write** — caller whose `AdminUser.accountId` != the session account resolves the session account's owner `userId`; the resolved identity is the owner and the bootstrap flag is set.
-- **Own-account owner-is-speaker** — caller whose `AdminUser.accountId` == the session account keys to the caller `userId`; bootstrap flag is off. Unchanged.
-- **Second admin of the account** — caller with a home `AdminUser.accountId` equal to the session account attributes to self, proving multi-admin accounts do not mis-redirect.
-- **Foreign operator, no owner** — session account has no owner `AdminUser`; the write is rejected loudly, never caller-attributed.
-- **Cross-account (`targetAccountId`) path** — unchanged: still resolves the target owner, still rejects a no-owner target.
-
-The attribution is already logged (`[xacct] op=identity … resolved-userId=`, `[preference-write] op=… accountId=`), so on-device the before/after is visible from the journal without new instrumentation. The runtime reproduce on the SiteDesk device is a confirmation of the already-established code path, not a design input; this Mac cannot read that device's session log, so the design rests on the code evidence above.
-
-## Out of scope
-
-- The cross-account `targetAccountId` / `resolveOwnerUserId` mechanism (Task 1461) and owner seeding (Task 1359) — consumed, not re-implemented.
-- How the sub-account picker switches/re-scopes sessions (Task 1311) — untouched; the fix needs no spawn-env change.
-- Attribution to an arbitrary named individual who is not an account owner — a much larger storage/schema change, explicitly excluded.
-- Backfill of pre-1359 sub-accounts created without an owner on record — a separate one-time seed, never a gate relaxation. If needed, filed as its own task.
-- Non-preference profile fields and the `personFields` owner-`Person` bootstrap beyond their sharing the same resolved-owner identity path.

package/payload/platform/docs/superpowers/specs/2026-07-13-account-schema-ontology-projection-design.md

@@ -1,178 +0,0 @@
-# Account file-schema as a real projection of the domain graph ontology — design
-
-Source task: `.tasks/1622-account-file-schema-does-not-mirror-the-domain-graph-ontology.md`.
-Prior design (the mechanism this extends): `2026-06-23-account-filesystem-schema-design.md`.
-
-## Problem
-
-The account data directory is specified to be a projection of the graph ontology,
-but the allowed top-level set is a hardcoded generic base
-(`platform/templates/account-schema/SCHEMA.md`: `projects`, `contacts`,
-`documents` plus tool-owned dirs). Domain entities that the businessType ontology
-declares top-level are never added. On SiteDesk the ontology
-(`platform/plugins/memory/references/schema-construction.md`) makes `:Job` the hub
-with `:Customer`/`:Site`/`:Quote`/`:Visit`/`:Asset` as first-class operator-entry
-node types, and the sidebar's SiteDesk primary container is `:Job`, yet the
-account `SCHEMA.md` lists no `jobs` bucket. So a produced quote is filed inside the
-pricing plugin's private `quoting/jobs/<jobId>/` workspace, disconnected from the
-`:Job`/`:Quote` graph nodes and invisible to the Jobs view.
-
-A second, internal inconsistency exists inside the sitedesk-job plugin: the
-`valuation` skill's `references/job-folder.md` already documents the job folder as
-the top-level `$ACCOUNT_DIR/jobs/{jobId}/`, a path the file-schema does not permit,
-so valuation's own filing is admissible only by accident. Making `jobs/` a real
-derived bucket fixes both the quotation gap and this latent valuation gap.
-
-## The single source (resolves the task's "Depends on")
-
-`platform/plugins/memory/mcp/src/lib/schema-loader.ts` already machine-parses the
-schema markdown entity tables (each recognised by a `Neo4j Label` +
-`Required Properties` header pair). `brand.json#vertical` already names which
-`schema-<vertical>.md` applies (SiteDesk = `schema-construction`). Therefore
-`schema-<vertical>.md` is the single authoritative ontology, and the file-schema
-generator becomes a second reader of the same file. The graph loader itself does
-not change: it already reads these files. "The ontology" is one list, read by both
-the loader (for validation) and the generator (for top-level bucket derivation).
-
-`graph-labels.ts` `FILTER_TOP_LEVEL_LABELS` (the `/graph` UI chip allowlist) stays
-a separate concern this sprint. Single-sourcing it from the same per-vertical
-source is filed as a follow-up, not built here.
-
-## What ships
-
-### A. File-schema derives domain buckets from the vertical ontology
-
-**Convention for "top-level".** A label is a derived operator-entity bucket iff it
-appears as a row in the entity table under the heading
-`## Top-level node types (operator-entry, natural key)` in `schema-<vertical>.md`
-**and** its `Schema.org Type` column is a `schema:`-namespaced type. The
-`schema:`-namespace test deterministically excludes transport labels
-(`WhatsAppGroup` carries `cdm:Channel`) with no hardcoded skip-list. A vertical
-whose schema file carries no such heading contributes no domain buckets (generic
-base only) and is surfaced by the reconcile check (below).
-
-**Label to directory name.** kebab-case-plural of the label: camelCase word
-boundaries split on case, joined with `-`, lowercased, with a trailing `s`
-appended (or `y` becomes `ies`). Examples: `Job` to `jobs`, `Customer` to
-`customers`, `Quote` to `quotes`, `Asset` to `assets`, `Visit` to `visits`,
-`Part` to `parts`, `PurchaseOrder` to `purchase-orders`, `PpmContract` to
-`ppm-contracts`, `InboundInvoice` to `inbound-invoices`. One collision
-special-case: `Site` maps to `customer-sites`, so the tool-owned `sites/`
-published-tree bucket is untouched. The special-case is a single explicit entry in
-a `LABEL_DIR_OVERRIDES` map keyed by label; every other label uses the mechanical
-rule.
-
-**Generator.** `platform/scripts/lib/account-schema-owned-dirs.py` gains a
-`resolve_domain_buckets(project_dir)` beside the existing `resolve()` (plugin
-owned-dirs). It reads `brand.json#vertical`, opens
-`<project_dir>/plugins/memory/references/<vertical>.md`, extracts the top-level
-labels per the convention above, maps each to a dir, and returns
-`[{dir, label}, ...]` in table order. `merge()` unions these dirs into the
-`allowed-top-level` fenced block (same insertion path as owned-dirs) and writes a
-documented region between `<!-- ontology-buckets:start -->` and
-`<!-- ontology-buckets:end -->` markers, listing each bucket and its source label.
-The region is regenerated wholesale on every merge (idempotent), exactly like the
-existing plugin-owned region.
-
-**Provision.** No new call site. `merge_owned_dirs_into_schema` (in
-`account-schema-owned-dirs.sh`, already called by `provision-account-dir.sh` and
-`setup-account.sh`) now emits domain buckets as well as owned-dirs. Empty domain
-directories are **not** pre-created on provision. A fresh account has no jobs yet;
-the directory is created on first write, the same as any tool-owned dir. Only the
-allowed set and the `SCHEMA.md` region change at provision time.
-
-**Guard.** `platform/plugins/admin/hooks/fs-schema-guard.sh` needs no logic change.
-It already reads the account's `SCHEMA.md` allowed block and admits any first
-segment in that set at any depth except the three flat operator-data buckets
-(`projects`, `contacts`, `documents`). A domain bucket such as `jobs/` is therefore
-admitted at any depth, which is correct for the `jobs/<jobId>/Quotations/...`
-subtree the ontology's own filesystem projection describes. The derived buckets
-reach the guard through the regenerated allowed block.
-
-### B. Quotation reifies the Job/Quote/QuoteLine chain and files under the Job
-
-With `jobs/` a real bucket, the quotation apply-path is brought to parity with
-`valuation`'s job-setup (which already creates/updates `:Job` and `:Quote` and
-seeds `:QuoteLine`s on the quote). After the engine prices the job and
-`quote-render`'s fail-closed gates pass, the apply-path:
-
-1. **Reifies** `:Job-[:HAS_QUOTE]->:Quote-[:HAS_LINE]->:QuoteLine`, idempotent on
-   the natural keys the construction ontology defines (`:Job` on
-   `(accountId, jobId)`, `:Quote` on `(accountId, ref)`, `:QuoteLine` on
-   `(accountId, jobId, trade, description)`), via the same graph-write path
-   `valuation` uses. The exact write surface (memory tools vs the
-   `database-operator` specialist) is pinned in the plan by reading how
-   `valuation`'s job-setup writes today, so the two paths stay identical.
-2. **Files** the produced quote documents under the Job bucket
-   (`jobs/<jobId>/Quotations/...`, the operator-facing location valuation's
-   `job-folder.md` already documents), not orphaned in `quoting/jobs/<jobId>/`.
-   The `quoting/` engine workspace (`engine.mjs`, `method.json`, `render.mjs`, and
-   per-job figures) stays tool-owned. What changes is `quote-render`'s
-   filing-scope for the operator-facing result and the graph binding.
-3. **Emits** `[quote-render] op=quote-reify jobId=<id> quoteRef=<ref> lines=<n>` on
-   the graph write, a post-condition breadcrumb. A quote that renders documents but
-   writes no `:Quote` node is then immediately visible in the log.
-
-The schema-free pricing-method capture (item catalogue, rates, roll-up) is
-untouched. Only the output's placement and its entity binding are in scope.
-
-### C. estate-agent schema reorganisation (proves derivation is not hardcoded)
-
-`schema-estate-agent.md` currently holds one mixed `## Additional Node Types` table
-(hub `Property` plus its children `Listing`, `ImageObject`, `Viewing`, `Applicant`,
-`Offer`). It is reorganised into a `## Top-level node types (operator-entry,
-natural key)` table and a `## Child node types` table, with no row duplication, so
-`schema-loader` sees the same union of labels it sees today (it already parses
-construction's two-table shape). Top-level for estate-agent: `Property` (the
-obligatory hub) plus the operator-entry entities the vertical's prose names
-(`Listing`, `Viewing`, `Offer`). `ImageObject` is a child of `Listing` (reached
-through its parent, as construction places `QuoteLine`); `Applicant` is a Person
-extension (base `:Person` plus applicant properties, the same additional-label
-pattern construction uses for `Engineer`/`Supplier`), so neither is a top-level
-bucket. The exact top-level/child split for estate-agent is finalised during
-implementation by reading the whole file, but the two `schema:`-namespaced sets
-above are the intent. The result: a construction account derives `jobs`/`customers`/...
-and an estate-agent account derives `properties`/`listings`/`viewings`/`offers`
-from the same generator, proving the set is derived, not hardcoded.
-
-## Testing
-
-- `platform/scripts/__tests__/account-schema-owned-dirs.test.sh`: for a
-  construction brand, the merged allowed set contains `jobs`, `customers`,
-  `customer-sites`, `assets`, `visits`, `quotes` (and the rest), and does **not**
-  collide with the tool-owned `sites`. For an estate-agent brand it contains
-  `properties`, `listings`, `viewings`, `offers` and none of SiteDesk's buckets. A
-  vertical with no top-level heading yields no domain buckets (generic base
-  intact). `reconcile` reports every top-level label and whether its bucket is
-  present.
-- `platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh`: a write under
-  `jobs/<jobId>/Quotations/q.pdf` is admitted (domain bucket, any depth); an
-  undeclared top-level segment is still blocked; the three flat buckets keep their
-  over-deep block.
-- Cardinal repro (device-side, per the Pi-signal verification step): producing a
-  quote files the documents under the Job and the graph shows
-  `:Job-[:HAS_QUOTE]->:Quote-[:HAS_LINE]->:QuoteLine`; the quote appears in the
-  sidebar Jobs view. What is unit-testable locally is the derivation, the guard
-  admission, and the presence of the reify call and its breadcrumb.
-
-## Observability
-
-- `account-schema-owned-dirs.py reconcile` is extended into a standing check that
-  reports, per account, every top-level ontology entity **missing** a file-schema
-  bucket, so a re-divergence surfaces without waiting for a mis-filed artifact.
-- `[quote-render] op=quote-reify jobId= quoteRef= lines=` on quote production
-  confirms the graph write occurred.
-
-## Out of scope (each a filed follow-up, no prose-only deferral)
-
-- Normalising the remaining vertical schema files (`schema-retail`,
-  `schema-logistics`, `schema-hospitality`, `schema-food-beverage`,
-  `schema-professional-services`, `schema-trades`, `schema-creator`,
-  `schema-knowledge-work`) to carry the top-level heading. Until done they fall
-  back to the generic base and the reconcile check flags them. New task.
-- Single-sourcing `graph-labels.ts` `FILTER_TOP_LEVEL_LABELS` from the same
-  per-vertical ontology source. New task.
-- Backfilling existing `quoting/jobs/<jobId>/` figures folders for
-  already-produced quotes (the source task already defers this).
-- Any change to the graph schema, the `schema-loader` validation path, or the
-  `fs-schema-guard` decision logic beyond consuming the derived set.