Client Critique Lifecycle & Universal Platform Architecture

Document Status: Approved / Living True Specification
Target Audience: Core Platform Architects, Daytime Engineers, and Autonomous AI Agent Contributors
Companion Specifications: docs/PRD.md, docs/specs/CLIENT_REVIEW_RUBRIC.md, docs/specs/EDITORIAL_ANTI_PATTERNS_AND_NEGATIVE_CONSTRAINTS.md, docs/INGRESS_AND_PREVIEW_ROUTING.md

1. Executive Summary & Strategic Philosophy

In SiteSwarm, client application delivery relies on rapid, high-polish iteration between business owners, daytime engineers, and autonomous AI coding agents. During battle-testing on smartphones and staging previews, reviewers submit granular visual and editorial feedback directly on the interface.

Historically, feedback tooling in web development suffers from two critical architectural defects:

The Ephemeral Environment Trap: Feedback recorded on a preview URL or staging slot is partitioned into an ephemeral database or local storage. When the preview branch is torn down, the feedback vanishes. Local development environments never see what was pinned on staging, and developers must manually juggle screenshots and Slack messages.
The Binary Status Fallacy: Systems that treat feedback as simply open or closed fail during verification. When an engineer pushes a fix, the reviewer has no way to distinguish between items that are still pending and items that are ready for visual re-testing.

1.1 The Core Operating Theses

Critiques Are Platform-Level Editorial Artifacts, Not Ephemeral Test Data: Critiques transcend individual hosting environments. There is only one authoritative critique platform service for all of SiteSwarm. Every environment (local dev, ephemeral PR preview, staging, and production) communicates with this unified platform store.
Cross-Version DOM Persistence: A critique is anchored to a specific build version (commitSha) where it was first observed, but it persists across subsequent software releases until it is explicitly resolved.
The 3-State Lifecycle: Workflows require an intermediate verification state: open $\to$ addressed $\to$ resolved, with instant bidirectional reopen capabilities.
Automated Staging Promotion Gate: Merging verified code into the staging branch represents the canonical acceptance milestone, automatically resolving all addressed feedback items across the fleet.

2. The 3-State Critique Lifecycle Machine

Critiques progress through three clearly defined operational states:

stateDiagram-v2
    [*] --> open: Reviewer Pins Element on Page (Tagged with Version & Selector)
    open --> addressed: Developer / Agent Implements Fix (Tagged with Fix Commit)
    addressed --> open: Reopened (Reviewer rejects fix on Preview URL)
    addressed --> resolved: Auto-Resolved on Merge to Staging (or Manual Verification)
    resolved --> open: Reopened (Visual regression detected)
    resolved --> [*]

2.1 State Definitions & In-Situ Visual Indicators

State	Badge Color	Pin Border Style	Operational Meaning
`open`	Amber (`#B45309`)	Dashed Amber Border (`2px`)	Unresolved feedback. The critique was filed and remains pending developer action. Persists across all future commits.
`addressed`	Teal (`#0F766E`)	Dashed Teal Border (`2px`, labeled `#N ✓`)	Fix committed & deployed. The defect was addressed in a branch or PR. Displayed prominently on preview URLs so reviewers can verify the fix in-situ.
`resolved`	Green (`#15803D`)	Translucent Green Border (`1px`, optional)	Verified & closed. The fix has been verified and integrated into `staging`. Hidden from default active views to preserve clean visual inspection.

2.2 In-Situ Review Ergonomics & State Controls

Inside the floating critique dock drawer (@siteswarm/critique), every item card exposes context-aware state controls:

┌────────────────────────────────────────────────────────┐
│ #1  <header.masthead>                     [ADDRESSED]  │
│ v: 34726d3                                             │
│ [Needs Restraint] [Remove Badge]                       │
│ "Remove aggressive FLAGSHIP ARCHITECTURE badge."       │
│                                                        │
│ ────────────────────────────────────────────────────── │
│ [ Verify & Resolve ]                  [ Reopen ]       │
└────────────────────────────────────────────────────────┘

