​

The Factory — Architecture & Playbook, v1

This document is the single source of truth for what The Factory is, how it works, and how to operate it. If a statement here conflicts with an older doc, this document wins. If a statement here conflicts with docs/supervisor/FRIDGE.md, FRIDGE wins.

​

Table of contents

1. Mission, principles, and scope
2. Portfolio of apps
3. Platform layers
4. Cross-cutting concerns
5. Delivery lifecycle
6. Governance

7. Add a new app to the portfolio
8. Ship a new version of a shared package
9. Rotate a secret
10. Respond to a Sentry spike
11. Debug a migration drift
12. Author a supervisor template
13. Resolve an open decision
14. Onboard a new agent

15. Gap register
16. Roadmap: current → steady state
17. Appendices

​

Part I — Architecture

​

1. Mission, principles, and scope

​

1.1 Mission

​

1.2 Design principles

• Factory Core owns the plumbing; apps own the product. No business logic in @latimer-woods-tech/* packages. No platform responsibilities in app repos.
• Distributed packages, not a monorepo. Each app is its own repo with pinned dependencies. Selling, transferring, or open-sourcing any single app is a clean handoff.
• Pinned exact versions + Renovate automation. No ^ / ~ ranges on platform packages. Upgrades are deliberate, tested, and auditable.
• Cloudflare Workers is the only runtime. No per-app AWS, no Node servers, no Next.js. Hono as the router, Drizzle as the ORM, JWT self-managed via Web Crypto. Stable stack.
• Sentry is the only error/observability platform. One org, one project per app.
• PostHog + first-party factory_events for analytics. Behavioral data in PostHog, business events in Neon.
• Resend for email, Stripe for billing, Telnyx/Deepgram/ElevenLabs for voice. One vendor per capability unless there’s a concrete forcing reason to fan out.

• Template-grounded supervisor, not generative. See docs/supervisor/ARCHITECTURE.md §5.5.
• Every LLM call is metered and routed through AI Gateway. Single ledger, per-project budgets, per-run hard cap.
• Security is confused-deputy-aware. Issue bodies are untrusted data; tool calls are schema-bounded; JWTs are short-lived and scoped per tool class.
• Put the rules on the fridge. docs/supervisor/FRIDGE.md is readable by any agent or human landing in the repo; it takes 2 minutes to read.

​

1.3 Scope

• The supervisor-eligible apps declared by the live service and capability registries
• Every shared package discovered from packages/*/package.json; generated docs carry the current count and dependency order
• The supervisor control plane (scheduled Sauna Phase-1; apps/supervisor Worker Phase-2)
• The Dreamstate spec plane
• All CI/CD, observability, cost, and secrets infrastructure

• wordis-bond (compliance pending; hard-locked from automation)
• focusbro (AdWords acceptance pending; not migrated to Latimer-Woods-Tech org yet)
• ijustus, cypher-healing, the-calling, neighbor-aid (design-stage; no active product surface)
• xpelevator (utility; not a product)
• AI tokens as a monetized SKU (revisit after 6 months of clean supervisor operation)
• Machine Payments Protocol (supervisor autonomously provisioning its own infra via Stripe identity — not in 2026)

​

1.4 Audiences

• Adrian and future CODEOWNERS — the humans who set strategy, review Red-tier PRs, and resolve decisions.
• Sauna (this instance) — the primary autonomous planner/drafter.
• Scheduled supervisor — the future daily-fired Sauna session (Phase-1) or Worker (Phase-2).
• Copilot / other autonomous agents — parallel workers on green-list issues.

​

2. Portfolio of apps

​

2.1 Active portfolio

​

2.2 On hold

​

2.3 Design-stage

​

2.4 Per-app canonical facts

​

3. Platform layers

