chore: organize repository scripts

.changeset/organize-repository-scripts.md

@@ -0,0 +1,2 @@
+---
+---

.dependency-cruiser.cjs

@@ -59,7 +59,7 @@ module.exports = {
     {
       name: "extension-api-is-import-free",
       comment:
-        "packages/hunk/src/extension-api is the published contract; declaration emission publishes whatever it reaches (scripts/check-pack.ts gates the pack, this gates the graph).",
+        "packages/hunk/src/extension-api is the published contract; declaration emission publishes whatever it reaches (scripts/packaging/check-pack.ts gates the pack, this gates the graph).",
       severity: "error",
       from: { path: "^packages/hunk/src/extension-api/" },
       to: { path: "^packages/", pathNot: "^packages/hunk/src/extension-api/" },

.github/workflows/install-sh-e2e.yml

@@ -1,6 +1,6 @@
 # Runs the hunk.dev install script end to end against the newest published release.
 #
-# The unit suite (scripts/install-sh.test.ts) checks the script as text and exercises its
+# The unit suite (scripts/packaging/install-sh.test.ts) checks the script as text and exercises its
 # functions in isolation; this workflow is the only place the real download, checksum, extract,
 # and PATH flow runs against real release assets. It triggers on changes to the script itself,
 # on a weekly schedule to catch release-asset drift the script did not cause, and on demand.

.github/workflows/pr-ci.yml

@@ -47,7 +47,7 @@ jobs:
         env:
           BASE_SHA: ${{ github.event.pull_request.base.sha }}
           HEAD_SHA: ${{ github.sha }}
-        run: bun run ./scripts/verify-pr-release-notes.ts "$BASE_SHA" "$HEAD_SHA"
+        run: bun run ./scripts/release/verify-pr-release-notes.ts "$BASE_SHA" "$HEAD_SHA"
 
   windows-compat:
     name: Windows compatibility

.github/workflows/release-prebuilt-npm.yml

@@ -59,7 +59,7 @@ jobs:
           if [ "$GITHUB_EVENT_NAME" = "push" ]; then
             current_latest="$(npm view hunkdiff dist-tags.latest)"
           fi
-          resolution="$(bun ./scripts/resolve-release-channel.ts \
+          resolution="$(bun ./scripts/release/resolve-release-channel.ts \
             --event "$GITHUB_EVENT_NAME" \
             --ref "$GITHUB_REF_NAME" \
             --requested-tag "$REQUESTED_NPM_TAG" \
@@ -94,7 +94,7 @@ jobs:
 
       - name: Verify tag matches package version
         if: github.event_name == 'push'
-        run: bun run ./scripts/check-release-version.ts "${{ github.ref_name }}"
+        run: bun run ./scripts/release/check-release-version.ts "${{ github.ref_name }}"
 
       - name: Compare release benchmark snapshot
         id: benchmark-gate
@@ -163,7 +163,7 @@ jobs:
       - name: Build host artifact
         run: |
           bun run build:bin
-          bun run ./scripts/build-prebuilt-artifact.ts --expect-package "${{ matrix.package_name }}"
+          bun run ./scripts/packaging/build-prebuilt-artifact.ts --expect-package "${{ matrix.package_name }}"
 
       # Bun's default x64 runtime is compiled for Haswell and raises SIGILL on older CPUs.
       # Run the real artifact under an emulated pre-AVX CPU so a dropped baseline target
@@ -207,7 +207,7 @@ jobs:
 
       - name: Verify tag matches package version
         if: github.event_name == 'push'
-        run: bun run ./scripts/check-release-version.ts "${{ github.ref_name }}"
+        run: bun run ./scripts/release/check-release-version.ts "${{ github.ref_name }}"
 
       - name: Download platform artifacts
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1

.github/workflows/website.yml

@@ -33,7 +33,7 @@ jobs:
         run: bun install --cwd website --frozen-lockfile
 
       - name: Test website tooling
-        run: bun test scripts/generate-docs.test.ts scripts/check-website-links.test.ts scripts/check-extension-catalog.test.ts
+        run: bun test scripts/generate/generate-docs.test.ts scripts/website/check-website-links.test.ts scripts/website/check-extension-catalog.test.ts
 
       - name: Check generated reference docs
         run: bun run check:docs

AGENTS.md

@@ -62,7 +62,7 @@ ReviewIntent + caller facts -> planReviewIntent -> ReviewAction[] -> reducer ->
 - **Conformance:** `test/review-conformance/` has hand-authored semantic fixtures covering every
   registered core, terminal, producer, broker, protocol, and extension projection. Every new
   semantic consumer registers its real projection and runs the whole corpus.
-  `scripts/source-boundaries.test.ts` keeps the seam
+  `scripts/quality/source-boundaries.test.ts` keeps the seam
   renderer/platform-free; its Node-debt list is shrink-only and tombstone lists append-only. A
   repaid seam finding deletes copies, adds a file or banned-symbol tombstone and adversarial
   fixture, registers consumers, and updates `docs/browser-review-seam-audit.md`.
@@ -120,7 +120,7 @@ ReviewIntent + caller facts -> planReviewIntent -> ReviewAction[] -> reducer ->
 - When adding or renaming a built-in theme, update validation, public exports, docs/examples, the
   appropriate Changeset, and tests. Keep source palette tokens separate from semantic mappings and
   cover non-trivial derived colors.
-- `BUNDLED_SHIKI_THEME_DIFF_COLORS` in `packages/hunk/src/core/theme/catalog.ts` is generated. Edit the sourcing policy in `scripts/generate-theme-diff-colors.ts`, then run `bun run generate:theme-colors`.
+- `BUNDLED_SHIKI_THEME_DIFF_COLORS` in `packages/hunk/src/core/theme/catalog.ts` is generated. Edit the sourcing policy in `scripts/generate/generate-theme-diff-colors.ts`, then run `bun run generate:theme-colors`.
 
 ## testing
 

docs/browser-review-rebuild.md

@@ -10,7 +10,7 @@ stack of small, independently reviewable PRs. Its Hunk-owned capability, resourc
 protocol remains separate from the generic per-application daemon contract in
 [`session-broker-sdk.md`](session-broker-sdk.md). Each phase has a hard gate and stands on the
 previous one. The seam contract — shared primitives stay renderer-free and platform-neutral —
-is enforced by `scripts/source-boundaries.test.ts`, whose debt lists may only shrink.
+is enforced by `scripts/quality/source-boundaries.test.ts`, whose debt lists may only shrink.
 
 Each phase lists the audit findings it repays (`browser-review-seam-audit.md`, ids A1–G5). A
 finding whose duplicate sites span phases is checked off when its **last** site converts; until
@@ -222,7 +222,7 @@ allowlist design exists.
 Import gates prove code _may_ use a primitive, not that it _does_ — a consumer can silently
 re-derive. Every phase therefore passes the same five-rung ladder, and each rung is mechanical:
 
-1. **Boundary gates** (every phase, exists today): `scripts/source-boundaries.test.ts` —
+1. **Boundary gates** (every phase, exists today): `scripts/quality/source-boundaries.test.ts` —
    import containment, shrink-only debt lists, and the extracted-duplicate tombstone list.
    Repaying an audit finding means deleting the duplicate copies **and appending their paths to
    the tombstone list in the same PR**; a resurrected path fails CI forever after.

docs/browser-review-seam-audit.md

@@ -286,7 +286,7 @@ duplication); hunk header text (browser delegates to Pierre separators); platfor
   the members that need them — and `toReviewIntent` strips them again, so an action is
   validated and narrowed rather than restated. The action-type-to-parser table is keyed by the
   vocabulary, so a wire-reachable intent without a parser does not compile.
-  `scripts/review-vocabulary.test.ts` is the ladder's rung 5: it asserts the equality, that
+  `scripts/quality/review-vocabulary.test.ts` is the ladder's rung 5: it asserts the equality, that
   every exclusion names a real intent once, and that every type in the vocabulary really
   reaches a parser. Round-trip fixtures for every action live in
   `test/review-conformance/wireFixtures.ts`, registered as the `review wire protocol` consumer.
@@ -385,7 +385,7 @@ path suffixes, expansion retention, git-status badges).
   clamped to the ceiling a reader is allowed to hold rather than emitting frames the reader
   will refuse. `browserReviewServer.ts` imports all of it and declares none of it; the
   browser client imports the same module unchanged in Phase 5, which
-  `scripts/source-boundaries.test.ts` keeps possible by gating the module's transitive
+  `scripts/quality/source-boundaries.test.ts` keeps possible by gating the module's transitive
   closure platform-free. Two decisions differ from the prototype deliberately: a chunked
   payload is framed and verified as the byte stream it is, so reading it is the shared
   `ReviewChunkAssembler` rather than a fourth reassembly loop (C2's rule applied here); and
@@ -488,7 +488,7 @@ path suffixes, expansion retention, git-status badges).
   registration's file limit, and every digest check is `isReviewSha256Digest`. The one
   coupling the protocol cannot express as an import is the transport frame size — importing
   the broker package would cost the module its browser safety — so
-  `scripts/review-vocabulary.test.ts` asserts it instead, alongside a check that no session
+  `scripts/quality/review-vocabulary.test.ts` asserts it instead, alongside a check that no session
   module re-declares a name the review model exports and that no module writes its own
   64-character digest pattern. Naming `isActiveStoredReviewNote` beside
   `isRenderableStoredReviewNote` and commenting `parseReviewState` are browser-tier work and
@@ -653,11 +653,11 @@ implementation does.
 The per-phase verification ladder lives in `browser-review-rebuild.md` § "Per-phase seam
 verification". A finding here counts as repaid only when all four hold: duplicate copies
 deleted, their paths (for whole files) or banned-symbol entries (for function-level
-deletions) appended to the tombstone lists in `scripts/source-boundaries.test.ts`,
+deletions) appended to the tombstone lists in `scripts/quality/source-boundaries.test.ts`,
 the finding's adversarial fixture landed in the conformance harness, and the consumer
 registered against that harness.
 
