Skip to content

Commit 9687141

Browse files
ProfRandom92ProfRandom92
committed
docs(phase6): add agy-ct CLI architecture handbook
1 parent 2be0d76 commit 9687141

2 files changed

Lines changed: 227 additions & 0 deletions

File tree

‎PHASE6A_AGY_CT_AGENTIC_DETERMINISTIC_CLI_HANDBOOK.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# Phase 6A agy-ct Agentic Deterministic CLI Handbook
2+
3+
## 1. Product Definition
4+
`agy-ct` is a terminal-first, agent-facing and developer-centric Antigravity-CompText Rust SPARK CLI and workbench tool. It is designed to orchestrate local trace compression, sidecar generation, and operational context validation workflows. Unlike generic coding agents, `agy-ct` is a specialized workflow executor. It does not attempt to clone full Antigravity agent codebases, but focuses strictly on managing administrative AI pipeline states.
5+
6+
## 2. sparkctl Compatibility Strategy
7+
`sparkctl` remains the historical compatibility CLI for legacy and hackathon integrations, maintaining its current behavior and CLI parameters. `agy-ct` is introduced as a parallel, production-grade tool. Common core models, validators, and serializers in the underlying `agy7rust` crate will be shared across both CLI binaries. This ensures that:
8+
- Existing `sparkctl` features and APIs remain unchanged.
9+
- Shared logic updates both CLIs simultaneously.
10+
- Validation behavior remains consistent between the two CLIs.
11+
12+
## 3. Human UX vs Agentic Experience (AX)
13+
`agy-ct` is designed for dual-mode operation:
14+
- **Human UX:** Provides clear, colorful terminal status lines, warning notifications, and an intuitive nested subcommand taxonomy.
15+
- **Agentic Experience (AX):** Provides structured JSON reporting, robust non-interactive flags, deterministic exit codes, and machine-parsable error payloads with diagnostic identifiers.
16+
The tool implements an agentic terminal workflow design:
17+
`Plan -> Run -> Verify -> Replay -> Context -> Report`
18+
19+
## 4. Non-Interactive Mode Design
20+
When the `--non-interactive` flag is passed (or if no terminal/TTY is detected):
21+
- The CLI disables interactive prompting, paging, and confirmation requests.
22+
- If a destructive operation or missing argument requires input, the CLI must abort immediately, print a JSON or plain-text diagnostic payload, and exit with a non-zero code.
23+
- Interactive elements like spinners or progress bars are hidden or converted to static log outputs.
24+
25+
## 5. Generate-Validate-Fix Workflow
26+
`agy-ct` supports a multi-pass execution mode for automated script integration:
27+
1. **Generate**: Create compressed sidecars or context files.
28+
2. **Validate**: Perform strict schema verification, canonical ordering, and boundary checking.
29+
3. **Fix**: If validation fails on fixable issues (such as unstable key sorting or non-canonical whitespaces), the CLI can run minor formatting adjustments if permitted, or emit precise machine-readable corrections for the caller to apply.
30+
31+
## 6. agy-ct Command Taxonomy
32+
The CLI implements the following subcommand tree:
33+
- `agy-ct run`: Automatically coordinates the full local step sequence.
34+
- `agy-ct demo`: Runs a predefined end-to-end trace workflow.
35+
- `agy-ct doctor`: Performs local workspace integrity and configuration diagnosis.
36+
- `agy-ct validate`: Validates current project formatting, tests, and clippy rules.
37+
- `agy-ct handoff`: Pre-checks local repository readiness for handoff.
38+
- `agy-ct package compress`: Compress raw extraction files to `.spkg`.
39+
- `agy-ct package inspect`: Read sidecar properties and headers from `.spkg`.
40+
- `agy-ct package verify`: Run SHA-256 cryptographic verification of `.spkg`.
41+
- `agy-ct package replay`: Deterministically reconstruct and replay the sidecar trace.
42+
- `agy-ct package adversarial`: Verify robustness against tampered payload attributes.
43+
- `agy-ct context build`: Generate a structured operational context from a package.
44+
- `agy-ct context render`: Render operational context into token-light text.
45+
- `agy-ct context validate`: Run structural validation and leak checks on a context.
46+
- `agy-ct context all`: Execute context build, render, and validate tasks in sequence.
47+
- `agy-ct schema check`: Validate raw trace files against target JSON schemas.
48+
- `agy-ct report export`: Exporter for generated pipeline JSON reports.
49+
- `agy-ct notebook bundle`: Bundles context state and text renderings into a unified documentation payload.
50+
51+
## 7. agy-ct run Automatic Workflow
52+
The automatic executor `agy-ct run` coordinates the following order of local steps:
53+
1. **workspace doctor**: Ensure that schemas and configs are present.
54+
2. **package compress**: Generate the `.spkg` file from input traces.
55+
3. **package verify**: Confirm cryptographic signature and hashes.
56+
4. **package replay**: Replay sidecar tool order.
57+
5. **schema check**: Verify data conforms to schema definitions.
58+
6. **context build**: Compile the operational context.
59+
7. **context render**: Generate the token-light rendered text.
60+
8. **context validate**: Verify context structure and leak boundaries.
61+
9. **report export**: Write the final pipeline execution JSON report.
62+
63+
## 8. Terminal Output Model, Stdout/Stderr, and Exit Codes
64+
- **stdout**: Strictly reserved for primary payload data, requested exports, and JSON report strings. This ensures simple redirection to downstream tools.
65+
- **stderr**: Used for progress bars, diagnostics, human-readable titles, warnings, and log messages.
66+
- **Exit Codes**:
67+
- `0`: Success.
68+
- `1`: General runtime error.
69+
- `2`: Validation/leak boundary failure.
70+
- `3`: Missing configuration or schema.
71+
- `4`: Invalid file format or signature.
72+
- **Compact Errors**: The CLI outputs compact, single-line error descriptions by default. Detailed diagnostic logs or debugging stack traces can be accessed via `--explain <ERROR_CODE>` or the `--verbose` flag.
73+
74+
## 9. Output Modes
75+
The CLI supports the following output configurations:
76+
- **Default**: Styled, human-readable terminal output.
77+
- **`--plain`**: Text output without animations, progress tickers, or formatting blocks.
78+
- **`--json` / `--output json`**: All outputs are emitted as structured JSON objects on stdout.
79+
- **`--verbose`**: Outputs step-by-step diagnostic statements.
80+
- **`--quiet`**: Suppresses all stderr info logs; only critical errors are output.
81+
- **`--no-color`**: Disables ANSI color escapes.
82+
- **`--non-interactive`**: Prevents prompts and forces immediate termination on input requests.
83+
84+
## 10. JSON Report Schema Draft
85+
The JSON output generated by `report export` follows this structure:
86+
```json
87+
{
88+
"$schema": "http://json-schema.org/draft-07/schema#",
89+
"title": "AgyCtPipelineReport",
90+
"type": "object",
91+
"properties": {
92+
"timestamp": { "type": "string" },
93+
"cli_version": { "type": "string" },
94+
"execution_mode": { "type": "string" },
95+
"status": { "type": "string", "enum": ["success", "failed"] },
96+
"steps": {
97+
"type": "array",
98+
"items": {
99+
"type": "object",
100+
"properties": {
101+
"step_name": { "type": "string" },
102+
"status": { "type": "string" },
103+
"duration_ms": { "type": "integer" },
104+
"outputs": { "type": "object" },
105+
"error": { "type": "string" }
106+
},
107+
"required": ["step_name", "status", "duration_ms"]
108+
}
109+
},
110+
"metrics": {
111+
"type": "object",
112+
"properties": {
113+
"raw_bytes": { "type": "integer" },
114+
"compressed_bytes": { "type": "integer" },
115+
"compression_ratio": { "type": "number" },
116+
"leak_check_passed": { "type": "boolean" }
117+
}
118+
}
119+
},
120+
"required": ["timestamp", "cli_version", "status", "steps"]
121+
}
122+
```
123+
124+
## 11. Report/Notebook Export Strategy
125+
Reports and documentation packages generated by the pipeline are exported as standalone, self-contained artifacts. The `notebook bundle` subcommand combines:
126+
- Cryptographic signatures and package hashes.
127+
- Token-light context renderings.
128+
- Step-by-step metrics and timing statistics.
129+
The exported payload is formatted as a single archive or plain-text document, making it easily readable by down-stream agents or administrative archivists.
130+
131+
## 12. Artifact Model
132+
All files generated by the pipeline are mapped to deterministic output paths under the `artifacts/` folder:
133+
- Compressed packages: `artifacts/spark/*.spkg`
134+
- Build outputs: `artifacts/spark/*.json`
135+
- Renderings: `artifacts/spark/*_render.txt`
136+
- Reports: `reports/pipeline/*.json`
137+
138+
## 13. Context Cache Valve Strategy
139+
To optimize performance in nested agent executions without introducing file concurrency issues, `agy-ct` uses a local context cache valve:
140+
- Cached contexts are stored locally in a configured temp directory inside the project workspace.
141+
- The cache key is derived from the SHA-256 hash of the input `.spkg` and the JSON schema.
142+
- If a cached build output matches the key, the pipeline can skip the build phase and directly execute rendering or validation.
143+
- The cache valve is strictly local and offline.
144+
145+
## 14. Workspace Boundary and Safety Rules
146+
- **Safety Boundaries**: The CLI operates entirely locally. No network operations are run by default. No remote git actions (fetch, pull, commit, push) are executed.
147+
- **No Destructive Action Without Confirmation**: Commands that overwrite existing packages or clean historical records must require confirmation unless `--non-interactive` or `--force` is specified.
148+
- **Directory Traversal**: All operations are restricted to the local repository directory. No parent or sibling directory scanning is performed.
149+
- **Secrets Isolation**: Under no circumstances should access tokens, user secrets, or private environment variables be logged or stored inside exported JSON reports.
150+
151+
## 15. Dependency Recommendations
152+
- **Near-term Evaluation (Approved for blueprint only, no installation in this phase)**:
153+
- `clap`: For robust command-line argument parsing and nested subcommand trees.
154+
- `serde_json`: For structured JSON input/output and report generation.
155+
- `sha2`: For local SHA-256 hashing.
156+
- `anstream` & `anstyle`: For clean, style-aware terminal output handling.
157+
- `anyhow` or `miette`: For rich error reporting.
158+
- `thiserror`: For defining structured library error enumerations.
159+
- `assert_cmd` & `predicates`: For black-box integration tests of CLI binaries.
160+
- `insta`: For snapshot testing of rendered stdout outputs.
161+
- **Later Evaluation Options**:
162+
- `indicatif` (progress bars), `dialoguer` (interactive prompts), `dag_exec` (pipeline graph runner), `asupersync` (async IO synchronization), `wasm_sandbox` / `wasmtime` (secure plugin runtime), `tokio` (asynchronous runtime), `ratatui` (TUI terminal layouts).
163+
164+
## 16. Safety, Leak & Claim Hygiene Guidelines
165+
- **Wording Rules**:
166+
- Do NOT say "fully deterministic".
167+
- Do NOT say "100% safe".
168+
- Do NOT say "no risks".
169+
- Do NOT claim official SPARK compatibility.
170+
- Do NOT make EU AI Act compliance claims.
171+
- **Required Claims Wording**:
172+
- "Offline behavior was deterministic in the validated test scope."
173+
- "Configured leak checks passed in the validated scope."
174+
- "No blocking risks found in the validated scope."
175+
176+
## 17. Phased Implementation Plan
177+
- **Phase 6A**: Architecture blueprint and handbook definition (Current Phase).
178+
- **Phase 6B**: CLI binary initialization, setup of clap command parser tree, and validation tests.
179+
- **Phase 6C**: Implementation of `doctor`, `validate`, and `handoff` compatibility commands.
180+
- **Phase 6D**: Implementation of `package` and `context` orchestration wrappers.
181+
- **Phase 6E**: Implementation of `agy-ct run` step executor and JSON reporting.
182+
- **Phase 6F**: Pre-release verification and final rollup snapshot of the `agy-ct` tool.

