Skip to content

ADR 0026 — Rename new-system/tooling/ to new-system/scripts/

  • Status: ACCEPTED
  • Date: 2026-09-09
  • Decision owner: direct user (Product owner), 2026-09-09 session directive (two explicit confirmations)
  • Method deviation: governance and implementation run in one pass. Approver is the direct user, not the implementing agent. Recorded as DIRECT_USER override in NS3-119; the implementer does not self-approve.

Context

new-system/tooling/ (local validators, catalog/context/docs/migration/release support, 226 files) and root scripts/ (Legacy PHP/KJ-View operations, 177 files) have confusingly similar names. Investigation on 2026-09-09 proved there is no content duplication: filename overlap between the two directories is zero, and new-system/scripts/ held only one orphan one-off generator (since removed). The remaining problem is naming confusion, stated by the Product owner as the reason for this change.

tooling/ is the canonical location in SYSTEM_STRUCTURE_STANDARD.md (BINDING, sections 2, 3, 5.8, 7.1) and is pinned by load-bearing references: 17 package.json scripts, tests/architecture relative imports, tools/context/context_gate.py manifest-directory literals, tooling/docs/validate.mjs execution-state literal, structure/architecture validator self-paths, catalog implementation locations, playwright.config.ts web-server command, .gitignore scratch exclusion, and 300+ documentation path strings.

Decision

Rename new-system/tooling/ to new-system/scripts/ with git mv (content-preserving) and update every load-bearing reference plus documentation path strings in the same changeset (NS3-119). Update the filesystem standard to match; Git history preserves the original paths.

Alternatives

Alternative A — Keep tooling/, add a README pointer (no structural change)

Cheapest and validator-safe, but keeps the exact naming confusion the Product owner asked to remove. Rejected by direct user decision.

Alternative B — Chosen: rename to new-system/scripts/, sweep references

One mechanical rename plus reference sweep. Costs: ~350 touched files (mostly path strings), regenerated structure/architecture baselines, one new Task slice. No behavior change: every moved file keeps byte-identical content at move time; only path strings change.

Alternative C — Merge into root scripts/

Rejected. Root scripts/ is Legacy-runtime operations with no naming discipline; mixing New-System validators into it crosses the New/Legacy boundary the repository deliberately keeps separate.

Consequences

Positive:

  • One fewer confusing near-duplicate top-level name inside new-system/.
  • All executable local tooling lives under a single conventional scripts/ directory.

Negative:

  • Large mechanical diff; blame history on moved lines now passes through the rename commit.
  • Historical operations/handoff/task records are rewritten to the new paths (originals remain in Git history only).
  • Any external checkout, stash, or automation referencing new-system/tooling/ breaks and must rebase onto the rename.
  • NS3-116 audit EVIDENCE_MANIFEST.json path keys are updated; SHA digests are unchanged because file contents are unchanged.

Revisit triggers

  • A second local-support directory appears beside scripts/.
  • The rename breaks a consumer that cannot rebase (revert the single rename commit; no runtime or data rollback is required).

Review evidence

  • NS3-119 handoff records focused checks (residual grep, structure/architecture checks, affected architecture tests, docs/catalog validation) and BLOCKED items (HEAD-based preflight/verify, independent verifier).
  • No commit or push is part of this slice; Git delivery follows the standard promotion path only on separate explicit request.

---

Source: new-system/docs/decisions/0026-rename-tooling-to-scripts.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.