Add antigravity governance and token economy plan (Phase 12)

Author: ProfRandom92

.agent/skills/ctxt-antigravity-governance/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: ctxt-antigravity-governance
+summary: "Defines token-efficient governance and operating guidelines for agent runs."
+---
+
+# Skill: ctxt-antigravity-governance
+
+## Goal
+Enforce token-efficient context parsing, hook governance, permissions checks, and subagent boundaries during Antigravity agent execution.
+
+## Read first
+- AGENTS.md
+- PROJEKT.md
+- docs/TOKEN_ECONOMY.md
+- docs/HOOK_GOVERNANCE.md
+- docs/SUBAGENT_GOVERNANCE.md
+
+## Use when
+- Auditing agent task runs.
+- Defining permissions profiles or subagent boundaries.
+- Refining token usage and model effort guidelines.
+
+## Forbidden
+- Reading `.env` or credentials files.
+- Dumping environment variables.
+- Performing live network calls without explicit phase authorization.
+- Writing outside the repository root.
+
+## Validation
+- `cargo test`
+- `git diff --exit-code`
+
+## Return
+Standard Phase Return Format.

PROJEKT.md

@@ -19,9 +19,9 @@ CompText CLI is an experimental terminal context client for building determinist
 
 ### Current State
 ```text
-CURRENT_PHASE: 11
-CURRENT_TASK: Release Packaging
-LAST_GREEN_PHASE: 11
+CURRENT_PHASE: 12
+CURRENT_TASK: Antigravity CLI Governance & Token Economy
+LAST_GREEN_PHASE: 12
 STATUS: complete
 ```
 
@@ -86,8 +86,8 @@ git push
 | **Phase 9** | Validate and Benchmark | Local validation, dry-runs, and deterministic benchmark flows | **COMPLETE** |
 | **Phase 10** | MVP Stabilization & Release Readiness | Audit documentation, verify command flows, safety hygiene checks | **COMPLETE** |
 | **Phase 11** | Release Packaging | Package CLI binary, finalize manifests, release artifact generation | **COMPLETE** |
-| **Phase 12** | Antigravity CLI Governance & Token Economy | Hook, registry token bindings, runtime stake checks | *NEXT* |
-| **Phase 13** | Skill Bundle Registry | Distributed skills indexing and integrity hashing | *QUEUED* |
+| **Phase 12** | Antigravity CLI Governance & Token Economy | Hook, registry token bindings, runtime stake checks | **COMPLETE** |
+| **Phase 13** | Skill Bundle Registry | Distributed skills indexing and integrity hashing | *NEXT* |
 | **Phase 14** | Hook/Permission Integration | Hook boundaries, dynamic run approvals | *QUEUED* |
 | **Phase 15** | Cryptographic Provenance Engine | Signed evidence trail generation and cryptographic integrity seals | *QUEUED* |
 

README.md

@@ -85,9 +85,9 @@ CompText is for developers who want AI-assisted workflows with stronger boundari
 
 ```text
 Binary: ctxt
-Current phase: Phase 11
-Current task: Release Packaging
-Last green phase: Phase 11
+Current phase: Phase 12
+Current task: Antigravity CLI Governance & Token Economy
+Last green phase: Phase 12
 Status: complete
 ```
 
@@ -108,13 +108,13 @@ Phase 8   OpenAI-Compatible Adapter              COMPLETE
 Phase 9   Validate and Benchmark                 COMPLETE
 Phase 10  MVP Stabilization & Release Readiness  COMPLETE
 Phase 11  Release Packaging                      COMPLETE
+Phase 12  Antigravity CLI Governance & Token Economy COMPLETE
 ```
 
 Next areas:
 
 ```text
