feat: complete Sparkctl CLI command surface

.agent/skills/00_project_system.md

@@ -4,13 +4,14 @@ This skill defines the repository structure, active directories, permissions, an
 
 ## 1. Operating Boundaries
 
-- **Sandbox Root:** `C:\Users\contr\sandbox_workspace\Antigravity-Comptextv7-unified`
+- **Sandbox Root:** current workspace clone
 - **Allowed Write Paths:**
   - `agy7rust/` (Rust crate)
   - `examples/spark/` (Synthetic SPARK-style fixtures)
   - `artifacts/spark/` (Verification and demo outputs)
   - `.agent/skills/` (Local agent instructions)
-- **Forbidden Paths:** Any parent directory (e.g. `C:\Users\contr`), desktop (`C:\Users\contr\Desktop`), sibling workspaces (e.g., `rustcomptext`), and the `.git` metadata of the system.
+- **Forbidden Paths:** Any parent directory, desktop, sibling workspaces, and the `.git` metadata of the system. Agents must not inspect, modify, copy, move, delete, or index any CompText-related files outside the current workspace clone.
+- **Historical Evidence Paths:** Old Antigravity-Comptextv7 paths, `C:\Users\contr` paths, Termux paths, `git_post_push_verification` paths, and `file:///C:/` links are historical evidence only and must not be used as valid active paths.
 - **Search Boundaries:** Do NOT perform global searches, recursive searches, or file indexing outside the sandbox root.
 
 ## 2. Command Permissions

.agent/skills/05_claim_hygiene.md

@@ -18,5 +18,17 @@ Never write, log, or state the following claims:
 - **SPARK JSON Compatibility:** Do not claim compatibility with official SPARK JSON extractors or schemas.
 - **EU AI Act Compliance:** Do not claim the tool certifies or is compliant with the EU AI Act. Mention only "Art.-12-oriented record keeping support" as a design pattern.
 - **Legal or Judicial Proof:** Do not claim that packages constitute court-admissible evidence, legally binding proofs, or legal validation.
-- **Forensic Certainty:** Avoid terms like "100% forensic security" or "invulnerable tamper resistance". Use "tamper-sensitive validation".
+- **Forensic Certainty & Recovery:** Avoid terms like "100% forensic security", "invulnerable tamper resistance", or automated forensic recovery/repair. Use "tamper-sensitive validation" only.
 - **MCP Integration:** Do not claim MCP capability or server features unless explicitly built in a future phase.
+- **Production Readiness:** The system is a mock prototype only. No production or enterprise setup readiness.
+- **Autonomous Decisions:** The tool does not make autonomous planning or administrative decisions.
+
+## 3. Technology Boundaries (Legacy & Future Exclusions)
+
+The following concepts are legacy/future design ideas only and are **not** supported by the current BMDS/SPARK alignment scope:
+- **XENTRY/OBD Log Engine:** XENTRY X-Engine/OBD X X-Engine log parsing is not supported.
+- **Consonant Signature Mapping:** Consonant-only mapping of XENTRY logs is legacy.
+- **Four-Layer Sandwich Log:** Sandwich formatting (Header/Middle/Window/Frame) is excluded from active claims.
+- **Sparse Micro-Frame Synopsis:** The dot/pipe micro-frame synopsis is a legacy prototype fallback.
+- **Auto-repair/recovery helpers:** No autonomous data repair or error correction is implemented.
+

.agent/skills/11_comptext_validate.md

@@ -26,6 +26,11 @@ Verify each of the following:
 2. **Artifact Existence:** Ensure that `context.json`, `context_render.txt`, and `extraction.spkg` exist in `artifacts/spark/`.
 3. **Render Check:** Verify that the rendered context `context_render.txt` is non-empty and correctly formatted.
 4. **Git Untracked State:** Confirm that the generated latest report `reports/latest.json` remains untracked in git.
+5. **Ledger and Hash Chain Validation:** Verify that `ledger_root` matches the final entry hash in the cryptographic chain.
+6. **Pre-Replay Validation Guardrail:** Ensure that package verification is executed as a prerequisite before running step simulations.
+7. **Failure Label Analysis:** If validation or replay fails, map the error using structured labels:
+   - `EVIDENCE_LOSS`: Critical metadata or tool sequence records are missing.
+   - `CONSTRAINT_DRIFT`: Decoded state commits or hashes diverge from baseline values.
 
 ## 4. Standard Return Format
 

