spark-cli AGENTS.md

Spark CLI Agent Ruleset

Repo Role

spark-cli owns Spark's local installer, registry, provenance, secrets, health checks, module lifecycle, sandbox/operator commands, and Spark OS read-model compilation.

Canonical truth owned here:

• starter-module registry, bundle membership, pins, and attestation metadata
• installer scripts, installer manifest, hosted-installer verification contracts, and onboarding checks
• local module lifecycle commands: setup, update, status, start/stop, fix, verify, doctor
• safe secret storage and generated module environment wiring
• Spark OS compiled read models: system map, repo board, authority view, trace index, memory projections, capability catalog, voice surface view, and operating cockpit inputs

This repo does not own:

• Telegram conversation behavior, composition, or channel tokens
• Builder AOC, route confidence, identity, or memory orchestration
• Spawner mission execution and provider result bodies
• domain-chip memory algorithms or durable memory doctrine
• Cockpit UI layout or user-facing dashboards

Start-of-Work Protocol

1. Run git status --short --branch.
2. Read this file plus README.md and the relevant command/installer docs.
3. Identify whether the change is CLI-owned or belongs in Builder, Telegram, Spawner, memory, Cockpit, Labs, Swarm, voice, or Skill Graphs.
4. Define the smallest verifiable behavior and the stop-ship gate.
5. Prefer focused tests for the changed command or compiler slice before broader suites.
6. Update docs when commands, installer behavior, registry metadata, or compiled artifact shapes change.
7. Commit one logical checkpoint with verification notes.

One Truth Rules

• Registry pins and installer manifests must describe owner repo truth; do not paper over dirty runtime state with local-only assumptions.
• Compiled Spark OS artifacts are projections. They must not become runtime authority, durable memory authority, or source state.
• If an artifact joins evidence from multiple repos, preserve source owner, freshness, blocker, and redacted reference fields.
• Do not create a new state root when an owner repo can expose metadata safely.
• Do not treat generated JSON, logs, proof folders, or local workspaces as source truth unless explicitly promoted and documented.
• If spark os compile reports canonical_runtime_dirty, stop installer work and clean or quarantine the residue without reading private payloads. Then rerun spark os compile --json and require critical_duplicate_truth_count=0 before any hosted publication claim.
• Runtime residue belongs under <spark-home>/state, not inside module source roots. If residue must be preserved, move it to a dated quarantine path and document the verification command.