@rubytech/create-sitedesk-code 0.1.524 → 0.1.525

package/payload/platform/docs/superpowers/specs/2026-07-14-graph-top-level-labels-ontology-single-source-design.md

@@ -1,119 +0,0 @@
-# Single-source the `/graph` top-level label allowlist from the vertical ontology — Design
-
-Task: `.tasks/1624-single-source-graph-labels-top-level-from-vertical-ontology.md`.
-
-## Problem
-
-A businessType's top-level operator-entry node types live in the `## Top-level node
-types` table of each vertical's `schema-<vertical>.md` (established by 1622). A third
-encoding of "top-level entity" still lives apart: `platform/ui/app/lib/graph-labels.ts`
-`FILTER_TOP_LEVEL_LABELS` is a hand-maintained global union of every brand's top-level
-labels — the `/graph` filter-popover chip allowlist. It drifts from the ontology by
-construction: a top-level label added to a vertical schema does not become a chip until
-someone also edits this TypeScript set.
-
-## Goal
-
-Derive the `/graph` chip allowlist from the same per-vertical ontology source so a
-top-level label added to a vertical schema surfaces as a chip with no second edit, while
-preserving today's exact chip visibility as the acceptance baseline.
-
-## Blast radius (evidence)
-
-`FILTER_TOP_LEVEL_LABELS` has four real code consumers:
-
-1. `server/routes/admin/graph-labels-in-graph.ts` — popover chip allowlist (the route the
-   task names). Passes the set as the `$allowed` cypher param; the cypher count-gates.
-2. `server/routes/admin/graph-subgraph.ts:280` — default-view label set.
-3. `server/routes/admin/graph-default-view.ts:158` — default-view eligibility check.
-4. `app/data/searchHelpers.ts:46` — client-side `/data` search chip pre-filter, a
-   build-time static import that cannot read files.
-
-Scope decision (operator-confirmed): **the three server routes switch to the
-ontology-derived source. The client `searchHelpers.ts` keeps the static set**, with a
-follow-up task filed to close that last second source.
-
-## Facts that shape the mechanism
-
-- Only `schema-construction.md` and `schema-estate-agent.md` currently carry a
-  `## Top-level node types` section. Every other vertical (and 1626) adds theirs later.
-- `schema-base.md` has no top-level section; its `## Node Types` table mixes top-level and
-  child types (Message, Section, Chunk). Base labels therefore **cannot** be derived — they
-  stay an explicit list. This resolves the task's open base-list decision.
-- The construction top-level table includes `WhatsAppGroup` typed `cdm:Channel`. The 1622
-  Python file-bucket generator excludes non-`schema:` rows (a channel gets no file bucket),
-  but `WhatsAppGroup` **is** a current graph chip. So the graph derivation takes **every**
-  Neo4j Label row and applies **no** namespace filter.
-- The construction table has 5 columns, estate-agent 4. The Neo4j Label column is resolved
-  by header name, never by index.
-
-## Architecture
-
-New server-only module `platform/ui/server/lib/top-level-labels.ts`:
-
-```
-getTopLevelLabelAllowlist(opts?: { referencesDir?: string }): ReadonlySet<string>
-```
-
-- Resolves `referencesDir` to `${MAXY_PLATFORM_ROOT}/plugins/memory/references` (same
-  env/`__dirname` fallback the UI server already uses), or the injected override.
-- Reads every `schema-*.md`. For each, locates the `## Top-level node types` heading by
-  case-insensitive prefix, reads the first pipe-table beneath it (before the next `##`),
-  and extracts the `Neo4j Label` column by header name, stripping backticks.
-- Unions parsed labels with the module const `STATIC_TOP_LEVEL_LABELS` — the base-schema
-  infra plus any vertical whose schema has no top-level section yet (knowledge-work today).
-  Documented to shrink as 1626 adds sections.
-- Caches the result at module level (schema files are static per install). An injected
-  `referencesDir` bypasses the cache so tests are isolated.
-- Emits one observability line on computation:
-  `op=top-level-labels source=ontology count=<n> files=<...> derived=<d> static=<s>`.
-
-The three server routes replace `FILTER_TOP_LEVEL_LABELS` with
-`getTopLevelLabelAllowlist()` (a `ReadonlySet<string>`, so `.has()` and spread are
-preserved). Cypher count-gating is unchanged: a non-resident label surfaces no chip.
-
-Unchanged: `FILTER_TOP_LEVEL_LABELS` (client), `HIDDEN_BY_DEFAULT_LABELS`,
-`AGENT_ACTION_LABELS`, `EXCLUDED_EDGE_TYPES`.
-
-## Byte-identical guarantee
-
-Derived union = construction table (11) ∪ estate table (4) ∪ `STATIC_TOP_LEVEL_LABELS`
-(33) = the current 48-member `FILTER_TOP_LEVEL_LABELS`. Because the sets are equal, the
-existing route tests (which assert membership against `FILTER_TOP_LEVEL_LABELS`) keep
-passing unchanged.
-
-`STATIC_TOP_LEVEL_LABELS` (top-level labels not yet sourced from a vertical section):
-
-- Base-schema infra: `LocalBusiness`, `Service`, `PriceSpecification`,
-  `OpeningHoursSpecification`, `Organization`, `Person`, `UserProfile`, `Preference`,
-  `AdminUser`, `AccessGrant`, `KnowledgeDocument`, `DigitalDocument`, `CreativeWork`,
-  `Question`, `FAQPage`, `DefinedTerm`, `Review`, `ImageObject`, `Invoice`, `Task`,
-  `Project`, `Event`, `Workflow`, `Email`, `EmailAccount`, `Agent`.
-- Knowledge-work vertical (no top-level section yet; 1626): `Objective`, `KeyResult`,
-  `Decision`, `Risk`, `Source`, `Finding`, `Hypothesis`.
-
-## Testing
-
-Committed, colocated `platform/ui/server/lib/top-level-labels.test.ts`:
-
-1. `getTopLevelLabelAllowlist()` against the real references dir deep-equals
-   `FILTER_TOP_LEVEL_LABELS` (regression baseline).
-2. A fixture references dir with an added top-level row surfaces that label with no change
-   to any TypeScript set.
-3. A `cdm:`-namespaced row (e.g. `WhatsAppGroup`) is included (no namespace filter).
-
-The pre-existing `labels-in-graph` and `graph-default-topLevel` tests must still pass
-after the swap (count-gating and eligibility unchanged).
-
-## Observability
-
-`op=top-level-labels source=ontology count=<n>` on the server log, emitted when the
-allowlist is resolved, so an operator can confirm the chips come from the ontology, not a
-stale hardcoded list.
-
-## Out of scope
-
-- Client `searchHelpers.ts` static set — filed as a follow-up task.
-- `HIDDEN_BY_DEFAULT_LABELS`, `AGENT_ACTION_LABELS`, `EXCLUDED_EDGE_TYPES`.
-- Adding `## Top-level node types` sections to verticals that lack one (1626).
-- The file-schema generator and quotation reification (landed in 1622).

