PLN-202: Add multi-repo support for planning and exploration

CHANGELOG.md

@@ -14,6 +14,29 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Updated agent output path references from `.claude/runs/` to `.closedloop-ai/runs/` in `agent-prompt-generator`
 - Updated bootstrap configuration documentation in `agent-bootstrap.md` to reference `.closedloop-ai/` state directory
 
+### code v1.7.0
+
+#### Added
+- Multi-repo planning and exploration support via new `--add-dir` flag in `run-loop.sh`, exposing `CLOSEDLOOP_ADD_DIRS` and `CLOSEDLOOP_REPO_MAP` env vars to downstream agents
+- `pre-explorer` agent produces per-repo code maps (`code-map-{name}.json`) when secondary repos are supplied
+- `plan-draft-writer` agent emits multi-repo plans with a `## Repositories` table and `@{repo}:path` task prefixes
+- New `multi-repo.overlay.md` overlay assembled onto `prompt.md` at runtime for cross-repository planning workflows
+- `repositories` map field added to the plan root schema in `plan-schema.json` for multi-repo plan traceability, keyed by repo short-name with `path` and `isPrimary` metadata
+- Tier 0 explicit-directory discovery and dedup helpers in `discover-repos.sh`, with structured JSON output
+- Enhancements to `cross-repo-coordinator` and `cross-repo-prd-writer` agents for multi-repo context
+- Tests for `discover-repos.sh` and `setup-closedloop.sh` (`test_discover_repos.py`, `test_setup_closedloop.py`) plus new multi-repo cases in `test_validate_plan.py`
+
+#### Fixed
+- `run-loop.sh` now scans the full per-iteration stream for the `<promise>` completion marker instead of only inspecting the final `type==result` record, preventing missed completion signals when the orchestrator emits the promise in an intermediate message followed by additional tool_use or wrap-up output
+- `discover-repos.sh` now filters add-dirs that are ancestors of the workdir and deduplicates repo entries to prevent duplicate discovery results
+- Fixed multi-repo execution ordering and prompt definition string assembly in overlay resolution
+
+#### Changed
+- Consolidated Tier 0 `discover-repos.sh` tests into a single scenario-driven harness, replacing the prior fragmented per-case test files
+- Migrated workdir internal state directory from `.closedloop/` to `.closedloop-ai/` across hooks, setup scripts, and loop state management
+- Established `CLOSEDLOOP_STATE_DIR` constant as single source of truth for state directory name across shell scripts
+- Added `Skill` to `plan-evaluator` agent's allowed tools to enable `code:plan-validate` skill execution
+
 ### code v1.6.0
 
 #### Changed
@@ -45,6 +68,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Domain critic pass injection in fast-path reviewer via `{DOMAIN_CRITIC_PASS}` placeholder, enabling domain expert review within single-agent fast-path runs
 - Replaced shared prompt reasoning checklist with structured `PREMISE / EVIDENCE / GUARD CHECK / SEVERITY CHECK` analysis framework
 
+### judges v1.5.1
+
+#### Changed
+- Migrated perf-substep state paths from `.closedloop/` to `.closedloop-ai/` in `run-judges` skill telemetry instrumentation
+
 ### judges v1.5.0
 
 #### Changed
@@ -55,6 +83,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 #### Changed
 - Version bump to align with cross-plugin `.closedloop-ai/` directory migration
 
+### self-learning v1.1.1
+
+#### Changed
+- Established `CLOSEDLOOP_STATE_DIR` constant as single source of truth for state directory name in `bootstrap-learnings.sh`, `compute_success_rates.py`, and `write_merged_patterns.py`
+
 ### self-learning v1.1.0
 
 #### Changed

CLAUDE.md

