Skip to content

Commit e0edbf2

Browse files
ProfRandom92ProfRandom92
authored
Merge pull request #2 from ProfRandom92/phase-16-agent-state-contract
Add Phase 16 agent state contract skeleton
2 parents d2f75d6 + 2b36fa0 commit e0edbf2

9 files changed

Lines changed: 884 additions & 11 deletions

File tree

‎.agent/skills/REGISTRY.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,3 +90,12 @@ This document serves as the local registry index for all authorized skills in th
9090
- **Forbidden Scope**: Implementing remote network registries, blockchain, consensus protocols, or active hooks.
9191
- **Validation Commands**: `cargo test`
9292
- **Local SHA-256 Checksum**: `68D210DCAF7E7A95F65AC9EE5179FD60212D63CD9B85A92F24A9D4267B64B329`
93+
94+
### 10. `ctxt-phase-16-agent-state-contract`
95+
- **Path**: [.agent/skills/ctxt-phase-16-agent-state-contract/SKILL.md](file:///.agent/skills/ctxt-phase-16-agent-state-contract/SKILL.md)
96+
- **Description**: Adds local agent state capturing, verification, and reporting commands.
97+
- **Intended Use**: Capturing local agent state and verifying agent-state JSON files against actual files.
98+
- **Allowed Scope**: Modifying Rust CLI files and adding markdown docs.
99+
- **Forbidden Scope**: Implementing remote network registries, blockchain, consensus protocols, active hooks, or making unsupported claims.
100+
- **Validation Commands**: `cargo test`
101+
- **Local SHA-256 Checksum**: `AD4A5832B29E290B8E0EEAF535EB97D8589CB6E4AAF565B8882F0F2DC9BB51A6`

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

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
name: ctxt-phase-16-agent-state-contract
3+
description: "Adds local agent state capturing, verification, and reporting commands."
4+
summary: "Defines agent-state contract skeleton for CompText."
5+
---
6+
7+
# Skill: ctxt-phase-16-agent-state-contract
8+
9+
## Goal
10+
Establish a skeleton for agent-state tracking using bounded evidence JSON files.
11+
12+
## Read first
13+
- AGENTS.md
14+
- PROJEKT.md
15+
- docs/AGENT_STATE_CONTRACT.md
16+
- docs/EVIDENCE_CONTROL_PLANE.md
17+
18+
## Use when
19+
- Capturing local agent state.
20+
- Verifying agent-state JSON files against actual files.
21+
- Summarizing evidence status reports.
22+
23+
## Allowed
24+
- Modifying Rust CLI files (`src/cli.rs`) and adding markdown docs.
25+
- Writing test verification artifacts.
26+
27+
## Forbidden
28+
- Performing live network calls or using cloud APIs.
29+
- Creating remote registries.
30+
- Using active hooks.
31+
- Making unsupported assurance claims.
32+
33+
## Validation
34+
- `cargo test`

‎PROJEKT.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,10 @@ CompText CLI is an experimental terminal context client for building determinist
1919

2020
### Current State
2121
```text
22-
CURRENT_PHASE: 15
23-
CURRENT_TASK: Cryptographic Provenance Engine
22+
CURRENT_PHASE: 16
23+
CURRENT_TASK: Agent State Contract Skeleton Review-Gate
2424
LAST_GREEN_PHASE: 15
25-
STATUS: complete
25+
STATUS: review-pending
2626
```
2727

2828
### Autonomy Contract
@@ -90,7 +90,7 @@ git push
9090
| **Phase 13** | Skill Bundle Registry | Local skill bundle registry and starter skill templates | **COMPLETE** |
9191
| **Phase 14** | Hook/Permission Integration | Hook boundaries, dynamic run approvals | **COMPLETE** |
9292
| **Phase 15** | Cryptographic Provenance Engine | local SHA-256 provenance manifests | **COMPLETE** |
93-
| **Phase 16** | Agent State Contract | Planning only on feature branch | **PLANNING** |
93+
| **Phase 16** | Agent State Contract | Add local agent-state capture/verify/report | **REVIEW-GATE** |
9494

9595
---
9696

‎README.md‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -86,11 +86,11 @@ CompText is for developers who want AI-assisted workflows with stronger boundari
8686

8787
```text
8888
Binary: ctxt
89-
Current phase: Phase 15
90-
Current task: Cryptographic Provenance Engine
89+
Current phase: Phase 16
90+
Current task: Agent State Contract Skeleton Review-Gate
9191
Last green phase: Phase 15
92-
Status: complete
93-
Next allowed action: Phase 16 planning on feature branch
92+
Status: review-pending
93+
Next allowed action: Phase 16 Review-Gate closeout
9494
```
9595

9696
Completed so far:
@@ -114,12 +114,13 @@ Phase 12 Antigravity CLI Governance & Token Economy COMPLETE
114114
Phase 13 Skill Bundle Registry COMPLETE
115115
Phase 14 Hook/Permission Integration COMPLETE
116116
Phase 15 Cryptographic Provenance Engine COMPLETE
117+
Phase 16 Agent State Contract Skeleton REVIEW-GATE
117118
```
118119

119120
Next areas:
120121

121122
```text
122-
Phase 16 Agent State Contract planning on feature branch
123+
Phase 16 Review-Gate closeout
123124
```
124125

125126
### Review-Gate Operating Rules
@@ -162,7 +163,7 @@ flowchart LR
162163
P12 --> P13[Skill Registry]
163164
P13 --> P14[Hook Integration]
164165
P14 --> P15[Provenance Engine Cleanup]
165-
P15 --> P16[Agent State Contract Planning]
166+
P15 --> P16[Agent State Contract Skeleton]
166167
```
167168

168169
---

‎docs/AGENT_STATE_CONTRACT.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Agent State Contract
2+
3+
This document outlines the local agent state contract for context-controlled execution.
4+
5+
---
6+
7+
## 1. Local Agent State Contract Model
8+
9+
The agent state contract captures local workspace metadata and files to serve as bounded evidence artifacts.
10+
11+
- **Schema Definition**: Agent state files are stored as JSON documents (such as `.comptext/agent_state.latest.json`).
12+
- **Paths**: All paths in the evidence list must be relative to the repository root.
13+
- **Evidence IDs**: Every evidence item must have a unique identifier.
14+
- **Status and Failure Labels**: The state contract distinguishes between different status values and details errors using standard labels:
15+
- `ChecksumMismatch`
16+
- `PathSafetyViolation`
17+
- `InvalidSchema`
18+
- `MissingFile`
19+
20+
### Schema Shape
21+
22+
```json
23+
{
24+
"schema_version": "0.1",
25+
"task": "Build feature x",
26+
"timestamp": "2026-06-05T13:39:50Z",
27+
"evidence": [
28+
{
29+
"id": "src_cli_rs",
30+
"file_path": "src/cli.rs",
31+
"sha256": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
32+
"status": "verified",
33+
"failure_label": null
34+
}
35+
]
36+
}
37+
```
38+
39+
---
40+
41+
## 2. Boundaries and Verification Rules
42+
43+
- **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.
44+
- **No Unsupported Assurance Claims**: These state files and integrity checks are designed to support local change verification only.

‎docs/EVIDENCE_CONTROL_PLANE.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Evidence Control Plane
2+
3+
This document specifies the relationship between the local control plane and execution surfaces.
4+
5+
---
6+
7+
## 1. Role Division
8+
9+
- **CompText (Control Plane)**: CompText acts as the offline-first control plane. It defines context packs, executes verification commands, and manages local agent state schemas.
10+
- **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.
11+
12+
---
13+
14+
## 2. Bounded Evidence Trail
15+
16+
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.
17+
All audits, verification, and state reporting occur locally without remote coordination.

‎docs/MCP_PROVIDER_BOUNDARY.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# MCP and Provider Boundary
22

3-
MCP servers provide context and tool surfaces. They are security-sensitive boundaries.
3+
Model Context Protocol providers provide context and tool surfaces. They are security-sensitive boundaries.
44

55
## Minimal MCP stack
66

‎reports/phase_16_status.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Phase 16 Status Report: Agent State Contract Skeleton
2+
3+
## Status Summary
4+
- **Phase**: Phase 16: Agent State Contract Skeleton
5+
- **Status**: success
6+
- **Date**: 2026-06-05
7+
8+
---
9+
10+
## Metadata details
11+
- **PHASE**: Phase 16: Agent State Contract Skeleton
12+
- **STATUS**: success
13+
- **FILES_CHANGED**:
14+
- `src/cli.rs`
15+
- **DOCS_ADDED**:
16+
- `docs/AGENT_STATE_CONTRACT.md`
17+
- `docs/EVIDENCE_CONTROL_PLANE.md`
18+
- **COMMANDS_RUN**:
19+
- `cargo fmt --all --check`
20+
- `cargo check`
21+
- `cargo test`
22+
- `cargo clippy -- -D warnings`
23+
- **VALIDATION**:
24+
- Parsed, capture, and verification integration tests passed successfully.
25+
- **ARTIFACTS**:
26+
- `docs/AGENT_STATE_CONTRACT.md`
27+
- `docs/EVIDENCE_CONTROL_PLANE.md`
28+
- `reports/phase_16_status.md`
29+
- **GIT**: Committed to branch `phase-16-agent-state-contract` and pushed to origin.
30+
- **NETWORK**: offline-only
31+
- **SECRETS**: Redacted from all configurations and outputs.
32+
- **POLICY_DECISIONS**:
33+
- The local control plane is implemented strictly offline-only with no network connection.
34+
- The transient `.comptext` directory is ignored by file collection to prevent concurrent test race conditions.
35+
- Agent state capture evidence is deterministically sorted by ID and file path to guarantee a stable artifact output.
36+
- **RISKS**: Local checksums are supplementary change-detection metadata and do not represent unsupported assurance claims.
37+
- **NEXT**: Phase 16 Review-Gate closeout

0 commit comments

Comments
 (0)