refactor(repo): reorganize the repository for its first release

.config/README.md

@@ -7,7 +7,7 @@ container, it goes in here.
 Policy and rationale:
 [`docs/adr/0011-tooling-configuration-layout.md`](../docs/adr/0011-tooling-configuration-layout.md).
 Enforcement: `task check:config` (CFG-01..CFG-08), implemented in
-[`tools/src/config.ts`](../tools/src/config.ts).
+[`tools/src/policy/config.ts`](../tools/src/policy/config.ts).
 
 The convention is shared with `musher-dev/development-container` and
 `musher-dev/platform`. Keeping the three aligned is the point: a contributor
@@ -31,9 +31,11 @@ Call sites are [`Taskfile.yml`](../Taskfile.yml), [`taskfiles/`](../taskfiles/),
 `.config/lefthook.yml`, and [`.github/workflows/`](../.github/workflows/).
 Tool versions are pinned in
 [`tools/package.json`](../tools/package.json) for anything installed by Bun,
-and in [`.devcontainer/mise.toml`](../.devcontainer/mise.toml) for the rest —
-with the CI workflow mirroring the same version, because CI is not a mise host
-and does not read that file.
+and in [`.devcontainer/mise.toml`](../.devcontainer/mise.toml) for the rest.
+CI is not a mise host and does not read that file. The CI workflows pin the
+tools they install themselves, Task and actionlint, to the same versions.
+ShellCheck is the exception: CI uses the copy preinstalled on the runner image,
+which is not pinned and can differ from the container's.
 
 ## Rules
 
@@ -69,7 +71,7 @@ whole directory exists to prevent, and it is one command to rule out.
 | `LICENSE`, `NOTICE` | Repo root | GitHub detects a licence at the root only, and Apache-2.0 expects NOTICE to travel with the work |
 | `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md` | `.github/` | Community health files, which GitHub resolves from there |
 | `biome.json`, `tsconfig.json` | `tools/` | They belong to the `tools/` package and are resolved by it — a package's own config, not a repo-level one |
-| `catalog.json`, `published.json` | Repo root | Published data artifacts, not tool configuration |
+| `published.json` | Repo root | A published data artifact, not tool configuration. The catalog is build output under `dist/`, never tracked |
 | `mise.toml`, `devcontainer.json` | `.devcontainer/` | They provision the environment rather than checking the code |
 | `dependabot.yml`, `release-please/`, `rulesets/`, `workflows/` | `.github/` | GitHub reads these from fixed locations |
 

.config/actions/actionlint.yaml

@@ -15,4 +15,7 @@ self-hosted-runner:
 # is exhaustive on purpose -- with it, `vars.TYPO` is a build failure instead of
 # an empty string that silently changes what a job does. Add a name here in the
 # same change that adds the variable to the repository settings.
-config-variables: []
+config-variables:
+  # The release GitHub App's id. Its private key is the RELEASE_APP_PRIVATE_KEY
+  # secret. Read by release.yml and release-ledger.yml.
+  - RELEASE_APP_ID

.config/lefthook.yml

@@ -7,6 +7,12 @@
 # Keep min_version in step with .devcontainer/mise.toml.
 min_version: 2.1.10
 
+# Standard `**` semantics. Under the default gobwas matcher `**/*.md` needs at
+# least one directory, so a root README.md or tools/biome.json never matched
+# the globs below. With doublestar, `*` stops at `/`: a glob meant for any
+# depth says `**/`.
+glob_matcher: doublestar
+
 pre-commit:
   parallel: true
   jobs:
@@ -42,12 +48,8 @@ pre-commit:
       glob: '**/*.md'
       run: task check:md
 
-    - name: drift
-      glob: 'specifications/**/*.schema.json'
-      run: task check:drift
-
     - name: shell
-      glob: '*.sh'
+      glob: '**/*.sh'
       run: task check:shell:files -- {staged_files}
 
     - name: workflow
@@ -71,11 +73,11 @@ commit-msg:
           printf "  Got:      %s\n" "$first_line" >&2
           printf "%s\n" "" >&2
           printf "%s\n" "  Types:  feat, fix, chore, docs, style, refactor, perf, test, ci, build, revert" >&2