package/payload/platform/docs/superpowers/specs/2026-07-17-task-1736-retire-mcp-stderr-tee-design.md

@@ -1,128 +0,0 @@
-# Task 1736 — retire `mcp-stderr-tee`
-
-**Date:** 2026-07-17
-**Task:** [`.tasks/1736-*.md`](../../../../.tasks/1736-nothing-sets-stream-log-path-so-the-per-conversation-mcp-stream-log-does-not-exist.md)
-**Verdict:** retire the module, its call sites, and every doc claim that a per-conversation
-MCP stream log exists.
-
-## Why retire, precisely
-
-`mcp-stderr-tee` reads `STREAM_LOG_PATH` and mirrors MCP stderr into a per-conversation
-stream log. Nothing sets that variable, so `initStderrTee` takes its skip path on every
-production spawn and 21 call sites wire up a no-op.
-
-The reason to retire is **not** that the surface was deliberately retired elsewhere. It is
-that `mcp-spawn-tee` already serves the same consumer, strictly better:
-
-- It is a shim Claude Code runs *in place of* each server's entry, so it replaces
-  `process.stderr.write` before the real entry imports. It captures every stderr byte with
-  no cooperation from the plugin — including module-load throws that happen before
-  `initStderrTee` would ever run.
-- It writes `${LOG_DIR}/mcp-<name>-<SESSION_ID>.log`, keyed by session, which *is* the
-  conversation. Per-conversation correlation already exists.
-- It handles the sessionless spawn explicitly (`mcp-<name>-nosession.log`).
-- It uses `appendFileSync`, which survives an immediate `process.exit`. `mcp-stderr-tee`
-  used an async `createWriteStream`, which does not.
-
-The two modules were never complements. Task 1721's docstring records that they wrote the
-same file and "every line landed twice". 1721 removed the duplication and left the loser
-holding a destination nothing produces.
-
-## Correcting the record
-
-The task file and its LANES row currently argue "retire because Tasks 287 and 288
-dismantled the consumers." That is wrong and it is load-bearing: 287 retired the
-`script_stream` surface — shell scripts narrating phase lines into the chat UI. It never
-evaluated the MCP-stderr surface, whose consumer is an investigator grepping a file. That
-consumer still exists; it is simply already served by `mcp-spawn-tee`.
-
-Both records get the correct argument before the task archives. A wrong reason in an
-archive licenses the next removal that the reason does not actually cover.
-
-## What changes
-
-**Code.**
-
-- Delete `platform/lib/mcp-stderr-tee/`.
-- Delete its two `tsc -p lib/mcp-stderr-tee/tsconfig.json` entries in
-  `platform/package.json` (`build` and `build:lib`).
-- Remove 21 `initStderrTee` call sites — 20 plugin MCP entry files plus
-  `platform/lib/graph-mcp/src/index.ts`. Each loses one import line and one call line.
-  `graph-mcp` is inside the 21, not additional. Premium plugins have zero call sites.
-- Remove the now-dead `STREAM_LOG_PATH` assignment in
-  `platform/plugins/memory/mcp/scripts/boot-smoke.sh` — the last assignment in the tree once
-  the reader is gone.
-- Strip the dangling module name from two comment-only references
-  (`services/claude-session-manager/src/rc-daemon.ts`, `platform/scripts/logs-rotate.sh`).
-  Neither imports it.
-- `packages/create-maxy-code/scripts/bundle.js` names `mcp-stderr-tee` as the example in its
-  lib-rewrite comment. The mechanism is generic and collects whatever premium plugins import;
-  the example just becomes stale. Point it at a lib that is actually imported.
-
-**Docs.** `platform/plugins/docs/references/plugins-guide.md` loses every claim that a
-per-conversation MCP stream log exists:
-
-- the `initStderrTee` opt-in block;
-- "How the tee decides which file to write to" (asserts the platform sets `STREAM_LOG_PATH`
-  on every spawn — it does not);
-- the tee-state markers paragraph (`[mcp-tee-attach]` / `[mcp-tee-skip]` /
-  `[mcp-tee-detach]` "land in the stream log");
-- the `logs-read { type: "system", sessionId }` → grep `[mcp:<name>]` retrieval instruction;
-- the "Main-subprocess stderr" `[subproc-stderr]` paragraph, which describes the retired
-  admin server;
-- the `initStderrTee` `createWriteStream` write-race paragraph in the failure-path contract;
-- the premium-plugins paragraph's `mcp-stderr-tee` bundler example.
-
-What replaces them is short: a plugin author calls `console.error`; the `mcp-spawn-tee` shim
-captures every byte into `mcp-<name>-<SESSION_ID>.log`; that file is where you grep. No
-import, no call, no opt-in.
-
-`platform/plugins/admin/skills/platform-architecture/SKILL.md` is generated from that
-reference doc. Regenerate it; never hand-edit.
-
-## Scope boundaries
-
-**In scope:** the `STREAM_LOG_PATH` contract — the module, its 21 call sites, its build
-entries, and the doc claims asserting the surface works.
-
-**Out of scope:**
-
-- The raw sink. Task 1721 settled it and this removal does not touch it.
-- `mcp-spawn-tee`'s stale marker names (`[mcp-spawn-tee-attached]` / `[mcp-spawn-tee-exit]`,
-  retired by Task 989 in favour of `[mcp-helper] op=spawn|boot|exit`) and its stale
-  two-process description. Owned by [`.tasks/1737-*.md`](../../../../.tasks/1737-mcp-spawn-tee-docs-promise-lifecycle-markers-and-a-child-process-that-task-989-removed.md),
-  which is designed but unimplemented on branch `worktree-task-1737-mcp-spawn-tee-docs`.
-  This sprint must not restate those names when it points authors at the sink, or it
-  re-introduces the exact bug 1737 exists to fix.
-- Reviving `claude-agent-stream-<id>.log` or any per-conversation agent stream file. It has
-  no producer in the PTY architecture; building one is a different task with a different
-  premise.
-- The `script_stream` surface and its banned-token gate. Tasks 287/288 settled it.
-
-## Open question to resolve during implementation
-
-`logs-read { type: "system", sessionId }` is documented as returning the conversation's
-stream log for `[mcp:<name>]` grepping. The doc instruction goes either way — grepping
-`[mcp:<name>]` on that log returns nothing, so the sentence is false regardless of what the
-tool does internally.
-
-What is unresolved is the *tool*. If `logs-read type:"system"` reads a file with no producer,
-that is a live bug and not this task's doc defect. Establish which during implementation. If
-it is a bug, file a `.tasks/NNN-*.md` for it — deleting the doc sentence while leaving a tool
-that silently returns nothing would hide the same false-clean shape one layer down, which is
-the exact failure this task exists to close.
-
-## Verification
-
-- `npm run build` at `maxy-code/platform/` is clean after the tsconfig entries are removed.
-- The 21 affected MCP packages typecheck.
-- `initStderrTee` and `mcp-stderr-tee` return zero hits outside `.tasks/archive/` and
-  `docs/superpowers/specs/`.
-- The architecture-skill regeneration gate passes with the regenerated `SKILL.md` committed.
-- `STREAM_LOG_PATH` returns zero hits in the live tree.
-
-## Deployment
-
-Every one of the 21 call sites ships in the bundled `create-maxy-code` payload, so this
-requires an installer publish to reach the fleet. Per the sprint gating rule, publish awaits
-an explicit operator command.

