@rubytech/create-sitedesk-code 0.1.523 → 0.1.525

package/payload/platform/docs/superpowers/plans/2026-07-18-ledger-write-path-fix.md

@@ -1,109 +0,0 @@
-# Ledger write path fix — implementation plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax.
-
-**Goal:** Every ledger write tool successfully creates its node, because relationships carry the element id `writeNodeWithEdges` actually requires.
-
-**Architecture:** Delete the ledger's invented `GraphRelationship` and the cast that forced it past the type checker; import the real type so the shape becomes a compile-time constraint. Resolve each relationship target to an element id before writing. Add a census counter so a dead write path can no longer read as a healthy empty ledger.
-
-**Spec:** [`.tasks/1788-...md`](../../../../.tasks/1788-ledger-write-tools-pass-an-invented-relationship-shape-so-every-write-is-rejected.md). No separate design doc; the task carries the decisions.
-
-## Global constraints
-
-- Node 22. Never `npm install` in this worktree; deps are symlinked from the parent.
-- Build and test from `maxy-code/platform`.
-- The four write tools must not be tested with a stubbed `write`. That stub is why the bug shipped.
-- Do not touch `lib/ledger-core`'s arithmetic (money, balance, ageing) — only `reconcile.ts` gains a counter.
-- Baseline before changes: 56 ledger tests, 508 memory-plugin tests.
-
----
-
-### Task 1: Make the wrong shape a compile error
-
-**Files:** `plugins/ledger/mcp/src/lib/types.ts`, `plugins/ledger/mcp/src/index.ts`
-
-**Produces:** the real `GraphRelationship { type, direction, targetNodeId }` in scope for every tool.
-
-- [ ] **Step 1: Prove the current code is wrong at the type level.** In `types.ts`, delete the local `GraphRelationship` and re-export the real one:
-
-```ts
-export type { GraphRelationship } from "../../../../../lib/graph-write/dist/index.js";
-```
-
-- [ ] **Step 2: Delete the cast in `index.ts`.** Replace the `writeNodeWithEdges as unknown as (...)` wrapper with a direct reference. Run `tsc -p plugins/ledger/mcp/tsconfig.json` and record every error. Expect failures in `invoice-record.ts`, `payment-record.ts`, `cash-record.ts` on `targetLabel`/`targetProps`. **Those errors are the bug** — they are what the cast was hiding.
-
-- [ ] **Step 3: Fix the attribution while here.** `createdBy` becomes `{ agent: agentSlug, session: sessionId, tool, source: "ledger" }` with no `?? ""`, so `graph-write:254`'s `agent ?? source ?? "unknown"` chain can work.
-
-- [ ] **Step 4: Commit** once the remaining errors are only the three tool files.
-
----
-
-### Task 2: Resolve targets to element ids
-
-**Files:** `plugins/ledger/mcp/src/lib/read.ts`, `tools/{invoice-record,payment-record,cash-record}.ts`, `index.ts`, `PLUGIN.md`
-
-**Consumes:** the real type from Task 1.
-
-- [ ] **Step 1: `readInvoice` returns the node's id.** Add `nodeId: string` to `InvoiceRead`; add `elementId(i) AS nodeId` to the Cypher and map it.
-
-- [ ] **Step 2: Write the failing tests first.** For each of the three tools, assert the relationship carries a `targetNodeId` equal to the id supplied or resolved, and that no relationship carries `targetLabel`:
-
-```ts
-it('targets the counterparty by element id', async () => {
-  const write = okWrite()
-  await invoiceRecord({ ...base, counterpartyNodeId: '4:abc:12', session: {} as never, write })
-  const rel = write.mock.calls[0]![0].relationships[0]
-  expect(rel.targetNodeId).toBe('4:abc:12')
-  expect(rel).not.toHaveProperty('targetLabel')
-})
-```
-
-- [ ] **Step 3: Implement.** `invoice-record` and `cash-record` take a required `counterpartyNodeId`. `payment-record` and `credit-record` use `invoice.nodeId` from the read. Each `zod` schema gains the field with a description telling the agent to look the organisation up first.
-
-- [ ] **Step 4: Reject a blank id** before writing, with `op=reject reason=missing-counterparty`, so the failure names the cause rather than surfacing as `unresolved-target`.
-
-- [ ] **Step 5: `tsc` clean, ledger tests green, commit.**
-
----
-
-### Task 3: The test that would have caught it
-
-**Files:** `plugins/ledger/mcp/src/tools/__tests__/write-contract.test.ts` (new)
-
-One integration test per write tool that calls the **real** `writeNodeWithEdges` against a fake `Session` (`run` + `close`), asserting the issued Cypher carries the resolved target id and that no `unresolved-target` rejection occurs.
-
-- [ ] **Step 1: Write it against the current code and watch it fail** if Tasks 1 and 2 were somehow incomplete.
-- [ ] **Step 2: Confirm it passes.**
-- [ ] **Step 3: Prove it is load-bearing.** Temporarily reintroduce `targetLabel` in one tool; the build must fail. Revert.
-- [ ] **Step 4: Commit.**
-
----
-
-### Task 4: Make a dead write path visible
-
-**Files:** `lib/ledger-core/src/reconcile.ts`, `plugins/ledger/mcp/src/lib/read.ts`, `tools/reconcile.ts`, `ui/app/lib/ledger-census.ts`, tests
-
-`[ledger-census]` currently prints `invoices=0 payments=0` identically whether the ledger is healthy-and-empty or wholly broken. That is why this bug ran all day unseen.
-
-- [ ] **Step 1: Failing test.** `reconcileLedger` alarms when `writeRejects24h > 0`.
-- [ ] **Step 2: Implement.** Add `writeRejects24h` to `LedgerCensusRows`, `LedgerCensusFinding`, the alarm condition, and `formatCensusLine`.
-- [ ] **Step 3: Source the count.** Both the census and the reconcile tool count `[graph-write] reject` lines in `<LOG_DIR>/mcp-ledger-*.log` with a timestamp inside the trailing 24 hours.
-- [ ] **Step 4: Tests green, commit.**
-
----
-
-### Task 5: Docs
-
-**Files:** `plugins/ledger/PLUGIN.md`, `plugins/docs/references/ledger.md`
-
-State that the counterparty must be looked up first and passed by id, that the ledger never creates organisations, and what `writeRejects24h` means. Keep the shipped reference free of em-dashes.
-
-- [ ] Commit.
-
----
-
-## Self-review
-
-**Spec coverage.** Type import and cast removal: Task 1. Attribution: Task 1 step 3. Element-id resolution for all four write tools: Task 2. The banned-stub integration test: Task 3. Census counter: Task 4. Docs: Task 5. Out-of-scope items (duplicate-org matching, `:InvoiceLine`, read tools, ledger-core arithmetic) are untouched.
-
-**Risk.** Task 2 changes the tool signatures, so any agent prompt or skill that calls `ledger-invoice-record` with a bare counterparty name breaks. Nothing calls these tools yet except live agent turns, and they have never succeeded, so there is no working caller to regress.