-Phase 12  Antigravity CLI Governance & Token Economy NEXT
-Phase 13  Skill Bundle Registry                      QUEUED
+Phase 13  Skill Bundle Registry                      NEXT
 Phase 14  Hook/Permission Integration                QUEUED
 Phase 15  Cryptographic Provenance Engine            QUEUED
 ```

docs/ANTIGRAVITY_CLI_INTEGRATION.md

@@ -0,0 +1,49 @@
+# Antigravity CLI Integration Model
+
+This document outlines the integration architecture and operational boundaries between the **Antigravity Framework** (the Agent Execution Surface) and the **CompText CLI** (the Context, Policy, and Evidence Control Plane).
+
+---
+
+## 1. Core Doctrine
+
+CompText operates under a strict separation of concerns between agent execution and context governance:
+
+- **Antigravity CLI is the Agent Execution Surface**: Handles task orchestration, command execution, tool invocations, and subagent lifecycle management.
+- **CompText CLI (`ctxt`) is the Context, Policy, and Evidence Control Plane**: Manages deterministic context packaging, proposal audits, file-write validation gates, and safety constraints.
+- **Skills are progressive context-loading capsules**: Bounded guidelines designed to prevent context bloat and restrict agent operations.
+- **Hooks are policy-interceptor targets**: Structural interception points allowing verification before, during, and after agent activities.
+- **Permissions are defense-in-depth, not the source of truth**: Hard platform sandboxing boundaries that back up (but do not replace) the repository safety constitution.
+- **Subagents are bounded specialist reviewers**: Highly targeted, read-only assistants delegated for review rather than autonomous development.
+- **The source of truth remains the code repository**: Safety constitution (`AGENTS.md`), project tracker (`PROJEKT.md`), CompText configurations, the Proposal/Apply Gate, and local validation commands.
+
+---
+
+## 2. Structural Interaction
+
+```mermaid
+flowchart TD
+    subagent[Antigravity Subagent]
+    agent[Antigravity Orchestrator]
+    ctxt[CompText CLI]
+    repo[(Repository Codebase)]
+    policy[Policy Gate / Hook]
+
+    agent -->|1. context inspect| ctxt
+    ctxt -->|2. harvest & redact| repo
+    ctxt -->|3. pack latest| pack[.comptext/context_pack.latest.json]
+    agent -->|4. propose| ctxt
+    ctxt -->|5. write proposal| prop[proposals/proposal.latest.json]
+    agent -->|6. invoke reviewer| subagent
+    subagent -->|7. audit proposal| prop
+    agent -->|8. apply gate| ctxt
+    ctxt -->|9. policy hook validation| policy
+    policy -->|10. sandboxed commit| repo
+```
+
+---
+
+## 3. Operational Flow
+
+1. **Context Harvesting**: Before launching a task, the Antigravity Orchestrator executes `ctxt context pack --task "<task_description>"`. This harvest sanitizes the repository state, redacting secrets and building a deterministic Context Pack under `.comptext/context_pack.latest.json`.
+2. **Proposal Generation**: When proposing changes, the agent runs `ctxt propose --provider dummy "<prompt>"`. This creates a structured JSON patch proposal under `proposals/` without mutating source files.
+3. **Apply and Verification**: To modify the codebase, the agent calls `ctxt apply <proposal_path>`. The CompText control plane intercepts the request, validates that target files lie within allowed write boundaries, prompts for user confirmation (or validation suite success), applies the patches, and runs local tests.

docs/HOOK_GOVERNANCE.md

@@ -0,0 +1,52 @@
+# Hook Governance Model
+
+Hooks are policy-interceptor targets designed to enforce strict safety boundaries before, during, and after agent runs. This document defines the target architecture for interceptor hooks within the CompText workspace.
+
+---
+
+## 1. Interception Points
+
+The target architecture defines four critical interceptor locations:
+
+```text
+[ SessionStart Hook ]
+         │
+         ▼
+[ PreToolUse Hook ] ────( Violations? )────► [ FAIL CLOSED / HALT ]
+         │
+         ▼
+    ( Tool Run )
+         │
+         ▼
+[ PostToolUse Hook ] ───( Redact Secrets )──► [ Filtered Context ]
+         │
+         ▼
+[ PostPhase Hook ] ─────( Cargo Validation )──► [ Git Commit Pipeline ]
+```
+
+1. **SessionStart**:
+   - **Trigger**: Executed when a new agent session or subagent run is initiated.
+   - **Verification**: Parses workspace config, verifies CLI version, and checks that `AGENTS.md` and `PROJEKT.md` match remote origin main branches.
+2. **PreToolUse**:
+   - **Trigger**: Executed immediately before any tool (e.g. file read, file write, shell command execution) is run.
+   - **Verification**: Evaluates inputs against active policy rules. Fails closed and blocks execution if a violation is detected.
+3. **PostToolUse**:
+   - **Trigger**: Executed immediately after a tool finishes running, before returning the output to the agent's context.
+   - **Verification**: Filters and redacts high-entropy secrets, passwords, or credentials from command output and file read buffers.
+4. **PostPhase**:
+   - **Trigger**: Executed when an agent signals completion of a roadmap phase.
+   - **Verification**: Runs the **Global Validation Suite** and checks git status to ensure the working tree remains clean before triggering the git push progression pipeline.
+
+---
+
+## 2. Policy Enforcements
+
+The hook governance architecture must actively enforce the following rules:
+
+- **Block `.env` and Secret Reads**: PreToolUse hooks block attempts to read `.env`, `.env.*`, keyfiles (`*.key`, `*.pem`, `*.p12`, `*.pfx`), or private keys.
+- **Block Environment Variable Printing**: Blocks executing commands like `env`, `printenv`, or `Get-ChildItem Env:` to prevent leakages of system configuration credentials.
+- **Block Network and Provider Calls**: Intercepts socket calls or provider invocations unless the active phase config explicitly permits network access.
+- **Block Out-of-Bounds Writes**: Restricts file modifications to paths inside the repository root. Rejects edits targeting directories outside the workspace.
+- **Block Broad Repository Rereads**: Limits tool executions that read the entire codebase recursively unless justified by a phase transition.
+- **Require Proposal Before Apply**: Enforces that source code modification is only done via the `ctxt apply` flow referencing a verified JSON proposal from `proposals/`.
+- **Require Local Validation**: Blocks marking a phase as complete until all commands in the validation suite pass successfully.

docs/PERMISSIONS_MODEL.md

@@ -0,0 +1,32 @@
+# Permissions Model
+
+CompText utilizes a defense-in-depth permissions model to restrict agent actions at the operating system and execution environment level. 
+
+---
+
+## 1. Defense-in-Depth Doctrine
+
+Permissions do not serve as the primary policy compiler. Instead, they act as low-level guards supporting the Safety Constitution (`AGENTS.md`):
+
+1. **Safety Constitution (`AGENTS.md`)**: The primary rulebook governing logical behavior.
+2. **Hook Interceptors (`docs/HOOK_GOVERNANCE.md`)**: Contextual software gates executing within the workspace.
+3. **Permissions Model**: Hardware/runtime restrictions enforced by the orchestration host.
+
+If a hook fails or an agent attempts to bypass logical constraints, the permissions model catches the violation and halts the execution thread.
+
+---
+
+## 2. Permission Scopes
+
+The active execution environment is partitioned into narrow permission scopes:
+
+- **Read Access**: Restricted to the repository workspace directory. Reading files under `/etc`, `C:\Windows`, system temp directories, or user home directories (outside the workspace) is denied by default.
+- **Write Access**: Restricted to allowed targets within the workspace. Writing to system folders or configuration targets outside the project root is denied.
+- **Network Access**: Denied by default. Enforces blockades on remote socket connections.
+- **Provider Access**: Denied by default. Enforces blockades on calling external LLM providers or remote endpoints unless the phase explicitly authorizes mock or local integrations.
+
+---
+
+## 3. Explicit Phase Approval
+
+If a task requires a restricted operation (e.g., querying a local Ollama socket), the permissions must be upgraded using explicit, phase-scoped approvals in the task definition. Once the phase transitions, permissions automatically downgrade back to the default-deny baseline.

docs/SKILL_AUTHORING_GUIDE.md

@@ -0,0 +1,66 @@
+# Skill Authoring Guide
+
+Skills are progressive context-loading capsules that guide agent behavior for specific phases or architectural boundaries. This document outlines the structure, syntax, and registry rules for creating new skills.
+
+---
+
+## 1. Skill File Layout
+
+Every skill must live in the `.agent/skills/` (or `.agents/skills/`) directory as a markdown file structured as:
+
+```markdown
+---
+name: ctxt-phase-XX-name
+summary: "A brief 1-line description of the skill for the compatibility manifest."
+---
+
+# Skill: ctxt-phase-XX-name
+
+## Goal
+The exact objective this skill is authorized to accomplish.
+
+## Read first
+List of absolute or workspace-relative file links that the agent must read before executing any task under this skill.
+
+## Use when
+Explicit description of triggers, keywords, or phase constraints under which this skill is active.
+
+## Forbidden
+Concrete list of actions, commands, and files that are strictly banned while this skill is active.
+
+## Validation
+Command sequence required to verify task completeness.
+
+## Return
+The requested response format (e.g., standard status report schema).
+```
+
+---
+
+## 2. YAML Trigger Tracing
+
+Triggers in the YAML frontmatter inform the Antigravity Orchestrator when a skill is relevant. Triggers are resolved from:
+- The **task description** matching the skill `name` or `summary`.
+- Active **phase declarations** (e.g., `Phase 12`).
+
+---
+
+## 3. Naming Conventions
+
+To keep the registry consistent, all skill filenames and YAML names must follow one of these patterns:
+
+- `ctxt-phase-XX-*`: Mapped to a specific sequential phase in the project state machine (e.g., `ctxt-phase-12-antigravity-governance`).
+- `ctxt-security-review`: General security review and claims validation.
+- `ctxt-release-packaging`: Build verification and release checklist validation.
+- `ctxt-antigravity-governance`: Governance policy auditing.
+
+---
+
+## 4. Required Content Sections
+
+1. **Goal**: Must be concrete and bounded (no vague goals like *"Improve code"*).
+2. **Read first**: Must list the files representing the source of truth for the task (e.g., `AGENTS.md`, `PROJEKT.md`).
+3. **Use when**: Must describe the precise phase state.
+4. **Forbidden**: Must list global rules (e.g., *no network*, *no .env reads*) and task-specific constraints.
+5. **Validation**: Must include standard local commands (`cargo check`, `cargo test`, etc.).
+6. **Return**: Must match the standard schema declared in `AGENTS.md`.

docs/SUBAGENT_GOVERNANCE.md

@@ -0,0 +1,23 @@
+# Subagent Governance Model
+
+Subagents allow parallel task execution and validation. To prevent recursive execution issues or safety bypasses, subagents are subject to strict governance boundaries.
+
+---
+
+## 1. Allowed Roles
+
+Only the following specialist subagent roles are permitted in the CompText workspace:
+
+- **`security-reviewer`**: Audits codebase modifications and document updates for secret leakage, credentials, and forbidden compliance claims.
+- **`ci-diagnoser`**: Analyzes Cargo compilation failures, clippy warnings, or test logs, and recommends precise, localized corrections.
+- **`docs-consistency-checker`**: Audits documentation links, checks for file presence, and verifies README consistency.
+- **`proposal-auditor`**: Reviews proposal JSON structures before apply gate execution, confirming target write path safety.
+
+---
+
+## 2. Structural Constraints
+
+- **Read-Only Baseline**: Subagents are read-only by default. They are authorized to search and inspect files but are strictly denied write access to the repository unless explicitly authorized for a highly specific, localized task.
+- **No Git Commit or Push Authority**: Subagents must never stage, commit, or push changes to Git. Only the primary orchestrator holds Git progression authority.
+- **No Autonomous Feature Building**: Subagents are bounded specialist validators. They are prohibited from writing new features, modifying program logic, or creating new provider adapters.
+- **Inherited Boundaries**: Subagents inherit the parent agent's configuration, including network blockades, secret redaction policies, and stop conditions. They must never be used to circumvent parental sandboxes.

docs/TOKEN_ECONOMY.md

@@ -0,0 +1,33 @@
+# Token Economy Guidelines
+
+To maintain long-running, safe autonomous development, CompText enforces a token-efficient operating model. Large context windows introduce noise, increase costs, and degrade model reasoning capabilities. Bounding the context size is a core safety control.
+
+---
+
+## 1. Context Minimization Principles
+
+- **Read-First Minimalism**: The agent must read only the files declared in the `Read first` section of the active skill. Bulk directory reads or loading file logs outside the active scope are prohibited.
+- **One-Skill-at-a-Time Loading**: Only the single skill matching the active phase should be loaded into the workspace context. Loading multiple skills simultaneously causes instruction interference and unnecessary token consumption.
+- **No Repo-Wide Rereads Without Justification**: Repeating full context pack harvests (e.g., `ctxt context pack`) is permitted only when source files have changed or a new task boundary is crossed.
+- **Compact Phase Reports**: Status reports in the `reports/` folder must remain structured and concise. Avoid dumping complete compilation outputs, test outputs, or whole files. Summarize verification command results in a few clear bullet points.
+- **Session State Tracking**: The file `.comptext/session_state.md` is designated as the temporary local runtime session cache. This file is ignored by Git and is used to store active task notes, remaining token counts, and session progress metrics.
+
+---
+
+## 2. Model Effort Selection
+
+To optimize costs and reasoning depths, the orchestrator should select model efforts based on task complexity:
+
+| Complexity / Task Type | Target Model Effort | Description |
+|---|---|---|
+| **Low** / Syntax, Formatting, Clippy fixes | **Medium Effort** | Use for minor document cleanups, format checking, running local cargo checks, or generating release metadata. |
+| **High** / Structural Code, Merge Resolving, Security Auditing | **High Effort** | Use for resolving Git merge conflicts, reconciling branched PR states, running security/credential scans, or verifying critical provider adapter boundaries. |
+
+---
+
+## 3. Skill-Based Prompt Referencing
+
+Instead of repeating long, descriptive instructions inside the agent's chat window prompts, prompts should reference skills directly:
+
+- **Reference Syntax**: *"Load and execute skill `ctxt-phase-XX-name` by reading `file:///.agent/skills/ctxt-phase-XX-name/SKILL.md`."*
+- **Reasoning**: This offloads instruction formatting from the central chat context, ensuring the model references the precise skill markdown file statically rather than bloating the conversation transcript.