package/payload/platform/docs/superpowers/specs/2026-07-18-graph-native-ledger-design.md

@@ -1,241 +0,0 @@
-# Graph-native cash book + AR/AP ledger — design
-
-Spec for [Task 1771](../../../../.tasks/1771-graph-native-cash-book-ledger.md). Written 2026-07-18.
-
-## Why
-
-On 2026-07-18 an admin asked the agent to record a £2,000 payment. The agent began inventing `Invoice`
-properties (`total`, `amountPaid`, `balance`, `status:"part-paid"`), then reported that no ledger exists
-and offered QuickBooks, a bespoke design, or a reminder task.
-
-The report was partly wrong. `:Invoice` is in the base ontology (`schema-base.md:20`). But
-`:InvoicePayment`, `:Credit`, `:InvoiceLine` and `:InboundInvoice` are declared only for the construction
-vertical (`schema-construction.md:63-64`), so on the other nine `businessType` values an invoice can be
-raised and a payment against it has nowhere to land. `paymentStatus` is free text. No arithmetic anywhere
-relates an invoice total to what has been paid. The QuickBooks plugin performs zero graph writes. Write
-Cypher is specialist-only (`platform/plugins/graph/PLUGIN.md:42`), so the admin agent has no deterministic
-path even where the labels exist.
-
-## Corrections to the task file
-
-Three statements in Task 1771 were checked against the tree and do not hold. The implementation follows
-the tree, not the task file.
-
-1. **`ADMIN_CORE_TOOLS` does not exist.** `grep -rn "ADMIN_CORE_TOOLS\s*[=:]"` returns zero hits. It is
-   named in `CLAUDE.md:35` but `.docs/superpowers/plans/2026-06-26-email-body-extraction.md:15` records it
-   as stale. The live mechanism is `eagerTool` (`platform/lib/mcp-eager/src/index.ts:63`), which sets
-   `_meta["anthropic/alwaysLoad"]`, plus the generated canonical-tool-names artifact.
-2. **`packages/create-maxy-code/payload/` must not be hand-edited.** It is gitignored and
-   `scripts/bundle.js:276-280` wipes it on every run.
-3. **The ledger edges do not belong in `TYPED_EDGE_ALLOWLIST`.** See § Ontology below. The task file's
-   list of eight triples is dropped; five patterns go to `schema-base.md` § Relationship Patterns instead,
-   and `typed-edge-schema.ts` is not touched.
-4. **A tool alone is not a standing check.** There is no plugin-level API for recurring jobs. The two real
-   homes are a `setInterval` module wired into `platform/ui/server/index.ts`, or code called from
-   `platform/plugins/scheduling/mcp/src/scripts/check-due-events.ts`. The SiteDesk censuses cited as
-   precedent in the task file (`quote-generation.md:241-243`, `issue-flow.md:103-115`) have **no emitter in
-   code**; they are documented log lines nothing produces. Shipping `ledger-reconcile` as only a tool would
-   reproduce that defect.
-
-## Architecture
-
-Three units. The arithmetic invariant is needed by two processes, so it lives in neither of them.
-
-### 1. `platform/lib/ledger-core/` — pure
-
-No Neo4j, no filesystem, no environment reads. Exports:
-
-- `computeOutstanding(totalPaymentDue, payments, credits)` — the invariant
-  `outstanding = totalPaymentDue - Σpayments - Σcredits`.
-- `applyPayment(invoice, existing, candidate)` — returns `{accepted}` or
-  `{rejected, reason: 'over-application', remaining}`. Never clamps.
-- `ageBuckets(openInvoices, now)` — 0-30 / 31-60 / 61-90 / 90+ days.
-- `reconcileLedger(rows, now)` — returns the census finding, including `alarm`.
-
-`platform/ui` already imports `platform/lib/*/dist` (`server/index.ts:45`,
-`app/lib/graph-health.ts:25`), so one shared lib serves both consumers and the invariant is defined once.
-ledger-core computes in integer minor units so the equality is exact and never subject to float drift.
-Graph storage is unchanged: `amount` and `totalPaymentDue` stay decimal numbers, matching the existing
-JobLogic-exact construction rows. The tools convert on the way in and on the way out, so no stored value
-changes shape and existing construction data stays readable.
-
-### 2. `platform/plugins/ledger/` — the MCP
-
-Seven tools, registered with `eagerTool`, which wraps each handler in `wrapWithLifeline` and therefore
-emits `op=request` and `op=result` with a correlation token and a handle census for free. This also
-satisfies `platform/scripts/check-no-raw-mcp-registrations.mjs`.
-
-| Tool | Purpose |
-|---|---|
-| `ledger-invoice-record` | Raise an AR `:Invoice` or record an AP `:InboundInvoice`, selected by a required `direction` |
-| `ledger-payment-record` | Apply a payment to either invoice label |
-| `ledger-credit-record` | Apply a credit to an `:Invoice` |
-| `ledger-cash-record` | A `:CashEntry` not attached to any invoice |
-| `ledger-balance` | One invoice: total, applied, outstanding |
-| `ledger-statement` | Open receivables in ageing buckets, open payables, net cash position |
-| `ledger-reconcile` | On-demand form of the census |
-
-Structure copies `platform/plugins/contacts/`: own `mcp/src/lib/neo4j.ts`, per-tool files under
-`mcp/src/tools/`, writes through `writeNodeWithEdges` from `platform/lib/graph-write/dist/index.js`.
-`accountId` is read once from `process.env.ACCOUNT_ID` at `index.ts` and passed in, never derived inside a
-tool. `createdBy` is `{agent: AGENT_SLUG, session: SESSION_ID, tool: <name>}`. Every arithmetic decision
-delegates to ledger-core; the plugin contains no money arithmetic of its own.
-
-### 3. `platform/ui/app/lib/ledger-census.ts` — the standing check
-
-Mirrors `platform/ui/app/lib/timeentry-census.ts`: pure reconcile imported from ledger-core, impure
-`runLedgerCensusOnce(session, now)`, and `startLedgerCensus(openSession, opts)` returning a stop function.
-The interval is `unref()`'d so it never holds the process open, defaults to 15 minutes matching its
-sibling, and takes a boot tick. A Neo4j error logs and returns null rather than throwing into the timer.
-Wired at `platform/ui/server/index.ts` alongside `startTimeEntryCensus` (`:2208-2215`).
-
-`ledger-reconcile` and the interval both call the same `reconcileLedger`, so the on-demand and standing
-forms cannot drift apart.
-
-## Ontology
-
-Promote to `schema-base.md` so all ten verticals are covered by one definition:
-
-| Label | Natural key |
-|---|---|
-| `:InboundInvoice` | `(accountId, supplier, confirmationNumber)` |
-| `:InvoiceLine` | `(accountId, invoiceId, lineId)` |
-| `:InvoicePayment` | `(accountId, invoiceId, paymentId)` |
-| `:Credit` | `(accountId, creditId)` |
-| `:CashEntry` | `(accountId, entryId)` — new |
-
-`:CashEntry` requires `accountId`, `entryId`, `direction` (`'in'|'out'`), `amount`, `date`, `description`.
-
-Two derivations, not stored fields:
-
-- **Direction of a payment comes from the parent label.** An `:InvoicePayment` under `:Invoice` is money
-  received; under `:InboundInvoice` it is money paid. No `direction` property on `:InvoicePayment`.
-- **Outstanding is computed on read.** `outstanding`, `balance` and `amountPaid` join § Forbidden
-  Properties (`schema-base.md:119`) for `:Invoice` and `:InboundInvoice`.
-
-`schema.cypher` additionally gains the `:Invoice` `(accountId, confirmationNumber)` uniqueness constraint
-that base already claims as its natural key but never declared, the `:CashEntry` constraint and index, and
-entries in the `entity_search_admin` fulltext union (`:465-481`).
-
-`schema-construction.md` drops the rows now owned by base. Construction-only labels stay.
-
-The line-item `amount` carve-out against the base `totalPaymentDue` synonym ban
-(`schema-construction.md:66-70`) moves to `schema-base.md` § Property Naming Rules with the labels.
-
-Five edge patterns join `schema-base.md` § Relationship Patterns (`:168`), beside the
-`(:Invoice)-[:BILLED_TO]->` pattern already there:
-
-```
-(:Invoice|:InboundInvoice)-[:HAS_LINE]->(:InvoiceLine)
-(:Invoice|:InboundInvoice)-[:HAS_PAYMENT]->(:InvoicePayment)
-(:Invoice)-[:HAS_CREDIT]->(:Credit)
-(:InboundInvoice)-[:FROM_SUPPLIER]->(:Organization)
-(:CashEntry)-[:COUNTERPARTY]->(:Person|Organization)
-```
-
-**Not `TYPED_EDGE_ALLOWLIST`.** That constant is imported by exactly two consumers,
-`plugins/memory/mcp/src/tools/memory-ingest.ts:25` and `scripts/generate-edge-docs.ts:20`. It governs what
-the typed-edge classifier may propose from free-text document ingest. `lib/graph-write/src/index.ts` never
-references it and `lib/schema-validator.ts` performs no edge-type validation, so the ledger tools' writes
-are not checked against it. Adding ledger triples there would make the classifier extract ledger edges out
-of ingested documents, which is not intended. The allowlist header states the rule directly: edge types
-outside it "are governed by schema-base.md / vertical-schema rules".
-
-## Data flow — one payment
-
-1. Resolve the invoice by reference; capture its label and `totalPaymentDue`.
-2. Fetch existing `:InvoicePayment` and `:Credit` children.
-3. ledger-core validates the candidate.
-4. Write through `writeNodeWithEdges`, or reject.
-5. Re-read outstanding from the graph.
-6. Emit `op=verify`.
-
-Step 5 is the point of the design. `op=write` proves intention; only the re-read proves outcome.
-
-## Errors
-
-Over-application rejects, is logged, and is reported to the user verbatim. It is never clamped and never
-silently recorded. An unresolvable invoice reference rejects. Neo4j failures surface as `isError` payloads,
-which `wrapWithLifeline` logs as `outcome=error` (`mcp-lifeline/src/index.ts:20-26`). The census swallows
-nothing but never throws into the interval.
-
-## Observability
-
-Failure modes and the signal for each. Four are no-event failures owned by the census, not by a log line.
-
-| # | Failure | Event? | Signal |
-|---|---|---|---|
-| 1 | Narrated as recorded, nothing written | No | `[ledger-census]` counts flat across a window containing `op=request` lines |
-| 2 | Payment with no parent-invoice edge | No | `[ledger-census] orphanPayments=<N>` |
-| 3 | A stored balance field reappears and drifts | No | `[ledger-census] storedBalanceProps=<N>` |
-| 4 | Duplicate payment via non-deterministic `paymentId` | No | `[ledger-census] suspectDuplicates=<N>` |
-| 5 | Over-application | Yes | `op=reject reason=over-application` |
-| 6 | Write rejected, resolved vertical lacks the label | Yes | `op=reject reason=unknown-label vertical=<file>` |
-| 7 | `schema.cypher` edited, `seed-neo4j.sh` not re-run | No | `[ledger-census] declaredNotLive=<labels>` from `live-schema-source.ts:180` |
-| 8 | Tool in one registry, absent from the other | No | `[ledger-census] toolsResolved=7/7` |
-
-Lifecycle for `ledger-payment-record`, correlated by `paymentId`. Lines 1 and 6 come free from
-`wrapWithLifeline`; the rest are domain lines the tool emits.
-
-```
-[ledger] op=request  paymentId=… invoiceRef=… direction=… amount=… date=…
-[ledger] op=resolve  paymentId=… found=<bool> label=<Invoice|InboundInvoice> vertical=… totalPaymentDue=…
-[ledger] op=arithmetic paymentId=… priorApplied=… priorCredits=… amount=… outstandingBefore=… outstandingAfter=…
-[ledger] op=write    paymentId=… nodesCreated=… edgesCreated=…
-[ledger] op=reject   paymentId=… reason=<over-application|unknown-label|no-parent> detail=…
-[ledger] op=verify   paymentId=… outstandingReRead=…
-[ledger] op=exit     paymentId=… ranMs=… outcome=<applied|rejected|error>
-[ledger-census] invoices=… payments=… orphanPayments=… storedBalanceProps=… suspectDuplicates=… declaredNotLive=… toolsResolved=…/7
-```
-
-**Success:** `op=verify` present, `outstandingReRead` equal to `op=arithmetic`'s `outstandingAfter`; census
-with every counter zero and `toolsResolved=7/7`.
-
-**Failure:** `op=request` with no matching `op=exit`; `op=write` with no `op=verify`; any non-zero census
-counter; **absence of a census line** in the expected window; `op=resolve found=false` on a reference the
-user just supplied.
-
-**Diagnostic path:** the plugin MCP tee log, `grep -E '\[ledger\]|\[ledger-census\]'`, then filter by one
-`paymentId` for that operation's full lifeline.
-
-## Registration
-
-- `platform/plugins/ledger/PLUGIN.md` frontmatter is the source of truth for tool names.
-- `cd platform && npm run gen:canonical-tools` regenerates
-  `services/claude-session-manager/src/canonical-tool-names.generated.ts`.
-  `platform/scripts/check-canonical-tool-names.mjs` fails the build on drift.
-- `plugins.core[]` in all four brand JSONs: `maxy-code`, `realagent-code`, `sitedesk-code`,
-  `property-administrators`. A plugin absent from a brand's list does not ship to that brand.
-- Specialist templates `database-operator.md` and `project-manager.md`.
-- `platform/package.json` build chain gains `lib/ledger-core`. The `plugins/*/mcp` glob picks the plugin up
-  automatically.
-
-## Testing
-
-- **ledger-core** — pure unit tests, no infrastructure. Part payment leaves the exact remainder; two
-  payments summing to the total leave zero; a credit reduces outstanding identically to a payment; an
-  over-application is rejected with the remaining figure; a zero-total invoice accepts no payment; the same
-  `paymentId` twice does not double-count; ageing buckets at the 30/60/90 boundaries.
-- **Tools** — stubbed session; asserts the reject branch writes nothing and that `op=verify` re-reads.
-- **Per-vertical coverage** — iterates all ten `businessType` values resolved by
-  `resolve-active-vertical.ts:38,67-81` including the `trades → schema-construction` alias, validating an
-  `:Invoice` + `:InvoicePayment` + `:CashEntry` write against each. Fails before the promotion, passes
-  after. This is the test that would have caught the reported defect.
-- **Census** — pure `reconcileLedger` cases for each non-zero counter.
-- **Drift gate** — `schema-cypher-drift.test.ts:60` green with no new `PROSE_ONLY_LABELS` entries.
-
-Baseline in this worktree before any change: 508 vitest tests pass across the memory plugin, 56 node:test
-tests pass. Three suites report as failed under vitest because they are `node:test` files vitest cannot
-collect. That is pre-existing and unrelated.
-
-## Regression boundary
-
-Existing construction-vertical tests unchanged. `resolve-active-vertical.test.ts` cases at `:69,:82,:95,:108`
-unchanged. `account-schema-owned-dirs.test.sh` confirms no new account file-schema bucket is minted, since
-`schema-base.md` has no `## Top-level node types` section. The SiteDesk `:Job -> :Quote -> :QuoteLine`
-reification is untouched.
-
-## Out of scope
-
-Double-entry. QuickBooks-to-graph mirroring. VAT, tax and multi-currency. Bank feed import. Any UI.
-SiteDesk quoting figures. Backfill of existing construction accounts.

