Skip to main content

Operations

Purpose​

This page is the canonical v1.6 operations surface for jhf-reed. It keeps the stable docs-platform entrypoint small while the deeper operator runbook remains the authoritative supporting runbook.

Run This Check​

python scripts/validate_docs_platform_v1_6.py

Scan&Fix Quickstart​

Dry-Run​

bash scripts/scan_and_fix.sh --dry-run

Live-Run​

export SCAN_AND_FIX_EXECUTOR='your-agent-cli --prompt-file "{prompt_file}"'
bash scripts/scan_and_fix.sh

Target One Issue​

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

Useful Filters​

bash scripts/scan_and_fix.sh --labels bug,security --since 7d --max-issues 3 --dry-run

Scan&Fix Failure Modes​

  • missing executor:
    • live-run exits non-zero and prints the generated prompt path
  • dirty worktree:
    • live-run stops before execution to avoid mixed issue branches
  • no matching issues:
    • script exits with no selection and does not create a branch
  • Gitea API/network failure:
    • issue scan fails closed; rerun with bounded filters or restore API reachability
  • credentialed or SSH origin remote:
    • set SCAN_AND_FIX_GITEA_BASE_URL=http://host:3000 so the script can resolve the API base deterministically
  • missing shell env setup:
    • the script auto-loads .env from the repo root plus <local-env-redacted> and <local-env-redacted> before it talks to Gitea or creates PRs
  • prompt artifact location:
    • by default the script writes generated prompt/queue files below TMPDIR or /tmp; override with SCAN_AND_FIX_OUTPUT_DIR only if you intentionally want a custom artifact location
  • executor returns success without commits:
    • prompt dispatch is recorded, but no PR is created because there is no branch delta

Scan&Fix Runtime Notes​

  • Default live host context is <internal-runtime-redacted> / administrator
  • Override with --host and --user only when the issue requires a different runtime target
  • Default queue behavior processes all matching open issues in severity/updated order; use --max-issues <n> to bound
  • The embedded execution standard is loaded from prompts/scan_and_fix_execution_standard.md and appended unchanged to each issue header

Supporting Docs​

  • Operator Runbook (docs/OPERATOR_RUNBOOK.md)
  • Stack Container Contract (docs/STACK_CONTAINER_CONTRACT.md)
  • Troubleshooting

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>.
  • repo-scoped open-issue discovery must stay inside scripts/scan_and_fix.sh and query only current repo open issues via the 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.