feat: add architecture workspace prototype

[simple-agent-manager]

Summary

• Add packages/architecture, an extractable TypeScript package for compiling, validating, querying, and serving a repository-native architecture workspace.
• Add the checked-in architecture/ model for SAM with 19 elements, 21 relationships, three views, CLI login and session-startup flows, and the TaskRunner lifecycle state machine.
• Add bounded JSON CLI queries, source/path confinement, file-backed threads and replies, a loopback-only HTTP/SSE server, and a responsive Structure/Topology/Flow/State viewer with source previews and collaboration controls.
• Document the file/API/CLI contracts, generated-evidence boundary, maintenance workflow, and intended extraction path. This PR is intentionally a draft and must not be merged without Raphaël's authorization.

Validation

• pnpm lint
• pnpm typecheck
• pnpm test
• Additional validation run (if applicable)
• If this PR changes candidate selection for a sweep/cron/alarm loop (WHERE clause, status set, join, or equivalent), expected candidate volume and worst-case per-candidate cost are stated in the summary or validation notes (see .claude/rules/47-control-loop-io-budget.md)

Additional validation:

• pnpm build, pnpm format:check, git diff --check, and pnpm quality:file-sizes passed.
• The full test run completed all 23 Turborepo tasks, including 7,193 API tests and 3,077 web tests.
• packages/architecture passed 66 unit/integration tests with 89.8% line and 71.57% branch coverage.
• Six real-server Playwright scenarios passed at 375x667 and 1280x800; explicit 320px overflow audits passed, with Topology coverage for normal, selected-connection, long-content, dense, and special-character states.
• Five persistent local UI, frontend, and backend review passes completed with no blockers. The post-review drafting/topology audit scored visual hierarchy 5/5, interaction clarity 5/5, mobile usability 4/5, accessibility 5/5, and system consistency 5/5.
• A real browser-created question was discovered by a local reviewer through architecture:inbox, answered through architecture:reply, and appeared in the still-open desktop/mobile browser through watcher/SSE with zero browser errors.
• pnpm architecture:validate, summary, show, inbox, and impact commands passed. Summary compiled 19 elements, 21 relationships, three flows, one state machine, and three views.
• Current head 76cac95aef9edcf3d8c12966d940cc461f0b9011 passed the full local repository gate, pnpm check:fast, pnpm quality:file-sizes, and pnpm architecture:validate. Fresh CI run 31777620116 passed, including the 8m29s coverage Test job and 8m45s Durable Object Workers job.
• N/A candidate-volume gate: this PR does not change a sweep, cron, alarm, database candidate query, or per-candidate loop.

Staging Verification (REQUIRED for all code changes — merge-blocking)

• Staging deployment green — Deploy Staging workflow triggered manually and passed for this branch
• Live app verified via Playwright — logged into app.sammy.party (staging) using test credentials and actively tested the application
• Existing workflows confirmed working — navigated dashboard, projects, and settings; confirmed no regressions in core flows (pages load, data displays, navigation works, no new console errors)
• New feature/fix verified on staging — the specific changes in this PR work correctly on the live staging environment (describe what was tested below)
• Infrastructure verification completed — N/A: no infra changes
• Mobile and desktop verification notes added for UI changes

Staging Verification Evidence

• Deploy Staging run 31722867891 passed for the reviewed deployed-runtime commit d44c8ebc6b0fd1dd39a1e1191ff6c007127c0c06. Validate Configuration, Cloudflare deployment, workflow health check, and all 12 smoke tests passed. Newer commits contain task/supply-chain evidence, a CI test timeout adjustment, and package-only Sonar/deterministic-ordering fixes; no deployed API, web, or infrastructure path changed.
• A separate authenticated desktop Playwright pass verified https://api.sammy.party/health, the loaded dashboard and project cards, click-through to a real project chat, loaded cloud-provider settings, and zero console or uncaught page errors. Screenshots: .codex/tmp/playwright-screenshots/architecture-regression-{dashboard,project,settings}.png.
• pnpm quality:observability-noise exited successfully. OBSERVABILITY_DB_ID was absent and the Workers telemetry endpoint returned 403, so those optional probes were explicitly skipped.
• The new viewer is deliberately a loopback-only developer tool and is not mounted in the deployed SAM app. Its feature-specific behavior was therefore verified against its real local HTTP/SSE server: six mobile/desktop Playwright scenarios plus the 320px audit exercise all four lenses, drill-down, source preview, thread creation/replies, live updates, empty/many/invalid/error states, focus management, and overflow.
• Mobile (375x667) and desktop (1280x800) package layouts passed; the 320px audit found no horizontal overflow. Opening the mobile inspector, focus trapping/return, and resizing an open sheet to desktop were verified.

UI Compliance Checklist (Required for UI changes)

• Mobile-first layout verified
• Accessibility checks completed
• Shared UI components used or exception documented
• Playwright visual audit run locally — mock data scenarios (normal, long text, empty, many items, error, special chars) tested at mobile (375x667) and desktop (1280x800); no horizontal overflow; screenshots in .codex/tmp/playwright-screenshots/ (see .claude/rules/17-ui-visual-testing.md)

The package viewer is extraction-oriented and owns its intentionally self-contained CSS/component surface; it does not import SAM app UI packages. Keyboard-accessible relationship lists complement canvas edges, and the mobile inspector implements initial focus, Tab/Shift+Tab wrapping, outside-focus containment, Escape/close behavior, and focus return.

End-to-End Verification (Required for multi-component changes)

• Data flow traced from user input to final outcome with code path citations (see .claude/rules/10-e2e-verification.md)
• Capability test exercises the complete happy path across system boundaries
• All spec/doc assumptions about existing behavior verified against code (not just "read the code")
• If any gap exists between automated test coverage and full E2E, manual verification steps documented below

