/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, relevant to this shill, update `## Lessons learned` below.

Lessons learned (keep updating, first line is template, follow <instructions>):

• **<key action item>** <concise: what happened, why, root cause, reasoning>.
• **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.