From 697f5774a5cb052364878cacaf74968e8456e7d0 Mon Sep 17 00:00:00 2001 From: Adam Clemens Date: Tue, 8 Sep 2026 13:22:11 +0100 Subject: [PATCH] Fold Insights follow-ups into CLAUDE.md, add make preflight and /ship Adds four process rules from the 2026-09-08 Claude Code Insights report to root CLAUDE.md: a Feature Verification section (run the real command before calling a user-facing feature done), a Tooling Gotchas section (the formatter hook stripping unused-looking imports, Git Bash mangling heredocs), and a Documentation Blast Radius subsection under Documentation. The proposed "Branch & PR Workflow" section overlapped almost entirely with the same-day Branch Discipline section, so its content (the CLAUDE.md-only-edit exception, the PR/merge/cleanup steps, the make-preflight-before-commit requirement) was folded into Branch Discipline instead of duplicating it under a second heading. Adds `make preflight`: docs/inventory regeneration, the link checker, the two structural-consistency checks fast enough for a local gate (check-manifest, check-references), lint, typecheck, and the test suite -- a faster pre-commit gate than full `make ci`, which it does not replace. Adds `.claude/skills/ship/SKILL.md`, a checklist for the branch -> TDD -> blast-radius -> preflight -> ci -> PR -> merge loop that every numbered step cites back to the CLAUDE.md section it restates. Blast radius: creating `.claude/skills/` and `.claude/skills/ship/` brought the tracked CLAUDE.md count from 47 to 49, which required updating docs/planning/roadmap.md's TASK-009 row and regenerating docs/repository-inventory.md and docs/planning/status.md. While fixing that count, found and corrected two pre-existing drifts: docs/ repository-manifest.md's own copy of the same count had been stale at 45 since 2026-08-23 (two updates behind roadmap.md), and the roadmap's "N carry real content" arithmetic no longer matched its own total (44 implied, 42 stated). Both corrected in this change. make ci: 1142 passed, 21 skipped, 99% coverage; all structural checks (check-graph, check-manifest, check-references, check-scenarios, check-stages, check-documents, check-status, check-dates, check-benchmark-report) green. Co-Authored-By: Claude Sonnet 5 --- .claude/CLAUDE.md | 7 ++- .claude/skills/CLAUDE.md | 22 ++++++++ .claude/skills/ship/CLAUDE.md | 13 +++++ .claude/skills/ship/SKILL.md | 77 +++++++++++++++++++++++++ CLAUDE.md | 102 ++++++++++++++++++++++++++++++++++ Makefile | 29 +++++++++- docs/planning/roadmap.md | 2 +- docs/planning/status.md | 2 +- docs/repository-inventory.md | 11 +++- docs/repository-manifest.md | 84 +++++++++++++++++----------- 10 files changed, 309 insertions(+), 40 deletions(-) create mode 100644 .claude/skills/CLAUDE.md create mode 100644 .claude/skills/ship/CLAUDE.md create mode 100644 .claude/skills/ship/SKILL.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index ce3ab39..a6d9825 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -1,9 +1,10 @@ # CLAUDE Claude Code's own configuration for this repository: `settings.json` -(hook wiring) and `hooks/` (the hook scripts themselves -- see -`hooks/CLAUDE.md`). Tracked in Git so the configuration travels with the -repository rather than living only on one machine. +(hook wiring), `hooks/` (the hook scripts themselves -- see +`hooks/CLAUDE.md`), and `skills/` (reusable, user-invoked workflow +prompts -- see `skills/CLAUDE.md`). Tracked in Git so the configuration +travels with the repository rather than living only on one machine. Found undocumented and unrecorded in either `docs/repository-manifest.md` or `docs/planning/knowledge-architecture.md` during the 2026-08-19 F2 diff --git a/.claude/skills/CLAUDE.md b/.claude/skills/CLAUDE.md new file mode 100644 index 0000000..c4ce133 --- /dev/null +++ b/.claude/skills/CLAUDE.md @@ -0,0 +1,22 @@ +# CLAUDE + +Claude Code skills for this repository: reusable, user-invoked (`/`) +prompt files that encode a workflow already documented elsewhere in the +repository, so it doesn't have to be re-described by hand each time it's +run. One subdirectory per skill, each `/SKILL.md`. + +- `ship/` -- the branch/TDD/blast-radius/preflight/CI/PR/merge sequence + from root `CLAUDE.md`'s Branch Discipline and Merge Gate sections. See + its own `CLAUDE.md`. + +A skill here is a checklist referencing the repository's actual rules, +never a second copy of them -- if a skill's steps and the `CLAUDE.md` +section they cite disagree, the `CLAUDE.md` section wins, and the skill +gets fixed in the same change (the same restated-fact discipline +`docs/CLAUDE.md` asks of every generated document, applied here to a +hand-written one instead, since a skill's steps cannot be generated from +the rules they summarise). + +Added 2026-09-08, alongside `ship/`, following the same "real content +first, `CLAUDE.md` and manifest entry in the same change" pattern +`tools/CLAUDE.md` already states for a new subdirectory. diff --git a/.claude/skills/ship/CLAUDE.md b/.claude/skills/ship/CLAUDE.md new file mode 100644 index 0000000..db05865 --- /dev/null +++ b/.claude/skills/ship/CLAUDE.md @@ -0,0 +1,13 @@ +# CLAUDE + +`SKILL.md` -- the `/ship` skill: branch, TDD-first implementation, Blast +Radius doc propagation, `make preflight`, `make ci`, PR, and merge, in +that order. Every numbered step cites the root `CLAUDE.md` section it +restates rather than stating the rule independently, so the two cannot +quietly diverge -- see `../CLAUDE.md` for why that matters here +specifically. + +Added 2026-09-08, at a user's direct request to stop re-describing the +same delivery loop by hand each session. Update this skill in the same +change as any of the root `CLAUDE.md` sections it cites, if that change +alters what the step actually requires. diff --git a/.claude/skills/ship/SKILL.md b/.claude/skills/ship/SKILL.md new file mode 100644 index 0000000..7bc5aef --- /dev/null +++ b/.claude/skills/ship/SKILL.md @@ -0,0 +1,77 @@ +--- +name: ship +description: Branch, implement TDD-first, propagate documentation, run the local gate, open a PR, watch CI, and merge -- the standard PyFlow delivery loop from root CLAUDE.md. +--- + +# Ship + +This skill is a checklist, not new policy -- every step below restates a +rule that already lives in root `CLAUDE.md` or `docs/practices.md`. It +exists so the same sequence doesn't have to be re-described by hand each +time. If this file and one of those disagree, the other document wins; +fix this file in the same change. + +1. **Branch before the first edit** (CLAUDE.md, Branch Discipline). + `git checkout main && git pull`, then create + `/` (`docs/practices.md`): `feat/` for + a roadmap task, `fix/` for a defect, `docs/` for documentation/ + planning/process only. One branch per task -- don't fold an unrelated + second task onto a branch already in flight. + +2. **Write the failing test first, then implement** (root CLAUDE.md, + Acceptance Criteria section; `docs/practices.md`'s TDD examples + throughout the roadmap). The test must assert intent -- the physical + or behavioural meaning a reader would check -- not an implementation + detail that would still pass under a wrong implementation. + +3. **Implement until it's green**, re-reading any file where an import + was added before running tests against it -- the post-edit format + hook strips an import that has no usage yet in the same edit + (CLAUDE.md, Tooling Gotchas / Formatter Hook Interaction). + +4. **Propagate the Blast Radius in the same change** (CLAUDE.md, Blast + Radius; Documentation Blast Radius). Grep for the name of whatever + changed and update every restatement: `README.md`, the relevant + handbook/manifest entry, the roadmap/backlog status line, the + `CHANGELOG`/`docs/CHANGELOG-DESIGN.md` where a decision was made, and + every `CLAUDE.md` that names the thing. If something in the radius + can't be updated now, say so explicitly in the PR description rather + than leaving an unrecorded gap. + +5. **Before calling a user-facing feature done, run it** (CLAUDE.md, + Feature Verification Before Reporting Done). The exact command a user + would run, not the test suite standing in for it -- `pyflow run`, + `make graph`, whatever the feature's own entry point is. Confirm any + new CLI flag actually appears in `--help`. Then re-read the diff as a + hostile auditor and list anything overstated, defaulted off, or + unreachable. + +6. **Run `make preflight`** (CLAUDE.md, Branch Discipline / Development + Commands) before the first commit on the branch, and again before + opening the PR. It regenerates the generated docs, then runs the link + checker, the fast structural-consistency checks, lint, typecheck, and + the test suite, failing at the first error. + +7. **Commit.** No heredocs for the message -- write it with the Write + tool to a scratch file and use `git commit -F ` (CLAUDE.md, + Tooling Gotchas / Shell Usage). State what changed and why, not what + the diff already shows. + +8. **Run `make ci` in full before merge** (CLAUDE.md, Merge Gate + criterion 1) -- `make preflight` is not a substitute. Push, open the + PR (`gh pr create`), and watch the real CI run on both platforms + (`gh pr checks --watch`) rather than assuming local green transfers. + +9. **Before merging, re-check Merge Gate criteria 2-4**: every + restatement of every changed fact is updated in this branch, every + acceptance criterion is checked by something that would fail if the + intent were violated, and anything left unverified is said so + explicitly rather than implied by silence. + +10. **Merge, delete the branch, return to `main`** before starting the + next task (CLAUDE.md, Branch Discipline). + +**Exception**: a trivial single-file edit to a `CLAUDE.md` or other +process-rule file may skip straight to a direct commit on `main`, but +only when the user explicitly says so in that turn (CLAUDE.md, Branch +Discipline). Everything else follows the full sequence above. diff --git a/CLAUDE.md b/CLAUDE.md index c162ecd..432ae56 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -108,6 +108,26 @@ easiest to implement -- also `docs/practices.md`. --- +# Feature Verification Before Reporting Done + +Before reporting a user-facing feature as done, run the exact command a +user would run -- `pyflow run`, `make graph`, whatever the feature's own +entry point is -- and describe the real output or the actual rendered +window, not the expected one. Confirm every new CLI flag actually +appears in `--help`. + +Then re-read the diff as a hostile auditor, not as its author: list +anything overstated, defaulted off, or unreachable before calling the +work finished. + +Added 2026-09-08, maintainer's instruction, after a HUD that shipped +defaulted off and a `--demos` flag that was never wired into the CLI +both passed review because neither was ever actually run. This is the +concrete form Merge Gate criterion 3 ("the intent is met") takes for +anything a person looks at or types. + +--- + # Branch Discipline **All coding work happens on a branch, never directly on `main`.** @@ -120,6 +140,20 @@ makes both apply every time rather than only when someone remembers to branch first. `main` only receives commits by merge, once the Merge Gate above is satisfied. +The one exception: a trivial single-file edit to a `CLAUDE.md` or other +process-rule file may be committed directly to `main` when the user +explicitly says so in the same turn -- it does not need its own +branch/PR. Everything else follows the full cycle: open a PR, watch CI +to green, merge, delete the branch, and return to `main` before starting +the next task. `make preflight` (Development Commands, below) must pass +locally before any commit made on a branch; it is a fast local gate, not +a substitute for `make ci` in full, which the Merge Gate above still +requires before merge. + +Added 2026-09-08, later the same day as the standing rule above, after +noticing this section said "never directly on main" without saying what +to do once a branch exists. + --- # Acceptance Criteria for Simulation Work @@ -431,6 +465,20 @@ prevent (P-011, single authoritative source). - `make clean` -- remove what `make install` created; states on its own output what it deliberately leaves alone (the `uv` binary, the shared interpreter, `uv`'s package cache) rather than restated here. +- `make preflight` -- a fast local pre-commit gate, added 2026-09-08: + regenerates `docs/index.md` and `docs/repository-inventory.md`, then + runs the link checker, the two cheapest structural-consistency checks + (`check-manifest`, `check-references`), lint, typecheck, and the test + suite, in that order, stopping at the first failure. Unlike `make ci` + it regenerates before checking, so a merely-stale generated doc heals + itself instead of failing outright. Deliberately narrower than `make + ci` -- it skips `check-graph`, `check-scenarios`, `check-stages`, + `check-documents`, `check-status`, `check-config-template`, + `check-dates` and `check-benchmark-report`, none of which are cheap + enough to justify running on every commit -- so a green `make + preflight` is a reason to commit, not a reason to skip `make ci` + before merge. See the Branch Discipline section above for when it's + required. Full detail, including what each target's acceptance criteria are and why the project settled on `uv`+`make`: `README.md`'s Quick Start @@ -438,6 +486,42 @@ section and `docs/planning/backlog.md` A1a/A1b/B2/B3. --- +# Tooling Gotchas + +Environment-specific failure modes worth knowing before they cost a +retry cycle. Neither of these is a PyFlow behaviour -- both are the +local development environment fighting back -- but both have cost real +time more than once, which is the bar the rest of this file uses for +writing something down. + +## Formatter Hook Interaction + +The repository's `PostToolUse` hook (`.claude/hooks/post_edit_format.py`) +runs `ruff --fix`/`ruff format` on every file an Edit/Write call +touches, and `ruff --fix` removes an import it believes is unused. Add a +new import and its first usage in the *same* edit, never the import +alone -- an import added ahead of the code that uses it reads as unused +to the hook and gets silently stripped before the follow-up edit lands. +After any edit that touches imports, re-read the file to confirm the +import survived before running tests against it. + +## Shell Usage (Git Bash) + +Do not use heredocs for multi-line file content or commit messages on +this platform -- Git Bash's line-ending handling has mangled heredoc +writes into CRLF-corrupted or duplicated content before. Use the Write +tool for file content, and `git commit -F ` (a file written by the +Write tool) for a long commit message instead of `git commit -m` with an +inline heredoc. Never reorder sections of a file with `sed` or index +arithmetic -- a botched reorder has duplicated thousands of lines of a +planning document in a single command before; use targeted `Edit` calls +instead. + +Added 2026-09-08, maintainer's instruction, after both failure modes had +each recurred across several sessions. + +--- + # Documentation Documentation is treated as part of the implementation. @@ -448,6 +532,24 @@ Generated documentation must never be edited manually. Follow `docs/documentation-guidelines.md`. +## Documentation Blast Radius + +Any change to behaviour, a CLI flag, or help text propagates in the same +commit to every place that restates it: `README.md`, the relevant +handbook or manifest entry, the roadmap/backlog status line, and every +`CLAUDE.md` that names the thing being changed. This is the Blast Radius +rule (above) applied specifically to documentation, because that is +where it has been missed most often -- run `make check-manifest`, +`make check-references` and `make check-docs` before committing (also +folded into `make preflight`, above), not only at full `make ci` time. + +Never state a relative timeframe ("months ago", "recently", "a while +back"). Use a commit date, an explicit `YYYY-MM-DD`, or omit the claim +-- `git log` and a PR's actual merge time are the source of truth; a +session's own sense of elapsed time is not, and has been wrong before. + +Added 2026-09-08, maintainer's instruction. + --- # Engineering Principles diff --git a/Makefile b/Makefile index 3e3fc41..b9e820b 100644 --- a/Makefile +++ b/Makefile @@ -3,7 +3,7 @@ check-manifest check-references check-scenarios check-stages check-documents \ check-claims check-dates status-report \ check-status config-template check-config-template docs graph demo benchmark \ - benchmark-report check-benchmark-report record-benchmarks ci clean + benchmark-report check-benchmark-report record-benchmarks ci preflight clean install: uv sync @@ -138,6 +138,33 @@ check-manifest: ci: lint typecheck test check-docs check-docs-index check-graph check-dependency-tree check-inventory check-manifest check-references check-scenarios check-stages check-documents check-status check-config-template check-dates check-benchmark-report +# Fast local pre-commit gate (root CLAUDE.md, Branch Discipline section; +# added 2026-09-08). Not a substitute for `make ci` above -- it skips +# check-graph, check-scenarios, check-stages, check-documents, +# check-status, check-config-template, check-dates and +# check-benchmark-report, none of which are cheap enough to run on every +# commit -- but it catches the failures that show up most often before +# they reach CI: a stale generated doc, a broken relative link, a +# tracked file missing from the manifest, a path named in prose that +# doesn't resolve, a lint/type error, or a broken test. +# +# `docs`/`inventory` regenerate rather than check -- unlike `ci`, a +# merely-stale generated doc heals itself here instead of failing +# outright, since the point of a local gate is to fix what it can before +# a human looks at the diff. +# +# No single script in this repository is named "the self-consistency +# validator" -- `check-manifest` (every tracked file is named somewhere) +# and `check-references` (every path named in prose resolves) are the +# two structural-consistency checks fast enough to belong in a local +# gate; `check-graph` covers a third kind (the planning knowledge graph) +# and stays in full `make ci` only, since ordinary commits don't usually +# touch it. +# +# Runs in the order listed, stopping at the first failure, same as `ci` +# above. +preflight: docs inventory check-docs check-manifest check-references lint typecheck test + # Fails if prose names a repository path that does not exist. Gating: # every rule is a definite structural fact (does this path resolve), # with the judgement-shaped cases excluded by document rather than by a diff --git a/docs/planning/roadmap.md b/docs/planning/roadmap.md index 2dfcf25..5daac27 100644 --- a/docs/planning/roadmap.md +++ b/docs/planning/roadmap.md @@ -299,7 +299,7 @@ TASK-000..010 rows below reading **Done**. | TASK-006 Logging Framework | **Done** 2026-08-16 -- stdlib `logging`, centralised on the `pyflow` logger; every subsystem gets its logger via `get_logger(__name__)` and inherits level/formatting through the hierarchy | | TASK-007 Rendering Framework | **Done** 2026-08-16 -- wgpu/pygfx (`adr/ADR-005`) window creation, render loop, clean shutdown; canvas backend (glfw interactive / offscreen headless) selected via configuration, both behind one interface (`src/pyflow/rendering/canvas.py`) | | TASK-008 Repository Documentation | **Done** -- this row previously read "Partial -- core documents drafted; the Handbook is largely empty", stale since 2026-08-17 when all sixteen Handbook entries (E3/E4) were written; corrected 2026-08-19. All nine artifacts TASK-008 names (README, Handbook, ADRs, Capability Map, Implementation Plan, Engineering Principles, Documentation Guidelines, Practices, Dreams) exist with real content, verified directly by line count, not assumed | -| TASK-009 CLAUDE.md Hierarchy | **Done** 2026-08-19, count kept current since -- 47 files exist as of 2026-09-06 (up from 46 as of 2026-08-29: `tools/benchmarks/CLAUDE.md` joined the same change as `tools/benchmarks/benchmark_demos.py`, real content from the day it was created, the same discipline this row exists to model; 46 itself up from 45 as of 2026-08-23: `tests/fixtures/CLAUDE.md` joined with TASK-034, real content from the day it was created, the same "one file added, count updated in the same change" discipline this row exists to model; 45 itself up from 42 as of 2026-08-22: `tests/features/CLAUDE.md` joined the same day as ADR-007, missed by that day's own consistency sweep; `src/pyflow/engine/numerics/CLAUDE.md` and `tests/unit/numerics/CLAUDE.md` joined with TASK-018, 2026-08-23 -- all three real content, found and fixed while drafting TASK-018, the same "count restated in three places, one file added, count not touched" failure this row exists to warn about. 42 itself up from 40: F2 found `.claude/` and `.claude/hooks/` had no `CLAUDE.md` at all and were untracked by both inventories, fixed with real content, not placeholders; 40 itself down from 43: `assets/icons/`, `assets/shaders/`, `assets/textures/` retired 2026-08-19, E9, no document anywhere having ever stated what they were for, the same test that retired `tools/planner/`/`tools/scripts/`, 2026-08-17, E10; 43 itself down from 45 for that earlier retirement); **3** are still generic placeholders as of 2026-09-04 (down from 4: `examples/experiments/` gained real content that day, `smoke_transport_high_res.yaml`), 42 carry real content. E9's *Done when* was revised the same day it closed: no placeholder may remain in a directory that has content, not no placeholder anywhere -- all 3 remaining (`docs/tutorials/`, `examples/tutorials/`, `tests/performance/`) sit in directories with no real content yet, verified directly. `docs/planning/backlog.md` E9/F2 hold the file-by-file breakdown and are the authoritative count | +| TASK-009 CLAUDE.md Hierarchy | **Done** 2026-08-19, count kept current since -- 49 files exist as of 2026-09-08 (up from 47 as of 2026-09-06: `.claude/skills/CLAUDE.md` and `.claude/skills/ship/CLAUDE.md` joined with `.claude/skills/ship/SKILL.md`, the new `/ship` skill, real content from the day the directory was created, the same discipline this row exists to model. **`docs/repository-manifest.md`'s own restatement of this count had drifted to 45 (dated 2026-08-23) while this row kept being updated to 46 and then 47** -- found and fixed in the same change that added these two files, the identical "count restated in three places, one restatement not touched" failure this row already exists to warn about, this time on the manifest's side rather than this one's. 47 itself up from 46 as of 2026-08-29: `tools/benchmarks/CLAUDE.md` joined the same change as `tools/benchmarks/benchmark_demos.py`, real content from the day it was created; 46 itself up from 45 as of 2026-08-23: `tests/fixtures/CLAUDE.md` joined with TASK-034, real content from the day it was created; 45 itself up from 42 as of 2026-08-22: `tests/features/CLAUDE.md` joined the same day as ADR-007, missed by that day's own consistency sweep; `src/pyflow/engine/numerics/CLAUDE.md` and `tests/unit/numerics/CLAUDE.md` joined with TASK-018, 2026-08-23 -- all three real content, found and fixed while drafting TASK-018, the same "count restated in three places, one file added, count not touched" failure this row exists to warn about. 42 itself up from 40: F2 found `.claude/` and `.claude/hooks/` had no `CLAUDE.md` at all and were untracked by both inventories, fixed with real content, not placeholders; 40 itself down from 43: `assets/icons/`, `assets/shaders/`, `assets/textures/` retired 2026-08-19, E9, no document anywhere having ever stated what they were for, the same test that retired `tools/planner/`/`tools/scripts/`, 2026-08-17, E10; 43 itself down from 45 for that earlier retirement); **3** are still generic placeholders as of 2026-09-04 (down from 4: `examples/experiments/` gained real content that day, `smoke_transport_high_res.yaml`), 46 carry real content -- corrected from this row's own previous "42", which no longer matched even the total it sat beside (47 total minus 3 placeholders is 44, not 42; found while making this same edit). E9's *Done when* was revised the same day it closed: no placeholder may remain in a directory that has content, not no placeholder anywhere -- all 3 remaining (`docs/tutorials/`, `examples/tutorials/`, `tests/performance/`) sit in directories with no real content yet, verified directly. `docs/planning/backlog.md` E9's file-by-file breakdown is a record of its own 2026-08-19 closure, not a running total past that point; this row and `docs/repository-manifest.md`'s "CLAUDE.md files" section are the two that track the live count, so update both together | | TASK-010 Engine Bootstrap | **Done** 2026-08-16 -- `pyflow run` loads configuration, initialises logging, opens the render window, runs the loop, exits cleanly; verified with both the offscreen backend (automated, `tests/integration/test_bootstrap.py`) and the real interactive glfw backend (manual run, a real window opened and closed cleanly). `make ci`'s pass is what TASK-010 means by "the CI pipeline passes" here, per the C2 scope decision above -- not a claim that GitHub Actions itself has run it | This paragraph previously said `make install` and `make test` were still diff --git a/docs/planning/status.md b/docs/planning/status.md index 38ad29b..0632677 100644 --- a/docs/planning/status.md +++ b/docs/planning/status.md @@ -45,7 +45,7 @@ pie showData ## Live repository facts -- **47** `CLAUDE.md` files +- **49** `CLAUDE.md` files - **1163** tests collected - **144** Gherkin scenarios (`tests/features/*.feature`) diff --git a/docs/repository-inventory.md b/docs/repository-inventory.md index 80ad20c..1ee7396 100644 --- a/docs/repository-inventory.md +++ b/docs/repository-inventory.md @@ -16,7 +16,7 @@ reading job and lives in the manifest. Test counts and coverage are not here either -- those come from running the suite, not from listing files. -**358 tracked files** across 47 directories; +**361 tracked files** across 49 directories; 2 are empty. ## (root) @@ -44,6 +44,15 @@ listing files. - `post_edit_format.py` - `ruff.toml` +## .claude/skills + +- `CLAUDE.md` + +## .claude/skills/ship + +- `CLAUDE.md` +- `SKILL.md` + ## .github - `CLAUDE.md` diff --git a/docs/repository-manifest.md b/docs/repository-manifest.md index 8d6ef80..dfe6e9e 100644 --- a/docs/repository-manifest.md +++ b/docs/repository-manifest.md @@ -1242,6 +1242,27 @@ and `assets/`. --- +# .claude/skills/ + +`.claude/skills/ship/SKILL.md` (added 2026-09-08, at a user's direct +request): a reusable, user-invoked (`/ship`) checklist for the standard +PyFlow delivery loop -- branch, TDD-first implementation, Blast Radius +doc propagation, `make preflight`, `make ci`, PR, merge. Every step cites +the root `CLAUDE.md` section it restates rather than stating the rule +independently, the same "generate, don't restate" discipline +`docs/CLAUDE.md` states for generated documents, applied here by hand +since a skill's steps cannot literally be generated from the prose rules +they summarise. 🟩 -- real content from the day the directory was +created, not a placeholder, following the same pattern +`tools/CLAUDE.md` already states for a new subdirectory. + +Added in the same change as this manifest row: `.claude/skills/CLAUDE.md` +and `.claude/skills/ship/CLAUDE.md`, per KA-038's "every directory has a +CLAUDE.md" -- both counted in the "CLAUDE.md files" collective total +below. + +--- + # .github/ `.github/workflows/ci.yml` (C2, 2026-08-16) -- `make ci` on push to @@ -1267,39 +1288,36 @@ They are tracked collectively here, not as individual rows, because per-directory agent guidance is a property of the directory rather than a standalone artifact (KA-038). -As of 2026-08-23: **45 files exist; 4 are still the generic placeholder** -and 41 carry real local content. (Read "42 ... and 38", as of -2026-08-22, until 2026-08-23 -- three files joined in between and this -count was not updated for any of them: `tests/features/CLAUDE.md` -(added by the same change as ADR-007, 2026-08-22, real content, missed -by the very consistency sweep that landed hours earlier) and -`src/pyflow/engine/numerics/CLAUDE.md`/`tests/unit/numerics/CLAUDE.md` -(TASK-018, 2026-08-23, both real content). Found while drafting this -same TASK-018 change, the same "count restated in three places, one -file added, count not touched" failure this row already exists to warn -about.) (42 rather than 40 because F2 -(`docs/planning/backlog.md`) found `.claude/` and `.claude/hooks/` -untracked by this manifest and by `docs/planning/knowledge-architecture.md`, -with no `CLAUDE.md` at all -- both written in the same change, both real -content, not placeholders. 40 itself down from 43 because `assets/icons/`, -`assets/shaders/`, `assets/textures/` were retired 2026-08-19, E9, taking -their placeholder files with them, on the same "nothing states what this -is for" test that retired `tools/planner/`/`tools/scripts/`, E10; 43 -itself down from 45 for that same E10 retirement.) E9's *Done when* was -revised the same day it closed: no placeholder may remain in a directory -that has content, not no placeholder anywhere -- inventing -directory-specific guidance for a directory that is still genuinely -empty produces speculation, not knowledge. **3** remaining placeholders -as of 2026-09-04 (`docs/tutorials/`, `examples/tutorials/`, -`tests/performance/`) sit in directories with no real content yet -- -down from 4, `examples/experiments/` having gained real content that -day (`smoke_transport_high_res.yaml`, a higher-resolution variant of -`examples/golden-demos/smoke_transport.yaml`) -- so E9 is closed under -the revised criterion. `docs/planning/backlog.md` E9 -holds the file-by-file breakdown and is the authoritative count; this -row and `docs/planning/roadmap.md`'s TASK-009 status both restate it, so -update all three together. `examples/experiments/` gained a second file -2026-09-06, `smoke_transport_re1000.yaml` -- a 64x64, Re = 1000 trial of +As of 2026-09-08: **49 files exist** (up from 47 as of 2026-09-06: +`.claude/skills/CLAUDE.md` and `.claude/skills/ship/CLAUDE.md` joined +with `.claude/skills/ship/SKILL.md`, real content from the day the +directory was created, same as `.claude/skills/`'s own manifest section +above). **This row itself had drifted to 2026-08-23's count of 45 while +`docs/planning/roadmap.md`'s TASK-009 status kept being updated to 46 +and then 47** -- found and corrected in this same change, the identical +"count restated in three places, one restatement not touched" failure +this row already exists to warn about, this time caught by the change +that was about to make the count wrong a fourth way rather than by a +dedicated sweep. `docs/planning/roadmap.md`'s TASK-009 row carries the +full incremental history (46 from `tests/fixtures/CLAUDE.md`, TASK-034; +45 from `tests/features/CLAUDE.md`, ADR-007, plus +`src/pyflow/engine/numerics/CLAUDE.md`/`tests/unit/numerics/CLAUDE.md`, +TASK-018; 42 from F2 finding `.claude/` and `.claude/hooks/` untracked; +40 from retiring `assets/icons/`/`assets/shaders/`/`assets/textures/`, +E9/E10) -- this row restates only the current total and the two most +recent deltas rather than re-deriving that whole chain a second time, +since restating it fully in both places is exactly the duplication that +let this row go stale for two updates running. `docs/planning/backlog.md` +E9 holds the file-by-file breakdown as of its own 2026-08-19 closure and +is not kept current past that point -- it is a record of when E9 closed, +not a running total; this row and `docs/planning/roadmap.md`'s TASK-009 +status are the two that track the live count, so update both together. +**3** files sit in directories with no real content yet +(`docs/tutorials/`, `examples/tutorials/`, `tests/performance/`), +unchanged since 2026-09-04 (`docs/planning/backlog.md` E9's revised +*Done when*: no placeholder may remain in a directory that has content, +not no placeholder anywhere). `examples/experiments/` gained a second +file 2026-09-06, `smoke_transport_re1000.yaml` -- a 64x64, Re = 1000 trial of the same smoke-transport shape, checking whether more mesh and a higher Reynolds number make secondary corner vortices visible where Re = 100 does not (`examples/experiments/CLAUDE.md`'s own entry has the detail);