Skip to main content

Operations

jhf-deployment keeps its deep operational truth in RUNBOOK.md. This page is the stable docs-platform v1.6 entrypoint that points operators to the canonical deploy/verify lanes without duplicating the full runbook.

Run This Check​

python scripts/validate_docs_platform_v1_6.py
bash scripts/fabric-selfcheck.sh
bash scripts/release-readiness-check.sh

Canonical Operational Surface​

Scan&Fix​

Schnellstart​

bash scripts/scan_and_fix.sh --dry-run

Without --issue, Scan&Fix processes all matching open Issues in priority order by default. Use --max-issues <n> when only a bounded portion of the queue should be prepared or executed. If the live executor must be pinned explicitly, use --executor-cmd "<trusted command>". Workspace credentials are loaded from <local-env-redacted> (../.env from the repository perspective); values must not appear in logs, prompts, or evidence.

Dry-run​

bash scripts/scan_and_fix.sh --issue 310 --dry-run
bash scripts/scan_and_fix.sh --labels severity:critical --max-issues 3 --dry-run
bash scripts/scan_and_fix.sh --dry-run --issues-json tests/fixtures/scan_and_fix_issues.json
bash scripts/scan_and_fix.sh --dry-run --executor-cmd "cat"

Live-Run​

bash scripts/scan_and_fix.sh
bash scripts/scan_and_fix.sh --since 24h --severity-order "critical,high,medium,low"
bash scripts/scan_and_fix.sh --max-issues 2
bash scripts/scan_and_fix.sh --executor-cmd "codex exec --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox --ephemeral -"

Fehlerbilder​

  • missing GITEA_TOKEN for Gitea API access: export the repo-local token from <local-env-redacted> (../.env) into the process environment or use the default workspace layout.
  • refusing live Scan&Fix run on dirty checkout: reconcile local changes first or use --dry-run to inspect prompt composition.
  • unable to resolve codex executable for Scan&Fix run: ensure Codex CLI is installed, pass --executor-cmd "<trusted command>", or set SCAN_AND_FIX_CODEX_BIN.
  • live host / CI blockers remain issue-owned outcomes of the dispatched run; no local workaround should be hidden in this wrapper.

Ownership Boundary​

  • deployment-owned: rollout automation, verification, evidence contracts
  • external-owner runtime truth: consumed read-only from owner repos

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 the current repo via the Gitea API.
  • future-program issues remain visible in reconciliation output, but scan_and_fix must not dispatch them as the current actionable queue unless a caller explicitly targets one with --issue.

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.