Singularity

cosmos:singularity

Declare a project-level quantum singularity. Singularities are events that reshape the solution space itself — major migrations, paradigm shifts, compliance changes, framework upgrades. After a singularity, insights from before the event may be stale.

This is the macro-scale layer of QuantumAgent. While /cosmos spawn operates at the universe scale (N parallel implementations), /cosmos singularity operates at the project scale (events that affect ALL future explorations).

Trigger

/cosmos singularity --name "<event>" --invalidates "<pattern1,pattern2,...>" [--trigger "<reason>"] [--description "<text>"]

Examples:

/cosmos singularity --name "auth-migration-v2" \
  --trigger "compliance-2026-Q3" \
  --invalidates "session-based-auth,pre-2026-cookie-policy" \
  --description "All session-based auth retired. JWT-only going forward."

/cosmos singularity --name "framework-upgrade-next15" \
  --trigger "performance-mandate" \
  --invalidates "pages-router,getServerSideProps-patterns"

Execution Steps

Step 1 — Detect repo root

git rev-parse --show-toplevel

Store as <repo_root>.

Step 2 — Parse arguments

From the trigger message, extract:

• --name (required) — short identifier, kebab-case (e.g., auth-migration-v2)
• --invalidates (required) — comma-separated patterns/tags this event invalidates
• --trigger (optional) — what caused this singularity (compliance, performance, etc.)
• --description (optional) — free-text explanation

If --name or --invalidates missing:

❌ Singularity requires --name and --invalidates.
   Usage: /cosmos singularity --name "<event>" --invalidates "<patterns>"

Step 3 — Prepare quantum memory

mkdir -p <repo_root>/.quantum/singularities
touch <repo_root>/.quantum/singularities/events.jsonl

Step 4 — Generate ISO timestamp

Capture current timestamp in ISO 8601 format (UTC, e.g., 2026-05-12T14:32:00Z). Store as <ts>.

Step 5 — Append singularity event

Build the JSON event:

{
  "name": "<name>",
  "ts": "<ts>",
  "trigger": "<trigger or null>",
  "invalidates": ["<pattern1>", "<pattern2>", ...],
  "description": "<description or null>"
}

Append to events file:

echo '<json>' >> <repo_root>/.quantum/singularities/events.jsonl

Important: Always append, never overwrite. The events log is the project's macro-scale history — it must be append-only for audit integrity.

Step 6 — Check for active cosmos

git -C <repo_root> worktree list | grep -E '\[cosmos/' || true

If active cosmos worktrees exist, output a warning:

⚠️  Active cosmos detected: <list>
   This singularity will NOT retroactively affect running cosmos.
   New /cosmos spawn calls will inherit the singularity automatically.
   To apply to current cosmos: run /cosmos stop, then /cosmos spawn again.

If no active cosmos, skip this step.

Step 7 — Confirm declaration

Output:

☄️  Singularity declared

   Name:        <name>
   Timestamp:   <ts>
   Trigger:     <trigger or "(unspecified)">
   Invalidates: <invalidates>

   Description: <description or "(none)">

🌌 All future /cosmos spawn calls will inherit this singularity as macro context.
   Insights matching invalidated patterns will be treated as pre-singularity (stale).

   Logged at: .quantum/singularities/events.jsonl

When to use

Good fit:

• Major migration completed (auth system, database, framework)
• Compliance requirement changed (GDPR, SOC2, HIPAA scope shift)
• Architectural paradigm transition (monolith → microservices, REST → GraphQL)
• Performance contract changed (new SLA, hard latency ceiling)
• Security incident response (token format change, key rotation event)

Not a fit:

• Routine code changes (use git commits, not singularities)
• Single-feature additions (these don't invalidate prior context)
• Bug fixes (these are insights, not singularities)
• Personal preferences (singularities are project-wide, not per-developer)

Why this matters

Without macro-scale events, every /cosmos spawn starts from the same baseline. Insights from 6 months ago — when the project used cookies for auth — would still inform new explorations, even though cookies are no longer relevant.

Singularities establish temporal coherence: cosmos automatically know "we're in the post-migration era" without manual context-pasting. This is the General Relativity of QuantumAgent — the constraints curve the solution space, and singularities mark phase transitions in that curvature.

Format reference

.quantum/singularities/events.jsonl is append-only JSONL. Each line:

{"name":"<kebab-case-id>","ts":"<ISO-8601>","trigger":"<reason>","invalidates":["<pattern>",...],"description":"<text>"}

All future /cosmos spawn and /cosmos observe operations read this file to inject macro context.