[docs] - Rebuild the CyClaw-Sandbox skill around a local audit that runs code and lint, leaving the suites to CI

[cgfixit]

Proposed changes

The CyClaw-Sandbox skill told an operator to clone fresh and run the full pytest suite locally. CLAUDE.md §5 has since moved that suite to GitHub Actions. This PR rebuilds the skill around what you can actually verify on your own machine: run the code, run the linters and checkers, and read CI for the rest.

• New local_audit.py (Ladder L). One stdlib command, run with the 3.12 venv. It runs:

  • Static: the stdlib checkers (invariant/dotenv/doc-sync/config/dep/env-drift/otel --strict) and ruff (the F,B,S gate plus the advisory pass).
  • Run the code: each subsystem's cli test, the memory selftest, gate_runtime_check.py, every CLI's --help and the shipped-off status reports.
  • Swarm: the in-process swarm.
  • Live gate: a live gate.py probed against the CLAUDE.md §2 route contract. That covers 401/403/404/413/422/429/503, the security headers, cross-site rejection, /index/build refusals, the console tests and the terminal emulation.

  The swarm and the gate run in scratch copies of the working tree, uncommitted edits included, so soul.md, logs/ and index/ are never written. sync.cli test writes its rclone filter file into a scratch XDG_CONFIG_HOME, so ~/.config is never touched either. It never runs pytest.

• SKILL.md rewritten. It leads with Ladder L and states which ladders GitHub Actions owns (C verify.sh, E platform smokes, the full suite and coverage). The opt-in steps (auth, memory, pre-action hook, Tier 2 Ollama, MCP, agentic sandbox) are listed as SKIP until done. Surfaces and numbers were re-derived by running every command against main @ 29f639a.

• New gotchas, found by running things here:

  • The proxy denies Hugging Face Xet CAS, so model downloads hang at model.safetensors (HF_HUB_DISABLE_XET=1 fixes it).
  • A missing index makes /query answer 503 before the injection filter runs.
  • The shared 60/min rate limit trips partway through long probe batches.

• smoke.sh gains SMOKE_SKIP_PYTEST=1. It skips section F locally. CI leaves the variable unset, so behaviour there is byte-for-byte the same path.

• Commands updated: /CyClaw-Sandbox and /run. /run claimed a "draft PR"; this skill opens none.

Invariant / Governance Impact: none of the six. No core file is touched. check_invariants.py passes 46/46.

