Harden Antigravity governance docs

Author: ProfRandom92

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

@@ -1,5 +1,6 @@
 ---
 name: ctxt-antigravity-governance
+description: "Defines token-efficient governance and operating guidelines for agent runs."
 summary: "Defines token-efficient governance and operating guidelines for agent runs."
 ---
 

docs/ANTIGRAVITY_CLI_INTEGRATION.md

@@ -37,13 +37,13 @@ flowchart TD
     subagent -->|7. audit proposal| prop
     agent -->|8. apply gate| ctxt
     ctxt -->|9. policy hook validation| policy
-    policy -->|10. sandboxed commit| repo
+    policy -->|10. sandboxed write execution| 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.
+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. Note that `proposals/` contains ignored/generated runtime state and is excluded from Git tracking in the release package baseline.
 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/ARTIFACT_POLICY.md

@@ -18,4 +18,4 @@ This document clarifies the classification, location, and Git tracking rules for
 - **Classification**: Committed audit evidence.
 - **Location**: `reports/` at the repository root.
 - **Git Policy**: **Tracked**. These files serve as permanent evidence of completed developmental milestones, including network constraints and validation command logs.
-- **Purpose**: Documents phase reports and compliance tracking logs (e.g., `reports/phase_*_status.md`).
+- **Purpose**: Documents phase reports and milestone tracking logs (e.g., `reports/phase_*_status.md`).

docs/HOOK_GOVERNANCE.md

@@ -1,6 +1,6 @@
 # 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.
+Hooks are policy-interceptor targets designed to enforce safety boundaries before, during, and after agent runs. This document defines the target architecture for interceptor hooks within the CompText workspace. Note that these hooks represent a planned target architecture and are not yet locally implemented in the current code execution pipeline.
 
 ---
 