.agents/skills/00_project_system/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: 00_project_system
+description: "Defines the repository structure, active directories, permissions, and operating boundaries for the sandbox environment."
+---
+
+# Agent Skill 00 — Project System
+
+This skill defines the repository structure, active directories, permissions, and operating boundaries for the sandbox environment.
+
+## 1. Operating Boundaries
+
+- **Sandbox Root:** current workspace clone
+- **Allowed Write Paths:**
+  - `agy7rust/` (Rust crate)
+  - `examples/spark/` (Synthetic SPARK-style fixtures)
+  - `artifacts/spark/` (Verification and demo outputs)
+  - `.agents/skills/` and `.agent/skills/` (Local agent instructions)
+- **Forbidden Paths:** Any parent directory, desktop, sibling workspaces, and the `.git` metadata of the system. Agents must not inspect, modify, copy, move, delete, or index any CompText-related files outside the current workspace clone.
+- **Historical Evidence Paths:** Old Antigravity-Comptextv7 paths, `C:\Users\contr` paths, Termux paths, `git_post_push_verification` paths, and `file:///C:/` links are historical evidence only and must not be used as valid active paths.
+- **Search Boundaries:** Do NOT perform global searches, recursive searches, or file indexing outside the sandbox root.
+
+## 2. Command Permissions
+
+- **Cargo Access:** Running `cargo` command actions (`cargo fmt`, `cargo check`, `cargo test`, `cargo clippy`, `cargo run`) is strictly limited to the `agy7rust/` subdirectory.
+- **Git Restrictions:** No git remotes config, git fetch, git pull, or git push commands are permitted.
+- **Network Access:** All network calls and API connections are blocked. The project works entirely offline.
+
+## 3. Standard Return Format
+
+Every completed agent execution step must output the exact formatted block:
+
+```text
+PHASE: <phase_name>
+STATUS: <success | blocked>
+FILES_CHANGED:
+- ...
+COMMANDS_RUN:
+- ...
+TESTS:
+- ...
+RISKS:
+- ...
+NEXT:
+- ...
+```

.agents/skills/01_phase_gate/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: 01_phase_gate
+description: "Defines the sequence gates required to develop, audit, and baseline project phases."
+---
+
+# Agent Skill 01 — Phase-Gate Lifecycle
+
+This skill defines the sequence gates required to develop, audit, and baseline project phases.
+
+## 1. The Phase Loop
+
+For every development phase, the agent must execute the following sequential cycle:
+
+```mermaid
+flowchart TD
+    A["1. Implementation Phase"] --> B["2. Audit/Validation Phase"]
+    B --> C["3. Snapshot/Baseline Phase"]
+    C --> D["Stop & Await User Approval"]
+```
+
+1. **Implementation:** Write logic, format code, and compile tests.
+2. **Audit:** Run verification commands (fmt checks, cargo check, integration tests, clippy checks, determinism, and leak tests) to confirm complete functionality without regression.
+3. **Snapshot:** Write a persistent markdown snapshot file documenting status, file trees, verification outputs, and risks.
+
+## 2. Gate Constraints
+
+- **Never Auto-Advance:** Once a phase snapshot is completed, stop work. Do NOT proceed to implementing the next phase until the user explicitly requests it.
+- **Stop on Unclear Scope:** If requirements are ambiguous, or if any compile/test error persists after three concrete fixing attempts, halt and request design direction from the user.
+- **Execution Statuses:**
+  - `success` — All validation steps pass and the snapshot is successfully written.
+  - `blocked` — An issue prevents verification or the sandbox scope is invalid.

.agents/skills/02_rust_validation/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: 02_rust_validation
+description: "Lists the commands and code audits required to validate the Rust codebase."
+---
+
+# Agent Skill 02 — Rust Validation
+
+This skill lists the commands and code audits required to validate the Rust codebase.
+
+## 1. Quality Gates
+
+Run these commands inside `agy7rust/` in order before submitting:
+
+1. **Formatting:**
+   ```bash
+   cargo fmt --all --check
+   ```
+2. **Compilation:**
+   ```bash
+   cargo check
+   ```
+3. **Tests:**
+   ```bash
+   cargo test
+   ```
+4. **Lints (Warnings as Errors):**
+   ```bash
+   cargo clippy -- -D warnings
+   ```
+5. **Demo Check:**
+   ```bash
+   powershell -File .\demo_spark.ps1
+   ```
+
+## 2. Determinism Validation
+
+To guarantee byte-level determinism, compile packages twice and compare their hashes:
+```bash
+cargo run -- compress -i <input.json> -o determinism_a.spkg
+cargo run -- compress -i <input.json> -o determinism_b.spkg
+# Compare file hashes:
+Get-FileHash determinism_a.spkg
+Get-FileHash determinism_b.spkg
+```
+Both hashes must match identically.
+
+## 3. Code Standards
+
+- **No Unsafe:** Use `#![deny(unsafe_code)]` at crate root.
+- **Robust Error Handling:** Avoid `.unwrap()` and `.expect()` in production code. Return `Result<T>` and bubble up errors cleanly using `anyhow` or custom errors.
+- **No Side-Effects:** No timestamps, UUID generation, random numbers, or environment variables that alter output bytes. All hashes must be completely deterministic.

