merge-main

You are a thoughtful and meticulous senior software engineer.

Sync+merge remote origin main into this branch.

On conflicts: understand what both parts did. Use 3 way merge logic. Not just selecting A vs B. Not extremes. Not mechanical.

Automatically resolve if you are 100% sure, otherwise MUST USE HITL.

Workspace root:

• plugins are autogenerated => let user know to regenerate.
• docs/web is the web site content, which 99% follows original files.
• instructions is the actual instructions, use by plugin generator, which are sent to AI coding agents working on separate their own repositories.
• src contains MCPs, additional packages, and tools.

If you learned something new which is reusable, there are process efficiency improvements, you can prevent failures in the future, update ## Lessons learned below for self-improvement.

Lessons learned (self-improvement, keep updating, first line is template, keep template, follow "<instructions>", high confidence only):

• <key action item, less then 7 words> <concise/terse: what happened, why, root cause, reasoning, less then 25 words>.
• Regeneration is per-profile — the default pass leaves sibling profile trees stale. After resolving generated-file conflicts, running rosettify-plugins once cleaned the 7 standard trees but left all 6 core-*-light trees carrying pre-merge content, including frontmatter keys the merge had deleted. No conflict, no test failure — scripts/pre_commit.py runs the generator twice (standard, then --profile lightweight) and only both passes together make plugins/ consistent. Verify with diff -rq plugins/<t> plugins/<t>-light: anything differing beyond the profile-scoped files and the manifest name/description is stale.
• Check whether a doc reference survives the plugin boundary. Plugin output is only agents/ configure/ hooks/ rules/ skills/ workflows/ — nothing under docs/. A shipped instructions/ file that points at docs/… dangles for consumer repos, so "concise pointer vs inline contract" is a real HITL decision, not a style preference.
• Hunt semantic conflicts after the textual merge; git flags none of them. Three appeared here: main documented paths this branch had deleted, main asserted "no plugin directory yet" for a target this branch added, and main deleted instructions/ rule files whose generated copies survived in a branch-only plugin. Grep the merged tree for paths/claims each side touched, and always run both src/rosettify-plugins and src/hooks suites — a regression test caught the stale path a doc review missed.
• When both sides fixed the same stale string, compose the line — don't pick a side. Main and the branch independently corrected "Rosetta 2.0" in the Codex manifest; git conflicted only on that line while cleanly taking main's version bump and the branch's new defaultPrompt. The resolution is per-field, and the one word neither side can decide (3 vs 3.0) is the HITL question — not the whole file.
• A generated plugins/** conflict is a shadow of its preserved source. plugins/<t>/…/plugin.json is byte-copied from src/rosettify-plugins/plugins/<t>/…, so both conflict identically. Resolve them the same way, then tell the user to regenerate rather than hand-tuning the generated copy.
• Version drift survives a clean merge silently. Main bumped every plugin manifest and marketplace to a new patch while the branch had bumped only src/rosettify-plugins/package.json to a new minor. No conflict, no test failure — the two just disagree afterwards. Compare package.json against the manifests post-merge and surface it.
• Re-verify main's new content against the branch's generation changes. Main added a workflow plus 8 phase files; this branch had changed how workflows become skills. Nothing conflicted and every test passed, because no fixture covers content that did not exist when the tests were written. Generate and inspect the new artifact.
• Diff each side against the merge-base before merging; the overlap set is tiny. comm -12 on git diff --name-only <base> origin/main vs … <base> HEAD reduced 717+331 changed files to 15 real overlaps, which made the one genuine judgment call obvious immediately.
• Verify any incoming "generated / auto-built" claim against the build config; never trust the doc. Main imported docs/reviews/DOC-STRUCTURE-PLAN.md asserting llms-full.txt is "generated by the build pipeline (no manual facts)". It is hand-maintained: .github/workflows/pages.yml only cps it to docs/web/, no generator references it, and its history is all feature commits. A false generated-claim is high-damage — it invites treating hand-written content as disposable and skipping updates. Grep *.ts/js/json/sh/yml for the filename and check git log -- <file> before believing it.
• Zero textual overlap does not mean zero semantic conflict, and a dirty tree may be irrelevant. This merge had 0 overlapping files yet still imported a wrong maintenance claim about a file the branch edited. Separately, check git diff --name-only <base> origin/main | grep ^plugins/ first: if the incoming side touches no plugin files, locally modified plugins/ neither blocks the merge nor needs discussion — the user regenerates it regardless.
• Identical independent edits auto-resolve — don't assume a same-file overlap needs HITL. All 6 overlapping files here were plugin copies of one workflow, and both sides had made the byte-identical check_state→check_mode rename (each regenerating plugins to catch up with an instructions source that already had check_mode at the merge-base). git merge --ort merged them with zero conflict markers. Diff each overlapping file on both sides before assuming a HITL question exists — same-diff overlaps are free.
• The repo has multiple independent version tracks — never compare raw numbers across them. scripts/bump_versions.sh is the ground truth: it bumps plugin.json+marketplace.json together as one group (kept equal to each other), and separately, opt-in, bumps src/rosettify/package.json, src/rosettify-plugins/package.json, src/rosettify-prompts/package.json, src/curiocity/package.json, and each pyproject.toml — with no expectation any of those match each other or the plugin/marketplace group. rosettify-plugins/package.json at 3.2.0 next to plugin.json at 3.1.8 is not drift, it's two unrelated counters — a genuine "did the user mean to conflate these" moment, corrected after the user pushed back with "solution has individual components with individual versions, you must think." The real post-merge check is per-track: diff each file in the list above at base vs main vs branch vs merged — a track is a problem only if main and branch both bumped the same file to different values, or one side bumped a track's file and the merge silently reverted it.
• A clean textual merge can disable a feature when one side adds a closed allow-list and the other adds a new member of the validated set. Main added throw-on-unknown-filename-directive; this branch added the profile-<name>-only token kind. The two hunks sit in different parts of directives.ts, so git merged both with zero conflict markers — and the build would have hard-failed on all 11 profile-scoped source files. The suites that build from the real instruction tree are what expose this; a unit test on the parser alone would not. After any merge that touches validation, run the generator end-to-end against the real tree and check the exit code, not just the tests.
• When both sides independently create the same canonical constant, keep the shape that can DERIVE the other. Main added spec/target-names.ts (role-keyed object), this branch had put the same seven literals in types.ts (array + type + guard). Object.values recovers the list from the roles, but no expression recovers a role from a name string — so the role-keyed object is the literal home and the list/type/guard hang off it. Picking the other direction leaves the literals duplicated and free to drift.
• "Did the incoming side specify its new behavior?" is a merge check. Main shipped a build-aborting validation while touching only docs/hooks-verify.md under docs/ — no requirement unit at all, and the branch's shape-exemption was equally unspecified. git diff --name-only <base> origin/main | grep ^docs/REQUIREMENTS/ in one line tells you whether incoming behavior arrived with its spec.
• Main's generated edits skip branch-only plugin folders. Main's skill-README edits reached plugins/core-* only; 294 branch-only plugins/rosetta-* copies stayed stale. Regenerate with the local generator into scratch, then diff -rq.
• Read the branch's handoff, plan and gates before resolving anything. Merged without them, misjudged branch defects as "pre-existing", and skipped the branch's own acceptance gates. Read agents/TEMP/*-state.md and plans/ first.
• Run the branch's acceptance gates after merging. The equivalence gate caught main's 31 post-snapshot README edits; every test suite stayed green and missed them.
• Main's new links can name paths the branch moved. Rename detection carried main's README edits, but main's new Skills lists linked core/skills/* for moved skills. Run a dead-link check.
• Raise the rename limit before merging moved trees. Without -c merge.renameLimit=100000, main's edits to moved files can land on old paths or resurrect deleted ones.
• A case-only rename collides on macOS. Main's docs/requirements/X overwrote the branch's docs/REQUIREMENTS/X on disk. 3-way merge from index stages; git rm --cached the lowercase path only.
• "Take theirs, re-apply ours" needs the branch's full file diff. The conflict hunk hid a functional PLUGIN_HOOKS=plugins/rosetta-claude/… line; checking base→HEAD per file caught it.
• Rename detection does not carry version bumps to moved manifests. Main bumped core-*/plugin.json; the branch's template-<ide> copies and branch-only marketplaces stayed old. Set the group by hand.
• Never add a total beside an existing per-set table. It created a second number with a different "workflows" meaning. Define terms once, then align every statement to them.
• Reword a corrected claim across every doc surface, and watch the letter case. "the closing fence yields an empty, inert token" lived in 8 places: two FR-ARCH statements AND their two criteria, FR-PROF notes AND an AC, GLOSSARY, and ASSUMPTIONS twice. A criterion can be half-right — these already said the token set is {overwrite} yet still appended the inert clause — so grep the claim, don't reason about where it "should" be. One instance began "The" rather than "the" and silently survived a case-sensitive replace.
• One side replaced a line the other kept: keep both meanings. Branch swapped an r3 criterion for --release r2; main kept r3. Both test different behavior; picking one silently dropped a criterion.
• A guard in a function the branch deleted must move, not vanish. Main hardened resolveSourceDirs (empty --domain); the branch had replaced that function. Port the guard to where input is now parsed, with its tests.
• Main's diagrams are facts too. Main replaced ASCII diagrams with D2 SVGs that named pre-split plugins. Fix the .d2 source, re-render with d2 --dark-theme 200 (byte-reproduces committed SVGs), never keep stale art.
• Merge one behavior's tests by intent, not by hunk. Main removed real-tree model assertions (models are owner-tunable) and also dropped a model-agnostic TOML-parse test as collateral; read the commit message to separate intent from collateral.