package/payload/platform/docs/superpowers/specs/2026-07-20-task-1704-data-portal-standing-audit-design.md

@@ -1,177 +0,0 @@
-# Task 1704 — data portal standing audit
-
-**Date:** 2026-07-20 · **Lane:** cloudflare + storage-broker · data-portal observability
-**Depends on:** 1689 (portal, landed), 1694 (broker R2 object ops, landed), 1810 (loop registry, landed)
-
-## The problem
-
-The `[data-portal]` lifeline traces one upload end to end and ends in a re-read post-condition, so
-every failure that emits an event is already covered. Three conditions emit nothing:
-
-- **An orphan object** — an object in R2 with no manifest row. Stored, invisible to ingestion
-  forever, and the upload that produced it returned `200`.
-- **A phantom row** — a manifest row whose object is absent. Ingestion will pull a missing file,
-  and nothing says so until ingestion runs, which may be never.
-- **A stalled ingestion sweep** — an ingestion that never runs logs nothing, so a climbing backlog
-  and an empty one look identical.
-
-Only a standing reconcile reveals any of them. Absence of the audit's line is itself the signal that
-all three are unobservable.
-
-## Premise corrections carried from the task file
-
-The task brief predates three changes. All three point the same way; none change its intent.
-
-1. **The `[storage-audit]` idiom is now `registerLoop`.** Task 1810 moved every standing loop onto
-   `platform/ui/server/loop-registry.ts`, and `scripts/check-loops-registered.mjs` fails the build on
-   a bare `setInterval`. "Copy the `[storage-audit]` shape" therefore means registering a loop, not
-   hand-rolling two unref'd timers.
-2. **Every line number in the brief is stale**, though every cited thing still exists.
-   `runStorageAudit` is `storage-broker.ts:773`; the "silent when the config names no portal" idiom
-   is the `hasBookingSite` check in the availability loop; `r2ObjectList`'s drain-to-exhaustion
-   comment at `cf-exec.ts:443` names this audit as its own reason for existing.
-3. **`reconcilePages` (Task 1728) is a closer template than the brief knew.** It is already a pure
-   orphan/phantom set difference over two lists in `lib/storage-broker/src/audit.ts`, carrying the
-   concurrency contract and the refusal to print `orphan=<everything>` off a failed read. This audit
-   is that shape one level down: objects against rows instead of projects against records.
-
-## Components
-
-### 1. `reconcileDataPortal` — pure, in `lib/storage-broker/src/audit.ts`
-
-Third reconcile beside `reconcileStorage` and `reconcilePages`. It is D1 rows against R2 objects,
-which is that lib's domain, and the ui server imports the lib by source path so there is no dist
-rebuild in the loop.
-
-```ts
-interface DataPortalReconcile {
-  objects: number
-  rows: number
-  orphanObjects: string[]   // object keys with no manifest row
-  phantomRows: string[]     // manifest objectKeys with no object
-  oldestUningestedHrs: number | null   // null renders as `na`
-}
-
-function reconcileDataPortal(
-  objects: Array<{ key: string }>,
-  rows: Array<{ objectKey: string; ingested: number; uploadedAt: string }>,
-  nowMs: number,
-): DataPortalReconcile
-```
-
-`nowMs` is injected so the age arithmetic is deterministic under test rather than clock-dependent.
-
-`oldestUningestedHrs` is computed from rows with `ingested === 0` only, and is `null` when there are
-none. **An `uploadedAt` that will not parse is excluded from the minimum rather than allowed to
-produce `NaN`** — that is the `snapshotAgeMs=NaN` lesson from the availability loop, where a truthy
-but non-ISO value slipped past a `??` guard and logged `NaN`. If exclusion leaves no usable row, the
-result is `null`.
-
-### 2. `parseManifestRows` — pure, exported from the route module
-
-`cf.d1Query` shells `npx wrangler d1 execute --json` and is typed `unknown`. This function parses
-that envelope into the row shape above and **throws on anything it does not recognise**.
-
-Throwing rather than returning `[]` is the load-bearing decision. Zero rows against a populated
-bucket reads as "every object is an orphan" — a fabricated defect count off a failed read, which is
-precisely what `reconcilePages` refuses to print. A throw lands in the d1-degraded branch, where the
-line says the read failed instead of asserting a number it does not have.
-
-### 3. `runDataPortalAudit(root)` — the caller, in `ui/server/routes/storage-broker.ts`
-
-Sits with `runStorageAudit` and `runPagesAudit` at the foot of the same file.
-
-**Discovery.** Walks `data/accounts/*/data-portal.json`. A config that is absent, unparseable, or
-parses but names no `portalDbName` and `bucketName` is **silent** — the `hasBookingSite` idiom. An
-account with no portal is not a fault and must not produce a line.
-
-**It returns before minting a house token when no account has a portal.** Most installs have no data
-portal and no house Cloudflare credential; minting unconditionally would make this loop report an
-error forever on every one of them.
-
-**Reads.** One `makeHouseCfExec(root)` for the whole run, then per account:
-
-- rows — `d1Query(portalDbName, 'SELECT objectKey, ingested, uploadedAt FROM manifest')`
-- objects — `r2ObjectList(bucketName)`
-
-The two halves are caught **separately**, and the line is emitted unconditionally afterwards. This is
-`.tasks/backlog/1351` made structural: the log is not downstream of either read, so neither read can
-skip it. An audit that a data-source failure silences is the same blind spot one layer up, in a task
-that exists because failures emit nothing.
-
-**Degradation.** Each line carries exactly what is still measurable:
-
-| Failure | Line still carries |
-|---|---|
-| R2 read fails | `rows=N oldestUningestedHrs=N`, remainder `na`, `degraded=r2` |
-| D1 read fails | `objects=N`, remainder `na`, `degraded=d1` |
-| Both fail | all `na`, `degraded=d1+r2` |
-
-`oldestUningestedHrs` surviving an R2 failure is not incidental: the backlog age is computable from
-the manifest alone, and it is the one of the three conditions that a half-broken audit can still
-report.
-
-**Line format.** Counts only:
-
-```
-[data-portal-audit] account=<id> objects=N rows=N orphanObjects=N phantomRows=N oldestUningestedHrs=N
-```
-
-Healthy is `orphanObjects=0 phantomRows=0` with a bounded age. **Any non-zero orphan or phantom count
-is a defect, not noise.**
-
-`reconcilePages` reports orphan and phantom *names*, on the grounds that a count says something is
-wrong and a name says what to fix. This audit deliberately does not, and the pure function returning
-the keys does not change that: the keys here are `<ownerId>/<filename>`, real people's filenames,
-and the journal is not where they belong. The task's success criterion specifies counts, and the
-audit owning its own ownership discipline is called out in the brief as load-bearing precisely
-because the in-process path holds the account-wide credential and bypasses `objectGate` entirely.
-
-### 4. Arming, in `ui/server/index.ts`
-
-```ts
-registerLoop({
-  name: 'data-portal-audit',
-  intervalMs: 300_000,
-  firstRunDelayMs: 50_000,
-  run: runDataPortalAuditSafe,
-})
-```
-
-Same interval as the storage and pages audits. The first run is offset past storage (20s), pages
-(35s) and google-account (45s) so a boot does not fire four token mints in the same instant.
-
-**Degradation is not an error.** A degraded run returns a note (`portals=N degraded=M`) and the
-registry records `ok`, because the audit did the job it could and said so. A genuine throw — no
-house credential where a portal exists, an unreachable registry — is logged and **rethrown**, the
-`runStorageAuditSafe` shape, so /activity shows a fresh Last run against a stale Last OK.
-
-## Testing
-
-**Unit, `lib/storage-broker/src/__tests__/audit.test.ts`** — an object with no row counts one
-`orphanObjects`; a row with no object counts one `phantomRows`; a matched pair counts neither;
-`oldestUningestedHrs` comes from the oldest `ingested=0` row; `ingested=1` rows are excluded from it;
-`na` when there are no uningested rows; an unparseable `uploadedAt` does not yield `NaN`.
-
-**Envelope, same run** — `parseManifestRows` on a well-formed wrangler payload, and a throw on a
-malformed one. The throw case is what stops a parse failure reading as an empty manifest.
-
-**Route, new `ui/server/__tests__/data-portal-audit.test.ts`** — modelled on
-`storage-broker-object-routes.test.ts`: `// @vitest-environment node`, `vi.mock` the neo4j store,
-partially mock the lib via `importOriginal`, stub `makeHouseCfExec` with a fake carrying
-`r2ObjectList` and `d1Query`. Cases: two accounts, one with a portal, yields one line; a D1 throw
-still emits a line carrying `degraded=d1`; an R2 throw emits `degraded=r2` with `rows` still counted;
-a malformed D1 payload degrades rather than reporting zero rows; a config naming no portal is silent;
-no portal anywhere mints no token.
-
-**Mutation check** — reverting the reconcile to compare in one direction only must fail the opposite
-direction's test.
-
-## Scope boundaries
-
-**In scope:** the reconcile and its tests, the caller, the arming, the route-level tests, and
-`.docs/data-portal.md` § Observability, which currently states the audit is not built.
-
-**Out of scope:** the device-side ingestion sweep (unbuilt, agent-side); any change to the portal
-template or the gate (1689, landed); escalation beyond a log line — `.tasks/backlog/1351` records
-that a non-zero count escalating nowhere is its own problem, and that is lane-wide, not this task's.