-- The seam boundary tests (`scripts/source-boundaries.test.ts`) keep deleted copies deleted.
+- The seam boundary tests (`scripts/quality/source-boundaries.test.ts`) keep deleted copies deleted.
 - Renderer parity tests (Phase 5 gate) drive shared fixtures through the terminal planner and
   browser projection and assert identical note placement, gap addressing, reveal targets, and
   default note targets — the drift class import gates cannot catch.

docs/changelog-on-hunk-dev.md

@@ -1,7 +1,7 @@
 # Release notes on hunk.dev
 
-`CHANGELOG.md` is the source of truth for what shipped. `scripts/generate-changelog.ts` projects it
-into the pages published at `hunk.dev/changelog`, the same way `scripts/generate-docs.ts` projects
+`CHANGELOG.md` is the source of truth for what shipped. `scripts/generate/generate-changelog.ts` projects it
+into the pages published at `hunk.dev/changelog`, the same way `scripts/generate/generate-docs.ts` projects
 runtime metadata into the CLI and config references. Nothing under the generated paths is
 hand-edited; `bun run check:changelog` fails the build when they drift.
 
@@ -103,7 +103,7 @@ Presentation lives in the site:
 - The landing page imports `website/releases/latest.json` for its release ribbon, so the current
   version is a static import rather than a build-time parse of generated Markdown.
 
