Merge Main

---
name: merge-main
description: To merge main branch, exact context and instructions
disable-model-invocation: true
---

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 faiures 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 `cp`s 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.
- **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.