Data Flow Trace

1. packages/architecture/src/client/Inspector.tsx:useQuestionCreator sends a selected target and question through packages/architecture/src/client/api.ts:createApiClient to POST /api/threads.
2. packages/architecture/src/server.ts:handleCreateThread validates the strict bounded payload and calls packages/architecture/src/threads.ts:createThread.
3. createThread validates the target/content, rejects reserved message delimiters, confines the thread path, and writes atomically through atomicWriteNewFile.
4. packages/architecture/src/server/workspace-state.ts observes workspace/thread changes; packages/architecture/src/server/events.ts publishes the SSE update; packages/architecture/src/client/useArchitectureViewer.ts:reloadAfterSse reloads while retaining the last valid view state.
5. Replies follow Inspector.tsx:useThreadReply → api.ts → server.ts:handleReply → threads.ts:appendThreadReply, with library and real HTTP tests proving the resulting file mutation and recompiled model.
6. Source preview follows Inspector.tsx:useSourceLoader → POST /api/source-preview → server.ts:handleSource → source.ts:readSourceReference, which enforces repository confinement, symlink safety, byte/line limits, and validated source ranges.
7. Agent context follows cli.ts:runCli → loader.ts:loadArchitectureWorkspace → compiler.ts:compileWorkspace → bounded functions in queries.ts; distribution tests exercise the built ESM/CLI output rather than source-only imports.

Untested Gaps

• Remote multi-user hosting, authentication, live telemetry overlays, environment comparison, and automatic AST/LSP extraction are explicit future phases, not gaps in this local prototype.
• The viewer is not mounted in the deployed SAM application. Its complete local collaboration vertical slice is automated against the real loopback server; staging verification therefore covers monorepo build/deploy compatibility and regression health rather than a nonexistent staging route.

Post-Mortem (Required for bug fix PRs)

N/A: not a bug fix. This PR adds a new package, checked-in workspace, local viewer, and maintenance workflow.

Specialist Review Evidence (Required for agent-authored PRs)

• All local reviewers completed and findings addressed before merge
• If any reviewer did NOT complete: needs-human-review label added and merge deferred to human — N/A: every reviewer completed.

Reviewer	Status	Outcome
task-completion-validator	PASS	Research, checklist, all eight acceptance criteria, diff, 66 tests, architecture commands, exact-SHA staging, and draft-delivery constraint reconciled; task remains active pending human confirmation.
test-engineer	PASS	Unit/integration coverage thresholds passed; all six real-server browser scenarios passed with no skipped/flaky/unexpected results.
doc-sync-validator	PASS	Public exports/signatures/examples, HTTP payload/errors, defaults, thread format, maintenance contract, and dogfood model are synchronized.
constitution-validator	PASS	Package boundaries, file-size/function-size policy, configurability, and no-hardcoded-values review passed after refactoring and documentation fixes.
ui-ux-specialist	PASS	Mobile/desktop hierarchy, responsive inspector, focus trap/return, resize behavior, long/empty/many/error states, and 320px overflow audit passed.
security-auditor	PASS	Loopback authority/origin, traversal/symlink confinement, request limits, atomic writes, strict schemas, and reserved delimiter rejection passed at library and HTTP boundaries.

Exceptions (If any)

• Scope: The architecture viewer is not mounted in the deployed SAM web application.
• Rationale: This first phase intentionally proves an extractable, loopback-only developer package and file contract before adding a hosted product surface.
• Expiration: Revisit when remote hosting/authentication or live telemetry overlays are scoped.

Agent Preflight (Required)

• Preflight completed before code changes

Classification

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

Official/project documentation and prior-art behavior were researched before implementation: C4's semantic abstraction approach; LikeC4's multi-file model, views, source links, and queries; Rivière/Éclair's source-backed operational flows; Oh My Mermaid's filesystem watcher/SSE loop; Ilograph's hierarchy/sequence perspectives; and ArchUnit's validation/ratcheting model. No external API integration was added, so this is not classified as external-api-change.

Codebase Impact Analysis

Primary paths are packages/architecture/ for the extractable model/compiler/query/server/viewer package, architecture/ for SAM-owned curated data, root package.json/pnpm-workspace.yaml/pnpm-lock.yaml for workspace commands and dependencies, .claude/rules/57-architecture-workspace.md plus CLAUDE.md/AGENTS.md for agent maintenance policy, and apps/www/src/content/docs/docs/ for architecture/local-development guidance. Existing apps/api, apps/web, and infrastructure runtime code are not modified.

Documentation & Specs

Updated packages/architecture/README.md, architecture/README.md, apps/www/src/content/docs/docs/architecture/overview.md, apps/www/src/content/docs/docs/guides/local-development.md, .claude/rules/57-architecture-workspace.md, CLAUDE.md, AGENTS.md, and tasks/active/2026-08-13-architecture-workspace-prototype.md.

Constitution & Risk Check

Checked Principles III, VIII, IX, X, XI, and XIII. The package documents its public contract, keeps compact bounded agent queries, avoids SAM app imports, favors a small neutral model, makes server/query/UI limits configurable, and validates file, HTTP, source-preview, and mutation boundaries. Key risks addressed are path/symlink escape, unsafe local writes, oversized/unbounded payloads, marker/terminator injection, schema drift, visually attractive but semantically weak diagrams, and duplicated documentation. Curated intent remains authoritative; generated evidence cannot silently redefine the model.

[codspeed-hq]

Merging this PR will not alter performance

✅ 6 untouched benchmarks

---

_{Comparing sam/architecture-workspace-prototype (d0f2f7d) with main (68701ee)}

[sonarqubecloud]

Quality Gate passed

Issues
62 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.3% Duplication on New Code

See analysis details on SonarQube Cloud