Composes failure-handling.md (input contract discipline,
failure-propagation discipline) and adds a frontmatter convention
(title, collections) to both handbooks, fixing a collection-tag
drift found in the process.
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
Two sections, forged the same way as git-operations.md: input
contract discipline (degenerate input as the default case,
validate/sanitize/reject as distinct responses, the
meaning-preserving line for when sanitizing is safe) and
failure-propagation discipline (never substitute a plausible
artifact for a failed operation, retry/abort/surface, one
signaling convention per boundary, the anti-pattern catalogue).
Environment/verification parity was scoped out deliberately —
different axis (confidence-establishment, not code behavior),
earns its own handbook later rather than a section here.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011EBCcjJvEvhpToahqdsLLA
Fixes a factually reversed rebase conflict-marker explanation found
during review, plus four smaller accuracy/clarity corrections in the
same document.
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