diff --git a/CLAUDE.md b/CLAUDE.md index 8b3cf835..f84f7b5f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,11 +2,17 @@ This repository builds repositories for AI agents first and people second. -Every repository generated from it shares one shape: the same folders, the same commands, the same checks, and the same kinds of docs in the same places. What is shared is that each file exists and where it sits, not what it says. The program and its files differ from one repository to the next, and so do the contents of the files that describe it: every repository has a `CLAUDE.md`, but each holds that repository's own contract. So does local configuration: every repository has a `.env`, and some fill it. An addon is part of the shape too: a repository adopts it only when it has a reason to, but once adopted it sits where it sits everywhere else. An agent that has learned one repository has learned the rest, so it spends its context on the task instead of on finding its way around. +Every repository generated from it shares one shape: the same folders, the same commands, the same checks, and the same kinds of docs in the same places. What is shared is that each file exists and +where it sits, not what it says. The program and its files differ from one repository to the next, and so do the contents of the files that describe it: every repository has a `CLAUDE.md`, but each +holds that repository's own contract. + +So does local configuration: every repository has a `.env`, and some fill it. An addon is part of the shape too: a repository adopts it only when it has a reason to, but once adopted it sits where it +sits everywhere else. An agent that has learned one repository has learned the rest, so it spends its context on the task instead of on finding its way around. Judge every structural decision by four questions: -1. **Is it the same everywhere?** If a repository needs its structure to differ, that's a gap in the template. Fix it here so every repository gets the fix, rather than letting one repository drift on its own. +1. **Is it the same everywhere?** If a repository needs its structure to differ, that's a gap in the template. Fix it here so every repository gets the fix, rather than letting one repository drift on + its own. 2. **Can an agent find it without searching?** A file's location should follow from what the file is, so the path can be predicted before anything is opened. 3. **Does it cost fewer tokens to understand?** The nearest `CLAUDE.md`, the glossary, and one command per job should answer what would otherwise take a sweep of the tree. 4. **Is the work as good or better?** Saving tokens never justifies a worse result. If a shortcut makes the agent's output worse, it doesn't belong here. @@ -20,54 +26,90 @@ This repository builds other repositories, and holds two trees that must not be - **Live configuration** — `scripts/`, `.github/`, `.claude/`, and the root dotfiles govern *this* repository. - **Template payload** — `apps/github-repository-template/src/base-repo/` is copied into every generated repository. Editing it changes future repositories and nothing here. -The trees hold near-identical files, so decide which one a change belongs to before editing: a root-only fix leaves the template shipping the bug, and a payload-only fix leaves this repository running it. +The trees hold near-identical files, so decide which one a change belongs to before editing: a root-only fix leaves the template shipping the bug, and a payload-only fix leaves this repository running +it. -The root was generated from its own payload, plus repository-specific merges. `.repo-template.json` records the payload commit it was last reconciled with and marks `apps/**` as product, so an update never overwrites the payload. It names this file managed: an unmatched path is product-owned, which would put this file beyond every update. +The root was generated from its own payload, plus repository-specific merges. `.repo-template.json` records the payload commit it was last reconciled with and marks `apps/**` as product, so an update +never overwrites the payload. It names this file managed: an unmatched path is product-owned, which would put this file beyond every update. `apps/github-repository-template/docs/github_repository_structure.md` is the payload's structure and bill of materials. Read it before changing what the template ships. ## Commands -Use these instead of per-language tools; each detects the languages present and fails when an expected check cannot run. The payload's `CLAUDE.md` Template Contract restates this section and Layout as bare rules; `apps/github-repository-template/CLAUDE.md` owns keeping them in step. Each script's header comment carries its full reasoning. +Use these instead of per-language tools; each detects the languages present and fails when an expected check cannot run. The payload's `CLAUDE.md` Template Contract restates this section and Layout as +bare rules; `apps/github-repository-template/CLAUDE.md` owns keeping them in step. Each script's header comment carries its full reasoning. - `scripts/doctor` — verify local toolchains, dependencies, hooks, and configuration without contacting hosted services - `scripts/repo-settings check` — inspect GitHub-hosted security and branch settings; run explicitly, since it needs the network and administration visibility -- `scripts/check` — the full local gate: `doctor`, `structure` and `payload-parity`, then lint, format, type check, test, and build with the script tests beside them, the security audit, and pre-commit over every file, tracked and untracked. It prints only the Result table and always writes the full run to `tmp/check.log`; `--verbose` streams everything; `--fast` leaves out `build`, which CI runs on the pull request. It reads no hosted GitHub state but is not offline: `commitlint-test` and pre-commit's hook environments fetch on first use -- `scripts/fix` — the write half of `check`: lint autofix, then formatting, for every stack, unconditionally and in that order so the formatter lays out what the linter rewrote. Go, Swift and Kotlin have no lint autofix and report `lint-fix` `not-applicable`. A `lint-fix` FAIL means findings remain that need hand work -- `scripts/summarize ` — run a check and print only its Result table with findings, then a verdict line of its exit status and a count per state, exiting with that status; read `ci` and other commands through this, since `check` already does +- `scripts/check` — the full local gate: `doctor`, `structure` and `payload-parity`, then lint, format, type check, test, and build with the script tests beside them, the security audit, and + pre-commit over every file, tracked and untracked. It prints only the Result table and always writes the full run to `tmp/check.log`; `--verbose` streams everything; `--fast` leaves out `build`, + which CI runs on the pull request. It reads no hosted GitHub state but is not offline: `commitlint-test` and pre-commit's hook environments fetch on first use +- `scripts/fix` — the write half of `check`: lint autofix, then formatting, for every stack, unconditionally and in that order so the formatter lays out what the linter rewrote. Go, Swift and Kotlin + have no lint autofix and report `lint-fix` `not-applicable`. A `lint-fix` FAIL means findings remain that need hand work +- `scripts/summarize ` — run a check and print only its Result table with findings, then a verdict line of its exit status and a count per state, exiting with that status; read `ci` and + other commands through this, since `check` already does - `scripts/clean` — recursively delete build output and tool caches (`dist`, `build`, `coverage`, `__pycache__`, `.*_cache`, `*.pyc`) -- `scripts/run [unit] [--entry ] [-- args…]` — start a unit per its declared `run` fact. The unit name is required when `apps/` holds several; `--entry` names one program from the unit's own language manifest (a `[project.scripts]` name, a `bin` key, a main package's import path) and is required when it declares several. Arguments after `--` pass through unchanged +- `scripts/run [unit] [--entry ] [-- args…]` — start a unit per its declared `run` fact. The unit name is required when `apps/` holds several; `--entry` names one program from the unit's own + language manifest (a `[project.scripts]` name, a `bin` key, a main package's import path) and is required when it declares several. Arguments after `--` pass through unchanged - `scripts/integration` — run every `tests/integration/` tier, at any scope. Kept out of the gate, since a tier may need a database, container, or network the gate cannot assume -- `scripts/package [unit]` — deliver what the unit ships: an executable per declared target into its `dist/`, emptied first so no stale binary reaches a release, or its `deploy/quadlet/` files validated. Not part of the gate -- `scripts/structure` — audit file placement against Layout below; run by `scripts/check` and by pre-commit on every commit -- `scripts/payload-parity` — refuse a divergence between `.github/` or `scripts/` and the payload's copy, `scripts/CLAUDE.md` excepted; run by `scripts/check` and by pre-commit. It reports rather than repairs, so a Dependabot bump merged into the root fails until it is mirrored; where exactly one copy changed since `HEAD`, a finding ends with the command that mirrors it: a `cp`, or a `git rm` for a deletion. The shellcheck hook skips the payload's `scripts/` on the strength of it +- `scripts/package [unit]` — deliver what the unit ships: an executable per declared target into its `dist/`, emptied first so no stale binary reaches a release, or its `deploy/quadlet/` files + validated. Not part of the gate +- `scripts/structure` — audit file placement against Layout below, and cap each `CLAUDE.md`'s line and block length (ADR 0012); run by `scripts/check` and by pre-commit on every commit +- `scripts/payload-parity` — refuse a divergence between `.github/` or `scripts/` and the payload's copy, `scripts/CLAUDE.md` excepted; run by `scripts/check` and by pre-commit. It reports rather + than repairs, so a Dependabot bump merged into the root fails until it is mirrored; where exactly one copy changed since `HEAD`, a finding ends with the command that mirrors it: a `cp`, or a `git + rm` for a deletion. The shellcheck hook skips the payload's `scripts/` on the strength of it -Every check runs for every language present. Results distinguish `pass`, `not-applicable`, `unavailable`, and `FAIL`, so an intentional no-op cannot look like a runner that executed. See `scripts/CLAUDE.md` before adding a language or a check. +Every check runs for every language present. Results distinguish `pass`, `not-applicable`, `unavailable`, and `FAIL`, so an intentional no-op cannot look like a runner that executed. See +`scripts/CLAUDE.md` before adding a language or a check. -The only non-shell code here is the Python under `apps/repo-builder/`, declared by the root `pyproject.toml`. Detection reads it, which puts ruff, ty, and pytest over that unit and makes `scripts/doctor` require `uv`. It is root-only and never mirrored into the payload, whose repositories have no such unit. It sets: +The only non-shell code here is the Python under `apps/repo-builder/`, declared by the root `pyproject.toml`. Detection reads it, which puts ruff, ty, and pytest over that unit and makes +`scripts/doctor` require `uv`. It is root-only and never mirrored into the payload, whose repositories have no such unit. It sets: - `testpaths`, bounding pytest to that unit so a payload `.py` is not collected as a test here. ruff and ty get no `include`: one would narrow them to that path rather than widen them. -- the formatter's `exclude = ["*.md"]`, since `ruff format` rewrites Python fenced in Markdown, which would put `scripts/fix` in the business of editing the payload and the frozen plans in `docs/plans/`. +- the formatter's `exclude = ["*.md"]`, since `ruff format` rewrites Python fenced in Markdown, which would put `scripts/fix` in the business of editing the payload and the frozen plans in + `docs/plans/`. - `addopts`, running the suite with a worker per CPU through pytest-xdist, since it waits on git and subprocesses; `-n 0` runs it serially. ## Git - Pre-commit blocks commits to `main` and `master`; branch first. -- Run `scripts/check --fast` before committing, and the whole `scripts/check` when the change could break the build. It runs CI's checks plus pre-commit over every file, `--fast` leaving the build to CI, but with the machine's tool versions rather than CI's fresh installs, so a lint can pass here and fail there; `scripts/CLAUDE.md` carries the rule. -- These prompt for approval: `git reset --hard`, `git clean`, `git rebase`, `rm`, `git rm`, and the `gh` commands that merge pull requests, cut releases, or delete the repository. Edits do not: this repository's `.claude/settings.json` allows `Edit(/**)`, anchored at the session's starting directory, so a session started at the checkout root edits or writes any file without a prompt, root files and dotfiles included. Claude Code's built-in protected paths, such as `.claude/`, `.git/`, `.devcontainer/`, and `.pre-commit-config.yaml`, stay gated whatever an allow rule says, and so do the files the operator's global `ask` rules name, such as `.env`, `*.pem`, and `secrets/`, since an `ask` outranks an `allow`. +- Run `scripts/check --fast` before committing, and the whole `scripts/check` when the change could break the build. It runs CI's checks plus pre-commit over every file, `--fast` leaving the build to + CI, but with the machine's tool versions rather than CI's fresh installs, so a lint can pass here and fail there; `scripts/CLAUDE.md` carries the rule. +- These prompt for approval: `git reset --hard`, `git clean`, `git rebase`, `rm`, `git rm`, and the `gh` commands that merge pull requests, cut releases, or delete the repository. Edits do not: this + repository's `.claude/settings.json` allows `Edit(/**)`, anchored at the session's starting directory, so a session started at the checkout root edits or writes any file without a prompt, root files + and dotfiles included. + + Claude Code's built-in protected paths, such as `.claude/`, `.git/`, `.devcontainer/`, and `.pre-commit-config.yaml`, stay gated whatever an allow rule says, and so do the files the operator's + global `ask` rules name, such as `.env`, `*.pem`, and `secrets/`, since an `ask` outranks an `allow`. - Work reaches `main` through a pull request under `.github/PULL_REQUEST_TEMPLATE.md`; a ruleset enforces it (Repository settings below). -- Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#specification): `type(optional scope): subject`, a blank line, then the body. commitlint enforces it at `commit-msg`, with rules in `.commitlintrc.yaml`. The subject is lowercase after the type, with no trailing period. A body is expected: it is the only surviving record of why. -- Every commit carries a `Generated-By: ` trailer, required by `trailer-exists` in `.commitlintrc.yaml`. `scripts/attribute-commit` writes it at `prepare-commit-msg`: it inserts `Generated-By: ` from `CLAUDE_COMMIT_MODEL`, which the operator's user-level `commit-model` hook exports into an agent's git commands, or else from the entries that hook writes under `${XDG_CACHE_HOME:-~/.cache}/claude-commit-model//`, one per command, taking the model only when the entries for the exact command running agree, so parallel agents in one session cannot cross-attribute; and it replaces a stray `Co-Authored-By: ` with that ID, or without one rewrites it as a `Generated-By` spelling the display name as an ID, since a tool is not a co-author; a human's `Co-Authored-By:` stays. It inserts nothing without either source or during a rebase or cherry-pick, so those commits and any written by hand add their own line or are refused at `commit-msg`. There `attribute-commit --check` refuses a value that is not shaped as a model ID (one word, no `[1m]`-style suffix), since hand-typed display names made the record unsearchable; replayed commits pass. -- GitHub's generated merge subjects are on commitlint's default ignore list and need no CI check. A hand-written merge subject takes one of those shapes, `Merge into `; `.commitlintrc.yaml` says why it holds no `ignores`. -- A changed `CHANGELOG.md` is structurally checked at `pre-push`, and in CI over the pull-request range; that validates an entry, not whether one was owed. This repository keeps none: `CHANGELOG.md` is an addon at `apps/github-repository-template/src/repository-addons/CHANGELOG.md`, the only changelog the check fires on here. -- The commit type signals a changelog entry without deciding it: `feat`, `fix`, and anything with `!` or a `BREAKING CHANGE:` footer usually owe one; `docs`, `style`, `test`, `ci`, and `chore` usually do not. Notability is judged per pull request. +- Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#specification): `type(optional scope): subject`, a blank line, then the body. commitlint enforces it at + `commit-msg`, with rules in `.commitlintrc.yaml`. The subject is lowercase after the type, with no trailing period. A body is expected: it is the only surviving record of why. +- Every commit carries a `Generated-By: ` trailer, required by `trailer-exists` in `.commitlintrc.yaml`. + + `scripts/attribute-commit` writes it at `prepare-commit-msg`: it inserts `Generated-By: ` from `CLAUDE_COMMIT_MODEL`, which the operator's user-level `commit-model` hook exports into an + agent's git commands, or else from the entries that hook writes under `${XDG_CACHE_HOME:-~/.cache}/claude-commit-model//`, one per command, taking the model only when the entries for the + exact command running agree, so parallel agents in one session cannot cross-attribute; + + and it replaces a stray `Co-Authored-By: ` with that ID, or without one rewrites it as a `Generated-By` spelling the display name as an ID, since a tool is not a + co-author; a human's `Co-Authored-By:` stays. + + It inserts nothing without either source or during a rebase or cherry-pick, so those commits and any written by hand add their own line or are refused at `commit-msg`. There `attribute-commit + --check` refuses a value that is not shaped as a model ID (one word, no `[1m]`-style suffix), since hand-typed display names made the record unsearchable; replayed commits pass. +- GitHub's generated merge subjects are on commitlint's default ignore list and need no CI check. A hand-written merge subject takes one of those shapes, `Merge into `; + `.commitlintrc.yaml` says why it holds no `ignores`. +- A changed `CHANGELOG.md` is structurally checked at `pre-push`, and in CI over the pull-request range; that validates an entry, not whether one was owed. This repository keeps none: `CHANGELOG.md` + is an addon at `apps/github-repository-template/src/repository-addons/CHANGELOG.md`, the only changelog the check fires on here. +- The commit type signals a changelog entry without deciding it: `feat`, `fix`, and anything with `!` or a `BREAKING CHANGE:` footer usually owe one; `docs`, `style`, `test`, `ci`, and `chore` usually + do not. Notability is judged per pull request. - Plan mode writes to the tracked `docs/plans/`, so a plan lands in the diff with its code. ## Layout -Where a new file goes. `scripts/structure` enforces every placement rule here as code, checks a unit declaration's values, and reports the three content rules `not-applicable`. The orphan-manifest rule at the end is `libs/detect.sh`'s, since it needs a language. +Where a new file goes. `scripts/structure` enforces every placement rule here as code, checks a unit declaration's values, and reports the three content rules `not-applicable`. The orphan-manifest +rule at the end is `libs/detect.sh`'s, since it needs a language. -**Root holds only these, and everything at root is repo-wide.** Root `libs/`, `tests/`, `scripts/`, `tools/`, `deploy/`, `assets/`, `config/`, `examples/`, and `vendor/` hold only what spans apps or operates on the whole repository; anything scoped to one app belongs under that app. +**Root holds only these, and everything at root is repo-wide.** Root `libs/`, `tests/`, `scripts/`, `tools/`, `deploy/`, `assets/`, `config/`, `examples/`, and `vendor/` hold only what spans apps or +operates on the whole repository; anything scoped to one app belongs under that app. - `.claude/` — agent configuration for this repository - `.devcontainer/` — the dev container, an addition by occasion @@ -77,7 +119,8 @@ Where a new file goes. `scripts/structure` enforces every placement rule here as - `libs/` — code shared across apps - `scripts/` — every portable shell script, whoever runs it - `tests/` — cross-app and end-to-end tests only -- `tools/` — helpers built before they run, one directory per program with its own manifest. The split from `scripts/` is by artifact, not caller: a CI script is the first thing run locally to reproduce a failure +- `tools/` — helpers built before they run, one directory per program with its own manifest. The split from `scripts/` is by artifact, not caller: a CI script is the first thing run locally to + reproduce a failure - `deploy/` — one folder per technology: `quadlet/`, `containerfile/`, `compose/`, `systemd/`, `env/`, and no loose files - `assets/` — static non-code files shared across apps - `config/` — settings a program reads, its defaults; per-environment values go in `deploy/env/` @@ -86,16 +129,22 @@ Where a new file goes. `scripts/structure` enforces every placement rule here as - `tmp/` — gitignored scratch space - a toolchain folder, such as `gradle/` beside `gradlew`; see below -Root *files* are permitted by name: the eight the template ships, `.repo-template.json`, `.gitmodules`, `.structure-allow`, `GLOSSARY.md`, `GLOSSARY-MAP.md`, every addition by occasion, the root workspace manifests and lockfiles of six of the seven languages (Swift has none; see the orphan-manifest rule), and C and C++'s `.clang-format` and `.clang-tidy`, which read no manifest. `.gitkeep` is permitted anywhere. Anything else needs an entry in `.structure-allow`. +Root *files* are permitted by name: the eight the template ships, `.repo-template.json`, `.gitmodules`, `.structure-allow`, `GLOSSARY.md`, `GLOSSARY-MAP.md`, every addition by occasion, the root +workspace manifests and lockfiles of six of the seven languages (Swift has none; see the orphan-manifest rule), and C and C++'s `.clang-format` and `.clang-tidy`, which read no manifest. `.gitkeep` is +permitted anywhere. Anything else needs an entry in `.structure-allow`. **`apps/` holds the smallest deployable units**, possibly just one. - A unit is one folder under `apps/`: the smallest piece delivered on its own, whether deployed, installed, published, or copied. A file directly in `apps/` belongs to no unit. -- Split a unit into domains only for distinct business areas that benefit from isolation. Each domain is a folder under its unit with its own `src/`, which is what tells a domain from a misspelled scoped folder: the unit level cannot be an allowlist, since a domain name is yours to choose. So a folder under a unit without one is a finding. Below a domain only `src/`, scoped folders, and the domain's own files are allowed. Domains do not nest. +- Split a unit into domains only for distinct business areas that benefit from isolation. Each domain is a folder under its unit with its own `src/`, which is what tells a domain from a misspelled + scoped folder: the unit level cannot be an allowlist, since a domain name is yours to choose. So a folder under a unit without one is a finding. Below a domain only `src/`, scoped folders, and the + domain's own files are allowed. Domains do not nest. - `src/` sits under the unit, or under each domain when there are domains. Never both, and never `apps/src/`. -- A unit or domain may hold its own `libs/`, `tests/`, `scripts/`, `docs/`, `tools/`, `deploy/`, `assets/`, `config/`, `examples/`, or `vendor/`, scoped to it. A unit, never a domain, may hold a gitignored `state/` at its root; see the rule on files a program writes. +- A unit or domain may hold its own `libs/`, `tests/`, `scripts/`, `docs/`, `tools/`, `deploy/`, `assets/`, `config/`, `examples/`, or `vendor/`, scoped to it. A unit, never a domain, may hold a + gitignored `state/` at its root; see the rule on files a program writes. -**Every unit declares how it runs and what it ships** in a `.unit.json` at the unit's root, never a domain's. Neither fact is on disk: a Go module with one `main` package could be a CLI, a TUI, or a service. `docs/adrs/0001-declare-unit-delivery-as-two-facts.md` has the reasoning; read it before changing the shape. +**Every unit declares how it runs and what it ships** in a `.unit.json` at the unit's root, never a domain's. Neither fact is on disk: a Go module with one `main` package could be a CLI, a TUI, or a +service. `docs/adrs/0001-declare-unit-delivery-as-two-facts.md` has the reasoning; read it before changing the shape. ```json { "schema_version": 1, "run": "oneshot", "ships": { "kind": "executable", "targets": ["linux-amd64"] } } @@ -105,48 +154,82 @@ Root *files* are permitted by name: the eight the template ships, `.repo-templat - `ships.kind` — `executable`, `quadlet`, or `none`. - `ships.targets` — required exactly when the kind is `executable`, rejected otherwise. The template's own vocabulary, which each language adapter translates: `linux-amd64`, `macos-arm64`. -The two facts vary independently and every pairing is legal: a scheduled job runs `oneshot` and ships a `quadlet`; a library runs `none` and still ships. The audit checks values only, since a rule forbidding a combination is one nobody revisits when the exception arrives. +The two facts vary independently and every pairing is legal: a scheduled job runs `oneshot` and ships a `quadlet`; a library runs `none` and still ships. The audit checks values only, since a rule +forbidding a combination is one nobody revisits when the exception arrives. Reading the file needs `jq`, which `scripts/doctor` requires. Without it the audit reports `unavailable` and fails, and the suites that exercise a unit skip every case. -**`tests/integration/` is the integration tier**, at any scope holder. It needs no placement rule, since `tests/` may nest its own kind; the name matters only to the capabilities: `scripts/integration` runs it and the gate does not. pytest and `go test ./...` discover by walking the tree, so their exclusion is wired; the other five declare their test set (an npm script, a Gradle source set, a SwiftPM or Cargo test target, a CMake `add_test()`), and that declaration leaves the tier out. +**`tests/integration/` is the integration tier**, at any scope holder. It needs no placement rule, since `tests/` may nest its own kind; the name matters only to the capabilities: +`scripts/integration` runs it and the gate does not. pytest and `go test ./...` discover by walking the tree, so their exclusion is wired; the other five declare their test set (an npm script, a +Gradle source set, a SwiftPM or Cargo test target, a CMake `add_test()`), and that declaration leaves the tier out. + +**Scoped folders nest freely but never hold a `src/`.** `libs/`, `tests/`, `scripts/`, `tools/`, `assets/`, `config/`, `docs/`, and `deploy/` may nest another kind (`scripts/tests/libs/`) or their own +(`tests/` under `tests/`). Choose the folder whose scope matches the file's. -**Scoped folders nest freely but never hold a `src/`.** `libs/`, `tests/`, `scripts/`, `tools/`, `assets/`, `config/`, `docs/`, and `deploy/` may nest another kind (`scripts/tests/libs/`) or their own (`tests/` under `tests/`). Choose the folder whose scope matches the file's. +**`examples/` and `vendor/` are opaque.** Each is a scoped folder whose contents are another program's shape, an example's own `src/` included, so every depth rule stops at it. Nothing lints, formats, +or tests `vendor/`: `libs/detect.sh` excludes it from ruff, ty, pytest, and gofmt, the other runners build only what their manifests declare, and both `.pre-commit-config.yaml` copies exclude it from +each fixer and lint. gitleaks, `detect-private-key`, `check-added-large-files`, and `check-merge-conflict` still read it. A `.structure-allow` prefix is left for tracked fixtures. -**`examples/` and `vendor/` are opaque.** Each is a scoped folder whose contents are another program's shape, an example's own `src/` included, so every depth rule stops at it. Nothing lints, formats, or tests `vendor/`: `libs/detect.sh` excludes it from ruff, ty, pytest, and gofmt, the other runners build only what their manifests declare, and both `.pre-commit-config.yaml` copies exclude it from each fixer and lint. gitleaks, `detect-private-key`, `check-added-large-files`, and `check-merge-conflict` still read it. A `.structure-allow` prefix is left for tracked fixtures. +**A toolchain folder sits beside the file that fixes its name.** `scripts/structure`'s `toolchain_folders` pairs a file with the folder its tool requires beside it and cannot be told to move: +`gradle/` beside `gradlew`, `public/` beside `package.json`. The folder is permitted only in that file's directory, at a scope holder, and is opaque. A framework needing another gets an entry in the +template's table, so every repository carries the same table rather than its own `.structure-allow` line; a name a config line can relocate is relocated into the layout instead. -**A toolchain folder sits beside the file that fixes its name.** `scripts/structure`'s `toolchain_folders` pairs a file with the folder its tool requires beside it and cannot be told to move: `gradle/` beside `gradlew`, `public/` beside `package.json`. The folder is permitted only in that file's directory, at a scope holder, and is opaque. A framework needing another gets an entry in the template's table, so every repository carries the same table rather than its own `.structure-allow` line; a name a config line can relocate is relocated into the layout instead. +**`apps/` is not a scope holder.** The scope holders are the root, a unit, and a domain, so the segment directly under `apps/` is always a unit name: `apps/docs/` and `apps/tests/` are ordinary units. +The rules resume at the unit: `apps/docs/docs/notes.yaml` still needs permission, and `apps/api/docs/src/` is still a `src/` under a scope holder. -**`apps/` is not a scope holder.** The scope holders are the root, a unit, and a domain, so the segment directly under `apps/` is always a unit name: `apps/docs/` and `apps/tests/` are ordinary units. The rules resume at the unit: `apps/docs/docs/notes.yaml` still needs permission, and `apps/api/docs/src/` is still a `src/` under a scope holder. +**Every rule that reads depth stops at the first `src/`**, and at an opaque or toolchain folder. Below a `src/` the language decides, whether a Go package named `docs/`, a Python `scripts/` module, or +a vendored tree. So `apps/api/src/internal/docs/swagger.json` is fine, `apps/api/docs/swagger.json` is not, and a `src/` inside a `src/` is the source tree's own business. -**Every rule that reads depth stops at the first `src/`**, and at an opaque or toolchain folder. Below a `src/` the language decides, whether a Go package named `docs/`, a Python `scripts/` module, or a vendored tree. So `apps/api/src/internal/docs/swagger.json` is fine, `apps/api/docs/swagger.json` is not, and a `src/` inside a `src/` is the source tree's own business. +**No file a program writes is tracked.** What a program only reads is an asset, in the `assets/` at its scope, or a setting, in its `config/`. What it writes while running, such as a save file, a +session, or its own cache, goes in its unit's `state/`, gitignored as `/apps/*/state/`, so a run, a test included, leaves git as it found it. The pattern is anchored to the unit root so a source +package named `state/` below `src/` stays tracked; a re-clone or `git clean -x` loses it. -**No file a program writes is tracked.** What a program only reads is an asset, in the `assets/` at its scope, or a setting, in its `config/`. What it writes while running, such as a save file, a session, or its own cache, goes in its unit's `state/`, gitignored as `/apps/*/state/`, so a run, a test included, leaves git as it found it. The pattern is anchored to the unit root so a source package named `state/` below `src/` stays tracked; a re-clone or `git clean -x` loses it. A file the operator edits by hand is a setting when it changes how the program behaves and an asset otherwise, and so is a record the program wrote once and will not write again, such as a finished season: its snapshot is tracked under `assets/` and read when `state/` holds no working copy, so a fresh clone starts from it. No script checks this rule: it is about what a program does with a file, not where the file sits. +A file the operator edits by hand is a setting when it changes how the program behaves and an asset otherwise, and so is a record the program wrote once and will not write again, such as a finished +season: its snapshot is tracked under `assets/` and read when `state/` holds no working copy, so a fresh clone starts from it. No script checks this rule: it is about what a program does with a file, +not where the file sits. **`docs/` takes Markdown freely at every scope**; anything else needs permission. `.gitkeep` is exempt everywhere. -**`.structure-allow` records permission.** A bare path allows one file. A path ending in `/` is a prefix the audit stops descending into, for a tracked fixture whose shape is not this repository's to decide. The one place it still looks inside is a domain's own `src/`, without which a prefix entry would make the domain rule stricter. +**`.structure-allow` records permission.** A bare path allows one file. A path ending in `/` is a prefix the audit stops descending into, for a tracked fixture whose shape is not this repository's to +decide. The one place it still looks inside is a domain's own `src/`, without which a prefix entry would make the domain rule stricter. -Three rules are about content, and no script can settle them: whether `libs/` holds what several apps share, whether `tests/` spans them, and whether a file sits at its own scope. `scripts/structure` reports them `not-applicable` rather than guessing from paths. +Three rules are about content, and no script can settle them: whether `libs/` holds what several apps share, whether `tests/` spans them, and whether a file sits at its own scope. `scripts/structure` +reports them `not-applicable` rather than guessing from paths. -A package whose language has no root manifest fails the run, because that manifest is what lists it: `go list -m` names only `go.work`'s `use` entries, the Gradle settings file likewise, and CMake configures only what the root `CMakeLists.txt` reaches through `add_subdirectory()`. Swift is excluded: it has no root manifest, and nested packages are how a Swift repository is meant to look. So is a `CMakeLists.txt` below a `src/` or beside another language's manifest, which belongs to that language's native build. The failure names the root manifest to add. +A package whose language has no root manifest fails the run, because that manifest is what lists it: `go list -m` names only `go.work`'s `use` entries, the Gradle settings file likewise, and CMake +configures only what the root `CMakeLists.txt` reaches through `add_subdirectory()`. Swift is excluded: it has no root manifest, and nested packages are how a Swift repository is meant to look. So is +a `CMakeLists.txt` below a `src/` or beside another language's manifest, which belongs to that language's native build. The failure names the root manifest to add. ## Repository settings Some guarantees these files make depend on hosted settings. Current state on `possiblyneal/template`: - Dependabot alerts and security updates: **enabled**. `scripts/security` fails a pull request introducing a CVE; these open the pull request that resolves it. -- Secret scanning and push protection: **enabled**, available because the repository is public. Push protection refuses a push carrying a recognized secret at the remote, beyond any `--no-verify`. gitleaks in `.pre-commit-config.yaml` still runs earlier and sees formats GitHub's providers do not. -- Branch rulesets: **active on `main`**, named `main`, with no bypass actors, so an administrator disabling it is the only way past. It requires a pull request, a true merge commit, and the three checks that report on every pull request: `CI`, `Security`, and CodeQL's `Code scanning enabled` (`docs/adrs/0010-run-generates-fixed-steps-as-commands.md` has why no language-matrix name is required). It refuses deletion and non-fast-forward. `required_approving_review_count` is `0` and `require_extra_approval_for_unattributed_changes` is off, because GitHub refuses self-approval with HTTP 422 and either would leave a solo pull request unmergeable; the `code-reviewed` label and its `Reviewed-Head:` comment stand in for approval. `strict_required_status_checks_policy` is off, leaving a stale base to `/land`, which runs the full local gate when the base moved; the GitHub merge button does not. The ruleset applies before a fresh clone runs `pre-commit install`; `no-commit-to-branch` and `scripts/protect-branch` stay as the earlier, faster refusal. -- Automatic head branch deletion: **enabled**, so the remote branch list stays the work in flight; local branches survive until `git fetch --prune`. It is a checkbox rather than a workflow, which would need a `contents: write` job to reimplement a free setting. Every repository requires it: `scripts/repo-settings check` reports it off as `FAIL`, where the other merge settings are optional. -- Code scanning: **enabled**. `.github/workflows/codeql.yml`'s `scanning` job finds the repository public, so `detect` and `analyze` run over actions and python. The stand-down path stays for private generated repositories, where the check goes green without scanning, so only an `analyze` row that ran means coverage. `generation.features` is empty, since nothing is omitted by choice. +- Secret scanning and push protection: **enabled**, available because the repository is public. Push protection refuses a push carrying a recognized secret at the remote, beyond any `--no-verify`. + gitleaks in `.pre-commit-config.yaml` still runs earlier and sees formats GitHub's providers do not. +- Branch rulesets: **active on `main`**, named `main`, with no bypass actors, so an administrator disabling it is the only way past. It requires a pull request, a true merge commit, and the three + checks that report on every pull request: `CI`, `Security`, and CodeQL's `Code scanning enabled` (`docs/adrs/0010-run-generates-fixed-steps-as-commands.md` has why no language-matrix name is + required). It refuses deletion and non-fast-forward. + + `required_approving_review_count` is `0` and `require_extra_approval_for_unattributed_changes` is off, because GitHub refuses self-approval with HTTP 422 and either would leave a solo pull request + unmergeable; the `code-reviewed` label and its `Reviewed-Head:` comment stand in for approval. `strict_required_status_checks_policy` is off, leaving a stale base to `/land`, which runs the full + local gate when the base moved; the GitHub merge button does not. + + The ruleset applies before a fresh clone runs `pre-commit install`; `no-commit-to-branch` and `scripts/protect-branch` stay as the earlier, faster refusal. +- Automatic head branch deletion: **enabled**, so the remote branch list stays the work in flight; local branches survive until `git fetch --prune`. It is a checkbox rather than a workflow, which + would need a `contents: write` job to reimplement a free setting. Every repository requires it: `scripts/repo-settings check` reports it off as `FAIL`, where the other merge settings are optional. +- Code scanning: **enabled**. `.github/workflows/codeql.yml`'s `scanning` job finds the repository public, so `detect` and `analyze` run over actions and python. The stand-down path stays for private + generated repositories, where the check goes green without scanning, so only an `analyze` row that ran means coverage. `generation.features` is empty, since nothing is omitted by choice. - GitHub Actions: **verified**. `ci.yml` and `security.yml` pass on `main`. -Secret scanning, push protection, code scanning, and rulesets are free on a public repository and unavailable on a private one on this plan, so a generated repository that stays private does without all four. `scripts/repo-settings check` reports push protection and rulesets `not offered for the plan` there, which is where its stand-down paths are exercised. +Secret scanning, push protection, code scanning, and rulesets are free on a public repository and unavailable on a private one on this plan, so a generated repository that stays private does without +all four. `scripts/repo-settings check` reports push protection and rulesets `not offered for the plan` there, which is where its stand-down paths are exercised. ## Agent skills -The engineering skills (`/wayfinder`, `/triage`, `/ship`) carry the GitHub Issues, `gh`, and sixteen-role label defaults: five triage states and eleven categories, one per Conventional Commit type. A repository that differs records a departure in `.repo-template.json` `generation.features`; this repository records none. See `docs/adrs/0007-carry-agent-skill-defaults-in-the-skills.md` and `docs/adrs/0009-name-ticket-categories-after-commit-types.md`. +The engineering skills (`/wayfinder`, `/triage`, `/ship`) carry the GitHub Issues, `gh`, and sixteen-role label defaults: five triage states and eleven categories, one per Conventional Commit type. A +repository that differs records a departure in `.repo-template.json` `generation.features`; this repository records none. See `docs/adrs/0007-carry-agent-skill-defaults-in-the-skills.md` and +`docs/adrs/0009-name-ticket-categories-after-commit-types.md`. ## Child Index diff --git a/apps/github-repository-template/CLAUDE.md b/apps/github-repository-template/CLAUDE.md index 36c95c1b..541e125f 100644 --- a/apps/github-repository-template/CLAUDE.md +++ b/apps/github-repository-template/CLAUDE.md @@ -7,12 +7,25 @@ Owns the payload copied into every repository generated from this template, and ## Ownership - `src/base-repo/` — the payload. Every file here is destined for other repositories. -- `src/repository-addons/` — files held back from the payload because each answers a condition the template cannot know has arrived. Not copied during generation; added by hand when the occasion does arrive. `docs/github_repository_structure.md` groups them under "Additions by Occasion" and names the condition for each. No addon shares a path with `src/base-repo/`: adoption copies into a tree that already holds the payload, so a shared path would overwrite a shipped file while reading as an addition everywhere the directory is described. Guidance about a payload path belongs in that payload file, commented out. The test below enforces it. No addon ships empty either: each carries its own guidance — comments where the format has them, prose where it does not — because someone adopting a file by hand has no manifest to read, and a zero-byte copy gives them a path and nothing else. -- `src/addon-adoption.json` — which regions of each addon must be edited before that addon is safe to ship: `slots` (a token to replace), `reviews` (a section demanding a judgement, with no token to grep for), `external` (a step outside the repository). Read by the `repo-builder` skill's walkthrough in `apps/repo-builder/src/references/addon-adoption.md`. -- `src/ownership.json` — the ownership rules every generated repository's `.repo-template.json` starts with. `apps/repo-builder/src/scripts/generate.py manifest` writes them at the source commit, and `test_reference_assertions.py` fails when a payload path has no rule here, so a path added to `src/base-repo/` needs a rule in the same commit. -- `src/ruleset.json` — the `main` ruleset body every generated repository starts with, sent by `apps/repo-builder/src/scripts/generate.py settings`. Its required contexts are the job `name:` values of the payload's `ci.yml` and `security.yml` and of `codeql.yml`'s `scanning` job, and `apps/repo-builder/src/scripts/tests/test_generate.py` fails when they differ, so renaming one of those jobs means editing this file in the same commit. Root-only like `src/addon-adoption.json`: it is data for the skill, not a file a generated repository holds. +- `src/repository-addons/` — files held back from the payload because each answers a condition the template cannot know has arrived. Not copied during generation; added by hand when the occasion + does arrive. `docs/github_repository_structure.md` groups them under "Additions by Occasion" and names the condition for each. + + No addon shares a path with `src/base-repo/`: adoption copies into a tree that already holds the payload, so a shared path would overwrite a shipped file while reading as an addition everywhere the + directory is described. Guidance about a payload path belongs in that payload file, commented out. The test below enforces it. + + No addon ships empty either: each carries its own guidance — comments where the format has them, prose where it does not — because someone adopting a file by hand has no manifest to read, and a + zero-byte copy gives them a path and nothing else. +- `src/addon-adoption.json` — which regions of each addon must be edited before that addon is safe to ship: `slots` (a token to replace), `reviews` (a section demanding a judgement, with no token to + grep for), `external` (a step outside the repository). Read by the `repo-builder` skill's walkthrough in `apps/repo-builder/src/references/addon-adoption.md`. +- `src/ownership.json` — the ownership rules every generated repository's `.repo-template.json` starts with. `apps/repo-builder/src/scripts/generate.py manifest` writes them at the source commit, + and `test_reference_assertions.py` fails when a payload path has no rule here, so a path added to `src/base-repo/` needs a rule in the same commit. +- `src/ruleset.json` — the `main` ruleset body every generated repository starts with, sent by `apps/repo-builder/src/scripts/generate.py settings`. Its required contexts are the job `name:` values + of the payload's `ci.yml` and `security.yml` and of `codeql.yml`'s `scanning` job, and `apps/repo-builder/src/scripts/tests/test_generate.py` fails when they differ, so renaming one of those jobs + means editing this file in the same commit. Root-only like `src/addon-adoption.json`: it is data for the skill, not a file a generated repository holds. - `docs/github_repository_structure.md` — Structure and bill of materials for this repo, and briefly what each file/folder is for. -- `scripts/contract-eval` — measures what `src/base-repo/CLAUDE.md`'s Template Contract saves an agent: the same tasks, in fixtures generated from the committed payload, run by `claude -p` with and without that section, reporting pass, turns, tokens, and cost per arm. Run it by hand after committing a contract change, since fixtures come from `HEAD` and it refuses an uncommitted payload; it spends money, so it is in no gate. Its header says how each run is isolated from the operator's own instructions. +- `scripts/contract-eval` — measures what `src/base-repo/CLAUDE.md`'s Template Contract saves an agent: the same tasks, in fixtures generated from the committed payload, run by `claude -p` with and + without that section, reporting pass, turns, tokens, and cost per arm. Run it by hand after committing a contract change, since fixtures come from `HEAD` and it refuses an uncommitted payload; it + spends money, so it is in no gate. Its header says how each run is isolated from the operator's own instructions. The `repo-builder` skill reads `src/base-repo` at a specific commit, never the working tree, so an uncommitted payload edit does not reach a generated repository. @@ -20,40 +33,107 @@ The `repo-builder` skill reads `src/base-repo` at a specific commit, never the w **A file under `src/base-repo/` is not this repository's configuration. It is data.** `src/base-repo/scripts/check` never runs here; the root `scripts/check` does. -**Payload and root are separate edits.** When a change should apply to both, make it in both places in the same commit. A fix at the root only leaves the template shipping the bug to every repository generated afterward. +**Payload and root are separate edits.** When a change should apply to both, make it in both places in the same commit. A fix at the root only leaves the template shipping the bug to every repository +generated afterward. -**The `github-actions` ecosystem only ever bumps the root.** `.github/dependabot.yml` scans it at `/` and `/.github/actions/*`, and neither reaches `apps/`. A bot pull request bumping a pinned action therefore updates the root copy and leaves the payload pinned to the old revision. Mirror the bump into `src/base-repo/.github/` on the bot's own branch before merging it. Nothing in the files themselves says the trees disagree, since both are valid YAML and both pass actionlint, so `scripts/payload-parity` is what reports it: it fails the commit and the gate until the bump is mirrored. It refuses the divergence rather than repairing it, which is what turns each action bump into a complete one. +**The `github-actions` ecosystem only ever bumps the root.** `.github/dependabot.yml` scans it at `/` and `/.github/actions/*`, and neither reaches `apps/`. A bot pull request bumping a pinned action +therefore updates the root copy and leaves the payload pinned to the old revision. Mirror the bump into `src/base-repo/.github/` on the bot's own branch before merging it. -That guard reaches `.github/` and nothing else, so `.pre-commit-config.yaml` — shipped in both trees — is covered by no check at all. The answer there is not a mirror but a second directory, which that ecosystem does allow: `.github/dependabot.yml`'s `pre-commit` entry names the payload alongside the root, and its group carries `group-by: dependency-name`, so a bot bump arrives mirrored rather than needing to be completed by hand. Without that key Dependabot opens one pull request per directory and the split returns in a new shape, so the second directory is worth nothing on its own. That directory is derived rather than carried, from this repository tracking a `.pre-commit-config.yaml` under the payload — the rule is in `apps/repo-builder/src/references/lifecycle.md` beside the one for language entries, so a template update rewriting this file cannot drop it. A hand edit to one copy is still refused by nothing, so read the two against each other rather than waiting for a check to say. The `uv` ecosystem needs no second directory: the root `pyproject.toml` is root-only, for the reason the repository's own `CLAUDE.md` gives. +Nothing in the files themselves says the trees disagree, since both are valid YAML and both pass actionlint, so `scripts/payload-parity` is what reports it: it fails the commit and the gate until the +bump is mirrored. It refuses the divergence rather than repairing it, which is what turns each action bump into a complete one. -**`src/addon-adoption.json`, `src/ownership.json` and `src/ruleset.json` are root-only and stay that way**, deliberate exceptions to the rule above, as `scripts/CLAUDE.md` below is. `src/ownership.json` describes the payload rather than shipping in it: a generate writes its rules into the destination's manifest, so a copy in the payload would be a second list to keep in step. `src/ruleset.json` is the body a generate sends to the host, which a generated repository never reads. `src/addon-adoption.json` describes `src/repository-addons/`, which never reaches a generated repository, so mirroring it into the payload ships an index of files that are not there. It is also a sibling of that directory rather than a file inside it, because anything inside is an addon to copy. The in-file guidance carried by the addons themselves is not deduplicated against it: that guidance serves someone adopting a file by hand, in a repository that has no manifest to read. +That guard reaches `.github/` and nothing else, so `.pre-commit-config.yaml` — shipped in both trees — is covered by no check at all. The answer there is not a mirror but a second directory, which +that ecosystem does allow: `.github/dependabot.yml`'s `pre-commit` entry names the payload alongside the root, and its group carries `group-by: dependency-name`, so a bot bump arrives mirrored rather +than needing to be completed by hand. -**A payload file may exist to serve an addon**, where the unadopted state is a no-op rather than a failure. `src/base-repo/scripts/system-packages` reads `.github/system-packages.txt`, which never ships: without it the script stats one path and exits 0. That is what satisfies the test "The payload is what is useful on day one" sets below — adding a file to the payload asserts its condition holds for every generated repository — since an absence that costs nothing asserts nothing. A shipped file that errors without its addon fails every generated repository instead, which is the line. +Without that key Dependabot opens one pull request per directory and the split returns in a new shape, so the second directory is worth nothing on its own. That directory is derived rather than +carried, from this repository tracking a `.pre-commit-config.yaml` under the payload — the rule is in `apps/repo-builder/src/references/lifecycle.md` beside the one for language entries, so a +template update rewriting this file cannot drop it. -**The `check-json` exclude diverges between the two `.pre-commit-config.yaml` copies on purpose.** `devcontainer.json` is JSON with comments — the dev container schema sets `allowComments` — and both the addon and any copy adopted into a generated repository carry their guidance in them, so the strict-JSON hook has to be told to skip the file. The path differs because the file lives in different places: root excludes the addon at `apps/github-repository-template/src/repository-addons/.devcontainer/devcontainer.json`, the payload excludes `.devcontainer/devcontainer.json` at a destination root. A normalized diff of the two configs shows five divergences and no others: this `exclude` line; the comment above it, since root's explains an addon path and the payload's a destination path; the two root-only hooks `addon-adoption` and `reference-assertions`, which check paths that never reach a generated repository; and the `rulesets` comment, which names this template at the root and cannot at the destination. The `payload-parity` hook is not among them: the check ships in both trees and reports `not-applicable` where there is no payload, so a repository that later grows one is guarded without a sixth divergence to maintain. +A hand edit to one copy is still refused by nothing, so read the two against each other rather than waiting for a check to say. The `uv` ecosystem needs no second directory: the root `pyproject.toml` +is root-only, for the reason the repository's own `CLAUDE.md` gives. -**`scripts/CLAUDE.md` is root-only.** It is this repository's own contract for `scripts/`, and the payload ships no copy — a generated repository gets the Template Contract in `src/base-repo/CLAUDE.md` and builds the rest of its `CLAUDE.md` tree itself, rather than inheriting prose it did not write. So `diff -r scripts apps/github-repository-template/src/base-repo/scripts` reports that one file as only-in-root and nothing else; a second difference is a drift to fix, in whichever tree is behind. +**`src/addon-adoption.json`, `src/ownership.json` and `src/ruleset.json` are root-only and stay that way**, deliberate exceptions to the rule above, as `scripts/CLAUDE.md` below is. +`src/ownership.json` describes the payload rather than shipping in it: a generate writes its rules into the destination's manifest, so a copy in the payload would be a second list to keep in step. -**`src/base-repo/CLAUDE.md`'s Template Contract restates the root `CLAUDE.md`'s Commands and Layout as bare rules.** The root keeps the reasoning; the payload keeps only what a generated repository's agent must obey, since it loads in every session there. Commands names only the four an agent reaches for in most tasks and points to `ls scripts/` for the rest. Git rules are left out: the shipped hooks refuse a bad commit and say why. This repository's root `CLAUDE.md` carries the full Commands and Layout in place of the contract, so a template update to the root merges a contract change into those sections rather than adding a `## Template Contract` beside them. Change a rule in both in the same commit; `test_template_contract.py` catches the payload half when it drifts from the code. Leave out anything that names this repository: the payload, `pyproject.toml`, ADRs it does not ship. +`src/ruleset.json` is the body a generate sends to the host, which a generated repository never reads. `src/addon-adoption.json` describes `src/repository-addons/`, which never reaches a generated +repository, so mirroring it into the payload ships an index of files that are not there. It is also a sibling of that directory rather than a file inside it, because anything inside is an addon to +copy. + +The in-file guidance carried by the addons themselves is not deduplicated against it: that guidance serves someone adopting a file by hand, in a repository that has no manifest to read. + +**A payload file may exist to serve an addon**, where the unadopted state is a no-op rather than a failure. `src/base-repo/scripts/system-packages` reads `.github/system-packages.txt`, which never +ships: without it the script stats one path and exits 0. That is what satisfies the test "The payload is what is useful on day one" sets below — adding a file to the payload asserts its condition +holds for every generated repository — since an absence that costs nothing asserts nothing. A shipped file that errors without its addon fails every generated repository instead, which is the line. + +**The `check-json` exclude diverges between the two `.pre-commit-config.yaml` copies on purpose.** `devcontainer.json` is JSON with comments — the dev container schema sets `allowComments` — and +both the addon and any copy adopted into a generated repository carry their guidance in them, so the strict-JSON hook has to be told to skip the file. + +The path differs because the file lives in different places: root excludes the addon at `apps/github-repository-template/src/repository-addons/.devcontainer/devcontainer.json`, the payload excludes +`.devcontainer/devcontainer.json` at a destination root. + +A normalized diff of the two configs shows five divergences and no others: this `exclude` line; the comment above it, since root's explains an addon path and the payload's a destination path; the two +root-only hooks `addon-adoption` and `reference-assertions`, which check paths that never reach a generated repository; and the `rulesets` comment, which names this template at the root and cannot at +the destination. + +The `payload-parity` hook is not among them: the check ships in both trees and reports `not-applicable` where there is no payload, so a repository that later grows one is guarded without a sixth +divergence to maintain. + +**`scripts/CLAUDE.md` is root-only.** It is this repository's own contract for `scripts/`, and the payload ships no copy — a generated repository gets the Template Contract in +`src/base-repo/CLAUDE.md` and builds the rest of its `CLAUDE.md` tree itself, rather than inheriting prose it did not write. So `diff -r scripts apps/github-repository-template/src/base-repo/scripts` +reports that one file as only-in-root and nothing else; a second difference is a drift to fix, in whichever tree is behind. + +**`src/base-repo/CLAUDE.md`'s Template Contract restates the root `CLAUDE.md`'s Commands and Layout as bare rules.** The root keeps the reasoning; the payload keeps only what a generated repository's +agent must obey, since it loads in every session there. Commands names only the four an agent reaches for in most tasks and points to `ls scripts/` for the rest. Git rules are left out: the shipped +hooks refuse a bad commit and say why. + +This repository's root `CLAUDE.md` carries the full Commands and Layout in place of the contract, so a template update to the root merges a contract change into those sections rather than adding a `## +Template Contract` beside them. Change a rule in both in the same commit; `test_template_contract.py` catches the payload half when it drifts from the code. Leave out anything that names this +repository: the payload, `pyproject.toml`, ADRs it does not ship. **Payload paths lose the `src/base-repo/` prefix when generated**, so a relative reference written inside the payload must be relative to the generated repository's root, not to this one. **Deliberate placeholders, not omissions:** -- `src/base-repo/apps/app-name/` is replaced during generation, and the payload says nothing about it. `apps/repo-builder/src/references/generate.md` step 8 owns the rename: the placeholder is moved to the first derived deployable rather than copied, so it cannot survive generation. -- **The payload ships no directory whose only content is its own name.** `apps/app-name/` carries `.unit.json` and `src/` and nothing else; root `libs/`, `tests/`, `docs/specs/`, and `docs/plans/` and the unit's `tests/` and `docs/specs/` are not shipped. Each was a third statement of what `src/base-repo/scripts/structure` and `docs/github_repository_structure.md` already make — one that carries no reason, cannot be checked, and is free to drift from both. Shipping `tests/` empty at the root *and* at the unit additionally posed the scope question with nothing in either to answer it, and `docs/specs/` contradicted the default tracker, GitHub Issues, which holds specs as issues. Every one remains a valid placement; the structure doc records them as conventions rather than shipped directories. `tmp/` and the `.claude/` subdirectories keep their `.gitkeep` — the first is gitignored and cannot survive empty otherwise, and the second is the surfaces bullet below. `docs/plans/` does not, since plan mode creates it on its first plan. `generate.md` step 8 replicates the two-entry skeleton, so widening it here means widening it there. -- `src/base-repo/.env` is an intentionally empty tracked file giving a generated repository somewhere to put local variables. Do not add content. It is tracked only because the root `.gitignore` pattern does not reach into the payload; at a destination root the same pattern matches it, so it copies across like any other file and can never be committed there. A generated repository has it locally and a clone of that repository does not. -- `.mcp.json` and every `.claude/` subdirectory ship empty, so a new project sees the available surfaces without inheriting rules. Hooks, rules, output styles, and skills are personal tooling, not project configuration — an operator's own global `~/.claude` covers them instead of the payload vendoring copies. The whole `.claude/` tree is gitignored in a generated repository, so — like `.env` — it arrives in its working tree but not its history, and is force-tracked here to ship at all. `CLAUDE.md` is not gitignored there: it carries the repository's actual contract now, not a disposable shim, so it is committed like any other payload file, at the root and at every nested location. +- `src/base-repo/apps/app-name/` is replaced during generation, and the payload says nothing about it. `apps/repo-builder/src/references/generate.md` step 8 owns the rename: the placeholder is moved + to the first derived deployable rather than copied, so it cannot survive generation. +- **The payload ships no directory whose only content is its own name.** `apps/app-name/` carries `.unit.json` and `src/` and nothing else; root `libs/`, `tests/`, `docs/specs/`, and `docs/plans/` and + the unit's `tests/` and `docs/specs/` are not shipped. Each was a third statement of what `src/base-repo/scripts/structure` and `docs/github_repository_structure.md` already make — one that + carries no reason, cannot be checked, and is free to drift from both. + + Shipping `tests/` empty at the root *and* at the unit additionally posed the scope question with nothing in either to answer it, and `docs/specs/` contradicted the default tracker, GitHub Issues, + which holds specs as issues. Every one remains a valid placement; the structure doc records them as conventions rather than shipped directories. + + `tmp/` and the `.claude/` subdirectories keep their `.gitkeep` — the first is gitignored and cannot survive empty otherwise, and the second is the surfaces bullet below. `docs/plans/` does not, + since plan mode creates it on its first plan. `generate.md` step 8 replicates the two-entry skeleton, so widening it here means widening it there. +- `src/base-repo/.env` is an intentionally empty tracked file giving a generated repository somewhere to put local variables. Do not add content. It is tracked only because the root `.gitignore` + pattern does not reach into the payload; at a destination root the same pattern matches it, so it copies across like any other file and can never be committed there. A generated repository has it + locally and a clone of that repository does not. +- `.mcp.json` and every `.claude/` subdirectory ship empty, so a new project sees the available surfaces without inheriting rules. Hooks, rules, output styles, and skills are personal tooling, not + project configuration — an operator's own global `~/.claude` covers them instead of the payload vendoring copies. + + The whole `.claude/` tree is gitignored in a generated repository, so — like `.env` — it arrives in its working tree but not its history, and is force-tracked here to ship at all. `CLAUDE.md` is + not gitignored there: it carries the repository's actual contract now, not a disposable shim, so it is committed like any other payload file, at the root and at every nested location. -**`.github/dependabot.yml` lists only actions and pre-commit**, and that is not an oversight. An entry naming a manifest the repository does not have fails with `dependency_file_not_found` rather than being skipped, and a template cannot know which ecosystem a clone will use — listing six guarantees five broken entries in every one. Nobody copies an entry out of this file by hand either: every `/repo-builder` flow that writes it derives one entry per manifest the destination tracks and appends it to these two, re-deriving the whole set each run, so the entry survives an update by being rebuilt rather than by being carried. The rule is "Dependabot entries follow the manifests present" in `apps/repo-builder/src/references/lifecycle.md`, and the file's own header states the manifest-to-ecosystem mapping for whoever is reading the file rather than the rule. +**`.github/dependabot.yml` lists only actions and pre-commit**, and that is not an oversight. An entry naming a manifest the repository does not have fails with `dependency_file_not_found` rather than +being skipped, and a template cannot know which ecosystem a clone will use — listing six guarantees five broken entries in every one. -**The payload is what is useful on day one.** `README.md`, `LICENSE`, `CONTRIBUTING.md`, `CODEOWNERS`, and the rest are absent because each answers a condition the template cannot know has arrived — not because the baseline is private. The structure doc's "Additions by Occasion" groups them by that condition. Adding one to the payload asserts its condition holds for every generated repository, which is the test to apply before doing so. +Nobody copies an entry out of this file by hand either: every `/repo-builder` flow that writes it derives one entry per manifest the destination tracks and appends it to these two, re-deriving the +whole set each run, so the entry survives an update by being rebuilt rather than by being carried. + +The rule is "Dependabot entries follow the manifests present" in `apps/repo-builder/src/references/lifecycle.md`, and the file's own header states the manifest-to-ecosystem mapping for whoever is +reading the file rather than the rule. + +**The payload is what is useful on day one.** `README.md`, `LICENSE`, `CONTRIBUTING.md`, `CODEOWNERS`, and the rest are absent because each answers a condition the template cannot know has arrived — +not because the baseline is private. The structure doc's "Additions by Occasion" groups them by that condition. Adding one to the payload asserts its condition holds for every generated repository, +which is the test to apply before doing so. ## Work Guidance Before editing under `src/`, ask whether this is a payload change or a root change; no rule in this repository's settings prompts for it. -A payload change ships to repositories that cannot be inspected from here, so prefer changes that fail loudly in a generated repository over changes that silently do nothing. The payload's scripts distinguish `pass`, `not-applicable`, `unavailable`, and `FAIL` for exactly that reason. +A payload change ships to repositories that cannot be inspected from here, so prefer changes that fail loudly in a generated repository over changes that silently do nothing. The payload's scripts +distinguish `pass`, `not-applicable`, `unavailable`, and `FAIL` for exactly that reason. When the structure doc and the payload disagree, one of them is wrong — fix both in the same commit rather than leaving the rationale describing a file that no longer behaves that way. @@ -61,11 +141,23 @@ When the structure doc and the payload disagree, one of them is wrong — fix bo The root `scripts/check` runs shellcheck and actionlint over these files through pre-commit, which is syntax-level only. -The root `scripts/structure` audits these paths too, since they are tracked files of this repository like any other. `src/base-repo/` mirrors a whole repository and passes the Layout rules unaltered, which is a property worth keeping: a payload that needed a `.structure-allow` entry to survive its own audit would be shipping a shape it forbids. `src/repository-addons/` passes for a duller reason — the root allowlists apply only at the real repository root, and nothing there trips a rule that applies at depth. +The root `scripts/structure` audits these paths too, since they are tracked files of this repository like any other. `src/base-repo/` mirrors a whole repository and passes the Layout rules unaltered, +which is a property worth keeping: a payload that needed a `.structure-allow` entry to survive its own audit would be shipping a shape it forbids. `src/repository-addons/` passes for a duller reason +— the root allowlists apply only at the real repository root, and nothing there trips a rule that applies at depth. + +One check reads this directory semantically: the `addon-adoption` pre-commit hook runs `apps/repo-builder/src/scripts/tests/test_addon_adoption.py`, which fails when `src/addon-adoption.json` and +`src/repository-addons/` disagree about which files exist, when an addon sits at a path `src/base-repo/` already ships, when an entry declares a slot token no longer present in its file, or when any +addon ships as a zero-byte file. + +It runs on every commit rather than on a path filter, because `git rm` of an addon is the case a filter cannot see. It does not check that a described region is described *well* — only that it +exists. -One check reads this directory semantically: the `addon-adoption` pre-commit hook runs `apps/repo-builder/src/scripts/tests/test_addon_adoption.py`, which fails when `src/addon-adoption.json` and `src/repository-addons/` disagree about which files exist, when an addon sits at a path `src/base-repo/` already ships, when an entry declares a slot token no longer present in its file, or when any addon ships as a zero-byte file. It runs on every commit rather than on a path filter, because `git rm` of an addon is the case a filter cannot see. It does not check that a described region is described *well* — only that it exists. +`apps/repo-builder/src/scripts/tests/test_template_contract.py` reads `src/base-repo/CLAUDE.md` against `src/base-repo/scripts/structure`: the Template Contract's root folders, scoped folders, +toolchain folders, `deploy/` folders, and `.unit.json` values must equal the audit's lists, every root file it names must be one the audit permits, its `.unit.json` example must pass the audit's own +`unit_facts_program` (skipped where `jq` is absent), and every script it names must exist and be executable. -`apps/repo-builder/src/scripts/tests/test_template_contract.py` reads `src/base-repo/CLAUDE.md` against `src/base-repo/scripts/structure`: the Template Contract's root folders, scoped folders, toolchain folders, `deploy/` folders, and `.unit.json` values must equal the audit's lists, every root file it names must be one the audit permits, its `.unit.json` example must pass the audit's own `unit_facts_program` (skipped where `jq` is absent), and every script it names must exist and be executable. It runs under pytest in `scripts/check`, not as a hook, so it adds no divergence between the two `.pre-commit-config.yaml` copies. It checks the contract against code, not against the root `CLAUDE.md`'s prose, so the root half of the sync rule above is still kept by hand. +It runs under pytest in `scripts/check`, not as a hook, so it adds no divergence between the two `.pre-commit-config.yaml` copies. It checks the contract against code, not against the root +`CLAUDE.md`'s prose, so the root half of the sync rule above is still kept by hand. The payload's behavior is verified where it lands: by `src/base-repo/scripts/tests/*-test` once a repository is generated, and by the `repo-builder` evals under `apps/repo-builder/src/evals/`. diff --git a/apps/github-repository-template/docs/github_repository_structure.md b/apps/github-repository-template/docs/github_repository_structure.md index f09f7a61..98900688 100644 --- a/apps/github-repository-template/docs/github_repository_structure.md +++ b/apps/github-repository-template/docs/github_repository_structure.md @@ -95,7 +95,7 @@ The specific operating parameters for the AI agent. `scripts/release`: Validates a version tag against the changelog, packages every unit under `apps/`, and cuts a GitHub release with whatever those units produced attached. Packaging runs before the tag, so a build that cannot be made publishes nothing; a repository where no unit ships a file still releases. -`scripts/structure`: Audits where files sit against the Layout rules it holds as code — the root folder and file allowlists, the `apps/` unit-and-domain shape, the closed folder vocabulary under a domain, `src/` placement, and the Markdown-only rule for `docs/`. Called by `scripts/check` and by pre-commit on every commit. It reads the contents of exactly one file, a unit's `.unit.json`, whose whole purpose is to state what a tree cannot show; the three rules that turn on what any other file contains are reported `not-applicable` rather than guessed. Reading a declaration needs `jq`, and its absence is reported `unavailable` rather than passed over. +`scripts/structure`: Audits where files sit against the Layout rules it holds as code — the root folder and file allowlists, the `apps/` unit-and-domain shape, the closed folder vocabulary under a domain, `src/` placement, and the Markdown-only rule for `docs/` — and caps every tracked `CLAUDE.md` at 200 bytes a line (`claudemd-lines`) and 600 bytes a block (`claudemd-blocks`), exempting fenced code (``` or ~~~), table rows, and unbreakable tokens, with a section over 8000 bytes counted in the `claudemd-blocks` row as an advisory that never fails. Called by `scripts/check` and by pre-commit on every commit. It reads the contents of two kinds of file: a unit's `.unit.json`, whose whole purpose is to state what a tree cannot show, and every `CLAUDE.md`, measured for length rather than meaning; the three rules that turn on what any other file contains are reported `not-applicable` rather than guessed. Reading a declaration needs `jq`, and its absence is reported `unavailable` rather than passed over. `scripts/payload-parity`: Refuses a divergence between a repository's own `.github/` or `scripts/` and the copy a template payload ships to generated repositories, reading both which paths exist and what each one holds from the Git index, since it runs at pre-commit and the index is the tree being committed. `scripts/CLAUDE.md` is the one root-only path, since it documents this repository's scripts. The shellcheck hook skips the payload's `scripts/` because this check holds it identical to the root's. `.github/dependabot.yml` is the one named content exception, and it differs twice. Its language entries are derived per repository from the manifests that repository tracks, so the payload copy must not carry an entry for a manifest it does not ship while the root copy carries the entry its own `pyproject.toml` earns. And where a repository tracks a `.pre-commit-config.yaml` under a payload, its `pre-commit` entry names that second directory so a hook bump reaches both copies; a repository with no payload has no such directory to name. Both differences are by design rather than by drift. Presence is still checked, so neither copy may go missing; a payload file the root deliberately dropped is excused only where `generation.features` in `.repo-template.json` records the omission, which needs `jq` and is reported `unavailable` without it; a divergence the record cannot excuse is still named on a host without `jq`. Where exactly one copy of a pair changed since `HEAD`, its finding ends with the `cp` and `git add` that mirror it, or the `git rm` that mirrors a deletion; where both or neither did, it names no direction. Reports `not-applicable` in a repository with no payload, which is every repository generated from one. Called by `scripts/check` and by pre-commit on every commit. diff --git a/apps/github-repository-template/src/base-repo/CLAUDE.md b/apps/github-repository-template/src/base-repo/CLAUDE.md index 32902418..b24646db 100644 --- a/apps/github-repository-template/src/base-repo/CLAUDE.md +++ b/apps/github-repository-template/src/base-repo/CLAUDE.md @@ -1,40 +1,51 @@ ## Template Contract -These sections are identical in every repository built from the template. Do not edit them here: a repository whose shape needs to differ has found a gap in the template, so fix it there and let the next template update (`/repo-builder`) carry it. This repository's own instructions start at Purpose. +These sections are identical in every repository built from the template. Do not edit them here: a repository whose shape needs to differ has found a gap in the template, so fix it there and let the +next template update (`/repo-builder`) carry it. This repository's own instructions start at Purpose. ### Commands Use these instead of per-language tools. `check` and `fix` run for every language present and report `pass`, `not-applicable`, `unavailable`, or `FAIL`. -- `scripts/check` — the full local gate, a superset of CI except the pull request's changelog check: doctor, structure, then lint, format, type check, test, and build with the script tests beside them, security audit, pre-commit over every file. Prints only the Result table, with the full run in `tmp/check.log`; `--verbose` streams everything; `--fast`, the commit-time gate, leaves `build` to CI and so is no superset of it +- `scripts/check` — the full local gate, a superset of CI except the pull request's changelog check: doctor, structure, then lint, format, type check, test, and build with the script tests beside + them, security audit, pre-commit over every file. Prints only the Result table, with the full run in `tmp/check.log`; `--verbose` streams everything; `--fast`, the commit-time gate, leaves `build` + to CI and so is no superset of it - `scripts/fix` — lint autofix, then formatting -- `scripts/summarize ` — run a check and print only its Result table, then a verdict line of its exit status and a count per state; read `ci` and other commands through this, since `check` already does +- `scripts/summarize ` — run a check and print only its Result table, then a verdict line of its exit status and a count per state; read `ci` and other commands through this, since + `check` already does - `scripts/run [unit] [--entry ] [-- args…]` — start a unit; the unit name is required when `apps/` holds several `ls scripts/` lists the rest, such as `doctor`, `integration`, and `package`. ### Layout -`scripts/check` fails on any of these; pre-commit runs `scripts/structure` over the placement rules on every commit. +`scripts/check` fails on any of these; pre-commit runs `scripts/structure` over the placement rules, and the line and block length of every `CLAUDE.md`, on each commit. -- Root holds only `apps/`, `docs/`, `libs/`, `scripts/`, `tests/`, `tools/`, `deploy/`, `assets/`, `config/`, `examples/`, `vendor/`, `tmp/`, the toolchain folders below, and the dot-folders `.claude/`, `.github/`, `.devcontainer/`. -- Root files are permitted by name: the shipped dotfiles, `CLAUDE.md`, `GLOSSARY.md`, `GLOSSARY-MAP.md`, `.gitmodules`, `.structure-allow`, `.repo-template.json`, adopted addons, each language's root manifests and lockfiles, and `.clang-format` and `.clang-tidy`. Any other root file or folder needs an entry in `.structure-allow`. +- Root holds only `apps/`, `docs/`, `libs/`, `scripts/`, `tests/`, `tools/`, `deploy/`, `assets/`, `config/`, `examples/`, `vendor/`, `tmp/`, the toolchain folders below, and the dot-folders + `.claude/`, `.github/`, `.devcontainer/`. +- Root files are permitted by name: the shipped dotfiles, `CLAUDE.md`, `GLOSSARY.md`, `GLOSSARY-MAP.md`, `.gitmodules`, `.structure-allow`, `.repo-template.json`, adopted addons, each language's root + manifests and lockfiles, and `.clang-format` and `.clang-tidy`. Any other root file or folder needs an entry in `.structure-allow`. - `apps//` is one unit: the smallest piece delivered on its own. Its code goes in `apps//src/`. Nothing sits directly in `apps/`. - Split a unit into domains only for distinct business areas: `apps///src/`. A unit has `src/` or domains, never both. Domains do not nest. -- A root, unit, or domain may hold its own `libs/`, `tests/`, `scripts/`, `tools/`, `assets/`, `config/`, `docs/`, `deploy/`, `examples/`, or `vendor/`, scoped to it. Outside `examples/` and `vendor/`, these never contain `src/`. -- `examples/` holds runnable programs that show how the code is used and assert nothing. `vendor/` holds third-party code kept verbatim; no lint, formatter, or test run touches it, and of the pre-commit hooks only the secret, key, large-file, and merge-conflict checks read it. A copy you patch is a fork you own, and goes in `libs/`. -- A toolchain folder is permitted only beside the file whose toolchain fixes its name, at the root, a unit, or a domain: `gradle/` beside `gradlew`, `public/` beside `package.json`. A new one is added to the template's table, never as a per-repository permission. +- A root, unit, or domain may hold its own `libs/`, `tests/`, `scripts/`, `tools/`, `assets/`, `config/`, `docs/`, `deploy/`, `examples/`, or `vendor/`, scoped to it. Outside `examples/` and + `vendor/`, these never contain `src/`. +- `examples/` holds runnable programs that show how the code is used and assert nothing. `vendor/` holds third-party code kept verbatim; no lint, formatter, or test run touches it, and of the + pre-commit hooks only the secret, key, large-file, and merge-conflict checks read it. A copy you patch is a fork you own, and goes in `libs/`. +- A toolchain folder is permitted only beside the file whose toolchain fixes its name, at the root, a unit, or a domain: `gradle/` beside `gradlew`, `public/` beside `package.json`. A new one is added + to the template's table, never as a per-repository permission. - `tools/` holds one directory per program, never loose files. - `deploy/` holds only `quadlet/`, `containerfile/`, `compose/`, `systemd/`, and `env/`. - `docs/` takes Markdown; anything else there needs `.structure-allow`. - Below a `src/`, an `examples/`, a `vendor/`, or a toolchain folder, that tree's own language or tool decides the layout. - A path ending in `/` in `.structure-allow` exempts that whole prefix, for a tracked fixture tree. -- A package whose language has no root manifest fails the gate; add the root workspace manifest (`go.work`, `settings.gradle.kts`, a `CMakeLists.txt` that reaches it through `add_subdirectory()`, and so on) that lists it. Swift is excepted: it has no root manifest. So is a `CMakeLists.txt` below a `src/` or beside another language's manifest, which belongs to that language's native build. +- A package whose language has no root manifest fails the gate; add the root workspace manifest (`go.work`, `settings.gradle.kts`, a `CMakeLists.txt` that reaches it through `add_subdirectory()`, and + so on) that lists it. Swift is excepted: it has no root manifest. So is a `CMakeLists.txt` below a `src/` or beside another language's manifest, which belongs to that language's native build. These are conventions `scripts/structure` does not check: - Root-level `libs/`, `tests/`, `scripts/`, `tools/`, `deploy/`, `assets/`, `config/`, `examples/`, and `vendor/` hold only what spans several units. -- Settings a program reads go in `config/`, with per-environment values in `deploy/env/`. Other files it reads go in `assets/`. Files it writes while running go in `apps//state/`, which is gitignored. +- Settings a program reads go in `config/`, with per-environment values in `deploy/env/`. Other files it reads go in `assets/`. Files it writes while running go in `apps//state/`, which is + gitignored. - `tests/integration/` is the integration tier, run by `scripts/integration` and left out of the gate. Every unit has a `.unit.json` at its root, never at a domain's: @@ -59,4 +70,5 @@ Every unit has a `.unit.json` at its root, never at a domain's: ## Child Index -This project is not yet indexed. Before continuing you must scan the repository, create a `CLAUDE.md` in every child folder that is a durable boundary, and replace this message with one bullet per child `CLAUDE.md` — its path, then what that file owns. Go deep and scan files recursively to properly evaluate complexity. Do not create `CLAUDE.md` files in dot folders. +This project is not yet indexed. Before continuing you must scan the repository, create a `CLAUDE.md` in every child folder that is a durable boundary, and replace this message with one bullet per +child `CLAUDE.md` — its path, then what that file owns. Go deep and scan files recursively to properly evaluate complexity. Do not create `CLAUDE.md` files in dot folders. diff --git a/apps/github-repository-template/src/base-repo/scripts/structure b/apps/github-repository-template/src/base-repo/scripts/structure index e7c15eb1..eda367f1 100755 --- a/apps/github-repository-template/src/base-repo/scripts/structure +++ b/apps/github-repository-template/src/base-repo/scripts/structure @@ -5,10 +5,13 @@ set -euo pipefail # check below carries the rule it enforces, as a literal list or a literal test. # Runs from scripts/check and from pre-commit on every commit. # -# This checks where a file sits, and reads the contents of exactly one file -- -# a unit's .unit.json, which exists because how a unit runs and what it ships -# are the two facts a tree cannot show. Three of the rules are about content -# and are reported not-applicable rather than guessed at: whether +# This checks where a file sits, and reads the contents of two kinds of file. +# A unit's .unit.json, which exists because how a unit runs and what it ships +# are two facts a tree cannot show. And every CLAUDE.md, whose physical lines +# and rendered blocks are capped so the contract stays readable rather than +# drifting into unscannable walls; a run between headings that grows long is a +# non-failing advisory, printed below the table. Three of the rules are about +# content and are reported not-applicable rather than guessed at: whether # libs/ really holds code shared across apps, whether tests/ really spans them, # and whether a file sits at the scope it belongs to. A script that inferred # those from paths would be wrong quietly, which is worse than not asking. @@ -585,6 +588,107 @@ for path in "${paths[@]}"; do done verdict docs-content "docs/ holds Markdown only" +# --- CLAUDE.md readability -------------------------------------------------- + +# A CLAUDE.md is the local work contract, read every session before editing its +# subtree, so its cost in tokens and in attention is paid over and over. These +# caps keep it scannable: no physical line past claudemd_line_max, no rendered +# block (a paragraph, or a list item -- a marker opens a new one) past +# claudemd_block_max, both measured in bytes so the audit is the same on every +# host regardless of locale. Fenced code (``` or ~~~), table rows, and a line +# that is one unbreakable token (a URL, a path) are exempt from both caps, since +# none can be rewrapped; a heading is capped like any line. A run between +# headings past claudemd_section_max is only an advisory, named in the +# claudemd-blocks row: splitting it is a judgment about meaning the audit will +# not force. +claudemd_line_max=200 +claudemd_block_max=600 +claudemd_section_max=8000 + +# Emits, per offending span: line::, block::, +# section::. Run under LC_ALL=C so length() counts bytes. The reader +# below turns each into a finding or an advisory. +# shellcheck disable=SC2016 +claudemd_program=' + function flush_block() { + if (in_block && block_sum > BLOCK) printf "block:%d:%d\n", block_start, block_sum + in_block = 0; block_sum = 0 + } + function flush_section() { + if (sec > SECTION) printf "section:%d:%d\n", sec_start, sec + sec = 0; sec_start = NR + 1 + } + BEGIN { in_fence = 0; in_block = 0; block_sum = 0; sec = 0; sec_start = 1 } + { + # A fence closes only on its own character, at least as long as the one + # that opened it, so a ``` inside a ~~~ block is content, not a close. Any + # indent is allowed, since a fence in a nested list item sits deep. + if (match($0, /^[ \t]*(`{3,}|~{3,})/)) { + run = substr($0, RSTART, RLENGTH); sub(/^[ \t]*/, "", run) + if (!in_fence) { in_fence = 1; fence_char = substr(run, 1, 1); fence_len = length(run) } + else if (substr(run, 1, 1) == fence_char && length(run) >= fence_len) in_fence = 0 + sec += length($0) + 1; flush_block(); next + } + if (in_fence) { sec += length($0) + 1; flush_block(); next } + + heading = ($0 ~ /^ {0,3}#{1,6}([ \t]|$)/) + table = ($0 ~ /^[ \t]*\|/) + blank = ($0 ~ /^[ \t]*$/) + marker = ($0 ~ /^[ \t]*([-*+]|[0-9]+\.)[ \t]+/) + + if (heading) flush_section(); else sec += length($0) + 1 + if (table) { flush_block(); next } + + content = $0 + sub(/^[ \t]*/, "", content) + sub(/^>[ \t]*/, "", content) + sub(/^([-*+]|[0-9]+\.)[ \t]+/, "", content) + breakable = (content ~ / /) + if (breakable && length($0) > LINE) printf "line:%d:%d\n", NR, length($0) + + if (heading || blank) { flush_block(); next } + size = breakable ? length($0) + 1 : 0 + if (!in_block || marker) { flush_block(); in_block = 1; block_start = NR; block_sum = size } + else block_sum += size + } + END { flush_block(); flush_section() } +' + +claudemd_files=() +for path in "${paths[@]}"; do + [[ "${path##*/}" == CLAUDE.md ]] && claudemd_files+=("$path") +done + +claudemd_line_findings=() +claudemd_block_findings=() +claudemd_sections=() +for path in ${claudemd_files[@]+"${claudemd_files[@]}"}; do + while IFS=: read -r kind lineno size; do + [[ -n "$kind" ]] || continue + case "$kind" in + line) claudemd_line_findings+=("$path:$lineno: line is $size bytes, over the ${claudemd_line_max}-byte cap; wrap it") ;; + block) claudemd_block_findings+=("$path:$lineno: block is $size bytes, over the ${claudemd_block_max}-byte cap; split it at a blank line or a heading") ;; + section) claudemd_sections+=("$path:$lineno: $size bytes to the next heading, over ${claudemd_section_max}; consider a heading to break it up") ;; + esac + done < <(LC_ALL=C awk \ + -v LINE="$claudemd_line_max" -v BLOCK="$claudemd_block_max" -v SECTION="$claudemd_section_max" \ + "$claudemd_program" "$path") +done + +if (( ${#claudemd_files[@]} == 0 )); then + result claudemd-lines not-applicable "no CLAUDE.md files" + result claudemd-blocks not-applicable "no CLAUDE.md files" +else + for finding in ${claudemd_line_findings[@]+"${claudemd_line_findings[@]}"}; do record "$finding"; done + verdict claudemd-lines "every CLAUDE.md line is within the ${claudemd_line_max}-byte cap" + for finding in ${claudemd_block_findings[@]+"${claudemd_block_findings[@]}"}; do record "$finding"; done + blocks_detail="every CLAUDE.md block is within the ${claudemd_block_max}-byte cap" + if (( ${#claudemd_sections[@]} > 0 )); then + blocks_detail+="; advisory: ${#claudemd_sections[@]} section(s) over ${claudemd_section_max} bytes; scripts/structure lists them" + fi + verdict claudemd-blocks "$blocks_detail" +fi + # --- what this cannot answer ------------------------------------------------ echo @@ -593,6 +697,11 @@ result tests-are-crossapp not-applicable "whether tests/ spans apps is a judgmen result scope-matching not-applicable "whether a file sits at its own scope is a judgment about content" echo +if (( ${#claudemd_sections[@]} > 0 )); then + echo "Advisory (not a failure): a CLAUDE.md runs long between headings." + printf ' %s\n' "${claudemd_sections[@]}" + echo +fi if (( pruned > 0 )); then echo "$pruned path(s) not descended into, per $allow_file." fi diff --git a/apps/github-repository-template/src/base-repo/scripts/tests/structure-test b/apps/github-repository-template/src/base-repo/scripts/tests/structure-test index 028b25ee..d257ecc1 100755 --- a/apps/github-repository-template/src/base-repo/scripts/tests/structure-test +++ b/apps/github-repository-template/src/base-repo/scripts/tests/structure-test @@ -585,4 +585,97 @@ else fail "expected unavailable, got: $output" fi +# --- CLAUDE.md readability -------------------------------------------------- +# +# A line over the cap, a rendered block over it, and a run between headings +# over the section cap, in both directions. Lengths are built here rather than +# written out so the fixture says what it means -- "over 200 bytes" -- instead +# of hiding the intent in a wall of lorem. A wrappable line is prose with +# spaces; an exempt one is a single token no wrap could break. +long_line="$(printf 'lorem ipsum %.0s' $(seq 1 18))" # 216 bytes, wrappable +para_line="$(printf 'lorem ipsum dolor %.0s' $(seq 1 10))" # 180 bytes, wrappable + +fixture "a CLAUDE.md line over the cap fails" +write CLAUDE.md "# Title + +$long_line" +assert_fails claudemd-lines + +# Four wrappable lines, none over the line cap, run together into one block +# over the block cap: the block rule catches what the line rule cannot. +fixture "a CLAUDE.md block over the cap fails" +write CLAUDE.md "# Title + +$para_line +$para_line +$para_line +$para_line" +assert_fails claudemd-blocks + +# Fenced code, a table row, and a bare URL each carry a line past the cap and +# none is a finding: the first two are verbatim, the last cannot be wrapped. +fixture "fenced code, table rows, and unbreakable tokens are exempt" +write CLAUDE.md "# Title + +Short prose that is fine. + +| $long_line | + +\`\`\` +$long_line +\`\`\` + +" +assert_passes + +# A ~~~ fence is code too, and a ``` inside it is content rather than its close, +# so the long line after the inner ``` is still exempt. +fixture "a tilde fence is exempt and closes only on its own character" +write CLAUDE.md "# Title + +~~~ +\`\`\` +$long_line +~~~" +assert_passes + +# A fence inside a nested list item is indented past three spaces and is +# still code, not prose. +fixture "a fence indented under a nested list item is exempt" +write CLAUDE.md "# Title + +- item + - nested + + \`\`\`bash + $long_line + \`\`\`" +assert_passes + +# A heading is capped like any line, and #331 opening a prose line is not a +# heading, so neither escapes the line cap. +fixture "a CLAUDE.md heading over the cap fails" +write CLAUDE.md "# $long_line" +assert_fails claudemd-lines + +fixture "a #-prefixed prose line is not a heading and is capped" +write CLAUDE.md "# Title + +#331 $long_line" +assert_fails claudemd-lines + +# A run between headings over the section cap is an advisory, printed below the +# table, and leaves the audit green. Every line and block here is within cap. +fixture "an over-long CLAUDE.md section is advisory, not a failure" +body="# Title" +for _ in $(seq 1 60); do body+=" + +$para_line"; done +write CLAUDE.md "$body" +if audit && grep -q 'runs long between headings' "$work/.audit-output"; then + pass +else + fail "expected a green audit with a section advisory: $(grep -iE 'fail|advisory' "$work/.audit-output" | head -1 | xargs)" +fi + report diff --git a/apps/repo-builder/CLAUDE.md b/apps/repo-builder/CLAUDE.md index a6785f81..197758f9 100644 --- a/apps/repo-builder/CLAUDE.md +++ b/apps/repo-builder/CLAUDE.md @@ -2,47 +2,296 @@ ## Purpose -Develops the `/repo-builder` skill, which builds a repository from the payload at `apps/github-repository-template/src/base-repo/` and carries later template deltas into repositories already generated from it. The skill is this repository's product, so it lives under `apps/` like any other unit; the tracked symlink at `.claude/skills/repo-builder` points at it rather than holding a second copy. +Develops the `/repo-builder` skill, which builds a repository from the payload at `apps/github-repository-template/src/base-repo/` and carries later template deltas into repositories already generated +from it. + +The skill is this repository's product, so it lives under `apps/` like any other unit; the tracked symlink at `.claude/skills/repo-builder` points at it rather than holding a second copy. ## Ownership +### Entry point and flow references + - `src/SKILL.md` — the entry point, and the only file Claude Code reads to decide the skill applies. -- `src/references/` — the flows the entry point routes to: `lifecycle.md` (read whole only by an adopt), `generate.md` with `generate-into-content.md`, `update.md`, `adopt.md`, `retrofit.md`, `wayfinding.md`, `addon-adoption.md`, and `reporting.md` at the end of any of them. `retrofit.md` is an index: it states the `lifecycle.md` rules a retrofit needs throughout inline, each with an anchor link for the reasoning, so a retrofit never opens the whole file, and names the step that reads each of the rest, states the records convention once, and links one file per step, `retrofit-step-1-preflight.md` through `retrofit-step-9-publish.md`, each read when the flow reaches it. `retrofit-unmet-bar.md` is read from step 7 only when the bar is unmet, and `retrofit-report.md` once the flow ends or stops. The reasoning behind the flow's shape is `docs/adrs/0005-stage-a-retrofit-locally-and-write-the-host-last.md`, which step files link rather than restate. `update.md` is inlined the same way: it opens with the lifecycle rules every update needs, each with an anchor link, puts each conditional rule at its triggering step, and leaves out the sections an update never reads (the first manifest's tools, hooks after a merge, ruleset satisfiability, architecture records). `generate.md` is inlined the same way, with the eight lifecycle rules a generate needs and a link to `### Working hooks in a candidate` at step 9; the rules for a destination that already has content are in `generate-into-content.md`, read from step 1 only then, and the reasoning behind the fixed steps is `docs/adrs/0010-run-generates-fixed-steps-as-commands.md`, which steps link rather than restate. A lifecycle rule a generate, a retrofit or an update newly depends on goes on that flow's list or behind an anchor link at the step that needs it, or the flow never reads it. `choosing_a_language.md` is the method wayfinding is a short path through. -- `src/scripts/preflight.py` — validates and describes a flow's inputs before it acts. Retrofit shares the git helpers and the addon manifest reader, and none of the record ones: every check in `load_provenance` reads a `.repo-template.json` a retrofit has not written yet. -- `src/scripts/retrofit.py` — runs a retrofit's fixed steps and reports each as JSON: `proofs`, `normalize`, `facts`, `references` (tracked lines naming a moved path or a script that now has a console script, read from the proofs record and each unit's `[project.scripts]`; it skips ADRs and plans at any depth, changelogs, and the proofs record's `copy.identical_paths`, and marks a basename or console-script stem several moves or units share as ambiguous with its candidates; its record keeps the `moves` it searched so a rerun after repairs still searches a move the new proofs lost, and a mention resolving to a tracked file from its own directory or unit root is no hit unless that file sits at a move's old path), `autofix`, `hooks`, `sync` (fast-forwards the operator's clone onto a taken merge where it is clean on the default branch, and deletes each `emptied` directory the pulled tree leaves untracked unless it holds a file the proofs record's residue did not name), `sweep`, `hosted read`, `hosted apply` and `resume` (merges the default branch into a standing candidate, taking the default branch's side of a conflicted lockfile), plus `report` (its Orca line read from the record `orca_icon.py` writes) and `pr-body`, which render the final report and the pull-request body from the records the others wrote, and `decide`, which records the judgements both leave as slots. Every slot is keyed in `SLOTS`, so a judgement both renderers show is decided once; `Report` takes the slot table as an argument so `generate.py` renders with its own keys; a line a record can settle renders from that record rather than becoming a slot. It writes where `preflight.py` is read-only by contract, which is why it is a second file rather than more subcommands there; it imports `preflight.py`'s git helpers rather than copying them. -- `src/scripts/update.py` — runs an update's mechanical steps and reports each as JSON: `apply` runs `update_preflight` and lands every delta path that needs no judgment, staged, at the payload's mode read from the target commit (an unmodified path, a `current` path the destination already holds at the target, an absent add, an expired override, a deletion the destination already made, a `modified` path whose status is a modification and whose three-way merge is clean, written as action `merge`, and every `.github/` path in the delta, plus `codeql.yml` unless the record omitted it by choice; `dependabot.yml` lands as the payload's file with the ecosystem entries derived from the destination's tracked manifests appended, staged), skips overridden paths except under `.github/`, whose entry it lands over, counts as discarded, and reports under `refused_overrides` with the path the entry records (a `.github/` entry outside the delta is reported there too, not under `unmatched_overrides`), and lists the rest under `left` with a reason (`conflicted` for a merge with overlapping edits, `modified` for a deletion, rename, symlink or a file `git merge-file` cannot run, `absent`, `product-owned` including a rename whose old path is product-owned, `codeql-omitted-by-choice`) for the flow to reconcile by hand; a path the ignore file excludes is written to disk and not staged. Its output is `applied` as counts by action (`write`, `merge`, `already-current`, `move`, `delete`, `already-absent`), `applied_paths` (the same actions mapped to their paths, for `report`), `removed` (each `delete`, `move` with its `old_path`, and `already-absent`, for step 6's grep), `discarded` (each `.github/` path it overwrote, deleted, or moved over destination edits or a refused override, for the loss report), `left`, `dependabot` (null unless the delta holds `dependabot.yml`; `watched` the `[ecosystem, directory]` pairs parsed from the written file, `dropped` every pair the old file watched that it lacks), `pruned` (each `apps//src/.gitkeep` or `apps///src/.gitkeep` it deleted and staged because that `src/` tracks another file, a domain being any folder but `src/`, a scoped folder, or a toolchain folder, which `NOT_DOMAINS` lists and `test_update.py` holds to `scripts/structure`; `pr-body` lists them in the blast radius and `report` under Renamed/deleted), `overridden` and `refused_overrides` as `{path, reason}`, and `unmatched_overrides`. The derivation reads the mapping and the YAML reader from the payload's `scripts/libs/dependabot.sh` at the target commit through bash and keeps no copy in Python; it reads workspace members itself, since the library has no reader for them, and a payload without the library fails the run. `proof` is the copy proof of `references/reporting.md`'s "Reviewing the pull request", stateless and run before `advance`: `identical`, `total`, and the `authored` surface, with `.repo-template.json` always authored; ignored payload paths count only where they are in the delta from the recorded commit to the target; the split itself is `copy_proof`, which takes the ignored paths from its caller so `generate.py filelist` shares it. `pr-body` renders the pull-request body from four records the flow saves beside the clone, named by appending to the destination path (`.apply.json`, `.proof.json`, `.check.txt` for the `scripts/check` table, `.settings.txt` for `scripts/repo-settings check`), and writes `.pr-body.md`: one section per `## ` heading of the destination's `.github/PULL_REQUEST_TEMPLATE.md` (its blast radius the delta without renames folded and without overridden paths), rendered from the records where they settle it, else a `[[FILL: ]]` slot (Decisions names each merged path when `left` is empty and is one otherwise), with the slot names under `slots`; a missing record fails naming it. `advance` rewrites `template.commit` textually so the file's formatting survives, refuses unless the `"commit": ""` pair occurs exactly once, revalidates the manifest, and stages it. `eligible --owner --template-repo --target [--clone ]` is the several-destinations start: it lists the owner's non-archived repositories, reads each `.repo-template.json` through `gh api` (a repository without one, a 404, is omitted; any other read failure stops it), and reports `{repository, commit, verdict}` with `current`, `eligible` (a strict ancestor of the target) or `not-ancestor`, and with `--clone` writes an empty `/pytest.ini` and clones each eligible one to `/` unless that exists, adding `cloned`. `run` is the several-destinations path: for each clone passed to `--destination`, in order, it applies (record `.apply.json`; a non-empty `left` stops it as `reconcile`), runs `npm ci` for a root `package-lock.json` (`install-failed`), installs hooks through `retrofit.py`'s `hook_types`, `prior_hooks` and `install_hooks` where `.pre-commit-config.yaml` exists, proves, advances, runs `scripts/check` (on failure, or when it cannot run, the prior manifest text is restored and staged, `check-failed` or `stopped`), runs `scripts/repo-settings check` (its `FAIL` rows are `drift` and its `unavailable` rows, or why it could not run, `settings_unavailable`, never a stop; that reason is also written to `.settings.txt` as a `settings unavailable ` row so `report` reads it), branches `repo-builder/`, commits with `--generated-by` as the `Generated-By` trailer, and renders the body, reporting `{destination, status, detail, drift, settings_unavailable}` per clone with `ready` for a finished one; a `PreflightError` or failed subprocess is `stopped`, and the next destination still runs. `publish` pushes each destination's branch and opens its pull request with `.pr-body.md`, refusing one off a `repo-builder/` branch, with nothing ahead of the origin default branch, or whose body holds a `[[FILL:` slot; it is separate from `run` so the remote gate stays the parent's, and records each result as `.publish.json`; a destination whose record already says `published` keeps it and is not pushed again. `verify` then reads each published pull request back, as step 9 of `references/update.md` describes: it waits on `gh pr checks`, and records `{destination, status, pull_request, base, head, files, template_commit, checks}` in `.verify.json`, with `not-published` for a destination whose `.publish.json` is missing or not `published`. `report` renders the Final report for several destinations from the six records beside each clone (`.apply.json`, `.proof.json`, `.check.txt`, `.settings.txt`, `.publish.json`, `.verify.json`; a missing one fails naming it) into `/report.md`, aggregating reconciliation and the authored surface by path with the destinations each applies to, and returns `{operation, path, slots}`; Preserved/Merged/Conflicted aggregates the merged paths, `none` when there are none; a line the records cannot settle (status when a destination is unverified, has no checks, or has a failing check conclusion, `left`, cleanup for an unpublished destination, pending action) is a `[[FILL: ]]` slot. It writes where `preflight.py` is read-only by contract, which is why it is a separate file; it imports `preflight.py`'s helpers rather than copying them. -- `src/scripts/generate.py` — runs a generate's mechanical steps and reports each as JSON under the retrofit records convention. `materialize` archives the payload subtree at the exact source commit into `tmp//` under the template checkout (`--template-repo`, default the working directory), runs `git init -b ` there with no remote, and records `candidate`, `commit`, `subtree`, `head` and `payload_paths`; it refuses a candidate directory that already holds files, and fails when the archive leaves out a payload path, as an `export-ignore` attribute would. `settings` reads the candidate from `.materialize.json` and sends step 5's writes through `retrofit.py`'s writers and `WriteLog`: the merge settings, Dependabot alerts and security updates, push protection, and the ruleset body `ruleset.json` beside the payload subtree, read at the materialize record's commit (`--template-repo`), recording each outcome, a 403 or 422 on push protection or the ruleset as `not offered`; only where the ruleset was created, by this run or one the write log records, does it probe, pushing an empty `commit-tree` commit on the remote tip straight to the default branch and requiring `GH013`, and an accepted push exits non-zero naming the commit. `test_generate.py` holds the ruleset's required contexts to the payload workflows' job `name:` values. `bootstrap` reads the candidate from `.materialize.json`, pushes a parentless empty-tree commit built with `commit-tree` to `origin`'s default branch, and records it as `root`; it refuses a default branch already on `origin` or one in the candidate that is not an empty root, and pushes an empty root already there, which is a push that failed. `labels` creates the sixteen triage roles (respelled by the candidate manifest's `generation.features.triage_labels`, which also turns case-variant renames off) and the five `wayfinder:` labels through `retrofit.py`'s `write_labels` and `WriteLog`, recording `created`, `renamed`, `existing` and `kept`, and fails on a refused write. `hooks --tree ` installs the candidate's hooks through `retrofit.py`'s `hook_types`, `prior_hooks` and `install_hooks` into its own `.git/hooks` at local scope, records `not-applicable` without a `.pre-commit-config.yaml`, and exits 1 unless every configured type resolves where git will consult it. `filelist --tree --commit ` reads the subtree and `generation.applications` from the candidate's `.repo-template.json`, maps the payload's `apps/app-name/` onto the first application, and records `missing`, `additions` and `strays` (the allowed candidate-only set is `.repo-template.json`, `docs/adrs/NNNN-*.md`, `docs/adrs/index.md`, every later application, and `.scratch/` where `generation.features.issue_tracker` is recorded), `ignored_present`, `ignored_tracked` (from `git check-ignore --no-index`), and `copy` from `update.py`'s `copy_proof`; it exits 1 on a missing path, a stray or an ignored-but-tracked path. A step that ran and found defects writes its record with `ok` false and exits 1; a refusal writes none and exits 2. `manifest` writes the candidate's `.repo-template.json` from `apps/github-repository-template/src/ownership.json` at the source commit, `--application` and `--feature` (`triage_labels.=