Skip to main content

Operations

jhf-swatch stays runtime-free. Operational verification in this repository is limited to bounded evidence, seed-validation, and owner-routing for external runtime concerns.

Run This Check​

python scripts/validate_docs_platform_v1_6.py
python scripts/run_local_checks.py
bash scripts/verify_runtime_guardrails_live.sh --host <internal-runtime-redacted>

Scan&Fix Runbook​

Quickstart​

bash scripts/scan_and_fix.sh --dry-run

The default run resolves all matching open non-PR issues in severity/recency order.

Dry-run​

bash scripts/scan_and_fix.sh --issue 19 --dry-run

Dry-run prints the selected issue set and the full assembled prompt header plus the embedded execution standard without dispatching any implementation run.

Live Run​

export SCAN_AND_FIX_EXECUTOR_CMD='cat > /dev/null'
bash scripts/scan_and_fix.sh

Use a real executor command only when the downstream implementation path is ready to create/update issue branches and PRs. The prompt source of truth is prompts/scan_and_fix_execution_standard.md.

Common Failure Modes​

  • repo identity cannot be resolved from origin or explicit overrides
  • GITEA_TOKEN is unavailable for live issue discovery
  • no valid executor command is supplied for non-dry execution
  • label/severity filters produce an empty issue set
  • the embedded execution standard file drifts from the required block
  • minimal host Python lacks PyYAML or jsonschema; scripts/docs/validate_docs_inventory.py now falls back to repo-owned read-only compatibility checks for the docs inventory lane

Runtime Ownership Boundary​

  • repo-owned validation only
  • no repo-owned compose stack
  • host/runtime owner follow-up routes to jhf-openclaw-env

Supporting Docs​

  • Runbook
  • Runtime Guardrails (docs/RUNTIME_GUARDRAILS.md)
  • Test Readiness (docs/TEST_READINESS.md)

AGPLv3. See ../LICENSE (LICENSE). Learn more at helpifyr.com.

Workspace Git/Scan Guardrails (Mandatory)​

  • Gitea is Source of Truth; local Windows workspaces are disposable working copies.
  • Never run Codex sessions on <local-workspace-redacted> root; always use a concrete repo path.
  • Limit active repo sessions to 2-3 in parallel.
  • Before each run in a repo: git fetch --prune, git checkout <branch>, git pull --ff-only.
  • No background git discovery loops (git status, git ls-files, worktree scans) without explicit scoped need.
  • Automation scripts must run repo-scoped only, never global over <local-workspace-redacted>.

scan_and_fix Standard​

  • scripts/scan_and_fix.sh must enforce runner timeout + single-run lock + .env fallback to <local-env-redacted> and <local-env-redacted>.
  • scripts/scan_open_issues_repo_only.sh must exist and query only current repo open issues via Gitea API.

Workspace Hygiene​

  • Daily cleanup: stale _worktrees/*, _tmp/*, test-results/*, large temporary artifacts.
  • Weekly cleanup: stale local branches/worktrees.
  • Never leave valuable artifacts as untracked files in workspace root.

Dirty-State Policy​

  • Dirty state is allowed while actively implementing.
  • Before new scan/automation runs: commit/stash, or use a dedicated worktree.
  • Never propagate dirty_unknown states.

Incident Playbook (git.exe storm)​

  1. Identify parent of git.exe (usually one Codex.exe).
  2. Stop only the offending process tree.
  3. Restart session on concrete repo path.
  4. Reduce parallel sessions.
  5. Verify git.exe count drops within 30-60s.