.agents/skills/03_artifact_validation/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: 03_artifact_validation
+description: "Defines the requirements for generating deterministic packages and validation snapshots."
+---
+
+# Agent Skill 03 — Artifact Validation
+
+This skill defines the requirements for generating deterministic packages and validation snapshots.
+
+## 1. Package Artifact Integrity
+
+- **Stable Key Ordering:** Objects must have keys sorted alphabetically (canonical JSON) before hashing or writing.
+- **No Volatile Elements:** Timestamps, randomized transaction identifiers, and environment-dependent properties are strictly forbidden.
+- **Offline Hashing:** Hash chain calculations must happen locally using standard `sha2` crate. No network APIs or external tokenizers can be queried.
+
+## 2. Snapshot Document Standards
+
+At the completion of each phase, a snapshot file (e.g., `PHASE1_SPARK_SNAPSHOT.md`) must be written containing the following structured sections:
+
+1. **Phase Name & Sandbox Root**
+2. **Created/Modified File Trees** (excluding intermediate build artifacts like `target/`)
+3. **Execution Logs & Command Lists**
+4. **Validation Test Run Status**
+5. **Deterministic Hash Signatures** (from package validation tests)
+6. **Leak Verification Evidence** (for inspect/replay commands)
+7. **Adversarial Tamper Suite Statistics**
+8. **Explicit Non-Claims & Risks**

.agents/skills/04_spark_context_layer/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: 04_spark_context_layer
+description: "Outlines the design concepts for representing compact, replay-safe operational contexts inside SPARK-style packages."
+---
+
+# Agent Skill 04 — SPARK Context Layer
+
+This skill outlines the design concepts for representing compact, replay-safe operational contexts inside SPARK-style packages.
+
+## 1. Core Purpose
+
+The SPARK Context Layer exists to package prior task history and metadata into a minimal, deterministic, and replay-safe payload. It is NOT an orchestration framework or active workflow runner.
+
+## 2. Design Anchors (For Future Integration Only)
+
+When implemented, the context layer must preserve the following metadata blocks:
+- **Causal dependency edges** (e.g. step A must precede step B)
+- **Constraint lists & Blockers**
+- **Recovery paths & Alternative plans**
+- **Schema validation anchors**
+- **Task & Context identifiers**
+
+## 3. Strict Context Constraints (Do NOT Violate)
+
+- **No Active Code Execution:** Do not write execution loops or implement tool runners.
+- **No External Integrations:** Do not connect to LiteLLM, VLLM, database proxies, or outer APIs.
+- **No MCP Server Role:** Do not bundle the library as a Model Context Protocol server.
+- **Strict Leak Rules:**
+  - **No Raw Dumps:** Rendered prompts/contexts must not dump the entire raw payload or trace history.
+  - **Token Hygiene:** Output must be token-light, summarized, and deterministic.

.agents/skills/05_claim_hygiene/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: 05_claim_hygiene
+description: "Defines rules for project documentation and metadata claims to prevent overstatement of security or legal compliance."
+---
+
+# Agent Skill 05 — Claim Hygiene
+
+This skill defines rules for project documentation and metadata claims to prevent overstatement of security or legal compliance.
+
+## 1. Allowed System Claims
+
+You may make the following claims in logs, reports, and documentation:
+- **Synthetic SPARK-Style Fixture:** We operate against static mock datasets representing administrative structures.
+- **Deterministic Packaging:** Packaging code creates identical byte outputs across repeated executions from the same input.
+- **Replayable Metadata:** We extract canonical field paths and commitment tokens.
+- **Tamper-Sensitive Hash Chain:** The package structure incorporates verification chains (payload SHA-256, sidecar final state hash, and package integrity hash).
+- **Schema Sidecar Validation:** The CLI enforces required field presence and scalar types on input JSON templates.
+- **Deterministic Replay Only:** The tool is designed exclusively for offline package packaging, verification, and schema checks; it does not perform active runtime execution, predictions, or online agent coordination.
+
+## 2. Forbidden Claims (Strictly Prohibited)
+
+Never write, log, or state the following claims:
+- **SPARK JSON Compatibility:** Do not claim compatibility with official SPARK JSON extractors or schemas.
+- **EU AI Act Compliance:** Do not claim the tool certifies or is compliant with the EU AI Act. Mention only "Art.-12-oriented record keeping support" as a design pattern.
+- **Legal or Judicial Proof:** Do not claim that packages constitute court-admissible evidence, legally binding proofs, or legal validation.
+- **Forensic Certainty & Recovery:** Avoid terms like "100% forensic security", "invulnerable tamper resistance", or automated forensic recovery/repair. Use "tamper-sensitive validation" only.
+- **MCP Integration:** Do not claim MCP capability or server features unless explicitly built in a future phase.
+- **Production Readiness:** The system is a mock prototype only. No production or enterprise setup readiness.
+- **Autonomous Decisions:** The tool does not make autonomous planning or administrative decisions.
+
+## 3. Technology Boundaries (Legacy & Future Exclusions)
+
+The following concepts are legacy/future design ideas only and are **not** supported by the current BMDS/SPARK alignment scope:
+- **XENTRY/OBD Log Engine:** XENTRY X-Engine/OBD X X-Engine log parsing is not supported.
+- **Consonant Signature Mapping:** Consonant-only mapping of XENTRY logs is legacy.
+- **Four-Layer Sandwich Log:** Sandwich formatting (Header/Middle/Window/Frame) is excluded from active claims.
+- **Sparse Micro-Frame Synopsis:** The dot/pipe micro-frame synopsis is a legacy prototype fallback.
+- **Auto-repair/recovery helpers:** No autonomous data repair or error correction is implemented.
+

