Sales Proposal Workspaces — PRODUCT

Sales Proposal Workspaces — PRODUCT

Status: [CURRENT-CANONICAL] — NEW-S243 (Wave 0 of Phase 1 per docs/specs/id-31-canonical-pipeline-implementation-plan/PLAN.md §8 Wave 0 entry 2b). Phase 3 application-feature spec for the sales_proposal application_type. Substrate from docs/plans/phase-0-investigation/architecture/04-workspace-types.md §3.2 (Q-OQR1-03 application_types vocabulary — sales_proposal row) + §4.2 (S240 upfront-seats ratification) and docs/specs/reserved-workspace-seats/PRODUCT.md S-1..S-8 (seat-shape invariants this spec inherits at Phase 1).

Phase placement: Per-app columns are deferred to Phase 3 build time and land via ALTER TABLE per S-7 discipline — NOT in the Phase 1 Q-OQR1-16 combined-PR migration (T2). This spec ratifies the satellite seat NOW so Phase 3 has settled substrate when build kicks off; Phase 3 closure criteria revised per RATIFIED-S243 Item 13 (docs/reference/project-plan.md §7).

How to use this doc

This file holds user-perspective invariants for the sales-proposal application — what an admin / proposal author / curator can rely on about the existence and shape of a sales-proposal workspace’s satellite seat at Phase 1, plus an explicit deferral of all per-app behaviour to Phase 3. Companion TECH.md carries implementation references (Phase 1 reserved-seat DDL inheritance + Phase 3 ALTER pathway) and validation steps.

Invariants are numbered globally (S-1, S-2, …) so TECH.md references by ID. Each carries [RATIFIED-S2XX] with source citation, [INHERITS-RWS S-N] where the invariant is inherited verbatim from docs/specs/reserved-workspace-seats/PRODUCT.md, or [DEFERRED-PHASE-3] for items whose ratification is explicitly held over to the Phase 3 build cycle.

Source-of-truth pointers

• docs/plans/phase-0-investigation/architecture/04-workspace-types.md §3.2 (Q-OQR1-03 application_types vocabulary — sales_proposal row + sales_proposal_workspaces reserved seat name) + §4.2 (S240 upfront-seats ratification — satellite created at Phase 1 with PK + FK + RLS only) + §4.3 (extensibility procedure — feature spec adds per-app columns via ALTER).
• docs/specs/reserved-workspace-seats/PRODUCT.md S-1..S-8 (Phase 1 seat-shape invariants this spec inherits). sales_proposal_workspaces is one of the five non-procurement reserved seats covered by RWS.
• docs/specs/reserved-workspace-seats/TECH.md T-1 + T-5 (Phase 1 DDL pattern + per-tenant RLS policy pattern).
• docs/specs/id-38-rls-pattern/PRODUCT.md P-1 + P-2 (RLS auto-trigger + per-role grants helper this spec leverages at Phase 1 apply time).
• docs/specs/id-31-canonical-pipeline-implementation-plan/PLAN.md §4.2 T2 subtask 7 (5 reserved satellite seats land in the combined-PR migration) + §5 row “sales-proposal-workspaces” (this spec entry — Phase 3 substrate; per-app ALTER at Phase 3 build) + §8 Wave 0 entry 2b (drafting placement).
• docs/reference/project-plan.md §7 (Phase 3 Sales Proposals — closure criteria revised per RATIFIED-S243 Item 13: full application functionality, not Q&A pair reuse alone).
• docs/plans/phase-0-investigation/pre-s244-project-feedback.md Item 13 (revised Phase 3 closure criteria) + Item 15 (NEW Phase 1 specs ratified including this spec).

Audience

Phase 1 migration authors writing the reserved-seats combined-PR migration (T2 subtask 7); reviewers verifying seat-shape compliance against this spec + RWS; Phase 3 build kickoff authors who will draft the sibling per-app spec extension (or per-column ALTER spec) carrying the proposal-stage / client-metadata / win-loss / evidence-reference column lists; future agents needing to know which decisions are settled (the seat) versus deferred (everything else).

