Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .commitlintrc.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,11 @@
# third is this repository's own. Everything else -- type-enum, subject-case,
# header-max-length, body-max-line-length -- is the stock preset, at error
# level already.
#
# There is no `ignores` list: commitlint's entries are functions, which YAML
# cannot hold. The default ignore list already passes GitHub's and git's own
# merge subjects, so a hand-written merge commit uses one of those shapes,
# `Merge <what> into <branch>`, rather than a `Merge #12: title` this refuses.
extends:
- "@commitlint/config-conventional"

Expand Down
9 changes: 9 additions & 0 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -194,6 +194,15 @@ repos:
language: script
stages: [prepare-commit-msg]

# The other half of the pair: refuses a Generated-By that is missing or
# is not a model ID, with the line to write. A reader at commit-msg, so
# its order against commitlint does not matter.
- id: attribution-check
name: check the Generated-By trailer names a model ID
entry: scripts/attribute-commit --check
language: script
stages: [commit-msg]

# These hooks let Git remove only stale administrative records for linked
# worktrees whose directories have already disappeared. They never remove
# a live worktree directory, and SessionStart reports candidates without
Expand Down
8 changes: 4 additions & 4 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,13 +34,13 @@ Use these instead of per-language tools; each detects the languages present and
- `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`, the script tests, lint, format, type check, test, build, 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. 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 <command…>` — run a check and print only its Result table with findings, exiting with that command's status; read `ci` and other commands through this, since `check` already does
- `scripts/summarize <command…>` — 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 <name>] [-- 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. The shellcheck hook skips the payload's `scripts/` on the strength of it
- `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.

Expand All @@ -57,8 +57,8 @@ The only non-shell code here is the Python under `apps/repo-builder/`, declared
- 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: <model>` trailer, required by `trailer-exists` in `.commitlintrc.yaml`. `scripts/attribute-commit` writes it at `prepare-commit-msg`: it inserts `Generated-By: <model ID>` 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/<session id>/`, 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 rewrites a stray `Co-Authored-By: <model> <noreply@anthropic.com>`, 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`.
- GitHub's generated merge subjects are on commitlint's default ignore list and need no CI check.
- Every commit carries a `Generated-By: <model>` trailer, required by `trailer-exists` in `.commitlintrc.yaml`. `scripts/attribute-commit` writes it at `prepare-commit-msg`: it inserts `Generated-By: <model ID>` 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/<session id>/`, 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: <model> <noreply@anthropic.com>` 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 <what> into <branch>`; `.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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ The specific operating parameters for the AI agent.

`scripts/check`: The full local gate. By default it prints only the Result table and the findings under any check that failed, by running itself under `scripts/summarize`, and it writes the complete run to `tmp/check.log` every time, passing or failing, since a pre-commit fixer repairs the file and a re-run no longer reproduces the failure. `--verbose` streams the whole run live, still writing the log. Exits with the gate's status either way.

`scripts/summarize`: Runs a check command and prints only its Result table — one line per check, the findings under any that failed — dropping every other thing the command wrote. Exits with that command's status, so it can stand in for the command rather than only report on it. `scripts/check` is its first caller; it stays the way to read `scripts/ci` and any other command. It is the one consumer of the printed layout `scripts/libs/result.sh` documents, which is where a change to the column widths has to be reflected.
`scripts/summarize`: Runs a check command and prints only its Result table — one line per check, the findings under any that failed — dropping every other thing the command wrote. Exits with that command's status, so it can stand in for the command rather than only report on it, and ends with a verdict line naming that status and a count per state. `scripts/check` is its first caller; it stays the way to read `scripts/ci` and any other command. It is the one consumer of the printed layout `scripts/libs/result.sh` documents, which is where a change to the column widths has to be reflected.

`scripts/run`: Starts a unit, dispatching on the `run` fact its `.unit.json` declares — a one-shot runs the program's own entry point, a long-lived one runs the dev server, `none` exits saying there is nothing to run. Names the unit when `apps/` holds several, since a run is one foreground process; `--entry <name>` names one of the programs the unit's own language manifest declares, required for the same reason when it declares several; everything after `--` reaches the program unchanged.

Expand All @@ -95,7 +95,7 @@ The specific operating parameters for the AI agent.

`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/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`. 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.
`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.