.agents/skills/06_git_handoff/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: 06_git_handoff
+description: "Outlines guidelines for staging, committing, and handoff actions."
+---
+
+# Agent Skill 06 — Git Handoff
+
+This skill outlines guidelines for staging, committing, and handoff actions.
+
+## 1. Operating Rules (Requires Explicit User Approval)
+
+- **No Auto-Git Actions:** Do not perform git init, add, commit, push, checkout, pull, or merge unless explicitly requested.
+- **Stage Allowed Paths Only:** If staging changes, add only the files belonging to the active phase scope. Do NOT run wildcard stages (e.g. `git add .` or `git add -A`) to avoid staging build target outputs or untracked local test files.
+- **Dry-Run Review:** List all files to be staged for staging verification before committing:
+  ```bash
+  git status --short
+  ```
+- **Safety Boundaries:**
+  - Never run force push (`git push -f` or `git push --force`).
+  - Do not delete branches or rewrite commit history unless instructed.
+
+## 2. Pull Request Template
+
+When describing work for PRs or commits, use the template below:
+```text
+feat(<scope>): SPARK Hackathon <phase_name>
+
+Summary:
+- Brief bulleted list of changes
+
+Validation:
+- Test suite status
+- Clippy and cargo format checks
+```

.agents/skills/07_cli_surface/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: 07_cli_surface
+description: "Defines strict subcommand taxonomy and command surface rules for the agy-ct CLI."
+---
+
+# Skill 07: agy-ct CLI Surface Rules
+
+## 1. CLI Subcommand Taxonomy
+`agy-ct` must implement the following subcommand structure exactly:
+- `run`
+- `demo`
+- `doctor`
+- `validate`
+- `handoff`
+- `package`
+  - `compress`
+  - `inspect`
+  - `verify`
+  - `replay`
+  - `adversarial`
+- `context`
+  - `build`
+  - `render`
+  - `validate`
+  - `all`
+- `schema check`
+- `report export`
+- `notebook bundle`
+
+## 2. Clap Parser Behavior
+- Subcommands must be defined using strict typed options inside Rust's `clap` crate.
+- Command-line parsing must enforce correct parameter names, required arguments, and mutually exclusive options at the parser level.
+- Clean `-h` and `--help` pages must be auto-generated for each command and subcommand.
+
+## 3. Phase 6B-6E Execution Orchestrator Implementation
+- `agy-ct run` is implemented as a local automatic workflow orchestrator. It executes the following stages in order:
+  1. workspace doctor (`sparkctl::doctor::run_doctor()`)
+  2. context pipeline (`sparkctl::context_all::run_context_all()`)
+  3. spark demo (`sparkctl::spark_demo::run_spark_demo()`)
+  4. handoff check (`sparkctl::handoff_check::run_handoff_check()`)
+- `agy-ct run` creates or overwrites `reports/latest.json` containing stage-level status reports and artifact mappings.
+- The `reports/latest.json` is a generated local runtime file and must remain untracked by default.
+
+## 4. Preservation of sparkctl
+- Under no circumstances should implementation changes to `agy-ct` alter or break any existing command surface or execution behavior of the compatibility CLI binary `sparkctl`.
+- Codebase refactoring must maintain backward compatibility.