Settle how cead is built: spec, skeleton, fill

AGENTS.md

@@ -3,7 +3,7 @@ You build; I direct, review, approve, and answer for everything that ships.
 Public artifacts — commits, code, docs, descriptions — carry "Roone" only, never my last name.
 
 # CONTEXT
-Read these root-level files: `README.md` (what this is), `CODE.md` (workflows, environments and vocabularies by language).
+Read these root-level files: `README.md` (what this is), `CODE.md` (method, vocabulary, languages).
 Every time you create or discover a new AGENTS.md, paste its path here:
 
 # COMMUNICATION
@@ -20,6 +20,7 @@ Code is the primary documentation surface; you are its steward.
 Every addition carries maintenance and trust cost: default to omission, delete when behavior is preserved, merge duplicates, and let an existing artifact absorb new work before adding one.
 Measure complexity by branch count, not lines; reduce it with better abstractions, never by minifying or code golfing.
 Label uncertainty as uncertainty; volunteer absences; find problems and opportunities, don't grade.
+Prefer end-to-end tests; they prove the system works. Each ends in an artifact another person can check and re-run from the same initial state. Smaller tests only where an end-to-end test cannot reach an edge cheaply.
 
 When you hit a wall — a case that doesn't fit, a spec that breaks, an assumption that fails — the wall is information: the design is wrong somewhere. Stop the invalid path, re-derive the design from first principles until the wall doesn't exist, and return control only when meaning, evidence or authority must change.
 NEVER patch around a wall to comply with my words — no flags, special cases, shims, parallel paths, or tests rewritten to dodge a broken rule.
@@ -30,7 +31,7 @@ A blocker honestly reported is a desired outcome; a "working" deliverable built
 Pull Requests (PRs) are the units of work; only ever create PRs. No issues: the PR is the only record.
 
 For new work, create a draft PR from the first commit, on a branch and worktree specific to that PR. One writer per branch; both are deleted upon merge.
-Branches: short kebab-case topic — `ssh-inventory`, never `feature/…`.
+Branches: short kebab-case, naming the change, not the thing changed — `initial-spec`, never `spec` or `feature/…`.
 Commits: one imperative line; the diff is the what, the message is the why.
 
 Every PR description has these sections, kept current:
@@ -39,11 +40,12 @@ Every PR description has these sections, kept current:
 3. **Merge requirements** — definition of done; think like a Software Engineer
 
 PR descriptions become the squash-commit body, so write them as records of truth with links to related PRs (#PR).
+Squash trades bisect granularity for readable history: the unsquashed commits stay at `refs/pull/N/head`, and `gh land` keeps the comment thread as a note in `refs/notes/pr` (fetch `+refs/notes/*:refs/notes/*`).
 A leaning lives in the description of the PR that will settle it. Once code settles it, the why is a doc comment. No third document.
-Until its PR exists, a leaning is a comment on #7 (Horizon), in the description template. Check #7 before opening a PR; update a comment as intent clarifies; when one is ready, open its PR and delete the comment.
+Only #7 (Horizon) and PRs in progress are open. Until its PR exists, a leaning is a comment on #7, in the description template; scope it there, and when it is ready, open its PR and delete the comment.
 
-The first commit is the model, when `CODE.md` says the seed's shape demands one; its checker is green before any code exists.
-The next commit is typed stubs ONLY: types and signatures, placeholder bodies, the language's type gate green. The diff defines that PR's scope; one signature per action of the model. `CODE.md` names each language's stub and gate.
+The first commit is the spec, when `CODE.md` says the seed's shape demands one; its checker is green before any code exists.
+The next commit is typed stubs ONLY: types and signatures, placeholder bodies, the language's type gate green. The diff defines that PR's scope; one signature per action of the spec. `CODE.md` names each language's stub and gate.
 Subsequent commits fill those stubs.
 **Zero placeholders may remain at merge. This is always a hard requirement.** `CODE.md` names what counts as a placeholder and the lints that count them.
 
@@ -58,9 +60,7 @@ For every subsequent commit, add a comment to the PR briefly describing:
 8. **Verify yourself** — the 2–3 places most worth my direct attention before merging.
 9. **Next steps** — choose one of these three: additional commits (briefly describe), blocked (explain what is needed), or finished (all merge requirements met, PR is ready for review)
 
-Before marking a PR ready, fold what is durable from its comments (decisions, the measurement, the limitation) into the description; the description lands in git, the comments stay on GitHub.
-
-Every milestone yields one measurement and one honest limitation, in the PR. Nothing enters that the current milestone doesn't demand.
+Before marking a PR ready, fold what is durable from its comments (decisions, measurements, limitations) into the description: the description is the record, the comments its receipts.
 
 You may freely commit and push to PR branches via their worktrees.
 I own ALL reviews and merges, with `gh land` (squash, delete the branch, evict the worktree), never by hand. `main` is protected.