Converge Bookkeeping and Sponsors operator surfaces

[alexeygrigorev]

Converge Bookkeeping and Sponsors operator presentation

Status: accepted and committed locally — exact accepted commit 8c3b110c8aa138d95385a89fe3328749bdf47250; not merged, pushed, deployed, shipped, or closed
Tags: enhancement, portal, frontend, testing, design, P1
Depends on: satisfied — accepted containing commits #218 0c89588df809b2e84af02e796d1910a25eea0165, #219 9d204d208820e3d842a3d3fc83493c230bcadaa5, and #220 d334020ca5a582d31a81b371988169cab4e7f6b2
Blocks: #162 Wave C integrated acceptance
Starting inventory baseline: 78e91223203aa54376a318fd1a3214ce0242e0c3
Next owner: Orchestrator — when coordinated publication resumes, merge the accepted local Wave A chain in order, push main, then hand off to On-Call; no implementation or review rerun is pending for #221
Resume condition: local main is clean and the Orchestrator is ready to publish the accepted Wave A chain; #221 requires no rerun unless commit 8c3b110c8aa138d95385a89fe3328749bdf47250 changes

Product outcome

An authenticated operator can move through Bookkeeping's Ledger, Evidence, and Monthly package jobs and a Sponsor booking's Overview, Finance, Communications, and History without deciphering imported-tool layouts.

Each region leads with the current decision, exposes only actions valid under the existing authenticated contract, keeps successful information visible when another source fails, and states precisely what happened. Desktop uses intentional queue/detail or dominant-job composition. Mobile uses one readable decision pane at a time. No UI action claims that money moved or a provider message was sent.

This is presentation and honest-state convergence over existing APIs. It does not authorize a new route, endpoint, field, permission, provider integration, import, migration, or browser-only simulation.

Criterion-to-current-source/test inventory at baseline 78e9122

Already compliant — preserve

• frontend/src/surfaces/finance/bookkeeping.js already renders the three canonical jobs, a semantic ledger table that becomes labeled cards on narrow screens, native form controls, private-evidence linking, explicit destructive confirmation, and the existing monthly snapshot/archive workflow.
• frontend/src/surfaces/finance/sponsors.js, sponsor-layout.js, sponsor-finance.js, sponsor-communications.js, and sponsor-alerts.js already use the canonical /#/sponsors?bookingId=<id> route, authenticated Sponsor CRM projections, server-enforced role behavior, version conflicts, finance idempotency/recovery, exact-review revocation, provider-safe wording, and Overview/Finance/Communications/History data.
• Current Sponsor finance links existing synthetic Bookkeeping evidence; it does not execute a payment. Reviewed communications queue through the existing guarded contract and never send inline. Those safety contracts are frozen.
• Existing dialogs, confirmations, native labels, status/alert regions, selected-booking state, close/return behavior, light/dark tokens, responsive route styles, and 44px narrow-screen controls are current foundations, not a reason to rebuild the surfaces.
• frontend/test/finance-surface.test.mjs covers Bookkeeping and Sponsor rendering, validation, mutations, finance recovery/idempotency, communications review safety, and route behavior.
• backend/e2e/canonical-capability-behavior.spec.js provides real-server runtime evidence for the six current Bookkeeping states and eight current Sponsor role/state cases. The catalog in backend/e2e/frontend-capabilities.json already defines those durable identities.
• backend/e2e/bookkeeping-production-portal.spec.js, sponsor-crm-production-portal.spec.js, and sponsor-crm-communications-production-portal.spec.js preserve additional real authenticated behavior. They remain regression owners.
• Accepted Restore behavior-based browser coverage and fix canonical UI accessibility races #180 browser/focus diagnostics and accepted Finalize the canonical scan-first Operations Home #161 Home/shell composition are present in the containing baseline. Converge Bookkeeping and Sponsors operator surfaces #221 does not reopen them.

Concrete unmet gaps owned by #221

1. Bookkeeping job navigation breaks the canonical hash route. The three controls use href="#bookkeeping-*" inside a hash-routed application. Activating one can replace /#/bookkeeping rather than preserving the workspace route. Replace this with route-preserving job navigation that exposes the current job, moves focus/scroll intentionally, and does not add history entries or a second router.
2. Bookkeeping loading is falsely all-or-nothing. Transactions load before Evidence accounts/documents/links inside one catch path. One failed source replaces unrelated successful regions with generic text. Ledger, Evidence, and Monthly package must settle independently: successful regions remain usable, unavailable regions are named, and retry is local and observable.
3. Bookkeeping mutation feedback can live behind an open modal or away from the initiating job. Save/delete/upload/report failures currently funnel through one page status. Dialog validation/conflict/failure must retain entered values, announce and focus useful in-dialog guidance, prevent duplicate submission, and leave the authoritative record unchanged. Job-level failures and success belong beside the initiating job.
4. Monthly package completion is under-specified. A global “Snapshot ready” or warning count does not make the durable result and selected month clear. Present the existing server result as a reviewable completion/warning state without exposing storage paths, inventing persisted fields, or changing the existing private-download contract.
5. Sponsor detail lacks a coherent responsive section contract. Overview, Finance, Communications, and History are one long stack controlled by scroll buttons. Provide an accessible selected-section model that preserves the booking URL and loaded state. Desktop may retain intentional detail composition; at 390×844 only the selected section is the active decision pane, with a reachable Return to bookings action and no loss of section context during rerender/retry.
6. Sponsor finance presents too many equal-weight actions. The existing permitted actions must be ordered around one state-valid next action, with secondary evidence operations quiet and unlink/void actions visibly separated and confirmed. Existing role, version, idempotency, outcome-unknown, reconciliation, and no-payment semantics remain exact.
7. Sponsor communication states are visually undifferentiated. Suggestions, drafts awaiting review, immutable attempts, disabled delivery, and recovery/history should be grouped and labeled by operator decision. Copy must continue to distinguish draft, exact review, queued, provider accepted, delivered, delayed, rejected, outcome unknown, and read receipt. No state may imply a provider send or recipient read that the API did not prove.
8. Sponsor history exposes implementation-shaped chronology. Render status history as a semantic chronological list with human labels and Europe/Berlin dates/times rather than raw timestamps. Keep the current safe projection only; do not surface private notes, addresses, raw IDs, provider codes, or hidden metadata.
9. The visual regression owner is not valid behavior evidence. backend/e2e/bookkeeping-sponsors-design-production-portal.spec.js intercepts application requests and uses palette/style assertions. Replace it in the same change with a dedicated Converge Bookkeeping and Sponsors operator surfaces #221 real-server journey that emits durable capability evidence. Do not leave old and new harnesses in parallel.

