@yemi33/minions 0.1.2413 → 0.1.2414

package/docs/dev-composite-workflow.md

@@ -0,0 +1,101 @@
+# Dev composite branch + dev-dashboard workflow
+
+This documents the recurring "rebuild the composite branch from all my open PRs and
+relaunch the dev dashboard" workflow. It exists because the flow is otherwise
+reconstructed from `git reflog` every time. The [`rebuild-composite`](../.claude/skills/rebuild-composite/SKILL.md)
+skill and [`scripts/rebuild-composite.ps1`](../scripts/rebuild-composite.ps1) automate it.
+
+## What the composite branch is
+
+`composite/calebt-prs` is a throwaway integration branch: `origin/main` plus every
+one of an operator's currently-open PRs merged on top, so the whole in-flight set can
+be exercised together in one running dev instance. It is **rebuilt from scratch each
+time** (hard reset to `origin/main`, then re-merge each open PR) — never fast-forwarded
+and never pushed. Because of the hard reset, **anything committed only to
+`composite/calebt-prs` is discarded on the next rebuild**; durable changes (like this
+doc, the skill, and the script) must land on `main` via a normal PR.
+
+## The rebuild flow
+
+1. Confirm you are on `composite/calebt-prs` and note any dirty tracked files.
+2. Stash dirty tracked edits (see "Rogue dev edits" below) — do **not** discard them.
+3. `git fetch origin --prune`.
+4. Enumerate the operator's open PRs against `main`:
+   `gh pr list --repo <owner/repo> --state open --author <login> --base main --json number,headRefName`.
+5. `git reset --hard origin/main`.
+6. Merge each PR's head branch (`origin/<headRefName>`) in ascending PR-number order
+   with `git merge --no-edit`. Resolve conflicts, then `git commit --no-edit`.
+7. `node --check` the touched `.js` files.
+8. Relaunch the dev dashboard (see "Relaunching the dev dashboard").
+
+## Recurring merge conflicts
+
+Two conflicts have recurred on essentially every rebuild. Both are **clean additive**
+conflicts (two branches append to the same spot); the resolution is always "keep both
+sides". The canonical resolutions:
+
+### `bin/minions.js` (from the `agent rekey` PR, e.g. #412)
+
+`main` adds an `else if (cmd === 'state')` command block; the PR adds an
+`else if (cmd === 'agent')` block at the same location. **Keep both** — the `state`
+block first, then the `agent` block, then continue to the existing `doctor` block.
+Simply delete the three conflict markers (`<<<<<<<`, `|||||||`/`=======`, `>>>>>>>`);
+no lines between the sides need to be dropped.
+
+### `dashboard/slim/styles.css` (from the slim-ux Engine-embed PR, e.g. #896)
+
+`main` has the `#slim-settings-modal` block; the PR adds `.slim-engine-embed,` to the
+front of the `.slim-*-embed` selector group. **Keep both** — the settings-modal block,
+then `.slim-engine-embed,`, then the existing `.slim-work-embed, …` group.
+
+> **Strongly recommended: `git rerere`.** These resolutions are byte-identical every
+> rebuild. Enabling `git config rerere.enabled true` records each resolution once and
+> replays it automatically on every subsequent rebuild, so the conflicts resolve
+> themselves. The rerere cache lives in `.git/` and therefore survives the hard reset.
+
+Stop and resolve manually only when a **new** conflict (any other path) appears.
+
+## Relaunching the dev dashboard
+
+`--dev` mode runs the current checkout **as** the runtime root (`MINIONS_HOME = checkout`)
+with the dashboard on port **7332** (default) so it coexists with a global install on
+7331. See `bin/minions.js` (`--dev` / `--dev-port`).
+
+Rebuild is not a compile step — the dashboard SPA is reassembled at startup — so
+"rebuild + relaunch" is just a dev restart:
+
+```powershell
+node bin/minions.js --dev restart   # or: npm run dev
+```
+
+### Restart-under-load gotchas
+
+When the box is saturated (e.g. the dev fleet is running the full test suite), the
+`--dev restart` health verifier can **fast-fail**: the freshly spawned engine can't
+write its pid file inside the verifier's short window, so it is reported
+`state=stopped, pid=none`, the partial stack is torn down, and `engine/stop-intent.json`
+is set — which then blocks the next start, creating a loop. A **stray orphaned
+`dashboard.js`** from an earlier attempt independently trips the verifier's
+duplicate-daemon check.
+
+Reliable recovery:
+
+1. Stop any stray `engine.js` / `dashboard.js` / `supervisor.js` daemons (leave
+   `dispatch-*` agent processes and their worktree children alone — those are detached
+   agents that reattach on the next start).
+2. Delete `engine/stop-intent.json`.
+3. Confirm nothing is listening on the dev port.
+4. Start with `node bin/minions.js --dev start` — from a clean state this is more
+   reliable than `restart` under load.
+5. Verify: `GET http://localhost:7332/api/status` returns HTTP 200.
+
+The engine itself boots fine under load (a foreground `node engine.js` stays healthy);
+the fragility is only in the restart verifier's fast-fail path.
+
+## Rogue dev edits
+
+Because `--dev` uses the checkout as the runtime root, the dev fleet's own agents
+sometimes edit **tracked** files in place (e.g. `dashboard/js/settings.js`, docs, even
+reverting `README.md`). These show up as dirty tracked files before a rebuild. This is
+expected, not corruption — stash them (with a dated message) rather than discarding, so
+nothing is lost, then rebuild.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2413",
+  "version": "0.1.2414",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"