@@ -44,7 +44,7 @@ Always use `plugin-name:skill-name` format (e.g., `self-learning:learning-qualit
 
 ### Closed Loop (run-loop.sh)
 
-The core orchestration loop in `plugins/code/scripts/run-loop.sh`. Drives fresh-context Claude iterations — each `claude -p` invocation gets a clean context window. The orchestrator prompt at `plugins/code/prompts/prompt.md` coordinates 8 workflow phases via subagent delegation. Post-iteration, `run-loop.sh` runs an 11-step pipeline calling Python scripts from `self-learning/tools/python/`.
+The core orchestration loop in `plugins/code/scripts/run-loop.sh`. Drives fresh-context Claude iterations — each `claude -p` invocation gets a clean context window. The orchestrator prompt at `plugins/code/prompts/prompt.md` coordinates 8 workflow phases via subagent delegation. Post-iteration, `run-loop.sh` runs an 11-step pipeline calling Python scripts from `self-learning/tools/python/`. The base prompt is the single source of truth; variants (e.g. `--prompt multi-repo`) are expressed as append-only overlays under `plugins/code/prompts/overlays/` and assembled at runtime — see `plugins/code/prompts/overlays/README.md`.
 
 ### Hooks
 

plugins/code/README.md

@@ -63,7 +63,7 @@ State is maintained in `$CLOSEDLOOP_WORKDIR/state.json` at each phase transition
 ```
 
 - `working-directory`: Path to the work directory containing the PRD (defaults to current directory)
-- `--prompt <name>`: Select an alternate orchestrator prompt from `prompts/` (defaults to `prompt`)
+- `--prompt <name>`: Select an alternate orchestrator prompt. Resolves to `prompts/<name>.md` if present, otherwise to `prompts/prompt.md` assembled with `prompts/overlays/<name>.overlay.md`. Defaults to `prompt`. See `prompts/overlays/README.md` for the overlay authoring guide.
 - `--prd <file>`: Explicitly specify the requirements file (auto-detected if omitted)
 
 **What it does:**
@@ -276,7 +276,7 @@ Cleans up session-level artifacts: removes the session workdir mapping file, cle
 
 Runs when any subagent starts. Performs three tasks:
 
-1. **Loop agent state creation**: If the agent type appears in `loop-agents.json`, creates the initial state file in `{WORKDIR}/.closedloop/` if it does not already exist.
+1. **Loop agent state creation**: If the agent type appears in `loop-agents.json`, creates the initial state file in `{WORKDIR}/.closedloop-ai/` if it does not already exist.
 2. **Agent type tracking**: Writes the agent type, short name, and start timestamp to `.agent-types/{agent_id}` so the stop hook can track timing and type.
 3. **Learning injection**: Reads `~/.closedloop-ai/learnings/org-patterns.toon`, filters patterns matching the agent's name, sorts by category priority (mistake > convention > pattern > insight) and confidence, and injects up to 15 patterns into the agent's context via `additionalContext`. Also injects environment variables (`CLOSEDLOOP_WORKDIR`, `CLAUDE_PLUGIN_ROOT`, etc.) into every agent's context.
 
@@ -293,7 +293,7 @@ Runs when any subagent exits. Performs:
 
 Implements the validation loop for agents registered in `loop-agents.json`. When an agent exits:
 
-1. Reads the loop state file (`{WORKDIR}/.closedloop/{state_file_suffix}`)
+1. Reads the loop state file (`{WORKDIR}/.closedloop-ai/{state_file_suffix}`)
 2. Checks whether the agent output contains the expected completion promise (e.g., `<promise>PLAN_VALIDATED</promise>`)
 3. If the promise is present, optionally runs a validation script (e.g., `validate-plan.sh`)
 4. If validation passes, allows the agent to exit (returns nothing)
@@ -346,7 +346,7 @@ Defines the structure of `code-map.json` produced by the `pre-explorer` agent. R
 
 ### `setup-closedloop.sh`
 
-Initializes a ClosedLoop session. Parses arguments (`--prd`, `--max-iterations`, `--prompt`, positional workdir), auto-detects the PRD file by checking common patterns (`prd.md`, `prd.pdf`, `requirements.md`, etc.), establishes the session-to-workdir mapping, validates the prompt name, and writes `{WORKDIR}/.closedloop/config.env` with all environment variables.
+Initializes a ClosedLoop session. Parses arguments (`--prd`, `--max-iterations`, `--prompt`, positional workdir), auto-detects the PRD file by checking common patterns (`prd.md`, `prd.pdf`, `requirements.md`, etc.), establishes the session-to-workdir mapping, validates the prompt name, and writes `{WORKDIR}/.closedloop-ai/config.env` with all environment variables.
 
 ### `run-loop.sh`
 
@@ -485,7 +485,7 @@ After a full run, the work directory will contain:
   log.md                     # Change log appended each phase
   perf.jsonl                 # Agent timing events
   reviews/                   # Critic review files (*.review.json)
-  .closedloop/config.env     # Session environment variables
+  .closedloop-ai/config.env   # Session environment variables
   .learnings/                # Self-learning artifacts
     pending/                 # Unprocessed learning JSON files
     outcomes.log             # Pattern application outcomes

plugins/code/agents/cross-repo-coordinator.md

@@ -59,6 +59,19 @@ Parse the JSON output to get:
 
 **Write the discovery result to `$CLOSEDLOOP_WORKDIR/.workspace-repos.json`** so other agents can access it.
 
+### Step 1.5: Local Repos (--add-dir)
+
+After running `discover-repos.sh`, check `CLOSEDLOOP_ADD_DIRS` from the environment. This variable contains pipe-separated paths passed via `--add-dir` flags, representing local repositories that are already part of the current task plan. Example: `CLOSEDLOOP_ADD_DIRS="/path/to/a|/path/to/b"`.
+
+For each path in `CLOSEDLOOP_ADD_DIRS`:
+1. Normalize the path (resolve symlinks, trailing slashes)
+2. Find the matching entry in the `peers[]` array from the discovery output by comparing the `path` field
+3. If a match is found, mark that peer with `"local": true` in the entry written to `.cross-repo-needs.json`
+
+**Local repos must NOT generate cross-repo PRDs** — they already have tasks in the plan. When writing capabilities for a local peer, set `"local": true` and skip PRD generation for that peer in the downstream workflow.
+
+External repos (peers NOT found in `CLOSEDLOOP_ADD_DIRS`) continue through the existing PRD-generation workflow unchanged.
+
 ### Step 2: Handle No Peers Case
 
 If `peers` array is empty:
@@ -104,6 +117,7 @@ Write `$CLOSEDLOOP_WORKDIR/.cross-repo-needs.json`:
       "peerName": "astoria-service",
       "peerType": "backend",
       "peerPath": "/path/to/backend",
+      "local": false,
       "capabilities": [
         {
           "type": "endpoint",
@@ -116,6 +130,19 @@ Write `$CLOSEDLOOP_WORKDIR/.cross-repo-needs.json`:
           "neededBy": ["T-3.1"]
         }
       ]
+    },
+    {
+      "peerName": "astoria-shared",
+      "peerType": "library",
+      "peerPath": "/path/to/shared",
+      "local": true,
+      "capabilities": [
+        {
+          "type": "module",
+          "description": "Shared auth utilities",
+          "neededBy": ["T-1.2"]
+        }
+      ]
     }
   ]
 }