Dependency-owned — do not absorb

• Converge Wave A surfaces on bounded shared UI primitives #218: canonical page-header, action-row, form/footer, semantic-status, honest-state, token, and responsive primitive presentation across Wave A. Converge Bookkeeping and Sponsors operator surfaces #221 starts after its accepted commit, consumes those primitives, and may add only Bookkeeping/Sponsor-specific layout rules.
• Restore behavior-based browser coverage and fix canonical UI accessibility races #180: browser diagnostics, fixture isolation, focus race fixes, and retained journey behavior.
• Finalize the canonical scan-first Operations Home #161: Home, shell, navigation, account composition, and Home evidence.
• Show signed-in identity and authorized teammates’ Task/Card work #164: actor/selected-owner identity, teammate scope, Users/Admin authorization, and delegated work.
• Make assistant output review safe and lifecycle-complete #158: Assistant/Artifact lifecycle and access.
• Restore canonical frontend behavior coverage and SAM parity gates #159: capability evidence schema, collector/reporter, and source/SAM parity machinery. Converge Bookkeeping and Sponsors operator surfaces #221 may add exact state records and emit them; it must not change the machinery.
• Existing Bookkeeping, Sponsor CRM, finance, and communications backend contracts/tests own authorization, concurrency, idempotency, safe projections, and provider boundaries. A missing contract stops this issue and requires a separately groomed backend issue.

Exact write ownership

Implementation may edit only these production paths:

• frontend/src/surfaces/finance/bookkeeping.js
• frontend/src/surfaces/finance/sponsors.js
• frontend/src/surfaces/finance/sponsor-layout.js
• frontend/src/surfaces/finance/sponsor-alerts.js
• frontend/src/surfaces/finance/sponsor-finance.js
• frontend/src/surfaces/finance/sponsor-communications.js
• frontend/src/styles.css — only route-specific Bookkeeping/Sponsor layout after Converge Wave A surfaces on bounded shared UI primitives #218; no shared primitive redefinition

Allowed test/evidence paths:

• frontend/test/finance-surface.test.mjs
• backend/e2e/bookkeeping-sponsors-design-production-portal.spec.js may be replaced/renamed; the intercepted prototype owner must not remain
• one replacement backend/e2e/issue-221-bookkeeping-sponsors.spec.js
• backend/e2e/frontend-capabilities.json only for exact new Bookkeeping/Sponsor presentation states exercised by the normal real-server run

Existing canonical capability, Bookkeeping, Sponsor CRM, finance, and communications specs are read-only regression owners. #159 helpers/reporter/schema are read-only. Any newly required production or test path needs PM amendment before editing.

Because styles.css, all six finance modules, finance-surface.test.mjs, the capability catalog, and browser fixture capacity overlap #218, implementation is serialized after #218 by default. It may start earlier only if the Orchestrator and both issue owners prove exact disjoint paths and record that decision on both issues. Reconstruct from the accepted containing baseline; do not merge/replay a stale prototype or silently overwrite #218.

Acceptance criteria

Bounded implementation and no-backcompat boundary

• Before editing, the engineer records the exact post-Converge Wave A surfaces on bounded shared UI primitives #218 starting SHA and posts a refreshed criterion-to-current-source/test inventory, classifying each item as already compliant, concrete gap, dependency-owned, or out of scope.
• Only concrete gaps above are changed. Existing authenticated routes, request/response shapes, role projections, versions, idempotency keys, domain states, and provider safeguards remain unchanged.
• The implementation consumes Converge Wave A surfaces on bounded shared UI primitives #218 primitives and deletes superseded route-specific declarations in the same change. No duplicate old/new classes, alias-only selectors, legacy fallback, compatibility shim, second route model, or parallel intercepted test harness remains.
• No browser-only fake success, client-side authorization, new API/persisted field, migration/import path, private-data lookup, provider call, or broad CSS rewrite is introduced.

Bookkeeping

• Ledger, Evidence, and Monthly package have route-preserving job controls. Activating a job leaves the canonical URL /#/bookkeeping, gives the selected control a programmatic state, moves focus to the owned heading or first useful recovery control, and does not corrupt Back/Forward behavior.
• Ledger, accounts, documents, and links settle independently through the real local server. A deterministic single-source failure keeps successful regions and entered filters visible, names only the unavailable source, never reports a false zero/success, and provides a local retry.
• Add/edit/delete validation, conflict, non-404 failure, and retry retain entered values and useful focus, announce the exact outcome in the initiating dialog/job, disable duplicate submission while pending, and produce at most one intended mutation.
• Evidence upload/link/unlink keeps the selected file metadata, document type, account/month, and transaction context when a retry is safe; private download language remains truthful and no private URL/path appears in screenshots or logs.
• Monthly package validation and completion identify the selected month, existing missing-evidence warning count, and whether the package is ready under the current response. The UI does not claim a download opened or a package completed before authoritative success.

Sponsors