-`vercel.json` must keep `CHANGELOG.md` and `scripts/generate-changelog.ts` in its `ignoreCommand`
+`vercel.json` must keep `CHANGELOG.md` and `scripts/generate/generate-changelog.ts` in its `ignoreCommand`
 path list, or release commits will not trigger a deploy.
 
 ## Social cards

docs/extension-architecture.md

@@ -372,7 +372,7 @@ ordering before core or UI consumes it.
 The authoring surface is the `hunkdiff/extension` export — a façade over
 internal types, declared in `packages/hunk/src/extension-api/types.ts`. That module must
 stay import-free: declaration emission ships every module the entry reaches,
-so an import there publishes Hunk internals (`scripts/check-pack.ts` fails
+so an import there publishes Hunk internals (`scripts/packaging/check-pack.ts` fails
 the pack when it does, and typechecks every `docs/extensions.md` example as
 a consumer). Shapes shared with internal code are declared there and
 re-exported inward.

docs/module-boundaries.md

@@ -10,7 +10,7 @@ graph (`packages/hunk/src/` plus `packages/`, tests excluded):
   and nothing is ever added. New code must respect the boundaries from day one.
 - Rules live in `.dependency-cruiser.cjs`; each rule's comment states the boundary it protects.
 
-`scripts/source-boundaries.test.ts` remains the deeper, hand-authored gate for the review seam
+`scripts/quality/source-boundaries.test.ts` remains the deeper, hand-authored gate for the review seam
 (browser-safe closure, Node-debt tombstones). The dependency-cruiser rules are the coarse
 tier-level complement, with real module resolution instead of regex import scanning.
 
@@ -169,7 +169,7 @@ module that owns their behaviour, one home each:
 Deleting the re-exports made one hidden dependency visible: `core/review/annotations.ts` names
 `AgentAnnotation`, which is declared in `packages/hunk/src/extension-api/types.ts` because it is
 simultaneously an internal model type and part of the published contract. Routing that through
-`core/types.ts` had disguised it as a core-local import, and `scripts/source-boundaries.test.ts`
+`core/types.ts` had disguised it as a core-local import, and `scripts/quality/source-boundaries.test.ts`
 ("keeps the review model contained in core") caught it the moment the disguise came off. The
 allowance is now explicit and narrow — that one file, not the tree — and it cannot widen the
 seam, since `extension-api-is-import-free` forbids `extension-api/types.ts` any import at all.

docs/source-architecture.md

@@ -20,7 +20,7 @@ for executable rules and migration history.
 
 Of the checked-in workspaces, only `hunkdiff` is published. Release automation also generates the
 public `hunkdiff-{platform}-{arch}` binary packages from the matrix in
-`scripts/prebuilt-package-helpers.ts`. Provider, VCS helper, broker, and term-video workspaces remain
+`scripts/packaging/prebuilt-package-helpers.ts`. Provider, VCS helper, broker, and term-video workspaces remain
 private.
 
 ## Hunk source ownership
@@ -102,8 +102,8 @@ path. The browser client and UI remain planned.
   public/provider contracts.
 
 `bun run deps:check` applies `.dependency-cruiser.cjs` to every package and to Hunk's internal tiers.
-`scripts/source-boundaries.test.ts` adds browser-safe review and provider checks. The executable
-rules take precedence over this summary.
+`scripts/quality/source-boundaries.test.ts` adds browser-safe review and provider checks. The
+executable rules take precedence over this summary.
 
 ## Bootstrap and lifecycle
 

docs/watch-benchmark-final.md

@@ -274,7 +274,7 @@ Complete harness file inventory:
 - **Protocol/fixture/schema/runner/report:** `benchmarks/watch/README.md`, `fixture.ts`, `campaign.ts`, `schema.ts`, `run.ts`, `report.ts`, and their `fixture.test.ts`, `campaign.test.ts`, `schema.test.ts`, and `run.test.ts`.
 - **Terminal, ConPTY, sampling, and Git instrumentation:** `terminal.ts`, `sampler.ts`, `git-log.ts`, `observer-probe.ts`, `artifacts.ts`, with `terminal.test.ts`, `sampler.test.ts`, `git-log.test.ts`, and `observer-probe.test.ts`.
 - **Freeze, provenance, transfer, build, and preflight:** `freeze.ts`, `stage.ts`, `build-host.ts`, `host-identity.ts`, `host-preflight.ts`, `prepare-preflight.ts`, with `stage.test.ts`, `build-host.test.ts`, `host-identity.test.ts`, `host-preflight.test.ts`, and shared `test-helpers.ts`.
-- **Package/build integration:** seven `bench:watch*` scripts in `package.json`; dev-only `@xterm/headless@5.5.0` and `ghostty-opentui@1.4.10` plus `bun.lock`; `scripts/build-bin.ts` reuses `process.execPath` to prevent ambient-Bun builds.
+- **Package/build integration:** seven `bench:watch*` scripts in `package.json`; dev-only `@xterm/headless@5.5.0` and `ghostty-opentui@1.4.10` plus `bun.lock`; `scripts/build/build-bin.ts` reuses `process.execPath` to prevent ambient-Bun builds.
 - **Benchmark-only production seams:** `packages/hunk/src/core/watch/observer.ts` and `.test.ts` accept an injected `auto|native|chokidar` backend for forced probes; production remains `auto`.
 - **Workflow:** `.github/workflows/benchmarks.yml` contains the Windows adapter.
 - **Maintenance changesets:** `.changeset/watch-benchmark-harness.md` and `.changeset/witty-schools-sit.md` are empty/non-release changesets.
@@ -306,4 +306,4 @@ The ARM64 VM uses native ARM64 Bun 1.3.14 and builds/checksums a native PE. Beca
 
 Campaign-owned worktrees, binaries, fixture reconstructions, terminal logs, and temporary libraries are cleanup-owned by the campaign operator. Linux recovery inventoried and removed only campaign-created extraction files; unrelated paths were not touched. Remote copies may be deleted after archive/checksum acceptance, but the canonical frozen bundle, raw JSON, terminal evidence, failure records, manifests, provenance, summaries, and checksum index should be retained together.
 
-The reusable fixture/freeze/schema/report pieces have value for a future benchmark, but maintaining the full harness means owning ConPTY adapters, two terminal parsers, OS samplers, workflow behavior, and cross-platform tests. **Recommended disposition:** retain the canonical campaign archive and this report; keep PR #531 free of harness-only code; preserve or extract the reusable core in a focused benchmark follow-up only if another campaign is planned; otherwise delete the temporary harness branch, manual workflow additions, dev-only terminal dependencies, empty changesets, forced-backend seam, and recovery script after the archive is secured. The exact-Bun `scripts/build-bin.ts` fix is independently useful but should be proposed separately if retained.
+The reusable fixture/freeze/schema/report pieces have value for a future benchmark, but maintaining the full harness means owning ConPTY adapters, two terminal parsers, OS samplers, workflow behavior, and cross-platform tests. **Recommended disposition:** retain the canonical campaign archive and this report; keep PR #531 free of harness-only code; preserve or extract the reusable core in a focused benchmark follow-up only if another campaign is planned; otherwise delete the temporary harness branch, manual workflow additions, dev-only terminal dependencies, empty changesets, forced-backend seam, and recovery script after the archive is secured. The exact-Bun `scripts/build/build-bin.ts` fix is independently useful but should be proposed separately if retained.

install.sh

@@ -22,7 +22,7 @@
 # macOS and Linux only. On Windows, install with `npm install -g hunkdiff`.
 #
 # This file's canonical home is the repository root; the website build stages it into the
-# deploy output so hunk.dev serves it (scripts/stage-install-script.ts).
+# deploy output so hunk.dev serves it (scripts/packaging/stage-install-script.ts).
 #
 # Everything below only defines functions; the last line runs main. A partially delivered
 # script therefore dies on a syntax error instead of executing a truncated prefix.

knip.json

@@ -11,8 +11,8 @@
         "test/session-broker-node/*.ts",
         "test/session-broker-runtime/*.ts",
         "scripts/launch-video/*.{ts,mjs}",
-        "scripts/probe-terminal-theme.ts",
-        "scripts/test-large-untracked-render.tsx",
+        "scripts/dev/probe-terminal-theme.ts",
+        "scripts/dev/test-large-untracked-render.tsx",
         "examples/extensions/**/index.{ts,tsx}",
         "examples/extensions/**/run.ts",
         "examples/**/*.test.ts"