`.structure-allow`: Convention (not a shipped file) for the permission the Layout rules refer to — one path per line to allow a named exception, a trailing `/` to stop the audit descending into a tracked fixture tree, save for one lookup that keeps a prefix over a domain's `src/` from failing the domain it defines. Absent until a repository needs one.

Expand Down Expand Up @@ -137,7 +137,7 @@ Toolchain folders: `scripts/structure`'s `toolchain_folders` pairs a file with t

`.pre-commit-config.yaml`: Local checks that run automatically before a commit.

`.commitlintrc.yaml`: Commit message rules (Conventional Commits), plus a required `Generated-By:` trailer naming the model that wrote the commit. `scripts/attribute-commit` writes that trailer at `prepare-commit-msg` from `CLAUDE_COMMIT_MODEL`, the model ID an agent's user-level hook exports, or else from the entry that hook writes under `${XDG_CACHE_HOME:-~/.cache}/claude-commit-model/<session id>/` naming the exact command running, or by rewriting an agent's `Co-Authored-By` line; the rule is what makes a commit fail when the hook is not installed rather than land unattributed, and a commit written by hand adds the trailer itself or is refused.
`.commitlintrc.yaml`: Commit message rules (Conventional Commits), plus a required `Generated-By:` trailer naming the model that wrote the commit. `scripts/attribute-commit` writes that trailer at `prepare-commit-msg` from `CLAUDE_COMMIT_MODEL`, the model ID an agent's user-level hook exports, or else from the entry that hook writes under `${XDG_CACHE_HOME:-~/.cache}/claude-commit-model/<session id>/` naming the exact command running, or by rewriting an agent's `Co-Authored-By` line; the rule is what makes a commit fail when the hook is not installed rather than land unattributed, and a commit written by hand adds the trailer itself or is refused. `attribute-commit --check` at `commit-msg` refuses a trailer value that is not a model ID, such as a display name.

### Additions by Occasion

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,11 @@
# third is this repository's own. Everything else -- type-enum, subject-case,
# header-max-length, body-max-line-length -- is the stock preset, at error
# level already.
#
# There is no `ignores` list: commitlint's entries are functions, which YAML
# cannot hold. The default ignore list already passes GitHub's and git's own
# merge subjects, so a hand-written merge commit uses one of those shapes,
# `Merge <what> into <branch>`, rather than a `Merge #12: title` this refuses.
extends:
- "@commitlint/config-conventional"

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,15 @@ repos:
language: script
stages: [prepare-commit-msg]

# The other half of the pair: refuses a Generated-By that is missing or
# is not a model ID, with the line to write. A reader at commit-msg, so
# its order against commitlint does not matter.
- id: attribution-check
name: check the Generated-By trailer names a model ID
entry: scripts/attribute-commit --check
language: script
stages: [commit-msg]

# These hooks let Git remove only stale administrative records for linked
# worktrees whose directories have already disappeared. They never remove
# a live worktree directory, and SessionStart reports candidates without
Expand Down
2 changes: 1 addition & 1 deletion apps/github-repository-template/src/base-repo/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Use these instead of per-language tools. `check` and `fix` run for every languag

- `scripts/check` — the full local gate, a superset of CI except the pull request's changelog check: doctor, script tests, structure, lint, format, type check, test, build, security audit, pre-commit over every file. Prints only the Result table, with the full run in `tmp/check.log`; `--verbose` streams everything
- `scripts/fix` — lint autofix, then formatting
- `scripts/summarize <command…>` — run a check and print only its Result table; read `ci` and other commands through this, since `check` already does
- `scripts/summarize <command…>` — 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 <name>] [-- args…]` — start a unit; the unit name is required when `apps/` holds several

`ls scripts/` lists the rest, such as `doctor`, `integration`, and `package`.
Expand Down
Loading
Loading