• Opening a synthetic booking preserves /#/sponsors?bookingId=<id>, exact selected booking, safe sponsor label, and Return to bookings behavior across refresh, section changes, Back, Forward, retry, and stale/not-found recovery.
• Overview, Finance, Communications, and History use one programmatically selected section contract. At 1440×900 the booking queue/detail hierarchy remains intentional; at 390×844 only the selected section is the active decision pane and all section/return controls remain reachable.
• Overview leads with current status and next relevant dates using human labels. It displays only fields already present in the authenticated safe projection; raw IDs, email addresses, private notes, artifact/provider/storage metadata, and reason codes are not introduced as routine presentation.
• Finance exposes one state-valid primary action, quiet secondary evidence actions, and separately confirmed unlink/void actions. Operator/admin visibility, 409 reload, outcome-unknown same-operation retry, reconciliation, and idempotency behavior are preserved exactly.
• Finance never claims money was paid by an operator action. Existing linked synthetic payment evidence may be displayed as recorded evidence only.
• Communications distinguish suggestion, draft/review, queued/dispatch, provider fact, outcome-unknown, and disabled/recovery groups. Drafting and exact review never imply approval or send; queued never implies provider acceptance; delivered never implies read.
• History is a semantic chronological list with humanized transitions and Europe/Berlin dates/times. Empty history is explicit. Existing safe notes may appear only when returned by the current authenticated projection and must be synthetic in evidence.
• Partial Finance or Communications failure leaves Overview, History, and other successful sections usable. Retry belongs to the failed section and restores useful focus without changing booking identity.

Desktop, mobile, accessibility, and honest states

• At 1440×900 each captured state has one dominant heading/decision region, readable content width, clear primary/secondary/destructive action hierarchy, and no equal-weight dashboard clutter.
• At 390×844 jobs/sections reflow in reading order, every interactive target is at least 44×44 CSS pixels, the first meaningful record/state/recovery action is visible in the initial viewport for the selected job/section, and there is no page-level horizontal scroll, clipping, overlap, or unreachable action.
• Both themes use existing tokens and retain semantic contrast. Reduced motion removes smooth section transitions without losing state, focus, or orientation.
• Changed states preserve one main landmark, correctly nested headings, native labels, semantic table/list/description/dialog structure, accessible names/descriptions, visible focus, keyboard operation, modal focus containment/restoration, and useful focus after close/retry.
• Loading/busy, empty, partial, unavailable, validation, conflict, success, and destructive states are textually and programmatically distinct. Blocking failures use an alert; progress/success use an appropriate status/live region; status meaning never relies on color alone.
• Axe reports zero critical or serious WCAG A/AA findings for every captured changed state.

Real-server behavior, capability evidence, and parity

• The intercepted design prototype spec is removed/replaced. The dedicated Converge Bookkeeping and Sponsors operator surfaces #221 journey uses the normal local TypeScript backend, authenticated synthetic fixtures, and real requests; it does not intercept core application API calls.
• Core proof uses observable route, DOM, focus, request completion, persisted state, and emitted capability evidence—not source-string assertions, fixed sleeps, history-length arithmetic, serial fallout, broad 404 swallowing, incidental copy/whitespace pins, retries, screenshot assertions, palette pins, pixel goldens, or expected-count constants.
• Existing Bookkeeping and Sponsor capability states still pass. New durable state IDs cover at least Bookkeeping partial-source recovery and Sponsor selected-section, Finance recovery, Communications disabled/review, and History presentation; every ID is emitted only by a passed real-server journey.
• The successful full browser run accounts for every catalog state and role. Source and packaged SAM parity runs emit the same applicable Converge Bookkeeping and Sponsors operator surfaces #221 evidence, with no screenshot- or source-inspection-only state.
• Every changed frontend asset is identical in source, backend/dist, and packaged SAM output.
• Fixtures, screenshots, logs, comments, and capability payloads contain only synthetic public-safe records: .invalid contacts where unavoidable in private review UI, example domains, synthetic amounts, and no real sponsor, finance, contact, provider, private link, credential, operational note, or production identifier.

Test scenarios

Bookkeeping job route and partial Evidence outage

Given an authenticated synthetic operator, a populated ledger, linked evidence, and a deterministic documents or links failure through the real local server
When the operator activates Ledger, Evidence, and Monthly package in turn
Then the URL remains /#/bookkeeping, selected/focus state follows the active job, successful ledger data remains usable, only the failed Evidence source is unavailable, and local retry restores it without losing filters or selections

Bookkeeping validation, retry, and monthly completion

Given public-safe entered transaction and monthly-package values
When validation fails, a deterministic retryable mutation fails, and the same operation is retried
Then the dialog/job retains values and focus, announces the failure, prevents duplicate writes, and the eventual server success identifies the exact saved entry or selected package month without exposing a private URL

Sponsor responsive section journey

Given one authenticated synthetic booking with safe Overview, Finance, Communications, and History data
When it is opened directly, refreshed, each section is selected, Return is used, and Back/Forward revisits it at 1440×900 and 390×844
Then booking identity and URL stay synchronized, one mobile decision pane is active, section/return focus is useful, and no state is clipped or unreachable

Sponsor Finance recovery without payment

Given an admin-visible finance projection and an operator-safe projection
When a permitted local evidence action encounters 409 or outcome-unknown and is recovered
Then one state-valid action remains dominant, the original idempotency contract is preserved, the operator cannot mutate, destructive evidence actions require confirmation, and no UI text says that money moved

Sponsor Communications and History honesty

Given synthetic suggestions, an awaiting-review draft, disabled delivery, immutable attempt states, and booking history
When Communications and History are selected
Then each communication state is grouped with precise draft/queue/provider/read semantics, no provider call occurs, history is chronological with Europe/Berlin time, and a partial Communications failure leaves Overview/History usable

Source/SAM identity

Given one frozen candidate and clean source and SAM servers
When the dedicated #221 journeys run against both targets
Then the same routes, roles, durable states, focus outcomes, and synthetic records pass, all evidence is accounted for, and every changed frontend asset is identical

Synthetic screenshot inventory

Capture exactly these 14 untracked native-size PNGs under .tmp/screenshots/issue-221/; remove stale extras before review:

