@yemi33/minions 0.1.1891 → 0.1.1892

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1891",
+  "version": "0.1.1892",
   "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"

package/playbooks/templates/verify-guide.md

@@ -63,6 +63,42 @@ List anything that requires human judgment:
 Cross-project or cross-feature interactions to verify:
 - e.g., "Service A calls Service B — verify the API contract"
 
+## Cross-PR Compatibility Audit
+
+Per-pair verdicts (one line per pair, format: `PR-A vs PR-B: independent | A supersedes B | B supersedes A | conflict <description> | order: B before A`). Cite `path:line` for every conflict claim.
+
+- PR-#### vs PR-####: <verdict>
+- ...
+
+## Semantic Regression Audit
+
+Per-PR verdict for each engine-touching PR (anything under `engine/`, `engine.js`, `dashboard.js`, `bin/`, `dashboard/**`). Format: `PR-####: <safe | risk: <description with path:line citation> | needs human review: <question>>`. Cite call sites, not just the diff.
+
+- PR-####: <verdict>
+- ...
+
+## Merge Decisions
+
+Required. Read by a human deciding what to merge in what order.
+
+### Recommended merge order
+1. PR-#### — <reason or `independent`>
+2. ...
+
+### PRs to close as superseded
+- PR-#### — superseded by PR-####; merging both would <regression description>
+- (or: `none`)
+
+### PRs requiring human decision
+- PR-#### — blocked on <contradiction with PR-#### at file:line>, or <missing CI / other>
+- (or: `none`)
+
+If the audit found nothing to decide, replace the three subsections above with the single line:
+
+```
+Merge Decisions: clean — all <N> PRs are pairwise independent and may merge in any order
+```
+
 ## Known Issues
 - Build warnings, test failures, merge conflicts, unimplemented items
 

package/playbooks/verify.md

@@ -49,6 +49,47 @@ For each project with aggregate verification changes, create or update one draft
 
 Track each E2E PR in the project's `.minions/pull-requests.json` if it is not already tracked.
 