Agent instruction surface: .claude/commands/*.md, SKILL.md, smoke.sh and local_audit.py steer later agent sessions. Everything in them was written from this repo's code and from runs in this session, with nothing copied from external content.

Security-gate answers (local_audit.py):

• Egress: loopback only (127.0.0.1 gate and mock), stdlib urllib, with a timeout on every request.
• Exec: fixed list-form argv only, no shell, and every command is bounded by a timeout. No model or request text reaches argv.
• File writes: only under tempfile dirs it creates, plus --out if you pass one. Its only config edit raises api.rate_limit.max_requests in the scratch copy for the functional launch, then restores the shipped value for the 429 launch.
• Keys: the API key is a fresh secrets.token_urlsafe per run and is never printed or logged.

Types of changes

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Security (auth, privacy, injection, egress, redaction, or secrets)
• Invariant / Governance refinement (use this for changes that strengthen or evolve the 6 invariants, I6 isolation, or harness phases)
• Dependencies (added, removed, or bumped)
• CI / infrastructure (workflows, hooks, templates, or checkers)
• Refactor or tests (behavior-preserving, no new capability)
• Documentation update
• Other (none of the boxes above fit)

Scope: .claude/ agent tooling only (skill, its scripts, two slash commands).

Benefits / why

• One command gives a truthful local verdict in about a minute: 74 PASS, 0 FAIL, 1 SKIP on this run, with zero writes to the checkout. It follows the owner's run-code-then-lint policy instead of a 20-minute local suite.
• It exercises things no unit test does end to end: the live route contract against the real config.yaml, the shipped rate limit, every subsystem pre-flight.
• The doc stops presenting CI-owned ladders as local chores, and it tells you how to read a SKIP.

Risks to monitor

• smoke.sh is CI-wired (verify-skills). The only change is a new if arm gated on an unset-by-default variable plus one moved echo. bash -n is clean, and I ran it with the variable set. CI runs it without the variable.
• Probe drift. When a route's contract changes, Ladder L's probe will FAIL. That is the intended signal; update the probe and CLAUDE.md §2 together.
• Untested platforms. Not run on macOS or Windows here. The script avoids POSIX-only calls (paths via pathlib/tempfile, terminate()/kill() for processes). XDG_CONFIG_HOME is honoured by sync/config.py on every OS.

Checklist

• I have read docs/THREAT_MODEL.md, INVARIANTS.md and SECURITY.md (and any relevant Phase docs)
• This change preserves all 6 security invariants and I6 module isolation (explicit evidence or invariant matrix included for core changes)
• Full sandbox validation has been run (GROK_API_KEY=dummy pytest tests/ -q --tb=short, and bash .claude/skills/CyClaw-Sandbox/verify.sh for core RAG/agentic paths) and passes with no regressions
• No new external network dependencies or mandatory online LLM assumptions were introduced without explicit justification + offline fallback path
• For any agentic/fsconnect change: two-phase audit, quota enforcement, governed delete/trash, and write guards have been verified
• Relevant architecture docs or threat model notes have been updated if core behavior or topology changed
• Commit messages follow the title prefix convention above
• For large or complex changes: before/after invariant matrix + sandbox evidence is included in "Further comments" or linked

Further comments

Checks run directly:

• Full Ladder L (--mock-ollama, real index, HF_HUB_DISABLE_XET=1): 74 PASS, 0 FAIL, 1 SKIP in 70 s.
  • The SKIP is sync.cli test, because rclone is not installed here.
  • Swarm 149/149 at Tier 1.
  • Console tests 41/41, and terminal emulation PASS.
  • The 429 arrived at request 61.
  • Afterwards: no orphan processes, no scratch left behind, clean git status.
• Ladder L with no index: 63 PASS, 0 FAIL, 4 SKIP. The query-path probes SKIP rather than FAIL.
• Quick Mode with SMOKE_SKIP_PYTEST=1: 10 passed, 4 skipped, 33 s.
• Lint and checks:
  • ruff (E,F,I,B,C4,UP,S) and mypy --strict are clean on local_audit.py.
  • bash -n smoke.sh, doc_sync.py (0 drift) and check_invariants.py (46/46) all pass.
• Not run locally:
  • pytest: CI runs the suite and the pins on verify.sh/smoke.sh/SKILL.md, such as the --no-proxy-headers recipe test. SKILL.md keeps a compliant uvicorn gate:app --host … --no-proxy-headers recipe.
  • macOS and Windows.

Not changed: verify.sh, macos-smoke.sh, windows-smoke.ps1, run_full_verification.py, and the .codex/skills/Cyclaw-Sandbox/ port.

Rollback: revert this one commit.

Suggested merge order of open PRs

Trial merge verified (git merge --no-commit --no-ff + abort) against main @ 29f639a on 2026-10-13.

#1650 · Safe ✅
Impact: .claude/ sandbox skill + two commands; independent, only open PR.
Action: Merge anytime once CI is green.

ELI5

The CyClaw-Sandbox skill was a checklist written for a time when you ran every test on your own laptop. Now GitHub runs those tests for you on every PR, so the checklist was asking for 20 minutes of busywork, and it also wasn't clear which steps were yours.

This PR replaces the checklist with one script, local_audit.py. It works on a photocopy of your project, never the original, and in about a minute it:

• runs the linters and the safety checkers;
• starts every command-line tool once;
• runs each add-on's own self-check;
• runs the fake end-to-end question test;
• boots the real server, knocks on every door, and makes sure each one answers exactly as the rulebook says.

It does not run the big test suite; GitHub does that. The guide now says which checks are yours to run and which belong to GitHub. It also lists the traps I hit while running everything here, like model downloads that hang forever in this cloud box unless you set HF_HUB_DISABLE_XET=1. smoke.sh gets a switch to skip its test-suite section when you run it by hand.

What could still go wrong:

• I didn't run it on a Mac or Windows. If something breaks there, the script prints a FAIL line naming the check.
• If someone changes what a route returns, this script will flag it. That's on purpose.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BJXTdWRbDpkynPYbpL2pxd

Last updated: 2026-10-13 11:31 ET

[github-actions]

PR is a complete fill of .github/PULL_REQUEST_TEMPLATE.md (every section, ticked boxes, merge order, ELI5 last, last-updated stamp, title, branch).

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-13T15:57:11.058400Z	835eae8	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.