• 01-bookkeeping-ledger-ready-desktop-1440x900.png
• 02-bookkeeping-ledger-ready-mobile-390x844.png
• 03-bookkeeping-evidence-partial-desktop-1440x900.png
• 04-bookkeeping-evidence-partial-mobile-390x844.png
• 05-bookkeeping-monthly-complete-desktop-1440x900.png
• 06-bookkeeping-monthly-complete-mobile-390x844.png
• 07-sponsors-overview-ready-desktop-1440x900.png
• 08-sponsors-overview-ready-mobile-390x844.png
• 09-sponsors-finance-recovery-desktop-1440x900.png
• 10-sponsors-finance-recovery-mobile-390x844.png
• 11-sponsors-communications-disabled-desktop-1440x900.png
• 12-sponsors-communications-disabled-mobile-390x844.png
• 13-sponsors-history-ready-desktop-1440x900.png
• 14-sponsors-history-ready-mobile-390x844.png

Use normal local backend behavior and synthetic public-safe records. Tester and Designer inspect every image at native resolution for decision hierarchy, wording, selected state, focus visibility, target sizing, theme/contrast, overflow, clipping, overlap, first-decision visibility, and absence of private facts. Screenshots are not committed, attached to the public issue, treated as behavior evidence, or compared as goldens.

Verification

Engineer may use focused tests while iterating:

node --test frontend/test/finance-surface.test.mjs
npm --prefix backend run test:e2e -- e2e/issue-221-bookkeeping-sponsors.spec.js --retries=0 --reporter=line
git diff --check

Tester runs the complete relevant workflow on one frozen diff/status/content fingerprint and records commands, exit codes, observed test counts, behavior titles, capability-state/role accounting, and evidence/screenshot paths:

npm run test:frontend:unit
npm run test:frontend:coverage
npm --prefix backend test
npm --prefix backend run typecheck
npm --prefix backend run build
node backend/scripts/verify-frontend-artifact.mjs --source frontend --artifact backend/dist
npm --prefix backend run test:e2e -- --retries=0
npm --prefix backend run test:e2e:frontend-parity
make sam-validate
make sam-build
node backend/scripts/verify-frontend-artifact.mjs --source frontend --artifact .aws-sam/build/BackendFunction
make ci
git diff --check

Do not run raw Bookkeeping/Sponsor import, migration, restore, export, payment, provider-send, worker, SES-event, transaction shell, or one-off data-movement scripts for this issue.

Lifecycle gates

• PM inventory completed read-only at 78e91223203aa54376a318fd1a3214ce0242e0c3
• Accepted Restore behavior-based browser coverage and fix canonical UI accessibility races #180 browser/focus foundation and accepted Finalize the canonical scan-first Operations Home #161 Home/shell foundation reconciled
• PM-groomed Converge Wave A surfaces on bounded shared UI primitives #218 shared-primitives ownership reconciled
• Converge Wave A surfaces on bounded shared UI primitives #218 receives Designer/Tester/PM acceptance and an exact commit
• Orchestrator records the post-Converge Wave A surfaces on bounded shared UI primitives #218 starting SHA and shared writer order
• Software Engineer posts the refreshed inventory and implements only current unmet gaps
• Software Engineer posts frozen diff/status/content fingerprints and READY FOR TEST
• Designer inspects exactly 14 screenshots and posts DESIGN PASS
• Independent Tester verifies every criterion and posts TESTER PASS on the same fingerprint
• PM reviews the operator journey and posts ACCEPTED on the same fingerprint
• Software Engineer commits only accepted issue-owned paths with Closes #221
• Orchestrator merges locally in the coordinated Replace the transitional Tasks table with the final cardId schema #166-safe order and pushes main
• On-Call verifies CI/CD, deployment, source/SAM identity, and smoke evidence before Converge Bookkeeping and Sponsors operator surfaces #221 is called shipped or closed

No HUMAN gate is required: all accepted proof is local, synthetic, authenticated, provider-free, and non-production.

Explicit exclusions

• Live payment, payment initiation, bank/provider mutation, SES/provider send, worker dispatch, production message, or recipient-read verification.
• Bookkeeping/Sponsor imports, migrations, restores, export/data-movement tooling, persisted-schema changes, data backfill, seed migration, or one-off production repair.
• New or expanded API, response field, DynamoDB shape/index, permission, role, authorization rule, idempotency contract, or server-side safe projection.
• Raw/private operational facts, real sponsors or contacts, production amounts/identifiers, private links, artifact/storage paths, provider metadata, credentials-adjacent setup, or committed/public screenshot evidence.
• Home, shared shell, account/team identity, selected owner, Users/Admin, global navigation, Settings, notifications, Task/Card behavior, Assistants/Artifacts, Newsletter, Calendar, Mailing exports, or Process Docs.
• Reopening Restore behavior-based browser coverage and fix canonical UI accessibility races #180 focus/browser work, Finalize the canonical scan-first Operations Home #161 Home behavior, Show signed-in identity and authorized teammates’ Task/Card work #164 authorization/identity, Make assistant output review safe and lifecycle-complete #158 lifecycle, Restore canonical frontend behavior coverage and SAM parity gates #159 evidence machinery, or Converge Wave A surfaces on bounded shared UI primitives #218 shared primitive definitions.
• Broad CSS rewrite, stylesheet split, framework/component library, new router/runtime abstraction, second frontend, visual novelty work, compatibility aliases, duplicate old/new presentation, or stale prototype replay.
• Editing source repositories, AWS/infrastructure, workflows, manual deployment, provider access, production data, or HUMAN gates.

[alexeygrigorev]

PM GROOMED — agent-ready bounded Wave A Bookkeeping/Sponsors slice

I completed a read-only criterion-to-current-source/test inventory at clean baseline 78e91223203aa54376a318fd1a3214ce0242e0c3, reconciled parent #162, accepted #180 browser/focus foundations, accepted #161 Home/shell foundations, and PM-groomed #218.

The issue now owns only concrete presentation and honest-state gaps in the existing authenticated Bookkeeping and Sponsor surfaces:

• route-preserving Ledger/Evidence/Monthly job navigation;
• independent Bookkeeping source settlement, local retry, in-context modal feedback, and truthful monthly-package completion;
• a responsive selected-section contract for Sponsor Overview/Finance/Communications/History;
• one state-valid Finance action hierarchy while preserving authorization, version, idempotency, reconciliation, and no-payment semantics;
• grouped Communications language that never conflates draft, queue, provider acceptance, delivery, or read;
• semantic Europe/Berlin booking history;
• replacement of the intercepted visual prototype spec with durable normal-server capability/source-SAM evidence.