Summary

A sales-proposal workspace is the per-engagement work surface for the sales_proposal application_type — the second domain application of Knowledge Hub after procurement, planned for Phase 3. At Phase 1, the platform reserves the sales_proposal_workspaces satellite table in the public schema with the minimal reserved-seat shape (PK + FK to workspaces.id + RLS via auto-trigger + per-tenant policies + grants helper applied), inheriting RWS S-1..S-8 verbatim. No per-app columns are added at Phase 1; the build of sales-proposal-specific behaviour (proposal stage, client metadata, win/loss tracking, evidence references, composer surface, export pipeline) is deferred to Phase 3 and lands via ALTER TABLE ... ADD COLUMN against the existing seat per RWS S-7 discipline. Drafting the spec at Wave 0 of Phase 1 settles the satellite shape early so Phase 3 has a stable FK target and a known starting point, without committing column-level decisions before the Phase 3 research substrate is in hand.

Behavior

Section A — Phase 1 reserved-seat behaviour (inherited from RWS)

S-1 — sales_proposal_workspaces satellite exists at Phase 1 apply time

When the Phase 1 Q-OQR1-16 combined-PR migration applies (T2 subtask 7 per PLAN.md §4.2), a satellite table named sales_proposal_workspaces exists in the public schema alongside the four other reserved seats (intelligence_workspaces, product_guide_workspaces, competitor_research_workspaces, training_onboarding_workspaces) and the populated procurement satellite (procurement_workspaces). No partial seat-application is permitted — all five reserved seats land together or the migration fails per RWS S-1.

[INHERITS-RWS S-1] — docs/specs/reserved-workspace-seats/PRODUCT.md S-1 holds verbatim. [RATIFIED-S240] for the upfront-seats decision; [RATIFIED-S243] (Item 15) for the explicit inclusion of this spec at Wave 0.

Cross-refs: [RWS S-1], [arch 04-workspace-types §4.2], [PLAN.md §4.2 T2 subtask 7], [S243 Item 15].

S-2 — Seat shape is PK + FK + audit timestamps only at Phase 1

At Phase 1 apply time, sales_proposal_workspaces carries exactly these columns:

• id uuid PRIMARY KEY DEFAULT gen_random_uuid() per RWS S-2.
• workspace_id uuid NOT NULL UNIQUE REFERENCES workspaces(id) ON DELETE CASCADE per RWS S-3.
• created_at timestamptz NOT NULL DEFAULT now() and updated_at timestamptz NOT NULL DEFAULT now() per RWS T-1 migration body (platform-standard satellite timestamps).

No other columns ship at Phase 1 — no proposal stage, no client metadata, no win-loss columns, no evidence references, no composer state. Per-app columns are explicitly deferred per S-6.

[INHERITS-RWS S-2 + S-3]. [RATIFIED-S240] for the reserved-seat column set.

Cross-refs: [RWS S-2], [RWS S-3], [arch 04-workspace-types §4.2].

S-3 — 1:1 cardinality between workspace and satellite

A workspace bound to application_type='sales_proposal' has exactly one row in sales_proposal_workspaces, enforced via UNIQUE(workspace_id) on the satellite FK. Deleting a workspace cascades to delete the satellite row; the reverse cascade does NOT apply (deleting a satellite row leaves the workspace intact, but the application surface treats this as a tear in the data model and the UI does not expose a direct-delete affordance on the satellite — this matches the procurement pattern per docs/specs/procurement-workspaces/PRODUCT.md B-4).

[INHERITS-RWS S-3]. [RATIFIED-S240] via Q-OQR1-113-A satellite-per-application-type cardinality closure.

Cross-refs: [RWS S-3], [Q-OQR1-113-A].

S-4 — Row-level security enabled at Phase 1 apply time