package/payload/platform/docs/superpowers/plans/2026-07-20-storage-pages-create.md

@@ -1,82 +0,0 @@
-# storage-pages-create Implementation Plan
-
-> **For agentic workers:** Implement task-by-task, TDD, commit at the end. Spec: `.tasks/1852-storage-broker-has-no-client-callable-pages-create-so-a-sub-account-cannot-stand-up-a-new-booking-page.md`.
-
-**Goal:** Add a client-callable `storage-pages-create` (MCP tool + `POST /api/storage/pages/create` route) that creates a brand-new Cloudflare Pages project and records the caller as its owner in one operation, mirroring `storage-d1-create`.
-
-**Architecture:** New Hono route in the storage-broker route file, modelled on `/d1/create` with an added Cloudflare-existence check so a pre-existing name is refused (`exists-unregistered`) rather than self-claimed. New thin MCP client tool forwarding to it. Ownership recorded via the existing takeover-safe `registerResource` MERGE. Deploy and adopt contracts unchanged.
-
-**Tech Stack:** TypeScript, Hono, Neo4j (registry), vitest.
-
-## Global Constraints
-
-- Production branch is hard-fixed to `'main'`, never a parameter (a create/deploy branch split would create on one branch and publish on another). State this in a code comment.
-- `registerResource` is takeover-safe (MERGE on `(kind,name)`, `accountId` ON CREATE only). Pages `cfResourceId` is the project name.
-- Deny before the house Pages credential is constructed: `cross-account` and idempotent-owner cases must return before `makeHousePagesExec` is called (tripwire).
-- Correlated `[pages-broker] op=request` / `op=create` log lines (caller, project, existedOnCf, created, decision) — a create must be diagnosable from the log alone, same idiom as deploy.
-- Registration surfaces in the same commit: MCP `index.ts`, `PLUGIN.md`, regenerated `canonical-tool-names.generated.ts`. `storage-pages-deploy` is in no `ADMIN_CORE_TOOLS` or specialist template, so neither is touched.
-- `mcp/dist/` is gitignored (build artifact, not a committed twin): build + grep at verify time, do not commit dist.
-- Shipped skill markdown: zero em-dashes; outcome statements, not command recipes.
-
----
-
-### Task 1: `POST /pages/create` route + route tests
-
-**Files:**
-- Modify: `platform/ui/server/routes/storage-broker.ts` (add route after `/pages/adopt`)
-- Test: `platform/ui/server/__tests__/storage-broker-pages-routes.test.ts` (extend the Neo4j mock to reflect a MERGE; add a `describe('POST /pages/create')` block)
-
-**Interfaces:**
-- Consumes: `caller`, `readJsonBody`, `nameBodyLimit('pages')`, `resolveOwner`, `registerResource`, `makeHousePagesExec(platformRoot())` → `{ pagesProjectList, pagesProjectCreate }`, `log`.
-- Produces: `POST /pages/create` accepting `{project}`; responses `{project,created:true|false}` 200, `{error:'no-caller'}` 403, `{error:'project-required'}` 400, `{error:'cross-account'}` 403, `{error:'exists-unregistered'}` 409, `{error:<str>}` 500.
-
-Route behaviour (ordering preserves the deny-before-credential tripwire):
-1. `account = caller(c)`; null → log deny `no-caller`, 403.
-2. `readJsonBody`; require `project` non-empty string → 400 `project-required`.
-3. `op=request` log line (caller, project).
-4. open session; `resolveOwner(session,'pages',project)`:
-   - owner !== null && owner !== account → `log('write','pages',account,project,owner,'deny')`, 403 `cross-account`.
-   - owner === account → `op=create existedOnCf=? created=false` is not applicable; return `{project,created:false}` 200 (before building exec).
-   - owner === null → continue.
-5. build `exec = await makeHousePagesExec(platformRoot())`; `existed = (await exec.pagesProjectList()).some(p=>p.name===project)`.
-   - existed → `log('write','pages',account,project,null,'deny','exists-unregistered')`, `op=create existedOnCf=true created=false`, 409 `exists-unregistered`.
-   - else → `pagesProjectCreate(project,'main')`, `registerResource(session,{accountId:account,kind:'pages',name:project,cfResourceId:project})`, `log('write','pages',account,project,account,'allow')`, `op=create existedOnCf=false created=true`, 200 `{project,created:true}`.
-6. catch → `{error:String(err)}` 500; finally → `session.close()`.
-
-Test-mock change (backward compatible): add a per-test `registered = new Map()` cleared in `beforeEach`. In `sessionRun`: if cypher includes `'MERGE'`, set `registered.set(\`${params.kind}:${params.name}\`, params.accountId)`, return `{records:[]}`. If cypher includes `'RETURN r.accountId'` (resolveOwner), return the merged owner when present else the `ownerAnswer` behaviour. Existing tests resolve owner before any merge, so behaviour is unchanged.
-
-- [ ] Step 1: Write the five failing route tests (created:true; idempotent created:false; cross-account 403; exists-unregistered 409; create→deploy handoff allow).
-- [ ] Step 2: Run — expect FAIL (route 404s / handler absent).
-- [ ] Step 3: Implement the route.
-- [ ] Step 4: Run — expect PASS, plus the pre-existing 23 still pass.
-
-### Task 2: `storage-pages-create` MCP tool
-
-**Files:**
-- Modify: `platform/plugins/storage-broker/mcp/src/index.ts` (add tool after `storage-pages-deploy`)
-
-Mirror `storage-d1-create`. Description: "Create a new Cloudflare Pages project owned by your account, so you can publish a site to it." Arg `project`. Call `callApi("storage-pages-create","/api/storage/pages/create","POST",{project})`. Map errors:
-- `cross-account` → `Creating the Pages project failed: "<project>" belongs to another account.`
-- `exists-unregistered` → `The Pages project "<project>" already exists on Cloudflare but has no owner on record. A pre-existing project cannot be self-claimed; ask the house admin to record it to your account.`
-- other → `Creating the Pages project failed: <err>`
-- success `created===false` → `The Pages project <project> is already yours.`
-- success else → `Created Pages project <project>. You can now publish to it.`
-
-- [ ] Verify with an ephemeral message-mapping check (discarded after).
-
-### Task 3: Registration surfaces (same commit)
-
-**Files:**
-- Modify: `platform/plugins/storage-broker/PLUGIN.md` — add `storage-pages-create` to the `tools:` block (publicAllowlist:false, adminAllowlist:true) and the `## Tools` list; correct the line-72 sentence so a client-created brand-new project is distinguished from house-recorded ownership of a pre-existing project.
-- Regenerate: `platform/services/claude-session-manager/src/canonical-tool-names.generated.ts` via `cd platform && npm run gen:canonical-tools`.
-- Build + grep (verify only, not committed): `platform/plugins/storage-broker/mcp/dist/index.js` carries `storage-pages-create`.
-
-### Task 4: Skill docs (same commit)
-
-**Files:**
-- Modify: `platform/plugins/cloudflare/skills/site-deploy/SKILL.md:36` — after the `storage-pages-deploy`/`storage-pages-adopt` sentence, add that for a brand-new project the client first creates and claims it with `storage-pages-create`, then deploys; adopt remains only for a project that already exists on Cloudflare the client did not create.
-- Modify: `platform/plugins/cloudflare/skills/calendar-site/SKILL.md:59` — add one sentence naming the client new-project path (`storage-pages-create` then `storage-pages-deploy`), outcome register, no command recipe.
-
-### Verify (Phase 4)
-
-- Route test file passes (28 tests). Ephemeral MCP message check. `check-canonical-tool-names.mjs` and typecheck pass. Build MCP dist, grep for the tool. Full `vitest run` for the ui package (no regressions in the changed area).