Implementation is explicitly sequenced after #218 because shared styles, finance modules, unit tests, capability catalog, and browser capacity overlap. The issue includes exact production/test write ownership, a required refreshed post-#218 inventory, measurable 1440×900 and 390×844 behavior, accessibility/honest-state criteria, exactly 14 synthetic public-safe screenshots, full commands and lifecycle gates, and a no-backcompat requirement that deletes superseded styles and the intercepted harness rather than retaining parallel contracts.

Excluded: live payment, provider send, imports/migrations/restores/exports, API/data-model/permission expansion, private operational facts, Home/shell/account/team identity, broad CSS work, infrastructure/deploy/provider actions, and HUMAN gates.

Labels are enhancement, portal, frontend, testing, design, and P1. needs grooming was removed because the issue is self-contained; it remains implementation-blocked only on #218's accepted exact commit and recorded writer order.

No repository file, worktree, commit, push, deployment, provider, production/private data, or HUMAN gate was touched.

Next owner: Orchestrator records the accepted post-#218 starting SHA and shared-path order; Software Engineer posts the refreshed inventory before editing.

[alexeygrigorev]

ORCHESTRATOR START — accepted containing baseline and writer order

Issue #221 starts from exact accepted #220 commit d334020ca5a582d31a81b371988169cab4e7f6b2 (tree 52cabe9d926446a6ed4644458f817fd0c9dd82bf), which contains accepted #218 commit 0c89588df809b2e84af02e796d1910a25eea0165 and accepted #219 commit 9d204d208820e3d842a3d3fc83493c230bcadaa5.

Project-local worktree: .tmp/worktrees/issue-221-bookkeeping-sponsors
Branch: issue-221-bookkeeping-sponsors

Shared writer order is serialized: #218 -> #219 -> #220 -> #221. #221 therefore owns its groomed finance paths only on this accepted containing baseline. #222 remains pending and must start after the accepted #221 commit because shared styles, capability catalog, and browser capacity overlap.

Next owner: Software Engineer. Before editing, post the required refreshed criterion-to-current-source/test inventory against d334020 and stop for PM amendment if any required path or backend contract falls outside the groomed boundary.

No product file, commit, merge, push, deployment, provider, production/private data, or HUMAN action was changed by this orchestration handoff.

[alexeygrigorev]

SWE PRE-EDIT REFRESHED INVENTORY — exact accepted containing baseline

Baseline and containment

• Clean starting HEAD: d334020ca5a582d31a81b371988169cab4e7f6b2 (tree 52cabe9d926446a6ed4644458f817fd0c9dd82bf).
• Accepted ancestors verified: Converge Wave A surfaces on bounded shared UI primitives #218 0c89588df809b2e84af02e796d1910a25eea0165, Converge Templates and Recurring operator flows #219 9d204d208820e3d842a3d3fc83493c230bcadaa5, and Converge Process Docs and search operator flows #220 at current HEAD.
• Worktree was clean before this inventory. No edit, stage, commit, merge, push, deploy, provider/private-data access, or HUMAN action has occurred.
• Writer order from the orchestration handoff is preserved: Converge Wave A surfaces on bounded shared UI primitives #218 → Converge Templates and Recurring operator flows #219 → Converge Process Docs and search operator flows #220 → Converge Bookkeeping and Sponsors operator surfaces #221. This issue will edit only the production/test paths listed in the groomed body.

Criterion-to-current-source/test classification

Bounded implementation

1. Already compliant: the current surfaces use the existing authenticated Bookkeeping and Sponsor APIs, canonical /#/bookkeeping and /#/sponsors?bookingId=<id> routes, server projections, versions, finance idempotency keys, exact-review revocation, and provider-safe copy. These contracts remain unchanged.
2. Concrete gap: route-specific legacy/intercepted presentation remains in backend/e2e/bookkeeping-sponsors-design-production-portal.spec.js; it must be replaced, not retained alongside the Converge Bookkeeping and Sponsors operator surfaces #221 journey. Route-specific Bookkeeping/Sponsor CSS will be converged without redefining Converge Wave A surfaces on bounded shared UI primitives #218 primitives.
3. Dependency-owned: Converge Wave A surfaces on bounded shared UI primitives #218 shared primitives and tokens; Restore canonical frontend behavior coverage and SAM parity gates #159 capability schema/collector/reporter/parity machinery; Restore behavior-based browser coverage and fix canonical UI accessibility races #180 browser/focus infrastructure; Finalize the canonical scan-first Operations Home #161 shell/Home; Show signed-in identity and authorized teammates’ Task/Card work #164 identity/authorization; Make assistant output review safe and lifecycle-complete #158 lifecycle; backend/API authorization, concurrency, projection, finance, communication, and provider contracts.
4. Out of scope: browser-only fake success, client authorization, new API/persisted fields, migration/import/export/restore/data movement, private-data lookup, provider/payment/send calls, broad CSS/framework/router work, and compatibility aliases.

Bookkeeping

5. Concrete gap: bookkeeping.js still uses href="#bookkeeping-*" job links. They can replace the SPA hash, have no selected-state contract, and use no owned focus behavior. Replace with route-preserving controls that keep /#/bookkeeping, expose the selected job, and focus its heading/recovery control without adding history.
6. Concrete gap: initial load is one try and refreshEvidence() uses one Promise.all; a transaction/document/link/account failure collapses unrelated regions. Split ledger, accounts, documents, and links into independently settled states with source-local alert/retry UI and retained filters/selections.
7. Concrete gap: safeAction() writes mutation failures to the page-global status. Save/delete/upload/report controls are not consistently disabled while pending; save/delete errors can sit behind dialogs; successful save/delete lacks initiating-job feedback. Add local live/error regions, retain values, restore useful focus, and prevent duplicate submission.
8. Already compliant: required add/edit fields already set aria-invalid, retain form values, and focus the missing field; delete already uses explicit confirmation; upload already carries current file/type/account/month/transaction values and the existing request/idempotency contracts; private downloads remain five-minute links opened only after server success. Preserve these foundations.
9. Concrete gap: upload/link/unlink failures currently report globally and refresh all evidence. Retain safe retry context and report in Evidence without exposing a private URL/path.
10. Concrete gap: monthly package currently reports only a generic warning count or Snapshot ready., immediately archives, and opens a private URL. Add a local reviewable state naming month, warning count, and authoritative ready result; do not claim completion/download before server success and do not render a storage path.

