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
175 changes: 129 additions & 46 deletions CLAUDE.md

Large diffs are not rendered by default.

138 changes: 115 additions & 23 deletions apps/github-repository-template/CLAUDE.md

Large diffs are not rendered by default.

Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
36 changes: 24 additions & 12 deletions apps/github-repository-template/src/base-repo/CLAUDE.md
Original file line number Diff line number Diff line change
@@ -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 <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/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`.

### 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/<unit>/` is one unit: the smallest piece delivered on its own. Its code goes in `apps/<unit>/src/`. Nothing sits directly in `apps/`.
- Split a unit into domains only for distinct business areas: `apps/<unit>/<domain>/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/<unit>/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/<unit>/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:
Expand All @@ -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.
117 changes: 113 additions & 4 deletions apps/github-repository-template/src/base-repo/scripts/structure
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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:<n>:<bytes>, block:<n>:<bytes>,
# section:<n>:<bytes>. 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
Expand All @@ -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
Expand Down
Loading