Operations

Purpose

This repository is in admission-preparation mode for future fabric-all inclusion. The current operator path validates repo-side readiness only.

Targeted Checks

• python scripts/check_fabric_contracts.py
• python scripts/export-fabric-metadata.py --pretty
• python scripts/export-fabric-metadata.py --pretty --output runtime/fabric-metadata/status.pretty.json
• optional override for non-default environments: set HELPIFYR_FABRIC_COMBINATION_URL before running the export script
• python scripts/check_runtime_materialization.py
• python scripts/verify_oci_runtime_candidate.py --check
• python scripts/verify_docs_inventory.py
• python scripts/verify_ci_runner_label.py
• python scripts/verify_oss_version_truth.py
• python scripts/verify_event_modeling_wave5_safety_gate.py
• python scripts/verify_universal_work_legal_tax_review_contract.py
• python -m pytest -q

CI Runner Label Compatibility

Repo CI must request only labels that are actually registered and online in the shared Gitea runner fleet.

• current repo baseline: .gitea/workflows/ci.yml uses runs-on: ubuntu-22.04
• fail closed if the workflow drifts to an unregistered label such as ubuntu-24.04
• verify live runner labels before assuming generic CI queue latency

Verify path:

• repo truth: inspect .gitea/workflows/ci.yml
• live truth: GET /api/v1/admin/actions/runners
• PR/job evidence: GET /api/v1/repos/{owner}/{repo}/commits/{sha}/statuses

Readiness Rules

• primary capability class must remain compliance-governance
• local bundle truth must not exist
• local detection truth must not exist
• no second truth family may be introduced
• runtime admission must remain disabled until a later explicit slice
• active admission blockers must stay explicit in Admission Blockers (docs/ADMISSION_BLOCKERS.md); no repo surface may treat planning truth as admission completion
• legal and tax intents remain review-only: Fabric derives gates, Heddle/owners bind human decisions, and this repository never executes external submissions

Monitoring Rules

• consume Fabric-authored combination truth read-only
• if the canonical Fabric surface is unavailable, expose only:
  • unknown
  • degraded
  • optional last_known_truth
• never infer active fabric-all membership locally

Non-HTTP Status Contract

• python scripts/export-fabric-metadata.py --pretty
• python scripts/export-fabric-metadata.py --pretty --output runtime/fabric-metadata/status.pretty.json

This export is the repo-side machine-readable status contract for issue #1. It is not a runtime admission signal. The export payload has focused repo-local regression coverage; host-bound wrapper scripts still rely on bounded manual/live verification instead of full local simulation. When an operator or downstream consumer needs a materialized artifact, use --output <path> instead of assuming one fixed workspace location.

Runtime Materialization Drift

jhf-selvage currently declares deployment.kind = admission-preparation-only.

That means live runtime materialization on the configured OpenClaw host must stay absent until a later explicit admission slice changes the contract.

Runtime drift rules:

• no host runtime overrides are supported under ~/.config/helpifyr/runtime/jhf-selvage/
• no active jhf-selvage compose materialization may appear on the host
• no jhf-selvage containers or runtime networks may exist before explicit admission
• no app readback surface may claim a live admitted runtime before explicit admission

If a host uses a different override base path, point the verifier at it with --runtime-override-base <path> or JHF_SELVAGE_RUNTIME_OVERRIDE_BASE=<path>.

Verify path:

• repo-only: python scripts/check_runtime_materialization.py
• live: python scripts/check_runtime_materialization.py --live-host <openclaw-host> --ssh-user <openclaw-user> --pretty
• live with non-default override base: python scripts/check_runtime_materialization.py --live-host <openclaw-host> --ssh-user <openclaw-user> --runtime-override-base /srv/helpifyr/runtime --pretty

OCI Runtime Candidate

runtime/oci-candidate/ carries a source-only shadow OCI runtime candidate for plan v4.3.1 section 25 (Python 3.12, FastAPI/Pydantic, PostgreSQL/NATS readiness probes). The candidate is packaging evidence only:

• the candidate is not admitted, not materialized, and not live
• it is not activated, not deployed, and not built by CI
• it declares no public ingress and defaults to loopback binding
• secrets are file (*_FILE) or keystore references only; no credential values exist in this repo slice
• fabric-manifest.json stays runtime_kind=no-runtime-stack / deployment.kind=admission-preparation-only; no docker-compose is added

See OCI Runtime Candidate (docs/OCI_RUNTIME_CANDIDATE.md) for the closed response models, the documented environment key set, and the container posture.

Verify path:

• python scripts/verify_oci_runtime_candidate.py --check
• python -m pytest -q tests/test_oci_runtime_candidate.py

Scan&Fix Runbook

Schnellstart:

• bash scripts/scan_and_fix.sh --dry-run
• bash scripts/scan_and_fix.sh --runner-cmd "<agent-cli-cmd>"

Default behavior: without --issue and without a positive --max-issues, the script processes all open issues (--max-issues 0).

Dry-run:

• shows only prioritized open issues and the generated execution prompt
• does not execute the work
• Beispiel:
  • bash scripts/scan_and_fix.sh --dry-run --max-issues 1 --severity-order "critical,high,medium,low"

Live-Run:

• nutzt den konfigurierten Runner (--runner-cmd oder SCAN_FIX_RUNNER_CMD)
• processes all open issues by default (--max-issues 0)
• Beispiel:
  • bash scripts/scan_and_fix.sh --issue 9 --runner-cmd "codex exec -"

Fehlerbilder:

• runner command missing: no runner configured; set --runner-cmd or SCAN_FIX_RUNNER_CMD
• no matching open issues found: filters (--labels, --since) are too restrictive or there are no open issues
• Gitea API cannot be read: check the base URL, token, and repository context
• runner exit code is non-zero: execution failed; inspect the runner logs

CPU-Safe Runtime Guardrails

Shared-host runs on the configured OpenClaw host must stay low-pressure and bounded.

• bounded diagnostics only (--since, --tail, timeout-bound reads)
• no unbounded log streams or endless polling loops in standard verify flows
• idempotent rerun must not increase idle pressure or leave hanging helper processes
• prefer repo-scoped checks and short evidence samples over long-running monitoring
• if a runtime check needs stronger pressure, it must be called out explicitly as an exception

AGPLv3 applies to this repository; see LICENSE and https://helpifyr.com for project context.

Workspace Git/Scan Guardrails (Mandatory)

• Gitea is Source of Truth; local Windows workspaces are disposable working copies.
• Never run Codex sessions on the workspace 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 the workspace root.

scan_and_fix Standard

• scripts/scan_and_fix.sh must enforce runner timeout + single-run lock + shared-env fallback via repo-local or workspace-parent .env.
• 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.