Sponsors

11. Already compliant: requested booking identity is read from the canonical route; booking rows navigate canonically; selected row and Return behavior exist; role-safe Overview/Finance/Communications/History data already come from authenticated projections. Preserve refresh/stale/not-found and exact-review navigation safety.
12. Concrete gap: section buttons reset to Overview on rerender and only smooth-scroll all four panels. Add one programmatic selected-section contract that survives in-memory rerender/retry, preserves the booking URL/identity, focuses the selected heading/recovery control, and exposes only the selected decision pane at 390×844.
13. Concrete gap: Overview’s status is secondary in the header and dates are raw ISO strings; make current status and next relevant dates the leading human-labeled decision while displaying no fields beyond the existing safe projection.
14. Concrete gap: sponsor-finance.js renders classification, invoice, payment, reconciliation, unlink, and void controls in one equal-weight action row. Derive one state-valid primary action; keep evidence actions quiet; isolate confirmed unlink/void actions. Preserve operator/admin visibility, version, 409 reload, outcome-unknown same-key retry, reconciliation, idempotency, and no-payment language.
15. Already compliant: Sponsor Finance links existing Bookkeeping evidence only; recovery copy says no payment is counted and current UI does not execute payment. Preserve and make recorded-evidence wording explicit.
16. Concrete gap: sponsor-communications.js concatenates disabled, suggestion, draft, and attempt cards without decision groups. Group and label suggestion, draft/review, queued/dispatch, provider fact, outcome-unknown, and disabled/recovery states while preserving precise queue/provider/delivered/read semantics and existing permissions.
17. Concrete gap: sponsors.js history is non-semantic <div> chronology with raw timestamps. Render a chronological list with human transitions and Europe/Berlin date/time; retain only currently projected safe notes and an explicit empty state.
18. Concrete gap: reopenBookingDetail() awaits History before rendering, then awaits Finance and Communications serially; a section failure can collapse the detail. Settle History, Finance, and Communications independently; keep Overview and successful panels usable; add section-local retry with useful focus and unchanged booking identity.

Desktop/mobile/accessibility/honest states

19. Concrete gap: current desktop composition and mobile section behavior do not yet prove one dominant decision region or one selected mobile pane. Add only Bookkeeping/Sponsor-specific layout rules in styles.css consuming Converge Wave A surfaces on bounded shared UI primitives #218 primitives.
20. Already compliant: accepted shared tokens/themes, base 44px narrow-screen controls, native form controls, semantic ledger table/cards, one outer main landmark, modal foundations, destructive confirmations, and reduced-motion foundation exist. Preserve them.
21. Concrete gap: changed job/section controls, local loading/partial/unavailable/recovery/success states, heading focus, and grouped actions need explicit semantic/programmatic states and tests. Blocking failures will be alerts; progress/success will use status/live regions; meaning will remain textual, not color-only.
22. Verification-owned after implementation: 1440×900 and 390×844 hierarchy, initial-viewport usefulness, 44×44 targets, overflow/clipping/overlap, both themes, reduced motion, keyboard/focus/modal behavior, and zero critical/serious Axe findings must be proven by the dedicated real-server journey and exactly 14 native screenshots on the frozen candidate.

Real-server behavior, capability evidence, and parity

23. Concrete gap: the current bookkeeping-sponsors-design-production-portal.spec.js intercepts core app APIs, asserts exact palette/CSS, and captures the obsolete screenshot set. Delete/replace it with backend/e2e/issue-221-bookkeeping-sponsors.spec.js using the normal local TypeScript backend and authenticated synthetic fixtures.
24. Concrete gap: add observable journey assertions for canonical route, DOM, selected state, focus, request completion/persistence/recovery, accessibility, responsive behavior, and emitted capability evidence. Avoid source-string checks, fixed sleeps, history arithmetic, broad 404 swallowing, retries, screenshot assertions/goldens, palette pins, and expected-count constants.
25. Already compliant: canonical real-server specs own the six Bookkeeping and eight Sponsor runtime states and remain read-only regression owners. Restore canonical frontend behavior coverage and SAM parity gates #159’s full catalog/role accounting and source/SAM parity machinery are present and read-only.
26. Concrete gap: add exact durable catalog IDs for Bookkeeping partial-source recovery and Sponsor selected-section, Finance recovery, Communications disabled/review, and History presentation, each emitted only by passed Converge Bookkeeping and Sponsors operator surfaces #221 real-server journeys for applicable roles.
27. Verification-owned after implementation: full browser capability/role accounting, source/SAM parity, and source→backend/dist→SAM asset identity will be run on one frozen candidate.
28. Already compliant / preserve: existing fixtures use synthetic/example records and .invalid contacts where private review requires an address. New fixture data, screenshots, logs, comments, and evidence will remain public-safe and contain no private URL/path, real sponsor/contact/amount/provider fact, credential, note, or production identifier.

Explicit out-of-scope ownership

29. Out of scope: live payment/payment initiation/bank mutation; SES/provider send/worker dispatch/production messaging/read verification.
30. Out of scope: Bookkeeping/Sponsor imports, migrations, restores, exports/data movement, schema/index/backfill/seed/repair work.
31. Out of scope: API/response/DynamoDB/permission/role/authorization/idempotency/projection expansion.
32. Out of scope: real/private operational facts and links; Home/shell/account/team/Users/Admin/global nav/Settings/notifications/Task/Card/Assistants/Artifacts/Newsletter/Calendar/Mailing/Process Docs; reopening Restore behavior-based browser coverage and fix canonical UI accessibility races #180/Finalize the canonical scan-first Operations Home #161/Show signed-in identity and authorized teammates’ Task/Card work #164/Make assistant output review safe and lifecycle-complete #158/Restore canonical frontend behavior coverage and SAM parity gates #159/Converge Wave A surfaces on bounded shared UI primitives #218; broad CSS/framework/router/second-frontend/backcompat work; source-repo/AWS/workflow/deploy/provider/production/HUMAN actions.