When status: "open":
- [Mark Addressed]: Transitions to addressed (used by engineers during local testing or PR verification).
- [Resolve]: Immediately closes the item if already satisfied.
When status: "addressed":
- [Verify & Resolve]: Confirms that the fix looks correct on the smartphone or browser, transitioning status to resolved.
- [Reopen]: Flags that the fix was incomplete or introduced a visual regression, transitioning status back to open with updated timestamp.
When status: "resolved":
- [Reopen]: Restores the critique to open if an old defect resurfaces.

3. Software Version Tagging & Cross-Version Persistence

When a critique is created, it captures the immutable build telemetry of the running software isolate:

export interface VersionMetadata {
  commitSha?: string;           // e.g. "34726d3"
  buildTime?: string;           // ISO 8601 build timestamp
  environmentObserved?: string; // e.g. "preview-pr-155"
}

export interface Critique {
  id: string;
  tenantId: string;              // e.g. "me-portfolio", "bakery"
  environment: string;           // Environment where created (informational)
  url: string;                   // Full page URL
  componentName?: string;        // Inferred Astro/HTML component name
  selector: string;              // Deterministic CSS selector path
  textSnippet?: string;          // Element text content at capture time
  tags: string[];                // Standardized critique tags
  comment?: string;              // Human critique notes
  authorName?: string;           // Reviewer identity
  status: "open" | "addressed" | "resolved";

  // Build & Lifecycle Versioning
  detectedAtVersion?: VersionMetadata;
  addressedAtVersion?: {
    commitSha?: string;          // SHA that implemented the fix
    prNumber?: number;           // Pull Request number
    addressedAt: string;         // ISO timestamp
  };
  resolvedAtVersion?: {
    commitSha?: string;          // Staging integration commit SHA
    resolvedAt: string;          // ISO timestamp
  };

  createdAt: string;
  updatedAt: string;
}

3.1 The Cross-Version Persistence Invariant

A fundamental requirement of the critique engine is that critiques must never be lost across software builds:

When a reviewer opens an app running commit 4a8f9c, the client overlay requests: GET /api/critique?tenantId=me-portfolio&status=open,addressed
Even if the critique was recorded 10 commits earlier at 1e2d3c, the item persists on the canvas and in the dock drawer.
DOM Selector Resilience: The client overlay attempts to resolve the DOM node using selector. If a code refactor modified the class hierarchy or element structure, the overlay falls back to matching textSnippet or component boundaries, ensuring that critiques remain accessible in the dock feed even if the DOM node migrated.

4. Environment Transcendence: Single Platform Production Store

Critiques represent durable design and content feedback, not throwaway environment state.

flowchart TD
    subgraph Client Workspaces & Runtimes
        DEV["Local Development\nlocalhost:4324"]
        PR["Ephemeral PR Preview\nme-portfolio-preview-pr-155.jacobmiller22.com"]
        STG["Staging Sandbox\nme-portfolio-staging.jacobmiller22.com"]
        PROD["Production Edge\njacobmiller22.com"]
    end

    subgraph Single Platform Critique Service
        GW["Universal Critique Gateway\n/api/critique (Cloudflare Workers)"]
        STORE[("Production Platform Storage\nKV: critiques:tenantId")]
    end

    DEV -->|Read / Write| GW
    PR -->|Read / Write| GW
    STG -->|Read / Write| GW
    PROD -->|Read / Write| GW
    GW --> STORE

4.1 Zero Environment Silos

Global Tenant Keying: Critiques are stored under critiques:${tenantId} (e.g. critiques:me-portfolio). They are never partitioned into isolated sub-keys like critiques:me-portfolio:preview or critiques:me-portfolio:staging.
Environment as Informational Metadata: The environment field on a critique records where the reviewer was standing when the issue was discovered (e.g. preview-pr-155), but does not restrict visibility.
Cross-Environment Sync: When CritiqueOverlay.syncWithServer() executes on any device, it queries /api/critique without environment filters, providing complete global feedback parity across devices and stages.

5. End-to-End Operational Lifecycle Walkthrough

