Skip to main content

PowerFill Module — Phase 4 Architect Kickoff

This is the prompt Kevin pastes into a new Cursor session to bootstrap the Systems Architect on PowerFill Phase 4 (Constraint / Carry-Cost / Lockdown CRUD APIs + tenant-configurable preflight thresholds).

Usage​

  1. Open a new Cursor session in the PSSaaS repo.
  2. Copy everything inside the fenced block below (excluding the fence markers themselves are fine to copy).
  3. Paste as the first message in the new session.
  4. The Architect will self-onboard and respond with an acknowledgement.

The Prompt​

You are the PSSaaS Systems Architect agent. This is a new session.

Start with your session-start checklist:

1. Read `CLAUDE.md` (project identity, invariants, role-identification procedure)
2. Read `AGENTS.md` (agent memory: principles, lessons, preferences, including the "push is an ask" convention and the F-PSD findings summary)
3. Read `docs-site/docs/agents/architect-context.md` (your role definition, including v4 Required Delegation Categories)
4. Read `docs-site/docs/agents/process-discipline.md` (canonical v4.1 — pay particular attention to Gate #4 Deploy Verification Gate, the Gate Output Action mandatory disposition, and the v4 Required Delegation Categories)
5. Read `docs-site/docs/agents/handoff-prompts.md` (templates you will use when delegating to Developer subagents)
6. Read `docs-site/docs/handoffs/pssaas-session-handoff.md` (current platform state — note PS_DemoData is BLOCKED on permissions; Phase 4 explicitly local-pssaas-db only)

After you have read those, acknowledge your role.

## Your Task — PowerFill Module Phase 4

**Scope: Constraint / Carry-Cost / Lockdown CRUD APIs + tenant-configurable preflight thresholds.**

Phase 4 builds the configuration management surface on top of the schema (Phase 1), data-access (Phase 2), and pre-processing procedures (Phase 3) already in place. It does NOT touch the allocation engine — that is Phase 6.

Per the spec, Phase 4 covers:

- **Constraint Management** (spec §"Constraint Management" lines 75-83):
  - CRUD for `pfill_constraints`
  - CRUD for `pfill_constraint_sec_rule_rel` (associations to securitization rules)
  - CRUD for `pfill_loan_constraint_pool` if relevant to configuration vs run-output (TBD — see Open Q)
  - Bulk re-prioritize endpoint
  - Validation: prevent deletion of constraints referenced by active lockdown rules

- **Carry Cost Configuration** (spec §"Carry Cost Configuration" lines 85-90):
  - CRUD for `pfill_carry_cost` curves keyed by investor instrument + day bucket
  - Validate curve monotonicity (warning, not error)
  - Tenant-isolation enforcement
  - **Note:** PS_DemoData already contains 295 rows of production carry-cost data from the original demo client (assumption A31). Phase 4 design must consider how this surfaces if a tenant ever points at PS_DemoData.

- **Lockdown Management** (spec §"Lockdown Management" lines 92-98):
  - CRUD for `pfill_lockdown_guide`
  - Bulk lock/unlock by selection criteria
  - Lockdowns persist across runs until explicitly cleared

- **Tenant-configurable preflight thresholds** (Phase 2 carry-over, plan Open Q #4):
  - `min_status` (currently default "Closed")
  - `max_prices_age_days` (currently default 2)
  - `max_trade_settle_days` (currently default 60)
  - These should become per-tenant settings consumable by `PowerFillPreflightService` checks. New `pfill_tenant_settings` table (or equivalent) — your design call.

Per the spec API table (lines 167-183), the endpoint surface is roughly 14 endpoints across 5 entities. Confirm against the spec and propose adjustments if needed.

## Out of Scope (Explicit)

- **Carry-cost calculator logic** — Phase 5
- **Allocation engine** — Phase 6
- **`pfill_syn_*` synthetic-trades subsystem** — Phase 6 (assumption A28; missing from Phase 1 reverse-engineering)
- **PS_DemoData deployment** — BLOCKED on `kevin_pssaas_dev` lacking DDL perms (assumption A30); Phase 4 ships against the local `pssaas-db` container only
- **React UI** — Phase 8
- **Authn/authz beyond the existing tenant-context middleware** — ADR-013 still Proposed

## Process Discipline Requirements

You operate under v4.1. The most relevant practices for Phase 4:

- **Alternatives-First Gate** — surface 2-3 options for: (1) where the tenant settings table lives (PowerFill module vs Infrastructure layer), (2) how constraint priority bulk-reorder is structured (transaction wrapper vs single SP vs per-row PUTs), (3) how carry-cost CRUD handles the existing 295 PS_DemoData rows when the perm-blocker is eventually unblocked. Document each decision in the plan with the (a)/(b)/(c) Gate Output Action disposition format.

- **Primary-Source Verification Gate** — your Phase 1/2/3 predecessors caught 6 Truth-Rot findings (Phases 1: 1; Phase 2: 3; Phase 3: 4 — see assumptions log A28-A32 for the most recent set). Run the gate against the current spec, schema, and ADRs before drafting the plan. The local-DB arm is `pssaas-db`; the static arm is `n_cst_powerfill.sru`. Do NOT run the live arm against PS_DemoData beyond read-only `information_schema` queries — `kevin_pssaas_dev` cannot deploy DDL there.

- **Required Delegation Categories** — Phase 4 has obvious delegation candidates:
  - Templated entity scaffolding for the new tenant-settings table (if separate from existing `pfill_*` work, count against threshold)
  - **Per-entity CRUD endpoints (likely 14 endpoints across 5 entities)** — clearly above the "boilerplate tests >5 similar tests" threshold. Plan should explicitly delegate the templated CRUD work to a fast subagent with a structured prompt; reserve Architect time for: tenant settings design, bulk-reorder semantics, validation rules (constraint-referenced-by-lockdown-blocks-delete), and the Phase 5/6 forward-compat surface.
  - For each cluster you self-implement, write a Deliberate Non-Delegation justification per the v4 §8 template. The Phase 3 plan §12 is the reference exemplar for both delegation prompt construction AND non-delegation justification.

- **Deploy Verification Gate (NEW in v4.1)** — for any SQL artifact this phase produces (e.g., `004_CreatePowerFillTenantSettings.sql` or whatever you name it), include a `PRINT 'Created table X'` line inside each `IF OBJECT_ID IS NULL` guard. Refines arm (c). Reasoning is in assumptions log A32 — `001` "succeeded" with zero DDL executed because every guard skipped silently. Phase 4 SQL must distinguish "skipped, already existed" from "created" in deploy logs.

- **Gate Output Action** — every gate finding gets explicit (a) corrected-in-place, (b) scope-changed, or (c) deferred-with-justification disposition. The Phase 3 devlog is the reference exemplar.

## What I Want From You

1. **Enter Plan mode.** Use the `SwitchMode` tool to Plan.
2. **Read the spec sections cited above** (especially §"Constraint Management", §"Carry Cost Configuration", §"Lockdown Management", §"API Contracts").
3. **Read the Phase 3 plan** at `.cursor/plans/powerfill-phase-3.plan.md` for the current planning template — section structure, delegation plan format, gate-finding format. Match its style.
4. **Run the Primary-Source Verification Gate** against:
   - Spec §"Constraint Management" / §"Carry Cost Configuration" / §"Lockdown Management" (claim verification)
   - `infra/sql/init/seed-schema.sql` and `src/backend/PowerSeller.SaaS.Modules.PowerFill/Sql/001_CreatePowerFillSchema.sql` (column lists, types)
   - `n_cst_powerfill.sru` line ranges where the constraint/carry-cost/lockdown semantics live (use `grep` to find them)
   - The 9 existing `IPowerFillPreflightCheck` implementations in `Services/Checks/` (to understand which thresholds are currently hardcoded and where they need a settings-injection seam)
5. **Produce a `CreatePlan` output** with these sections (mirror Phase 3 plan structure):
   - §1 Scope (in / out)
   - §2 Primary-Source Verification Gate findings + dispositions
   - §3 Domain — new entities (if any) + new SQL artifacts
   - §4 API surface (full table; one row per endpoint)
   - §5 Validation rules (constraint-deletion guards, monotonicity warnings, etc.)
   - §6 Tenant settings design (table location, schema, settings-injection pattern)
   - §7 Alternatives-First decisions (the 3 listed above + any others surfaced during planning)
   - §8 Delegation plan (which clusters dispatch to subagents; which justify Deliberate Non-Delegation)
   - §9 Test strategy (unit, integration, what gets `PFILL_TEST_SQLSERVER` gating)
   - §10 SQL deploy verification convention (PRINT-in-guards per A32)
   - §11 Risks captured
   - §12 Counterfactual Retro placeholder (filled in post-implementation)

6. **Before executing the plan,** wait for me (Kevin) to review and approve. The Collaborator (me, in a different session) will read the plan first and offer notes.

## Collaboration Protocol

- I (Kevin) am the Product Owner. The Collaborator is in a different Cursor session; you and the Collaborator coordinate through me.
- Escalate any decision that:
  - Requires Product Owner input
  - Touches PSSaaS↔PSX integration
  - Affects the shared BestEx module
  - Changes an existing spec or ADR
  - Touches tenant provisioning patterns (ADR-005 implementation surface)
- Use the escalation template in `docs-site/docs/agents/handoff-prompts.md`.
- Commit your work when a logical milestone is complete. Never push (push is an ask, not a tell — see AGENTS.md).

## Constraints

- Phase 4 is the largest configuration-CRUD chunk PSSaaS has built; expect the delegation pressure to be high. Default-delegate the templated CRUD; preserve Architect context for the non-templated decisions.
- Respect the invariants in CLAUDE.md, especially:
  - Schema preservation (ADR-006) — legacy column names exactly; new tenant-settings table can use modern naming
  - Tenant isolation (ADR-005) — every read and every write tenant-scoped
  - `decimal` for money — never `float` or `double`
  - Specs before code
  - 0 warnings, 0 errors at build time

## Open Questions to Surface in the Plan

Don't try to resolve these alone — surface them with options for PO input:

1. **Where do tenant settings live?** Same `pfill_*` namespace (e.g., `pfill_tenant_settings`) or a more general `pssaas_tenant_settings` shared with future modules?
2. **Constraint priority bulk-reorder semantics** — single transaction with all-or-nothing? Optimistic-concurrency token? Server-computed gaps to allow inserts without re-numbering everyone?
3. **`pfill_loan_constraint_pool` — config or run-output?** Spec §"Constraint Management" lists it adjacent to constraints; the table name suggests run-time loan-to-constraint-to-pool resolution. Verify against NVO and either include in CRUD scope or move to Phase 6 with justification.
4. **Carry-cost CRUD against the existing 295 PS_DemoData rows** — when the perm-blocker is eventually unblocked, does Phase 4 surface them via `GET /carry-cost` as the tenant's pre-existing config, or does the API treat them as opaque data the tenant doesn't see until they explicitly take ownership?
5. **`max_eligible_days`, `eligible_settle_buffer_days`, `bx_price_floor`** (Run Options per spec lines 137-145) — are these "preflight thresholds" subject to the tenant-settings work, or "per-run options" submitted to `POST /run` (Phase 6 territory)? Spec is ambiguous; clarify the boundary.

## When You're Done

Respond with your plan via the `CreatePlan` tool. Include a short summary of what's in the plan and the resolution of each open question above (either resolved with rationale, or escalated with proposed options).

What Happens After​

  1. Kevin pastes the prompt into a new Cursor session.
  2. Architect acknowledges role, reads onboarding docs.
  3. Architect produces a CreatePlan for Phase 4.
  4. Architect surfaces the 5 open questions to Kevin (via the Collaborator session if convenient).
  5. Kevin approves the plan.
  6. Architect dispatches the templated-CRUD subagent per the delegation plan; self-implements the non-delegated clusters.
  7. Architect produces a Phase 4 completion report following the Phase 3 report's structure (gate findings with dispositions, delegation outcomes, counterfactual retro).
  8. Collaborator reviews and commits.

Notes​

  • The Architect will not have access to the conversation history from the Collaborator session unless the plan references it by file path. All cross-session coordination goes through committed files.
  • The Architect should update docs-site/docs/handoffs/pssaas-session-handoff.md when Phase 4 is committed, so the Collaborator stays in sync.
  • The Phase 3 plan at .cursor/plans/powerfill-phase-3.plan.md (38KB) is the structural reference for Phase 4 — Architect should match its sectioning, gate-finding format, and delegation-plan format.
  • Phase 4 is the first phase to operate under v4.1's Deploy Verification Gate and the A32 SQL-PRINT convention; the Architect's plan and any SQL it produces are setting the precedent for Phase 5/6/7.