refactor(scripts): move ops and docs scripts by audience, gate terramate script paths

[Smana]

PR 2 of 3 in the scripts/ restructure. It moves the day-2 operations scripts into scripts/ops/<area>/ and the docs generators into scripts/docs/. A new gate goes in first: it fails CI when any script path that opentofu or terramate executes doesn't exist. PR 1 (#2061) is merged; PR 3 (provision/) is still to come.

flowchart LR
  subgraph before["after PR 1"]
    R["scripts/ root<br/>32 files"]
  end
  subgraph after["after PR 2"]
    O["ops/aws · gcp · k8s · demo · teardown<br/>17 scripts"]
    D["docs/<br/>3 generators"]
    C["ci/check-rebased.sh"]
    P["root: 8 files<br/>provision-bound (PR 3)"]
  end
  R ==> O & D & C & P
  G["test-terramate-script-refs.sh<br/>88 executed refs, 0 unresolved"] -.->|gates| O
  classDef new fill:#d4edda,stroke:#28a745
  classDef pending fill:#f8f9fa,stroke:#adb5bd,stroke-dasharray:4
  class O,D,C,G new
  class P pending

Loading

📋 Design

• Design: 2026-09-17-scripts-restructure-design.md
• Plan: 2026-09-21-scripts-restructure-pr2-plan.md. PR 1's plan is 2026-09-17-scripts-restructure-pr1-plan.md.

What changed

scripts/ci/tests/test-terramate-script-refs.sh	New gate. It resolves every script mention on an executed line in opentofu/**/*.{tf,tm.hcl,tfvars}: 88 refs, floor 80, .yaml included, .terraform/ excluded. A shape it can't resolve, or a ${…} prefix outside its allowlist, fails loudly instead of being skipped. These paths run at apply and destroy time, and no CI job executes them.
scripts/ops/{aws,gcp,k8s,demo}/	13 scripts. The prefix drops where it repeats the directory: aws-sweep-orphaned-volumes.sh becomes ops/aws/sweep-orphaned-volumes.sh.
scripts/ops/teardown/	teardown.sh, the supported teardown, plus the 3 helpers terramate destroy calls
scripts/docs/	export-diagrams.sh, diagram-icons.py, build-og-card.html
scripts/ci/check-rebased.sh	the pre-push hook, with .pre-commit-config.yaml updated
task --list	15 ops:*/docs:* entries that work from any directory. Destroy-time helpers are deliberately not indexed.
scripts/ci/tests/test-script-paths.sh	It now tells a sibling path (../../lib/…) from a root climb, and fails an under-climb that lands on a name the repo root also has (nested AGENTS.md, scripts/README.md).

The design's Deletions table was overruled for teardown.sh and aws-sweep-controller-orphans.sh. Both have "no caller" only because a human is the caller: teardown.sh is the supported teardown (#1970, #1976), and the sweep is its recovery step. Owner decision, 2026-09-21. Nothing is deleted in this PR.

⚠️ Merge gate: read before merging

The plan makes terramate script run preview on both clouds a merge gate (owner decision, 2026-09-21). The whole-branch review then found that preview runs none of the moved scripts. Counting terramate script info lines that name a moved script:

Script	Lines
preview	0
drift detect	0
deploy	3
destroy	28

The design's preview evidence fits PR 3, where helm-release-present.sh runs at plan time. For this PR, the reviewer recommends different evidence:

• the two static gates, which cover every executed path;
• the first real deploy and task ops:teardown after merge, whose logs should be watched for No such file.

I left the gate as you set it. Please choose:

• Run the preview on both clouds, or accept the static gates plus a watched first deploy and teardown in its place

Evidence

Run on this branch, rebased on main @ 1c987b17. CI runs the render.

$ bash scripts/ci/tests/test-terramate-script-refs.sh
88 script reference(s) on executed opentofu/terramate lines checked; 0 failed
$ bash scripts/ci/tests/test-script-paths.sh
11 roots, 4 relative paths, 21 sources, 16 subjects checked; 0 failed
$ task ci:test
23 passed, 1 skipped, 0 failed        # SKIP test-vector-vrl  missing: vector
$ task ci:links / ci:doc-paths / ci:doc-claims / ci:idp-topology   # all exit 0
$ task --list | grep -cE '^\* (ops|docs):'
15

The refs gate was proved against fixtures:

• moving terramate-destroy-confirm.sh without rewriting gives 15 failed;
• breaking helm-release-present.sh gives 2 failed;
• an empty tree trips the floor;
• all 5 previously silent shapes fail;
• ${path.root}/… fails as an unrecognised prefix.

All 13 symlinks are intact, no workflow changed, and job names are unchanged.

Rulings made during implementation

All are recorded in the SDD ledger.

• P3: pacing. The gate got the full protocol; the moves went as one batch with one review.
• R1: keep and move the two tools the design listed for deletion (owner).
• R2: the gate reads .yaml too (88, not 87).
• R3 and R5: the paths gate classifies sibling, root and ambiguous paths instead of treating every /.. as a root climb.
• R4: the # shellcheck source= lines stay root-relative, because CI runs shellcheck from the root.
• R6: this merge-gate note.
• R7: don't index ops:k8s:reclaim-csi-volumes. It deletes every PVC on the current context without a prompt.

Follow-ups (not in this PR)

• teardown.sh's ${ROOT}/scripts/ops/aws/… sweep calls are not gated. The paths gate's check 3 covers only HERE/SCRIPT_DIR.
• The paths gate classifies only the first /.. climb on a line.
• Neither gate has a committed negative-fixture suite. The fixtures live in the plan and the reviews.
• scripts/ci/validate-manifests.sh:20 and flux-schema/gen-catalog.sh:37 have # shellcheck source= paths that don't resolve from the root (SC1091, hidden at -S warning).
• Known limits of the refs gate:
  • a multi-line /* */ block would be read as code, which fails loud, and there are 0 today;
  • a script path inside a Terramate bundle.tm.yml is not scanned, and there are no bundles today.

[github-actions]

🔍 Rendered manifest diff — this PR vs main (desired state)

No changes to the rendered desired state. ✅