id: GUIDE-OPS-001 title: Operating Guide: The Promotion Protocol (CI/CD) status: active visibility: public

Operating Guide: The Promotion Protocol

The following diagram visualizes how different types of changes (Code vs. Documentation) navigate their own "Flight Paths" through common checkpoints to reach production.

graph TD
    %% Starting Actors
    Human[👤 Human Developer]
    Robot[🤖 AI Swarm / Robot]

    %% Decision Spine (Vertically Aligned)
    Human --> Dev
    Robot --> Dev[Active Development]

    Dev --> D1{"{Pre-Commit Audit}"}

    D1 -->|Pass| Commit[Local Commit]
    D1 -->|Fail| Dev

    Commit --> Push[Push to dev]

    Push --> D2{"{Flight Path Router}"}

    subgraph "Validation Airstrips"
        direction LR
        D2 -->|docs/*| F1[Doc Audit]
        D2 -->|apps/*| F2[Code Check]
        D2 -->|pkg/*| F3[Full Blast]
    end

    F1 --> D3{"{Integration Gate}"}
    F2 --> D3
    F3 --> D3

    D3 -->|FAILED| Push
    D3 -->|PASSED| Promote[PROMOTE to stg]

    Promote --> D4{"{Forensic Review}"}

    D4 -->|REJECT| Dev
    D4 -->|APPROVE| Ratify[RATIFY to main]

    Ratify --> Live[Live / Production]
    Live --> Publish[PUBLISH / Docs Site]

    %% Styling for alignment and emphasis
    style Human fill:#eef,stroke:#333
    style Robot fill:#fee,stroke:#333
    style D1 fill:#f9f,stroke:#333
    style D2 fill:#f9f,stroke:#333
    style D3 fill:#dfd,stroke:#333,stroke-width:2px
    style D4 fill:#f9f,stroke:#333
    style Live fill:#dfd,stroke:#333,stroke-width:3px

1. The Shortcut Language (The Lifecycle)

We use a specific vocabulary to describe the movement of work through our environments:

Shortcut	Phase	Goal	Command/Action
Commit	Sandbox (Local)	Save & Validate	`git commit` (triggers audit)
Push	Integration (`dev`)	Sync with Team	`git push origin dev`
Promote	Staging (`stg`)	Human Review	GH Action: `Promote dev -> stg`
Ratify	Production (`main`)	Release to World	GH Action: `Merge stg -> main`
Publish	Live Site	Public Visibility	Automatic on Ratification

2. Shared Foundations vs. Atomic Flight Paths

The repository is built as a Monorepo, but we use Atomic Pipelines to ensure speed and isolation.

2. The Validation Battery (Detailed Breakdown)

Each path triggers a specific set of automated "Examinations" before the code is allowed to enter the Integration (dev) airstrip.

📝 Documentation Path (`docs/*`)

Integrity Audit: Runs audit-docs.ts. It checks for missing frontmatter (ID, Title), verifies footer consistency, and scans for secrets/high-entropy strings. It will "Auto-Fix" metadata but "Block" on security risks.

🏛️ Platform Path (`apps/platform/*`)

Lint & Style: Ensures code follows the project's formatting and quality rules (ESLint).
Structural Integrity (TSC): A deep "MRI" of the code's types. It ensures that data flowing between components matches their expected shapes.
Logic Verification (Vitest): Runs the core unit tests to ensure that internal business logic hasn't broken during changes.

🎨 Marketing Path (`apps/marketing/*`)

Consolidated Suite: Runs Lint, Type-Check, and a Production Build simultaneously. This ensures the site not only looks right but can be successfully compiled for the web.

🛠️ SysOps Path (`apps/sysops/*`)

Execution Test: Validates that the operations tools and AI orchestration scripts can build and execute without circular dependencies.
Automated Deployment: Unlike legacy versions, the Unified Beast is now automatically deployed to Google Cloud Run via Cloud Build when changes are promoted to tst or stg. This ensures the "Brain" of the system is always using the latest logic.

🔋 Shared Path (`packages/*`)

Full Battery Blast: Since shared packages are the "Foundation," changing them triggers ALL of the above validations. If you change the shared UI library, we test the Platform, Marketing, and SysOps apps to ensure no regressions were introduced.

3. How to Execute (Developer Workflow)

3. Local Checkpoints: The Pre-Commit "Blockade"

Before your code is even allowed to be saved (committed) to your local machine, the system runs a series of GCP-Native Health Checks. This ensures that only "Self-Healing" and verified code enters the shared stream.

1. The Architecture Re-Index

Action: pnpm run arch:index
Goal: Automatically scans the documentation/ folder and updates 00_INDEX.md. This ensures the project's "Table of Contents" is always accurate without manual maintenance.

2. Documentation Pulse-Check

Action: scripts/diagnostics/audit-docs.ts --fix
Goal: Injects missing technical headers and ensures every document has a Version History.
CRITICAL: It scans for leaked secrets or high-entropy tokens. If it finds a potential risk, the commit will fail, and you must remove the data before proceeding.

3. Modular Boundary Defense

Action: pnpm run dep:check (Dependency Cruiser)
Goal: Enforces the architecture's "Sovereignty." For example, it prevents a low-level Utility package from accidentally importing a high-level UI component (which would cause "Circular Dependency circular-death").

4. The Global "Look-See" (Lint & TSC)

Action: pnpm run lint & tsc --noEmit
Goal: Catches syntax errors, unused variables, and type mismatches across the entire workspace. If your change breaks a package in a distant part of the monorepo, you'll know before you push.

4. How to Execute (Developer Workflow)

Stage 1: Commit & Push (Local to Integration)

Follow the "Blockade" checks mentioned above. Once passed:

Push: git push origin feature/my-cool-feature (or direct to dev for small fixes).

Stage 2: Promote (Integration to Staging)

To Staging: Use the GitHub "Promote" workflow. This moves code into stg for pilot review.

Stage 3: Ratify (Staging to Production)

To Production: Once verified in Staging, the code is Ratified into main. This is the final "Book of Truth."

5. Branching Strategy: The Hierarchy of Truth

We use a "Tiered Branching" model to isolate experimental work from stable releases.

The Permanent Tiers

These branches are protected and should never be deleted: | Branch | Tier | Purpose | Allowed Sources | | :--- | :--- | :--- | :--- | | dev | Integration | Where all team work converges for initial testing. | feature/*, ghost/* | | stg | Staging | The pre-release environment for pilot review. | dev | | main | Production | The "Book of Truth" - current live release. | stg |

8. The Architecture of Segregation (Sovereign Domains)

Our Monorepo is physically and logically divided into "Sovereign Domains". This segregation ensures that a change in Marketing does not accidentally break the Platform.

1. The Physical Segregation (`apps/`)

apps/marketing: The Public Website (singulardream.org).
Promotion: Deploys via Vercel when you push to main.
apps/platform: The Resident Portal ("Check-In App").
Promotion: Deploys via Firebase Hosting when you push to main.
apps/sysops: Internal Tools (Ghostbusters, Scripts, AI Brain).
Promotion: Deploys to Google Cloud Run for internal scaling and orchestration. Accessible via Mission Control.

2. The Documentation Airlift (`documentation/`)

Documentation lives in the "Vault" (Monorepo) but is published to a separate "Display Case".

Source: You edit markdown files in documentation/ on main.
Filter: When you push, tools/publish-docs.ts runs.
- It REMOVES any file marked security: internal.
- It REMOVES private folders (contracts, keys).
Airlift: Clean files are pushed to SD-HOA/singular-dream-docs (gh-pages branch).
Result: The public sees only sanitized content at docs.singulardream.org.

Feature Branches (LOC: The Laboratory)

When starting a new task, always work in a Feature Branch.

Naming: Use LOC/[scope]/[task-name] (e.g., LOC/marketing/hero-update).
When to use: For any non-trivial change, new feature, or bug fix.
When NOT to use: Small, documentation-only typos can sometimes be pushed directly to tst (if allowed), but feature branches are always safer.

Ghost Branches (The Daily Catch-All)

Naming: Use ghost/[date] or ghost/[theme] (e.g., ghost/2026-01-29).
When to use: For "gardening," rapid-fire small fixes, agentic sessions, or daily cleanup where a full "Feature" is overkill.
Workflow: Create in the morning -> Accumulate small wins -> Merge to tst at sunset -> Delete.

Common Commands

Action	Command
Start Task	`git checkout -b LOC:[scope]/[name]`
Save Work	`git commit -m "feat(scope): desc"`
Update	`git pull origin tst --rebase`
Finish	Open Pull Request to `tst`

9. Standard 99: Air Traffic Control (ATC)

We maintain a "Friendly Skies" policy. Branches must not be left stranded.

Basis: Risk Assessment Report (2026-01-29)

The ATC Protocol

Executed daily via /air_traffic_control.

Scan: Run npx tsx scripts/ops/flight-radar.ts.
Analyze: Identify "Stranded Flights" (Behind > 3 days or Diverged).
Remediate:
- CRASH: Delete abandoned branches immediately.
- LAND: Rebase and merge valuable stranded code.
Report: Ensure the Flight Radar is clean before starting new work.

Rule: If a branch runs out of fuel (no commits for 7 days), it is liable to be crashed (deleted) without warning to clear the airspace.

5. Documentation as an Application

We treat our docs as a first-class application.

Drafting: Write in Markdown in the documentation/ folder.
Audit: Every push triggers audit-docs.ts to check for security and integrity.
Filtration: When we Publish, a special script filters out everything marked security: internal before it hits the public website.

6. The Transformation: Linking vs. Transpilation

Just as a Mainframe Linker binds object modules into an executable Load Module, our CI/CD pipeline performs a modern equivalent. We don't just "copy" files; we transform them into their final optimized states.

1. The Code Airstrips (Transpilation & Tree Shaking)

For Platform and Marketing, we use a process called Hydration and Linking:

Transpilation: Raw TypeScript (human-readable) is transpiled into optimized JavaScript (machine-executable).
Tree Shaking (Linking): The build engine (Next.js/Webpack) scans all shared packages and "links" only the code that is actually used. Unused functions are discarded to keep the "Load Module" small.
Static Optimization: Dynamic paths are pre-calculated and "baked" into the bundle, similar to how a linker resolves external references.

2. The Documentation Airstrip (Filtering & Publishing)

Documentation follows a Sovereignty Filter before it becomes "Public":

Logical Linking: The publish-docs.ts tool acts as a security gateway. It scans every document and "unlinks" any file marked security: internal.
Markdown to HTML: The raw Markdown is transformed into a navigable, linked web portal via MkDocs.
Index Ratification: The 00_INDEX.md is verified and renamed to index.md to ensure the entry point is consistent for the web server.

3. Packaging & Shared modules (Monorepo Convergence)

When you change a Shared Package, the "Linker" logic (Turborepo) calculates the downstream impact:

Dependency Tracing: If packages/foundation changes, the system knows exactly which "Load Modules" (apps) need to be re-linked and re-verified.
Remote Caching: We store previously "linked" bundles. If the input hasn't changed, we reuse the existing executable instead of re-linking from scratch.

7. Alternatives Considered

Directory-Tree Based Promotion (Environmental Folders)

An alternative approach to branching is managing environments as physical folders (e.g., /dev, /stg, /prd) within a single branch.

Why we considered it: It provides instant visibility; you can compare environments with a simple folder diff.
Why we rejected it:
Path Rot: Moving code between folders breaks relative imports (e.g., ../../components becomes ../components).
Code Duplication: It requires maintaining three complete copies of the application on every branch.
CI Complexity: It is difficult to trigger environment-specific security gates and branch protections.
Hybrid History: Global logs become "noisy," mixing production releases with developmental experiments.

Decision: We standardized on Branch-Based Promotion to maintain the architectural sovereignty of each environment and leverage standard CI/CD hardening tools.

Version History

Version	Date	Author	Change
1.1.0	2026-02-09	Antigravity	Unified Beast: Integrated Cloud Run deployment into SysOps path
1.0.0	2026-01-26	Antigravity	Initial Operating Guide for Cl/CD & Promotion Protocol