plugins/code/agents/cross-repo-prd-writer.md

@@ -21,15 +21,25 @@ Read `$CLOSEDLOOP_WORKDIR/.cross-repo-needs.json` for the list of needed capabil
 
 Read `$CLOSEDLOOP_WORKDIR/.discovery-cache/{peer_name}.json` for each peer to see verification results.
 
-### Step 2: Identify Missing Capabilities
+### Step 2: Filter Out Local Repos
 
-For each capability in the needs file, check the discovery cache:
+Before evaluating capabilities, inspect each peer entry in `.cross-repo-needs.json`:
+- If the peer has `local: true` → **exclude it entirely** from all further processing. These are add-dir repos whose tasks are already incorporated into the plan; there is nothing to build in a remote repo.
+- Only process peers where `local` is absent or `local: false`.
+
+Track the count of excluded peers for the output summary.
+
+### Step 3: Identify Missing Capabilities
+
+For each **non-local** peer's capabilities, check the discovery cache:
 - If `exists: true` → skip (already exists in peer)
 - If `exists: false` → include in PRD
 
-### Step 3: Generate PRDs
+### Step 4: Generate PRDs
+
+For each non-local peer with missing capabilities, create `$CLOSEDLOOP_WORKDIR/cross-repo-prd-{peer_name}.md`.
 
-For each peer with missing capabilities, create `$CLOSEDLOOP_WORKDIR/cross-repo-prd-{peer_name}.md`:
+**Guard:** If a capability's parent peer has `local: true`, skip PRD generation for that capability entirely — do not create or modify any PRD file for it.
 
 **IMPORTANT:** Before writing any file, you MUST first attempt to Read it. This is required by Claude Code's safety system:
 1. Try to Read the target file path