+## Cross-PR Compatibility Audit
+
+Before declaring verification complete, audit the plan's PRs against each other — not just against master. A clean E2E build is necessary but not sufficient: two PRs can both compile and pass tests in isolation, both look fine in the merged E2E branch, and still represent contradictory or duplicate intent that will silently regress one of them once merged into master in the wrong order.
+
+For each pair of plan PRs, check and record a verdict:
+
+1. **Line-level overlap** — run `git diff --name-only <prA-base>..<prA-head>` and `<prB-base>..<prB-head>`; for any shared file, run `git diff <prA-head> <prB-head> -- <file>` and inspect. If both PRs touch the same line/symbol with different values, name the conflict explicitly (don't trust the auto-merge).
+2. **Semantic supersession** — does PR-A do everything PR-B does, plus more? If yes, PR-B is superseded; recommend closing it. The classic trap: PR-B adds field X to a list, PR-A adds field X *and* removes dead field Y. Merging B after A reintroduces Y.
+3. **Contradictory acceptance criteria** — do two plan items prescribe different shapes for the same contract (CLI flag, JSON field, prompt section)? If yes, one must lose; flag for human decision.
+4. **Order dependency** — does PR-A's diff make sense only after PR-B lands (e.g., PR-A's tests reference a symbol PR-B introduces)? Record the required merge order.
+
+For each PR pair, a one-line verdict in the form: `PR-A vs PR-B: independent | A supersedes B | B supersedes A | conflict <description> | order: B before A`. Cite the file:line for any conflict claim. "No conflicts" without per-pair audit evidence is not acceptable.
+
+## Semantic Regression Audit
+
+A green E2E build proves the code compiles and the existing tests still pass. It does NOT prove the new behavior is correct or that it doesn't silently break a code path the test suite never exercised. For every plan PR that touches engine code (anything under `engine/`, `engine.js`, `dashboard.js`, `bin/`, `dashboard/**`), do a behavioral audit before approving the merge:
+
+1. **Trace the changed function's call graph one hop out.** For each modified function/exported symbol, run `git grep -n '<symbol>'` across the repo (not just within the PR's diff). For each caller, ask: does the new behavior still satisfy what this caller expects? Cite the caller as `path:line — assumption — still holds? yes/no/unsure`.
+2. **Identify the silent failure modes.** A change that adds a guard, demotes a fallback, or removes a field has a *what-used-to-happen-here* shadow. Name it. For removals: which call sites read the removed field, and what do they fall back to now? For added guards: what input previously passed and now gets rejected — is that input ever produced legitimately? For demoted fallbacks: which production path relied on the fallback, and is the new primary path actually populated there?
+3. **Check the test additions cover the new branch, not just the happy path.** A test that only asserts the new behavior on a freshly constructed input is half a test. The other half is: does an *existing* fixture that exercised the old behavior still pass, and does it pass for the right reason (not because the assertion got loosened)? Cite the test by file:line and the fixture it uses.
+4. **Read the comments in the diff with suspicion.** Comments like "this also handles X" or "the gate at Y skips this path" are claims the agent made. Verify each one by opening Y and confirming the gate actually does what the comment says. If the claim is wrong, the change has a hole.
+5. **Schema/contract changes deserve a grep across language boundaries.** A field added to a JSON contract in `engine/shared.js` may also be referenced in `dashboard/js/*.js`, `playbooks/*.md`, `test/**`, and any external consumer. Run a literal grep for the field name across the whole tree, not just the PR's touched files.
+
+Record one verdict per engine-touching PR in the form: `PR-####: <safe | risk: <description with path:line citation> | needs human review: <question>>`. "Looks fine" without per-call-site evidence is not acceptable. If you cannot complete the audit in the time available, say so explicitly and list the unaudited PRs in the Merge Decisions section under "PRs requiring human decision".
+
+## Merge Decision Note
+
+The inbox copy at `{{team_root}}/notes/inbox/verify-{{plan_slug}}.md` MUST include a **Merge Decisions** section with three required subsections, written for a human deciding what to merge in what order:
+
+1. **Recommended merge order** — numbered list of PRs that should land, in the order they should land, with a one-line reason for each ordering constraint (or `independent` if order doesn't matter).
+2. **PRs to close as superseded** — bullet list of PRs that should be closed without merging, with the superseding PR cited and the regression that would occur if both lands.
+3. **PRs requiring human decision** — bullet list of PRs blocked on a contradiction the agent could not resolve (cite the contradicting PR and the field/line in dispute), or on missing CI runs that need re-triggering.
+
+If the audit finds nothing to decide ΓÇö all PRs are independent, none superseded, none contradictory ΓÇö the section MUST take this exact form instead:
+
+```
+Merge Decisions: clean ΓÇö all <N> PRs are pairwise independent and may merge in any order
+```
+
+A bare "no conflicts found" or an empty Merge Decisions section is not acceptable. The point of this section is to spare the human a second audit; if you skip it, the human has to redo the work you were dispatched to do.
+
 ## Constraints
 
 - Do not assume any specific platform, language, framework, shell, build system, mobile app, web app, Android, or iOS target.
@@ -61,6 +102,6 @@ Track each E2E PR in the project's `.minions/pull-requests.json` if it is not al
 
 ## When to Stop
 
-Your task is complete once dependency branches are merged, build/test verification has run, the permanent guide is written, the inbox copy is written only if verification succeeded, and E2E PR URLs are included in your final response.
+Your task is complete once dependency branches are merged, build/test verification has run, the cross-PR compatibility audit has produced a per-pair verdict, the semantic regression audit has produced a per-PR verdict for every engine-touching PR, the permanent guide is written with a Merge Decisions section, the inbox copy is written only if verification succeeded, and E2E PR URLs are included in your final response.
 
 Include each E2E PR URL and the testing guide path in your final message, for example: `E2E PR created: <url>` and `Testing guide: {{team_root}}/prd/guides/verify-{{plan_slug}}.md`.