From 002d5682a3c1155bcf08f505f231f087840b5f06 Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Tue, 9 Jun 2026 19:37:52 +0200 Subject: [PATCH 01/27] docs: harden Spark hackathon governance - documents synthetic-only SPARK hackathon boundaries - adds replay failure labels EVIDENCE_LOSS and CONSTRAINT_DRIFT - documents canonical JSON, ledger/hash chain checks, and verify-before-replay - marks XENTRY/OBD and legacy compression concepts as future-only exclusions - removes hardcoded legacy local path assumptions from active governance docs - Rust validation not run due Windows NUL ACL executor issue; no Rust source changed --- .agent/skills/00_project_system.md | 5 +- .agent/skills/05_claim_hygiene.md | 14 ++++- .agent/skills/11_comptext_validate.md | 5 ++ .antigravitycli/settings.example.json | 23 +++++++ .gitignore | 1 + DEMO_SPARK_EVIDENCE.md | 18 +++--- README.md | 4 +- docs/REPLAY_FAILURE_LABELS.md | 46 ++++++++++++++ docs/SPARK_ALIGNMENT.md | 15 ++++- docs/SPARK_HACKATHON_SETUP.md | 89 +++++++++++++++++++++++++++ 10 files changed, 204 insertions(+), 16 deletions(-) create mode 100644 .antigravitycli/settings.example.json create mode 100644 docs/REPLAY_FAILURE_LABELS.md create mode 100644 docs/SPARK_HACKATHON_SETUP.md diff --git a/.agent/skills/00_project_system.md b/.agent/skills/00_project_system.md index 24a9382..792e844 100644 --- a/.agent/skills/00_project_system.md +++ b/.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 diff --git a/.agent/skills/05_claim_hygiene.md b/.agent/skills/05_claim_hygiene.md index 65bf126..d7c55d7 100644 --- a/.agent/skills/05_claim_hygiene.md +++ b/.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. + diff --git a/.agent/skills/11_comptext_validate.md b/.agent/skills/11_comptext_validate.md index 5534207..c795a28 100644 --- a/.agent/skills/11_comptext_validate.md +++ b/.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 diff --git a/.antigravitycli/settings.example.json b/.antigravitycli/settings.example.json new file mode 100644 index 0000000..fbc3f42 --- /dev/null +++ b/.antigravitycli/settings.example.json @@ -0,0 +1,23 @@ +{ + "governance": { + "rules": [ + "Operate only inside the current workspace clone.", + "Request human review before making any file edits.", + "No network access by default. Run completely offline.", + "No secret reads (do not read .env, credentials, SSH keys).", + "No git writes (do not commit, push, pull, or create remote branches).", + "Do not use or process real citizen/admin case data.", + "Operate exclusively on synthetic mock fixtures.", + "Do not make legal, compliance, production-readiness, or official SPARK compatibility claims.", + "Cargo commands must be executed only inside the agy7rust/ subdirectory." + ], + "sandbox": { + "offline": true, + "read_only_git": true + } + }, + "review": { + "boundary": "human_review", + "require_approval_before_patch": true + } +} diff --git a/.gitignore b/.gitignore index e8697b6..c2de2b8 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ reports/performance_baseline.json artifacts/spark/ __pycache__/ *.pyc +.antigravitycli/workspace_config.json diff --git a/DEMO_SPARK_EVIDENCE.md b/DEMO_SPARK_EVIDENCE.md index 7a3ac5a..2afc4d0 100644 --- a/DEMO_SPARK_EVIDENCE.md +++ b/DEMO_SPARK_EVIDENCE.md @@ -25,17 +25,17 @@ CompText-Sparkctl turns extraction and context artifacts into a local validation The workspace organizes generated and static artifacts across the following paths: -- [artifacts/spark/extraction.spkg](file:///C:/Users/contr/sandbox_workspace/Antigravity-Comptextv7-unified/git_post_push_verification/repo/artifacts/spark/extraction.spkg) — Binary SPARK-style compressed package. -- [artifacts/spark/context.json](file:///C:/Users/contr/sandbox_workspace/Antigravity-Comptextv7-unified/git_post_push_verification/repo/artifacts/spark/context.json) — JSON operational context layout. -- [artifacts/spark/context_render.txt](file:///C:/Users/contr/sandbox_workspace/Antigravity-Comptextv7-unified/git_post_push_verification/repo/artifacts/spark/context_render.txt) — Rendered text overview of the context layers. -- [reports/latest.json](file:///C:/Users/contr/sandbox_workspace/Antigravity-Comptextv7-unified/git_post_push_verification/repo/reports/latest.json) — Local orchestrator step run log (untracked). -- [reports/performance_baseline.json](file:///C:/Users/contr/sandbox_workspace/Antigravity-Comptextv7-unified/git_post_push_verification/repo/reports/performance_baseline.json) — Recorded local execution baseline timings. +- [artifacts/spark/extraction.spkg](artifacts/spark/extraction.spkg) — Binary SPARK-style compressed package. +- [artifacts/spark/context.json](artifacts/spark/context.json) — JSON operational context layout. +- [artifacts/spark/context_render.txt](artifacts/spark/context_render.txt) — Rendered text overview of the context layers. +- [reports/latest.json](reports/latest.json) — Local orchestrator step run log (untracked). +- [reports/performance_baseline.json](reports/performance_baseline.json) — Recorded local execution baseline timings. ## 6. Expected Reviewer Path Reviewers are recommended to follow these verification steps: -1. **Inspect README.md:** Read the core design specifications and command mappings in [README.md](file:///C:/Users/contr/sandbox_workspace/Antigravity-Comptextv7-unified/git_post_push_verification/repo/README.md). +1. **Inspect README.md:** Read the core design specifications and command mappings in [README.md](README.md). 2. **Execute Orchestrator:** Run the main pipeline orchestrator: ```bash cargo run --bin agy-ct -- run @@ -44,9 +44,9 @@ Reviewers are recommended to follow these verification steps: ```bash python -m json.tool ../reports/latest.json ``` -4. **Inspect Context Layout:** Verify the generated model structure in [context.json](file:///C:/Users/contr/sandbox_workspace/Antigravity-Comptextv7-unified/git_post_push_verification/repo/artifacts/spark/context.json). -5. **Inspect Render Output:** Open [context_render.txt](file:///C:/Users/contr/sandbox_workspace/Antigravity-Comptextv7-unified/git_post_push_verification/repo/artifacts/spark/context_render.txt) to see the printed text log. -6. **Inspect Performance Baseline:** Read [PERFORMANCE_BASELINE.md](file:///C:/Users/contr/sandbox_workspace/Antigravity-Comptextv7-unified/git_post_push_verification/repo/PERFORMANCE_BASELINE.md) to compare timings. +4. **Inspect Context Layout:** Verify the generated model structure in [context.json](artifacts/spark/context.json). +5. **Inspect Render Output:** Open [context_render.txt](artifacts/spark/context_render.txt) to see the printed text log. +6. **Inspect Performance Baseline:** Read [PERFORMANCE_BASELINE.md](PERFORMANCE_BASELINE.md) to compare timings. ## 7. Exact Commands for Reviewers diff --git a/README.md b/README.md index 0ea6c6f..b8067ec 100644 --- a/README.md +++ b/README.md @@ -108,8 +108,8 @@ These artifacts are intended for local, reproducible validation and review workf ### Demo Evidence Demo evidence: -- SPARK challenge demo evidence: [DEMO_SPARK_EVIDENCE.md](file:///C:/Users/contr/sandbox_workspace/Antigravity-Comptextv7-unified/git_post_push_verification/repo/DEMO_SPARK_EVIDENCE.md) -- Local performance baseline: [PERFORMANCE_BASELINE.md](file:///C:/Users/contr/sandbox_workspace/Antigravity-Comptextv7-unified/git_post_push_verification/repo/PERFORMANCE_BASELINE.md) +- SPARK challenge demo evidence: [DEMO_SPARK_EVIDENCE.md](DEMO_SPARK_EVIDENCE.md) +- Local performance baseline: [PERFORMANCE_BASELINE.md](PERFORMANCE_BASELINE.md) #### Reviewer Quickstart diff --git a/docs/REPLAY_FAILURE_LABELS.md b/docs/REPLAY_FAILURE_LABELS.md new file mode 100644 index 0000000..8f0310f --- /dev/null +++ b/docs/REPLAY_FAILURE_LABELS.md @@ -0,0 +1,46 @@ +# SPARK Replay Failure Labels and Verification Standards + +This document defines the structured failure labels, ledger validation criteria, and cryptographic verification policies implemented within the `CompText-Sparkctl` toolkit for the BMDS SPARK Hackathon. + +## 1. Replay Failure Labels + +During trace validation or package replay operations, any error or schema mismatch is mapped to one of the following structured failure labels: + +### EVIDENCE_LOSS +* **Definition:** Critical payload elements, metadata, or step-sequence logs are missing or stripped. +* **Indicators:** Expected JSON fields are absent, the artifact manifest is missing entries, or the tool sequence chain is broken. + +### CONSTRAINT_DRIFT +* **Definition:** Decoded values, commitments, or state hashes diverge from their initial baseline configuration. +* **Indicators:** Mismatch in the payload SHA-256 hash, key-ordering changes, or mismatch in the cryptographic signatures. + +## 2. Ledger and Hash Chain Validation + +To guarantee forensic auditability without live environment dependencies, the system enforces a strict cryptographic chain check: +1. **Entry Chaining:** Each ledger entry in the evidence package contains a `previous_hash` field that must match the `entry_hash` of the preceding entry. +2. **Root Anchoring:** The `ledger_root` field of the overall package envelope must equal the `entry_hash` of the final ledger transaction. +3. **Payload Mapping:** The `payload_hash` in the sidecar must match the SHA-256 checksum of the decoded payload. + +## 3. Canonical JSON & Stable Serialization + +To prevent environment-dependent hash drift (e.g. from key ordering in dictionaries or array whitespace variations), all hashes are computed over **Canonical JSON**: +* Keys must be recursively sorted in ascending ASCII order. +* Whitespace between tokens is completely stripped during canonical representation compilation. + +## 4. Pre-Replay Validation Guardrail + +To maintain strict execution safety: +* A package **must** successfully pass cryptographic signature checks (`verify_package_value`) before the step-simulation runner is allowed to parse and execute replay steps. +* Any verification failure halts the execution immediately and blocks replay. + +## 5. Synthetic-Only SPARK Evidence Boundary + +The verification and planning pipeline operates strictly inside a mock boundary: +* All input fixtures contain strictly synthetic planning data. +* The system must not process real citizen, administrator, or live public-sector case files. + +## 6. Safety Exclusions + +The current `CompText-Sparkctl` alignment scope excludes the following capabilities: +* **No Autonomous Recovery or Repair:** The system is strictly diagnostic and records evidence; it does not perform automated data repair. +* **Legacy Log Sandbox Exclusions:** Domain-specific XENTRY/OBD log X-Engines, consonant signatures, sparse micro-frame synopses, and the four-layer sandwich log parser are legacy design prototypes only and must not be asserted as active SPARK alignment features. diff --git a/docs/SPARK_ALIGNMENT.md b/docs/SPARK_ALIGNMENT.md index 696b80d..5f80d8c 100644 --- a/docs/SPARK_ALIGNMENT.md +++ b/docs/SPARK_ALIGNMENT.md @@ -25,6 +25,17 @@ The SPARK Evidence Packet v1 demo records a reviewable trail with: ## Boundaries -The packet does not replace human review. Provider output remains untrusted until reviewed, and the goal does not bypass the Policy Gate or authorize auto-apply behavior. +The packet does not replace human review. Provider output remains untrusted until reviewed, and the goal does not bypass the Policy Gate or authorize auto-apply behavior. All planning workflows terminate at a mandatory human-in-the-loop review boundary. + +The demo is local, offline, and bounded. It makes no provider calls and operates exclusively against synthetic/mock fixtures. It does not process real citizen or administrative case data. + +We explicitly do **not** claim: +- production readiness or enterprise setup deployment +- regulatory compliance certification (such as the EU AI Act) +- legal or judicial proof admissibility +- official SPARK schema compatibility or compliance +- autonomous administrative decisions or approval +- data repair, recovery, or forensic certainty helpers + +Legacy / future concepts such as XENTRY/OBD log sandwich models, consonant signature mapping, sparse micro-frame synopsis, and error correction layers are completely excluded from the active SPARK alignment scope. -The demo is local and bounded. It makes no provider calls and does not claim production readiness, compliance certification, legal validation, forensic proof, guaranteed correctness, or certified government use. diff --git a/docs/SPARK_HACKATHON_SETUP.md b/docs/SPARK_HACKATHON_SETUP.md new file mode 100644 index 0000000..3e4d6d4 --- /dev/null +++ b/docs/SPARK_HACKATHON_SETUP.md @@ -0,0 +1,89 @@ +# SPARK Hackathon Setup and Governance Guidelines + +This document outlines the local setup, operating boundaries, and validation guidelines for compiling and testing the `CompText-Sparkctl` codebase within the BMDS SPARK Hackathon alignment context. + +## 1. Purpose + +The purpose of this alignment setup is to ensure that development work is conducted in a verifiable, offline, and review-safe local sandbox. This setup coordinates planning context verification and trace metadata packaging without introducing external network side-effects or autonomous governance risks. + +## 2. Sandbox Clone Instructions (Windows PowerShell) + +To initialize and setup the sandbox workspace locally on Windows, execute the following commands in PowerShell: + +```powershell +# Navigate to your local development workspace directory +cd "$HOME\development" + +# Clone the repository locally +git clone https://github.com/ProfRandom92/comptext-sparkctl.git +cd comptext-sparkctl + +# Verify that the local directory structure matches the expected repository map +ls +``` + +## 3. Antigravity Launch Steps + +When launching an Antigravity agent session inside the clone: +1. Ensure the workspace settings are loaded from `.antigravitycli/settings.example.json`. +2. Write any local environment mappings exclusively to `.antigravitycli/workspace_config.json` (this file is git-ignored). +3. Confirm that the agent remains in **read-only git mode** and **offline mode**. + +## 4. Command Boundaries + +All command execution must strictly respect the repository policy limits: + +### Safe Commands +These local validation commands can be run at any time inside the `agy7rust/` subdirectory to check code syntax and correctness: +* `cd agy7rust` +* `cargo fmt --all --check` +* `cargo check` +* `cargo test` +* `cargo clippy -- -D warnings` +* `cargo run --bin agy-ct -- --help` +* `cargo run --bin sparkctl -- --help` + +### Review-Required Commands (Artifact/Evidence Generation) +These commands modify the local filesystem, generate planning context models, or compile run summaries. They require explicit human approval and should not be run automatically: +* `cargo run --bin agy-ct -- doctor` / `cargo run --bin sparkctl -- doctor` +* `cargo run --bin agy-ct -- validate` / `cargo run --bin sparkctl -- rust-validate` +* `cargo run --bin agy-ct -- context all` / `cargo run --bin sparkctl -- context-all` +* `cargo run --bin agy-ct -- demo` / `cargo run --bin sparkctl -- spark-demo` +* `cargo run --bin agy-ct -- handoff` / `cargo run --bin sparkctl -- handoff-check` +* `cargo run --bin sparkctl -- spark-evidence-demo --output ` +* `cargo run --bin sparkctl -- spark-evidence-validate --input ` + +### Denied Commands +The following operations are strictly forbidden in this workspace and are blocked by hooks: +* `cargo run --bin agy-ct -- run` (restricted to prevent untracked report modifications) +* `cargo run --bin agy-ct -- benchmark` (restricted to prevent performance baseline drift) +* Any git mutating commands (`git commit`, `git push`, `git pull`, `git fetch`, `git merge`, `git rebase`, `git tag`) +* Any GitHub CLI write commands (`gh pr`, `gh issue`, `gh release`) +* Environment dumps (`env`, `printenv`, `Get-ChildItem env:`) +* Reading secrets or keys (`.env`, credentials, SSH files) +* Web server deployments (`vercel`, `netlify`, `wrangler deploy`, etc.) + +## 5. Validation Plan + +To validate the code offline, run the safe local check suite: +1. Run `cargo fmt --all --check` to verify code style formatting. +2. Run `cargo check` to verify compilation. +3. Run `cargo test` to execute the integration and unit tests. +4. Run `cargo clippy -- -D warnings` to enforce linter compliance. + +Do not run `agy-ct run`, `agy-ct demo`, or `agy-ct benchmark` unless the final reports and artifacts are specifically requested for human review. + +## 6. Synthetic-Data-Only Rule + +All planning modules, extractors, and validators operate exclusively against static mock datasets (e.g. `examples/spark/extraction.json`). Processing of real citizen, administrator, or live public-sector cases is strictly prohibited. + +## 7. Safety Non-Claims & Technology Exclusions + +The `CompText-Sparkctl` workflow enforces the following non-claims and exclusions: +* **No Official SPARK Schema Compatibility:** All SPARK-oriented terminology is conceptual mock-up and synthetic schema alignment. +* **No EU AI Act Compliance Certification:** The toolkit serves as design support for record-keeping patterns only; it does not constitute certification or compliance. +* **No Legal or Judicial Proof:** Generated evidence packages do not replace official review, and have no forensic or judicial admissibility. +* **No Autonomous Approval:** System outputs are strictly untrusted proposals. All planning workflows terminate at a mandatory human-in-the-loop review boundary. +* **No Repair or Forensic Recovery:** The tool does not perform autonomous data recovery, error correction, or assert forensic certainty. +* **Legacy Exclusions:** Domain-specific concepts like XENTRY/OBD log X-Engines, consonant signatures, sparse micro-frame synopses, and the four-layer sandwich log parser are future/legacy design prototypes only and are not part of the active SPARK alignment claims. + From 88e9e863e942b1d739b0f9999de85241b88f004b Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Tue, 9 Jun 2026 22:47:09 +0200 Subject: [PATCH 02/27] docs: add Antigravity workspace skills --- .agents/skills/00_project_system/SKILL.md | 45 +++++ .agents/skills/01_phase_gate/SKILL.md | 31 +++ .agents/skills/02_rust_validation/SKILL.md | 51 +++++ .../skills/03_artifact_validation/SKILL.md | 27 +++ .../skills/04_spark_context_layer/SKILL.md | 30 +++ .agents/skills/05_claim_hygiene/SKILL.md | 39 ++++ .agents/skills/06_git_handoff/SKILL.md | 34 ++++ .agents/skills/07_cli_surface/SKILL.md | 46 +++++ .../08_agentic_output_contract/SKILL.md | 35 ++++ .../09_codex_desktop_governance/SKILL.md | 48 +++++ .../09_phase6_implementation_gate/SKILL.md | 25 +++ .../10_generated_artifact_policy/SKILL.md | 30 +++ .../skills/10_spark_evidence_review/SKILL.md | 44 +++++ .agents/skills/11_comptext_validate/SKILL.md | 48 +++++ .../skills/12_agent_handoff_profile/SKILL.md | 46 +++++ .agents/skills/codex-role-workflows/SKILL.md | 149 +++++++------- .agents/skills/codex-token-saving/SKILL.md | 93 ++++----- .agents/skills/comptext-governance/SKILL.md | 119 +++++------ .../skills/pdf-extraction-contracts/SKILL.md | 187 +++++++++--------- .agents/skills/reviewer-final-report/SKILL.md | 59 +++--- .../skills/rust-canonical-artifacts/SKILL.md | 77 ++++---- .../security-readonly-boundaries/SKILL.md | 89 +++++---- .../skills/spark-hackathon-alignment/SKILL.md | 75 +++---- .../skills/sparkctl-evidence-packet/SKILL.md | 131 ++++++------ AGENTS.md | 4 +- 25 files changed, 1093 insertions(+), 469 deletions(-) create mode 100644 .agents/skills/00_project_system/SKILL.md create mode 100644 .agents/skills/01_phase_gate/SKILL.md create mode 100644 .agents/skills/02_rust_validation/SKILL.md create mode 100644 .agents/skills/03_artifact_validation/SKILL.md create mode 100644 .agents/skills/04_spark_context_layer/SKILL.md create mode 100644 .agents/skills/05_claim_hygiene/SKILL.md create mode 100644 .agents/skills/06_git_handoff/SKILL.md create mode 100644 .agents/skills/07_cli_surface/SKILL.md create mode 100644 .agents/skills/08_agentic_output_contract/SKILL.md create mode 100644 .agents/skills/09_codex_desktop_governance/SKILL.md create mode 100644 .agents/skills/09_phase6_implementation_gate/SKILL.md create mode 100644 .agents/skills/10_generated_artifact_policy/SKILL.md create mode 100644 .agents/skills/10_spark_evidence_review/SKILL.md create mode 100644 .agents/skills/11_comptext_validate/SKILL.md create mode 100644 .agents/skills/12_agent_handoff_profile/SKILL.md diff --git a/.agents/skills/00_project_system/SKILL.md b/.agents/skills/00_project_system/SKILL.md new file mode 100644 index 0000000..0b4287e --- /dev/null +++ b/.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: +STATUS: +FILES_CHANGED: +- ... +COMMANDS_RUN: +- ... +TESTS: +- ... +RISKS: +- ... +NEXT: +- ... +``` diff --git a/.agents/skills/01_phase_gate/SKILL.md b/.agents/skills/01_phase_gate/SKILL.md new file mode 100644 index 0000000..6dc9548 --- /dev/null +++ b/.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. diff --git a/.agents/skills/02_rust_validation/SKILL.md b/.agents/skills/02_rust_validation/SKILL.md new file mode 100644 index 0000000..12d354e --- /dev/null +++ b/.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 -o determinism_a.spkg +cargo run -- compress -i -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` 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. diff --git a/.agents/skills/03_artifact_validation/SKILL.md b/.agents/skills/03_artifact_validation/SKILL.md new file mode 100644 index 0000000..0f3028c --- /dev/null +++ b/.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** diff --git a/.agents/skills/04_spark_context_layer/SKILL.md b/.agents/skills/04_spark_context_layer/SKILL.md new file mode 100644 index 0000000..d15d2e5 --- /dev/null +++ b/.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. diff --git a/.agents/skills/05_claim_hygiene/SKILL.md b/.agents/skills/05_claim_hygiene/SKILL.md new file mode 100644 index 0000000..125055b --- /dev/null +++ b/.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. + diff --git a/.agents/skills/06_git_handoff/SKILL.md b/.agents/skills/06_git_handoff/SKILL.md new file mode 100644 index 0000000..da92d91 --- /dev/null +++ b/.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(): SPARK Hackathon + +Summary: +- Brief bulleted list of changes + +Validation: +- Test suite status +- Clippy and cargo format checks +``` diff --git a/.agents/skills/07_cli_surface/SKILL.md b/.agents/skills/07_cli_surface/SKILL.md new file mode 100644 index 0000000..c7d2434 --- /dev/null +++ b/.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. diff --git a/.agents/skills/08_agentic_output_contract/SKILL.md b/.agents/skills/08_agentic_output_contract/SKILL.md new file mode 100644 index 0000000..4a35a12 --- /dev/null +++ b/.agents/skills/08_agentic_output_contract/SKILL.md @@ -0,0 +1,35 @@ +--- +name: 08_agentic_output_contract +description: "Defines stdout/stderr separation, structured JSON outputs, quiet configurations, and exit codes." +--- + +# Skill 08: Agentic Output Contract + +## 1. Stdout and Stderr Separation +To facilitate automation and downstream piping by software agents: +- **stdout** is strictly reserved for machine-readable payloads, exported file contents, and structured JSON logs. +- **stderr** is used for interactive human-facing indicators, warnings, logs, diagnostics, and CLI title blocks. + +## 2. Structured JSON Output +- When running with `--json` or `--output json`, all command-line outputs, errors, and run steps must be serialized into structured JSON objects on stdout. +- Any output sent to stdout under JSON mode must validate against the target JSON schema. +- `agy-ct run` generates a structured report at `reports/latest.json` mapping indices, stages, status, and generated SPARK context artifacts. +- Generated `reports/latest.json` is a local runtime artifact and must not be committed to git. +- No official SPARK compatibility, production readiness, or EU AI Act compliance claims are made. + +## 3. Quiet and Plain Configurations +- Under `--plain` or `--json` or `--non-interactive` flags, no ANSI formatting escape codes, progressive spinners, interactive loading lines, or ticker indicators may be printed to stdout or stderr. +- Terminal outputs must remain static and flat in these modes. + +## 4. Exit Codes and Compact Error Model +- The binary must propagate specific exit codes on validation failures: + - `0`: Complete success. + - `1`: Unexpected execution error. + - `2`: Validation integrity or leak check failure. + - `3`: Missing configuration files or schema files. + - `4`: Invalid file structure or signature. +- Error outputs must be compact (single-line text) by default. Detailed traces can be requested via `--explain ` or `--verbose`. +- In non-interactive mode, if input is required, the execution must abort immediately and exit with a non-zero code. + +## 5. Security and Leak Limits +- Access keys, environment secrets, and sensitive tokens must never be written to JSON reports, stdout, or stderr logs. diff --git a/.agents/skills/09_codex_desktop_governance/SKILL.md b/.agents/skills/09_codex_desktop_governance/SKILL.md new file mode 100644 index 0000000..0a213ca --- /dev/null +++ b/.agents/skills/09_codex_desktop_governance/SKILL.md @@ -0,0 +1,48 @@ +--- +name: 09_codex_desktop_governance +description: "Documents the repo-local Codex Desktop guardrail layer for this worktree." +--- + +# Agent Skill 09 - Codex Desktop Governance + +This skill documents the repo-local Codex Desktop guardrail layer for this worktree. + +## Scope + +- Hooks are project-local under `.codex/` and require Codex hook trust before they run. +- The layer is a guardrail, not a complete security boundary. +- GitHub remains read-only unless a human explicitly authorizes otherwise. +- Provider output remains untrusted until human review. + +## Allowed Local Commands + +Run Rust validation only from `agy7rust/`: + +- `cargo fmt --all --check` +- `cargo check` +- `cargo test` +- `cargo clippy -- -D warnings` +- `cargo run --bin agy-ct -- --help` + +Normal repo-local reads and searches are allowed. Do not read secrets, token stores, credential files, or `.env` files. + +## Blocked Operations + +The pre-tool hook blocks: + +- `git commit`, `git push`, `git pull`, `git merge`, `git rebase`, `git tag`, and `git fetch` +- GitHub PR, issue, and release write commands +- deploy and release-oriented commands +- environment dumps such as `env`, `printenv`, and `Get-ChildItem Env:` +- `.env`, credential, SSH key, and secret file reads +- `agy-ct run` and `agy-ct benchmark` + +## Warnings + +The hook layer warns on references to protected documentation, source, and generated artifact paths: + +- `README.md` +- `agy7rust/src/` +- `reports/latest.json` +- `reports/performance_baseline.json` +- `artifacts/spark/` diff --git a/.agents/skills/09_phase6_implementation_gate/SKILL.md b/.agents/skills/09_phase6_implementation_gate/SKILL.md new file mode 100644 index 0000000..d01fde3 --- /dev/null +++ b/.agents/skills/09_phase6_implementation_gate/SKILL.md @@ -0,0 +1,25 @@ +--- +name: 09_phase6_implementation_gate +description: "Defines the phased execution roadmap, dependency restrictions, and safety bounds for Phase 6." +--- + +# Skill 09: Phase 6 Implementation Gates + +## 1. Phased Execution Roadmap +No cross-phase implementations are allowed. Development must follow these strict gates: +- **Phase 6B**: `agy-ct` binary configuration and `clap` tree definition (Complete). +- **Phase 6C**: Compatibility wrappers mapping `doctor`, `validate`, `handoff`, `demo`, and `context all` (Complete). +- **Phase 6D**: Automatic `agy-ct run` orchestrator sequencing doctor, context pipeline, demo, and handoff checks (Complete). +- **Phase 6E**: Execution JSON report exporter writing to `reports/latest.json` (Complete). +- **Phase 6F**: Context cache valve functionality and optional NotebookLM source bundle exporter (Future / Optional). +- **Performance Baseline & Hardening**: Baseline validation benchmarks and downstream event loop execution (Future work). + +## 2. Dependency Restriction +- The installation of heavy or complex libraries (`dag_exec`, `asupersync`, `wasm_sandbox`, `wasmtime`, `tokio`, `ratatui`) is deferred for future phases. +- No new packages or dependencies may be registered in `Cargo.toml` without explicit phase-gate approval. + +## 3. Safety and Sandbox Bounds +- **Offline Operations**: By default, no subcommands may access the network. +- **Git Safety**: CLI commands must never run git commits or push operations. +- **No Destructive Overwrites**: Commands must prompt before overwriting files unless overridden by `--non-interactive` or `--force`. +- **Directory Bounds**: Commands must restrict all scans to the workspace directory. No parent or sibling directory searches are permitted. diff --git a/.agents/skills/10_generated_artifact_policy/SKILL.md b/.agents/skills/10_generated_artifact_policy/SKILL.md new file mode 100644 index 0000000..a900ffd --- /dev/null +++ b/.agents/skills/10_generated_artifact_policy/SKILL.md @@ -0,0 +1,30 @@ +--- +name: 10_generated_artifact_policy +description: "Records how Codex sessions should handle generated CompText artifacts." +--- + +# Agent Skill 10 - Generated Artifact Policy + +This skill records how Codex sessions should handle generated CompText artifacts. + +## Non-Commit Defaults + +Generated runtime files are not automatically commit candidates: + +- `reports/latest.json` +- `reports/performance_baseline.json` +- `artifacts/spark/*` +- Rust `target/` outputs + +Do not stage or commit generated reports unless the human explicitly approves the exact files. + +## Artifact Hygiene + +- Prefer validation commands that do not regenerate reports when the task does not require new artifacts. +- Do not run `agy-ct run` or `agy-ct benchmark` during governance-only work. +- Treat generated artifacts as evidence trail material, not source-of-truth implementation. +- Preserve deterministic and replayable outputs; do not fake hashes or rewrite reports to satisfy a claim. + +## Claim Hygiene + +Generated reports and handoff text may describe local validation results, deterministic packaging behavior, and tamper-sensitive checks when evidenced by commands. They must not claim production readiness, legal proof, forensic certainty, EU AI Act compliance, official SPARK compatibility, or autonomous approval. diff --git a/.agents/skills/10_spark_evidence_review/SKILL.md b/.agents/skills/10_spark_evidence_review/SKILL.md new file mode 100644 index 0000000..75206b9 --- /dev/null +++ b/.agents/skills/10_spark_evidence_review/SKILL.md @@ -0,0 +1,44 @@ +--- +name: 10_spark_evidence_review +description: "Defines the requirements and checklist for reviewing the README-linked demo evidence and local baseline artifacts." +--- + +# Agent Skill 10 — SPARK Evidence Review + +This skill defines the requirements and checklist for reviewing the README-linked demo evidence and local baseline artifacts of the CompText-Sparkctl toolkit. + +## 1. Input Files + +The reviewer path verifies the presence of the following files: +- `README.md` +- `DEMO_SPARK_EVIDENCE.md` +- `PERFORMANCE_BASELINE.md` +- `reports/performance_baseline.json` +- `artifacts/spark/context.json` +- `artifacts/spark/context_render.txt` + +## 2. Review Commands + +Reviewers should execute and inspect the output of these commands inside `agy7rust/`: +- `cargo run --bin agy-ct -- run` +- `python -m json.tool ../reports/latest.json` +- `python -m json.tool ../reports/performance_baseline.json` + +## 3. Checklist + +Verify each of the following: +1. **File Presence:** Ensure all input files exist at their expected locations under the workspace directory. +2. **JSON Parsability:** Run `python -m json.tool` on the JSON reports to guarantee they are correctly structured. +3. **Reviewer Path Clarity:** Confirm that `README.md` contains clear links to the demo evidence documents, and the reviewer path is easy to follow. +4. **Claim Hygiene:** Ensure all documents strictly avoid prohibited assertions (such as official specification compatibility, production/enterprise setup readiness, and regulatory certifications). + +## 4. Standard Return Format + +The results of this review must be reported using the following format: +- `STATUS: ` +- `EVIDENCE_FILES: ` +- `COMMANDS_CHECKED: ` +- `CLAIM_HYGIENE: ` +- `REVIEWER_SUMMARY: ` +- `RISKS: ` +- `NEXT: ` diff --git a/.agents/skills/11_comptext_validate/SKILL.md b/.agents/skills/11_comptext_validate/SKILL.md new file mode 100644 index 0000000..39687dd --- /dev/null +++ b/.agents/skills/11_comptext_validate/SKILL.md @@ -0,0 +1,48 @@ +--- +name: 11_comptext_validate +description: "Defines the verification process for checking generated local CompText-Sparkctl artifacts." +--- + +# Agent Skill 11 — CompText Validation + +This skill defines the verification process for checking generated local CompText-Sparkctl artifacts. + +## 1. Input Files + +Verification targets the presence and integrity of the following local files: +- `reports/latest.json` +- `reports/performance_baseline.json` +- `artifacts/spark/context.json` +- `artifacts/spark/context_render.txt` +- `artifacts/spark/extraction.spkg` + +## 2. Validation Commands + +Execute these commands inside `agy7rust/` to validate the files: +- `cargo run --bin agy-ct -- run` +- `cargo run --bin agy-ct -- context all` +- `python -m json.tool ../reports/latest.json` +- `python -m json.tool ../reports/performance_baseline.json` + +## 3. Checklist + +Verify each of the following: +1. **JSON Parsability:** Run `python -m json.tool` on `reports/latest.json` and `reports/performance_baseline.json` to confirm valid formatting. +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 + +Validation results must be reported using the following format: +- `STATUS: ` +- `CHECKED_ARTIFACTS: ` +- `MISSING_ARTIFACTS: ` +- `VALIDATION_NOTES: ` +- `RISKS: ` +- `NEXT: ` diff --git a/.agents/skills/12_agent_handoff_profile/SKILL.md b/.agents/skills/12_agent_handoff_profile/SKILL.md new file mode 100644 index 0000000..ecdefa6 --- /dev/null +++ b/.agents/skills/12_agent_handoff_profile/SKILL.md @@ -0,0 +1,46 @@ +--- +name: 12_agent_handoff_profile +description: "Defines the safe handoff profile and repository coordination guidelines for future Antigravity agent sessions." +--- + +# Agent Skill 12 — Agent Handoff Profile + +This skill defines the safe handoff profile and repository coordination guidelines for future Antigravity agent sessions. + +## 1. Validated Commands + +The following commands are validated for usage inside `agy7rust/`: +- `cargo fmt --all --check` +- `cargo check` +- `cargo test` +- `cargo clippy -- -D warnings` +- `cargo run --bin agy-ct -- run` +- `cargo run --bin agy-ct -- doctor` +- `cargo run --bin agy-ct -- validate` +- `cargo run --bin agy-ct -- context all` +- `cargo run --bin sparkctl -- doctor` + +## 2. Protected Local Files + +The following files are untracked local runtime outputs and must remain untracked (never stage or commit them): +- `reports/latest.json` +- `POST_PUSH_GITHUB_VERIFICATION.md` + +## 3. Operations Rules + +Future sessions must adhere to these coordination rules: +1. **Inspect Before Editing:** Read the active handbook and existing snapshot documentation before making any modifications. +2. **Smallest Safe Patch:** Prefer small, scoped changes over large edits. +3. **Change Only Allowed Files:** Restrict edits to the paths explicitly specified in the active phase roadmap. +4. **No Premature Staging:** Keep generated runtime output files untracked. +5. **No Unauthorized Commits/Pushes:** Only stage, commit, or push when explicitly instructed by the user's phase requests. + +## 4. Standard Return Format + +Handoff status updates must be reported using the following format: +- `STATUS: ` +- `CURRENT_STATE: ` +- `SAFE_COMMANDS: ` +- `PROTECTED_FILES: ` +- `RECOMMENDED_NEXT_ACTION: ` +- `RISKS: ` diff --git a/.agents/skills/codex-role-workflows/SKILL.md b/.agents/skills/codex-role-workflows/SKILL.md index f6fd3ef..5f7a48b 100644 --- a/.agents/skills/codex-role-workflows/SKILL.md +++ b/.agents/skills/codex-role-workflows/SKILL.md @@ -1,72 +1,77 @@ -# Skill: Codex Role Workflows - -## Purpose - -Apply CompText Agent Governor Policy v1 to Codex-style role, plugin, connector, and skill workflows. - -## Use This Skill When - -- A task mentions Agent Governor, Codex roles, plugins, connectors, skills, policy gates, PR candidates, or agent workflow policy. -- Work may move between read-only audit, local autonomous edits, and PR-candidate preparation. -- A final report must explain approval boundaries and evidence requirements. - -## Role Modes - -### read_only_audit - -Inspect and report without source mutation. Use for audits, review summaries, claim scans, and security read-only work. - -### sandbox_autonomous - -Make local, reviewable changes only inside approved paths. Use local validation and keep remote mutation disabled. - -### pr_candidate - -Prepare validated local work for possible pull request review. Do not push, create a pull request, merge, or deploy without explicit approval. - -## Required Gates - -Report gates using exactly one of: - -- `pass` -- `fail` -- `not_applicable` -- `deferred` - -Use `not_applicable` only when a gate does not apply, and explain why. -Use `deferred` when the gate is required but intentionally left for later human/tool review. - -Report these gates in the final answer or evidence packet when applicable: - -- `instructions_read` -- `secret_scan` -- `artifact_schema_validation` -- `canonical_hash_validation` -- `claim_boundary_check` -- `replay_or_roundtrip_validation` -- `human_review` - -## Connector Rules - -- Treat GitHub as read-only unless explicit mutation approval is given. -- Do not use write-capable connector actions without exact human approval. -- Do not create tokens, handle secrets, or expose provider keys. -- Treat provider output as an untrusted proposal until reviewed. -- Prefer local files and declared artifacts as source of truth. - -## Presentation And Annotations - -Sites and interactive views are presentation only. Annotations are human-review inputs only. Evidence packets and declared artifacts remain the source of truth. - -## Claim Boundaries - -Do not claim production-ready status, compliance or certification, legal evidentiary status, forensic certainty, official SPARK compatibility, autonomous approval, replacement of human review, or guaranteed correctness. - -## Final Checklist - -- Confirm role mode. -- Confirm allowed and forbidden paths. -- Confirm connector and plugin boundary. -- Confirm policy gate evidence. -- Confirm evidence packet priority. -- Confirm human-review boundary. +--- +name: codex-role-workflows +description: "Apply CompText Agent Governor Policy v1 to Codex-style role, plugin, connector, and skill workflows." +--- + +# Skill: Codex Role Workflows + +## Purpose + +Apply CompText Agent Governor Policy v1 to Codex-style role, plugin, connector, and skill workflows. + +## Use This Skill When + +- A task mentions Agent Governor, Codex roles, plugins, connectors, skills, policy gates, PR candidates, or agent workflow policy. +- Work may move between read-only audit, local autonomous edits, and PR-candidate preparation. +- A final report must explain approval boundaries and evidence requirements. + +## Role Modes + +### read_only_audit + +Inspect and report without source mutation. Use for audits, review summaries, claim scans, and security read-only work. + +### sandbox_autonomous + +Make local, reviewable changes only inside approved paths. Use local validation and keep remote mutation disabled. + +### pr_candidate + +Prepare validated local work for possible pull request review. Do not push, create a pull request, merge, or deploy without explicit approval. + +## Required Gates + +Report gates using exactly one of: + +- `pass` +- `fail` +- `not_applicable` +- `deferred` + +Use `not_applicable` only when a gate does not apply, and explain why. +Use `deferred` when the gate is required but intentionally left for later human/tool review. + +Report these gates in the final answer or evidence packet when applicable: + +- `instructions_read` +- `secret_scan` +- `artifact_schema_validation` +- `canonical_hash_validation` +- `claim_boundary_check` +- `replay_or_roundtrip_validation` +- `human_review` + +## Connector Rules + +- Treat GitHub as read-only unless explicit mutation approval is given. +- Do not use write-capable connector actions without exact human approval. +- Do not create tokens, handle secrets, or expose provider keys. +- Treat provider output as an untrusted proposal until reviewed. +- Prefer local files and declared artifacts as source of truth. + +## Presentation And Annotations + +Sites and interactive views are presentation only. Annotations are human-review inputs only. Evidence packets and declared artifacts remain the source of truth. + +## Claim Boundaries + +Do not claim production-ready status, compliance or certification, legal evidentiary status, forensic certainty, official SPARK compatibility, autonomous approval, replacement of human review, or guaranteed correctness. + +## Final Checklist + +- Confirm role mode. +- Confirm allowed and forbidden paths. +- Confirm connector and plugin boundary. +- Confirm policy gate evidence. +- Confirm evidence packet priority. +- Confirm human-review boundary. diff --git a/.agents/skills/codex-token-saving/SKILL.md b/.agents/skills/codex-token-saving/SKILL.md index d04ff4d..31797f3 100644 --- a/.agents/skills/codex-token-saving/SKILL.md +++ b/.agents/skills/codex-token-saving/SKILL.md @@ -1,44 +1,49 @@ -# Skill: Codex Token-Saving Workflow - -## Purpose -Reduce context waste and avoid repo-drift during Codex Desktop work. - -## Use this skill when -- Starting a new Codex Desktop session. -- Working under token limits. -- Deep-diving a large repo. - -## Operating mode -- Do not scan the entire repo blindly. -- Start with local instructions and manifests. -- Use targeted `rg` searches. -- Read only files relevant to the current phase. -- Produce compact summaries. -- Avoid rereading large files. -- Batch validation after coherent edits. - -## Standard phase pattern -1. Bootstrap workspace. -2. Read instructions. -3. Build compact repo map. -4. Identify smallest safe change. -5. Ask for approval if in plan mode. -6. Implement focused change. -7. Validate. -8. Report exact files and command results. - -## Useful search terms for CompText -- `canonical_json` -- `sha256_hex` -- `package` -- `artifact` -- `manifest` -- `goal` -- `policy` -- `review` -- `provider` -- `boundary` -- `handoff` -- `roundtrip` -- `SPARK` -- `claim` +--- +name: codex-token-saving +description: "Reduce context waste and avoid repo-drift during Codex Desktop work." +--- + +# Skill: Codex Token-Saving Workflow + +## Purpose +Reduce context waste and avoid repo-drift during Codex Desktop work. + +## Use this skill when +- Starting a new Codex Desktop session. +- Working under token limits. +- Deep-diving a large repo. + +## Operating mode +- Do not scan the entire repo blindly. +- Start with local instructions and manifests. +- Use targeted `rg` searches. +- Read only files relevant to the current phase. +- Produce compact summaries. +- Avoid rereading large files. +- Batch validation after coherent edits. + +## Standard phase pattern +1. Bootstrap workspace. +2. Read instructions. +3. Build compact repo map. +4. Identify smallest safe change. +5. Ask for approval if in plan mode. +6. Implement focused change. +7. Validate. +8. Report exact files and command results. + +## Useful search terms for CompText +- `canonical_json` +- `sha256_hex` +- `package` +- `artifact` +- `manifest` +- `goal` +- `policy` +- `review` +- `provider` +- `boundary` +- `handoff` +- `roundtrip` +- `SPARK` +- `claim` diff --git a/.agents/skills/comptext-governance/SKILL.md b/.agents/skills/comptext-governance/SKILL.md index 13328e4..748d03e 100644 --- a/.agents/skills/comptext-governance/SKILL.md +++ b/.agents/skills/comptext-governance/SKILL.md @@ -1,57 +1,62 @@ -# Skill: CompText Governance - -## Purpose -Preserve the CompText product contract during any code, UI, CLI, documentation, or artifact work. - -## Use this skill when -- Working on CompText Gateway, comptext-cli, comptext-sparkctl, Context Governor, or related docs. -- Changing pipeline, provider, review, artifact, or safety logic. -- Preparing material for reviewers, SPARK, public sector, or enterprise stakeholders. - -## Product contract -CompText is a deterministic Context Pack / proposal-gated evidence workflow. - -Core line: -Models are providers. Context is the product. - -Canonical pipeline: -Source / GitHub URL → Goal → Inspect → Context Pack → Policy Gate → Provider Boundary → Untrusted Proposal → Human Review → Artifacts - -## Required boundaries -- Provider output is untrusted until reviewed. -- Proposals are never auto-applied. -- Policy Gate decides whether provider calls are allowed. -- Human Review is the approval boundary. -- Artifacts preserve the evidence trail. -- GitHub/source repos remain read-only unless explicitly approved. - -## Allowed claims -- deterministic context infrastructure -- bounded inspection -- proposal-gated workflow -- review boundary -- evidence trail -- provider-agnostic boundary -- artifact manifest -- local integrity anchor if actually implemented -- SHA-256 hash of canonical JSON if actually computed - -## Blocked claims -- production-ready -- certified -- EU AI Act compliant -- legally compliant -- forensic proof or forensic certainty -- solved hallucinations -- guaranteed correctness -- guaranteed replay validity for arbitrary inputs -- autonomous enterprise agent -- autonomous approval -- universal AI memory - -## Checklist before final answer -- Did the change preserve Goal → Context Pack → Policy Gate → Review → Artifacts? -- Is provider output clearly untrusted? -- Are claims bounded and review-safe? -- Are artifacts/data honest and not faked? -- Are source repos/GitHub writes blocked unless explicitly approved? +--- +name: comptext-governance +description: "Preserve the CompText product contract during any code, UI, CLI, documentation, or artifact work." +--- + +# Skill: CompText Governance + +## Purpose +Preserve the CompText product contract during any code, UI, CLI, documentation, or artifact work. + +## Use this skill when +- Working on CompText Gateway, comptext-cli, comptext-sparkctl, Context Governor, or related docs. +- Changing pipeline, provider, review, artifact, or safety logic. +- Preparing material for reviewers, SPARK, public sector, or enterprise stakeholders. + +## Product contract +CompText is a deterministic Context Pack / proposal-gated evidence workflow. + +Core line: +Models are providers. Context is the product. + +Canonical pipeline: +Source / GitHub URL → Goal → Inspect → Context Pack → Policy Gate → Provider Boundary → Untrusted Proposal → Human Review → Artifacts + +## Required boundaries +- Provider output is untrusted until reviewed. +- Proposals are never auto-applied. +- Policy Gate decides whether provider calls are allowed. +- Human Review is the approval boundary. +- Artifacts preserve the evidence trail. +- GitHub/source repos remain read-only unless explicitly approved. + +## Allowed claims +- deterministic context infrastructure +- bounded inspection +- proposal-gated workflow +- review boundary +- evidence trail +- provider-agnostic boundary +- artifact manifest +- local integrity anchor if actually implemented +- SHA-256 hash of canonical JSON if actually computed + +## Blocked claims +- production-ready +- certified +- EU AI Act compliant +- legally compliant +- forensic proof or forensic certainty +- solved hallucinations +- guaranteed correctness +- guaranteed replay validity for arbitrary inputs +- autonomous enterprise agent +- autonomous approval +- universal AI memory + +## Checklist before final answer +- Did the change preserve Goal → Context Pack → Policy Gate → Review → Artifacts? +- Is provider output clearly untrusted? +- Are claims bounded and review-safe? +- Are artifacts/data honest and not faked? +- Are source repos/GitHub writes blocked unless explicitly approved? diff --git a/.agents/skills/pdf-extraction-contracts/SKILL.md b/.agents/skills/pdf-extraction-contracts/SKILL.md index 995e4b3..671289d 100644 --- a/.agents/skills/pdf-extraction-contracts/SKILL.md +++ b/.agents/skills/pdf-extraction-contracts/SKILL.md @@ -1,91 +1,96 @@ -# Skill: PDF Extraction Contracts - -## Purpose - -Guide work on `PDF-EXTRACTION-V1` structured-data artifacts for SPARK-like administrative workflows. - -## Use This Skill When - -- Adding or reviewing PDF extraction fixtures. -- Updating `schemas/spark/pdf_extraction_v1.schema.json`. -- Validating external or manual extraction JSON before evidence packaging. -- Connecting PDF extraction artifacts to Context Pack or Evidence Packet workflows. - -## Contract Boundary - -`PDF-EXTRACTION-V1` is an adapter contract. It accepts structured JSON from manual or external extraction tools as input evidence. - -It does not: - -- implement OCR -- parse PDFs -- download source PDFs -- call providers -- create a Codex plugin bundle -- create an MCP server -- create hooks or commands -- claim official OpenAI plugin compatibility -- claim official SPARK compatibility -- replace human review - -## Required Fields - -Every artifact must include: - -- `schema_version` -- `source_file` -- `document_type` -- `pages` -- `tables` -- `figures` -- `extracted_fields` -- `warnings` -- `tool_metadata` - -`schema_version` must be `PDF-EXTRACTION-V1`. - -`tool_metadata.converter` must be one of: - -- `manual` -- `docling` -- `mineru` -- `marker` -- `pdftotext` -- `other` - -`tool_metadata.extraction_mode` must be one of: - -- `synthetic_fixture` -- `manual_fixture` -- `external_tool` - -## Fixture Rules - -Synthetic fixtures must not include protected personal data, real SPARK data, real Daimler data, real medical data, or real ePA data. - -Do not commit source PDFs unless a future task explicitly approves that artifact and license boundary. - -## Validation - -Prefer local runtime validation with `validate_pdf_extraction_contract_value` and deterministic canonical hashing with the existing `canonical_json` and `sha256_hex` helpers. - -Report Agent Governor gate states using exactly one of: - -- `pass` -- `fail` -- `not_applicable` -- `deferred` - -Use `not_applicable` only when a gate does not apply, and explain why. Use `deferred` when the gate is required but intentionally left for later human/tool review. - -For Rust changes, run: - -- `cargo fmt --all --check` -- `cargo test` -- `cargo clippy --all-targets --all-features -- -D warnings` - -## Claim Boundaries - -Use bounded wording: adapter contract, structured input evidence, manual fixture, external-tool output, review input, artifact manifest. - -Do not claim production readiness, compliance or certification, legal evidentiary status, forensic certainty, official SPARK compatibility, official OpenAI plugin compatibility, autonomous approval, or guaranteed correctness. +--- +name: pdf-extraction-contracts +description: "Guide work on PDF-EXTRACTION-V1 structured-data artifacts for SPARK-like administrative workflows." +--- + +# Skill: PDF Extraction Contracts + +## Purpose + +Guide work on `PDF-EXTRACTION-V1` structured-data artifacts for SPARK-like administrative workflows. + +## Use This Skill When + +- Adding or reviewing PDF extraction fixtures. +- Updating `schemas/spark/pdf_extraction_v1.schema.json`. +- Validating external or manual extraction JSON before evidence packaging. +- Connecting PDF extraction artifacts to Context Pack or Evidence Packet workflows. + +## Contract Boundary + +`PDF-EXTRACTION-V1` is an adapter contract. It accepts structured JSON from manual or external extraction tools as input evidence. + +It does not: + +- implement OCR +- parse PDFs +- download source PDFs +- call providers +- create a Codex plugin bundle +- create an MCP server +- create hooks or commands +- claim official OpenAI plugin compatibility +- claim official SPARK compatibility +- replace human review + +## Required Fields + +Every artifact must include: + +- `schema_version` +- `source_file` +- `document_type` +- `pages` +- `tables` +- `figures` +- `extracted_fields` +- `warnings` +- `tool_metadata` + +`schema_version` must be `PDF-EXTRACTION-V1`. + +`tool_metadata.converter` must be one of: + +- `manual` +- `docling` +- `mineru` +- `marker` +- `pdftotext` +- `other` + +`tool_metadata.extraction_mode` must be one of: + +- `synthetic_fixture` +- `manual_fixture` +- `external_tool` + +## Fixture Rules + +Synthetic fixtures must not include protected personal data, real SPARK data, real Daimler data, real medical data, or real ePA data. + +Do not commit source PDFs unless a future task explicitly approves that artifact and license boundary. + +## Validation + +Prefer local runtime validation with `validate_pdf_extraction_contract_value` and deterministic canonical hashing with the existing `canonical_json` and `sha256_hex` helpers. + +Report Agent Governor gate states using exactly one of: + +- `pass` +- `fail` +- `not_applicable` +- `deferred` + +Use `not_applicable` only when a gate does not apply, and explain why. Use `deferred` when the gate is required but intentionally left for later human/tool review. + +For Rust changes, run: + +- `cargo fmt --all --check` +- `cargo test` +- `cargo clippy --all-targets --all-features -- -D warnings` + +## Claim Boundaries + +Use bounded wording: adapter contract, structured input evidence, manual fixture, external-tool output, review input, artifact manifest. + +Do not claim production readiness, compliance or certification, legal evidentiary status, forensic certainty, official SPARK compatibility, official OpenAI plugin compatibility, autonomous approval, or guaranteed correctness. diff --git a/.agents/skills/reviewer-final-report/SKILL.md b/.agents/skills/reviewer-final-report/SKILL.md index 9953cd1..00a0d35 100644 --- a/.agents/skills/reviewer-final-report/SKILL.md +++ b/.agents/skills/reviewer-final-report/SKILL.md @@ -1,27 +1,32 @@ -# Skill: Reviewer Final Report - -## Purpose -Ensure every Codex Desktop run ends with an auditable, reviewer-grade report. - -## Required final report sections -1. Working folder path. -2. Repository root path. -3. Instructions/skills read. -4. MCP/connectors/plugins used or skipped. -5. Git remote status showing push disabled. -6. Files changed. -7. Artifact contract improvements. -8. Goal support improvements. -9. Policy/review/provider-boundary improvements. -10. SPARK alignment improvements. -11. Validation commands and exact results. -12. Remaining risks. -13. Final ZIP path if created. -14. Next safe action. - -## Reporting rules -- Do not hide failed commands. -- Distinguish implemented vs documented vs future work. -- Do not inflate claims. -- Mention any assumptions. -- Keep the final report compact but complete. +--- +name: reviewer-final-report +description: "Ensure every Codex Desktop run ends with an auditable, reviewer-grade report." +--- + +# Skill: Reviewer Final Report + +## Purpose +Ensure every Codex Desktop run ends with an auditable, reviewer-grade report. + +## Required final report sections +1. Working folder path. +2. Repository root path. +3. Instructions/skills read. +4. MCP/connectors/plugins used or skipped. +5. Git remote status showing push disabled. +6. Files changed. +7. Artifact contract improvements. +8. Goal support improvements. +9. Policy/review/provider-boundary improvements. +10. SPARK alignment improvements. +11. Validation commands and exact results. +12. Remaining risks. +13. Final ZIP path if created. +14. Next safe action. + +## Reporting rules +- Do not hide failed commands. +- Distinguish implemented vs documented vs future work. +- Do not inflate claims. +- Mention any assumptions. +- Keep the final report compact but complete. diff --git a/.agents/skills/rust-canonical-artifacts/SKILL.md b/.agents/skills/rust-canonical-artifacts/SKILL.md index 54da212..eae5162 100644 --- a/.agents/skills/rust-canonical-artifacts/SKILL.md +++ b/.agents/skills/rust-canonical-artifacts/SKILL.md @@ -1,36 +1,41 @@ -# Skill: Rust Canonical Artifacts - -## Purpose -Keep Rust artifact packaging deterministic, testable, and honest. - -## Use this skill when -- Editing Rust package/codec/serialization code. -- Working on `canonical_json`, `sha256_hex`, manifests, or roundtrip tests. - -## Determinism rules -- Canonical serialization must be stable across runs. -- Avoid map iteration order unless explicitly sorted/canonicalized. -- Avoid nondeterministic timestamps in hash inputs unless intentionally part of the schema and tested. -- Avoid platform-specific path separators inside canonical hashes unless normalized. -- Hash only canonical bytes/string, not pretty-printed or debug output. - -## Hash rules -- Never display `sha256` unless actually computed. -- Never call a placeholder hash an integrity anchor. -- If a hash is optional, represent missing hash explicitly. -- If docs mention SHA-256, say “over canonical JSON” only when implemented. - -## Rust quality rules -- Prefer typed structs/enums over loose strings for contract-critical fields. -- Use serde derives consistently. -- Keep backwards compatibility if an existing package format exists. -- Add tests before broad refactors. -- Keep changes small. - -## Validation -Prefer: -- `cargo fmt --check` -- `cargo test` -- `cargo clippy --all-targets --all-features -- -D warnings` - -If clippy fails on pre-existing warnings, report honestly and fix only safe issues. +--- +name: rust-canonical-artifacts +description: "Keep Rust artifact packaging deterministic, testable, and honest." +--- + +# Skill: Rust Canonical Artifacts + +## Purpose +Keep Rust artifact packaging deterministic, testable, and honest. + +## Use this skill when +- Editing Rust package/codec/serialization code. +- Working on `canonical_json`, `sha256_hex`, manifests, or roundtrip tests. + +## Determinism rules +- Canonical serialization must be stable across runs. +- Avoid map iteration order unless explicitly sorted/canonicalized. +- Avoid nondeterministic timestamps in hash inputs unless intentionally part of the schema and tested. +- Avoid platform-specific path separators inside canonical hashes unless normalized. +- Hash only canonical bytes/string, not pretty-printed or debug output. + +## Hash rules +- Never display `sha256` unless actually computed. +- Never call a placeholder hash an integrity anchor. +- If a hash is optional, represent missing hash explicitly. +- If docs mention SHA-256, say “over canonical JSON” only when implemented. + +## Rust quality rules +- Prefer typed structs/enums over loose strings for contract-critical fields. +- Use serde derives consistently. +- Keep backwards compatibility if an existing package format exists. +- Add tests before broad refactors. +- Keep changes small. + +## Validation +Prefer: +- `cargo fmt --check` +- `cargo test` +- `cargo clippy --all-targets --all-features -- -D warnings` + +If clippy fails on pre-existing warnings, report honestly and fix only safe issues. diff --git a/.agents/skills/security-readonly-boundaries/SKILL.md b/.agents/skills/security-readonly-boundaries/SKILL.md index e9522c1..82836c8 100644 --- a/.agents/skills/security-readonly-boundaries/SKILL.md +++ b/.agents/skills/security-readonly-boundaries/SKILL.md @@ -1,42 +1,47 @@ -# Skill: Security and Read-Only Boundaries - -## Purpose -Prevent unsafe actions while working with Codex Desktop, GitHub, MCP/connectors, and local repositories. - -## Use this skill when -- GitHub plugin is enabled. -- Codex Security plugin is enabled. -- Any MCP/connector is available. -- Working on CompText source repos or hackathon deliverables. - -## Hard restrictions -- Do not push. -- Do not deploy. -- Do not create PRs. -- Do not create issues. -- Do not create remote branches. -- Do not create tokens. -- Do not write secrets. -- Do not paste secrets into code, docs, prompts, or tests. -- Do not install unofficial Codex UI/Android/remote-control packages. - -## Git safety -After cloning, run: -`git remote set-url --push origin DISABLED` - -Then show: -`git remote -v` - -Treat GitHub as read-only even if credentials allow writes. - -## MCP / connector rules -- Use MCP/connectors only for read-only context unless explicitly approved. -- Prefer local cloned files as source of truth. -- Do not use connectors to mutate GitHub or deployments. -- Do not rely on hidden external state for deterministic validation. - -## Network/tooling caution -- Do not add provider calls for sparkctl. -- Do not add shell execution features to the product. -- Do not add arbitrary filesystem readers. -- Do not expose private provider keys to frontend/runtime output. +--- +name: security-readonly-boundaries +description: "Prevent unsafe actions while working with Codex Desktop, GitHub, MCP/connectors, and local repositories." +--- + +# Skill: Security and Read-Only Boundaries + +## Purpose +Prevent unsafe actions while working with Codex Desktop, GitHub, MCP/connectors, and local repositories. + +## Use this skill when +- GitHub plugin is enabled. +- Codex Security plugin is enabled. +- Any MCP/connector is available. +- Working on CompText source repos or hackathon deliverables. + +## Hard restrictions +- Do not push. +- Do not deploy. +- Do not create PRs. +- Do not create issues. +- Do not create remote branches. +- Do not create tokens. +- Do not write secrets. +- Do not paste secrets into code, docs, prompts, or tests. +- Do not install unofficial Codex UI/Android/remote-control packages. + +## Git safety +After cloning, run: +`git remote set-url --push origin DISABLED` + +Then show: +`git remote -v` + +Treat GitHub as read-only even if credentials allow writes. + +## MCP / connector rules +- Use MCP/connectors only for read-only context unless explicitly approved. +- Prefer local cloned files as source of truth. +- Do not use connectors to mutate GitHub or deployments. +- Do not rely on hidden external state for deterministic validation. + +## Network/tooling caution +- Do not add provider calls for sparkctl. +- Do not add shell execution features to the product. +- Do not add arbitrary filesystem readers. +- Do not expose private provider keys to frontend/runtime output. diff --git a/.agents/skills/spark-hackathon-alignment/SKILL.md b/.agents/skills/spark-hackathon-alignment/SKILL.md index a27a7ed..6e64bf5 100644 --- a/.agents/skills/spark-hackathon-alignment/SKILL.md +++ b/.agents/skills/spark-hackathon-alignment/SKILL.md @@ -1,35 +1,40 @@ -# Skill: SPARK Hackathon Alignment - -## Purpose -Align CompText work with SPARK / Safe & Stable positioning without overclaiming. - -## Use this skill when -- Preparing hackathon material. -- Writing README, demo, pitch, or docs for SPARK. -- Adding evidence/review functionality. - -## Positioning -SPARK stands for “Schnellere Planung und Realisierung durch KI”. -CompText should be positioned as the review, policy, and evidence boundary for AI-assisted workflows. - -## Good framing -- Safe and stable AI workflows need reviewable context, provider boundaries, and evidence artifacts. -- CompText does not replace human review; it preserves a reviewable trail. -- sparkctl packages the artifact/evidence layer. -- Provider output is an untrusted proposal until reviewed. - -## Avoid -- automated approval -- legal review replacement -- compliance certification -- production-ready government deployment claims -- forensic proof -- live public-sector data processing claims - -## Demo object -Prefer a concrete “SPARK Evidence Packet v1” over vague dashboard features. - -Minimum demo story: -1. Goal: Assess a module/workflow for safe and stable use. -2. Policy Gate: ALLOW / REVIEW_NEEDED / BLOCK with reasons. -3. Evidence Packet: preserves goal, context, proposal, review, claim hygiene, and manifest. +--- +name: spark-hackathon-alignment +description: "Align CompText work with SPARK / Safe & Stable positioning without overclaiming." +--- + +# Skill: SPARK Hackathon Alignment + +## Purpose +Align CompText work with SPARK / Safe & Stable positioning without overclaiming. + +## Use this skill when +- Preparing hackathon material. +- Writing README, demo, pitch, or docs for SPARK. +- Adding evidence/review functionality. + +## Positioning +SPARK stands for “Schnellere Planung und Realisierung durch KI”. +CompText should be positioned as the review, policy, and evidence boundary for AI-assisted workflows. + +## Good framing +- Safe and stable AI workflows need reviewable context, provider boundaries, and evidence artifacts. +- CompText does not replace human review; it preserves a reviewable trail. +- sparkctl packages the artifact/evidence layer. +- Provider output is an untrusted proposal until reviewed. + +## Avoid +- automated approval +- legal review replacement +- compliance certification +- production-ready government deployment claims +- forensic proof +- live public-sector data processing claims + +## Demo object +Prefer a concrete “SPARK Evidence Packet v1” over vague dashboard features. + +Minimum demo story: +1. Goal: Assess a module/workflow for safe and stable use. +2. Policy Gate: ALLOW / REVIEW_NEEDED / BLOCK with reasons. +3. Evidence Packet: preserves goal, context, proposal, review, claim hygiene, and manifest. diff --git a/.agents/skills/sparkctl-evidence-packet/SKILL.md b/.agents/skills/sparkctl-evidence-packet/SKILL.md index 8686661..20e9eb1 100644 --- a/.agents/skills/sparkctl-evidence-packet/SKILL.md +++ b/.agents/skills/sparkctl-evidence-packet/SKILL.md @@ -1,63 +1,68 @@ -# Skill: sparkctl Evidence Packet - -## Purpose -Guide `comptext-sparkctl` work toward a SPARK Evidence Packet v1: a deterministic, reviewable artifact package for CompText. - -## Use this skill when -- Working in `ProfRandom92/comptext-sparkctl`. -- Modifying artifact/package/codec/manifest/roundtrip code. -- Preparing SPARK Safe & Stable hackathon material. - -## Target artifact -SPARK Evidence Packet v1 should contain, as data fields or manifest sections: -- `schema_version` -- `package_id` or `local_id` -- `goal` -- `source_summary` -- `context_pack_ref` or `context_pack_summary` -- `policy_result` -- `provider_boundary_status` -- `untrusted_proposal` -- `human_review_decision` -- `claim_hygiene` -- `artifact_manifest` -- `canonical_hash` only if computed from canonical JSON -- `warnings` / `limitations` - -## Enums -Policy Gate result: -- `ALLOW` -- `REVIEW_NEEDED` -- `BLOCK` - -Provider Boundary status: -- `DEMO` -- `UNAVAILABLE` -- `AVAILABLE` -- `BLOCKED_BY_POLICY` - -Human Review decision: -- `PASS` -- `NOTES` -- `BLOCKED` - -## Rules -- Goal informs packaging and review criteria. -- Goal never bypasses Policy Gate. -- Goal never authorizes auto-apply. -- Provider output is untrusted until reviewed. -- Human Review is the approval boundary. -- Artifacts preserve the evidence trail. -- Do not fake hashes. -- If a hash is shown, compute it from canonical JSON. - -## Tests to prefer -- canonical JSON deterministic output -- SHA-256 stable for known canonical input -- package roundtrip verify -- goal included in manifest -- policy result included -- provider boundary status included -- review decision included -- claim hygiene included -- SPARK Evidence Packet demo validates +--- +name: sparkctl-evidence-packet +description: "Guide comptext-sparkctl work toward a SPARK Evidence Packet v1: a deterministic, reviewable artifact package for CompText." +--- + +# Skill: sparkctl Evidence Packet + +## Purpose +Guide `comptext-sparkctl` work toward a SPARK Evidence Packet v1: a deterministic, reviewable artifact package for CompText. + +## Use this skill when +- Working in `ProfRandom92/comptext-sparkctl`. +- Modifying artifact/package/codec/manifest/roundtrip code. +- Preparing SPARK Safe & Stable hackathon material. + +## Target artifact +SPARK Evidence Packet v1 should contain, as data fields or manifest sections: +- `schema_version` +- `package_id` or `local_id` +- `goal` +- `source_summary` +- `context_pack_ref` or `context_pack_summary` +- `policy_result` +- `provider_boundary_status` +- `untrusted_proposal` +- `human_review_decision` +- `claim_hygiene` +- `artifact_manifest` +- `canonical_hash` only if computed from canonical JSON +- `warnings` / `limitations` + +## Enums +Policy Gate result: +- `ALLOW` +- `REVIEW_NEEDED` +- `BLOCK` + +Provider Boundary status: +- `DEMO` +- `UNAVAILABLE` +- `AVAILABLE` +- `BLOCKED_BY_POLICY` + +Human Review decision: +- `PASS` +- `NOTES` +- `BLOCKED` + +## Rules +- Goal informs packaging and review criteria. +- Goal never bypasses Policy Gate. +- Goal never authorizes auto-apply. +- Provider output is untrusted until reviewed. +- Human Review is the approval boundary. +- Artifacts preserve the evidence trail. +- Do not fake hashes. +- If a hash is shown, compute it from canonical JSON. + +## Tests to prefer +- canonical JSON deterministic output +- SHA-256 stable for known canonical input +- package roundtrip verify +- goal included in manifest +- policy result included +- provider boundary status included +- review decision included +- claim hygiene included +- SPARK Evidence Packet demo validates diff --git a/AGENTS.md b/AGENTS.md index 25c0e99..e891adf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,7 +33,7 @@ Codex Desktop governance: Before editing: 1. Read AGENTS.md. -2. Read `.agent/skills/*.md` relevant to the task; treat `.agents/skills/**/SKILL.md` as legacy/compatibility metadata only if present. -3. If `.agent/skills/00_project_system.md` exists, read it too. +2. Read `.agents/skills/**/SKILL.md` relevant to the task; treat `.agent/skills/*.md` as legacy/compatibility metadata only if present. +3. If `.agents/skills/00_project_system/SKILL.md` exists, read it too. 4. Build a compact repo map. 5. Stop for approval if the user asked for plan mode. From 61450852593ae5f6d30740027849e0f805340b77 Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Tue, 9 Jun 2026 22:56:11 +0200 Subject: [PATCH 03/27] feat: wire package verify replay validation --- agy7rust/src/bin/agy_ct.rs | 8 +- agy7rust/src/codec/package.rs | 199 ++++++++++++++++++++++++------ agy7rust/src/error.rs | 4 + agy7rust/tests/spark_roundtrip.rs | 108 ++++++++++++++++ 4 files changed, 278 insertions(+), 41 deletions(-) diff --git a/agy7rust/src/bin/agy_ct.rs b/agy7rust/src/bin/agy_ct.rs index fc0cb65..ea201cb 100644 --- a/agy7rust/src/bin/agy_ct.rs +++ b/agy7rust/src/bin/agy_ct.rs @@ -207,11 +207,11 @@ fn main() -> Result<()> { PackageCommands::Inspect { .. } => { println!("Placeholder: package inspect"); } - PackageCommands::Verify { .. } => { - println!("Placeholder: package verify"); + PackageCommands::Verify { input } => { + agy7rust::commands::verify_cmd::run(input)?; } - PackageCommands::Replay { .. } => { - println!("Placeholder: package replay"); + PackageCommands::Replay { input } => { + agy7rust::commands::replay_cmd::run(input)?; } PackageCommands::Adversarial { .. } => { println!("Placeholder: package adversarial"); diff --git a/agy7rust/src/codec/package.rs b/agy7rust/src/codec/package.rs index 0adc65d..db98430 100644 --- a/agy7rust/src/codec/package.rs +++ b/agy7rust/src/codec/package.rs @@ -572,65 +572,79 @@ pub fn build_package_from_value(value: &serde_json::Value) -> anyhow::Result anyhow::Result<()> { - let pkg = value - .as_object() - .ok_or_else(|| anyhow::anyhow!("Package is not a JSON object"))?; - - let schema = pkg - .get("schema") - .and_then(|v| v.as_str()) - .ok_or_else(|| anyhow::anyhow!("schema mismatch: Missing schema"))?; + use crate::error::SparkError; + + let pkg = value.as_object().ok_or_else(|| { + anyhow::Error::new(SparkError::EvidenceLoss( + "Package is not a JSON object".to_string(), + )) + })?; + + let schema = pkg.get("schema").and_then(|v| v.as_str()).ok_or_else(|| { + anyhow::Error::new(SparkError::EvidenceLoss( + "schema mismatch: Missing schema".to_string(), + )) + })?; if schema != "SPARK-V7-PACKAGE" { - return Err(anyhow::anyhow!( + return Err(anyhow::Error::new(SparkError::ConstraintDrift(format!( "schema mismatch: expected SPARK-V7-PACKAGE, got {}", schema - )); + )))); } - let version = pkg - .get("version") - .and_then(|v| v.as_i64()) - .ok_or_else(|| anyhow::anyhow!("version mismatch: Missing version"))?; + let version = pkg.get("version").and_then(|v| v.as_i64()).ok_or_else(|| { + anyhow::Error::new(SparkError::EvidenceLoss( + "version mismatch: Missing version".to_string(), + )) + })?; if version != 1 { - return Err(anyhow::anyhow!( + return Err(anyhow::Error::new(SparkError::ConstraintDrift(format!( "version mismatch: expected 1, got {}", version - )); + )))); } - let payload = pkg - .get("payload") - .ok_or_else(|| anyhow::anyhow!("Missing payload"))?; + let payload = pkg.get("payload").ok_or_else(|| { + anyhow::Error::new(SparkError::EvidenceLoss("Missing payload".to_string())) + })?; - let sidecar_val = pkg - .get("sidecar") - .ok_or_else(|| anyhow::anyhow!("Missing sidecar"))?; - let sidecar = sidecar_val - .as_object() - .ok_or_else(|| anyhow::anyhow!("sidecar is not a JSON object"))?; + let sidecar_val = pkg.get("sidecar").ok_or_else(|| { + anyhow::Error::new(SparkError::EvidenceLoss("Missing sidecar".to_string())) + })?; + let sidecar = sidecar_val.as_object().ok_or_else(|| { + anyhow::Error::new(SparkError::EvidenceLoss( + "sidecar is not a JSON object".to_string(), + )) + })?; let schema_version = sidecar .get("schema_version") .and_then(|v| v.as_str()) .ok_or_else(|| { - anyhow::anyhow!("schema_version mismatch: Missing sidecar schema_version") + anyhow::Error::new(SparkError::EvidenceLoss( + "schema_version mismatch: Missing sidecar schema_version".to_string(), + )) })?; if schema_version != "KVTC7-SPARK-1" { - return Err(anyhow::anyhow!( + return Err(anyhow::Error::new(SparkError::ConstraintDrift(format!( "schema_version mismatch: expected KVTC7-SPARK-1, got {}", schema_version - )); + )))); } let source_type = sidecar .get("source_type") .and_then(|v| v.as_str()) - .ok_or_else(|| anyhow::anyhow!("source_type mismatch: Missing sidecar source_type"))?; + .ok_or_else(|| { + anyhow::Error::new(SparkError::EvidenceLoss( + "source_type mismatch: Missing sidecar source_type".to_string(), + )) + })?; if source_type != "spark_extraction_json" { - return Err(anyhow::anyhow!( + return Err(anyhow::Error::new(SparkError::ConstraintDrift(format!( "source_type mismatch: expected spark_extraction_json, got {}", source_type - )); + )))); } let payload_canonical = canonical_json(payload); @@ -640,17 +654,23 @@ pub fn verify_package_value(value: &serde_json::Value) -> anyhow::Result<()> { .get("payload_sha256") .and_then(|v| v.as_str()) .ok_or_else(|| { - anyhow::anyhow!("payload_sha256 mismatch: Missing sidecar payload_sha256") + anyhow::Error::new(SparkError::EvidenceLoss( + "payload_sha256 mismatch: Missing sidecar payload_sha256".to_string(), + )) })?; if calculated_payload_sha256 != expected_payload_sha256 { - return Err(anyhow::anyhow!("payload_sha256 mismatch")); + return Err(anyhow::Error::new(SparkError::ConstraintDrift( + "payload_sha256 mismatch".to_string(), + ))); } let expected_final_state_hash = sidecar .get("final_state_hash") .and_then(|v| v.as_str()) .ok_or_else(|| { - anyhow::anyhow!("final_state_hash mismatch: Missing sidecar final_state_hash") + anyhow::Error::new(SparkError::EvidenceLoss( + "final_state_hash mismatch: Missing sidecar final_state_hash".to_string(), + )) })?; let mut sidecar_preimage = sidecar_val.clone(); @@ -661,13 +681,19 @@ pub fn verify_package_value(value: &serde_json::Value) -> anyhow::Result<()> { let calculated_final_state_hash = sha256_hex(sidecar_preimage_canonical); if calculated_final_state_hash != expected_final_state_hash { - return Err(anyhow::anyhow!("final_state_hash mismatch")); + return Err(anyhow::Error::new(SparkError::ConstraintDrift( + "final_state_hash mismatch".to_string(), + ))); } let expected_integrity_hash = pkg .get("integrity_hash") .and_then(|v| v.as_str()) - .ok_or_else(|| anyhow::anyhow!("integrity_hash mismatch: Missing integrity_hash"))?; + .ok_or_else(|| { + anyhow::Error::new(SparkError::EvidenceLoss( + "integrity_hash mismatch: Missing integrity_hash".to_string(), + )) + })?; let mut package_preimage = value.clone(); if let serde_json::Value::Object(ref mut map) = package_preimage { @@ -677,7 +703,106 @@ pub fn verify_package_value(value: &serde_json::Value) -> anyhow::Result<()> { let calculated_integrity_hash = sha256_hex(package_preimage_canonical); if calculated_integrity_hash != expected_integrity_hash { - return Err(anyhow::anyhow!("integrity_hash mismatch")); + return Err(anyhow::Error::new(SparkError::ConstraintDrift( + "integrity_hash mismatch".to_string(), + ))); + } + + // Optional ledger validation + if let Some(ledger_val) = pkg.get("ledger") { + let ledger_arr = ledger_val.as_array().ok_or_else(|| { + anyhow::Error::new(SparkError::EvidenceLoss( + "ledger is not an array".to_string(), + )) + })?; + + let ledger_root = pkg + .get("ledger_root") + .and_then(|v| v.as_str()) + .ok_or_else(|| { + anyhow::Error::new(SparkError::EvidenceLoss( + "ledger_root is missing".to_string(), + )) + })?; + + if ledger_arr.is_empty() { + return Err(anyhow::Error::new(SparkError::EvidenceLoss( + "ledger is empty".to_string(), + ))); + } + + for (idx, entry_val) in ledger_arr.iter().enumerate() { + let entry = entry_val.as_object().ok_or_else(|| { + anyhow::Error::new(SparkError::EvidenceLoss(format!( + "ledger entry at index {} is not an object", + idx + ))) + })?; + + let _entry_hash = entry + .get("entry_hash") + .and_then(|v| v.as_str()) + .ok_or_else(|| { + anyhow::Error::new(SparkError::EvidenceLoss(format!( + "ledger entry at index {} missing entry_hash", + idx + ))) + })?; + + let previous_hash = entry + .get("previous_hash") + .and_then(|v| v.as_str()) + .ok_or_else(|| { + anyhow::Error::new(SparkError::EvidenceLoss(format!( + "ledger entry at index {} missing previous_hash", + idx + ))) + })?; + + if idx > 0 { + let prev_entry = ledger_arr[idx - 1].as_object().ok_or_else(|| { + anyhow::Error::new(SparkError::EvidenceLoss( + "Preceding ledger entry is not an object".to_string(), + )) + })?; + let prev_entry_hash = prev_entry + .get("entry_hash") + .and_then(|v| v.as_str()) + .ok_or_else(|| { + anyhow::Error::new(SparkError::EvidenceLoss( + "Preceding ledger entry missing entry_hash".to_string(), + )) + })?; + + if previous_hash != prev_entry_hash { + return Err(anyhow::Error::new(SparkError::ConstraintDrift(format!( + "ledger chaining mismatch: previous_hash '{}' at index {} does not match entry_hash '{}' of preceding entry", + previous_hash, idx, prev_entry_hash + )))); + } + } + } + + let final_entry = ledger_arr.last().unwrap().as_object().ok_or_else(|| { + anyhow::Error::new(SparkError::EvidenceLoss( + "Final ledger entry is not an object".to_string(), + )) + })?; + let final_entry_hash = final_entry + .get("entry_hash") + .and_then(|v| v.as_str()) + .ok_or_else(|| { + anyhow::Error::new(SparkError::EvidenceLoss( + "Final ledger entry missing entry_hash".to_string(), + )) + })?; + + if ledger_root != final_entry_hash { + return Err(anyhow::Error::new(SparkError::ConstraintDrift(format!( + "ledger root anchoring mismatch: expected ledger_root '{}' to match final entry_hash '{}'", + ledger_root, final_entry_hash + )))); + } } Ok(()) diff --git a/agy7rust/src/error.rs b/agy7rust/src/error.rs index c05e8e5..1dba8ec 100644 --- a/agy7rust/src/error.rs +++ b/agy7rust/src/error.rs @@ -4,6 +4,8 @@ use std::fmt; pub enum SparkError { ValidationError(String), SerializationError(String), + EvidenceLoss(String), + ConstraintDrift(String), } impl fmt::Display for SparkError { @@ -11,6 +13,8 @@ impl fmt::Display for SparkError { match self { Self::ValidationError(msg) => write!(f, "Validation Error: {}", msg), Self::SerializationError(msg) => write!(f, "Serialization Error: {}", msg), + Self::EvidenceLoss(msg) => write!(f, "EVIDENCE_LOSS: {}", msg), + Self::ConstraintDrift(msg) => write!(f, "CONSTRAINT_DRIFT: {}", msg), } } } diff --git a/agy7rust/tests/spark_roundtrip.rs b/agy7rust/tests/spark_roundtrip.rs index 8ad814a..dfb27d2 100644 --- a/agy7rust/tests/spark_roundtrip.rs +++ b/agy7rust/tests/spark_roundtrip.rs @@ -1434,3 +1434,111 @@ fn test_sparkctl_handoff_check_execution() { assert!(stdout_str.contains("=== sparkctl handoff-check ===")); assert!(stdout_str.contains("handoff-check result: PASS")); } + +#[test] +fn test_package_verify_and_replay_with_structured_errors_and_ledger() { + use agy7rust::codec::package::{replay_package_value, verify_package_value}; + use serde_json::json; + + // Helper to construct a valid package envelope + let make_pkg = |payload: serde_json::Value, + ledger: Option, + ledger_root: Option<&str>| + -> serde_json::Value { + use agy7rust::codec::hash::sha256_hex; + use agy7rust::codec::package::canonical_json; + + let payload_canonical = canonical_json(&payload); + let payload_sha256 = sha256_hex(&payload_canonical); + + let mut sidecar_pre = json!({ + "schema_version": "KVTC7-SPARK-1", + "source_type": "spark_extraction_json", + "payload_sha256": payload_sha256 + }); + + let sidecar_canonical = canonical_json(&sidecar_pre); + let final_state_hash = sha256_hex(&sidecar_canonical); + + sidecar_pre["final_state_hash"] = serde_json::Value::String(final_state_hash); + + let mut pkg = json!({ + "schema": "SPARK-V7-PACKAGE", + "version": 1, + "payload": payload, + "sidecar": sidecar_pre + }); + + if let Some(l) = ledger { + pkg["ledger"] = l; + } + if let Some(r) = ledger_root { + pkg["ledger_root"] = serde_json::Value::String(r.to_string()); + } + + let pkg_canonical = canonical_json(&pkg); + let integrity_hash = sha256_hex(&pkg_canonical); + pkg["integrity_hash"] = serde_json::Value::String(integrity_hash); + + pkg + }; + + // 1. Valid package without ledger + let valid_pkg = make_pkg(json!({"case_id": "SPARK-123"}), None, None); + assert!(verify_package_value(&valid_pkg).is_ok()); + assert!(replay_package_value(&valid_pkg).is_ok()); + + // 2. Missing evidence field -> returns EVIDENCE_LOSS + let mut missing_field_pkg = valid_pkg.clone(); + missing_field_pkg.as_object_mut().unwrap().remove("payload"); + let err = verify_package_value(&missing_field_pkg).unwrap_err(); + assert!(err.to_string().contains("EVIDENCE_LOSS")); + + // 3. Hash manipulation -> returns CONSTRAINT_DRIFT + let mut manipulated_pkg = valid_pkg.clone(); + manipulated_pkg["sidecar"]["payload_sha256"] = + json!("wronghashwronghashwronghashwronghashwronghashwronghashwronghash"); + let err = verify_package_value(&manipulated_pkg).unwrap_err(); + assert!(err.to_string().contains("CONSTRAINT_DRIFT")); + + // 4. Replay fails on verify failure + let err_replay = replay_package_value(&manipulated_pkg).unwrap_err(); + assert!(err_replay.to_string().contains("CONSTRAINT_DRIFT")); + + // 5. Valid package with ledger + let valid_pkg_with_ledger = make_pkg( + json!({"case_id": "SPARK-123"}), + Some(json!([ + {"entry_hash": "hash1", "previous_hash": "0"}, + {"entry_hash": "hash2", "previous_hash": "hash1"} + ])), + Some("hash2"), + ); + assert!(verify_package_value(&valid_pkg_with_ledger).is_ok()); + + // 6. Ledger chaining mismatch -> returns CONSTRAINT_DRIFT + let manipulated_ledger_pkg = make_pkg( + json!({"case_id": "SPARK-123"}), + Some(json!([ + {"entry_hash": "hash1", "previous_hash": "0"}, + {"entry_hash": "hash2", "previous_hash": "wrongchainhash"} + ])), + Some("hash2"), + ); + let err = verify_package_value(&manipulated_ledger_pkg).unwrap_err(); + assert!(err.to_string().contains("CONSTRAINT_DRIFT")); + assert!(err.to_string().contains("ledger chaining mismatch")); + + // 7. Ledger anchoring mismatch -> returns CONSTRAINT_DRIFT + let manipulated_ledger_root_pkg = make_pkg( + json!({"case_id": "SPARK-123"}), + Some(json!([ + {"entry_hash": "hash1", "previous_hash": "0"}, + {"entry_hash": "hash2", "previous_hash": "hash1"} + ])), + Some("wrongroot"), + ); + let err = verify_package_value(&manipulated_ledger_root_pkg).unwrap_err(); + assert!(err.to_string().contains("CONSTRAINT_DRIFT")); + assert!(err.to_string().contains("ledger root anchoring mismatch")); +} From 30656e49f99d30754f224852397aea702ab1ebaa Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Tue, 9 Jun 2026 23:05:55 +0200 Subject: [PATCH 04/27] feat: wire package inspect command --- agy7rust/src/bin/agy_ct.rs | 4 ++-- agy7rust/tests/spark_roundtrip.rs | 26 ++++++++++++++++++++++++++ 2 files changed, 28 insertions(+), 2 deletions(-) diff --git a/agy7rust/src/bin/agy_ct.rs b/agy7rust/src/bin/agy_ct.rs index ea201cb..0943024 100644 --- a/agy7rust/src/bin/agy_ct.rs +++ b/agy7rust/src/bin/agy_ct.rs @@ -204,8 +204,8 @@ fn main() -> Result<()> { PackageCommands::Compress { .. } => { println!("Placeholder: package compress"); } - PackageCommands::Inspect { .. } => { - println!("Placeholder: package inspect"); + PackageCommands::Inspect { input } => { + agy7rust::commands::inspect::run(input)?; } PackageCommands::Verify { input } => { agy7rust::commands::verify_cmd::run(input)?; diff --git a/agy7rust/tests/spark_roundtrip.rs b/agy7rust/tests/spark_roundtrip.rs index dfb27d2..d3afe67 100644 --- a/agy7rust/tests/spark_roundtrip.rs +++ b/agy7rust/tests/spark_roundtrip.rs @@ -1542,3 +1542,29 @@ fn test_package_verify_and_replay_with_structured_errors_and_ledger() { assert!(err.to_string().contains("CONSTRAINT_DRIFT")); assert!(err.to_string().contains("ledger root anchoring mismatch")); } + +#[test] +fn test_agy_ct_package_inspect_execution() { + use std::process::Command; + let output = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "package", + "inspect", + "-i", + "../artifacts/spark/extraction.spkg", + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(output.status.success()); + let stdout_str = String::from_utf8_lossy(&output.stdout); + assert!(stdout_str.contains("schema: SPARK-V7-PACKAGE")); + assert!(stdout_str.contains("source_type: spark_extraction_json")); + assert!(stdout_str.contains("field_paths count:")); + assert!(stdout_str.contains("commitment_tokens count:")); + assert!(stdout_str.contains("tool_sequence count:")); +} From 6ed5e92e911c24db6f13173597bd8587cc5e8b13 Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Tue, 9 Jun 2026 23:17:21 +0200 Subject: [PATCH 05/27] feat: polish package replay output streams --- agy7rust/src/bin/agy_ct.rs | 7 ++- agy7rust/src/commands/replay_cmd.rs | 35 ++++++++++++- agy7rust/src/main.rs | 2 +- agy7rust/tests/spark_roundtrip.rs | 77 +++++++++++++++++++++++++++++ 4 files changed, 117 insertions(+), 4 deletions(-) diff --git a/agy7rust/src/bin/agy_ct.rs b/agy7rust/src/bin/agy_ct.rs index 0943024..994358f 100644 --- a/agy7rust/src/bin/agy_ct.rs +++ b/agy7rust/src/bin/agy_ct.rs @@ -211,7 +211,12 @@ fn main() -> Result<()> { agy7rust::commands::verify_cmd::run(input)?; } PackageCommands::Replay { input } => { - agy7rust::commands::replay_cmd::run(input)?; + let options = agy7rust::commands::replay_cmd::ReplayOptions { + quiet: cli.quiet, + plain: cli.plain, + no_color: cli.no_color, + }; + agy7rust::commands::replay_cmd::run(input, options)?; } PackageCommands::Adversarial { .. } => { println!("Placeholder: package adversarial"); diff --git a/agy7rust/src/commands/replay_cmd.rs b/agy7rust/src/commands/replay_cmd.rs index ff95b9c..ff8ab3d 100644 --- a/agy7rust/src/commands/replay_cmd.rs +++ b/agy7rust/src/commands/replay_cmd.rs @@ -2,7 +2,25 @@ use crate::codec::package::{replay_package_value, sort_json_value}; use anyhow::{Context, Result}; use std::fs; -pub fn run(input_path: &str) -> Result<()> { +#[derive(Default)] +pub struct ReplayOptions { + pub quiet: bool, + pub plain: bool, + pub no_color: bool, +} + +pub fn run(input_path: &str, options: ReplayOptions) -> Result<()> { + if !options.quiet { + if !options.plain && !options.no_color { + eprintln!( + "\x1b[36mReplaying sidecar trace from {}...\x1b[0m", + input_path + ); + } else { + eprintln!("Replaying sidecar trace from {}...", input_path); + } + } + let content = fs::read_to_string(input_path) .with_context(|| format!("Failed to read package file: {}", input_path))?; @@ -11,13 +29,26 @@ pub fn run(input_path: &str) -> Result<()> { match replay_package_value(&package_val) { Ok(replay_val) => { + if !options.quiet { + if !options.plain && !options.no_color { + eprintln!( + "\x1b[32mOK: package verified and trace replayed successfully\x1b[0m" + ); + } else { + eprintln!("OK: package verified and trace replayed successfully"); + } + } let sorted_replay = sort_json_value(&replay_val); let pretty_str = serde_json::to_string_pretty(&sorted_replay)?; println!("{}", pretty_str); Ok(()) } Err(e) => { - eprintln!("replay failed: {}", e); + if !options.plain && !options.no_color { + eprintln!("\x1b[31mreplay failed: {}\x1b[0m", e); + } else { + eprintln!("replay failed: {}", e); + } Err(e) } } diff --git a/agy7rust/src/main.rs b/agy7rust/src/main.rs index 3c2dcfb..11753f9 100644 --- a/agy7rust/src/main.rs +++ b/agy7rust/src/main.rs @@ -15,7 +15,7 @@ fn main() -> anyhow::Result<()> { agy7rust::commands::verify_cmd::run(&input)?; } Commands::Replay { input } => { - agy7rust::commands::replay_cmd::run(&input)?; + agy7rust::commands::replay_cmd::run(&input, Default::default())?; } Commands::Adversarial { input } => { agy7rust::commands::adversarial::run(&input)?; diff --git a/agy7rust/tests/spark_roundtrip.rs b/agy7rust/tests/spark_roundtrip.rs index d3afe67..d9fb7a2 100644 --- a/agy7rust/tests/spark_roundtrip.rs +++ b/agy7rust/tests/spark_roundtrip.rs @@ -1568,3 +1568,80 @@ fn test_agy_ct_package_inspect_execution() { assert!(stdout_str.contains("commitment_tokens count:")); assert!(stdout_str.contains("tool_sequence count:")); } + +#[test] +fn test_agy_ct_package_replay_output_streams() { + use std::process::Command; + + // 1. Standard run (should output status on stderr with color codes, and JSON on stdout) + let output = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "package", + "replay", + "-i", + "../artifacts/spark/extraction.spkg", + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(output.status.success()); + let stdout_str = String::from_utf8_lossy(&output.stdout); + let stderr_str = String::from_utf8_lossy(&output.stderr); + + // Verify stdout contains the replayed JSON schema + assert!(stdout_str.contains("\"schema\": \"SPARK-V7-REPLAY\"")); + // Verify stderr contains status and color escapes + assert!(stderr_str.contains("Replaying sidecar trace")); + assert!(stderr_str.contains("\x1b[36m")); // cyan color code for status + + // 2. Quiet run (should output JSON on stdout, but stderr should be empty/contain no status messages) + let output_quiet = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "--quiet", + "package", + "replay", + "-i", + "../artifacts/spark/extraction.spkg", + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(output_quiet.status.success()); + let stdout_quiet = String::from_utf8_lossy(&output_quiet.stdout); + let stderr_quiet = String::from_utf8_lossy(&output_quiet.stderr); + + assert!(stdout_quiet.contains("\"schema\": \"SPARK-V7-REPLAY\"")); + assert!(!stderr_quiet.contains("Replaying sidecar trace")); + + // 3. Plain run (should output JSON on stdout, status on stderr but without ANSI escapes) + let output_plain = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "--plain", + "package", + "replay", + "-i", + "../artifacts/spark/extraction.spkg", + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(output_plain.status.success()); + let stdout_plain = String::from_utf8_lossy(&output_plain.stdout); + let stderr_plain = String::from_utf8_lossy(&output_plain.stderr); + + assert!(stdout_plain.contains("\"schema\": \"SPARK-V7-REPLAY\"")); + assert!(stderr_plain.contains("Replaying sidecar trace")); + assert!(!stderr_plain.contains("\x1b[")); +} From 52da3418972668b55dd537cfffb4c4445bffd882 Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Tue, 9 Jun 2026 23:20:40 +0200 Subject: [PATCH 06/27] docs: record local Sparkctl development checkpoint --- docs/SPARK_ALIGNMENT.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/SPARK_ALIGNMENT.md b/docs/SPARK_ALIGNMENT.md index 5f80d8c..c1e6f85 100644 --- a/docs/SPARK_ALIGNMENT.md +++ b/docs/SPARK_ALIGNMENT.md @@ -39,3 +39,33 @@ We explicitly do **not** claim: Legacy / future concepts such as XENTRY/OBD log sandwich models, consonant signature mapping, sparse micro-frame synopsis, and error correction layers are completely excluded from the active SPARK alignment scope. +## Local Development Checkpoint + +This checkpoint records the current local development state. Current checkpoint is local-only; push/PR/release are outside this checkpoint. + +### 1. Active Settings & Path Configurations +* **Active Agent Skills:** `.agents/skills` is established as the active Antigravity skill path for local workspace coordination. +* **Legacy Compatibility:** The `.agent/skills` directory remains as legacy/compatibility metadata only. + +### 2. CLI Command Wiring +The following `agy-ct package` subcommands are fully wired and functional: +* **`agy-ct package verify`** — wired to `verify_cmd::run` +* **`agy-ct package replay`** — wired to `replay_cmd::run` +* **`agy-ct package inspect`** — wired to `inspect::run` + +### 3. Replay UX Stream Separation +The `package replay` command implements a strict separation of output streams: +* `stdout` is reserved exclusively for the replayed machine-readable JSON trace. +* `stderr` outputs status messages, progress updates, and validation warnings. +* Global CLI flags `--quiet` (suppresses status output), `--plain` (strips ANSI escapes), and `--no-color` (disables terminal color codes) are explicitly supported. + +### 4. Test and Placeholders Status +* **Validation Status:** The local Rust test suite executes successfully with **65 PASS** tests. +* **Remaining Placeholders:** The subcommands `package compress`, `package adversarial`, `context build`, `context render`, `context validate`, and `schema check` remain as placeholders. + +### 5. Exclusion and Alignment Boundaries +* **XENTRY/OBD/X-Engine:** Legacy/future diagnostic components (including OBD-II logs and X-Engine sandwich parsers) remain completely excluded from the active scope. +* **Synthetic-Only:** All testing and demonstration data remains strictly synthetic. +* **Human-Review:** Mandated human-in-the-loop review boundaries remain enforced; provider output is untrusted. +* **Non-Certified:** No certifications, official compliance statements, or production/forensic readiness claims are asserted. + From 109453a35b4867c57b1efdea49ee745682b71d3b Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Tue, 9 Jun 2026 23:25:46 +0200 Subject: [PATCH 07/27] feat: wire schema check command --- agy7rust/src/bin/agy_ct.rs | 4 +-- agy7rust/tests/spark_roundtrip.rs | 46 +++++++++++++++++++++++++++++++ 2 files changed, 48 insertions(+), 2 deletions(-) diff --git a/agy7rust/src/bin/agy_ct.rs b/agy7rust/src/bin/agy_ct.rs index 994358f..6c89600 100644 --- a/agy7rust/src/bin/agy_ct.rs +++ b/agy7rust/src/bin/agy_ct.rs @@ -237,8 +237,8 @@ fn main() -> Result<()> { } }, Commands::Schema { subcommand } => match subcommand { - SchemaCommands::Check { .. } => { - println!("Placeholder: schema check"); + SchemaCommands::Check { input, schema } => { + agy7rust::commands::schema_check::run(input, schema)?; } }, Commands::Report { subcommand } => match subcommand { diff --git a/agy7rust/tests/spark_roundtrip.rs b/agy7rust/tests/spark_roundtrip.rs index d9fb7a2..35e154a 100644 --- a/agy7rust/tests/spark_roundtrip.rs +++ b/agy7rust/tests/spark_roundtrip.rs @@ -1645,3 +1645,49 @@ fn test_agy_ct_package_replay_output_streams() { assert!(stderr_plain.contains("Replaying sidecar trace")); assert!(!stderr_plain.contains("\x1b[")); } + +#[test] +fn test_agy_ct_schema_check_execution() { + use std::process::Command; + + // 1. Valid call (should return exit status success) + let output = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "schema", + "check", + "-i", + "../examples/spark/extraction.json", + "-s", + "../schemas/genehmigung_v1.json", + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(output.status.success()); + let stdout_str = String::from_utf8_lossy(&output.stdout); + assert!(stdout_str.contains("OK: schema-check passed")); + assert!(stdout_str.contains("schema: genehmigung_v1")); + + // 2. Invalid call (should fail) + let output_fail = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "schema", + "check", + "-i", + "../examples/spark/pdf_extraction_fixture.json", + "-s", + "../schemas/genehmigung_v1.json", + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(!output_fail.status.success()); +} From c74df75a1765adccc8605455eb840ba62ec17328 Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Tue, 9 Jun 2026 23:38:04 +0200 Subject: [PATCH 08/27] docs: clarify Antigravity hook governance --- docs/SPARK_HACKATHON_SETUP.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/SPARK_HACKATHON_SETUP.md b/docs/SPARK_HACKATHON_SETUP.md index 3e4d6d4..6f88afd 100644 --- a/docs/SPARK_HACKATHON_SETUP.md +++ b/docs/SPARK_HACKATHON_SETUP.md @@ -63,7 +63,19 @@ The following operations are strictly forbidden in this workspace and are blocke * Reading secrets or keys (`.env`, credentials, SSH files) * Web server deployments (`vercel`, `netlify`, `wrangler deploy`, etc.) -## 5. Validation Plan +## 5. Hook and Skill Governance + +The workspace enforces governance and boundaries using a combination of local skills and client hook configurations: + +* **Active Skill Path:** The `.agents/skills` directory is the active Antigravity-compatible skill path for workspace-specific slash command registration. +* **Legacy Path:** The `.agent/skills` directory is kept for legacy compatibility metadata only. +* **Codex-Specific Hooks:** The scripts located in `.codex/hooks/` and configured in `.codex/hooks.json` are Codex-specific guardrails. They are not natively executed or loaded by the Antigravity CLI. +* **Optional Antigravity Customizations:** Native Antigravity plugins or global hooks (in the user's home configuration) are optional and not currently required for local work in this repository. +* **Governing Local Control:** The policies in `AGENTS.md` and the compiled instructions under `.agents/skills/` serve as the primary local control and operating boundaries for active agent sessions. +* **Recommended Execution Mode:** The `proceed-in-sandbox` execution configuration is the recommended local operating mode to ensure native OS process containment (AppContainer on Windows, nsjail on Linux, sandbox-exec on macOS). +* **No Absolute Security Guarantees:** Hooks and sandbox settings serve as developer-facing guardrails and process-isolation mechanisms. They do not constitute an absolute security guarantee or certification against intentional bypasses or underlying system vulnerabilities. + +## 6. Validation Plan To validate the code offline, run the safe local check suite: 1. Run `cargo fmt --all --check` to verify code style formatting. @@ -73,11 +85,11 @@ To validate the code offline, run the safe local check suite: Do not run `agy-ct run`, `agy-ct demo`, or `agy-ct benchmark` unless the final reports and artifacts are specifically requested for human review. -## 6. Synthetic-Data-Only Rule +## 7. Synthetic-Data-Only Rule All planning modules, extractors, and validators operate exclusively against static mock datasets (e.g. `examples/spark/extraction.json`). Processing of real citizen, administrator, or live public-sector cases is strictly prohibited. -## 7. Safety Non-Claims & Technology Exclusions +## 8. Safety Non-Claims & Technology Exclusions The `CompText-Sparkctl` workflow enforces the following non-claims and exclusions: * **No Official SPARK Schema Compatibility:** All SPARK-oriented terminology is conceptual mock-up and synthetic schema alignment. From 50121d78fc38be8e382eb31077f6baa6faa0e9f9 Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Tue, 9 Jun 2026 23:44:15 +0200 Subject: [PATCH 09/27] feat: wire context validate command --- agy7rust/src/bin/agy_ct.rs | 4 +- agy7rust/tests/spark_roundtrip.rs | 100 ++++++++++++++++++++++++++++++ 2 files changed, 102 insertions(+), 2 deletions(-) diff --git a/agy7rust/src/bin/agy_ct.rs b/agy7rust/src/bin/agy_ct.rs index 6c89600..5a9859d 100644 --- a/agy7rust/src/bin/agy_ct.rs +++ b/agy7rust/src/bin/agy_ct.rs @@ -229,8 +229,8 @@ fn main() -> Result<()> { ContextCommands::Render { .. } => { println!("Placeholder: context render"); } - ContextCommands::Validate { .. } => { - println!("Placeholder: context validate"); + ContextCommands::Validate { input, schema: _ } => { + agy7rust::commands::context_validate::run(input)?; } ContextCommands::All => { sparkctl::context_all::run_context_all()?; diff --git a/agy7rust/tests/spark_roundtrip.rs b/agy7rust/tests/spark_roundtrip.rs index 35e154a..22be966 100644 --- a/agy7rust/tests/spark_roundtrip.rs +++ b/agy7rust/tests/spark_roundtrip.rs @@ -1691,3 +1691,103 @@ fn test_agy_ct_schema_check_execution() { assert!(!output_fail.status.success()); } + +#[test] +fn test_agy_ct_context_validate_execution() { + use serde_json::json; + use std::fs; + use std::process::Command; + + let temp_dir = std::env::temp_dir(); + let valid_path = temp_dir.join("test_valid_context.json"); + let invalid_path = temp_dir.join("test_invalid_context.json"); + + // 1. Create a minimal valid context JSON + let valid_ctx = json!({ + "context_id": "ctx-valid-123", + "source_package_hash": "hash-123", + "schema_name": "schema-123", + "schema_version": 1, + "required_field_paths": ["$.field1"], + "satisfied_field_paths": ["$.field1"], + "missing_field_paths": [], + "constraints": [], + "required_order": [], + "dependency_edges": [], + "blockers": [], + "recovery_paths": [], + "validation": { + "valid": true, + "failure_labels": [], + "issues": [] + }, + "non_claims": ["some_claim"] + }); + + fs::write(&valid_path, serde_json::to_string(&valid_ctx).unwrap()).unwrap(); + + // 2. Create a minimal invalid context JSON + let invalid_ctx = json!({ + "context_id": "ctx-invalid-123", + "source_package_hash": "hash-123", + "schema_name": "schema-123", + "schema_version": 1, + "required_field_paths": ["$.field1"], + "satisfied_field_paths": [], + "missing_field_paths": ["$.field1"], + "constraints": [], + "required_order": [], + "dependency_edges": [], + "blockers": [], + "recovery_paths": [], + "validation": { + "valid": false, + "failure_labels": ["MISSING_REQUIRED_FIELD"], + "issues": ["field1 is missing"] + }, + "non_claims": ["some_claim"] + }); + + fs::write(&invalid_path, serde_json::to_string(&invalid_ctx).unwrap()).unwrap(); + + // 3. Test valid context validation (should return exit status success) + let output_valid = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "context", + "validate", + "-i", + valid_path.to_str().unwrap(), + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(output_valid.status.success()); + let stdout_str = String::from_utf8_lossy(&output_valid.stdout); + assert!(stdout_str.contains("OK: context-validate passed")); + assert!(stdout_str.contains("context: ctx-valid-123")); + + // 4. Test invalid context validation (should fail) + let output_invalid = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "context", + "validate", + "-i", + invalid_path.to_str().unwrap(), + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(!output_invalid.status.success()); + + // 5. Cleanup + let _ = fs::remove_file(valid_path); + let _ = fs::remove_file(invalid_path); +} From a3c25e263dcb799aba7d211306fdedf466602a98 Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Tue, 9 Jun 2026 23:52:21 +0200 Subject: [PATCH 10/27] feat: wire context build command --- agy7rust/src/bin/agy_ct.rs | 8 +++-- agy7rust/tests/spark_roundtrip.rs | 53 +++++++++++++++++++++++++++++++ 2 files changed, 59 insertions(+), 2 deletions(-) diff --git a/agy7rust/src/bin/agy_ct.rs b/agy7rust/src/bin/agy_ct.rs index 5a9859d..e202311 100644 --- a/agy7rust/src/bin/agy_ct.rs +++ b/agy7rust/src/bin/agy_ct.rs @@ -223,8 +223,12 @@ fn main() -> Result<()> { } }, Commands::Context { subcommand } => match subcommand { - ContextCommands::Build { .. } => { - println!("Placeholder: context build"); + ContextCommands::Build { + input, + schema, + output, + } => { + agy7rust::commands::context_build::run(input, schema, output)?; } ContextCommands::Render { .. } => { println!("Placeholder: context render"); diff --git a/agy7rust/tests/spark_roundtrip.rs b/agy7rust/tests/spark_roundtrip.rs index 22be966..22a781e 100644 --- a/agy7rust/tests/spark_roundtrip.rs +++ b/agy7rust/tests/spark_roundtrip.rs @@ -1791,3 +1791,56 @@ fn test_agy_ct_context_validate_execution() { let _ = fs::remove_file(valid_path); let _ = fs::remove_file(invalid_path); } + +#[test] +fn test_agy_ct_context_build_execution() { + use agy7rust::codec::package::build_package_from_value; + use std::fs; + use std::process::Command; + + let temp_dir = std::env::temp_dir(); + let temp_package_path = temp_dir.join("test_package.spkg"); + let temp_context_path = temp_dir.join("test_context.json"); + + // 1. Read and parse extraction.json, build spkg dynamically in memory + let input_content = fs::read_to_string("../examples/spark/extraction.json").unwrap(); + let input_value: serde_json::Value = serde_json::from_str(&input_content).unwrap(); + let package_value = build_package_from_value(&input_value).unwrap(); + + // 2. Write spkg to tempdir + let package_json = serde_json::to_string(&package_value).unwrap(); + fs::write(&temp_package_path, &package_json).unwrap(); + + // 3. Invoke context build CLI (should return exit status success) + let output = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "context", + "build", + "-i", + temp_package_path.to_str().unwrap(), + "-s", + "../schemas/genehmigung_v1.json", + "-o", + temp_context_path.to_str().unwrap(), + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(output.status.success()); + let stdout_str = String::from_utf8_lossy(&output.stdout); + assert!(stdout_str.contains("OK: context-build passed")); + assert!(stdout_str.contains("context:")); + + // 4. Verify context was created in temp dir and is readable + assert!(temp_context_path.exists()); + let context_content = fs::read_to_string(&temp_context_path).unwrap(); + assert!(context_content.contains("\"context_id\":")); + + // 5. Cleanup + let _ = fs::remove_file(temp_package_path); + let _ = fs::remove_file(temp_context_path); +} From c3b4a863faf426fa15f9370eebd7fc6efc34beda Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Wed, 10 Jun 2026 00:02:59 +0200 Subject: [PATCH 11/27] docs: refresh README for Spark Hackathon --- README.md | 385 ++++++++++++------------------------------------------ 1 file changed, 80 insertions(+), 305 deletions(-) diff --git a/README.md b/README.md index b8067ec..47ed9c0 100644 --- a/README.md +++ b/README.md @@ -1,356 +1,131 @@ -# CompText-Sparkctl +# Sparkctl -
- -**Deterministic Rust CLI for CompText trace packaging, replay-sidecar validation, and SPARK-style context artifacts.** - -![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square) -![Rust CLI](https://img.shields.io/badge/Rust-CLI-000000.svg?style=flat-square&logo=rust&logoColor=white) -![SHA-256 Sidecar](https://img.shields.io/badge/SHA--256-Sidecar-red.svg?style=flat-square) -![SPARK Context Artifacts](https://img.shields.io/badge/SPARK-Context%20Artifacts-2b6cb0.svg?style=flat-square) - -
- ---- - -## Overview - -**CompText-Sparkctl** is a local Rust command-line toolkit for turning agent or operational traces into compact, verifiable packages and SPARK-style context artifacts. - -The project is built around one hard rule: **compression must not destroy replay-critical state**. CompText separates compact linguistic payloads from replay-sensitive metadata, then validates the result with a replay sidecar, SHA-256 integrity anchors, schema checks, and offline context validation flows. - -The repository currently exposes two CLI entry points: - -- `sparkctl` — the validated compatibility surface for local diagnostics, Rust validation, context pipeline checks, demo execution, and handoff checks. -- `agy-ct` — the newer CompText command surface, currently wired to safe compatibility wrappers for selected existing `sparkctl` functionality. - -Previously, this project used the working name **Antigravity-CompText v7**. The current public project name is **CompText-Sparkctl**. +**Lokaler Prototyp im Kontext des BMDS/SPARK-Hackathons: Evidence-, Replay- und Validierungsschicht für SPARK-artige Verwaltungs-KI-Workflows.** --- -## What it does - -CompText-Sparkctl validates the split between compressible trace content and replay-critical state: +## Status und Eigenschaften -| Layer | Purpose | Target property | -|---|---|---| -| **CompText payload** | Pruned, compact linguistic trace | Lower token and transport cost | -| **Replay sidecar** | Tool sequence, commitments, hashes, state anchors | Deterministic reconstruction in the validated scope | -| **SHA-256 audit chain** | Integrity metadata over critical replay data | Tamper-sensitive validation | -| **Holdout validator** | Non-adaptive replay verification | Stable replay score in benchmark runs | -| **SPARK context artifacts** | Structured operational context and rendered summaries | Local validation and handoff readiness | +- **Typ:** Prototyp / Konzept-Demo +- **Datenbasis:** Rein synthetisch (*Synthetic-only*) +- **Freigabe:** Erfordert menschliche Prüfung (*Human Review Required / Human-in-the-Loop*) +- **Technologie:** Rust CLI (`agy-ct` und `sparkctl`) +- **Architektur:** Lokal-first (*Local-first / Offline*) +- **Einschränkung:** Keine Aussage zur Produktivreife, Rechtskonformität oder behördlichen Zertifizierung (*No production/legal/compliance claims*) -Classic lossy compression fails when validators expect exact tool order, commitment tokens, state hashes, and canonical replay strings. CompText-Sparkctl keeps those replay-sensitive fields outside the lossy zone. +*Kernsatz: Modelle sind Provider, Kontext ist das Produkt.* --- -## Command Surface +## Architektur-Übersicht -### `sparkctl` - -`sparkctl` is the validated operations controller: - -```bash -cd agy7rust -cargo run --bin sparkctl -- doctor -cargo run --bin sparkctl -- rust-validate -cargo run --bin sparkctl -- context-all -cargo run --bin sparkctl -- spark-demo -cargo run --bin sparkctl -- handoff-check +```mermaid +flowchart LR + A[Synthetischer Verwaltungs-Trace] --> B[Schema Check] + B --> C[Context Build] + C --> D[Evidence Package] + D --> E[Package Verify] + E --> F[Replay] + F --> G[Human Review Gate] + + E --> H{Fehler?} + H -->|EVIDENCE_LOSS| I[Nachweis fehlt] + H -->|CONSTRAINT_DRIFT| J[Hash/Constraint Drift] ``` -Validated command responsibilities: - -- `sparkctl doctor` checks local project readiness. -- `sparkctl rust-validate` runs local Rust quality checks. -- `sparkctl context-all` runs the local context build/render/validate sequence. -- `sparkctl spark-demo` runs the local end-to-end demonstration flow. -- `sparkctl handoff-check` checks local repository handoff readiness. - -### `agy-ct` - -`agy-ct` is the newer command surface for CompText-Sparkctl. It currently provides the command tree and safe compatibility wrappers without introducing a new run orchestrator. +--- -```bash -cd agy7rust -cargo run --bin agy-ct -- --help -cargo run --bin agy-ct -- doctor -cargo run --bin agy-ct -- validate -cargo run --bin agy-ct -- handoff -cargo run --bin agy-ct -- demo -cargo run --bin agy-ct -- context all -``` +## Warum relevant für den SPARK-Hackathon? -Current wrapper mapping: +Der SPARK-Hackathon („Schnellere Planung und Realisierung durch KI“) sucht nach Wegen, Verwaltungsverfahren mithilfe von KI-Systemen sicherer und effizienter zu gestalten. -| `agy-ct` command | Existing validated backend | -|---|---| -| `agy-ct doctor` | `sparkctl::doctor::run_doctor()` | -| `agy-ct validate` | `sparkctl::rust_validate::run_rust_validate()` | -| `agy-ct handoff` | `sparkctl::handoff_check::run_handoff_check()` | -| `agy-ct demo` | `sparkctl::spark_demo::run_spark_demo()` | -| `agy-ct context all` | `sparkctl::context_all::run_context_all()` | +**Sparkctl** greift hierbei an einer kritischen Stelle an: +- **Keine autonome Entscheidung:** Das Tool trifft keine eigenen inhaltlichen oder rechtlichen Entscheidungen. +- **Kontext-Sicherung:** Es sorgt dafür, dass die an KI-Modelle übergebenen Kontextdaten (Traces) strukturiert, reproduzierbar und für den menschlichen Bearbeiter vollständig nachvollziehbar bleiben. +- **Prüfbarkeit:** Durch die Trennung von komprimierbarem Fließtext und aufzeichnungsrelevanten Metadaten bleibt die Historie der Bearbeitungsschritte auditierbar. -Other `agy-ct` commands remain explicit placeholders until their implementation phase is approved. +Dies ermöglicht sichere, transparente und nachvollziehbare Prototyp-Workflows für die KI-gestützte Sachbearbeitung. --- -## SPARK Context Artifacts - -The local SPARK-style demo and context pipeline generates and validates artifacts under `artifacts/spark/`: +## Was der Prototyp lokal kann -- `artifacts/spark/extraction.spkg` — compact trace package containing payload and replay-sidecar metadata. -- `artifacts/spark/context.json` — structured operational context for validation and handoff. -- `artifacts/spark/context_render.txt` — token-light rendered context view for review and summarization. +Sparkctl implementiert folgende Mechanismen zur Absicherung synthetischer Planungsdaten: -These artifacts are intended for local, reproducible validation and review workflows. +- **Verify-before-Replay:** Vor jedem Replay-Durchlauf wird die strukturelle Integrität des Pakets verifiziert. +- **Fehlererkennung:** + - `EVIDENCE_LOSS`: Erkennt, wenn für die Wiederholung notwendige Nachweise im Paket fehlen. + - `CONSTRAINT_DRIFT`: Erkennt Manipulationen an Hashes oder verankerten Integritätsbedingungen. +- **Kryptografische Absicherung:** Nutzung von *canonical JSON* zur deterministischen Serialisierung und einer darauf aufbauenden *SHA-256 Hash-Chain* zur lückenlosen Protokollierung. +- **Grobübersicht der implementierten Befehle:** + - `agy-ct package verify`: Prüft SHA-256 Signaturen und Verkettungen. + - `agy-ct package replay`: Rekonstruiert die aufgezeichnete Trace deterministisch (strikte stdout/stderr Kanaltrennung). + - `agy-ct package inspect`: Zeigt Metadaten und Header-Einträge. + - `agy-ct schema check`: Abgleich von Traces gegen JSON-Schemas. + - `agy-ct context validate`: Führt strukturelle Validierung und Leckprüfungen auf Kontextmodellen durch. + - `agy-ct context build`: Erzeugt strukturierte operative Kontextmodelle. -### Demo Evidence - -Demo evidence: -- SPARK challenge demo evidence: [DEMO_SPARK_EVIDENCE.md](DEMO_SPARK_EVIDENCE.md) -- Local performance baseline: [PERFORMANCE_BASELINE.md](PERFORMANCE_BASELINE.md) +--- -#### Reviewer Quickstart +## Quickstart (Lokal) -To execute the reviewer evidence flow and local/offline validation check: +Führen Sie die folgenden sicheren lokalen Befehle im Rust-Unterverzeichnis aus: ```bash +# In das Rust-Verzeichnis wechseln cd agy7rust -cargo run --bin agy-ct -- run -cargo run --bin agy-ct -- benchmark -``` - -Benchmark output is local and environment-specific, and generated report files under `reports/` are not required to be committed. These commands generate and verify SPARK-style evidence artifacts. - ---- -## Architecture +# Testsuite ausführen (67+ Tests) +cargo test -```mermaid -flowchart TD - raw["Raw Agent / Operational Trace"] - - subgraph split["CompText Split Layer"] - splitter["Trace Splitter"] - classifier["Replay-Critical Field Classifier"] - end - - subgraph payload["Compressible Payload Stream"] - text["Linguistic Payload"] - prune["Redundancy Pruning"] - compact["Compact Payload"] - end - - subgraph sidecar["Replay Sidecar"] - order["Tool Order"] - commits["Commitment Tokens"] - state["State Hashes"] - anchors["Validation Anchors"] - end - - subgraph context["SPARK Context Layer"] - ctxbuild["context-build"] - ctxrender["context-render"] - ctxvalidate["context-validate"] - end - - subgraph integrity["Integrity Layer"] - canon["Canonical Metadata Serialization"] - hash["SHA-256 Hash Anchor"] - chain["Audit Chain"] - end - - raw --> splitter - splitter --> classifier - classifier --> text - text --> prune - prune --> compact - classifier --> order - classifier --> commits - classifier --> state - classifier --> anchors - anchors --> ctxbuild - ctxbuild --> ctxrender - ctxbuild --> ctxvalidate - order --> canon - commits --> canon - state --> canon - anchors --> canon - canon --> hash - hash --> chain -``` - -### Compression contract - -```mermaid -flowchart LR - subgraph lossy["Loss-Aware Zone"] - A["Natural-language trace text"] - B["Redundant reasoning prose"] - C["Verbose intermediate context"] - end - - subgraph lossless["Lossless Zone"] - D["Tool sequence"] - E["Commitment tokens"] - F["State hashes"] - G["Replay anchors"] - H["Context validation anchors"] - end - - subgraph output["CompText Package"] - I["Compact payload"] - J["Replay sidecar"] - K["SHA-256 audit chain"] - end - - A --> I - B --> I - C --> I - D --> J - E --> J - F --> J - G --> J - H --> J - J --> K - I --> K +# Schema-Check mit synthetischen Beispieldaten ausführen +cargo run --bin agy-ct -- schema check --input ../examples/spark/extraction.json --schema ../schemas/genehmigung_v1.json ``` ---- - -## Rust Integration - -Rust is the hardened local execution path for components that need to be fast, auditable, and deterministic in the validated scope: - -- byte-level payload handling -- deterministic hashing and verification -- replay-sidecar validation -- schema-sidecar validation -- operational context build/render/validate flows -- local CLI validation and handoff checks - -Python remains useful as a reference and experimentation layer. Rust is the direction for hardened execution. - ---- - -## Safety, Boundaries & Claim Hygiene - -- **Offline execution:** Validated commands operate locally. Offline behavior was deterministic in the validated test scope. -- **Leak boundaries:** Configured leak checks passed in the validated scope. -- **Local handoff checks:** `sparkctl handoff-check` checks local repository readiness and file availability only; it does not verify remote CI or GitHub Actions status. -- **SPARK:** No official SPARK compatibility claim is made. -- **Compliance:** No compliance claim, including EU AI Act compliance, is made. -- **Risk statement:** No blocking risks found in the validated scope. - -Non-claims: - -- no legal evidentiary-status claim -- no forensic certainty claim -- no MCP server capability claim -- no RAG, embeddings, vector database, or external tool-orchestration layer -- no production-readiness, certification, or compliance claim +*Hinweis: Befehle, die Berichte oder veränderte Artefakte generieren, sind optional und dienen dem manuellen Review-Prozess.* --- -## Benchmarks - -Current validation targets are based on the existing CompText v7 benchmark profile: +## Agenten-Setup & Governance -| Group | Strategy | Avg. Payload | Replay Validity | Notes | -|---|---:|---:|---:|---| -| A | Raw baseline | 2023.9 bytes | 1.00 | No compression | -| B | CompText v7 | **744.4 bytes** | **1.00** | **63.2 % reduction** | -| C | Regex pruning | ~68 % of raw | 1.00 | No forensic integrity | -| D/E | Blind reduction | variable | 0.0 on complex traces | Loses temporal/state-critical tokens | +Dieses Repository nutzt klare Richtlinien für die lokale Ausführung von KI-Entwicklungsagenten (z. B. Antigravity): -The design goal is not maximum textual compression at any cost. The goal is maximum safe reduction under strict replay constraints. +- **Regelwerk:** Die [AGENTS.md](AGENTS.md) ist das maßgebliche lokale Steuerungswerkzeug. +- **Skill-Pfad:** Das Verzeichnis `.agents/skills/` dient als aktiver Antigravity-Skill-Pfad. +- **Codex-Hooks:** Skripte unter `.codex/hooks/` sind Codex-spezifisch und bieten keine Ausführungs- oder Sicherheitsgarantie für Antigravity-Sitzungen. +- **Sicherheits-Modus:** Empfohlen wird die Ausführung im Sandbox-Modus (`proceed-in-sandbox`). --- -## Repository Map - -```text -. -├── .agent/ # Local agent skills used for gated implementation -├── .antigravitycli/ # Local agent runtime configuration -├── Comptextv7/ # CompText v7 integration surface -├── agy7rust/ # Rust CLI path for packaging, validation, and context flows -├── artifacts/spark/ # Generated SPARK-style demo/package/context artifacts -├── assets/branding/ # Project branding assets -├── benchmarks/ # Benchmark profiles and comparison material -├── core/ # KVTC / replay core components -├── datasets/ # Fixtures and trace datasets -├── examples/spark/ # SPARK-style extraction fixtures and demo input -├── reports/ # Evaluation notes and generated reports -├── schemas/ # JSON schema sidecar fixtures -├── tests/ # Holdout, replay, and integrity tests -└── README.md # Project landing page -``` - ---- +## Grenzen und Non-Claims -## Project Phase Status +Um Missverständnisse im Rahmen des SPARK-Hackathons auszuschließen, gelten folgende Grenzen: -- **Phase 3:** Operational context layer — complete. -- **Phase 4:** `sparkctl` command surface — complete. -- **Phase 5:** Release README and branding integration — complete. -- **Phase 6A:** `agy-ct` CLI architecture handbook — complete. -- **Phase 6B:** `agy-ct` binary and command tree — complete. -- **Phase 6C:** `agy-ct` compatibility wrappers — complete in the validated command scope. +- **Kein offizielles Produkt:** Sparkctl ist kein offizielles Produkt des BMDS (Bundesministerium für Digitales und Verkehr) oder seiner Partner. +- **Keine Produktivfreigabe:** Der Code ist ein reiner Prototyp für Testzwecke. +- **Keine Rechts- oder Compliance-Garantie:** Es wird keine rechtliche Beratung oder forensische Nachweissicherheit geboten. +- **Keine EU-AI-Act-Konformität:** Es wird keine Konformitätsbewertung oder Konformitätsgarantie nach dem EU AI Act gegeben. +- **Keine autonomen Entscheidungen:** Das System ersetzt zu keinem Zeitpunkt den menschlichen Review (*Mandatory Human-in-the-Loop*). +- **Keine Echtdaten:** Es werden ausschließlich künstliche (synthetische) Testdaten verarbeitet. Die Verarbeitung realer Bürger- oder Behördendaten ist ausgeschlossen. +- **Kein Diagnosefokus:** Legacy-Konzepte wie XENTRY, OBD-II oder X-Engine-Diagnoseschnittstellen sind ausdrücklich nicht Teil des aktiven SPARK-Scopes. --- ## Roadmap -- [x] Deterministic replay-sidecar architecture -- [x] SHA-256 integrity anchoring -- [x] Holdout-oriented validation profile -- [x] Rust execution path introduced -- [x] SPARK-style extraction package format -- [x] Schema-driven sidecar extraction -- [x] Offline SPARK demo fixtures -- [x] SPARK operational context model -- [x] SPARK context build/render/validate CLI flow -- [x] Unified `sparkctl` CLI -- [x] `agy-ct` command surface -- [x] `agy-ct` compatibility wrappers -- [ ] `agy-ct run` orchestrator -- [ ] JSON report export -- [ ] Notebook bundle/export -- [ ] Context compiler roadmap -- [ ] Agent-control event model -- [ ] Fresh-clone GitHub verification workflow - ---- - -## Contributing +### Aktuell Offen (Platzhalter-Befehle): +- `context render`: Generierung sprachlich reduzierter Zusammenfassungen. +- `package compress`: Algorithmen zur verlustbehafteten Trace-Kompression unter Beibehaltung kritischer Hashes. +- `package adversarial`: Robustheitstests gegen gezielte Manipulationen. -Contributions are welcome, especially work that improves determinism, compression quality, auditability, Rust hardening, SPARK-style administrative AI verification, or reproducible validation. - -Good first contribution areas: - -- add new trace fixtures -- add SPARK-style extraction fixtures -- improve benchmark coverage -- document edge cases -- add Rust-side validation tests -- tighten schema-sidecar checks -- improve CI reproducibility -- extend operational context validation while preserving leak boundaries - -Please keep pull requests small, reproducible, and validation-oriented. - ---- - -## License - -This project is released under the MIT License. +### Zukünftige Schritte: +- Erweiterung der synthetischen Planungs-Fixtures. +- Evaluierung von Community-Feedback zu Evidence-Strukturen. +- Optionale native Plugin- und Hook-Integrationen für verbesserte Absicherung. --- -
- -**CompText-Sparkctl: compress the noise, preserve the proof.** +## Community -
+- **Feedback & Issues:** Fragen, Anregungen oder Fehlerberichte zu den Prototypen sind via GitHub Issues willkommen. +- **Fokus auf Synthetik:** Bitte posten Sie in den Issues oder Diskussionen niemals echte Verwaltungs- oder Bürgerdaten. Verwenden Sie stets anonymisierte oder synthetische Beispieldaten. From 7e3c8501338dde7b07775455ff835fbe8bdeacd9 Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Wed, 10 Jun 2026 12:04:48 +0200 Subject: [PATCH 12/27] docs: sync Spark alignment checkpoint --- docs/SPARK_ALIGNMENT.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/SPARK_ALIGNMENT.md b/docs/SPARK_ALIGNMENT.md index c1e6f85..8aa9e8f 100644 --- a/docs/SPARK_ALIGNMENT.md +++ b/docs/SPARK_ALIGNMENT.md @@ -48,10 +48,13 @@ This checkpoint records the current local development state. Current checkpoint * **Legacy Compatibility:** The `.agent/skills` directory remains as legacy/compatibility metadata only. ### 2. CLI Command Wiring -The following `agy-ct package` subcommands are fully wired and functional: +The following `agy-ct` subcommands are fully wired and functional: * **`agy-ct package verify`** — wired to `verify_cmd::run` * **`agy-ct package replay`** — wired to `replay_cmd::run` * **`agy-ct package inspect`** — wired to `inspect::run` +* **`agy-ct schema check`** — wired to `schema_check::run` +* **`agy-ct context validate`** — wired to `context_validate::run` +* **`agy-ct context build`** — wired to `context_build::run` ### 3. Replay UX Stream Separation The `package replay` command implements a strict separation of output streams: @@ -60,8 +63,8 @@ The `package replay` command implements a strict separation of output streams: * Global CLI flags `--quiet` (suppresses status output), `--plain` (strips ANSI escapes), and `--no-color` (disables terminal color codes) are explicitly supported. ### 4. Test and Placeholders Status -* **Validation Status:** The local Rust test suite executes successfully with **65 PASS** tests. -* **Remaining Placeholders:** The subcommands `package compress`, `package adversarial`, `context build`, `context render`, `context validate`, and `schema check` remain as placeholders. +* **Validation Status:** The local Rust test suite executes successfully with **68 PASS** tests. +* **Remaining Placeholders:** The subcommands `package compress`, `package adversarial`, and `context render` remain as placeholders. ### 5. Exclusion and Alignment Boundaries * **XENTRY/OBD/X-Engine:** Legacy/future diagnostic components (including OBD-II logs and X-Engine sandwich parsers) remain completely excluded from the active scope. From d00132be82d180a4934c4cdf1c2cb195e7659b47 Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Wed, 10 Jun 2026 12:25:18 +0200 Subject: [PATCH 13/27] feat: wire context render command --- agy7rust/src/bin/agy_ct.rs | 4 +- agy7rust/tests/spark_roundtrip.rs | 103 ++++++++++++++++++++++++++++++ 2 files changed, 105 insertions(+), 2 deletions(-) diff --git a/agy7rust/src/bin/agy_ct.rs b/agy7rust/src/bin/agy_ct.rs index e202311..d586d27 100644 --- a/agy7rust/src/bin/agy_ct.rs +++ b/agy7rust/src/bin/agy_ct.rs @@ -230,8 +230,8 @@ fn main() -> Result<()> { } => { agy7rust::commands::context_build::run(input, schema, output)?; } - ContextCommands::Render { .. } => { - println!("Placeholder: context render"); + ContextCommands::Render { input, output } => { + agy7rust::commands::context_render::run(input, output)?; } ContextCommands::Validate { input, schema: _ } => { agy7rust::commands::context_validate::run(input)?; diff --git a/agy7rust/tests/spark_roundtrip.rs b/agy7rust/tests/spark_roundtrip.rs index 22a781e..4d0d94e 100644 --- a/agy7rust/tests/spark_roundtrip.rs +++ b/agy7rust/tests/spark_roundtrip.rs @@ -1844,3 +1844,106 @@ fn test_agy_ct_context_build_execution() { let _ = fs::remove_file(temp_package_path); let _ = fs::remove_file(temp_context_path); } + +#[test] +fn test_agy_ct_context_render_execution() { + use serde_json::json; + use std::fs; + use std::process::Command; + + let temp_dir = std::env::temp_dir(); + let temp_input_path = temp_dir.join("test_render_input.json"); + let temp_output_path = temp_dir.join("test_render_output.txt"); + let temp_bad_input_path = temp_dir.join("test_render_bad_input.json"); + let temp_bad_output_path = temp_dir.join("test_render_bad_output.txt"); + + // Ensure we clean up any pre-existing output files + let _ = fs::remove_file(&temp_output_path); + let _ = fs::remove_file(&temp_bad_output_path); + + // ============================================ + // 1. Success Test: Valid context JSON + // ============================================ + let valid_ctx = json!({ + "context_id": "ctx-render-test-123", + "source_package_hash": "hash-999", + "schema_name": "genehmigung_v1", + "schema_version": 1, + "required_field_paths": ["$.case_id"], + "satisfied_field_paths": ["$.case_id"], + "missing_field_paths": [], + "constraints": [], + "required_order": [], + "dependency_edges": [], + "blockers": [], + "recovery_paths": [], + "validation": { + "valid": true, + "failure_labels": [], + "issues": [] + }, + "non_claims": [] + }); + + fs::write(&temp_input_path, serde_json::to_string(&valid_ctx).unwrap()).unwrap(); + + let output_success = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "context", + "render", + "-i", + temp_input_path.to_str().unwrap(), + "-o", + temp_output_path.to_str().unwrap(), + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(output_success.status.success()); + let stdout_str = String::from_utf8_lossy(&output_success.stdout); + assert!(stdout_str.contains("OK: context-render passed")); + assert!(stdout_str.contains("context: ctx-render-test-123")); + + assert!(temp_output_path.exists()); + let render_content = fs::read_to_string(&temp_output_path).unwrap(); + assert!(!render_content.is_empty()); + assert!(render_content.contains("ctx-render-test-123")); + assert!(render_content.contains("genehmigung_v1")); + + // ============================================ + // 2. Failure Test: Corrupted context JSON + // ============================================ + fs::write(&temp_bad_input_path, "{ \"invalid\": ").unwrap(); + + let output_failure = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "context", + "render", + "-i", + temp_bad_input_path.to_str().unwrap(), + "-o", + temp_bad_output_path.to_str().unwrap(), + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(!output_failure.status.success()); + // Verify that the bad output file was not written (or doesn't exist) + assert!(!temp_bad_output_path.exists()); + + // ============================================ + // 3. Cleanup + // ============================================ + let _ = fs::remove_file(temp_input_path); + let _ = fs::remove_file(temp_output_path); + let _ = fs::remove_file(temp_bad_input_path); + let _ = fs::remove_file(temp_bad_output_path); +} From dcfbd020a24c08d79995b7135ac16b623c5381c7 Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Wed, 10 Jun 2026 12:39:54 +0200 Subject: [PATCH 14/27] docs: sync alignment after context render --- docs/SPARK_ALIGNMENT.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/SPARK_ALIGNMENT.md b/docs/SPARK_ALIGNMENT.md index 8aa9e8f..8cbc0c4 100644 --- a/docs/SPARK_ALIGNMENT.md +++ b/docs/SPARK_ALIGNMENT.md @@ -55,6 +55,7 @@ The following `agy-ct` subcommands are fully wired and functional: * **`agy-ct schema check`** — wired to `schema_check::run` * **`agy-ct context validate`** — wired to `context_validate::run` * **`agy-ct context build`** — wired to `context_build::run` +* **`agy-ct context render`** — wired to `context_render::run` ### 3. Replay UX Stream Separation The `package replay` command implements a strict separation of output streams: @@ -63,8 +64,8 @@ The `package replay` command implements a strict separation of output streams: * Global CLI flags `--quiet` (suppresses status output), `--plain` (strips ANSI escapes), and `--no-color` (disables terminal color codes) are explicitly supported. ### 4. Test and Placeholders Status -* **Validation Status:** The local Rust test suite executes successfully with **68 PASS** tests. -* **Remaining Placeholders:** The subcommands `package compress`, `package adversarial`, and `context render` remain as placeholders. +* **Validation Status:** The local Rust test suite executes successfully with **69 PASS** tests. +* **Remaining Placeholders:** The subcommands `package compress`, `package adversarial`, `report export`, and `notebook bundle` remain as placeholders. ### 5. Exclusion and Alignment Boundaries * **XENTRY/OBD/X-Engine:** Legacy/future diagnostic components (including OBD-II logs and X-Engine sandwich parsers) remain completely excluded from the active scope. From 228d23b2443d0904a89f5eafd5c4ce687dc0cc98 Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Wed, 10 Jun 2026 12:46:00 +0200 Subject: [PATCH 15/27] docs: add local Antigravity project control --- AGY_PROJECT.md | 197 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 AGY_PROJECT.md diff --git a/AGY_PROJECT.md b/AGY_PROJECT.md new file mode 100644 index 0000000..9c3bcb3 --- /dev/null +++ b/AGY_PROJECT.md @@ -0,0 +1,197 @@ +# Sparkctl Projektsteuerungsdatei + +## 1. Zweck +- Diese Datei dient als lokale Steuerungsdatei für die Sparkctl-Entwicklungsarbeiten mit Antigravity. +- Sie ist kein Ersatz für `AGENTS.md`. +- `AGENTS.md` und die Skills unter `.agents/skills/**/SKILL.md` bleiben die vorrangig verbindlichen Arbeitsregeln. +- Diese Datei konkretisiert und priorisiert lediglich den aktuellen lokalen Backlog für diese Arbeitsumgebung. + +--- + +## 2. Aktueller lokaler Stand +- **Branch:** `docs/spark-hackathon-governance` +- **Letzte relevante Commits:** + - `dcfbd02` docs: sync alignment after context render + - `d00132b` feat: wire context render command +- **Tests letzter Stand:** 69 PASS laut lokalem Audit/Teststand. + +--- + +## 3. Wired Commands +Folgende Befehle des CLI `agy-ct` sind vollständig verdrahtet: +- `agy-ct package verify` +- `agy-ct package replay` +- `agy-ct package inspect` +- `agy-ct schema check` +- `agy-ct context validate` +- `agy-ct context build` +- `agy-ct context render` + +--- + +## 4. Remaining Placeholders +Folgende Befehle des CLI `agy-ct` sind noch als Platzhalter deklariert: +- `agy-ct package compress` +- `agy-ct package adversarial` +- `agy-ct report export` +- `agy-ct notebook bundle` + +--- + +## 5. Arbeitsmodus +- Lokale Arbeit ausschließlich innerhalb des Workspace-Verzeichnisses. +- Standardmäßiger Containment-Modus: `proceed-in-sandbox`. +- Vor Feature-Änderungen wird eine Read-only/Explore- oder Plan-only-Phase durchgeführt, falls der genaue Task-Kontext unklar ist. +- Bei klar definierten Backlog-Tasks darf lokal implementiert, validiert und lokal committet werden. +- **Kein Push.** +- **Keine PR.** +- **Kein Release.** + +--- + +## 6. Erlaubte lokale Autonomie +- Durchführung von Read-only Audits im Workspace. +- Änderungen sind nur an Dateien erlaubt, die explizit im Scope der aktiven Backlog-Task aufgeführt sind. +- Ausführung der Rust-Validierung im Verzeichnis `agy7rust/`: + - `cargo fmt --all --check` + - `cargo check` + - `cargo test` + - `cargo clippy -- -D warnings` +- Nach Durchführung von `cargo test` wird `git status --short` auf gerufene Test-Seiteneffekte geprüft. +- Falls `reports/performance_baseline.json` geändert wurde, wird diese Datei sofort via `git restore reports/performance_baseline.json` zurückgesetzt. +- Erstellung lokaler Commits pro erfolgreich abgeschlossener und validierter Task. + +--- + +## 7. Verboten ohne explizite menschliche Freigabe +- `git push` +- PR (Pull Request) erstellen +- Release-Aktionen ausführen +- Deploy-Vorgänge starten +- Branch veröffentlichen (Branch publish) +- Remote-Synchronisierung (Remote sync) +- `git pull` / `git fetch` +- Plugins modifizieren +- Hooks modifizieren +- Skills modifizieren +- `AGENTS.md` modifizieren +- Globale Systemeinstellungen oder User-Home-Konfigurationen ändern +- Secrets oder Umgebungsvariablen exportieren/dumpen +- Ordner `reports/` oder `artifacts/` committen (Ausnahme: genehmigte Dokumentenaktualisierungen) +- Reale Behörden-, Personen- oder Falldaten einführen +- Offizielle SPARK-/BMDS-/Compliance-/Forensic-/Legal-/EU-AI-Act-Claims hinzufügen + +--- + +## 8. Commit-Regeln +- Lokale Commits sind erlaubt, wenn: + - Die Task vollständig abgeschlossen ist. + - Alle Validierungsschritte (Formatierung, Check, Linter, Tests) fehlerfrei durchlaufen wurden. + - `git status --short` ausschließlich die erlaubten Scope-Dateien als verändert anzeigt. + - Modifikationen an `reports/performance_baseline.json` zurückgesetzt wurden. + - Keine Berichts- oder Artefaktdateien im Commit-Set enthalten sind. +- Commit-Messages müssen task-spezifisch sein. Zulässige Formate: + - `feat: wire package compress command` + - `docs: sync alignment after package compress` + - `feat: wire package adversarial command` + - `docs: sync alignment after package adversarial` +- **Kein Push, keine PR.** + +--- + +## 9. Backlog + +- [ ] **Task 01: agy-ct package compress verdrahten und testen** + - **Scope:** + - `agy7rust/src/bin/agy_ct.rs` + - `agy7rust/tests/spark_roundtrip.rs` + - **Akzeptanzkriterien:** + - `PackageCommands::Compress` routet auf `compress::run`. + - Ein Success-Test läuft vollständig im Temp-Verzeichnis ab. + - Die Ausgabedatei `.spkg` existiert und ist nicht leer. + - Fehlverhalten bei fehlenden oder beschädigten Eingaben wird abgefangen und liefert einen Fehler-Exit-Code. + - Keine Erzeugung von Berichten oder dauerhaften Artefakten. + - Keine echten Daten. + - Rust-Güteprüfungen (`cargo fmt/check/test/clippy`) laufen fehlerfrei durch. + - Lokaler Commit wird erstellt. + +- [ ] **Task 02: docs/SPARK_ALIGNMENT.md nach package compress synchronisieren** + - **Scope:** + - `docs/SPARK_ALIGNMENT.md` + - **Akzeptanzkriterien:** + - `package compress` wird als "wired and functional" gelistet. + - Die verbleibenden Platzhalter werden aktualisiert. + - Der Teststatus wird auf den neuesten PASS-Wert aktualisiert. + - Keine neuen Claims. + - Lokaler Commit wird erstellt. + +- [ ] **Task 03: agy-ct package adversarial verdrahten und testen** + - **Scope:** + - `agy7rust/src/bin/agy_ct.rs` + - `agy7rust/tests/spark_roundtrip.rs` + - **Akzeptanzkriterien:** + - `PackageCommands::Adversarial` routet auf `adversarial::run`. + - CLI-Integrationstest läuft isoliert im Temp-Verzeichnis. + - Führt 5 simulierte Manipulationsprüfungen auf manipulierten `.spkg` Paketen aus und verifiziert den fehlerhaften Zustand. + - Keine Erzeugung von Berichten oder dauerhaften Artefakten. + - Keine echten Daten. + - Rust-Güteprüfungen laufen fehlerfrei durch. + - Lokaler Commit wird erstellt. + +- [ ] **Task 04: docs/SPARK_ALIGNMENT.md nach package adversarial synchronisieren** + - **Scope:** + - `docs/SPARK_ALIGNMENT.md` + - **Akzeptanzkriterien:** + - `package adversarial` wird als "wired and functional" gelistet. + - Die verbleibenden Platzhalter werden aktualisiert. + - Keine neuen Claims. + - Lokaler Commit wird erstellt. + +- [ ] **Task 05: report export read-only analysieren** + - **Scope:** Read-Only + - **Akzeptanzkriterien:** + - Realer CLI-Status geklärt. + - Vorhandene Backend-Logik unter `agy7rust` ermittelt. + - Für die Verdrahtung benötigte Dateien gelistet. + - Keine Code- oder Dokumentationsänderungen vorgenommen. + +- [ ] **Task 06: notebook bundle read-only analysieren** + - **Scope:** Read-Only + - **Akzeptanzkriterien:** + - Realer CLI-Status geklärt. + - Vorhandene Backend-Logik unter `agy7rust` ermittelt. + - Für die Verdrahtung benötigte Dateien gelistet. + - Keine Code- oder Dokumentationsänderungen vorgenommen. + +- [ ] **Task 07: Final Local Audit** + - **Scope:** Read-Only + - **Akzeptanzkriterien:** + - Workspace ist sauber. + - Alle wired/placeholder Befehle stimmen mit Code und Dokumenten überein. + - `README.md` und `docs/SPARK_ALIGNMENT.md` sind synchron. + - Berichte und Artefakte sind unverändert. + - Eventuelle verbleibende Remote/PR-Risiken sind erfasst. + +- [ ] **Task 08: Remote/PR-Strategie abstimmen** + - **Scope:** Read-Only bis zur Freigabe. + - **Akzeptanzkriterien:** + - Offene PRs berücksichtigt. + - Kein Push oder PR ohne explizite Freigabe. + +--- + +## 10. Nächster Task +- **Next:** `Task 01 — agy-ct package compress verdrahten und testen`. +- **Vor Start von Task 01:** Read-only Prüfung, ob die Signatur von `compress::run` und der Input/Output-Kontrakt stabil sind. + +--- + +## 11. Claim-Grenzen +- **Synthetic-only:** Alle Tests laufen auf rein synthetischer Datenbasis ab. +- **Mandatory human review:** Alle Ergebnisse sind unverbindliche Vorschläge. Systementscheidungen ohne menschliche Freigabe sind ausgeschlossen. +- **Non-certified:** Keine Zertifizierungen oder Konformitätsgarantien nach dem EU AI Act oder anderen regulatorischen Rahmenwerken. +- **Kein offizieller SPARK-/BMDS-Status:** Die Software ist ein inoffizieller Prototyp. +- **Keine Produktivfreigabe:** Die Software ist nicht für den produktiven Einsatz bestimmt. +- **Keine Legal-/Forensic-Claims:** Keine rechtsverbindlichen Nachweise oder forensischen Sicherheitsgarantien. +- **Keine Echtdaten:** Keine echten Personen-, Fall- oder Behördendaten. +- **XENTRY/OBD ausgeschlossen:** Eventuelle Diagnose- oder Diagnoseschnittstellenlogs sind nicht Scope des Projekts. From 07dd11d987d16f27faaf000984540d563b27ce95 Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Wed, 10 Jun 2026 13:19:36 +0200 Subject: [PATCH 16/27] feat: wire package compress command --- agy7rust/src/bin/agy_ct.rs | 4 +- agy7rust/tests/spark_roundtrip.rs | 120 ++++++++++++++++++++++++++++++ 2 files changed, 122 insertions(+), 2 deletions(-) diff --git a/agy7rust/src/bin/agy_ct.rs b/agy7rust/src/bin/agy_ct.rs index d586d27..3cbcc78 100644 --- a/agy7rust/src/bin/agy_ct.rs +++ b/agy7rust/src/bin/agy_ct.rs @@ -201,8 +201,8 @@ fn main() -> Result<()> { sparkctl::handoff_check::run_handoff_check()?; } Commands::Package { subcommand } => match subcommand { - PackageCommands::Compress { .. } => { - println!("Placeholder: package compress"); + PackageCommands::Compress { input, output } => { + agy7rust::commands::compress::run(input, output)?; } PackageCommands::Inspect { input } => { agy7rust::commands::inspect::run(input)?; diff --git a/agy7rust/tests/spark_roundtrip.rs b/agy7rust/tests/spark_roundtrip.rs index 4d0d94e..788f1f4 100644 --- a/agy7rust/tests/spark_roundtrip.rs +++ b/agy7rust/tests/spark_roundtrip.rs @@ -1947,3 +1947,123 @@ fn test_agy_ct_context_render_execution() { let _ = fs::remove_file(temp_bad_input_path); let _ = fs::remove_file(temp_bad_output_path); } + +#[test] +fn test_agy_ct_package_compress_execution() { + use agy7rust::codec::package::verify_package_value; + use std::fs; + use std::process::Command; + + let temp_dir = std::env::temp_dir(); + let temp_output_path = temp_dir.join("test_compressed.spkg"); + let temp_bad_input_path = temp_dir.join("test_compress_bad_input.json"); + let temp_bad_output_path = temp_dir.join("test_compress_bad_output.spkg"); + + let _ = fs::remove_file(&temp_output_path); + let _ = fs::remove_file(&temp_bad_output_path); + + // Ensure no residual temp file exists + let expected_tmp_success = temp_dir.join(".test_compressed.spkg.tmp"); + let expected_tmp_failure = temp_dir.join(".test_compress_bad_output.spkg.tmp"); + let _ = fs::remove_file(&expected_tmp_success); + let _ = fs::remove_file(&expected_tmp_failure); + + // ============================================ + // 1. Success Test: Valid JSON input + // ============================================ + let output_success = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "package", + "compress", + "-i", + "../examples/spark/extraction.json", + "-o", + temp_output_path.to_str().unwrap(), + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(output_success.status.success()); + assert!(temp_output_path.exists()); + assert!( + !expected_tmp_success.exists(), + "Temporary write file must not persist on success" + ); + + let package_content = fs::read_to_string(&temp_output_path).unwrap(); + assert!(!package_content.is_empty()); + + let package_value: serde_json::Value = serde_json::from_str(&package_content).unwrap(); + assert!( + verify_package_value(&package_value).is_ok(), + "Generated package must verify successfully" + ); + + // ============================================ + // 2. Failure Test 1: Missing input + // ============================================ + let non_existent_input = temp_dir.join("test_compress_non_existent.json"); + let _ = fs::remove_file(&non_existent_input); + + let output_failure_missing = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "package", + "compress", + "-i", + non_existent_input.to_str().unwrap(), + "-o", + temp_bad_output_path.to_str().unwrap(), + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(!output_failure_missing.status.success()); + assert!(!temp_bad_output_path.exists()); + assert!( + !expected_tmp_failure.exists(), + "Temporary write file must not persist on missing input failure" + ); + + // ============================================ + // 3. Failure Test 2: Corrupted JSON input + // ============================================ + fs::write(&temp_bad_input_path, "{ \"invalid\": ").unwrap(); + + let output_failure_corrupt = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "package", + "compress", + "-i", + temp_bad_input_path.to_str().unwrap(), + "-o", + temp_bad_output_path.to_str().unwrap(), + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(!output_failure_corrupt.status.success()); + assert!(!temp_bad_output_path.exists()); + assert!( + !expected_tmp_failure.exists(), + "Temporary write file must not persist on corrupt JSON failure" + ); + + // ============================================ + // 4. Cleanup + // ============================================ + let _ = fs::remove_file(temp_output_path); + let _ = fs::remove_file(temp_bad_input_path); + let _ = fs::remove_file(temp_bad_output_path); +} From 0bacac18c8dcbf4f289d973c60c1ed9862d8af79 Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Wed, 10 Jun 2026 13:21:35 +0200 Subject: [PATCH 17/27] docs: sync alignment after package compress --- docs/SPARK_ALIGNMENT.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/SPARK_ALIGNMENT.md b/docs/SPARK_ALIGNMENT.md index 8cbc0c4..8a2c11c 100644 --- a/docs/SPARK_ALIGNMENT.md +++ b/docs/SPARK_ALIGNMENT.md @@ -52,6 +52,7 @@ The following `agy-ct` subcommands are fully wired and functional: * **`agy-ct package verify`** — wired to `verify_cmd::run` * **`agy-ct package replay`** — wired to `replay_cmd::run` * **`agy-ct package inspect`** — wired to `inspect::run` +* **`agy-ct package compress`** — wired to `compress::run` * **`agy-ct schema check`** — wired to `schema_check::run` * **`agy-ct context validate`** — wired to `context_validate::run` * **`agy-ct context build`** — wired to `context_build::run` @@ -64,8 +65,8 @@ The `package replay` command implements a strict separation of output streams: * Global CLI flags `--quiet` (suppresses status output), `--plain` (strips ANSI escapes), and `--no-color` (disables terminal color codes) are explicitly supported. ### 4. Test and Placeholders Status -* **Validation Status:** The local Rust test suite executes successfully with **69 PASS** tests. -* **Remaining Placeholders:** The subcommands `package compress`, `package adversarial`, `report export`, and `notebook bundle` remain as placeholders. +* **Validation Status:** The local Rust test suite executes successfully with **70 PASS** tests. +* **Remaining Placeholders:** The subcommands `package adversarial`, `report export`, and `notebook bundle` remain as placeholders. ### 5. Exclusion and Alignment Boundaries * **XENTRY/OBD/X-Engine:** Legacy/future diagnostic components (including OBD-II logs and X-Engine sandwich parsers) remain completely excluded from the active scope. From 43d9c2ee89f61104ee192d2cc45c3be7723d5928 Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Wed, 10 Jun 2026 13:29:13 +0200 Subject: [PATCH 18/27] feat: wire package adversarial command --- agy7rust/src/bin/agy_ct.rs | 4 +- agy7rust/tests/spark_roundtrip.rs | 114 ++++++++++++++++++++++++++++++ 2 files changed, 116 insertions(+), 2 deletions(-) diff --git a/agy7rust/src/bin/agy_ct.rs b/agy7rust/src/bin/agy_ct.rs index 3cbcc78..1666590 100644 --- a/agy7rust/src/bin/agy_ct.rs +++ b/agy7rust/src/bin/agy_ct.rs @@ -218,8 +218,8 @@ fn main() -> Result<()> { }; agy7rust::commands::replay_cmd::run(input, options)?; } - PackageCommands::Adversarial { .. } => { - println!("Placeholder: package adversarial"); + PackageCommands::Adversarial { input } => { + agy7rust::commands::adversarial::run(input)?; } }, Commands::Context { subcommand } => match subcommand { diff --git a/agy7rust/tests/spark_roundtrip.rs b/agy7rust/tests/spark_roundtrip.rs index 788f1f4..34bc0d5 100644 --- a/agy7rust/tests/spark_roundtrip.rs +++ b/agy7rust/tests/spark_roundtrip.rs @@ -2067,3 +2067,117 @@ fn test_agy_ct_package_compress_execution() { let _ = fs::remove_file(temp_bad_input_path); let _ = fs::remove_file(temp_bad_output_path); } + +#[test] +fn test_agy_ct_package_adversarial_execution() { + use serde_json::json; + use std::fs; + use std::process::Command; + + let temp_dir = std::env::temp_dir(); + let temp_bad_input_path = temp_dir.join("test_adversarial_bad_input.json"); + let temp_missing_fields_path = temp_dir.join("test_adversarial_missing_fields.json"); + + // ============================================ + // 1. Success Test: Valid raw input JSON trace + // ============================================ + let output_success = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "package", + "adversarial", + "-i", + "../examples/spark/extraction.json", + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(output_success.status.success()); + let stdout_str = String::from_utf8_lossy(&output_success.stdout); + assert!(stdout_str.contains("adversarial: 5/5 detected")); + + // ============================================ + // 2. Failure Test 1: Missing input file + // ============================================ + let non_existent_input = temp_dir.join("test_adversarial_non_existent.json"); + let _ = fs::remove_file(&non_existent_input); + + let output_failure_missing = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "package", + "adversarial", + "-i", + non_existent_input.to_str().unwrap(), + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(!output_failure_missing.status.success()); + + // ============================================ + // 3. Failure Test 2: Corrupted JSON input + // ============================================ + fs::write(&temp_bad_input_path, "{ \"invalid\": ").unwrap(); + + let output_failure_corrupt = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "package", + "adversarial", + "-i", + temp_bad_input_path.to_str().unwrap(), + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(!output_failure_corrupt.status.success()); + + // ============================================ + // 4. Failure Test 3: Missing Required Fields (missing parcel_id) + // ============================================ + let bad_ctx_missing_fields = json!({ + "case_id": "test-123", + "extraction": { + "fields": { + // missing parcel_id and decision_recommendation + } + } + }); + fs::write( + &temp_missing_fields_path, + serde_json::to_string(&bad_ctx_missing_fields).unwrap(), + ) + .unwrap(); + + let output_failure_fields = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "package", + "adversarial", + "-i", + temp_missing_fields_path.to_str().unwrap(), + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(!output_failure_fields.status.success()); + + // ============================================ + // 5. Cleanup + // ============================================ + let _ = fs::remove_file(temp_bad_input_path); + let _ = fs::remove_file(temp_missing_fields_path); +} From 3c760fefca915d57d7c7afd9e67d16336e8d5410 Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Wed, 10 Jun 2026 13:30:55 +0200 Subject: [PATCH 19/27] docs: sync alignment after package adversarial --- docs/SPARK_ALIGNMENT.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/SPARK_ALIGNMENT.md b/docs/SPARK_ALIGNMENT.md index 8a2c11c..0770aee 100644 --- a/docs/SPARK_ALIGNMENT.md +++ b/docs/SPARK_ALIGNMENT.md @@ -53,6 +53,7 @@ The following `agy-ct` subcommands are fully wired and functional: * **`agy-ct package replay`** — wired to `replay_cmd::run` * **`agy-ct package inspect`** — wired to `inspect::run` * **`agy-ct package compress`** — wired to `compress::run` +* **`agy-ct package adversarial`** — wired to `adversarial::run` * **`agy-ct schema check`** — wired to `schema_check::run` * **`agy-ct context validate`** — wired to `context_validate::run` * **`agy-ct context build`** — wired to `context_build::run` @@ -65,8 +66,8 @@ The `package replay` command implements a strict separation of output streams: * Global CLI flags `--quiet` (suppresses status output), `--plain` (strips ANSI escapes), and `--no-color` (disables terminal color codes) are explicitly supported. ### 4. Test and Placeholders Status -* **Validation Status:** The local Rust test suite executes successfully with **70 PASS** tests. -* **Remaining Placeholders:** The subcommands `package adversarial`, `report export`, and `notebook bundle` remain as placeholders. +* **Validation Status:** The local Rust test suite executes successfully with **71 PASS** tests. +* **Remaining Placeholders:** The subcommands `report export` and `notebook bundle` remain as placeholders. ### 5. Exclusion and Alignment Boundaries * **XENTRY/OBD/X-Engine:** Legacy/future diagnostic components (including OBD-II logs and X-Engine sandwich parsers) remain completely excluded from the active scope. From 545d79d6f4c5e57a5f5c20d78fb638784f78fda5 Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Wed, 10 Jun 2026 14:43:46 +0200 Subject: [PATCH 20/27] feat: add report export command --- agy7rust/src/bin/agy_ct.rs | 11 ++- agy7rust/src/commands/mod.rs | 1 + agy7rust/src/commands/report_export.rs | 91 ++++++++++++++++++ agy7rust/tests/spark_roundtrip.rs | 127 +++++++++++++++++++++++++ 4 files changed, 227 insertions(+), 3 deletions(-) create mode 100644 agy7rust/src/commands/report_export.rs diff --git a/agy7rust/src/bin/agy_ct.rs b/agy7rust/src/bin/agy_ct.rs index 1666590..e804a76 100644 --- a/agy7rust/src/bin/agy_ct.rs +++ b/agy7rust/src/bin/agy_ct.rs @@ -170,7 +170,12 @@ enum SchemaCommands { #[derive(Subcommand)] enum ReportCommands { #[command(about = "Exporter for generated pipeline JSON reports")] - Export, + Export { + #[arg(long, short)] + input: String, + #[arg(long, short)] + output: String, + }, } #[derive(Subcommand)] @@ -246,8 +251,8 @@ fn main() -> Result<()> { } }, Commands::Report { subcommand } => match subcommand { - ReportCommands::Export => { - println!("Placeholder: report export"); + ReportCommands::Export { input, output } => { + agy7rust::commands::report_export::run(input, output)?; } }, Commands::Notebook { subcommand } => match subcommand { diff --git a/agy7rust/src/commands/mod.rs b/agy7rust/src/commands/mod.rs index 8d40815..729a4d1 100644 --- a/agy7rust/src/commands/mod.rs +++ b/agy7rust/src/commands/mod.rs @@ -7,6 +7,7 @@ pub mod context_render; pub mod context_validate; pub mod inspect; pub mod replay_cmd; +pub mod report_export; pub mod schema_check; pub mod verify_cmd; diff --git a/agy7rust/src/commands/report_export.rs b/agy7rust/src/commands/report_export.rs new file mode 100644 index 0000000..af556c6 --- /dev/null +++ b/agy7rust/src/commands/report_export.rs @@ -0,0 +1,91 @@ +use anyhow::{Context, Result}; +use std::fs; +use std::path::Path; + +pub fn run(input_path: &str, output_path: &str) -> Result<()> { + let content = fs::read_to_string(input_path) + .with_context(|| format!("Failed to read report file: {}", input_path))?; + + let value: serde_json::Value = serde_json::from_str(&content) + .with_context(|| format!("Failed to parse report JSON: {}", input_path))?; + + let mut md = String::new(); + md.push_str("# CompText-Sparkctl Execution Report\n\n"); + + md.push_str("## Metadata\n"); + let tool = value.get("tool").and_then(|v| v.as_str()).unwrap_or("n/a"); + let project = value + .get("project") + .and_then(|v| v.as_str()) + .unwrap_or("n/a"); + let phase = value.get("phase").and_then(|v| v.as_str()).unwrap_or("n/a"); + let result = value + .get("result") + .and_then(|v| v.as_str()) + .unwrap_or("n/a"); + + md.push_str(&format!("- **Tool**: {}\n", tool)); + md.push_str(&format!("- **Project**: {}\n", project)); + md.push_str(&format!("- **Phase**: {}\n", phase)); + md.push_str(&format!("- **Result/Status**: {}\n\n", result)); + + if let Some(stages) = value.get("stages").and_then(|v| v.as_array()) { + md.push_str("## Stages\n"); + for stage in stages { + let index = stage.get("index").and_then(|v| v.as_u64()); + let name = stage.get("name").and_then(|v| v.as_str()).unwrap_or("n/a"); + let status = stage + .get("status") + .and_then(|v| v.as_str()) + .unwrap_or("n/a"); + + if let Some(idx) = index { + md.push_str(&format!("{}. **{}**: {}\n", idx, name, status)); + } else { + md.push_str(&format!("- **{}**: {}\n", name, status)); + } + } + md.push_str("\n"); + } + + if let Some(artifacts) = value.get("artifacts").and_then(|v| v.as_array()) { + md.push_str("## Artifacts\n"); + for artifact in artifacts { + if let Some(art_str) = artifact.as_str() { + md.push_str(&format!("- {}\n", art_str)); + } + } + md.push_str("\n"); + } + + // Atomic write pattern + let output_path_buf = Path::new(output_path); + if let Some(parent) = output_path_buf.parent() { + if !parent.exists() { + fs::create_dir_all(parent) + .with_context(|| format!("Failed to create directory: {:?}", parent))?; + } + } + + let parent_dir = output_path_buf.parent().unwrap_or_else(|| Path::new(".")); + let file_name = output_path_buf + .file_name() + .ok_or_else(|| anyhow::anyhow!("Invalid output path filename"))? + .to_str() + .ok_or_else(|| anyhow::anyhow!("Filename contains invalid Unicode"))?; + let temp_file_name = format!(".{}.tmp", file_name); + let temp_path = parent_dir.join(temp_file_name); + + fs::write(&temp_path, &md) + .with_context(|| format!("Failed to write to temp file: {:?}", temp_path))?; + + if let Err(e) = fs::rename(&temp_path, output_path) { + let _ = fs::remove_file(&temp_path); + return Err(anyhow::anyhow!(e).context(format!( + "Failed to rename temp file {:?} to output file {:?}", + temp_path, output_path_buf + ))); + } + + Ok(()) +} diff --git a/agy7rust/tests/spark_roundtrip.rs b/agy7rust/tests/spark_roundtrip.rs index 34bc0d5..07de903 100644 --- a/agy7rust/tests/spark_roundtrip.rs +++ b/agy7rust/tests/spark_roundtrip.rs @@ -2181,3 +2181,130 @@ fn test_agy_ct_package_adversarial_execution() { let _ = fs::remove_file(temp_bad_input_path); let _ = fs::remove_file(temp_missing_fields_path); } + +#[test] +fn test_agy_ct_report_export_execution() { + use serde_json::json; + use std::fs; + use std::process::Command; + + let pid = std::process::id(); + let time = std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap_or_default() + .as_millis(); + let suffix = format!("{}_{}", pid, time); + + let temp_dir = std::env::temp_dir(); + let temp_input_path = temp_dir.join(format!("test_report_input_{}.json", suffix)); + let temp_output_path = temp_dir.join(format!("test_report_output_{}.md", suffix)); + let temp_bad_input_path = temp_dir.join(format!("test_report_bad_input_{}.json", suffix)); + + // Clean up from previous runs + let _ = fs::remove_file(&temp_input_path); + let _ = fs::remove_file(&temp_output_path); + let _ = fs::remove_file(&temp_bad_input_path); + + // ============================================ + // 1. Success Test: Valid JSON report + // ============================================ + let mock_report = json!({ + "tool": "agy-ct", + "project": "CompText-Sparkctl", + "phase": "6E", + "result": "PASS", + "stages": [ + { + "index": 1, + "name": "workspace doctor", + "status": "PASS" + } + ] + }); + fs::write( + &temp_input_path, + serde_json::to_string_pretty(&mock_report).unwrap(), + ) + .unwrap(); + + let output_success = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "report", + "export", + "-i", + temp_input_path.to_str().unwrap(), + "-o", + temp_output_path.to_str().unwrap(), + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(output_success.status.success()); + assert!(temp_output_path.exists()); + let md_content = fs::read_to_string(&temp_output_path).unwrap(); + assert!(!md_content.is_empty()); + assert!(md_content.contains("# CompText-Sparkctl Execution Report")); + assert!(md_content.contains("workspace doctor")); + assert!(md_content.contains("PASS")); + + // Clean up output + let _ = fs::remove_file(&temp_output_path); + + // ============================================ + // 2. Failure Test 1: Missing input file + // ============================================ + let non_existent_input = temp_dir.join(format!("test_report_non_existent_{}.json", suffix)); + let _ = fs::remove_file(&non_existent_input); + + let output_failure_missing = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "report", + "export", + "-i", + non_existent_input.to_str().unwrap(), + "-o", + temp_output_path.to_str().unwrap(), + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(!output_failure_missing.status.success()); + assert!(!temp_output_path.exists()); + + // ============================================ + // 3. Failure Test 2: Corrupted JSON input + // ============================================ + fs::write(&temp_bad_input_path, "{ \"invalid\": ").unwrap(); + + let output_failure_corrupt = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "report", + "export", + "-i", + temp_bad_input_path.to_str().unwrap(), + "-o", + temp_output_path.to_str().unwrap(), + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(!output_failure_corrupt.status.success()); + assert!(!temp_output_path.exists()); + + // Clean up temporary files + let _ = fs::remove_file(&temp_input_path); + let _ = fs::remove_file(&temp_bad_input_path); + let _ = fs::remove_file(&temp_output_path); +} From a3d30b3fcc75068789642bdb6d39904be6475f08 Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Wed, 10 Jun 2026 14:45:52 +0200 Subject: [PATCH 21/27] docs: sync alignment after report export --- docs/SPARK_ALIGNMENT.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/SPARK_ALIGNMENT.md b/docs/SPARK_ALIGNMENT.md index 0770aee..38552a3 100644 --- a/docs/SPARK_ALIGNMENT.md +++ b/docs/SPARK_ALIGNMENT.md @@ -54,6 +54,7 @@ The following `agy-ct` subcommands are fully wired and functional: * **`agy-ct package inspect`** — wired to `inspect::run` * **`agy-ct package compress`** — wired to `compress::run` * **`agy-ct package adversarial`** — wired to `adversarial::run` +* **`agy-ct report export`** — wired to `report_export::run` (CLI: `-i -o `) * **`agy-ct schema check`** — wired to `schema_check::run` * **`agy-ct context validate`** — wired to `context_validate::run` * **`agy-ct context build`** — wired to `context_build::run` @@ -66,8 +67,8 @@ The `package replay` command implements a strict separation of output streams: * Global CLI flags `--quiet` (suppresses status output), `--plain` (strips ANSI escapes), and `--no-color` (disables terminal color codes) are explicitly supported. ### 4. Test and Placeholders Status -* **Validation Status:** The local Rust test suite executes successfully with **71 PASS** tests. -* **Remaining Placeholders:** The subcommands `report export` and `notebook bundle` remain as placeholders. +* **Validation Status:** The local Rust test suite executes successfully with **72 PASS** tests (targeted report export test PASS). +* **Remaining Placeholders:** The subcommand `notebook bundle` remains as a placeholder. ### 5. Exclusion and Alignment Boundaries * **XENTRY/OBD/X-Engine:** Legacy/future diagnostic components (including OBD-II logs and X-Engine sandwich parsers) remain completely excluded from the active scope. From 89d4ac169056ecbe2af71856d62777bab79ad685 Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Wed, 10 Jun 2026 14:52:49 +0200 Subject: [PATCH 22/27] docs: sync README with current CLI status --- README.md | 112 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 68 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 47ed9c0..08bdbed 100644 --- a/README.md +++ b/README.md @@ -21,16 +21,13 @@ ```mermaid flowchart LR - A[Synthetischer Verwaltungs-Trace] --> B[Schema Check] - B --> C[Context Build] - C --> D[Evidence Package] - D --> E[Package Verify] - E --> F[Replay] - F --> G[Human Review Gate] - - E --> H{Fehler?} - H -->|EVIDENCE_LOSS| I[Nachweis fehlt] - H -->|CONSTRAINT_DRIFT| J[Hash/Constraint Drift] + A["Raw JSON Trace"] --> B["schema check"] + B --> C["package compress"] + C --> D["package verify"] + C --> E["package inspect"] + C --> F["package adversarial"] + A --> G["report export"] + G --> H["Markdown Report"] ``` --- @@ -50,20 +47,35 @@ Dies ermöglicht sichere, transparente und nachvollziehbare Prototyp-Workflows f ## Was der Prototyp lokal kann -Sparkctl implementiert folgende Mechanismen zur Absicherung synthetischer Planungsdaten: - -- **Verify-before-Replay:** Vor jedem Replay-Durchlauf wird die strukturelle Integrität des Pakets verifiziert. -- **Fehlererkennung:** - - `EVIDENCE_LOSS`: Erkennt, wenn für die Wiederholung notwendige Nachweise im Paket fehlen. - - `CONSTRAINT_DRIFT`: Erkennt Manipulationen an Hashes oder verankerten Integritätsbedingungen. -- **Kryptografische Absicherung:** Nutzung von *canonical JSON* zur deterministischen Serialisierung und einer darauf aufbauenden *SHA-256 Hash-Chain* zur lückenlosen Protokollierung. -- **Grobübersicht der implementierten Befehle:** - - `agy-ct package verify`: Prüft SHA-256 Signaturen und Verkettungen. - - `agy-ct package replay`: Rekonstruiert die aufgezeichnete Trace deterministisch (strikte stdout/stderr Kanaltrennung). - - `agy-ct package inspect`: Zeigt Metadaten und Header-Einträge. - - `agy-ct schema check`: Abgleich von Traces gegen JSON-Schemas. - - `agy-ct context validate`: Führt strukturelle Validierung und Leckprüfungen auf Kontextmodellen durch. - - `agy-ct context build`: Erzeugt strukturierte operative Kontextmodelle. +Sparkctl implementiert Mechanismen zur Absicherung synthetischer Planungsdaten. + +### Implementierte Befehle: +- **`agy-ct package compress`** — Komprimiert Roh-Traces zu einer `.spkg`-Datei unter Erhalt kritischer Hashes. +- **`agy-ct package inspect`** — Liest Sidecar-Eigenschaften und Header-Einträge aus `.spkg`. +- **`agy-ct package verify`** — Führt kryptografische SHA-256 Validierungen von `.spkg`-Evidence-Paketen durch. +- **`agy-ct package replay`** — Rekonstruiert die aufgezeichnete Trace deterministisch (strikte stdout/stderr Kanaltrennung). +- **`agy-ct package adversarial`** — Simuliert manipulierte Attribute zur Überprüfung der Manipulationserkennung. +- **`agy-ct report export`** — Exportiert JSON-Pipeline-Berichte als formatierten Markdown-Report. +- **`agy-ct schema check`** — Gleicht rohe Trace-Dateien gegen JSON-Schemas ab. +- **`agy-ct context validate`** — Führt strukturelle Validierung und Leckprüfungen auf Kontextmodellen durch. +- **`agy-ct context build`** — Erzeugt strukturierte operative Kontextmodelle. +- **`agy-ct context render`** — Rendert operative Kontextdaten in token-sparenden Fließtext. + +### Command Status Matrix + +| Bereich | Befehl | Backend/Modul | Status | Output | Teststatus | +|---|---|---|---|---|---| +| **Package** | `package compress` | `compress::run` | Wired | `.spkg` Evidence-Paket | 100% PASS | +| **Package** | `package inspect` | `inspect::run` | Wired | Eigenschafts-Zusammenfassung | 100% PASS | +| **Package** | `package verify` | `verify_cmd::run` | Wired | Signatur-/Hash-Status | 100% PASS | +| **Package** | `package replay` | `replay_cmd::run` | Wired | Trace-Rekonstruktion (stdout/stderr) | 100% PASS | +| **Package** | `package adversarial` | `adversarial::run` | Wired | Manipulationserkennungs-Bericht | 100% PASS | +| **Schema** | `schema check` | `schema_check::run` | Wired | Validierungsergebnis | 100% PASS | +| **Context** | `context build` | `context_build::run` | Wired | Operatives Kontextmodell (JSON) | 100% PASS | +| **Context** | `context render` | `context_render::run` | Wired | Token-reduzierter Text | 100% PASS | +| **Context** | `context validate` | `context_validate::run` | Wired | Leck- und Strukturprüfungsbericht | 100% PASS | +| **Report** | `report export` | `report_export::run` | Wired | Markdown-Export (`.md`) | 100% PASS | +| **Notebook** | `notebook bundle` | N/A | Placeholder | Unified payload | Ausstehend | --- @@ -75,25 +87,25 @@ Führen Sie die folgenden sicheren lokalen Befehle im Rust-Unterverzeichnis aus: # In das Rust-Verzeichnis wechseln cd agy7rust -# Testsuite ausführen (67+ Tests) +# Testsuite ausführen (72 PASS Tests) cargo test -# Schema-Check mit synthetischen Beispieldaten ausführen -cargo run --bin agy-ct -- schema check --input ../examples/spark/extraction.json --schema ../schemas/genehmigung_v1.json +# Berichtsexport mit einer synthetischen Beispieldokumentation ausführen +cargo run --bin agy-ct -- report export -i ../examples/spark/report_sample.json -o ../temp_output.md ``` *Hinweis: Befehle, die Berichte oder veränderte Artefakte generieren, sind optional und dienen dem manuellen Review-Prozess.* --- -## Agenten-Setup & Governance - -Dieses Repository nutzt klare Richtlinien für die lokale Ausführung von KI-Entwicklungsagenten (z. B. Antigravity): +## Kryptografische Absicherung und Integrität -- **Regelwerk:** Die [AGENTS.md](AGENTS.md) ist das maßgebliche lokale Steuerungswerkzeug. -- **Skill-Pfad:** Das Verzeichnis `.agents/skills/` dient als aktiver Antigravity-Skill-Pfad. -- **Codex-Hooks:** Skripte unter `.codex/hooks/` sind Codex-spezifisch und bieten keine Ausführungs- oder Sicherheitsgarantie für Antigravity-Sitzungen. -- **Sicherheits-Modus:** Empfohlen wird die Ausführung im Sandbox-Modus (`proceed-in-sandbox`). +Sparkctl nutzt eine Reihe technischer Mechanismen, um die Integrität synthetischer Planungsdaten nachzuweisen: +- **Canonical JSON:** Um Abweichungen durch Formatierung, Leerzeichen oder Keys-Sortierung zu verhindern, werden JSON-Strukturen deterministisch sortiert und serialisiert. +- **SHA-256 Hashing:** Die Verifikation stützt sich auf SHA-256 Hashes der serialisierten Daten. +- **Integrity Chain:** Der Hash des Preimages (`payload_sha256`) wird mit dem Zustand des Sidecars verknüpft, um ein manipulationssensitives Evidence Package zu erzeugen. +- **Adversarial-Simulation:** Der `package adversarial`-Befehl simuliert gezielte Manipulationen an Paketstrukturen, um zu demonstrieren, wie Abweichungen vom kanonischen Hash sofort erkannt werden. +- **Keine Sicherheits- oder Rechtsgarantie:** Diese Absicherung dient ausschließlich der Erkennung unbeabsichtigter Datenverluste oder struktureller Abweichungen (*tamper-sensitive validation*). Sie stellt keine kryptografische Signatur im Sinne des Signaturgesetzes und kein forensisch unumstößliches Beweismittel dar. --- @@ -101,22 +113,34 @@ Dieses Repository nutzt klare Richtlinien für die lokale Ausführung von KI-Ent Um Missverständnisse im Rahmen des SPARK-Hackathons auszuschließen, gelten folgende Grenzen: -- **Kein offizielles Produkt:** Sparkctl ist kein offizielles Produkt des BMDS (Bundesministerium für Digitales und Verkehr) oder seiner Partner. -- **Keine Produktivfreigabe:** Der Code ist ein reiner Prototyp für Testzwecke. -- **Keine Rechts- oder Compliance-Garantie:** Es wird keine rechtliche Beratung oder forensische Nachweissicherheit geboten. -- **Keine EU-AI-Act-Konformität:** Es wird keine Konformitätsbewertung oder Konformitätsgarantie nach dem EU AI Act gegeben. -- **Keine autonomen Entscheidungen:** Das System ersetzt zu keinem Zeitpunkt den menschlichen Review (*Mandatory Human-in-the-Loop*). -- **Keine Echtdaten:** Es werden ausschließlich künstliche (synthetische) Testdaten verarbeitet. Die Verarbeitung realer Bürger- oder Behördendaten ist ausgeschlossen. -- **Kein Diagnosefokus:** Legacy-Konzepte wie XENTRY, OBD-II oder X-Engine-Diagnoseschnittstellen sind ausdrücklich nicht Teil des aktiven SPARK-Scopes. +### Matrix der Non-Claims + +| Eigenschaft | Scope-Abgrenzung / Non-Claim | +|---|---| +| **Einsatzbereich** | Kein Produktivsystem. Reine Prototyp- & Konzept-Demo. | +| **Rechtskonformität** | Keine Rechtsberatung, rechtliche Zertifizierung oder forensische Absicherung. | +| **Konformitätsstufe** | Keine amtliche Konformität (z. B. EU AI Act). Nur Unterstützung des Art.-12-orientierten Record-Keeping. | +| **Systemzugehörigkeit** | Kein offizielles BMDS-Produkt und keine offizielle SPARK-Konformitätsgarantie. | +| **Datenbasis** | Ausschließlich synthetische Testdaten. Verarbeitung von Echtdaten ist ausgeschlossen. | +| **Entscheidungskompetenz** | Keine autonome Entscheidungsfindung. Ein menschlicher Review ist zwingend erforderlich (*Human-in-the-Loop*). | + +--- + +## Agenten-Setup & Governance + +Dieses Repository nutzt klare Richtlinien für die lokale Ausführung von KI-Entwicklungsagenten (z. B. Antigravity): + +- **Regelwerk:** Die [AGENTS.md](AGENTS.md) ist das maßgebliche lokale Steuerungswerkzeug. +- **Skill-Pfad:** Das Verzeichnis `.agents/skills/` dient als aktiver Antigravity-Skill-Pfad. +- **Codex-Hooks:** Skripte unter `.codex/hooks/` sind Codex-spezifisch und bieten keine Ausführungs- oder Sicherheitsgarantie für Antigravity-Sitzungen. +- **Sicherheits-Modus:** Empfohlen wird die Ausführung im Sandbox-Modus (`proceed-in-sandbox`). --- ## Roadmap ### Aktuell Offen (Platzhalter-Befehle): -- `context render`: Generierung sprachlich reduzierter Zusammenfassungen. -- `package compress`: Algorithmen zur verlustbehafteten Trace-Kompression unter Beibehaltung kritischer Hashes. -- `package adversarial`: Robustheitstests gegen gezielte Manipulationen. +- **`agy-ct notebook bundle`** — Bündelt Kontext-Zustände und Textrenderings in einen zusammenhängenden Dokumentations-Payload. ### Zukünftige Schritte: - Erweiterung der synthetischen Planungs-Fixtures. From ed846e21499c7a4e27fc78095842b9b22da4f728 Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Wed, 10 Jun 2026 15:11:07 +0200 Subject: [PATCH 23/27] feat: add notebook bundle command --- agy7rust/src/bin/agy_ct.rs | 31 +++- agy7rust/src/commands/mod.rs | 1 + agy7rust/src/commands/notebook_bundle.rs | 202 +++++++++++++++++++++++ agy7rust/tests/spark_roundtrip.rs | 181 ++++++++++++++++++++ 4 files changed, 412 insertions(+), 3 deletions(-) create mode 100644 agy7rust/src/commands/notebook_bundle.rs diff --git a/agy7rust/src/bin/agy_ct.rs b/agy7rust/src/bin/agy_ct.rs index e804a76..2e78c8c 100644 --- a/agy7rust/src/bin/agy_ct.rs +++ b/agy7rust/src/bin/agy_ct.rs @@ -183,7 +183,24 @@ enum NotebookCommands { #[command( about = "Bundles context state and text renderings into a unified documentation payload" )] - Bundle, + Bundle { + #[arg( + short = 'c', + long = "input-context", + help = "Path to input context JSON" + )] + input_context: String, + + #[arg( + short = 'r', + long = "input-render", + help = "Path to optional input render text" + )] + input_render: Option, + + #[arg(short = 'o', long = "output", help = "Path to output bundle .ipynb")] + output: String, + }, } fn main() -> Result<()> { @@ -256,8 +273,16 @@ fn main() -> Result<()> { } }, Commands::Notebook { subcommand } => match subcommand { - NotebookCommands::Bundle => { - println!("Placeholder: notebook bundle"); + NotebookCommands::Bundle { + input_context, + input_render, + output, + } => { + agy7rust::commands::notebook_bundle::run( + input_context, + input_render.as_deref(), + output, + )?; } }, Commands::Benchmark => { diff --git a/agy7rust/src/commands/mod.rs b/agy7rust/src/commands/mod.rs index 729a4d1..09a716c 100644 --- a/agy7rust/src/commands/mod.rs +++ b/agy7rust/src/commands/mod.rs @@ -6,6 +6,7 @@ pub mod context_build; pub mod context_render; pub mod context_validate; pub mod inspect; +pub mod notebook_bundle; pub mod replay_cmd; pub mod report_export; pub mod schema_check; diff --git a/agy7rust/src/commands/notebook_bundle.rs b/agy7rust/src/commands/notebook_bundle.rs new file mode 100644 index 0000000..fefdb3d --- /dev/null +++ b/agy7rust/src/commands/notebook_bundle.rs @@ -0,0 +1,202 @@ +use anyhow::{Context, Result}; +use std::fs; +use std::path::Path; + +pub fn run( + input_context_path: &str, + input_render_path: Option<&str>, + output_path: &str, +) -> Result<()> { + let context_content = fs::read_to_string(input_context_path) + .with_context(|| format!("Failed to read context file: {}", input_context_path))?; + + let value: serde_json::Value = serde_json::from_str(&context_content) + .with_context(|| format!("Failed to parse context JSON: {}", input_context_path))?; + + let render_text = if let Some(render_path) = input_render_path { + let txt = fs::read_to_string(render_path) + .with_context(|| format!("Failed to read render file: {}", render_path))?; + Some(txt) + } else { + None + }; + + let context_id = value + .get("context_id") + .and_then(|v| v.as_str()) + .unwrap_or("n/a"); + let source_hash = value + .get("source_package_hash") + .and_then(|v| v.as_str()) + .unwrap_or("n/a"); + let schema_name = value + .get("schema_name") + .and_then(|v| v.as_str()) + .unwrap_or("n/a"); + let schema_version = value + .get("schema_version") + .and_then(|v| v.as_u64()) + .map(|v| v.to_string()) + .unwrap_or_else(|| "n/a".to_string()); + + let (valid_status, failure_labels_str, issues_str) = + if let Some(validation) = value.get("validation") { + let valid = validation + .get("valid") + .and_then(|v| v.as_bool()) + .unwrap_or(false); + let valid_str = if valid { "PASS" } else { "FAIL" }; + + let labels = validation + .get("failure_labels") + .and_then(|v| v.as_array()) + .map(|arr| { + arr.iter() + .filter_map(|x| x.as_str()) + .collect::>() + .join(", ") + }) + .unwrap_or_else(|| "none".to_string()); + + let issues = validation + .get("issues") + .and_then(|v| v.as_array()) + .map(|arr| { + arr.iter() + .filter_map(|x| x.as_str()) + .collect::>() + .join(", ") + }) + .unwrap_or_else(|| "none".to_string()); + + (valid_str, labels, issues) + } else { + ("n/a", "n/a".to_string(), "n/a".to_string()) + }; + + let non_claims_str = value + .get("non_claims") + .and_then(|v| v.as_array()) + .map(|arr| { + arr.iter() + .filter_map(|x| x.as_str()) + .collect::>() + .join(", ") + }) + .unwrap_or_else(|| "none".to_string()); + + let mut metadata_md = String::new(); + metadata_md.push_str("## Context Metadata\n"); + metadata_md.push_str(&format!("- **Context ID**: {}\n", context_id)); + metadata_md.push_str(&format!("- **Source Package Hash**: {}\n", source_hash)); + metadata_md.push_str(&format!( + "- **Schema**: {} (v{})\n", + schema_name, schema_version + )); + metadata_md.push_str(&format!("- **Validation Status**: {}\n", valid_status)); + metadata_md.push_str(&format!("- **Failure Labels**: {}\n", failure_labels_str)); + metadata_md.push_str(&format!("- **Issues**: {}\n", issues_str)); + metadata_md.push_str(&format!("- **Non-Claims**: {}\n", non_claims_str)); + + let mut cells = serde_json::json!([]); + + let cell1 = serde_json::json!({ + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# CompText-Sparkctl Operational Notebook Bundle\n", + "\n", + "This notebook contains the bundled context state and text renderings for review.\n" + ] + }); + cells.as_array_mut().unwrap().push(cell1); + + let cell2_source: Vec = metadata_md.lines().map(|l| format!("{}\n", l)).collect(); + let cell2 = serde_json::json!({ + "cell_type": "markdown", + "metadata": {}, + "source": cell2_source + }); + cells.as_array_mut().unwrap().push(cell2); + + if let Some(txt) = render_text { + let cell3_content = format!("## Text Rendering\n\n{}", txt); + let cell3_source: Vec = cell3_content.lines().map(|l| format!("{}\n", l)).collect(); + let cell3 = serde_json::json!({ + "cell_type": "markdown", + "metadata": {}, + "source": cell3_source + }); + cells.as_array_mut().unwrap().push(cell3); + } + + let code_source = vec![ + "# Raw Context JSON representation\n".to_string(), + "import json\n".to_string(), + "raw_context = json.loads(\"\"\"".to_string(), + serde_json::to_string_pretty(&value)?, + "\"\"\")\n".to_string(), + "print(f\"Loaded Context ID: {raw_context.get('context_id', 'n/a')}\")\n".to_string(), + ]; + let cell4 = serde_json::json!({ + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": code_source + }); + cells.as_array_mut().unwrap().push(cell4); + + let ipynb = serde_json::json!({ + "cells": cells, + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "name": "python" + } + }, + "nbformat": 4, + "nbformat_minor": 5 + }); + + let output_path_buf = Path::new(output_path); + if let Some(parent) = output_path_buf.parent() { + if !parent.exists() { + fs::create_dir_all(parent) + .with_context(|| format!("Failed to create directory: {:?}", parent))?; + } + } + + let parent_dir = output_path_buf.parent().unwrap_or_else(|| Path::new(".")); + let file_name = output_path_buf + .file_name() + .ok_or_else(|| anyhow::anyhow!("Invalid output path filename"))? + .to_str() + .ok_or_else(|| anyhow::anyhow!("Filename contains invalid Unicode"))?; + + let pid = std::process::id(); + let time = std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap_or_default() + .as_millis(); + let temp_file_name = format!(".{}_{}_{}.tmp", file_name, pid, time); + let temp_path = parent_dir.join(temp_file_name); + + let serialized = serde_json::to_string_pretty(&ipynb)?; + fs::write(&temp_path, &serialized) + .with_context(|| format!("Failed to write to temp file: {:?}", temp_path))?; + + if let Err(e) = fs::rename(&temp_path, output_path) { + let _ = fs::remove_file(&temp_path); + return Err(anyhow::anyhow!(e).context(format!( + "Failed to rename temp file {:?} to output file {:?}", + temp_path, output_path_buf + ))); + } + + Ok(()) +} diff --git a/agy7rust/tests/spark_roundtrip.rs b/agy7rust/tests/spark_roundtrip.rs index 07de903..06e1789 100644 --- a/agy7rust/tests/spark_roundtrip.rs +++ b/agy7rust/tests/spark_roundtrip.rs @@ -2308,3 +2308,184 @@ fn test_agy_ct_report_export_execution() { let _ = fs::remove_file(&temp_bad_input_path); let _ = fs::remove_file(&temp_output_path); } + +#[test] +fn test_agy_ct_notebook_bundle_execution() { + use serde_json::json; + use std::fs; + use std::process::Command; + + let pid = std::process::id(); + let time = std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap_or_default() + .as_millis(); + let suffix = format!("{}_{}", pid, time); + + let temp_dir = std::env::temp_dir(); + let temp_context_path = temp_dir.join(format!("test_context_{}.json", suffix)); + let temp_render_path = temp_dir.join(format!("test_render_{}.txt", suffix)); + let temp_output_path = temp_dir.join(format!("test_bundle_{}.ipynb", suffix)); + let temp_output_no_render_path = + temp_dir.join(format!("test_bundle_no_render_{}.ipynb", suffix)); + let temp_bad_context_path = temp_dir.join(format!("test_bad_context_{}.json", suffix)); + + // Clean up from previous runs + let _ = fs::remove_file(&temp_context_path); + let _ = fs::remove_file(&temp_render_path); + let _ = fs::remove_file(&temp_output_path); + let _ = fs::remove_file(&temp_output_no_render_path); + let _ = fs::remove_file(&temp_bad_context_path); + + // Mock operational context JSON + let mock_context = json!({ + "context_id": "mock-ctx-123", + "source_package_hash": "abc123hash", + "schema_name": "genehmigung_v1", + "schema_version": 1, + "required_field_paths": ["field_a"], + "satisfied_field_paths": ["field_a"], + "missing_field_paths": [], + "constraints": [], + "required_order": [], + "dependency_edges": [], + "blockers": [], + "recovery_paths": [], + "validation": { + "valid": true, + "failure_labels": [], + "issues": [] + }, + "non_claims": ["No production claim"] + }); + + fs::write( + &temp_context_path, + serde_json::to_string_pretty(&mock_context).unwrap(), + ) + .unwrap(); + + let mock_render = "This is a mock render text summary."; + fs::write(&temp_render_path, mock_render).unwrap(); + + // ============================================ + // 1. Success Test: With Render Output + // ============================================ + let output_success = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "notebook", + "bundle", + "-c", + temp_context_path.to_str().unwrap(), + "-r", + temp_render_path.to_str().unwrap(), + "-o", + temp_output_path.to_str().unwrap(), + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(output_success.status.success()); + assert!(temp_output_path.exists()); + let ipynb_content = fs::read_to_string(&temp_output_path).unwrap(); + assert!(!ipynb_content.is_empty()); + + let ipynb_json: serde_json::Value = serde_json::from_str(&ipynb_content).unwrap(); + assert_eq!(ipynb_json["nbformat"].as_u64(), Some(4)); + let cells = ipynb_json["cells"] + .as_array() + .expect("cells should be an array"); + assert!(!cells.is_empty()); + + // Check cells content + let cells_str = ipynb_content.to_string(); + assert!(cells_str.contains("CompText-Sparkctl Operational Notebook Bundle")); + assert!(cells_str.contains("mock-ctx-123")); + assert!(cells_str.contains("This is a mock render text summary.")); + + // ============================================ + // 2. Success Test: Without Render Output + // ============================================ + let output_success_no_render = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "notebook", + "bundle", + "-c", + temp_context_path.to_str().unwrap(), + "-o", + temp_output_no_render_path.to_str().unwrap(), + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(output_success_no_render.status.success()); + assert!(temp_output_no_render_path.exists()); + let ipynb_no_render_content = fs::read_to_string(&temp_output_no_render_path).unwrap(); + assert!(!ipynb_no_render_content.is_empty()); + assert!(ipynb_no_render_content.contains("CompText-Sparkctl Operational Notebook Bundle")); + assert!(!ipynb_no_render_content.contains("This is a mock render text summary.")); + + // ============================================ + // 3. Failure Test 1: Missing input file + // ============================================ + let non_existent_input = temp_dir.join(format!("test_context_non_existent_{}.json", suffix)); + let _ = fs::remove_file(&non_existent_input); + + let output_failure_missing = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "notebook", + "bundle", + "-c", + non_existent_input.to_str().unwrap(), + "-o", + temp_output_path.to_str().unwrap(), + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(!output_failure_missing.status.success()); + + // ============================================ + // 4. Failure Test 2: Corrupted JSON input + // ============================================ + fs::write(&temp_bad_context_path, "{ \"invalid\": ").unwrap(); + + let output_failure_corrupt = Command::new("cargo") + .args([ + "run", + "--bin", + "agy-ct", + "--", + "notebook", + "bundle", + "-c", + temp_bad_context_path.to_str().unwrap(), + "-o", + temp_output_path.to_str().unwrap(), + ]) + .output() + .expect("failed to execute cargo run"); + + assert!(!output_failure_corrupt.status.success()); + + // ============================================ + // 5. Cleanup + // ============================================ + let _ = fs::remove_file(&temp_context_path); + let _ = fs::remove_file(&temp_render_path); + let _ = fs::remove_file(&temp_output_path); + let _ = fs::remove_file(&temp_output_no_render_path); + let _ = fs::remove_file(&temp_bad_context_path); +} From ae6a2bd5dd5736915590e026157e6758ff4f3ddd Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Wed, 10 Jun 2026 15:14:08 +0200 Subject: [PATCH 24/27] docs: finalize CLI alignment after notebook bundle --- README.md | 12 +++++++++--- docs/SPARK_ALIGNMENT.md | 5 +++-- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 08bdbed..be28306 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,11 @@ flowchart LR C --> D["package verify"] C --> E["package inspect"] C --> F["package adversarial"] + C --> I["context build"] + I --> J["context render"] + I --> K["notebook bundle"] + J --> K + K --> L[".ipynb Notebook"] A --> G["report export"] G --> H["Markdown Report"] ``` @@ -56,6 +61,7 @@ Sparkctl implementiert Mechanismen zur Absicherung synthetischer Planungsdaten. - **`agy-ct package replay`** — Rekonstruiert die aufgezeichnete Trace deterministisch (strikte stdout/stderr Kanaltrennung). - **`agy-ct package adversarial`** — Simuliert manipulierte Attribute zur Überprüfung der Manipulationserkennung. - **`agy-ct report export`** — Exportiert JSON-Pipeline-Berichte als formatierten Markdown-Report. +- **`agy-ct notebook bundle`** — Bündelt Kontext-Zustände und Textrenderings in ein `.ipynb` Jupyter Notebook. - **`agy-ct schema check`** — Gleicht rohe Trace-Dateien gegen JSON-Schemas ab. - **`agy-ct context validate`** — Führt strukturelle Validierung und Leckprüfungen auf Kontextmodellen durch. - **`agy-ct context build`** — Erzeugt strukturierte operative Kontextmodelle. @@ -75,7 +81,7 @@ Sparkctl implementiert Mechanismen zur Absicherung synthetischer Planungsdaten. | **Context** | `context render` | `context_render::run` | Wired | Token-reduzierter Text | 100% PASS | | **Context** | `context validate` | `context_validate::run` | Wired | Leck- und Strukturprüfungsbericht | 100% PASS | | **Report** | `report export` | `report_export::run` | Wired | Markdown-Export (`.md`) | 100% PASS | -| **Notebook** | `notebook bundle` | N/A | Placeholder | Unified payload | Ausstehend | +| **Notebook** | `notebook bundle` | `notebook_bundle::run` | Wired | `.ipynb` Jupyter Notebook | 100% PASS | --- @@ -87,7 +93,7 @@ Führen Sie die folgenden sicheren lokalen Befehle im Rust-Unterverzeichnis aus: # In das Rust-Verzeichnis wechseln cd agy7rust -# Testsuite ausführen (72 PASS Tests) +# Testsuite ausführen (73 PASS Tests) cargo test # Berichtsexport mit einer synthetischen Beispieldokumentation ausführen @@ -140,7 +146,7 @@ Dieses Repository nutzt klare Richtlinien für die lokale Ausführung von KI-Ent ## Roadmap ### Aktuell Offen (Platzhalter-Befehle): -- **`agy-ct notebook bundle`** — Bündelt Kontext-Zustände und Textrenderings in einen zusammenhängenden Dokumentations-Payload. +- Keine bekannten CLI-Platzhalter mehr. ### Zukünftige Schritte: - Erweiterung der synthetischen Planungs-Fixtures. diff --git a/docs/SPARK_ALIGNMENT.md b/docs/SPARK_ALIGNMENT.md index 38552a3..6e4cc46 100644 --- a/docs/SPARK_ALIGNMENT.md +++ b/docs/SPARK_ALIGNMENT.md @@ -55,6 +55,7 @@ The following `agy-ct` subcommands are fully wired and functional: * **`agy-ct package compress`** — wired to `compress::run` * **`agy-ct package adversarial`** — wired to `adversarial::run` * **`agy-ct report export`** — wired to `report_export::run` (CLI: `-i -o `) +* **`agy-ct notebook bundle`** — wired to `notebook_bundle::run` (CLI: `-c [-r ] -o `) * **`agy-ct schema check`** — wired to `schema_check::run` * **`agy-ct context validate`** — wired to `context_validate::run` * **`agy-ct context build`** — wired to `context_build::run` @@ -67,8 +68,8 @@ The `package replay` command implements a strict separation of output streams: * Global CLI flags `--quiet` (suppresses status output), `--plain` (strips ANSI escapes), and `--no-color` (disables terminal color codes) are explicitly supported. ### 4. Test and Placeholders Status -* **Validation Status:** The local Rust test suite executes successfully with **72 PASS** tests (targeted report export test PASS). -* **Remaining Placeholders:** The subcommand `notebook bundle` remains as a placeholder. +* **Validation Status:** The local Rust test suite executes successfully with **73 PASS** tests (targeted notebook bundle test PASS). +* **Remaining Placeholders:** Keine bekannten CLI-Platzhalter mehr. ### 5. Exclusion and Alignment Boundaries * **XENTRY/OBD/X-Engine:** Legacy/future diagnostic components (including OBD-II logs and X-Engine sandwich parsers) remain completely excluded from the active scope. From c6d9b5ffefc2b8baf0a8987060b17de5515d7198 Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Wed, 10 Jun 2026 15:24:49 +0200 Subject: [PATCH 25/27] docs: preserve Antigravity workspace context assets --- .antigravity/AGENTS.md | 51 +++++++++++++ .antigravity/BOOTSTRAP.md | 32 ++++++++ .antigravity/SKILL_INVENTORY.md | 74 +++++++++++++++++++ .antigravity/START_HERE.md | 31 ++++++++ .antigravity/hooks/hook-policy.example.json | 35 +++++++++ .../plugin.example.json | 15 ++++ .../plugin.example.json | 20 +++++ .antigravity/settings.comptext-sparkctl.json | 24 ++++++ docs/context/ACTIVE_WORK_LEDGER.md | 24 ++++++ docs/context/ANTIGRAVITY_MIGRATION_LEDGER.md | 33 +++++++++ docs/context/CLAIM_HYGIENE_LEDGER.md | 20 +++++ .../COMPTEXT_SPARKCTL_CONTEXT_CAPSULE.md | 35 +++++++++ 12 files changed, 394 insertions(+) create mode 100644 .antigravity/AGENTS.md create mode 100644 .antigravity/BOOTSTRAP.md create mode 100644 .antigravity/SKILL_INVENTORY.md create mode 100644 .antigravity/START_HERE.md create mode 100644 .antigravity/hooks/hook-policy.example.json create mode 100644 .antigravity/plugins/comptext-context-cache/plugin.example.json create mode 100644 .antigravity/plugins/comptext-sparkctl-guard/plugin.example.json create mode 100644 .antigravity/settings.comptext-sparkctl.json create mode 100644 docs/context/ACTIVE_WORK_LEDGER.md create mode 100644 docs/context/ANTIGRAVITY_MIGRATION_LEDGER.md create mode 100644 docs/context/CLAIM_HYGIENE_LEDGER.md create mode 100644 docs/context/COMPTEXT_SPARKCTL_CONTEXT_CAPSULE.md diff --git a/.antigravity/AGENTS.md b/.antigravity/AGENTS.md new file mode 100644 index 0000000..80e4cd9 --- /dev/null +++ b/.antigravity/AGENTS.md @@ -0,0 +1,51 @@ +# Antigravity Agent Rules + +> [!IMPORTANT] +> **Status**: inert, repo-local, review-gated, not active runtime. This config/documentation is for reference only. + +This repository is part of CompText. + +CompText is a deterministic Context Pack / proposal-gated evidence workflow, not a generic AI dashboard, not an agent memory product, and not an autonomous deployment agent. + +Core line: +Models are providers. Context is the product. + +Pipeline: +Source / GitHub URL → Goal → Inspect → Context Pack → Policy Gate → Provider Boundary → Untrusted Proposal → Human Review → Artifacts + +## Skill Sources Classifications + +Within this repository: +- **.agent/skills** = repo guidance source +- **.agents/skills** = compatibility metadata +- **docs/phase8a-draft-skills** = draft source +- **.antigravity** = inert adapted workspace config + +## Hard Rules + +- Treat GitHub as read-only unless the human explicitly asks otherwise. +- Do not push, deploy, create PRs, create issues, or create remote branches. +- Do not expose secrets. +- Do not fake hashes. +- Do not claim production-ready, EU AI Act compliance, legal certification, forensic proof, guaranteed correctness, or autonomous approval. +- Provider output is untrusted until reviewed. +- Proposals are never auto-applied. +- Human review is the approval boundary. +- Artifacts preserve the evidence trail. +- Keep changes scoped and reviewable. +- Do not modify root `README.md` unless the human explicitly approves it. +- Do not commit `reports/latest.json`. +- Do not commit `reports/performance_baseline.json` when it is only validation churn. +- Run cargo commands only inside `agy7rust/` unless the human explicitly approves otherwise. + +## Antigravity Governance + +- Repo-local Antigravity hooks live under `.antigravity/hooks/` and must be reviewed/trusted by Antigravity before enforcement. +- Antigravity hooks block unauthorized git writes, deploy/release actions, environment dumps, secret-file reads, `agy-ct run`, and `agy-ct benchmark`. +- Antigravity hooks warn on protected source, README, report, and `artifacts/spark/` changes; warnings do not make generated artifacts commit-ready. + +Before editing: +1. Read AGENTS.md. +2. Read `.antigravity/SKILL_INVENTORY.md` relevant to the task. +3. Build a compact repo map. +4. Stop for approval if the user asked for plan mode. diff --git a/.antigravity/BOOTSTRAP.md b/.antigravity/BOOTSTRAP.md new file mode 100644 index 0000000..987c1da --- /dev/null +++ b/.antigravity/BOOTSTRAP.md @@ -0,0 +1,32 @@ +# Antigravity Bootstrap Context + +> [!IMPORTANT] +> **Status**: inert, repo-local, review-gated, not active runtime. Reference only. + +## 1. Bootstrap Protocol +To prevent context redundancy, follow this exact initial sequence: +1. Read `AGENTS.md` first for fundamental workspace rules. +2. Read `.antigravity/BOOTSTRAP.md` second to align config boundaries. +3. Use `.antigravity/SKILL_INVENTORY.md` as the index for local/system skills. + +## 2. Repo Purpose & Scope +Deterministic trace packaging, replay-sidecar validation, and SPARK-style context artifact rendering for CompText. + +## 3. Skill & Source Classifications +- **.agent/skills**: Repo guidance source (15 guidelines). +- **.agents/skills**: Compatibility metadata (9 legacy skill directories). +- **docs/phase8a-draft-skills**: Draft global skill candidates / design source only. +- **.antigravity**: Inert adapted workspace configuration directory. + +## 4. Environment & Safety Boundaries +- **Hooks & Plugins**: Inert, repo-local, review-gated, not active runtime. +- **MCP Status**: Disabled/Not active. Do not create `.mcp.json`. +- **Claim Hygiene**: No production-ready, EU AI Act, legal, or official SPARK compatibility claims. +- **Allowed Edit Zones**: `./.antigravity/` and `./docs/context/` only. +- **Forbidden Edit Zones**: Rust sources (`./agy7rust/src/`), `README.md`, `.agent/skills/`, `.agents/skills/`, and `.codex/`. +- **Hard Rules**: Treat GitHub as read-only. No commits, pushes, deploys, secrets, or `.env` dumps. + +## 5. Next Workflow Order +1. Load startup parameters from `.antigravity/START_HERE.md`. +2. Inspect `docs/context/COMPTEXT_SPARKCTL_CONTEXT_CAPSULE.md` for active project state. +3. Formulate plans for user approval before proposing edits. diff --git a/.antigravity/SKILL_INVENTORY.md b/.antigravity/SKILL_INVENTORY.md new file mode 100644 index 0000000..3cf75f3 --- /dev/null +++ b/.antigravity/SKILL_INVENTORY.md @@ -0,0 +1,74 @@ +# Antigravity Skill Inventory + +> [!IMPORTANT] +> **Status**: inert, repo-local, review-gated, not active runtime. This config/documentation is for reference only. + +This inventory provides a complete comparison and registry of the skill sources in the repository, mapped to Antigravity guidelines. + +## Skill Sources Classifications + +- **.agent/skills** = repo guidance source +- **.agents/skills** = compatibility metadata +- **docs/phase8a-draft-skills** = draft source +- **.antigravity** = inert adapted workspace config + +--- + +## 1. Repo Guidance Source (`.agent/skills/`) + +These 15 files represent local repository guidance guidelines: +- `00_project_system.md`: Project system initialization guidelines. +- `01_phase_gate.md`: Phase transition verification. +- `02_rust_validation.md`: Cargo checks and testing protocols. +- `03_artifact_validation.md`: Validation rules for generated assets. +- `04_spark_context_layer.md`: Context pipeline documentation. +- `05_claim_hygiene.md`: Claim constraints. +- `06_git_handoff.md`: Handoff protocols. +- `07_cli_surface.md`: Command surface rules. +- `08_agentic_output_contract.md`: Code quality expectations. +- `09_codex_desktop_governance.md` -> **09_antigravity_governance.md**: Hook rules and boundaries. +- `09_phase6_implementation_gate.md`: Gate guidelines for Phase 6. +- `10_generated_artifact_policy.md`: Generated output management rules. +- `10_spark_evidence_review.md`: Evidence package checking instructions. +- `11_comptext_validate.md`: Local validation commands execution guide. +- `12_agent_handoff_profile.md`: Profile specifications for handoffs. + +--- + +## 2. Compatibility Metadata (`.agents/skills/`) + +These 9 folders contain compatibility metadata (with `SKILL.md` files): +- **comptext-governance**: Mapped to Antigravity workflow governance for CompText integrity. +- **codex-role-workflows** -> **antigravity-role-workflows**: Guidelines for role orchestration. +- **codex-token-saving** -> **antigravity-token-saving**: Strategies to minimize prompt size and trace context. +- **pdf-extraction-contracts**: Structural rules for processing and validation of PDF files. +- **reviewer-final-report**: Guidelines for creating evidence reports for human review. +- **rust-canonical-artifacts**: Rules for generating serialized Rust structures. +- **security-readonly-boundaries**: Enforcing read-only rules for source control and GitHub. +- **spark-hackathon-alignment**: Specific prompt engineering and validation guides for the SPARK challenge. +- **sparkctl-evidence-packet**: Structuring SPARK evidence packets for review gates. + +--- + +## 3. Draft Source (`docs/phase8a-draft-skills/`) + +These 7 subdirectories contain draft global skill candidates for review only: +- **comptext-operating-boundary**: Load governance and confirm boundaries before CompText work. +- **comptext-context-pack-review**: Review deterministic, redacted, replayable Context Pack workflows. +- **comptext-proposal-gate-review**: Review proposal schema, path safety, validation commands, and human gate before apply. +- **comptext-provider-boundary**: Review dry-run-first provider boundaries, network deny-by-default, auth metadata redaction, and untrusted outputs. +- **comptext-claim-hygiene**: Review docs and handoffs for unsupported assurance claims. +- **comptext-artifact-hygiene**: Classify generated artifacts and commit candidates before staging or handoff. +- **comptext-compact-handoff**: Produce concise phase handoffs with files, commands, validation, git state, risks, and next action. + +--- + +## 4. System-Level Antigravity Skills + +The following core Antigravity capabilities are available to this assistant: +- **kernel-dev**: Logic for Multimodal Graph VM and Bytecode Execution. +- **replay-engine**: Kernel Record-Replay (KRR) and Determinism Logic. +- **workflow-skill-creator**: Packages a completed workflow into a reusable Antigravity skill. +- **uv**: Python package manager helper. +- **Scientific Databases**: ensembl-database, pubchem-database, uniprot-database, gnomad-database, clinical-trials-database, etc. +- **Literature Search**: literature-search-arxiv, literature-search-openalex, pubmed-database, etc. diff --git a/.antigravity/START_HERE.md b/.antigravity/START_HERE.md new file mode 100644 index 0000000..875e8d8 --- /dev/null +++ b/.antigravity/START_HERE.md @@ -0,0 +1,31 @@ +# Antigravity Start Here + +> [!IMPORTANT] +> **Status**: inert, repo-local, review-gated, not active runtime. Reference only. + +## Prompt Template +When initializing a new session with this repository, always start with: +`Read .antigravity/START_HERE.md first.` + +## Quick Summary Matrix + +| Metric / Item | Status / Value | Description | +|---|---|---| +| **Repo Purpose** | CompText validation | Deterministic packaging & SPARK-style rendering. | +| **Hook Status** | Inert | Not active runtime. Located in `.antigravity/hooks/`. | +| **Plugin Status** | Inert | Not active runtime. Located in `.antigravity/plugins/`. | +| **MCP Status** | Inactive | No `.mcp.json` or active MCP server allowed. | +| **Claim Hygiene** | Bounded | Provider output is untrusted. No legal/compliance claims. | +| **Allowed Edits** | `./.antigravity/`, `./docs/context/` | Restricted scope for configuration adjustments. | +| **Forbidden Edits**| Rust, README, `.codex/`, `.agent/skills/` | Do not modify code, README, or active Codex files. | + +## Guidance Chain +1. **First**: Read `AGENTS.md` to establish the safety rules. +2. **Second**: Read `.antigravity/BOOTSTRAP.md` to load the context booster. +3. **Index**: Use `.antigravity/SKILL_INVENTORY.md` to index local and system skills. +4. **Active State**: See `docs/context/COMPTEXT_SPARKCTL_CONTEXT_CAPSULE.md`. + +## Safety Rules +- Provider output is untrusted; human review is the approval gate. +- Repo-relative paths only. No secrets or env dumps. +- Do not commit or push. diff --git a/.antigravity/hooks/hook-policy.example.json b/.antigravity/hooks/hook-policy.example.json new file mode 100644 index 0000000..26deaca --- /dev/null +++ b/.antigravity/hooks/hook-policy.example.json @@ -0,0 +1,35 @@ +{ + "status": "inert", + "scope": "repo-local", + "governance": "review-gated", + "runtime": "not active runtime", + "description": "Example Antigravity hooks policy for validating local agent actions before and after tool usage", + "hooks": { + "PreToolUse": [ + { + "matcher": "run_command|execute_url", + "action": "warn_or_block", + "policy_path": "./.antigravity/hooks/pre_tool_policy_example.py" + } + ], + "PostToolUse": [ + { + "matcher": "write_file|replace_file_content|run_command", + "action": "validate", + "validation_path": "./.antigravity/hooks/post_tool_validation_example.py" + } + ] + }, + "blocked_commands": [ + "git push", + "git commit", + "cargo run --bin agy-ct -- run", + "cargo run --bin agy-ct -- benchmark" + ], + "protected_paths": [ + "./README.md", + "./agy7rust/src/", + "./reports/", + "./artifacts/spark/" + ] +} diff --git a/.antigravity/plugins/comptext-context-cache/plugin.example.json b/.antigravity/plugins/comptext-context-cache/plugin.example.json new file mode 100644 index 0000000..35c1595 --- /dev/null +++ b/.antigravity/plugins/comptext-context-cache/plugin.example.json @@ -0,0 +1,15 @@ +{ + "name": "comptext-context-cache", + "status": "inert", + "scope": "repo-local", + "governance": "review-gated", + "runtime": "not active runtime", + "description": "Antigravity plugin to manage local caching of CompText context artifacts", + "version": "1.0.0", + "cache_settings": { + "enabled": false, + "cache_dir": "./artifacts/cache", + "retention_days": 7, + "verify_hashes": true + } +} diff --git a/.antigravity/plugins/comptext-sparkctl-guard/plugin.example.json b/.antigravity/plugins/comptext-sparkctl-guard/plugin.example.json new file mode 100644 index 0000000..a333ff0 --- /dev/null +++ b/.antigravity/plugins/comptext-sparkctl-guard/plugin.example.json @@ -0,0 +1,20 @@ +{ + "name": "comptext-sparkctl-guard", + "status": "inert", + "scope": "repo-local", + "governance": "review-gated", + "runtime": "not active runtime", + "description": "Antigravity plugin protecting CompText boundaries and ensuring human review validation", + "version": "1.0.0", + "rules": { + "block_remote_writes": true, + "require_human_review": true, + "untrusted_provider_output": true, + "repo_relative_paths_only": true + }, + "monitored_paths": [ + "./agy7rust/src/", + "./reports/", + "./artifacts/spark/" + ] +} diff --git a/.antigravity/settings.comptext-sparkctl.json b/.antigravity/settings.comptext-sparkctl.json new file mode 100644 index 0000000..c535450 --- /dev/null +++ b/.antigravity/settings.comptext-sparkctl.json @@ -0,0 +1,24 @@ +{ + "status": "inert", + "scope": "repo-local", + "governance": "review-gated", + "runtime": "not active runtime", + "project": { + "name": "comptext-sparkctl", + "root_dir": "./", + "rust_dir": "./agy7rust" + }, + "antigravity": { + "skills_dir": "./.agents/skills", + "hooks_dir": "./.antigravity/hooks", + "plugins_dir": "./.antigravity/plugins" + }, + "safety_rules": { + "provider_output_untrusted": true, + "human_review_required": true, + "repo_relative_only": true, + "allow_push": false, + "allow_deploy": false, + "expose_secrets": false + } +} diff --git a/docs/context/ACTIVE_WORK_LEDGER.md b/docs/context/ACTIVE_WORK_LEDGER.md new file mode 100644 index 0000000..633eb42 --- /dev/null +++ b/docs/context/ACTIVE_WORK_LEDGER.md @@ -0,0 +1,24 @@ +# Active Work Ledger + +> [!IMPORTANT] +> **Status**: inert, repo-local, review-gated, not active runtime. This ledger is for local reference and documentation only. + +This ledger tracks active work items, task mappings, and status checkpoints for the CompText-Sparkctl project. + +## Active Task Inventory + +1. **Antigravity Mapping Configuration**: + - Mapping Codex concepts to Antigravity. (Status: Done) + - Configuration files created under `./.antigravity/`. (Status: Done) + - Migration and claim ledgers created under `./docs/context/`. (Status: Done) + +2. **Compliance / Verification Gate**: + - Ensure all provider outputs are treated as untrusted proposals. + - Maintain the human review approval gate before modifying any source tree. + - Restrict all actions to repo-relative paths only. + +## Local Environment Integrity + +- **Active Runtime**: None (hooks and plugins are example files and not actively running). +- **GitHub / Remote Writes**: Blocked (read-only mode is active). +- **Environment and Secret Isolation**: No secrets, `.env`, or credential tokens are read or referenced. diff --git a/docs/context/ANTIGRAVITY_MIGRATION_LEDGER.md b/docs/context/ANTIGRAVITY_MIGRATION_LEDGER.md new file mode 100644 index 0000000..dfb6506 --- /dev/null +++ b/docs/context/ANTIGRAVITY_MIGRATION_LEDGER.md @@ -0,0 +1,33 @@ +# Antigravity Migration Ledger + +> [!IMPORTANT] +> **Status**: inert, repo-local, review-gated, not active runtime. This ledger is for local reference and documentation only. + +This file documents the conceptual mapping and legacy source classifications between Codex and Antigravity for the CompText project context. + +## Skill Sources Classifications + +- **.agent/skills** = repo guidance source +- **.agents/skills** = compatibility metadata +- **docs/phase8a-draft-skills** = draft source +- **.antigravity** = inert adapted workspace config + +## Codex to Antigravity Mapping Rules + +We map the original Codex infrastructure concepts to their Antigravity equivalents in all new documentation and configurations: + +| Codex Concept | Antigravity Concept | Description | +|---|---|---| +| Codex App | Antigravity | The core agent system workspace and host application. | +| Codex CLI | Antigravity CLI | The CLI execution layer for local agent orchestration. | +| Codex skills | Antigravity skills | The repository-relative or system-level capabilities. | +| Codex hooks | Antigravity hooks | Pre-tool and post-tool execution policy validation hooks. | +| Codex plugin | Antigravity plugin | Custom plugins extending workspace capabilities. | +| Codex workflow | Antigravity workflow | The pipeline executing the Context Pack process. | + +## Migration Status + +- **Migration Mode**: Manual documentation and alignment mapping. +- **Hook Integration**: Mapped, but disabled (inert, not active runtime). +- **Skill Discovery**: Completed; mapped to local directories and system-level capabilities. +- **Legacy Alignment**: Legacy and draft skill sources classified and cataloged. diff --git a/docs/context/CLAIM_HYGIENE_LEDGER.md b/docs/context/CLAIM_HYGIENE_LEDGER.md new file mode 100644 index 0000000..1349682 --- /dev/null +++ b/docs/context/CLAIM_HYGIENE_LEDGER.md @@ -0,0 +1,20 @@ +# Claim Hygiene Ledger + +> [!IMPORTANT] +> **Status**: inert, repo-local, review-gated, not active runtime. This ledger is for local reference and documentation only. + +This ledger documents the rules and guidelines for claim hygiene to prevent false, exaggerated, or compliance-oriented claims. + +## Governance Boundaries + +All documentation, metadata, and proposals generated must adhere to these strict bounds: + +- **Provider Output is Untrusted**: Any generation or proposal from a language model must be verified and approved by a human reviewer. +- **Human Review Approval Gate**: No proposal is auto-applied. The human is the definitive gate. +- **No Production-Ready Claims**: Do not claim the system is production-ready, enterprise-grade, or fully autonomous. +- **No Compliance Claims**: Do not claim compliance with the EU AI Act, forensic standards, legal audits, or certified compliance. +- **No Hallucination-Free Claims**: CompText is a deterministic pipeline, but makes no claim of resolving or eliminating hallucinations generally. +- **Environment Boundaries**: + - Restrict command execution and source edits to the local repo. + - No secrets, `.env` exposure, or environment dumps are permitted. + - No push/deploy commands are permitted. diff --git a/docs/context/COMPTEXT_SPARKCTL_CONTEXT_CAPSULE.md b/docs/context/COMPTEXT_SPARKCTL_CONTEXT_CAPSULE.md new file mode 100644 index 0000000..6c3a4f5 --- /dev/null +++ b/docs/context/COMPTEXT_SPARKCTL_CONTEXT_CAPSULE.md @@ -0,0 +1,35 @@ +# CompText Sparkctl Context Capsule + +> [!IMPORTANT] +> **Status**: inert, repo-local, review-gated, not active runtime. Reference only. + +This capsule acts as a persistent repository data store for Antigravity config state, avoiding document repetition in prompts. + +## 1. Governance & Protocol Chain +- **Read Order**: + 1. `AGENTS.md` (Rules and core constraints) + 2. `.antigravity/BOOTSTRAP.md` (Context alignment) + 3. `.antigravity/START_HERE.md` (Active prompt template) +- **Index**: Reference `.antigravity/SKILL_INVENTORY.md` for local and system capabilities. + +## 2. Skill Source Classifications +- `.agent/skills/` = repo guidance source +- `.agents/skills/` = compatibility metadata +- `docs/phase8a-draft-skills/` = draft source / design reference only +- `.antigravity/` = inert adapted workspace config + +## 3. Project Configuration Matrix +- **Purpose**: Local packaging, validation, and metadata generation for CompText. +- **Hook Status**: Inert (no active runtime) example configs. +- **Plugin Status**: Inert (no active runtime) example configs. +- **MCP Status**: Inactive (no MCP configurations or servers). +- **Claim Hygiene**: Strict adherence to no production-ready, legal, compliance, or official SPARK claims. Provider output is untrusted and human review is the gate. +- **Edit Isolation**: + - *Allowed*: `./.antigravity/` and `./docs/context/`. + - *Forbidden*: `./agy7rust/src/` (Rust source), `./README.md`, `./.agent/skills/`, `./.agents/skills/`, and `./.codex/`. +- **Handoff Rules**: All paths must be repo-relative. No secrets, `.env` files, git pushes, or deployments. + +## 4. Next Workflow Order +1. Apply the prompt prefix: `"Read .antigravity/START_HERE.md first."` +2. Follow the bootstrap and inventory files for contextual queries. +3. Obtain user approval before proposing changes to any workspace configs. From 56b913dd580fb9eb6937d5a14be04b68e7bcc50c Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Wed, 10 Jun 2026 16:01:26 +0200 Subject: [PATCH 26/27] fix: harden export paths and CI color tests --- agy7rust/src/commands/notebook_bundle.rs | 2 +- agy7rust/src/commands/report_export.rs | 6 +- agy7rust/tests/spark_roundtrip.rs | 99 +++++++++++++++++++++++- 3 files changed, 102 insertions(+), 5 deletions(-) diff --git a/agy7rust/src/commands/notebook_bundle.rs b/agy7rust/src/commands/notebook_bundle.rs index fefdb3d..c4faf17 100644 --- a/agy7rust/src/commands/notebook_bundle.rs +++ b/agy7rust/src/commands/notebook_bundle.rs @@ -165,7 +165,7 @@ pub fn run( let output_path_buf = Path::new(output_path); if let Some(parent) = output_path_buf.parent() { - if !parent.exists() { + if !parent.as_os_str().is_empty() && !parent.exists() { fs::create_dir_all(parent) .with_context(|| format!("Failed to create directory: {:?}", parent))?; } diff --git a/agy7rust/src/commands/report_export.rs b/agy7rust/src/commands/report_export.rs index af556c6..39188cc 100644 --- a/agy7rust/src/commands/report_export.rs +++ b/agy7rust/src/commands/report_export.rs @@ -45,7 +45,7 @@ pub fn run(input_path: &str, output_path: &str) -> Result<()> { md.push_str(&format!("- **{}**: {}\n", name, status)); } } - md.push_str("\n"); + md.push('\n'); } if let Some(artifacts) = value.get("artifacts").and_then(|v| v.as_array()) { @@ -55,13 +55,13 @@ pub fn run(input_path: &str, output_path: &str) -> Result<()> { md.push_str(&format!("- {}\n", art_str)); } } - md.push_str("\n"); + md.push('\n'); } // Atomic write pattern let output_path_buf = Path::new(output_path); if let Some(parent) = output_path_buf.parent() { - if !parent.exists() { + if !parent.as_os_str().is_empty() && !parent.exists() { fs::create_dir_all(parent) .with_context(|| format!("Failed to create directory: {:?}", parent))?; } diff --git a/agy7rust/tests/spark_roundtrip.rs b/agy7rust/tests/spark_roundtrip.rs index 06e1789..8bff887 100644 --- a/agy7rust/tests/spark_roundtrip.rs +++ b/agy7rust/tests/spark_roundtrip.rs @@ -1623,6 +1623,7 @@ fn test_agy_ct_package_replay_output_streams() { // 3. Plain run (should output JSON on stdout, status on stderr but without ANSI escapes) let output_plain = Command::new("cargo") + .env("CARGO_TERM_COLOR", "never") .args([ "run", "--bin", @@ -2487,5 +2488,101 @@ fn test_agy_ct_notebook_bundle_execution() { let _ = fs::remove_file(&temp_render_path); let _ = fs::remove_file(&temp_output_path); let _ = fs::remove_file(&temp_output_no_render_path); - let _ = fs::remove_file(&temp_bad_context_path); +} + +#[test] +fn test_plain_output_path_no_parent() { + use serde_json::json; + use std::env; + use std::fs; + + let original_dir = env::current_dir().unwrap(); + let temp_dir = std::env::temp_dir(); + + let pid = std::process::id(); + let time = std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap_or_default() + .as_millis(); + let subdir_name = format!("test_plain_dir_{}_{}", pid, time); + let run_dir = temp_dir.join(&subdir_name); + fs::create_dir_all(&run_dir).unwrap(); + + env::set_current_dir(&run_dir).unwrap(); + + // Mock files + let mock_report = json!({ + "tool": "agy-ct", + "project": "CompText-Sparkctl", + "phase": "6E", + "result": "PASS" + }); + fs::write( + "mock_report.json", + serde_json::to_string(&mock_report).unwrap(), + ) + .unwrap(); + + let mock_context = json!({ + "context_id": "mock-ctx-123", + "source_package_hash": "abc123hash", + "schema_name": "genehmigung_v1", + "schema_version": 1, + "required_field_paths": ["field_a"], + "satisfied_field_paths": ["field_a"], + "missing_field_paths": [], + "constraints": [], + "required_order": [], + "dependency_edges": [], + "blockers": [], + "recovery_paths": [], + "validation": { + "valid": true, + "failure_labels": [], + "issues": [] + }, + "non_claims": [] + }); + fs::write( + "mock_context.json", + serde_json::to_string(&mock_context).unwrap(), + ) + .unwrap(); + + // 1. Report export test + let res_report = agy7rust::commands::report_export::run("mock_report.json", "report.md"); + assert!( + res_report.is_ok(), + "Report export failed: {:?}", + res_report.err() + ); + assert!( + fs::metadata("report.md").is_ok(), + "report.md does not exist" + ); + assert!( + fs::metadata("report.md").unwrap().len() > 0, + "report.md is empty" + ); + + // 2. Notebook bundle test + let res_bundle = + agy7rust::commands::notebook_bundle::run("mock_context.json", None, "bundle.ipynb"); + assert!( + res_bundle.is_ok(), + "Notebook bundle failed: {:?}", + res_bundle.err() + ); + assert!( + fs::metadata("bundle.ipynb").is_ok(), + "bundle.ipynb does not exist" + ); + assert!( + fs::metadata("bundle.ipynb").unwrap().len() > 0, + "bundle.ipynb is empty" + ); + + // Restore original current dir and cleanup + env::set_current_dir(&original_dir).unwrap(); + let _ = fs::remove_dir_all(&run_dir); } From ce9297a3cf8771644ce787d774ccfc78721de79e Mon Sep 17 00:00:00 2001 From: ProfRandom92 <159939812+ProfRandom92@users.noreply.github.com> Date: Wed, 10 Jun 2026 16:15:42 +0200 Subject: [PATCH 27/27] fix: address remaining review hardening notes --- agy7rust/src/codec/package.rs | 16 +++++++++++----- agy7rust/src/commands/notebook_bundle.rs | 5 ++++- agy7rust/src/commands/report_export.rs | 12 ++++++++++-- 3 files changed, 25 insertions(+), 8 deletions(-) diff --git a/agy7rust/src/codec/package.rs b/agy7rust/src/codec/package.rs index db98430..4531120 100644 --- a/agy7rust/src/codec/package.rs +++ b/agy7rust/src/codec/package.rs @@ -783,11 +783,17 @@ pub fn verify_package_value(value: &serde_json::Value) -> anyhow::Result<()> { } } - let final_entry = ledger_arr.last().unwrap().as_object().ok_or_else(|| { - anyhow::Error::new(SparkError::EvidenceLoss( - "Final ledger entry is not an object".to_string(), - )) - })?; + let final_entry = ledger_arr + .last() + .ok_or_else(|| { + anyhow::Error::new(SparkError::EvidenceLoss("ledger is empty".to_string())) + })? + .as_object() + .ok_or_else(|| { + anyhow::Error::new(SparkError::EvidenceLoss( + "Final ledger entry is not an object".to_string(), + )) + })?; let final_entry_hash = final_entry .get("entry_hash") .and_then(|v| v.as_str()) diff --git a/agy7rust/src/commands/notebook_bundle.rs b/agy7rust/src/commands/notebook_bundle.rs index c4faf17..461176b 100644 --- a/agy7rust/src/commands/notebook_bundle.rs +++ b/agy7rust/src/commands/notebook_bundle.rs @@ -171,7 +171,10 @@ pub fn run( } } - let parent_dir = output_path_buf.parent().unwrap_or_else(|| Path::new(".")); + let parent_dir = output_path_buf + .parent() + .filter(|p| !p.as_os_str().is_empty()) + .unwrap_or_else(|| Path::new(".")); let file_name = output_path_buf .file_name() .ok_or_else(|| anyhow::anyhow!("Invalid output path filename"))? diff --git a/agy7rust/src/commands/report_export.rs b/agy7rust/src/commands/report_export.rs index 39188cc..aaa18fd 100644 --- a/agy7rust/src/commands/report_export.rs +++ b/agy7rust/src/commands/report_export.rs @@ -67,13 +67,21 @@ pub fn run(input_path: &str, output_path: &str) -> Result<()> { } } - let parent_dir = output_path_buf.parent().unwrap_or_else(|| Path::new(".")); + let parent_dir = output_path_buf + .parent() + .filter(|p| !p.as_os_str().is_empty()) + .unwrap_or_else(|| Path::new(".")); let file_name = output_path_buf .file_name() .ok_or_else(|| anyhow::anyhow!("Invalid output path filename"))? .to_str() .ok_or_else(|| anyhow::anyhow!("Filename contains invalid Unicode"))?; - let temp_file_name = format!(".{}.tmp", file_name); + let pid = std::process::id(); + let time = std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap_or_default() + .as_millis(); + let temp_file_name = format!(".{}_{}_{}.tmp", file_name, pid, time); let temp_path = parent_dir.join(temp_file_name); fs::write(&temp_path, &md)