Skip to main content

Operations

Tool / Contract Summary​

This page documents operational behavior for jhf-lantern, with emphasis on repo-owned verification and the Scan&Fix automation flow.

Current Verified State​

Available now:

  • repo-owned verification for the route-aware mixed shell, feature truth, and reference inventory
  • read-only Lantern runtime verification over the current route posture model
  • Scan&Fix prompt generation, standalone-issue ranking, batch execution, and runner handoff

Planned / not in current scope:

  • direct mutation flows from Scan&Fix
  • repo-owned runner provisioning
  • self-merge automation

Scan&Fix Runbook​

Quick start​

bash scripts/scan_and_fix.sh --dry-run
bash scripts/scan_and_fix.sh --dry-run --all-open

This performs a ranked sweep over all open standalone issues for jhf-lantern by default and prints the generated execution prompt set with issue and worktree context. Use --issue <id> to narrow execution to one standalone issue. When GITEA_TOKEN is not already exported, the script auto-loads it from a repo-parent .env or an operator-managed workspace .env.

If no standalone issues are open in Gitea, the script now exits cleanly with an empty-queue message instead of failing.

Dry-run examples​

bash scripts/scan_and_fix.sh --dry-run --issue 4
bash scripts/scan_and_fix.sh --dry-run --all-open
bash scripts/scan_and_fix.sh --dry-run --labels runtime,contract --max-issues 3
bash scripts/scan_and_fix.sh --dry-run --since 7d --severity-order "critical,high,medium,low"

Live run​

export SCAN_FIX_RUNNER='codex exec --input-file'
bash scripts/scan_and_fix.sh --all-open --host <live-host> --user <ssh-user>
bash scripts/scan_and_fix.sh --issue 4 --host <live-host> --user <ssh-user>
bash scripts/scan_and_fix.sh --all-open --executor-cmd 'codex exec --input-file'

The script writes the final prompt to test-results/scan-and-fix/generated_prompt.md for the first selected issue and, for batch runs, one prompt per issue under test-results/scan-and-fix/generated_prompt.issue-<id>.md. It then executes each selected standalone issue sequentially through --executor-cmd or SCAN_FIX_RUNNER. If neither is set, the script falls back to codex exec --input-file when the CLI is available.

Each live run uses a single-run lock under test-results/scan-and-fix/.scan_and_fix.lock and applies a per-issue runner timeout via SCAN_FIX_RUNNER_TIMEOUT_SECONDS (default 1800).

Failure modes​

  • GITEA_TOKEN is required:
    • verify the repo-parent .env or operator-managed workspace .env contains the token, or export it explicitly before running.
  • No open issues matched the filters:
    • if you expected work, relax --labels / --since or target an issue explicitly with --issue.
    • for the default repo sweep with no open standalone issues, the script exits successfully and reports an empty queue.
  • Issue #<id> is a pull request, not a standalone issue:
    • choose a real issue id or let automatic selection ignore PRs.
  • No runner found:
    • set --executor-cmd or SCAN_FIX_RUNNER explicitly, or install a supported Codex CLI path.
  • Another Scan&Fix run is already active:
    • wait for the active run to finish or remove the stale lock only after verifying the previous run is gone.
  • runner exits with timeout 124:
    • increase SCAN_FIX_RUNNER_TIMEOUT_SECONDS for genuinely long runs or debug the stuck executor command.
  • API auth/connectivity failures:
    • verify GITEA_BASE_URL, token scope, and repository visibility.
  • dirty worktree before implementation:
    • stop and reconcile foreign changes before live execution to avoid mixed commits.

Verification Paths​

  • python scripts/verify_fabric_oss_upgrade_consumer.py
  • python scripts/verify_module_features.py
  • python scripts/verify_scan_and_fix_automation.py
  • python -m pytest -q

Node Install Guardrails​

  • pnpm is the canonical package manager path for this repo (packageManager: pnpm@11.1.1).
  • CI must use pnpm install --frozen-lockfile and not npm ci.
  • Use bounded commands for install/build/test (for example timeout 300s ...) to avoid hanging lanes.
  • On Host172-like environments with unstable IPv6 npm routes, prefer NODE_OPTIONS=--dns-result-order=ipv4first.

License: AGPLv3 Project: https://helpifyr.com

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 + .env fallback to the operator-managed workspace .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.