New repos only, same non-retroactive caveat as trunk naming.
Underscores don't survive the trip to a domain, a Docker tag, or
most package-registry names, where hyphens do; matches the
kebab-case already used for branch descriptions.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011EBCcjJvEvhpToahqdsLLA
Each handbook now opens with a flat YAML frontmatter block so the
two ingest-time values that actually describe the document -
title and collections - live with it instead of being retyped by
hand at admission time. That drift was real, not hypothetical:
the ingest recipe documented `--collection dev-practice` while the
actual admission used `handbooks`.
`version` deliberately stays out of frontmatter - a file can't
contain the hash of the commit that writes it - and remains a
value the ingest recipe computes fresh, now scoped per-file
(git log -1 -- <file>) rather than the whole repo's HEAD.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011EBCcjJvEvhpToahqdsLLA
The rebase conflict-marker explanation had HEAD and the incoming
side backwards, verified by reproducing all three merge/rebase
scenarios in a throwaway repo. Rewrote that passage around the
actual behavior instead of a merge-vs-rebase binary, since the old
"merge = HEAD is trunk" claim was also only true for one of the two
merge scenarios the doc itself describes.
Also fixes, from the same review pass:
- push-rejection handling in Branching split into its two real
causes (protection/permission vs. plain non-fast-forward)
- the commit-body trigger reworded to match how it's actually used
("why worth keeping", not just subject length)
- a mislabeled checkout equivalent for unstaging (that was always
git reset's job, not checkout's)
- the vendor-sync example no longer assumes upstream's trunk is
named master
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011EBCcjJvEvhpToahqdsLLA
Branching through tags, forged collaboratively over a full session:
trunk-based branching with type/description naming, atomic commits,
rebase-to-stay-current paired with merge --no-ff to land, revert vs.
reset vs. switch/restore split by shared-vs-local history, an
origin/upstream/mirror remote-naming discipline (including a
vendor-branch pattern for reconciling borrowed-repo drift), and
SemVer tags driven by the same type taxonomy as commits.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011EBCcjJvEvhpToahqdsLLA
mikkeli