Imported from ofuhrer/rust_rockfall (AGENTS.md). Install upstream with npx skills add ofuhrer/rust_rockfall. Copyright stays with the author.

AGENTS.md

Compact operating guide for automated agents. Detailed background and broad policy live in docs/agent_reference.md; read that file only for broad model, physics, output, versioning, HPC, or review-policy changes.

Source Of Truth

• Active task queue: docs/task_backlog.md.
• Compact task context: scripts/print_agent_task_context.py.
• AOI front door and QGIS review: docs/aoi_user_manual.md.
• Durable decisions: docs/decision_log.md.
• Completed TB history: docs/agent_work_log.md.
• Current maturity snapshot: docs/current_maturity_snapshot.md.
• Sequential orchestration strategy: docs/orchestration_strategy.md.
• Detailed project background: docs/project_overview.md.
• Worker-facing scale status: scripts/summarize_balfrin_scale_readiness_matrix.py.
• Local scientific audit summary: scripts/summarize_local_scientific_progress.py.
• Local scientific backlog recommendation: scripts/recommend_local_scientific_backlog.py.

When files conflict, preserve hard safety/claim boundaries first, then update docs so the repository tells one consistent story.

TB Worker Fast Path

Start every TB implementation from the repo root:

cd /Users/fuhrer/Desktop/rust_rockfall/main
git pull --ff-only origin main
PYENV_VERSION=system uv run python scripts/print_agent_task_context.py --task TB-xxx --format json
rg -n "^### TB-xxx:" docs/task_backlog.md

If the context helper reports backlog_refill_needed=true, do not invent an implementation task. Run a scoped backlog-refill or gap-analysis task first.

Read only the selected backlog task and its Inspect first files unless the task explicitly asks for broader context. Use --detail full on the context helper only for orchestrator/review work.

For AOI user-facing work, keep docs/aoi_user_manual.md as the compact front door and link out to detailed workflow docs only when needed.

For local scientific work that does not require Balfrin, start with:

PYENV_VERSION=system uv run python scripts/summarize_local_scientific_progress.py --format text
PYENV_VERSION=system uv run python scripts/recommend_local_scientific_backlog.py --format text

Use the focused local audit commands before broad manual interpretation: audit_conditional_denominator_provenance.py, audit_trajectory_deposition_traceability.py, rank_local_hazard_layer_fragility.py, summarize_extreme_layer_sensitivity_smoke.py, inventory_second_site_local_blockers.py, audit_chant_sura_holdout_split.py, and check_calibration_separation_preflight.py.

Use PYENV_VERSION=system uv run python ...; avoid plain python or python3 because local pyenv shims can point at unavailable interpreters.

Sequential Orchestration

When looping over backlog tasks, treat each task as one transaction:

1. Pull origin/main and require a clean worktree.
2. Select only the lowest-numbered active TB-xxx task.
3. Launch exactly one worker for that task; do not pre-generate later prompts.
4. After the worker exits, verify that main fast-forwards, the worktree is clean, and the completed task was removed from docs/task_backlog.md.
5. Stop on any worker failure, dirty worktree, failed pull, or stale completed task.

Run workers directly on main; do not create branches or worktrees for normal TB execution. Keep worker output visible enough to diagnose failures, but route large JSON, diffs, and logs to /tmp and summarize the result. Preserve the final relevant error block on failure. Use docs/orchestration_strategy.md for the full file-backed monitoring pattern.

For live Balfrin work, the user has granted standing clearance for GPT-5.5 workers to submit jobs to the postproc partition and actively monitor them. Multiple concurrent postproc jobs are allowed, even if they fill the partition. If the work would keep the postproc partition fully busy for more than 6 hours, stop and rediscuss. This clearance does not relax access, readiness, output-budget, preservation, or evidence gates, and it does not authorize non-postproc partitions, distributed execution, scale-up claims, or scientific/operational claim upgrades.

Work Rules