Conclusion

All current unmet criteria map to the authorized #221 production/test paths. No missing backend/API contract or unauthorized path has been identified, so implementation can proceed without a PM amendment. I will stop and request a narrow amendment before touching any newly required path if that changes during implementation.

[alexeygrigorev]

SWE NARROW PM AMENDMENT REQUEST — capability state allowlist

The frozen #221 candidate reached the complete backend test gate. The groomed acceptance explicitly requires new durable Bookkeeping/Sponsor state IDs and authorizes their records in backend/e2e/frontend-capabilities.json. The read-only schema test backend/scripts/frontend-capabilities.test.mjs hard-codes the pre-#221 exact state arrays and fails with bookkeeping state coverage drifted as soon as the required IDs are added; Sponsor will require the corresponding exact-list update as well.

Please amend #221 write ownership narrowly to allow only:

• backend/scripts/frontend-capabilities.test.mjs
• only the expected Bookkeeping and Sponsor state-ID arrays needed to admit the groomed Converge Bookkeeping and Sponsors operator surfaces #221 catalog records
• no schema, collector, reporter, role, route, evidence-accounting, or parity machinery change

I have not touched that path. Current allowed-path implementation remains unstaged/uncommitted. Frontend unit is 305/305 and coverage passes at 76.51%. The aggregate backend run also showed unrelated concurrent local-state failures in conversational suites; after the owned allowlist is resolved I will rerun the gate cleanly and classify only reproducible evidence.

BLOCKED ON NARROW PM AMENDMENT; no backend/API/provider/production/HUMAN action taken.

[alexeygrigorev]

PM AMENDMENT APPROVED — capability state allowlist only

Decision

The narrow ownership amendment is approved. Read-only inspection at candidate HEAD d334020ca5a582d31a81b371988169cab4e7f6b2 confirms that the already-authorized additions in backend/e2e/frontend-capabilities.json necessarily fail the exact-state contract in backend/scripts/frontend-capabilities.test.mjs: the focused verifier reports bookkeeping state coverage drifted before it can evaluate the Sponsor additions. Updating the expected state suffixes is therefore required to make the groomed durable-state acceptance criterion testable; it does not broaden product behavior.

Newly authorized path and exact line purpose

• backend/scripts/frontend-capabilities.test.mjs
• Only the REQUIRED.bookkeeping.states array currently at lines 59–62 may add these exact suffixes:
  • job-selection
  • partial-source-recovery
  • monthly-review-ready
• Only the REQUIRED.sponsors.states array currently at lines 63–66 may add these exact suffixes:
  • selected-section
  • finance-recovery
  • communications-disabled
  • communications-review-contract
  • history-presentation
• Keep the existing state suffixes unchanged. Reformatting those two array literals is acceptable only as needed to make the exact additions readable; no unrelated mechanical churn is authorized.

Frozen invariants

• This approval changes expected state membership only. It does not authorize edits to schema version, catalog contract, evidence policy, routes, API boundaries, role sets or role overrides, state-role inheritance, allowed-kind taxonomy, collector, reporter, annotation/evidence accounting, source/SAM parity, artifact identity, workflow wiring, or any assertion/control flow outside those two state arrays.
• backend/e2e/frontend-capabilities.json remains limited by the original grooming to exact Converge Bookkeeping and Sponsors operator surfaces #221 Bookkeeping/Sponsor presentation records emitted by passing normal-server journeys. This amendment does not approve additional records or IDs.
• Every new record must still satisfy the existing verifier unchanged. In particular, the current candidate values kind: "conflict" for sponsors.finance-recovery and kind: "disabled" for sponsors.communications-disabled are not members of the existing ALLOWED_KINDS set (loading, empty, ready, stale, permission, error). This amendment does not authorize widening that taxonomy; the Software Engineer must map those records to an existing truthful kind within the already-authorized catalog path.
• No new role override is authorized. The new states retain the capability role contract unless an independently justified PM amendment is requested before editing.
• Existing canonical Bookkeeping/Sponsor specs and all Restore canonical frontend behavior coverage and SAM parity gates #159 schema/collector/reporter/parity machinery remain read-only regression owners.
• No API, backend runtime, persisted data, provider, production, deployment, infrastructure, source-repository, or HUMAN action is authorized.

Verification consequence

After making only the approved allowlist additions and correcting catalog records within their existing ownership to satisfy the frozen taxonomy, rerun the focused verifier and the complete issue-defined backend/frontend/E2E, capability-role accounting, source/SAM parity, artifact-identity, accessibility, and screenshot workflow on one newly frozen candidate. A focused pass alone is not acceptance evidence.

Next owner: Software Engineer. Apply the exact two-array amendment, keep every invariant above, rerun and classify reproducible gates, then post a fresh frozen fingerprint and READY FOR TEST. Stop for another PM amendment before touching any other previously read-only path or contract.

No repository file was edited, staged, committed, merged, pushed, or deployed; no provider, production/private-data, or HUMAN action was performed in this PM decision.

[alexeygrigorev]

SWE FROZEN READY HANDOFF