@@ -67,7 +77,7 @@ This document describes capabilities needed from **{peer_name}** to support impl
 ...
 ```
 
-### Step 4: Update plan.json
+### Step 5: Update plan.json
 
 **Note:** Read `$CLOSEDLOOP_WORKDIR/plan.json` first before editing it.
 
@@ -91,11 +101,13 @@ PRDS_GENERATED:
 - PRDs written: [list of files]
 - Missing capabilities: [count]
 - Existing capabilities: [count]
+- Local repos skipped: [count]
 - plan.json updated: yes/no
 ```
 
 If no missing capabilities:
 ```
 NO_PRDS_NEEDED:
 - All capabilities exist in peer repos
+- Local repos skipped: [count]
 ```

plugins/code/agents/plan-draft-writer.md

@@ -92,6 +92,14 @@ The `content` field contains the full markdown plan following this structure:
 ## Summary
 [2-3 sentences describing what will be implemented]
 
+## Repositories
+(Only present when CLOSEDLOOP_ADD_DIRS is non-empty)
+
+| Repo | Path | Primary |
+|------|------|---------|
+| primary | /path/to/primary | Yes |
+| secondary-name | /path/to/secondary | No |
+
 ## Acceptance Criteria
 
 | ID | Criterion | Source |
@@ -140,6 +148,7 @@ The `content` field contains the full markdown plan following this structure:
 
 7. **Visual References** (if attachments exist) - Embed images using `![description](attachments/filename.png)` relative path syntax
 Optional: **Architecture Diagrams** using `engineering:mermaid-visualizer` skill.
+Optional: **Repositories** (only when `CLOSEDLOOP_ADD_DIRS` is non-empty) - Table of all repos, placed after Summary. See `## Multi-Repository Plans`.
 
 ## JSON Field Sync
 
@@ -179,6 +188,87 @@ Optional: **Architecture Diagrams** using `engineering:mermaid-visualizer` skill
 Manual tasks do NOT block the automated loop from completing. They are reported at the end for the human to perform.
 </critical_constraint>
 
+## Multi-Repository Plans
+
+**Skip this entire section if `CLOSEDLOOP_ADD_DIRS` is empty or unset.**
+
+When `CLOSEDLOOP_ADD_DIRS` is non-empty, the plan spans multiple repositories. Follow these steps:
+
+### Step M1: Parse Repository Map
+
+Read the `CLOSEDLOOP_REPO_MAP` environment variable (pipe-separated `name=path` entries) to get the list of secondary repos. The primary repo is the main project codebase. Example:
+
+```
+CLOSEDLOOP_REPO_MAP="frontend=/workspace/ui|backend=/workspace/api"
+```
+
+Parse each entry as `{name}={path}`.
+
+### Step M2: Read Per-Repo Code Maps
+
+For each `name=path` entry in `CLOSEDLOOP_REPO_MAP`, read the pre-computed code map if it exists:
+
+```bash
+cat $CLOSEDLOOP_WORKDIR/code-map-{name}.json 2>/dev/null
+```
+
+These files are produced by the pre-explorer agent. Each contains the relevant files and patterns for that repository. Use this information to understand what files in each secondary repo are affected by the plan.
+
+### Step M3: Use `@{repo-name}:path` Prefix for File References
+
+When writing task descriptions that reference files in secondary repos, prefix them with `@{repo-name}:`:
+
+- **Primary repo** (no prefix): `src/components/LoginForm.tsx`
+- **Secondary repo** (with prefix): `@frontend:src/components/LoginForm.tsx`
+- **Another secondary repo**: `@backend:api/routes/auth.py`
+
+This convention makes cross-repo task scope unambiguous. Apply it consistently in all task descriptions, acceptance criteria references, and the Repositories section.
+
+### Step M4: Add `## Repositories` Section to Plan Markdown
+
+Include a `## Repositories` section in the markdown `content` field, placed immediately after `## Summary`:
+
+```markdown
+## Repositories
+
+| Repo | Path | Primary |
+|------|------|---------|
+| primary | /absolute/path/to/primary/repo | Yes |
+| frontend | /workspace/ui | No |
+| backend | /workspace/api | No |
+```
+
+- The primary repo name is derived from the base directory name of the project (or `primary` if ambiguous).
+- Each secondary repo appears as a row with `No` in the Primary column.
+- Use the absolute path as it appears in `CLOSEDLOOP_REPO_MAP`.
+
+### Step M5: Populate `repositories` Field in plan.json
+
+Add an optional `repositories` field to plan.json as an object map keyed by repo short name:
+
+```json
+{
+  "repositories": {
+    "primary": {
+      "path": "/absolute/path/to/primary/repo",
+      "isPrimary": true
+    },
+    "frontend": {
+      "path": "/workspace/ui",
+      "isPrimary": false
+    },
+    "backend": {
+      "path": "/workspace/api",
+      "isPrimary": false
+    }
+  }
+}
+```
+
+Fields per entry:
+- `path`: Absolute filesystem path to the repository root
+- `isPrimary`: `true` only for the primary repo
+
 ## Process
 
 Before writing, analyze in `<analysis>` tags:
@@ -305,6 +395,7 @@ PRD mentions: "Real-time updates from Linear"
 | No Code | Zero code snippets, function signatures, or pseudo-code in task descriptions |
 | Valid JSON | Output is valid JSON with all required fields |
 | JSON Sync | Structured fields match markdown content exactly |
+| Multi-Repo (if applicable) | When `CLOSEDLOOP_ADD_DIRS` is set: `## Repositories` table present in markdown, `repositories` field in plan.json, `@{repo-name}:path` prefix used for secondary repo file references |
 
 ## Completion
 

plugins/code/agents/plan-evaluator.md

@@ -31,7 +31,7 @@ You evaluate whether an implementation plan qualifies for **simple mode** (skipp
 
 ### Step 2: Evaluate Simple Mode
 
-Apply ALL six thresholds. ALL must pass for `simple_mode = true`. Default to `false` when uncertain.
+Apply ALL seven thresholds. ALL must pass for `simple_mode = true`. Default to `false` when uncertain.
 
 | # | Signal | Threshold | Source |
 |---|--------|-----------|--------|
@@ -41,12 +41,14 @@ Apply ALL six thresholds. ALL must pass for `simple_mode = true`. Default to `fa
 | 4 | Open questions count | <= 3 | `plan.json` → `openQuestions.length` |
 | 5 | Forbidden terms | 0 found | `plan.json` → `content` field: search for: database, migration, infra, auth, security, payments, concurrency |
 | 6 | Cross-repo keywords | 0 found | `plan.json` → `content` field: search for: backend, frontend, mobile, api contract, shared library |
+| 7 | Add-dir repos | 0 | Read CLOSEDLOOP_ADD_DIRS from environment; non-empty value forces count >= 1, failing this signal |
 
 **Evaluation rules:**
 - Count PRD words using whitespace splitting (approximate is fine)
 - Forbidden term matching is case-insensitive
 - Cross-repo keyword matching is case-insensitive
 - If any threshold fails, `simple_mode = false`
+- Signal 7 evaluates `CLOSEDLOOP_ADD_DIRS` from the injected environment -- if non-empty (count of pipe-delimited paths >= 1) the signal fails, forcing `simple_mode = false`; if empty or unset the signal passes.
 
 ### Step 3: Select Critics (only if simple_mode = false)
 
@@ -74,7 +76,8 @@ Write `$CLOSEDLOOP_WORKDIR/plan-evaluation.json`:
     "task_count": { "value": N, "threshold": 6, "pass": true | false },
     "open_questions_count": { "value": N, "threshold": 3, "pass": true | false },
     "forbidden_terms": { "value": ["term1", ...], "threshold": 0, "pass": true | false },
-    "cross_repo_keywords": { "value": ["keyword1", ...], "threshold": 0, "pass": true | false }
+    "cross_repo_keywords": { "value": ["keyword1", ...], "threshold": 0, "pass": true | false },
+    "add_dir_repos": { "value": N, "threshold": 0, "pass": true | false }
   },
   "selected_critics": ["critic-name-1", "critic-name-2"],
   "evaluation_summary": "Simple mode: true/false. Reason: ..."