sequenceDiagram
    autonumber
    actor Jacob as Reviewer (Smartphone)
    participant Preview as Ephemeral Preview (PR #155)
    participant Platform as Platform Critique Store
    actor Agent as Autonomous Agent (pm ship)
    participant Staging as Staging Pipeline (GitHub Actions)

    Jacob->>Preview: Inspects page on phone & taps "+ Click to Comment"
    Preview->>Platform: POST /api/critique (status: "open", commit: "34726d3")
    Platform-->>Preview: 201 Created (Pin turns Amber #1)

    Agent->>Platform: GET /api/critique?tenantId=me-portfolio&status=open
    Platform-->>Agent: Returns active open feedback items
    Agent->>Agent: Modifies Masthead.astro & runs Playwright e2e verification
    Agent->>Platform: PATCH /api/critique/:id (status: "addressed", commit: "8f9b12")

    Jacob->>Preview: Refreshes preview on smartphone
    Preview->>Platform: GET /api/critique?tenantId=me-portfolio
    Preview-->>Jacob: Pin renders Teal [#1 ✓ ADDRESSED]
    Note over Jacob,Preview: Jacob verifies fix. If dissatisfied, taps [Reopen]

    Jacob->>Staging: Merges PR #155 into main
    Staging->>Platform: POST /api/critique?action=resolve-addressed&tenantId=me-portfolio
    Platform->>Platform: Transitions all 'addressed' critiques to 'resolved'
    Platform-->>Staging: 200 OK (resolvedCount: 1)

6. Automated Staging Resolution Protocol

When a feature branch or bugfix PR is merged into main, SiteSwarm’s trunk-based staging deployment pipeline executes in .github/workflows/staging-deploy.yml.

6.1 The Staging Resolution Hook

To eliminate manual ticket closing and prevent feedback backlog stagnation, the staging workflow dispatches a batch resolution call to the platform critique engine:

# Executed in GitHub Actions after successful staging edge deployment:
curl -s -X POST "https://${APP_DOMAIN}/api/critique?action=resolve-addressed" \
  -H "Content-Type: application/json" \
  -H "X-SiteSwarm-Commit-Sha: ${GITHUB_SHA}" \
  -d "{\"tenantId\": \"${APP_ID}\", \"commitSha\": \"${GITHUB_SHA}\"}"

6.2 Behavior Rules

Targeting: Only critiques in status: "addressed" are promoted to status: "resolved".
Safety Invariant: Critiques in status: "open" remain untouched and active. If a PR only addressed 2 of 5 open critiques, the remaining 3 stay open and visible on the staging site.
Audit Imprint: Every resolved critique receives resolvedAtVersion: { commitSha, resolvedAt } documenting the exact staging commit that closed the loop.

7. Swarm CLI & Agent Tooling Reference

Autonomous agents and human operators can inspect and manipulate critiques via @siteswarm/governance:

# List all active (open & addressed) critiques for an application
pnpm swarm critique:list --tenant me-portfolio

# Mark specific critiques as addressed by an in-flight branch
pnpm swarm critique:address --tenant me-portfolio --ids <id1>,<id2> --commit <sha>

# Batch resolve addressed critiques during staging deployment
pnpm swarm critique:resolve-addressed --tenant me-portfolio --commit <sha>

# Deduplicate redundant client critiques
pnpm swarm critique:dedup --tenant me-portfolio

8. Summary of Architectural Guarantees

Requirement	Implementation Guarantee
No Lost Feedback	Universal KV/D1 production store (`critiques:${tenantId}`) shared across all runtimes.
Version Continuity	Critiques persist across newer software versions until explicitly marked `resolved`.
Clear Verification State	3-state lifecycle (`open` $\to$ `addressed` $\to$ `resolved`) with instant in-situ `[Reopen]` and `[Resolve]` dock controls.
Automated Closure	Staging deployment pipeline batch-resolves all verified `addressed` feedback on merge.
Ergonomic Mobility	Full point-and-click overlay operable from smartphones, tablets, and desktop viewports.