Add Phase 16 agent state contract skeleton

.agent/skills/REGISTRY.md

@@ -90,3 +90,12 @@ This document serves as the local registry index for all authorized skills in th
 - **Forbidden Scope**: Implementing remote network registries, blockchain, consensus protocols, or active hooks.
 - **Validation Commands**: `cargo test`
 - **Local SHA-256 Checksum**: `68D210DCAF7E7A95F65AC9EE5179FD60212D63CD9B85A92F24A9D4267B64B329`
+
+### 10. `ctxt-phase-16-agent-state-contract`
+- **Path**: [.agent/skills/ctxt-phase-16-agent-state-contract/SKILL.md](file:///.agent/skills/ctxt-phase-16-agent-state-contract/SKILL.md)
+- **Description**: Adds local agent state capturing, verification, and reporting commands.
+- **Intended Use**: Capturing local agent state and verifying agent-state JSON files against actual files.
+- **Allowed Scope**: Modifying Rust CLI files and adding markdown docs.
+- **Forbidden Scope**: Implementing remote network registries, blockchain, consensus protocols, active hooks, or making unsupported claims.
+- **Validation Commands**: `cargo test`
+- **Local SHA-256 Checksum**: `AD4A5832B29E290B8E0EEAF535EB97D8589CB6E4AAF565B8882F0F2DC9BB51A6`

.agent/skills/ctxt-phase-16-agent-state-contract/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: ctxt-phase-16-agent-state-contract
+description: "Adds local agent state capturing, verification, and reporting commands."
+summary: "Defines agent-state contract skeleton for CompText."
+---
+
+# Skill: ctxt-phase-16-agent-state-contract
+
+## Goal
+Establish a skeleton for agent-state tracking using bounded evidence JSON files.
+
+## Read first
+- AGENTS.md
+- PROJEKT.md
+- docs/AGENT_STATE_CONTRACT.md
+- docs/EVIDENCE_CONTROL_PLANE.md
+
+## Use when
+- Capturing local agent state.
+- Verifying agent-state JSON files against actual files.
+- Summarizing evidence status reports.
+
+## Allowed
+- Modifying Rust CLI files (`src/cli.rs`) and adding markdown docs.
+- Writing test verification artifacts.
+
+## Forbidden
+- Performing live network calls or using cloud APIs.
+- Creating remote registries.
+- Using active hooks.
+- Making unsupported assurance claims.
+
+## Validation
+- `cargo test`

PROJEKT.md

@@ -19,10 +19,10 @@ CompText CLI is an experimental terminal context client for building determinist
 
 ### Current State
 ```text
-CURRENT_PHASE: 15
-CURRENT_TASK: Cryptographic Provenance Engine
+CURRENT_PHASE: 16
+CURRENT_TASK: Agent State Contract Skeleton Review-Gate
 LAST_GREEN_PHASE: 15
-STATUS: complete
+STATUS: review-pending
 ```
 
 ### Autonomy Contract
@@ -90,7 +90,7 @@ git push
 | **Phase 13** | Skill Bundle Registry | Local skill bundle registry and starter skill templates | **COMPLETE** |
 | **Phase 14** | Hook/Permission Integration | Hook boundaries, dynamic run approvals | **COMPLETE** |
 | **Phase 15** | Cryptographic Provenance Engine | local SHA-256 provenance manifests | **COMPLETE** |
-| **Phase 16** | Agent State Contract | Planning only on feature branch | **PLANNING** |
+| **Phase 16** | Agent State Contract | Add local agent-state capture/verify/report | **REVIEW-GATE** |
 
 ---
 

README.md

@@ -86,11 +86,11 @@ CompText is for developers who want AI-assisted workflows with stronger boundari
 
 ```text
 Binary: ctxt
-Current phase: Phase 15
-Current task: Cryptographic Provenance Engine
+Current phase: Phase 16
+Current task: Agent State Contract Skeleton Review-Gate
 Last green phase: Phase 15
-Status: complete
-Next allowed action: Phase 16 planning on feature branch
+Status: review-pending
+Next allowed action: Phase 16 Review-Gate closeout
 ```
 
 Completed so far:
@@ -114,12 +114,13 @@ Phase 12  Antigravity CLI Governance & Token Economy COMPLETE
 Phase 13  Skill Bundle Registry                  COMPLETE
 Phase 14  Hook/Permission Integration            COMPLETE
 Phase 15  Cryptographic Provenance Engine        COMPLETE
+Phase 16  Agent State Contract Skeleton          REVIEW-GATE
 ```
 
 Next areas:
 
 ```text
-Phase 16  Agent State Contract planning on feature branch
+Phase 16 Review-Gate closeout
 ```
 
 ### Review-Gate Operating Rules
@@ -162,7 +163,7 @@ flowchart LR
     P12 --> P13[Skill Registry]
     P13 --> P14[Hook Integration]
     P14 --> P15[Provenance Engine Cleanup]
-    P15 --> P16[Agent State Contract Planning]
+    P15 --> P16[Agent State Contract Skeleton]
 ```
 
 ---

docs/AGENT_STATE_CONTRACT.md

@@ -0,0 +1,44 @@
+# Agent State Contract
+
+This document outlines the local agent state contract for context-controlled execution.
+
+---
+
+## 1. Local Agent State Contract Model
+
+The agent state contract captures local workspace metadata and files to serve as bounded evidence artifacts.
+
+- **Schema Definition**: Agent state files are stored as JSON documents (such as `.comptext/agent_state.latest.json`).
+- **Paths**: All paths in the evidence list must be relative to the repository root.
+- **Evidence IDs**: Every evidence item must have a unique identifier.
+- **Status and Failure Labels**: The state contract distinguishes between different status values and details errors using standard labels:
+  - `ChecksumMismatch`
+  - `PathSafetyViolation`
+  - `InvalidSchema`
+  - `MissingFile`
+
+### Schema Shape
+
+```json
+{
+  "schema_version": "0.1",
+  "task": "Build feature x",
+  "timestamp": "2026-06-05T13:39:50Z",
+  "evidence": [
+    {
+      "id": "src_cli_rs",
+      "file_path": "src/cli.rs",
+      "sha256": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
+      "status": "verified",
+      "failure_label": null
+    }
+  ]
+}
+```
+
+---
+
+## 2. Boundaries and Verification Rules
+
+- **Local Verification**: The verifying command parses the agent state and checks that all evidence IDs are unique, paths are relative, schema version is exactly `0.1`, and hashes match when present.
+- **No Unsupported Assurance Claims**: These state files and integrity checks are designed to support local change verification only.

docs/EVIDENCE_CONTROL_PLANE.md

@@ -0,0 +1,17 @@
+# Evidence Control Plane
+
+This document specifies the relationship between the local control plane and execution surfaces.
+
+---
+
+## 1. Role Division
+
+- **CompText (Control Plane)**: CompText acts as the offline-first control plane. It defines context packs, executes verification commands, and manages local agent state schemas.
+- **Antigravity (Execution Surface)**: Antigravity acts as the execution surface. It reads context packs to formulate prompt queries, but the control plane remains the authoritative boundary.
+
+---
+
+## 2. Bounded Evidence Trail
+
+Agent state JSON files serve as bounded evidence trails. By logging the status and SHA-256 hashes of changed files, the control plane can verify that execution is consistent with the planned task boundary.
+All audits, verification, and state reporting occur locally without remote coordination.

docs/MCP_PROVIDER_BOUNDARY.md

@@ -1,6 +1,6 @@
 # MCP and Provider Boundary
 
-MCP servers provide context and tool surfaces. They are security-sensitive boundaries.
+Model Context Protocol providers provide context and tool surfaces. They are security-sensitive boundaries.
 
 ## Minimal MCP stack
 

reports/phase_16_status.md

@@ -0,0 +1,37 @@
+# Phase 16 Status Report: Agent State Contract Skeleton
+
+## Status Summary
+- **Phase**: Phase 16: Agent State Contract Skeleton
+- **Status**: success
+- **Date**: 2026-06-05
+
+---
+
+## Metadata details
+- **PHASE**: Phase 16: Agent State Contract Skeleton
+- **STATUS**: success
+- **FILES_CHANGED**:
+  - `src/cli.rs`
+- **DOCS_ADDED**:
+  - `docs/AGENT_STATE_CONTRACT.md`
+  - `docs/EVIDENCE_CONTROL_PLANE.md`
+- **COMMANDS_RUN**:
+  - `cargo fmt --all --check`
+  - `cargo check`
+  - `cargo test`
+  - `cargo clippy -- -D warnings`
+- **VALIDATION**:
+  - Parsed, capture, and verification integration tests passed successfully.
+- **ARTIFACTS**:
+  - `docs/AGENT_STATE_CONTRACT.md`
+  - `docs/EVIDENCE_CONTROL_PLANE.md`
+  - `reports/phase_16_status.md`
+- **GIT**: Committed to branch `phase-16-agent-state-contract` and pushed to origin.
+- **NETWORK**: offline-only
+- **SECRETS**: Redacted from all configurations and outputs.
+- **POLICY_DECISIONS**:
+  - The local control plane is implemented strictly offline-only with no network connection.
+  - The transient `.comptext` directory is ignored by file collection to prevent concurrent test race conditions.
+  - Agent state capture evidence is deterministically sorted by ID and file path to guarantee a stable artifact output.
+- **RISKS**: Local checksums are supplementary change-detection metadata and do not represent unsupported assurance claims.
+- **NEXT**: Phase 16 Review-Gate closeout