-          printf "%s\n" "  Scopes: component, blueprint, listing, conformance, tools, ci," >&2
-          printf "%s\n" "          devcontainer, docs, repo, deps" >&2
+          printf "%s\n" "  Scopes: core, component, blueprint, listing, conformance, tools, ci," >&2
+          printf "%s\n" "          devcontainer, docs, repo, deps, deps-dev" >&2
           printf "%s\n" "" >&2
-          printf "%s\n" "  The scope drives release-please. feat(component): cuts component/v1.x.0;" >&2
-          printf "%s\n" "  an unscoped feat: releases nothing." >&2
+          printf "%s\n" "  release-please picks the release from the paths a commit changes, not" >&2
+          printf "%s\n" "  its scope: feat/fix/docs under specifications/<family>/ releases it." >&2
           exit 1
         fi
         ' -- {1}

.config/spelling/cspell.json

@@ -30,16 +30,16 @@
     "**/node_modules/**",
     "site/**",
     "tools/bun.lock",
-    "**/schemas/dist/**",
+    "dist/**",
     // The dictionary itself, and a licence whose wording is not ours to edit.
     ".config/spelling/**",
     "LICENSE",
     // Checksums and opaque identifiers, not words.
     "published.json",
     // Conformance vectors are chosen for their bytes, including deliberate
     // misspellings and malformed input. Correcting them would destroy the test.