Candidate is frozen, unstaged, and uncommitted at exact HEAD d334020ca5a582d31a81b371988169cab4e7f6b2 (accepted #218/#219/#220 baseline). No backend/API/provider/production/private-data/HUMAN action was performed.

Candidate inventory

Porcelain:

 D backend/e2e/bookkeeping-sponsors-design-production-portal.spec.js
 M backend/e2e/frontend-capabilities.json
 M backend/scripts/frontend-capabilities.test.mjs
 M frontend/src/styles.css
 M frontend/src/surfaces/finance/bookkeeping.js
 M frontend/src/surfaces/finance/sponsor-communications.js
 M frontend/src/surfaces/finance/sponsor-finance.js
 M frontend/src/surfaces/finance/sponsors.js
 M frontend/test/finance-surface.test.mjs
?? backend/e2e/issue-221-bookkeeping-sponsors.spec.js

Index is empty. git diff --check passes. Tracked diff stat: 9 files, 1,171 insertions, 509 deletions; the replacement E2E file is untracked and included in the changed-content fingerprint.

Fingerprints:

• tracked binary diff SHA-256: f6d04110d099500b59d143fc352ea168339116889c0948a54d1560e8126b84a9
• porcelain-v1-z SHA-256: 24935da871c60f9209c7894e8230fcdef9a7617b7db222929584161f323e67d6
• changed-content manifest SHA-256: 0387b9618eb8dc42612b307829c092928421472634e4fdcef0a52ae919191eda
• screenshot manifest SHA-256: 16e3eff84b9501200b3d5f0697bb3f365244e32b60d026927d2f28624f13a82d

Frozen verification evidence

• Focused Finance unit boundary: 13/13 pass.
• Full frontend unit: 305/305 pass.
• Frontend coverage: pass (all 305 tests; threshold met).
• Approved capability verifier: pass; canonical schema/catalog/public-safety/role/evidence checks pass.
• Typecheck: pass.
• Backend build/runtime boundary/frontend artifact: pass; 74 canonical frontend assets copied and identity-verified.
• SAM build: pass, frozen fingerprint d05f093fb9b0; SAM validation, frontend identity, runtime boundary, frontend isolation, workspace/concurrency isolation all pass; tracked inputs unchanged and no leaked SAM processes.
• Dedicated Converge Bookkeeping and Sponsors operator surfaces #221 source/SAM workflow, no retries: 2/2 pass in 50.6s; exact 14 screenshots generated by source only, no extras.
• Complete Playwright workflow, no retries: 97/97 pass in 9.7m; Converge Bookkeeping and Sponsors operator surfaces #221 source and packaged SAM both pass; global teardown verified stopped.
• Frontend parity: PASS, 40 evidence records and 40 screenshots.
• make ci: frontend coverage passes, then exits 2 at test-backend on the reproducible unrelated conversational baseline.
• Standalone backend aggregate: exit 1; 1,095 tests, 1,058 pass, 32 fail, 5 skip. Failures are confined to the pre-existing transactional conversational approval and durable execution, conversational state persistence, and private conversational Telegram adapter suites. Representative exact failures: canonicalizes every semantic proposal field and rejects nondeterministic rendering, normalizes private text once and rejects stale runtime output, revision-binds outbound persistence before a newer input races the send, maps core commands and blocks legacy mutation shortcuts, and persists bounded private events without usernames or raw media. Observed signatures remain conversation unavailable, HTTP 503 vs 200, absent outbound/message/voice-preview state, missing buttons, and no persisted Telegram event. No Converge Bookkeeping and Sponsors operator surfaces #221 capability or Finance test fails in this aggregate; no scope was broadened.

Screenshot evidence

Exactly 14 PNGs exist under .tmp/screenshots/issue-221, with dimensions encoded in and verified against each filename. All 14 were natively inspected at original resolution; selected states, recovery hierarchy, mobile 44px targets, no horizontal overflow, and public-safe synthetic content are acceptable.

Individual SHA-256 values:

d7b470642527cdb6a1bacd7de573c78a4c09c1ced0eee13d91dcdea661ac5f00  01-bookkeeping-ledger-ready-desktop-1440x900.png
fa6ebc64b92a9c7568d54510df069409c99ba8339606778189849379de710d8d  02-bookkeeping-ledger-ready-mobile-390x844.png
12180f0c7088c754e203eb887c6988e66cda00c44750acd393459d33aac3336e  03-bookkeeping-evidence-partial-desktop-1440x900.png
ecbc1a9ed6e043bc01f0735b1afef9b6c0fa5ebe7c0e6e723631edc037c3c321  04-bookkeeping-evidence-partial-mobile-390x844.png
fbd2b112da0907a777292e6978ae665697e34ccea224a8b5e18357cdcc035b8b  05-bookkeeping-monthly-complete-desktop-1440x900.png
8cfc290058ccd7849f6c87dca9831638cbf54cd130cf0b406a83679487787d77  06-bookkeeping-monthly-complete-mobile-390x844.png
193a012cd1d4744043ea050878ce8a558afa72933bf68497a0a8508dae44e92c  07-sponsors-overview-ready-desktop-1440x900.png
ffd78dce6aa20397ef128de91ca10e00845597f3203248a21515f28eb4d52ecd  08-sponsors-overview-ready-mobile-390x844.png
2b6ab205b511366508794c4bf7a155a69590fbf84cd15d8ac8fd14678776d4ee  09-sponsors-finance-recovery-desktop-1440x900.png
1bafffdb6402d6175450dbd08236acc931912c2874683d2521949b25058b5f1a  10-sponsors-finance-recovery-mobile-390x844.png
f01f88f5e2e4df5b2751707d0062ddc72ea1d9421e468c601c82ea54a90edfe1  11-sponsors-communications-disabled-desktop-1440x900.png
36c9919826f308855a2bcf4ca4c43118b5784e37969787ebdb349594ccb31ee9  12-sponsors-communications-disabled-mobile-390x844.png
8c2192117c64f3c16420b6ba37848efc855094884977d46c82b9fe19d5798341  13-sponsors-history-ready-desktop-1440x900.png
6fa436e91aefe74fb5557b353fc14f2efd924cb0986321c16b7ae254bfdb8ba7  14-sponsors-history-ready-mobile-390x844.png

Final cleanup: generated test-results removed, port 3001 has no listener, no process command line references this worktree, screenshot count remains exactly 14, and all fingerprints were rechecked after make ci.

READY FOR DESIGN / INDEPENDENT TEST / PM REVIEW

READY FOR TEST