cgg

Context Grapple Gun

A file-based governance lifecycle for persistent AI systems.

Three commands. Five structural mechanisms. One scale boundary.

---

You only need four things to start:

• Three commands: /cadence, /review, /siren
• Run /cadence to end every session cleanly; run /review every few sessions to approve lessons
• Scope ladder: Site > Domain > Estate > Federation > Global -- you decide what promotes
• Install: npx context-grapple-gun install -- or see INSTALL.md for details

---

Read this first (by intent)

You want to...	Start here
Install now	npx context-grapple-gun install -- zero-thought entry, handles everything
Use it now	START-HERE.md -- the three commands, a normal day, what to expect
Understand the pipeline	DEV-README.md -- session flow, hook lifecycle, extraction pipeline
Evaluate the architecture	ARCHITECTURE.md -- signal manifold, acoustic model, governance layers
Audit recent changes	docs/COMMIT-HISTORY-CHEATSHEET.md
Learn through story	academy/README.md -- five chapters, real simulations, one very persistent goat
All install options	INSTALL.md -- npm, plugin, bootstrap, manual, academy

---

90-second mental model

The problem: AI agents discover truths during work -- bug patterns, API quirks, coordination techniques that work. When the session ends, that knowledge vanishes. Next session: same agent, same repo, zero memory of what it learned.

The CGG answer: Lessons get captured as they happen, reviewed between sessions, and promoted to broader scopes with human approval at every gate. The project's operating rules grow from real work, not from someone writing documentation.

Three commands run the lifecycle:

Command	What it does
/cadence	End of session. Saves lessons, emits a tic (sequenced timestamp), writes a handoff for the next session.
/review	Review proposed lessons. Approve, reject, or modify before promotion.
/siren	Check on recurring friction. See what signals are building, what warrants have minted.

Five structural mechanisms make it work:

Mechanism	What it does
Abstraction ladder	Scope hierarchy: site > domain > estate > federation > global. Lessons climb it through review.
Epoch boundary	Context rotation discipline. End the session before cognitive degradation, carry knowledge forward.
Human gate	Every scope promotion requires explicit approval. The agent proposes; you decide.
Signal manifold	Runtime condition monitoring. Friction signals accrue volume, cross thresholds, mint warrants.
Tic / tic-zone	Canonical timestamping and jurisdictional scoping. Total ordering across agents and cadences.

One scale boundary:

CGG is the governance lifecycle. It uses flat files, git-tracked, auditable by default. When flat files aren't enough -- when you need semantic recall, graph topology, or conformation-aware retrieval -- the substrate layer (Ubiquity) picks up where CGG leaves off. Same governance primitives, deeper infrastructure. CGG is complete without Ubiquity. Ubiquity composes on top when scale demands it.

---

What CGG is not

• Not a vector database. No embeddings, no semantic search. Flat files and grep.
• Not a magical memory layer. Lessons require human review to promote. Nothing persists without approval.
• Not a full substrate. CGG handles governance lifecycle. Substrate capabilities (expression gating, graph topology, compiled constraints) require infrastructure CGG deliberately avoids.
• Not a hosted platform. Everything runs locally. No APIs, no services, no cloud dependencies.

---

Core terms (with neutral aliases)

On first encounter, CGG terminology maps to familiar systems concepts:

• CogPR -- behavior pull request: a proposed lesson flagged for review and promotion
• tic -- sequenced timestamp: ISO-8601 + monotonic counter for total ordering
• tic-zone -- jurisdiction boundary: .ticzone-defined acoustic region that scopes routing
• siren > warrant -- recurring friction signal that mints an escalation when it crosses threshold
• Abstraction ladder -- scope hierarchy: Site > Domain > Estate > Federation > Global; lessons climb through /review

Full glossary: docs/TERMINOLOGY.md.

---

Skeptic's evaluation path

~20 minutes to informed judgment.