┌─────────────────────────────────────────────────────────────────┐
│  L5: Spec plane — Dreamstate (specs → kanban issues)            │
├─────────────────────────────────────────────────────────────────┤
│  L4: Control plane — Supervisor (planner, executor, verifier)   │
├─────────────────────────────────────────────────────────────────┤
│  L3: Reusable workflows (_app-ci, _app-deploy, _prod-canary…)   │
├─────────────────────────────────────────────────────────────────┤
│  L2: Shared packages (@latimer-woods-tech/*)                     │
├─────────────────────────────────────────────────────────────────┤
│  L1: Runtime (Cloudflare + GCP + Neon + Sentry + Stripe + …)    │
└─────────────────────────────────────────────────────────────────┘

​

3.1 L1 — Runtime

• factory-495015 / Cloud Run processor (xico-city media transcoding; ffmpeg on real Chromium)
• Vertex AI (Gemini 2.5 Pro long-context fallback for the supervisor planner)
• Service accounts: factory-sa (owner, legacy; rotated at SUP-3 exit), supervisor-sa (Vertex-only least-privilege, minted at SUP-1.2)

• Anthropic (primary for synthesis + planner + verifier)
• Gemini via Vertex (long-context planner fallback only, via AI Gateway routing)
• Groq (Haiku-equivalent verifier fallback, small-call fallback)
• OpenAI, xAI: credentials exist but no workload currently routed to them. Kept for experimentation.

​

3.2 L2 — Shared packages

​

3.3 L3 — Reusable workflows

jobs:
  ci:
    uses: Latimer-Woods-Tech/factory/.github/workflows/_app-ci.yml@main
    secrets: inherit

​

3.4 L4 — Supervisor control plane

​

3.5 L5 — Dreamstate spec plane

• Human-authored issues on the LatWood Operations board (default, forever).
• documents/factory/dreamstate/<app>/<feature>/spec.yml files processed hourly by dreamstate-to-issues.mjs (ships in SUP-5).
• Sentry / Stripe webhook workers filing issues on production signals.

​

4. Cross-cutting concerns

​

4.1 Identity & access

​

4.2 Security model

• Delete a Cloudflare Worker, R2 bucket, KV namespace, or D1 database
• Change a ruleset, environment protection rule, or access policy
• Write to a Neon production user-data table
• Mutate Stripe products, prices, or webhook endpoints in production
• Send live email/SMS outside test mode
• Rotate the GitHub App private key (manual UI only)
• Make a private repo public or vice versa
• Cancel or change the org billing plan

• Issue body, comments, labels, and branch names are untrusted data, never instructions.
• Supervisor planner system prompt structurally separates [YOUR INSTRUCTIONS - IMMUTABLE] from [ISSUE CONTEXT - UNTRUSTED DATA].
• Tool calls are schema-bounded against capabilities.yml; no “execute arbitrary string” tool exists.
• Write-amplification ceiling: ≤25 mutating calls per run, ≤5 per app.
• /admin mutations get out-of-band CODEOWNER ✅ via GitHub comment reaction regardless of tier.

• credential-scrub.yml blocks PRs introducing credential-shaped strings to documents/, memory/, docs/, or *.md. Pattern set at PR #115.
• Policy: any credential appearing in a doc is compromised regardless of exposure duration; rotate, don’t just delete.

​

4.3 Secrets management

• Code
• wrangler.jsonc vars (only non-secret config)
• documents/, memory/, docs/ (credential-scrub enforces)
• Issue bodies, PR descriptions, comments

​

4.4 Observability

• Sentry — errors + perf + breadcrumbs + sourcemaps. Org latwood-tech. One project per worker (10 live projects).
• PostHog — product analytics. One project per app.
• factory_events — first-party business events table in Neon (factory-core DB). Everything material (signup, payment, webhook, deploy, rollback) writes a row.
• llm_ledger — D1 table owned by @latimer-woods-tech/llm-meter (ships SUP-2.2). Every LLM call writes a row keyed on (project, actor, run_id, yyyy-mm).
• template_stats — D1 table (ships SUP-3.4). Template hit-rate, revert-rate, blessed status.
• supervisor_runs / supervisor_steps / supervisor_locks_audit — D1, per-run audit trail.
• Pushover (conn_iR1TgasqajZH) — morning digest + Sentry SMS spike + budget-paused alerts.
• Telnyx SMS — backup alert channel for production-critical Sentry issues.

1. Sentry release created with the merge SHA as the release name
2. Sourcemaps uploaded for every worker (retroactive fix: many existing workers still need this wired — tracked as an item in the gap register §15)
3. /health curl passes before traffic shifts
4. Canary rides for N minutes (default 30) on new releases before marking stable

​

4.5 Cost & budgets

• Calibration (weeks 2–4): no monthly caps. Per-call ceiling 50k tokens. Per-run hard ceiling $5 USD. Every call metered to llm_ledger.
• Steady-state (week 5+): monthly caps set at observed p95 × 1.5 per (project, actor). Email alert at 75%. Hard stop at 100%. Monthly review.

• HumanDesign Practitioner tier at scale: ~$0.043/synthesis blended; 22$97 tier at 500 syntheses/mo.
• Supervisor planner: Sonnet 4.5 calls with growing RAG context; mitigate with prompt caching + switching to Gemini long-context at >150k tokens.
• Video pipeline (videoking): transcoding on CF Stream at ~$0.005/minute of source. Monitor when volume scales.

• Cloudflare Workers: ~$5/mo per account (current Pro plan). Grows with request volume.
• Neon: ~$19/mo per project at the Scale tier. 14 projects currently.
• GCP: ~$30/mo for Cloud Run idle (min=1 on xico-city processor) + Vertex AI usage (starts in SUP-2).

​

4.6 Data plane

Retired 2026-06-17: gemini-staging (fancy-mouse-91117889) + gemini-production (misty-bonus-64352779) — deleted after confirming archived branches + only wind-down ops (tenant_detach/timeline_archive 2026-06-10), no live compute. Org dropped 15→13 projects.

​

4.7 Compliance posture

• Stripe PCI — Handled by Stripe Elements; Factory never sees raw PAN. SAQ-A eligible.
• GDPR / CCPA — @latimer-woods-tech/compliance exposes a DSR (data subject request) primitive; not yet wired into all apps (gap).
• TCPA — Relevant only to wordis-bond (engine designed for it) and any telephony use in other apps. @latimer-woods-tech/compliance provides consent logs + opt-out enforcement; wordis-bond is the only consumer.
• FDCPA — Same story: wordis-bond-specific. Hard-locked from automation until legal clarity.
• HIPAA — Not in scope. HumanDesign Energy Blueprint is not PHI.
• State privacy laws (CA, VA, CO, CT, UT, NV, TX) — Relevant for HumanDesign Practitioner tier (clients are potentially residents). DSR path needs to be E2E tested before Q3 2026.

• DSR E2E path per app (HumanDesign priority)
• Data-retention policy documentation
• Incident response runbook for breach (a stub exists; needs legal review)

​

5. Delivery lifecycle

Stage 6 (Primus design system) is in flight — docs/architecture/PRIMUS.md is the authority for the token/component/a11y/forms/icons rollout.

​

5.1 The 9-step flow

1. Issue filed          → 2. Added to board     → 3. Agent claims
  ↓                        ↓                        ↓
[GitHub Issue]           [Project v2 #1]         [agent:claimed:X]
                         [Status: Todo]          [Status: In Progress]

4. Agent opens PR       → 5. CI validates       → 6. Required review
  ↓                        ↓                        ↓
[Branch pushed]          [_app-ci.yml]           [CODEOWNERS check]
[Links "Closes #N"]      [_app-reliability-gate] [mergeable_state: clean]

7. PR merges            → 8. Deploy fires       → 9. Verified live
  ↓                        ↓                        ↓
[squash to main]         [_app-deploy.yml]       [/health probe]
[Issue auto-closes]      [wrangler deploy]       [_post-deploy-verify]
[Status: Done]           [Deploy SHA captured]   [_app-prod-canary]
                                                 [rollback on fail]

​

5.2 Tier paths (exhaustive)

​

5.3 CODEOWNERS (target state after MA-4)

# Red-tier default
*                                    @adrper79-dot

# Yellow-tier paths where factory-cross-repo can auto-merge on green CI
apps/*/src/**                        @adrper79-dot @factory-cross-repo
client/**                            @adrper79-dot @factory-cross-repo
tests/**                             @adrper79-dot @factory-cross-repo

# Green-tier paths where factory-cross-repo can merge on blessed template
docs/**                              @adrper79-dot @factory-cross-repo
*.md                                 @adrper79-dot @factory-cross-repo
session/**                           @adrper79-dot @factory-cross-repo

# Explicit Red-tier guards (belt and suspenders)
.github/workflows/**                 @adrper79-dot
packages/**                          @adrper79-dot
workers/src/db/migrations/**         @adrper79-dot
workers/src/handlers/billing*        @adrper79-dot
workers/src/handlers/admin*          @adrper79-dot
workers/src/handlers/stripe*         @adrper79-dot
capabilities.yml                     @adrper79-dot
wrangler.jsonc                       @adrper79-dot

​

5.4 Canary + rollback protocol

1. Deploy new version to 10% of traffic (or equivalent for single-worker apps: deploy, then curl /health + key routes).
2. Watch Sentry for new issues + error-rate spike over baseline (default 30 min).
3. If clean: promote to 100% (no-op for single-worker pattern).
4. If spike: auto-rollback via wrangler rollback <prior_deployment_id> + Pushover alert.

​

5.5 Merge queue

​

6. Governance

​

6.1 Decision gating

• A CODEOWNER ✅ reaction on the issue, OR
• A merged PR updating docs/supervisor/DECISIONS.md with the resolved outcome.

​

6.2 ADRs

​

6.3 Fridge rules

​

6.4 Memory single-writer

1. supervisor-loop.yml concurrency group (group: supervisor-loop, cancel-in-progress: false) — queues supervisor runs so two instances never execute simultaneously. The second run waits until the first completes; no memory-write tick is lost.
2. memory-single-writer.yml PR check — blocks any PR that edits memory/*.md when another open PR already has pending memory edits. Posts a blocking comment identifying the conflicting PR(s) and fails the required status check.
3. CODEOWNERS memory/** entry — pins @adrper79-dot as sole required reviewer for all memory/ changes, so the branch-protection review gate fires on every memory write regardless of tier.

​

Part II — Playbooks

​

7. Playbook: add a new app to the portfolio

1. Decide strategic tier (revenue-facing, utility, etc.) and supervisor access level (none / Green / Yellow).
2. Use scripts/scaffold.mjs in factory to create the repo under Latimer-Woods-Tech.
3. Apply the standard ruleset via setup-all-apps.mjs (branch protection, required checks).
4. Add CODEOWNERS matching §5.3 tier paths, adjusted for this app’s specific Red-tier paths.
5. Add caller workflows pointing at _app-ci.yml, _app-deploy.yml, _post-deploy-verify.yml, _app-reliability-gate.yml, _app-prod-canary.yml.
6. Provision Neon project in Adrian org; create production branch; wire Hyperdrive binding in wrangler.jsonc.
7. Create Sentry project + DSN org secret.
8. Add row to docs/service-registry.yml with base_url, consumers, supervisor access.
9. Add capabilities.yml at repo root declaring every /admin route the supervisor can call. Strict slot typing. side_effects per route.
10. Add to this document’s §2.1 portfolio table.
11. File tracking epic on LatWood Operations board linking back to §2.

​

8. Playbook: ship a new version of a shared package

1. Create a branch feat/<package>-<summary> in factory.
2. Edit the package under packages/<name>/.
3. Run pnpm -F @latimer-woods-tech/<name> build && pnpm -F @latimer-woods-tech/<name> test locally.
4. Bump version in the package’s package.json (semver: patch for fixes, minor for additive, major for breaking).
5. Update CHANGELOG.md in the package directory.
6. Open PR against factory main. Label: priority:P1 (or P0 for security), phase as appropriate. Include blast-radius list of consumer apps.
7. CI runs _app-ci.yml + _app-reliability-gate.yml.
8. On merge: factory’s publish.yml workflow tags the package and publishes to registry.npmjs.org.
9. Renovate opens PRs in every consumer app to bump the pinned version.
10. Review consumer bumps per app (Red on packages; humans merge).
11. For breaking changes (major bump): write a migration guide in docs/packages/<name>/MIGRATION-<prev>-to-<new>.md.

​

9. Playbook: rotate a secret

​

9.a GCP service-account key

1. GCP console → IAM → Service Accounts → select SA → Keys → Add Key → Create new key (JSON). Download securely.
2. Map downstream consumers: grep -r "factory-sa\|supervisor-sa" ~/code/ + check wrangler secret list on every worker.
3. Update every consumer (worker secrets via wrangler secret put; GitHub Actions org secrets via gh secret set; Sauna stored connection via Settings UI).
4. Verify each consumer authenticates with the new key (whoami-style call per service).
5. GCP console → revoke the old key.
6. Document the rotation in docs/runbooks/secret-rotation.md with the date + consumers touched.

​

9.b GitHub App private key

​

9.c GH PAT (workflow scope)

1. Mint new PAT via https://github.com/settings/tokens with the needed scopes (usually repo + workflow + read:org + write:packages + project).
2. Update Sauna stored connection conn_pvMtrQjxhkoZ via Settings UI (or replace if UI blocks edit).
3. Update GH_PAT org secret via gh secret set GH_PAT --org Latimer-Woods-Tech.
4. Revoke old PAT.

​

9.d Cloudflare API Token

1. Cloudflare dashboard → My Profile → API Tokens → Create similar token with the same permissions.
2. Update conn_nud8DHhsDidu via Sauna Settings.
3. Update CLOUDFLARE_API_TOKEN org secret.
4. Revoke old.

​

9.e Stripe

​

9.f Anthropic / provider API keys

​

10. Playbook: respond to a Sentry spike

1. Pushover fires with the issue short-id + link.
2. Open Sentry → issue → events/latest/. Capture: culprit, stack frames, recent tags, request URL, user count.
3. If sourcemaps are uploaded: stack has real file:line. Otherwise you need to grep the dist or read the source to find the call site.
4. Determine blast radius: single user? Single route? All requests?
5. Decide:
   • Transient (third-party outage, one-off): resolve as auto-resolved with a note. Revisit if it recurs.
   • Code bug: file or find the GH issue; link Sentry. Follow playbook §11 if it’s a migration gap.
   • Degraded state: trigger the degraded-mode feature flag if available; post user-facing status if customer-visible.
6. If user impact is > 10 users OR revenue-critical: consider rolling back (wrangler rollback <prior_sha>) while investigating.
7. After fix merges + deploys: resolve the Sentry issue with the commit SHA in the note.

​

11. Playbook: debug a migration drift

1. Confirm the column/table exists in the repo. grep -r "<column_name>" workers/src/db/migrations/ in the app repo. If it’s there: this is drift, not a missing migration.
2. Connect to the app’s production Neon via the direct connection string from the Neon dashboard.
3. Query information_schema.columns (or .tables) to confirm what’s actually in prod.
4. Read the migration tracking table: SELECT * FROM drizzle.__drizzle_migrations ORDER BY id (or wherever the runner puts it).
5. Compute the gap: repo latest migration number minus prod applied. Apply missing migrations in order via psql -f OR via the repo’s npm run migrate.
6. Verify the Sentry error stops firing within 2 hours.
7. File or update SUP-1.4 (migration-drift-guard) so this never happens silently again.

​

12. Playbook: author a supervisor template

1. Pick a closed Red-tier or Yellow-tier issue that took the human < 2 hours and had a clear shape.
2. Read the merged PR diff + commit trail. What files changed? What API calls happened in workflow logs?
3. Draft docs/supervisor/plans/<slug>.yml following docs/supervisor/TEMPLATE_SPEC.md:
   • triggers (labels_any_of, title_pattern)
   • preconditions (capability_exists)
   • slots with strict validators (type + regex or enum or referential_check)
   • steps with depends_on chains
   • acceptance_gate with verifier_query where possible
   • rollback plan
4. Create a fixture at tests/supervisor/fixtures/<slug>.yml (a sample issue that should match).
5. Open PR. template-suite.yml runs match + parameterize + gates against the fixture; must pass.
6. Review with a CODEOWNER. Template starts unblessed. After 3 clean runs in prod (0 reverts, 0 overrides), it auto-blesses.

​

13. Playbook: resolve an open decision

1. Open docs/supervisor/DECISIONS.md and find the decision row.
2. Click through to the linked issue (#110, #111, #112, etc.).
3. Read the context + options + recommendation.
4. Either:
   • React ✅ on the issue. The scheduled daily digest picks this up and opens a PR moving the row from “Currently open” to “Resolved” in DECISIONS.md.
   • Open a decision PR directly updating DECISIONS.md. Include the reasoning in the PR body.
5. Merge the resolution PR. Downstream work (typically a phase exit gate) unblocks.

​

14. Playbook: onboard a new agent

​

14.a Human CODEOWNER

1. Grant repo write access under Latimer-Woods-Tech.
2. Add to CODEOWNERS on paths they’ll own.
3. Have them read docs/supervisor/FRIDGE.md (5 minutes) and this document’s §1 + §4 + §5 (another 15).
4. Pair on one Red-tier PR review before they solo.

​

14.b Second Sauna instance (parallel worker)

1. MA-8 (memory single-writer) is mechanically enforced: memory-single-writer.yml blocks any PR that edits memory/*.md while another PR already has pending memory edits. The second Sauna must treat memory/*.md as read-only and propose edits as PRs.
2. Agent claims issues via agent:claimed:sauna-2 label (or similar discriminator).
3. Same fridge rules apply.
4. Coordinate via issue comments, not via shared memory.

​

14.c Third-party autonomous agent (e.g., Copilot)

1. Give it access scoped to Green-list paths only.
2. Its commits must carry a trailer identifying the agent for audit traceability.
3. If it’s App-authenticated: verify the App’s signed-commit requirement matches what the ruleset expects.
4. Start it on supervisor:approved-source + Green-only issues for the first week.

​

Part III — Current-state routing

​

15. Gap register

1. docs/supervisor/DECISIONS.md for founder-blocked decisions.
2. Open GitHub issues carrying status:blocked, priority:*, and ownership labels for executable work.
3. docs/STATE.md and docs/service-registry.yml for generated and deployed facts.
4. Docs Health and service-registry validation for detected drift.

​

16. Roadmap: current → steady state

​

17. Appendices

​

17.a Canonical names + IDs

• conn_pvMtrQjxhkoZ — GitHub PAT (workflow scope)
• conn_nud8DHhsDidu — Cloudflare API Token
• conn_yF3m9DEuPI8x — GCP SA (known-broken for OAuth minting; use in-script JWT)
• conn_iR1TgasqajZH — Pushover (primary alerts)
• conn_C9zi6T2td8mt — Telnyx (SMS backup)

​

17.b Glossary

• Blessing — a template reaches blessed status after ≥3 successful runs with 0 reverts and 0 human overrides. Blessed templates skip plan-approval on Green.
• Calibration phase — weeks 2–4 when LLM usage is metered without monthly caps, only per-run $5 hard stops. Data feeds the steady-state caps.
• Confused deputy — an attack where an authorized principal (supervisor) is tricked into performing actions on behalf of an unauthorized actor (issue-body prompt injection).
• Dreamstate — the spec-layer input to the supervisor. Intent in YAML; supervisor translates to issues.
• Fridge — docs/supervisor/FRIDGE.md. The 10 non-negotiable operating rules. Read first.
• Hard-never list — actions the supervisor cannot perform regardless of tier or approval. See §4.2.
• Plan-approval — the gate requiring CODEOWNER ✅ on the planner’s proposed tool-call sequence before EXEC. Required on first 10 runs per template and always on Yellow/Red.
• Side effects (graded) — capability declaration field: none / read-external / write-app / write-external. Replaces boolean mutating.
• Source-trust label — supervisor:approved-source. Required on any issue before the supervisor will pick it up.
• Template drift / migration drift — code and deployed state disagreeing about schema or interface. The class of bug SUP-1.4 catches.

​

17.c Related documents (canonical map)

​

17.d Change log

• 2026-05-02 — v1 initial publication. Consolidates prior architecture docs. Supersedes listed above. Authored by Sauna for Adrian; awaiting CODEOWNER ✅ for canonical status.

​

How to propose changes to this document

1. Open a PR updating docs/architecture/FACTORY_V1.md on factory.
2. Label documentation + priority:P1.
3. If the change resolves an open decision, also update docs/supervisor/DECISIONS.md in the same PR.
4. If the change conflicts with FRIDGE rules, stop and open an ADR first (FRIDGE revisions require ADRs).
5. CODEOWNER review required (Red-tier path by default).