happy-stacks 0.3.0 → 0.5.0

package/docs/commit-audits/happy/leeroy-wip.commit-inventory.md

@@ -0,0 +1,102 @@
+# `happy` WIP branch commit inventory (`leeroy-wip`)
+
+Generated: 2026-01-24  
+Worktree: `/Users/leeroy/Documents/Development/happy-local/components/.worktrees/happy/slopus/tmp/leeroy-wip`
+
+## Scope
+
+- Branch: `leeroy-wip`
+- HEAD: `c803115dcbdcd55c036e47c0f0cfd6e1bceb9f74`
+- Upstream base ref: `upstream/main`
+- Merge-base (HEAD vs `upstream/main`): `40792d9eddf7fdaabd375e00134c5cfe5aea2db5`
+- Commits in scope (`upstream/main..HEAD`): `249`
+- Working tree state at capture time: **dirty** (many modified + untracked files)
+
+## Mandatory Workflow (incremental audit → regroup → rewrite)
+
+This workflow is designed to be incremental: you can keep auditing while new commits land, then do backups + history rewrite only when you’re ready to actually rewrite.
+
+### Phase 0: Audit setup (non-destructive)
+
+1. Record an “audit baseline” (no backups yet; no history rewriting):
+   - `merge-base HEAD upstream/main`
+   - `rev-parse HEAD`
+2. Prefer to avoid rebases on `leeroy-wip` while auditing. If the branch *does* get rebased, re-derive equivalence with `range-diff` before continuing to avoid losing audit context.
+
+### Phase 1: Audit commits (oldest → newest)
+
+For each commit:
+
+1. Read the original message body + file stats from `docs/commit-audits/happy/leeroy-wip.commit-export.fuller-stat.md` (this file is already ordered oldest → newest).
+2. Write/track the audit for that commit in `docs/commit-audits/happy/leeroy-wip.commit-analysis.md` (also ordered oldest → newest).
+3. Classify it into a single “topic bucket” (or mark it as “mixed / needs split”).
+4. Note:
+   - what changed (observable behavior)
+   - whether the message matches the diff
+   - whether the commit contains unrelated changes
+   - suggested rewritten Conventional Commit subject (+ body notes if needed)
+   - dependency ordering constraints (must land before/after other topics)
+
+Progress tracking (update manually while auditing):
+
+- Auto-triaged commits: `249/249`
+- Manually reviewed commits: `3/249`
+- Current commit under manual review: (set SHA)
+- Next planned topic bucket: (set)
+
+Current state (2026-01-24):
+
+- `docs/commit-audits/happy/leeroy-wip.commit-export.fuller-stat.md` covers all commits with full message + files + diffstat.
+- `docs/commit-audits/happy/leeroy-wip.commit-analysis.md` covers all commits with a diff-based summary and flags “Manual review needed: YES” for higher-risk commits.
+- `docs/commit-audits/happy/leeroy-wip.manual-review-queue.md` lists flagged commits in audit order.
+- `docs/commit-audits/happy/leeroy-wip.commit-manual-review.md` contains deep-review notes for flagged commits (fill incrementally).
+
+### Phase 2: Keep the audit fresh (when new commits land)
+
+When new commits are added on top of `leeroy-wip`:
+
+1. Regenerate the export file (so the raw messages + stats remain complete).
+2. Append the new commits to whatever “analysis” document we’re using (keeping the analysis document ordered oldest → newest).
+3. Update the progress counters (`Reviewed commits`, `Total commits`) and continue from the previous cursor.
+
+### Phase 3: Backup + rewrite by topic (only when ready)
+
+Preferred approach for a long-lived WIP branch: create a fresh branch from `upstream/main` and cherry-pick topic groups (squash within a topic as needed). Validate incrementally (typecheck/tests via `happys`) after each topic group.
+
+Before rewriting:
+
+1. Ensure the worktree is clean (stash or move WIP to a separate branch/worktree).
+2. Create at least two backups **immediately before** rewriting history (branch + tag, and ideally push a backup ref).
+3. Capture the “before” fingerprint:
+   - `range-diff upstream/main...leeroy-wip`
+   - `diff --stat upstream/main...leeroy-wip`
+
+### Phase 4: Prove equivalence
+
+After rewrite:
+
+- `range-diff upstream/main...<old-branch> upstream/main...<new-branch>`
+- `diff --stat upstream/main...<old-branch> upstream/main...<new-branch>`
+
+## Full Commit Messages + Stats Export
+
+See: `docs/commit-audits/happy/leeroy-wip.commit-export.fuller-stat.md`.
+
+## How To Drill Into A Commit (stack/worktree-safe)
+
+All commands below run against the worktree directly:
+
+```bash
+happys wt git happy slopus/tmp/leeroy-wip -- show --name-status --stat <sha>
+happys wt git happy slopus/tmp/leeroy-wip -- show <sha>
+happys wt git happy slopus/tmp/leeroy-wip -- show --word-diff <sha>
+```
+
+Useful “what changed overall?” comparisons (before/after history rewrite):
+
+```bash
+happys wt git happy slopus/tmp/leeroy-wip -- range-diff upstream/main...leeroy-wip
+happys wt git happy slopus/tmp/leeroy-wip -- diff --stat upstream/main...leeroy-wip
+```
+
+```