chore(repo): classify scripts by lifecycle and retire stale one-offs

[kevkantes]

Summary

Give repository scripts explicit ownership and lifecycle boundaries, remove stale one-off generators, and keep supported upgrade tooling out of the flat scripts/ root.

Problem

scripts/ currently contains 36 tracked entries and about 8,558 lines with no index or placement convention. Unrelated categories are mixed together:

• CI validators and policy gates
• checked-in artifact generators
• local debugging and benchmark helpers
• database/index initialization
• destructive or one-shot migration/repair commands
• manual test-data seeds
• documentation and log-shipping examples

This makes every file look equally current and supported. A contributor or coding agent cannot tell whether a script is an active CI contract, a supported upgrade step, an optional operator tool, or an implementation artifact that should only exist in Git history.

The audit found concrete drift:

• scripts/generate-rbac-matrix-us1.py --check fails against clean main; it encodes an old hand-curated rollout inventory and is not invoked by CI.
• scripts/append-pending-rbac-entries.py exists for legacy requireAdmin call sites, but production routes now contain zero such calls and the matrix contains zero migration_status: pending rows.
• scripts/seed-deprecated-agent-conversations.py is a 365-line manual fixture with no caller or current documentation and names a nonexistent docker-compose/docker-compose.yaml path.
• scripts/add-new-agent-helm-chart.py has no caller or contributor documentation and perpetuates the repeated per-MCP chart dependency/value blocks that the Helm simplification audit should replace.
• Several database migration and repair scripts are stored at the root without the release that needs them, a removal date, or a supported-upgrade contract.
• scripts/audit-log-shipping/ is operator documentation/example configuration rather than a repository automation script.

Proposed structure

Use a small number of intent-based directories, with a short scripts/README.md index:

scripts/
  ci/             # deterministic validators invoked by workflows
  dev/            # optional local contributor helpers
  ops/            # current operator diagnostics/recovery
  migrations/
    <version>/    # supported upgrade scripts, purpose and retirement version
  generators/     # reproducible checked-in artifact generators

Examples/configuration that belong in documentation should move there instead of creating another script category.

Acceptance criteria

• Inventory every tracked script with owner, callers, side effects, supported environment, and lifecycle: active, supported migration, deprecated, or dead.
• Remove the obsolete RBAC rollout generators and any stale instructions/markers that advertise them.
• Resolve the unreferenced deprecated-conversation seed after confirming whether QA still uses it.
• Do not preserve the current Helm mutation script if the chart is converted to data-driven MCP configuration; otherwise document and test its contract.
• Move active scripts into intent-based directories and update all workflows, Make targets, docs, tests, and generated-file headers atomically.
• Put supported data migrations under a versioned directory with dry-run/apply behavior, rollback/backup guidance, and an explicit retirement policy tied to supported upgrade paths.
• Move operator examples such as audit log shipping into canonical documentation/examples.
• Add a guard that fails when Make, CI, or current docs reference a missing script.
• Keep scripts/README.md concise and generated or validated from the actual caller inventory where practical.

Related

• fix(testing): make contributor and CI test entry points truthful #2423 — truthful contributor and CI test entry points
• docs(maintenance): curate public docs and retain one snapshot per minor #2430 — docs/history retention policy
• [Feature]: Unified local development experience — Docker Compose and Kind parity with shared configuration #1131 — canonical Docker Compose/Kind contributor paths and setup-caipe.sh decomposition

Constraints

• Preserve scripts required to upgrade from every supported release line.
• Never run migration or destructive scripts as part of this cleanup audit.
• Prefer deletion over an archive/ directory when Git history already preserves an unsupported artifact.