‎PHASE6A_AGY_CT_CLI_ARCHITECTURE_AUDIT_SNAPSHOT.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Phase 6A agy-ct CLI Architecture Audit Snapshot
2+
3+
## 1. Files Inspected
4+
- [PHASE6A_AGY_CT_AGENTIC_DETERMINISTIC_CLI_HANDBOOK.md](file:///C:/Users/contr/sandbox_workspace/Antigravity-Comptextv7-unified/git_post_push_verification/repo/PHASE6A_AGY_CT_AGENTIC_DETERMINISTIC_CLI_HANDBOOK.md)
5+
6+
## 2. Audit Findings
7+
- **Handbook Confirmation**: The handbook `PHASE6A_AGY_CT_AGENTIC_DETERMINISTIC_CLI_HANDBOOK.md` exists and defines the product definition, compatibility strategy, human/AX experience parameters, output modes, command taxonomy, automatic execution workflow steps, caching, output models, and roadmap.
8+
- **Strict Scope Boundaries**:
9+
- No Rust source files were added or modified.
10+
- No changes were made to `Cargo.toml` or dependencies.
11+
- No integration or unit tests were added or modified.
12+
- No changes were made to the main `README.md` file.
13+
- No image assets or repository assets were added or modified.
14+
- No modifications to GitHub workflow files were introduced.
15+
- No dependency additions were made.
16+
- No git actions (commits, pushes, pulls, fetches) were performed.
17+
- No network activity occurred.
18+
- **sparkctl Compatibility**: Preserved by design; `sparkctl` remains the entry point for compatibility integrations, and `agy-ct` is mapped as a separate, parallel CLI.
19+
- **Phase 6A Scope**: Handbook and planning only; no code implementation is approved.
20+
- **Phase 6B Scope**: Set to setup the binary base shell and the nested `clap` command parser tree only.
21+
- **Evaluation Dependencies**: Libraries such as `dag_exec`, `asupersync`, `wasm_sandbox`, `wasmtime`, `tokio`, and `ratatui` are strictly classified as future/evaluate-only options.
22+
23+
## 3. Claim Hygiene Result
24+
Wording guidelines are followed:
25+
- No claims of being "fully deterministic" are made.
26+
- No claims of being "100% safe" are made.
27+
- No claims of "no risks" are made.
28+
- No statements claiming "official SPARK compatibility" are present.
29+
- No EU AI Act compliance claims are made.
30+
31+
## 4. Safety Boundaries
32+
- Offline behavior was deterministic in the validated test scope.
33+
- Configured leak checks passed in the validated scope.
34+
35+
## 5. Known Limitations
36+
- GitHub Actions status is verified through GitHub UI outside this local rollup.
37+
- `handoff-check` is local repository readiness only and does not verify remote CI.
38+
- No official SPARK compatibility claim is made.
39+
- No compliance claim is made.
40+
41+
## 6. Risks
42+
- No blocking risks found in the validated scope.
43+
44+
## 7. Next Recommended Phase
45+
- Commit Phase 6A architecture handbook and audit snapshot only after approval.

0 commit comments

Comments
 (0)