@neotx/agents 0.1.0-alpha.20 → 0.1.0-alpha.22

package/SUPERVISOR.md

@@ -140,6 +140,20 @@ neo run scout --prompt "Explore this repository and surface bugs, improvements,
 
 ### 2. Routing
 
+**Pre-dispatch dedup check (MANDATORY before every `developer` dispatch):**
+
+```bash
+# 1. Check for open PRs on the same topic
+gh pr list --repo <repo> --search "<2-3 keywords from finding>" --state open --json number,title
+# → If a similar PR is OPEN: skip dispatch, add a comment on the existing PR instead
+
+# 2. Check for recently merged fixes
+gh pr list --repo <repo> --search "<2-3 keywords>" --state merged --limit 5 --json number,title,mergedAt
+# → If a similar fix was merged in the past 7 days: skip dispatch, the issue is already resolved
+```
+
+Skip silently and log: `neo log discovery "Skipping <finding> — covered by PR #<N>"`.
+
 | Condition | Action |
 |-----------|--------|
 | Bug + critical priority | Dispatch `developer` directly (hotfix) |
@@ -185,6 +199,7 @@ Parse fixer's JSON output:
 Parse scout's JSON output:
 - For each finding with `decision_id`: wait for user decision at future heartbeat.
 - User answers "yes" on a decision:
+  - **Run pre-dispatch dedup check** (§2) before dispatching — if a similar PR is already open or was merged recently, skip and log.
   - `effort: "XS" | "S"` → dispatch `developer` with finding as ticket
   - `effort: "M" | "L"` → dispatch `architect` for design first
 - User answers "later" → log to backlog, no dispatch
@@ -231,40 +246,22 @@ Infer missing fields before routing:
 
 **Priority** (when unset): `medium`
 
-## Idle Behavior — Scout Dispatch
+## Idle Behavior
 
 When the supervisor has **no events, no active runs, and no pending tasks**, it enters idle mode.
 
-Instead of doing nothing, dispatch a `scout` agent to proactively explore a repository:
-
-1. **Check preconditions:**
-   - Budget remaining > 10% — do not scout if budget is tight
-   - No pending decisions from a previous scout — wait for user to answer before scouting again
-   - No active runs — scout only when truly idle
-
-2. **Pick a repo:**
-   - Choose the repo least recently scouted (check memory for previous `scout` runs)
-   - If no scout has ever run, pick the first configured repo
-   - Rotate across repos over time — do not scout the same repo twice in a row
-
-3. **Dispatch:**
-   ```bash
-   neo log decision "Idle — dispatching scout on <repo-name>"
-   neo run scout --prompt "Explore this repository. Surface bugs, improvements, security issues, and tech debt. Create decisions for critical and high-impact findings." \
-     --repo <path> \
-     --branch <default-branch> \
-     --meta '{"stage":"scout","label":"scout-<repo-name>"}'
-   ```
-
-4. **On scout completion** (see Protocol §8):
-   - Read the output with `neo runs <runId>`
-   - The scout has already created decisions via `neo decision create`
-   - Log the `health_score` and finding count as a fact
-   - Wait for user to answer decisions at future heartbeats
-
-5. **Frequency guard:**
-   - Max ONE scout per repo per 24h — do not re-scout a repo that was scouted today
-   - Write a fact after each scout: `neo memory write --type fact --scope <repo> "Last scouted: <date>, health: <score>/10, <N> findings"`
+**Do not dispatch new agents proactively.** Instead, use idle time to audit past work and catch dropped tasks:
+
+1. **Review completed runs:** `neo runs --short` — scan for runs that completed but were never followed up on.
+2. **Check for missed dispatches:**
+   - A `developer` run completed with a `PR_URL` but no `reviewer` was dispatched → dispatch `reviewer`.
+   - A `fixer` run completed with `status: "FIXED"` but no re-review was dispatched → dispatch `reviewer`.
+   - A `reviewer` returned `CHANGES_REQUESTED` but no `fixer` was dispatched → dispatch `fixer` (check anti-loop guard first).
+   - A `refiner` returned `pass_through` but no `developer` was dispatched → dispatch `developer` with `enriched_context`.
+   - A `refiner` returned `decompose` but no `sub-tickets` were created (and/or no `developer` was dispatched) → create sub-tickets from `sub_tickets[]`, then dispatch one `developer` per sub-ticket.
+   - A `architect` returned `milestones[].tasks[]` but sub-tickets were never created → create them and dispatch.
+3. **Verify ticket states:** cross-reference tracker state with run outcomes — a ticket stuck in "ci pending" or "in review" with no active run is a sign of a dropped handoff.
+4. **If everything checks out:** do nothing. Wait for the next heartbeat or user input.
 
 ## Safety Guards
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neotx/agents",
-  "version": "0.1.0-alpha.20",
+  "version": "0.1.0-alpha.22",
   "description": "Built-in agent definitions and prompts for @neotx/core",
   "type": "module",
   "license": "MIT",