• Prefer executable progress over process artifacts: implemented behavior, measured analysis, reproducibility improvements, focused bug fixes, or tests.
• Do not add a new gate, report, wrapper, validator, YAML record, or synthesis package unless it removes a concrete execution/reproducibility blocker, produces a new measurement, or consolidates duplicated workflow logic.
• Prefer extending an existing helper or deleting a stale cue over creating a parallel status vocabulary. New status labels need a clear downstream command or decision that existing labels cannot express.
• Distinguish measured completion from fixture-backed proofs and blocked-state reports. A blocked report is useful evidence, but it is not the same as achieving the task's measured capability. Do not chain blocked reports; the next task should either unblock the input, run/recover/measure something, or explicitly defer the path.
• For scale and Balfrin planning, use the scale readiness matrix and preserve its evidence labels: measured_on_balfrin, fixture_backed, measured_on_balfrin_postproc_microbenchmark, scratch_local, projection_only, blocked_pre_submit, and failed_closed. Do not treat local ladders, fixtures, synthetic postproc probes, projections, or pre-submit/failed-closed branches as measured Balfrin hazard scale capability.
• Treat management-facing summaries and closure packages as secondary outputs. They are justified only after executable evidence changes or when they replace multiple stale summaries with one canonical surface.
• Keep edits scoped to the task and existing module boundaries.
• Add or update focused tests for behavior, parser, CLI, output, and bug-fix changes.
• Keep seeded/stochastic runs deterministic.
• Keep scratch outputs in /tmp; do not commit generated trajectory or hazard outputs unless they are intentional tiny fixtures.
• Keep visible worker progress compact: use 1-2 sentence updates, redirect large JSON/logs/diffs to /tmp, never paste full diffs, and preserve the final relevant error block when a command fails.
• Finish with the compact structured report schema: TASK, STATUS, SUMMARY, FILES_CHANGED, CHECKS_RUN, COMMIT, PUSH_STATUS, REMAINING_NEXT_TASK, BOUNDARY_NOTE. Use statuses such as implemented_measured, implemented_fixture_backed, implemented_blocked_report, blocked_unresolved, or partial_needs_followup when that distinction matters.
• For dataset or validation-case changes, keep calibration, validation, and operational input data separate.
• Treat local scientific audit helpers as diagnostic/routing surfaces only: they do not create physical-probability, annual-frequency, operational, risk/exposure/vulnerability, scale-up, distributed-execution, or Balfrin authorization claims.
• For Swiss geodata changes, preserve CRS, vertical datum, resolution, extent, source-tile ids, and provenance; never commit large swisstopo raw products.
• Append completed TB entries to the bottom of docs/agent_work_log.md using its template; do not insert entries near older related work.
• Remove the completed task from docs/task_backlog.md; never leave stale active tasks for the next worker.

Required Checks

Run the focused checks named by the task. Before commit also run:

git diff --check
PYENV_VERSION=system uv run --with PyYAML python scripts/check_repo_consistency.py
scripts/git-hooks/pre-commit
find data/processed/swisstopo validation/private hazard/results validation/policies \
  \( -path '*placeholder_second_site_v1*' -o -name '*placeholder*' \) -print

The default consistency check is the fast local safety gate. Use PYENV_VERSION=system uv run --with PyYAML python scripts/check_repo_consistency.py --full when changing generated command-plan helpers or their script references.

There is no repository pre-push hook. Before pushing, confirm task-specific checks passed and inspect git status --short --branch plus the committed diff.

Hard Boundaries

• Do not introduce hidden physics, tuning, or undocumented parameter choices.
• Do not claim equivalence with proprietary or operational hazard tools.
• Do not present current products as operational hazard assessment.
• Do not describe hazard-map layers as risk maps unless exposure and vulnerability are explicitly in scope.
• Do not introduce annual-frequency, physical-probability, risk, exposure, vulnerability, scale-up, or distributed-execution claims unless a task explicitly authorizes that phase change.