sales_proposal_workspaces has row-level security enabled at Phase 1 apply time. The enabling mechanism is the rls_auto_enable() event trigger per docs/specs/rls-pattern/PRODUCT.md P-1 — no explicit ALTER TABLE ... ENABLE ROW LEVEL SECURITY is required by this spec (the Phase 1 reserved-seats migration includes the belt-and-braces explicit ALTER per RWS S-4 / T-4 to cover the migration-ordering corner case).

Per-tenant access is governed by inheritance through the workspace_id FK per RWS S-5 — the seat row is readable / writable to the same tenant role with access to the parent workspaces row, via a JOIN-or-EXISTS RLS policy delegating to the workspaces-level access predicate. No separate tenant_id column lives on the satellite.

[INHERITS-RWS S-4 + S-5]. [RATIFIED-S240] (combined with RLS-PATTERN P-1).

Cross-refs: [RWS S-4], [RWS S-5], [RLS-PATTERN P-1].

S-5 — Per-role grants applied via grants helper at Phase 1 apply time

At Phase 1 apply time, the migration calls grant_standard_public_table_access('public.sales_proposal_workspaces'::regclass) per RLS-PATTERN P-2 + RWS S-6 / T-6 — applying the 3-role grant set (anon SELECT, authenticated full CRUD, service_role full CRUD) for the Data API surface. Without this call, PostgREST returns 42501 permission denied per RLS-PATTERN P-3 (fail-loud) — the Phase 1 migration validation explicitly asserts both the RLS-enabled state and the grants-applied state per RWS T-1 validation steps.

[INHERITS-RWS S-6]. [RATIFIED-S240] (combined with RLS-PATTERN P-2).

Cross-refs: [RWS S-6], [RLS-PATTERN P-2], [RLS-PATTERN P-3].

Section B — Phase 3 build deferrals

S-6 — Per-app columns deferred to Phase 3 ALTER pathway

No application-specific columns are added to sales_proposal_workspaces at Phase 1 — no proposal stage, no client metadata (client_name, engagement type, etc.), no win-loss tracking columns, no evidence references, no proposal-template binding, no composer state. The seat is created as a stable FK target and a reserved name; the column list lands at Phase 3 build time via ALTER TABLE public.sales_proposal_workspaces ADD COLUMN ... migrations, per the feature-spec ALTER discipline established in RWS S-7.

[INHERITS-RWS S-7] for the deferral discipline. [DEFERRED-PHASE-3] for the column-set ratification itself.

The Phase 3 build cycle is responsible for:

• Identifying which sales-proposal-specific columns are required (the column set is not specified by this spec — see S-8 gap flag).
• Drafting the ALTER migration in a sibling docs/specs/sales-proposal-workspaces/PHASE-3-COLUMNS.md (or extending TECH.md Section B with a T-N entry per column) at Phase 3 kickoff.
• Maintaining 1:1 cardinality (S-3) — no per-column nullable defaults that would silently let a workspace get into a “satellite has gaps” state.
• Verifying RLS policies still hold after the ALTER (column-level grants inherit from the table-level grants helper call at Phase 1; no per-column grants needed).

Cross-refs: [RWS S-7], [arch 04-workspace-types §4.3 extensibility procedure], [S243 Item 13 — revised closure criteria].

S-7 — Composer / lifecycle / export surfaces deferred to Phase 3

All user-facing sales-proposal behaviour is deferred to Phase 3:

• The proposal composer surface — how a proposal author drafts a proposal inside a sales-proposal workspace, what fields/sections appear, how Q&A reuse from procurement evidence works (q_a_pairs.origin_kind='derived_from_bid_response' cross-domain reuse hook is established at Phase 1 in q_a_pairs per docs/plans/phase-0-investigation/architecture/05-qa-flow.md §1, but the per-app composer UI is Phase 3 scope).
• The proposal workflow state machine — whether sales-proposal mirrors the 10-state procurement workflow per Q-OQR1-05 or carries a distinct state set; the application key for state-machine code (lib/sales_proposal/ per the per-application-state-machine convention in 04-workspace-types.md §4.3 step 4) is reserved by naming alone, not by code at Phase 1.
• The proposal export pipeline — DOCX / PDF generation, template binding, branded styling.
• The proposal win-loss tracking — whether outcome columns mirror procurement (won / lost / withdrawn) or carry sales-proposal-specific outcomes (e.g. client_signed / client_declined / client_paused).
• The proposal success metrics — Phase 3 closure criteria per RATIFIED-S243 Item 13 (docs/reference/project-plan.md §7): sales-proposal application live in production + composer UI ships with UX-tested workflow + sales-proposal-specific extraction integrated (case-study reuse, win-story citation, client-metadata templating) + N successful proposals generated end-to-end on real client engagements + eval baseline established. Q&A pair reuse is one signal among several, not the sole criterion.

[DEFERRED-PHASE-3] across the board. [RATIFIED-S243] (Item 13) for the revised closure framing.

Cross-refs: [project-plan.md §7], [S243 Item 13], [arch 05-qa-flow §1], [arch 04-workspace-types §4.3].

Section C — Gap flags (construction-guide §5.3 format)

S-8 — Phase 3 research substrate NOTED, awaiting Liam ratification + canonical-pipeline reconciliation (gap flag)

Candidate substrate identified: Four files on disk are the substrate-of-record for Phase 3 Sales Proposals build kickoff:

Path	Date	Size	Role
docs/research/sales-proposals-reuse-audit-arm-a.md	28/04/2026	75 KB	Reuse-audit arm A — case-study + win-story reuse scoping.
docs/research/sales-proposals-reuse-audit-arm-b.md	28/04/2026	71 KB	Reuse-audit arm B — alternative reuse scoping (twin arm).
docs/plans/sales-proposals-workspace-plan-arm-a.md	12/05/2026	58 KB	Workspace-plan arm A — pre-canonical-pipeline workspace shape proposal.
docs/plans/sales-proposals-workspace-plan-arm-b.md	12/05/2026	59 KB	Workspace-plan arm B — alternative workspace shape proposal (twin arm).

Caveats (per Liam’s S244 Wave 0 note):

1. Liam has NOT yet reviewed these documents. They were created in the pre-canonical-pipeline era by autonomous research / planning passes and have not had a product-owner ratification pass. The reuse-audit pair (28/04) and workspace-plan pair (12/05) were both produced before Liam’s review queue cleared down to Phase 3 substrate.
2. All four files pre-date the canonical-pipeline pivot. The pivot was ratified in the S241 main-track architecture-family-close session (16-18/05/2026) and docs/specs/id-31-canonical-pipeline-implementation-plan/PLAN.md was authored 18/05/2026 (S241). The reuse-audit pair (28/04) pre-dates the pivot by ~3 weeks; the workspace-plan pair (12/05) by ~1 week. Any data-model assumptions in these files (workspace shape, application_type binding, satellite-vs-monolithic placement, q_a_pairs cross-domain reuse hook, RLS / grants patterns) must be reconciled against the post-pivot canonical-pipeline scope before adoption.
3. Twin-arm structure suggests the documents are exploratory, not ratified. The arm-a / arm-b paired files indicate the prior pass deliberately produced alternative options to choose between — Phase 3 build kickoff owns the arm-selection decision (or arm-merge synthesis), and that decision is NOT made by this spec.

Why this is still a gap flag (per construction-guide §5.3) rather than a closed reference:

• Specific gap: Phase 3 build cycle starts from these four documents (per RATIFIED-S243 Item 13 + Liam’s S244 Wave 0 note), but their ratification status is “candidate substrate, Liam-review-pending + canonical-pipeline-reconciliation-pending”. Adoption-as-written would propagate pre-canonical-pipeline assumptions into Phase 3 and risk re-litigating ratified canon (Q-OQR1-03 application_types vocabulary, S240 upfront-seats decision, Q-OQR1-113-A satellite cardinality, etc.).
• Category: Source Documentation (sub-category of Investigation needed per construction-guide §5.2) — the question is empirical-plus-product: “which arm (or merge) survives the post-canonical-pipeline review pass, and which provisions need replacement?”
• Prerequisite work: Liam-ratification pass on all four documents (arm selection or merge synthesis) + canonical-pipeline reconciliation pass (identify and replace any provisions superseded by Q-OQR1-* ratifications). Both gating Phase 3 build kickoff.

What this spec does in the meantime:

• Phase 1 lands the satellite seat with the inherited RWS shape (S-1 through S-5) — no dependency on the research substrate at Phase 1.
• Phase 3 build kickoff explicitly treats the four files as candidate substrate (not ratified canon). The Phase 3 kickoff continuation prompt should treat “Liam-review pass on sales-proposals-reuse-audit-arm-{a,b}.md + sales-proposals-workspace-plan-arm-{a,b}.md + canonical-pipeline reconciliation” as a Liam pre-decision item.
• The Phase 3 per-app spec extension (or PHASE-3-COLUMNS.md sibling per S-6) cites the surviving arm(s) post-Liam-review as substrate; provisions that conflict with canonical pipeline are reconciled at that point, not before.

Cross-refs: [S243 Item 13], [project-plan.md §7], [construction-guide §5.2 + §5.3], [S244 Wave 0 Liam note — substrate-noted-but-unratified caveat].

Out of scope (Phase 1)

• Per-app column lists — see S-6. Phase 3 owns these via the ALTER pathway; this spec ratifies the deferral.
• Composer / workflow / export behaviour — see S-7. Phase 3 owns the application surface in full.
• Proposal-specific extraction patterns (case-study reuse, win-story citation, client-metadata templating) — Phase 3 cocoindex integration; the canonical pipeline shipping at Phase 1 provides the substrate (q_a_pairs corpus-level cardinality + cocoindex source binding per 04-workspace-types.md §5 + 02-data-flow.md §3) but the sales-proposal-specific extractors are Phase 3 scope.
• Cross-application Q&A reuse from procurement evidence — the q_a_pairs.origin_kind='derived_from_bid_response' shape is established at Phase 1 in T6 (PLAN.md §4.6) so the data model can capture the cross-domain origin; the consumption of that data by the sales-proposal composer is Phase 3 scope (S-7).
• Application-type admin UI — workspace settings surfaces per application type are v1.1 admin-UI scope per Q-OQR1-13 (00-synthesis-v2.md §3.13); outside both this spec and Phase 3 build scope.
• State-machine code — per-application state machines live in lib/<application_key>/ per Q-OQR1-05. lib/sales_proposal/ is reserved by naming convention; code lands at Phase 3 build.

Phase 3 candidates (DEFERRED-PHASE-3 — not blocking Phase 1)

Items the Phase 3 build cycle will own — listed here as a forward-reference checklist, not as ratified scope:

• Sales-proposal workflow state set ratification (mirror procurement vs. distinct).
• Sales-proposal outcome enum ratification (terminal states; analogue to procurement’s won / lost / withdrawn).
• Client-metadata column set (client_name, engagement type, contract value, contract start date, etc. — exact set per Phase 3 research substrate per S-8).
• Proposal-template binding mechanism (whether form_templates is reused per the Phase 1 rename in PLAN.md §4.2 subtask 2, or a sibling proposal_templates lands at Phase 3).
• Composer UI surface (drafting affordances, evidence-insertion flow, draft-preview).
• Export pipeline (DOCX / PDF) and template-styling controls.
• Eval baseline on real client sales-proposal engagements per RATIFIED-S243 Item 13 closure criterion.
• Migration of any existing pre-canonical-pipeline sales-proposal substrate (audit at Phase 3 kickoff per S-8 prerequisite-work clause).

---

End of PRODUCT spec. Implementation references in ./TECH.md.