postmerge

name	postmerge
description	Post-merge workflow — extract lessons and compile rules (manual sequence, wrap is retired)

totem wrap is retired pending mmnto-ai/totem#1361 (it silently overwrites hand-crafted committed docs via the totem docs step). Run the post-merge steps directly instead.

After merging PRs, run the following sequence. Replace $ARGUMENTS with the merged PR numbers (space-separated, e.g. 1345 1347 1348).

1. Extract lessons from the merged PR(s): pnpm exec totem lesson extract $ARGUMENTS --yes

2. Sync the semantic index (usually already handled by the post-merge git hook, but running it explicitly is cheap and safe): pnpm exec totem sync

3. Compile new rules locally and export to AI tool configs. Do NOT pass --cloud; the cloud worker is Gemini-only (migration to Claude declined — mmnto-ai/totem#1221, closed not-planned). Local compile routes to the orchestrator.overrides.compile role in totem.config.ts (currently Claude Sonnet 5): pnpm exec totem lesson compile --export

4. Review the newly compiled rules. Step 3's output prints a count like N/M (100%) ... X compiled, Y skipped, Z failed. For each of the X newly compiled rules, inspect them in .totem/compiled-rules.json and verify:

   • The astGrepPattern or pattern is not over-broad (does it fire on legitimate code the rule is not trying to flag?)
   • The pattern does not reference hallucinated package names, type names, or file paths that do not exist in the repo
   • The lessonHeading accurately describes the rule's behavior

   For any rule that fails these checks, archive it with the atomic totem lesson archive <hash> --reason "<specific failure mode>" command (mmnto-ai/totem#1587). The command flips the rule's status to archived, stamps archivedAt on first transition, refreshes compile-manifest.json's output_hash, and regenerates the copilot and junie exports so the archived rule stops flowing into downstream AI tool configs — all in one invocation.

   pnpm exec totem lesson archive 8dbddb67 --reason "Pattern fires on every throw-in-catch; lesson's real scope is post-scaffold hooks only"
   

   Use as many characters of the hash as needed to unambiguously match one rule. The command matches on lessonHash prefix; ambiguous prefixes print the candidates and exit non-zero with no mutation. Idempotent on rerun — archivedReason refreshes, archivedAt is preserved. The mmnto-ai/totem#1345 archive filter in loadCompiledRules silences archived rules at lint time while preserving them in the ledger for future compile-worker prompt regression analysis.

   Do NOT use git checkout HEAD -- .totem/compiled-rules.json to revert the entire rules file. Reverting rules while keeping the new lessons on disk creates a manifest inconsistency (manifest.input_hash reflects the new lessons, output_hash reflects the reverted rules, verify-manifest fails on push). This is the symmetric counterpart of the mmnto-ai/totem#1337 bug. Archive-in-place via totem lesson archive is the intended curation surface; reverting is not.

   Empirical baseline: approximately 2 of every 6 auto-compiled rules are bad (1.14.1 postmerge), and the 2026-04-11 PM postmerge hit 4 of 5. The compile-worker prompt rewrite conversation lives under Strategy #73 and Strategy #62. Every archivedReason is feedback that informs that rewrite.

5. Format everything compile and archive touched: pnpm run format

6. Stage only the artifacts we keep: new lessons, the mutated rules file, the refreshed manifest, and the regenerated exports. Do NOT stage docs/wiki/roadmap.md or docs/reference/architecture.md unless you hand-edited them deliberately (those are totem docs targets and a postmerge run should not rewrite them): git add .totem/lessons/ .totem/compiled-rules.json .totem/compile-manifest.json .github/copilot-instructions.md .junie/skills/totem-rules/rules.md

7. Commit: git commit -m "chore: totem postmerge lessons for $ARGUMENTS"

8. Report: how many lessons extracted, how many rules compiled, how many were archived with totem lesson archive and their reasons, and whether any new tickets were filed for rules that need source- lesson refinement before they can be re-compiled cleanly.

Historical note. Postmerge curation scripts at scripts/archive-bad-postmerge-*.cjs (first introduced on mmnto-ai/totem#1366, last used on mmnto-ai/totem#1625) are retired. Those scripts hand-mutated compiled-rules.json and relied on a subsequent totem lesson compile --export call to refresh the manifest, but that no-op path only detected input-hash drift — not output-hash drift from inline mutations (the exact gap mmnto-ai/totem#1587 closed). totem lesson archive replaces them with one atomic call that handles the mutation + manifest refresh + export regeneration in a single step. The scripts were deleted from HEAD in the 2026-07 repo-surface cleanup (run-and-delete policy, CONTRIBUTING § Repo Tooling Policy); recover them from git history via the PR anchors above if audit archaeology ever needs them.

For an output-hash-only refresh without archiving (e.g., after manual edits to compiled-rules.json for other lifecycle reasons), use pnpm exec totem lesson compile --refresh-manifest — the no-LLM primitive that backs the atomic archive command.

The retirement error from totem wrap prints the same sequence at runtime (without step 4's curation detail), so if you forget the steps, run pnpm exec totem wrap <prs> for the short form.