Skip to content
SiteSwarm Platform Documentation

Rules

Architectural Rules & Invariants

This document defines the foundational architectural rules and non-negotiable operational invariants governing the SiteSwarm monorepo. Every developer, subagent, and automated process must adhere to these rules without exception.

1. Core Architectural & Code Invariants

  • Zero API Keys in Tests: Workspace unit and tooling test suites (pnpm run test, pnpm run test:tooling) must execute 100% offline and pass hermetically with zero API keys, cloud tokens, .env, or .dev.vars files present, remaining immune to ambient shell environment poisoning.
  • Strict Domain Separation (No Pricing in Architecture): Technical specifications, schemas, and code packages must never hardcode retail pricing, monthly retainers ($/mo), or gross margin formulas; architecture only manages technical capability IDs, schemas, and edge infrastructure.
  • No Prescriptive Founder Legal or Tax Advice: Technical documentation and AI agents must never issue prescriptive recommendations on business entity selection (LLC vs. S-Corp), tax distribution structures, or personal founder legal matters; output neutral checklists for external CPA/counsel consultation only.
  • Minimal Viable Abstraction (MVA): Design minimal flexible seams and intentionally defer premature complexity; every architectural specification must include an explicit ## Decisions Intentionally Deferred section.
  • Anti-Anchor Research Spikes: Research tickets (type:research / spike) must define (1) Unknown Question, (2) Decision Blocked, (3) Methodology, and (4) Objective Evaluation Criteria, and must never write predetermined answers or draft conclusions into ticket descriptions before research begins.

2. Documentation Governance Invariants

  • Strict 4-Pillar Documentation Taxonomy: All repository documentation under docs/ must reside exclusively inside one of four pillar directories: docs/architecture/, docs/runbooks/, docs/business/, or docs/write-ups/; loose files in the docs/ root or unauthorized directories fail pnpm run lint:arch.
  • Zero-Copy Documentation Portal Ingestion: The documentation portal (@siteswarm/app-docs) ingests canonical living documentation (docs/{architecture,runbooks,business}) directly in-place with zero file copying, no pre-build mirroring scripts, and complete omission of docs/write-ups/ (DOCS_PORTAL_ARCHITECTURE.md).
  • One-Way Citation Guard: Living canonical documents (AGENTS.md, HIGH_LEVEL_DESIGN.md, .agents/skills/**, and docs/{architecture,runbooks,business}/**) must never link to point-in-time files in docs/write-ups/. Point-in-time write-ups may freely link upward to canonical specifications.
  • Single Source of Truth (AGENTS.md): AGENTS.md is the canonical instruction file for developers and agents; tool-specific instruction files (CLAUDE.md, GEMINI.md) must be tracked relative symlinks pointing to AGENTS.md.

3. Development, Trunk & Verification Invariants

  • Trunk-Based Development & Worktree Confinement: main is the single integration trunk; direct pushes and force-pushes are blocked. All feature, bugfix, and documentation edits must be performed in isolated Worktrunk (wt) worktrees branched from origin/main and submitted via Pull Requests.
  • Two-Tier Verification Gate (Passing CI ≠ Verified): A task or PR is never declared ready for human review solely because CI passes. Passing unit tests with mocked functions do not prove runtime correctness. Every deliverable requires both Tier 1 Machine Gate verification (pnpm run check, pnpm run lint) and Tier 2 Behavioral Runtime Proof against the real edge runtime or CLI.
  • Mechanical Pre-Merge Latch: Pull Requests must never be merged via raw gh pr merge or unguarded wt merge. Merging is strictly attested and executed through the mechanical merge guard (pnpm run merge <PR_NUMBER>), enforcing 100% green status checks on Gate, governance/two-stage-review, and Evaluate Monorepo Changes.
  • Zero Untracked Ghost Work: Every interaction falls into Track 1 (Active Development associated with a claimed GitHub issue with 4-part Acceptance Criteria) or Track 2 (Idea Ingestion quarantined under needs-grooming). Never perform untracked code changes.

Decisions Intentionally Deferred

  • Automated enforcement of business domain boundaries via AST semantic linting is tracked as a future linter capability in docs/architecture/linters/.