fix: comprehensive documentation and template audit (Highload++ prep)

.claude-plugin/PLUGIN.md

@@ -4,15 +4,15 @@ Official Claude Code plugin for MAP Framework - Modular Agentic Planner with cog
 
 ## What is MAP Framework?
 
-MAP (Modular Agentic Planner) is a cognitive architecture that orchestrates 9 specialized agents to improve code quality through systematic validation and iterative refinement.
+MAP (Modular Agentic Planner) is a cognitive architecture that orchestrates 12 specialized agents to improve code quality through systematic validation and iterative refinement.
 
 **Based on research:**
 - [MAP Paper - Nature Communications (2025)](https://github.com/Shanka123/MAP) — 74% improvement in planning tasks
 - [ACE Paper - arXiv:2510.04618v1](https://arxiv.org/abs/2510.04618v1) — continuous learning from experience
 
 ## Features
 
-### 9 Specialized Agents
+### 12 Specialized Agents
 
 1. **TaskDecomposer** — breaks goals into atomic subtasks
 2. **Actor** — generates code and solutions
@@ -21,8 +21,11 @@ MAP (Modular Agentic Planner) is a cognitive architecture that orchestrates 9 sp
 5. **Evaluator** — scores solution quality (functionality, security, testability)
 6. **Reflector** — extracts lessons from successes and failures
 7. **Curator** — manages knowledge base (playbook)
-8. **Orchestrator** — coordinates all agents
-9. **DocumentationReviewer** — checks documentation completeness
+8. **DocumentationReviewer** — checks documentation completeness
+9. **Debate-Arbiter** — cross-evaluates variants with reasoning (Opus)
+10. **Synthesizer** — merges multiple variants (Self-MoA)
+11. **Research-Agent** — isolated codebase research
+12. **Final-Verifier** — adversarial verification (Ralph Loop)
 
 ### Claude Code Integration
 
@@ -33,11 +36,17 @@ MAP (Modular Agentic Planner) is a cognitive architecture that orchestrates 9 sp
 - `session-init` — loads ACE playbook at session start
 - `track-metrics` — tracks agent performance
 
-**4 Slash Commands:**
-- `/map-feature` — implement new features with full MAP workflow
+**10 Slash Commands:**
+- `/map-efficient` — implement features, refactor code, complex tasks with full MAP workflow
 - `/map-debug` — debug issues using MAP analysis
-- `/map-refactor` — refactor code with impact analysis
+- `/map-fast` — small, low-risk changes with minimal overhead
+- `/map-debate` — multi-variant synthesis with Opus arbiter
 - `/map-review` — comprehensive review of changes
+- `/map-check` — quality gates and verification
+- `/map-plan` — architecture decomposition
+- `/map-release` — release workflow with validation gates
+- `/map-resume` — resume interrupted workflows
+- `/map-learn` — extract and preserve lessons
 
 ### ACE Learning System
 
@@ -97,14 +106,14 @@ cp map-framework/.claude/settings.hooks.json your-project/.claude/
 ## Quick Start
 
 ```bash
-# Feature development
-/map-feature implement user authentication with JWT tokens
+# Feature development / refactoring / complex tasks
+/map-efficient implement user authentication with JWT tokens
 
 # Debugging
 /map-debug fix the API 500 error on login endpoint
 
-# Refactoring
-/map-refactor refactor UserService class with dependency injection
+# Small, low-risk changes
+/map-fast add environment variable for API timeout
 
 # Code review
 /map-review review the recent changes in auth.py

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "id": "map-framework",
       "name": "MAP Framework",
       "version": "1.0.0",
-      "description": "Modular Agentic Planner - Cognitive architecture for AI agents inspired by prefrontal cortex functions. Orchestrates 9 specialized agents for development with automatic quality validation.",
+      "description": "Modular Agentic Planner - Cognitive architecture for AI agents inspired by prefrontal cortex functions. Orchestrates 12 specialized agents for development with automatic quality validation.",
       "author": "azalio",
       "license": "MIT",
       "source": "github:azalio/map-framework",
@@ -32,10 +32,10 @@
         "development"
       ],
       "features": [
-        "9 specialized agents (TaskDecomposer, Actor, Monitor, Predictor, Evaluator, Reflector, Curator, Orchestrator, DocumentationReviewer)",
+        "12 specialized agents (TaskDecomposer, Actor, Monitor, Predictor, Evaluator, Reflector, Curator, DocumentationReviewer, Debate-Arbiter, Synthesizer, Research-Agent, Final-Verifier)",
         "ACE learning system with persistent knowledge base",
         "5 Claude Code hooks for automation",
-        "4 slash commands (/map-feature, /map-debug, /map-refactor, /map-review)",
+        "10 slash commands (/map-efficient, /map-debug, /map-fast, /map-debate, /map-review, /map-check, /map-plan, /map-release, /map-resume, /map-learn)",
         "Professional code review integration",
         "Cost optimization (40-60% savings)"
       ],

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "map-framework",
   "version": "1.0.0",
-  "description": "Modular Agentic Planner (MAP) - Cognitive architecture for AI agents with 9 specialized agents, ACE learning system, and professional code review integration",
+  "description": "Modular Agentic Planner (MAP) - Cognitive architecture for AI agents with 12 specialized agents, ACE learning system, and professional code review integration",
   "author": "azalio",
   "license": "MIT",
   "repository": "https://github.com/azalio/map-framework",
@@ -34,10 +34,10 @@
     ]
   },
   "features": [
-    "9 specialized MAP agents (TaskDecomposer, Actor, Monitor, Predictor, Evaluator, Reflector, Curator, Orchestrator, DocumentationReviewer)",
+    "12 specialized MAP agents (TaskDecomposer, Actor, Monitor, Predictor, Evaluator, Reflector, Curator, DocumentationReviewer, Debate-Arbiter, Synthesizer, Research-Agent, Final-Verifier)",
     "ACE (Agentic Context Engineering) learning system with persistent knowledge base",
     "5 Claude Code hooks for automation (validate-agent-templates, auto-store-knowledge, enrich-context, session-init, track-metrics)",
-    "4 slash commands (/map-feature, /map-debug, /map-refactor, /map-review)",
+    "10 slash commands (/map-efficient, /map-debug, /map-fast, /map-debate, /map-review, /map-check, /map-plan, /map-release, /map-resume, /map-learn)",
     "Professional code review with claude-reviewer MCP",
     "Chain-of-thought reasoning with sequential-thinking MCP",
     "Semantic pattern search with embeddings cache",
@@ -70,9 +70,9 @@
       "documentation-reviewer"
     ],
     "commands": [
-      "map-feature",
+      "map-efficient",
       "map-debug",
-      "map-refactor",
+      "map-fast",
       "map-review"
     ],
     "hooks": [

.claude/agents/actor.md

@@ -271,15 +271,15 @@ Task(
 
 # Required Output Structure
 
-**CRITICAL: Actor outputs CODE AS TEXT, NOT file edits**
+**Actor applies code directly using Edit/Write tools.**
 
-You are a **proposal generator**, NOT a code executor. Your output is reviewed by Monitor before application.
+You are a code implementer. Read affected files, then apply changes with Edit/Write tools.
+Monitor will validate the written code afterward.
 
-- ✅ DO: Output complete code in markdown code blocks
-- ❌ NEVER: Use Edit, Write, or MultiEdit tools
-- ❌ NEVER: Modify files directly
-- 📋 WHY: workflow-gate.py will BLOCK Edit/Write until actor+monitor steps complete
-- 🔄 FLOW: You output → Monitor reviews → Orchestrator applies with Edit/Write
+- Use Edit tool for modifying existing files
+- Use Write tool for creating new files
+- Read files before editing to understand current state
+- Apply changes incrementally — one logical change per Edit call
 
 ---
 
@@ -422,7 +422,7 @@ Only include if changes affect:
 ## Pre-Submission Checklist
 
 ### Code Quality (Mandatory)
-- [ ] Follows {{standards_url}} style guide
+- [ ] Follows {{standards_doc}} style guide
 - [ ] Complete implementations (no placeholders, no `...`)
 - [ ] Self-documenting names (clear variables/functions)
 - [ ] Comments for complex logic only
@@ -502,6 +502,29 @@ When assessing performance impact, use these as default baselines unless project
 
 **Protocol**: Document rationale → Add TODO if needed → Proceed
 
+### Evidence File (Artifact-Gated Validation)
+
+After applying all code changes, write an evidence file so the orchestrator can verify this step ran. Use Bash (not Write tool) to create the file:
+
+```bash
+cat > .map/<branch>/evidence/actor_<subtask_id>.json << 'EVIDENCE'
+{
+  "phase": "ACTOR",
+  "subtask_id": "<subtask_id>",
+  "timestamp": "<ISO 8601 UTC>",
+  "summary": "<one-line description of what was implemented>",
+  "aag_contract": "<the AAG contract line>",
+  "files_changed": ["<list of modified file paths>"],
+  "status": "applied"
+}
+EVIDENCE
+```
+
+**Required fields** (orchestrator validates these): `phase`, `subtask_id`, `timestamp`.
+Other fields are informational but recommended for audit trail.
+
+**CRITICAL**: Without this file, `validate_step("2.3")` will reject the step.
+
 </Actor_Quality_v3_1>
 
 ---
@@ -670,8 +693,8 @@ output:
 - **Project**: {{project_name}}
 - **Language**: {{language}}
 - **Framework**: {{framework}}
-- **Standards**: {{standards_url}}
-- **Branch**: {{branch}}
+- **Standards**: {{standards_doc}}
+- **Branch**: {{branch_name}}
 - **Allowed Scope**: {{allowed_scope}}
 - **Related Files**: {{related_files}}
 
@@ -733,7 +756,7 @@ output:
 
 Follow this protocol exactly — do not infer "how seniors write" or add stylistic flourishes.
 
-1. **Style standard**: Use {{standards_url}}. If unavailable: Python→PEP8, JS/TS→Google Style, Go→gofmt, Rust→rustfmt.
+1. **Style standard**: Use {{standards_doc}}. If unavailable: Python→PEP8, JS/TS→Google Style, Go→gofmt, Rust→rustfmt.
 2. **Architecture**: Dependency injection where applicable. No global mutable state.
 3. **Naming**: Self-documenting (`user_count` not `n`, `is_valid` not `flag`). No abbreviations except industry-standard ones (URL, HTTP, ID).
 4. **Intent comments**: Add a one-line `# Intent: <why>` comment above any non-obvious logic block. Do NOT comment obvious code.

.claude/agents/debate-arbiter.md

@@ -3,7 +3,7 @@ name: debate-arbiter
 description: Cross-evaluates Actor variants with explicit reasoning and synthesizes optimal solution (MAP Debate)
 model: opus
 version: 1.0.0
-last_updated: 2025-01-08
+last_updated: 2026-02-14
 ---
 
 # QUICK REFERENCE (Read First)

.claude/agents/documentation-reviewer.md

@@ -444,7 +444,7 @@ mcp__deepwiki__ask_question(
 # 4. Check historical patterns (if mem0 available)
 mcp__mem0__map_tiered_search(
     query="CRD installation documentation patterns",
-    top_k=5,
+    limit=5,
     similarity_threshold=0.7
 )
 ```

.claude/agents/final-verifier.md

@@ -18,36 +18,36 @@ You catch premature completion and hallucinated success.
 
 | Data | Source | How to Read |
 |------|--------|-------------|
-| Original Goal | `.map/task_plan_<branch>.md` | Section "## Goal" or first paragraph |
-| Acceptance Criteria | `.map/task_plan_<branch>.md` | Section "## Acceptance Criteria" (table) |
-| Completed Subtasks | `.map/progress_<branch>.md` | Checkboxes marked `[x]` |
+| Original Goal | `.map/<branch>/task_plan_<branch>.md` | Section "## Goal" or first paragraph |
+| Acceptance Criteria | `.map/<branch>/task_plan_<branch>.md` | Section "## Acceptance Criteria" (table) |
+| Completed Subtasks | `.map/<branch>/progress_<branch>.md` | Checkboxes marked `[x]` |
 | Global Validation | Task argument `$VALIDATION_CRITERIA` | Passed from map-efficient.md |
 
 ### OUTPUT Destinations (where to store results)
 
 | Data | Destination | Format | Written By |
 |------|-------------|--------|------------|
-| Verification Result | `.map/progress_<branch>.md` | Append "## Final Verification" section | **final-verifier agent** |
+| Verification Result | `.map/<branch>/progress_<branch>.md` | Append "## Final Verification" section | **final-verifier agent** |
 | Structured Result | `.map/<branch>/final_verification.json` | JSON (for programmatic access) | **final-verifier agent** |
 | Root Cause (if failed) | `.map/<branch>/final_verification.json` | In `root_cause` field | **final-verifier agent** |
 
 **WHO WRITES FILES:**
 - **final-verifier agent** writes verification results to BOTH markdown and JSON
 - **Orchestrator (map-efficient.md)** reads results and decides next action (COMPLETE/RE_DECOMPOSE/ESCALATE)
-- **Orchestrator (map-efficient.md)** ensures Acceptance Criteria section exists in `task_plan_<branch>.md` (derived from decomposition output)
+- **Orchestrator (map-efficient.md)** ensures Acceptance Criteria section exists in `.map/<branch>/task_plan_<branch>.md` (derived from decomposition output)
 
 **IMPORTANT:** Always use sanitized branch name (e.g., `feature-foo` not `feature/foo`).
 
 **SOURCE OF TRUTH CONTRACT:**
 - `.map/<branch>/final_verification.json` is the **ONLY** source of truth for orchestrator decisions
-- `.map/progress_<branch>.md` "## Final Verification" section is for **human readability only**
+- `.map/<branch>/progress_<branch>.md` "## Final Verification" section is for **human readability only**
 - **Orchestrator (map-efficient.md) MUST read JSON**, not parse markdown
 - Both must be written, but only JSON is used programmatically
 
 ## Verification Protocol
 
 ### Step 1: Goal Extraction
-Read `.map/task_plan_<branch>.md` to extract:
+Read `.map/<branch>/task_plan_<branch>.md` to extract:
 - Original goal from "## Goal" section
 - Acceptance criteria from "## Acceptance Criteria" table (if present)
 
@@ -101,7 +101,7 @@ Score confidence (0.0-1.0):
 
 **CRITICAL:** `root_cause` is REQUIRED if `passed=false`
 
-### 2. Append to `.map/progress_<branch>.md`
+### 2. Append to `.map/<branch>/progress_<branch>.md`
 
 ```markdown
 ## Final Verification

.claude/agents/monitor.md

@@ -94,8 +94,8 @@ If implementation deviates from the AAG contract — `valid: false` — regardle
 |-------------|------|-------------|---------|
 | `{{project_name}}` | string | Project identifier | `"auth-service"` |
 | `{{language}}` | enum | Primary language | `"python"`, `"typescript"`, `"go"` |
-| `{{solution}}` | string | Code/docs to review | Full code block or diff |
-| `{{requirements}}` | string | Subtask requirements | "Implement JWT validation" |
+| `{{solution}}` | string | Code/docs to review (in MAP workflow: provided via `<MAP_Written>` tag) | Full code block or diff |
+| `{{requirements}}` | string | Subtask requirements (in MAP workflow: provided via `<MAP_Contract>` tag) | "Implement JWT validation" |
 | `{{review_mode}}` | enum | Review scope mode | `"full"` or `"diff"` |
 
 ### Optional Placeholders
@@ -105,6 +105,7 @@ If implementation deviates from the AAG contract — `valid: false` — regardle
 | `{{framework}}` | string | `""` | Framework/runtime (Express, FastAPI, etc.) |
 | `{{standards_doc}}` | string | `""` | URL/path to style guide |
 | `{{security_policy}}` | string | `""` | URL/path to security policy |
+| `{{changed_files}}` | array | `[]` | List of modified file paths (for static analysis) |
 | `{{subtask_description}}` | string | `""` | Additional context |
 | `{{existing_patterns}}` | array | `[]` | Learned patterns from previous reviews |
 | `{{feedback}}` | array | `[]` | Previous review findings to verify |
@@ -2494,3 +2495,27 @@ def check_rate_limit(user_id, action, limit=100, window=3600):
 - Only MEDIUM/LOW issues → valid=true (with feedback)
 
 </Monitor_Critical_Reminders>
+
+### Evidence File (Artifact-Gated Validation)
+
+**Exception to read-only rule**: Monitor writes evidence files to `.map/` artifacts directory via Bash (not Write tool). This does NOT violate the read-only-for-project-code rule — `.map/` is a workflow artifact directory, not project code.
+
+After completing validation, write an evidence file:
+
+```bash
+cat > .map/<branch>/evidence/monitor_<subtask_id>.json << 'EVIDENCE'
+{
+  "phase": "MONITOR",
+  "subtask_id": "<subtask_id>",
+  "timestamp": "<ISO 8601 UTC>",
+  "valid": true,
+  "issues_found": <number of issues>,
+  "recommendation": "approve|reject|revise"
+}
+EVIDENCE
+```
+
+**Required fields** (orchestrator validates these): `phase`, `subtask_id`, `timestamp`.
+Other fields are informational but recommended for audit trail.
+
+**CRITICAL**: Without this file, `validate_step("2.4")` will reject the step.

.claude/agents/predictor.md

@@ -124,16 +124,16 @@ CONFLICT (Category B: -0.10):
 
 ### Position in MAP Pipeline
 ```
-Actor (propose changes)
-    ↓ analyzer_output
+Actor (implement changes)
+    ↓ code changes applied
+Monitor (validate correctness)
+    ↓ validation_result
 PREDICTOR (assess impact) ← YOU ARE HERE
     ↓ prediction_output
-Monitor (validate at runtime)
-    ↓ validation_result
-Evaluator (score quality)
+[Evaluator — only in /map-debug and /map-review]
 ```
 
-### Upstream (Actor → Predictor)
+### Upstream (Actor → Monitor → Predictor)
 **Input Contract Version**: 1.0
 
 | Field from Actor | How Predictor Uses It |
@@ -1784,6 +1784,28 @@ When an edge case is detected, it MUST appear in THREE places:
 
 </output_format>
 
+### Evidence File (Artifact-Gated Validation)
+
+After completing impact analysis, write an evidence file via Bash:
+
+```bash
+cat > .map/<branch>/evidence/predictor_<subtask_id>.json << 'EVIDENCE'
+{
+  "phase": "PREDICTOR",
+  "subtask_id": "<subtask_id>",
+  "timestamp": "<ISO 8601 UTC>",
+  "risk_assessment": "<low|medium|high|critical>",
+  "confidence_score": <0.30-0.95>,
+  "tier_selected": "<1|2|3>"
+}
+EVIDENCE
+```
+
+**Required fields** (orchestrator validates these): `phase`, `subtask_id`, `timestamp`.
+Other fields are informational but recommended for audit trail.
+
+**CRITICAL**: Without this file, `validate_step("2.6")` will reject the step.
+
 <confidence_calculation>
 
 ## Confidence Scoring Methodology