-    "conformance/**/case.yaml",
-    "conformance/**/tree/**"
+    "specifications/*/v*/conformance/**/case.yaml",
+    "specifications/*/v*/conformance/**/tree/**"
   ],
   "ignoreRegExpList": [
     "/\\b[0-9a-f]{7,64}\\b/",

.config/spelling/musher.txt

@@ -29,6 +29,7 @@ deserialisation
 
 # --- Names and acronyms ------------------------------------------------------
 bluemonday
+CNAB
 Consolas
 Pydantic
 Segoe

.devcontainer/devcontainer.json

@@ -1,4 +1,4 @@
-// musher-dev/spec dev container.
+// musher-dev/specifications dev container.
 //
 // Trimmed from the musher-dev/development-container template. This repository
 // bundles and validates JSON — it builds no images, runs no services, and needs
@@ -9,7 +9,7 @@
 // Kept: Bun and Node for tools/, Task as the runner, shellcheck for the
 // devcontainer scripts, gh for release work.
 {
-  "name": "Musher Specification",
+  "name": "Musher Specifications",
 
   // Pinned to the LTS, not the floating :ubuntu tag — that one rolls to interim
   // releases some upstream Features do not support.
@@ -145,19 +145,21 @@
         },
 
         // Authoring aid: bind the LOCAL bundles, not the published URLs, so
-        // examples and fixtures are checked against the working tree.
+        // examples and fixtures are checked against the working tree. They are
+        // build output under dist/: post-create runs `task bundle`, and so
+        // must you after editing schemas/src.
         "yaml.schemas": {
-          "./specifications/component/v1/schemas/dist/component.schema.json": [
+          "./dist/component/v1/component.schema.json": [
             "specifications/component/v1/examples/*.yaml",
-            "conformance/component/v1/**/case.yaml"
+            "specifications/component/v1/conformance/**/case.yaml"
           ],
-          "./specifications/blueprint/v1/schemas/dist/blueprint.schema.json": [
+          "./dist/blueprint/v1/blueprint.schema.json": [
             "specifications/blueprint/v1/examples/*.yaml",
-            "conformance/blueprint/v1/**/case.yaml"
+            "specifications/blueprint/v1/conformance/**/case.yaml"
           ],
-          "./specifications/listing/v1/schemas/dist/listing.schema.json": [
+          "./dist/listing/v1/listing.schema.json": [
             "specifications/listing/v1/examples/*.yaml",
-            "conformance/listing/v1/**/case.yaml"
+            "specifications/listing/v1/conformance/**/case.yaml"
           ]
         },
 

.devcontainer/scripts/lib/motd.sh

@@ -136,7 +136,6 @@ _motd_quickref() {
   echo ""
   echo "  ${_BOLD}Quick Reference${_RESET}"
   echo "  ${_DIM}${sep}${_RESET}"
-  echo "  docker compose -f .devcontainer/compose.yaml up -d / down / logs -f"
   echo "  git status / log / diff"
   echo "  task                             Task runner"
   echo "  claude                           Claude Code AI"

.devcontainer/scripts/post-create.sh

@@ -59,6 +59,23 @@ install_spec_tools() {
   }
 }
 
+# Builds the schema bundles into dist/, which the editor's yaml.schemas
+# bindings in devcontainer.json point at. Bundles are build output and not
+# tracked, so a fresh container has none until this runs. Best-effort: a
+# failure leaves the container usable, and `task bundle` recovers.
+#
+# Outputs:
+#   Writes progress to stderr via log()
+build_schema_bundles() {
+  command -v task >/dev/null 2>&1 || return 0
+  command -v bun >/dev/null 2>&1 || return 0
+  log "Building schema bundles (task bundle)..."
+  (cd "${SCRIPT_DIR}/../.." && task bundle >/dev/null) || {
+    log "WARNING: task bundle failed; run it once the container is up"
+    return 0
+  }
+}
+
 # Entry point: runs the full post-create setup sequence.
 #
 # Arguments:
@@ -75,6 +92,7 @@ main() {
   install_lefthook_hooks
   # --- Repo-specific setup ---
   install_spec_tools
+  build_schema_bundles
   if ((status != 0)); then
     log "Post-create setup completed with MISSING TOOLS (see the ✗ lines above)"
     return "${status}"

.gitattributes

@@ -10,16 +10,11 @@
 *.ts      text eol=lf
 *.sh      text eol=lf
 
-# Generated bundles are reviewed as text but should not inflate diff stats.
-specifications/*/v*/schemas/dist/*.json linguist-generated=true
-
 *.png     binary
-*.jpg     binary
-*.ico     binary
 
 # Two parser fixtures are *about* their bytes, so normalization would quietly
 # destroy what they test. The CRLF case asserts CRLF endings are accepted; the
 # `* text=auto eol=lf` rule above rewrote it to LF, and it passed while testing
 # nothing. `-text` opts both out of every normalization.
-conformance/component/v1/parser/013-crlf-line-endings/case.yaml -text
-conformance/component/v1/parser/012-byte-order-mark/case.yaml   -text
+specifications/core/v1/conformance/parser/013-crlf-line-endings/case.yaml -text
+specifications/core/v1/conformance/parser/012-byte-order-mark/case.yaml   -text

.github/CODEOWNERS

@@ -16,8 +16,10 @@
 # evaluated per changed file. Listing a path here is therefore a commitment to
 # review every change to it — not a label.
 #
-# Invariants. Each one silently breaks the gate rather than failing loudly, so
-# `task check:rulesets` enforces all of them:
+# Invariants. Each one silently breaks the gate rather than failing loudly.
+# `task check:rulesets` checks only part of this list: RUL-05 rejects a `*`
+# catch-all, and RUL-06 checks each owner's syntax and that every root-anchored
+# literal path exists. The rest are review obligations:
 #
 #   - NEVER add a `*` catch-all. It makes every pull request code-owned and
 #     re-imposes the blanket gate this file exists to retire.
@@ -38,10 +40,11 @@
 # CODEOWNERS entry naming a nonexistent user silently disables the review gate
 # it appears to configure.
 #
-# What is deliberately NOT owned: `specifications/` and `conformance/` carry the
-# normative contract, and GOVERNANCE.md still requires maintainer approval for a
-# breaking change to either. That obligation is now social rather than
-# mechanical — ADR 0015 records the trade and why it was accepted.
+# What is deliberately NOT owned: `specifications/` carries the normative
+# contract, every family's prose, schemas and conformance corpus, and
+# `conformance/` holds only the fixture-format README. GOVERNANCE.md still
+# requires maintainer approval for a breaking change. That obligation is social
+# rather than mechanical — ADR 0015 records the trade and why it was accepted.
 
 # The gate cannot be changed unreviewed. GitHub's own recommendation: protect
 # CODEOWNERS with CODEOWNERS, and protect the ruleset the same way — between