package/prompts/developer.md

@@ -21,6 +21,15 @@ Before any edit, verify:
 2. Files to modify exist and are readable
 3. Parent directories exist for new files
 4. Git clone is clean (`git status`)
+5. Branch is up to date with base:
+   ```bash
+   git fetch origin
+   git status -sb  # check for "behind" indicator
+   ```
+   If the branch is behind `origin/main`, rebase before editing:
+   ```bash
+   git rebase origin/main || { echo "MERGE CONFLICT — escalating"; exit 1; }
+   ```
 
 If ANY check fails, STOP and report.
 

package/prompts/fixer.md

@@ -14,7 +14,13 @@ Infer the project setup from `package.json`, config files, and source convention
 Read the latest PR review comments to understand what needs fixing:
 
 ```bash
-gh pr view --json number --jq '.number' | xargs -I{} gh api repos/{owner}/{repo}/pulls/{}/comments --jq '.[-5:][] | "[\(.user.login)] \(.path):\(.line) — \(.body)"'
+# Detect PR number from branch if not provided in the prompt
+PR_NUMBER=$(gh pr view --json number --jq '.number' 2>/dev/null)
+
+# Fetch the last 5 review comments
+gh pr view "$PR_NUMBER" --json reviews --jq \
+  '.reviews[-5:] | .[] | "[\(.author.login)] \(.body)"' 2>/dev/null \
+  || echo "No review comments found — using issues from prompt"
 ```
 
 If comments are unavailable, fall back to issues provided in the prompt.
@@ -22,6 +28,20 @@ If comments are unavailable, fall back to issues provided in the prompt.
 Group issues by file. Prioritize: CRITICAL → HIGH → WARNING.
 If fixing requires modifying more than 3 files, STOP and escalate immediately.
 
+### 1b. Sync with base branch
+
+Before making any edits, sync the branch to avoid conflicts:
+
+```bash
+git fetch origin
+git rebase origin/main || {
+  echo "MERGE CONFLICT — cannot rebase automatically"
+  exit 1
+}
+```
+
+If the rebase fails, STOP and escalate immediately — do not attempt manual conflict resolution.
+
 ### 2. Diagnose
 
 For each issue, read the full file and its dependencies.

package/prompts/reviewer.md

@@ -15,7 +15,6 @@ Review ONLY added/modified lines. Challenge by default.
 
 - No limit on tool calls — be as thorough as needed.
 - Max **15 issues** total across all lenses (prioritize by severity).
-- Do NOT checkout main for comparison.
 
 ## Protocol
 
@@ -75,7 +74,7 @@ Skip only: premature optimization suggestions, 100% coverage demands on internal
 pnpm tsc --noEmit 2>&1 | tail -20
 
 # Secrets scan on changed files only
-git diff main --name-only | xargs grep -inE \
+git diff origin/main --name-only | xargs grep -inE \
   '(api_key|secret|password|token|private_key)\s*[:=]' 2>/dev/null \
   || echo "clean"
 ```
@@ -130,7 +129,7 @@ EOF
 - **WARNING** → should fix: DRY violations, convention breaks, missing types, untested edge cases.
 - **SUGGESTION** → max 3 total. Genuine improvements worth considering.
 
-Verdict: any CRITICAL → `CHANGES_REQUESTED`. ≥3 WARNINGs → `CHANGES_REQUESTED`. Otherwise → `APPROVED`.
+Verdict: any CRITICAL → `CHANGES_REQUESTED`. ≥5 WARNINGs → `CHANGES_REQUESTED`. SUGGESTIONs never block. Otherwise → `APPROVED`.
 
 ## Rules