@@ -25,28 +25,28 @@ The target architecture defines four critical interceptor locations:
 ```
 
 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.
+   - **Trigger**: Planned trigger when a new agent session or subagent run is initiated.
+   - **Verification**: Intended to parse workspace config and verify CLI version. Checks local Git state by default; matching against remote origin main branches is performed only when remote checks are explicitly authorized.
 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.
+   - **Trigger**: Planned trigger immediately before any tool (e.g. file read, file write, shell command execution) is run.
+   - **Verification**: Intended to evaluate inputs against active policy rules, failing closed and blocking 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.
+   - **Trigger**: Planned trigger immediately after a tool finishes running, before returning the output to the agent's context.
+   - **Verification**: Intended to filter and redact 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.
+   - **Trigger**: Planned trigger when an agent signals completion of a roadmap phase.
+   - **Verification**: Intended to run the **Global Validation Suite** and check Git status to ensure the working tree remains clean before triggering the Git push progression pipeline.
 
 ---
 
-## 2. Policy Enforcements
+## 2. Intended Policy Enforcement (Target Architecture)
 
-The hook governance architecture must actively enforce the following rules:
+The hook governance target architecture is designed for the following intended enforcement policies:
 
-- **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.
+- **Block `.env` and Secret Reads**: PreToolUse hooks are planned to block attempts to read `.env`, `.env.*`, keyfiles (`*.key`, `*.pem`, `*.p12`, `*.pfx`), or private keys.
+- **Block Environment Variable Printing**: Intended to block executing commands like `env`, `printenv`, or `Get-ChildItem Env:` to prevent leakages of system configuration credentials.
+- **Block Network and Provider Calls**: Intended to intercept socket calls or provider invocations unless the active phase config explicitly permits network access.
+- **Block Out-of-Bounds Writes**: Intended to restrict file modifications to paths inside the repository root, rejecting edits targeting directories outside the workspace.
+- **Block Broad Repository Rereads**: Intended to limit tool executions that read the entire codebase recursively unless justified by a phase transition.
+- **Require Proposal Before Apply**: Intended to enforce that source code modification is only done via the `ctxt apply` flow referencing a verified JSON proposal from `proposals/`.
+- **Require Local Validation**: Intended to block marking a phase as complete until all commands in the validation suite pass successfully.

docs/MVP_STATUS.md

@@ -16,7 +16,7 @@ All core architecture components and phase requirements are fully implemented an
 
 ---
 
-## 2. Security Boundaries & Constitution Compliance
+## 2. Security Boundaries & Constitution Alignment
 
 - **Model/Provider Output Untrusted**: All suggestions, snippets, and patches produced by provider models are treated as untrusted inputs. They are subjected to the apply-time write sandbox and post-apply validation gates.
 - **Network Boundaries (Deny-by-Default)**: Real external network execution is strictly denied unless explicitly authorized. The OpenAI-compatible adapter operates entirely offline in this MVP phase.

docs/PERMISSIONS_MODEL.md

@@ -1,6 +1,6 @@
 # Permissions Model
 
-CompText utilizes a defense-in-depth permissions model to restrict agent actions at the operating system and execution environment level. 
+CompText utilizes a defense-in-depth permissions model to restrict agent actions at the orchestrator and runtime execution environment level. 
 
 ---
 
@@ -10,9 +10,9 @@ Permissions do not serve as the primary policy compiler. Instead, they act as lo
 
 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.
+3. **Permissions Model**: Orchestrator-enforced runtime restrictions acting as a defense-in-depth policy layer.
 
-If a hook fails or an agent attempts to bypass logical constraints, the permissions model catches the violation and halts the execution thread.
+If a hook fails or an agent attempts to bypass logical constraints, the orchestrator's runtime permissions model acts as a secondary layer to block unauthorized actions.
 
 ---
 

docs/RELEASE_CHECKLIST.md

@@ -30,7 +30,7 @@ Use this checklist to verify the stability, security boundaries, and validation
   ```bash
   cargo clippy -- -D warnings
   ```
-- [ ] Production build succeeds:
+- [ ] Release target build succeeds:
   ```bash
   cargo build --release
   ```

docs/SKILL_AUTHORING_GUIDE.md

@@ -4,14 +4,17 @@ Skills are progressive context-loading capsules that guide agent behavior for sp
 
 ---
 
-## 1. Skill File Layout
+## 1. Skill Folder and File Layout
 
-Every skill must live in the `.agent/skills/` (or `.agents/skills/`) directory as a markdown file structured as:
+Every skill must be authored as a directory under `.agent/skills/` (or `.agents/skills/`) containing a `SKILL.md` file. For example, `.agent/skills/ctxt-antigravity-governance/SKILL.md`.
+
+The frontmatter of each `SKILL.md` file must be structured as:
 
 ```markdown
 ---
 name: ctxt-phase-XX-name
-summary: "A brief 1-line description of the skill for the compatibility manifest."
+description: "A detailed description of the skill used as the primary routing and trigger field by the Antigravity Orchestrator."
+summary: "Optional secondary metadata summarizing the skill."
 ---
 
 # Skill: ctxt-phase-XX-name
@@ -40,7 +43,7 @@ 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`.
+- The **task description** matching the skill `name` or `description`.
 - Active **phase declarations** (e.g., `Phase 12`).
 
 ---

docs/SUBAGENT_GOVERNANCE.md

@@ -8,7 +8,7 @@ Subagents allow parallel task execution and validation. To prevent recursive exe
 
 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.
+- **`security-reviewer`**: Audits codebase modifications and document updates for secret leakage, credentials, and forbidden readiness/compatibility 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.

docs/VALIDATE_BENCHMARK.md

@@ -4,7 +4,7 @@ This document details the usage and specifications for the local validation and
 
 ## 1. Local Validation Command
 
-The `ctxt validate` command prints the standard local validation commands used to ensure codebase integrity and safety compliance.
+The `ctxt validate` command prints the standard local validation commands used to ensure codebase integrity and safety verification.
 
 ### Usage
 ```bash