@techwavedev/agi-agent-kit 1.6.4 → 1.7.0

package/CHANGELOG.md

@@ -5,6 +5,54 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [1.7.0] - 2026-03-22
+
+### Added
+
+- **Parallel Agent Isolation via Git Worktrees** (`execution/worktree_isolator.py`) — Full worktree lifecycle management for parallel agent dispatch. 7 commands: `create`, `create-all`, `merge`, `merge-all`, `cleanup`, `status`, `validate-partitions`. Branch naming: `worktree/{run_id}/{agent}`. Auto-copies `.env` files to worktrees. Worktrees placed in `/tmp/agi-worktrees/<project>/` for performance on cloud-synced filesystems (Synology Drive).
+- **Parallel Dispatch Mode** (`execution/dispatch_agent_team.py`) — New `--parallel` and `--partitions` flags for running sub-agents in parallel using git worktree isolation. File partition validation prevents agents from editing the same files. Manifest enriched with worktree paths and branches per sub-agent. Exit code 5 for partition overlap.
+- **Cloud Automation Directive** (`directives/cloud_automation.md`) — 4-tier automation SOP: Tier 1 Local Agent (Claude Code CLI), Tier 2 Claude Cowork (desktop VM with skills/MCP/scheduling), Tier 3 Cloud Tasks (24/7 scheduled on Anthropic servers), Tier 4 Channels (Telegram/Discord bot). Full automation patterns for hands-free dev cycles, mobile-first control, and project bootstrap.
+- **Cowork Project Bootstrap** (`skills/cowork-export/SKILL.md`) — New "Project Bootstrap Pattern" for delegating full project creation to Claude Cowork. Includes framework structure embedding, constraint passing, and pull-back workflow. Added 5 common automation project ideas.
+- **Session Close Protocol** (`execution/session_wrapup.py`) — End-of-session script that reviews Qdrant activity, verifies memory stores, optionally broadcasts accomplishments to other agents, and flags stale `.tmp/` files. Counterpart to `session_boot.py`.
+- **Skill Evaluation Script** (`skill-creator/scripts/evaluate_skill.py`) — Automated structural evaluation of skills against binary criteria (YAML frontmatter, line count, naming convention, script executability, etc.) with Qdrant storage for historical trend tracking.
+- **Progressive Disclosure Rule** — `SKILL.md` files must stay under 200 lines; overflow content goes into `references/` files.
+- **Mermaid Context Compression** — Added best practice rule to use Mermaid diagrams instead of verbose textual descriptions of architecture to reduce token usage.
+- **Security Team** (`directives/teams/security_team.md`) — New mandatory pre-release agent team with 3 sequential sub-agents: `secret-scanner` (enhanced regex + Shannon entropy + dangerous file detection), `dependency-auditor` (npm audit + license compliance), `code-security-reviewer` (OWASP Top 10 static analysis with CWE tags). Any critical/high finding blocks the release.
+- **Security Scan Script** (`execution/security_scan.py`) — Deterministic security scanner with 4 modes: `secrets`, `dependencies`, `code`, `all`. Supports 16 secret patterns, entropy analysis, npm audit integration, license compliance checks, and 16 OWASP code patterns across Python and JavaScript. Exit code 2 = release blocked, 3 = warnings only.
+- **Security Sub-Agents** — `secret_scanner.md`, `dependency_auditor.md`, `code_security_reviewer.md` in `directives/subagents/`.
+
+### Changed
+
+- **AGENTS.md** — Added Parallel Dispatch with Worktree Isolation section, Cloud Automation section (tier table, Cowork integration, full automation patterns), Session Close Protocol, `evaluate_skill.py` command reference, progressive disclosure enforcement, and Mermaid context compression examples. Added `directives/cloud_automation.md` to Key Directives table. Updated Pattern Reference with "Parallel sub-agents (worktree)".
+- **Multi-LLM Collaboration** (`directives/multi_llm_collaboration.md`) — Added "Pattern 5: Parallel Worktree Isolation (Same Machine)" with architecture diagram, key rules, Claude Code `isolation: "worktree"` integration, dispatch command examples, and edge cases for merge conflicts and orphaned worktrees.
+- **Subagent-Driven Development** (`templates/skills/extended/ai-agents/subagent-driven-development/SKILL.md`) — Added parallel mode comparison, full "Parallel Dispatch with Worktree Isolation" section with prerequisites, workflow, Claude Code Agent tool usage, and decision matrix.
+- **`.gitignore`** — Added `.worktrees/` exclusion for agent worktree directories.
+- **Release Gate** (`.agent/scripts/release_gate.py`) — Now runs the full Security Team scan (`execution/security_scan.py all`) as a mandatory final check. Release is blocked if any critical/high security findings are detected.
+- **Publish Workflow** (`.agent/workflows/publish-npm.md`) — Added Step 3 "Security Team Review" as mandatory gate before version bump. Renumbered steps 4-10.
+
+### Documentation
+
+- **`docs/execution/worktree_isolator.md`** — New. Full reference for worktree isolation commands, flags, exit codes, and edge cases.
+- **`docs/execution/dispatch_agent_team.md`** — New. Updated dispatch documentation covering parallel mode, partitions, and worktree integration.
+- **`docs/directives/cloud_automation.md`** — New. Summary doc pointing to the 4-tier cloud automation directive.
+
+## [1.6.5] - 2026-03-19
+
+### Added
+- **Skill Self-Improvement (Karpathy Loop)** — Autonomous test → improve → commit/reset cycle for continuous skill quality improvement. Inspired by Andrej Karpathy's "auto-research" concept:
+  - `execution/run_skill_eval.py` — Binary assertion runner with 18 assertion types (`contains`, `regex_match`, `max_words`, `has_yaml_frontmatter`, `no_trailing_whitespace`, etc.)
+  - `execution/karpathy_loop.py` — Autonomous loop orchestrator with git commit/reset integration, dry-run mode, and status reporting
+  - `eval/evals.json` standard — Structured binary assertion format for objective skill quality measurement
+- **Skill Creator: Step 8** — Added "Self-Improvement Loop (Karpathy Loop)" step to `SKILL_skillcreator.md` with methodology, assertion examples, and auto-generation guidance
+- **Eval Directory Scaffolding** — `init_skill.py` now creates `eval/evals.json` with 4 starter assertions (frontmatter, description quality, structure, no-placeholders) for every new skill
+- **Example evals** — `skills/qdrant-memory/eval/evals.json` added as reference implementation (17/17 passing)
+
+### Documentation
+
+- **`AGENTS.md`** — Added "Skill Self-Improvement (Karpathy Loop)" section with quick start commands, assertion types reference, and key rules. Updated directory structure to show `eval/`. Added eval scripts to Key Scripts section.
+
 ## [1.6.4] - 2026-03-14
 
 ### Fixed

package/README.md

@@ -95,6 +95,7 @@ python3 skills/plugin-discovery/scripts/platform_setup.py --project-dir .
 | **TDD Enforcement**           | Iron-law RED-GREEN-REFACTOR cycle — no production code without failing test                   |
 | **Verification Gates**        | Evidence before claims — no completion without fresh verification output                      |
 | **Self-Healing Workflows**    | Agents read error logs, patch scripts, and update directives automatically                    |
+| **Skill Self-Improvement**    | Karpathy Loop: autonomous test → improve → commit/reset cycle with 18 binary assertion types  |
 | **One-Shot Setup**            | Platform detection + project stack scan + auto-configuration in one command                   |
 
 ---
@@ -608,6 +609,7 @@ If these community skills help you, consider [starring the original repo](https:
 | **MCP Compatibility**               | ✅ Shipped    | Memory + cross-agent coordination exposed as MCP tools via `execution/mcp_server.py` (13 tools) and `skills/qdrant-memory/mcp_server.py` (6 tools). Pure chat clients (Claude Desktop) get full memory access. ([docs](./docs/mcp-compatibility.md)) |
 | **Platform-Adaptive Orchestration** | ✅ Shipped    | 10 platforms share one `AGENTS.md` via symlinks (Claude Code, Gemini CLI, Codex CLI, Cursor, Copilot, OpenCode, AdaL, Antigravity, OpenClaw, Kiro). Each uses its native orchestration strategy automatically.           |
 | **Workflow Engine**                 | ✅ Shipped    | `execution/workflow_engine.py` executes `data/workflows.json` playbooks as guided multi-skill sequences with progress tracking, skip/abort, and state persistence in `.tmp/playbook_state.json`.                         |
+| **Skill Self-Improvement**          | ✅ Shipped    | Karpathy Loop: `run_skill_eval.py` (18 binary assertion types) + `karpathy_loop.py` (autonomous test/improve/commit/reset). Skills include `eval/evals.json` for objective quality measurement.                           |
 | **Control Tower Orchestrator**      | 🚧 Active    | Basic dispatcher for agent registration and heartbeat via Qdrant (`control_tower.py`). Needs dedicated docs, test coverage, and integration with `session_boot`.                                                          |
 | **Secrets Management (Vault)**      | 🔬 Design    | HashiCorp Vault integration for secure secret sharing. Agents authenticate via Ed25519 keypair, access tenant-scoped secrets. Zero long-lived credentials.                                                                |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techwavedev/agi-agent-kit",
-  "version": "1.6.4",
+  "version": "1.7.0",
   "description": "Enterprise-Grade Agentic Framework - Modular skill-based AI assistant toolkit with deterministic execution, semantic memory, and platform-adaptive orchestration.",
   "bin": {
     "agi-agent-kit": "./bin/init.js"

package/templates/base/AGENTS.md

@@ -234,6 +234,30 @@ python3 execution/memory_manager.py cache-store \
   --response "The complete response that was generated"
 ```
 
+#### Session Close Protocol (MANDATORY)
+
+At the end of a work session, run the wrap-up script to verify cleanup and formally commit all contextual learnings to the shared cross-agent memory:
+
+```bash
+python3 execution/session_wrapup.py --auto-broadcast
+```
+
+**What it does:**
+
+1. **Reviews session activity** — queries Qdrant for memories stored in the last 60 minutes
+2. **Verifies memory stores** — warns if zero decisions/learnings were stored (protocol violation)
+3. **Broadcasts to all agents** — calls `cross_agent_context.py store` so other LLMs see what was accomplished
+4. **Checks stale .tmp/ files** — lists files older than 24h for manual cleanup
+5. **Updates Control Tower** — marks session as ended in the orchestrator
+
+**Options:**
+
+```bash
+python3 execution/session_wrapup.py --agent gemini --project myapp --since 90 --json
+```
+
+**Exit codes:** 0 = clean wrapup, 1 = zero stores warning, 2 = memory unreachable
+
 #### Proving Usage (Auditable)
 
 To verify the agent is actually using memory:
@@ -398,7 +422,8 @@ project/
 │   └── <skill-name>/
 │       ├── SKILL.md      # Skill instructions and triggers
 │       ├── scripts/      # Executable tools
-│       └── references/   # Documentation loaded on-demand
+│       ├── references/   # Documentation loaded on-demand
+│       └── eval/         # Binary assertions for self-improvement (evals.json)
 └── AGENTS.md             # This file (symlinked as CLAUDE.md, GEMINI.md)
 ```
 
@@ -406,15 +431,23 @@ project/
 
 Skills are modular packages that extend agent capabilities with specialized workflows, scripts, and domain knowledge. Each skill contains:
 
-- **SKILL.md** — Instructions with YAML frontmatter (`name`, `description`) for triggering
+- **SKILL.md** — Instructions with YAML frontmatter (`name`, `description`) for triggering. **Must be under 200 lines.** Use progressive disclosure by linking to reference files.
 - **scripts/** — Deterministic tools the agent can execute
-- **references/** — Documentation loaded only when needed
+- **references/** — Documentation loaded only when needed (to prevent token bloat)
 
 **Key Resources:**
 
 - **Skills Catalog:** `skills/SKILLS_CATALOG.md` — Complete documentation of all available skills
 - **Skill Creator Guide:** `skill-creator/SKILL_skillcreator.md` — How to create new skills
 
+**Progressive Disclosure Rules (MANDATORY):**
+
+- `SKILL.md` MUST be under 200 lines — it is a process router, not an encyclopedia
+- Put step-by-step instructions, output formatting, and routing logic in `SKILL.md`
+- Put deep knowledge, long examples, brand context, and frameworks in `references/`
+- Claude loads reference files only when `SKILL.md` explicitly tells it to, then unloads them
+- YAML frontmatter MUST include `name` (hyphen-case) and `description` (trigger conditions)
+
 **Commands:**
 
 ```bash
@@ -423,11 +456,19 @@ python3 skill-creator/scripts/init_skill.py <name> --path skills/
 
 # Update the skills catalog (MANDATORY after any skill change)
 python3 skill-creator/scripts/update_catalog.py --skills-dir skills/
+
+# Evaluate a skill against structural criteria (Skills 2.0)
+python3 skill-creator/scripts/evaluate_skill.py \
+  --skill-path skills/<name> \
+  --test-input "test prompt" \
+  --criteria '["SKILL.md exists", "Has YAML frontmatter", "Under 200 lines", "Has references/ directory"]'
 ```
 
+The evaluation stores results in Qdrant for cross-agent visibility and tracks historical pass rates.
+
 ### Deliverables vs. Intermediates
 
-| Type              | Location       | Examples                                             |
+| Type              | Location       | VExamples                                             |
 | ----------------- | -------------- | ---------------------------------------------------- |
 | **Deliverables**  | Cloud services | Google Sheets, Slides, Drive files, database records |
 | **Intermediates** | `.tmp/`        | Scraped HTML, processed JSON, temp exports           |
@@ -542,6 +583,42 @@ When a user says `/playbook`, "run a playbook", or asks for a multi-step workflo
 
 ---
 
+## Skill Self-Improvement (Karpathy Loop)
+
+Skills can autonomously improve their quality using the **Karpathy Loop** — an iterative cycle of test → change → eval → commit/reset.
+
+> Inspired by Andrej Karpathy's "auto-research" concept. See `skill-creator/SKILL_skillcreator.md` Step 8 for full methodology.
+
+### Quick Start
+
+```bash
+# Check current skill quality
+python3 execution/run_skill_eval.py --evals skills/my-skill/eval/evals.json --verbose
+
+# See failing assertions for a skill
+python3 execution/karpathy_loop.py --skill skills/my-skill --status-only
+
+# Run autonomous improvement loop
+python3 execution/karpathy_loop.py --skill skills/my-skill --max-iterations 10
+```
+
+### How It Works
+
+1. Each skill has `eval/evals.json` with **binary assertions** (true/false only)
+2. `run_skill_eval.py` runs assertions and reports pass rate
+3. `karpathy_loop.py` orchestrates: agent edits SKILL.md → run evals → `git commit` if improved, `git reset` if not
+4. Loop continues until perfect score or max iterations
+
+### Assertion Types
+
+`contains`, `not_contains`, `max_words`, `min_words`, `max_lines`, `min_lines`, `regex_match`, `regex_not_match`, `starts_with`, `ends_with`, `has_yaml_frontmatter`, `no_consecutive_blank_lines`, `max_chars`, `min_chars`, `contains_all`, `contains_any`, `line_count_equals`, `no_trailing_whitespace`
+
+### Key Rule
+
+Only use **binary assertions** — never subjective. `"max_words": 300` ✅, "Is the text good?" ❌.
+
+---
+
 ## Best Practices for Directives and Markdown (Token Optimization)
 
 Markdown files containing instructions, SOPs, and documentation (`.md`) are fed directly into the model's context window. **Long, extended markdown files waste precious tokens and dilute the agent's focus**, making it less effective.
@@ -552,6 +629,12 @@ Markdown files containing instructions, SOPs, and documentation (`.md`) are fed
 2. **Modularize Large Files**: If a directive or documentation file exceeds 1,500 words or 10,000 bytes, split it into smaller, logically separated files and use parent-child references.
 3. **Prefer Examples Over Prose**: Use concise input/output examples rather than verbose textual descriptions of how something should work.
 4. **Remove Filler**: Eliminate conversational filler, redundant instructions, and obvious statements. Focus on the *what* and the *how*.
+5. **Use Mermaid Context Compression**: Replace long, verbose textual descriptions of system architectures, folder structures, or process workflows with lightweight Mermaid diagrams. A Mermaid diagram costs a few hundred tokens; the same information as prose costs thousands. LLMs parse structured diagrams more efficiently than block paragraphs. Example — instead of a 20-line text description of a 5-step workflow, use:
+
+   ```mermaid
+   graph LR
+     A[Input] --> B[Process] --> C[Validate] --> D[Store] --> E[Output]
+   ```
 
 ---
 
@@ -764,6 +847,12 @@ python3 execution/cross_agent_context.py broadcast --agent "<name>" --message "<
 
 # Cross-agent: check pending handoffs
 python3 execution/cross_agent_context.py pending --agent "<name>" --project agi-agent-kit
+
+# Skill eval: run binary assertions
+python3 execution/run_skill_eval.py --evals skills/<skill>/eval/evals.json --verbose
+
+# Skill self-improvement: Karpathy Loop
+python3 execution/karpathy_loop.py --skill skills/<skill> --status-only
 ```
 
 ### MCP Servers

package/templates/base/CHANGELOG.md

@@ -5,10 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.6.3] - 2026-03-14
+## [1.7.0] - 2026-03-22
 
 ### Added
 
+- **Parallel Agent Isolation via Git Worktrees** — Full worktree lifecycle management for parallel agent dispatch.
+- **Parallel Dispatch Mode** — `--parallel` and `--partitions` flags for worktree-isolated parallel execution.
+- **Cloud Automation 4-Tier Architecture** — Local Agent, Cowork, Cloud Tasks, Channels.
+- **Cowork Project Bootstrap** — Delegate full project creation to Claude Cowork.
+- **Session Close Protocol** — End-of-session wrapup with memory verification.
+- **Skill Evaluation Script** — Automated structural evaluation with Qdrant storage.
+
+## [1.6.5] - 2026-03-19
+
+### Added
+
+- **Skill Self-Improvement (Karpathy Loop)** — Autonomous test → improve → commit/reset cycle.
+
+## [1.6.4] - 2026-03-14
+
+### Fixed
+
+- **CI publish pipeline** — `release_gate.py` no longer hangs on interactive prompts in CI.
+
+## [1.6.3] - 2026-03-14
+
+### Added
 - **MCP Compatibility Layer** — The framework is now consumable as MCP servers by Claude Desktop, Antigravity, Cursor, Copilot, OpenCode, OpenClaw, and any MCP-compatible client. Two servers provided:
   - `execution/mcp_server.py` (`agi-framework`) — 13 tools covering the full execution layer: memory auto-query, store, retrieve, cache, list, cross-agent coordination (store/sync/status/handoff/broadcast/pending), and session health check.
   - `skills/qdrant-memory/mcp_server.py` (`qdrant-memory`) — 6 tools wrapping the skill's Python modules directly (no subprocess, no external package).

package/templates/base/execution/session_wrapup.py

@@ -0,0 +1,377 @@
+#!/usr/bin/env python3
+"""
+Script: session_wrapup.py
+Purpose: Session Close Protocol. Reviews session activity, verifies memory stores,
+         broadcasts accomplishments to other agents, and checks for stale temp files.
+
+         This is the LAST script an agent should run before ending a session.
+         Counterpart to session_boot.py (Session Boot Protocol).
+
+Usage:
+    python3 execution/session_wrapup.py
+    python3 execution/session_wrapup.py --json
+    python3 execution/session_wrapup.py --agent gemini --project myapp --since 90
+    python3 execution/session_wrapup.py --auto-broadcast
+
+Arguments:
+    --agent          Agent name (default: "claude")
+    --project        Project name for Qdrant filter
+    --since          How far back to look for session activity in minutes (default: 60)
+    --json           JSON-only output
+    --auto-broadcast Automatically broadcast accomplishments to all agents
+
+Exit Codes:
+    0 - Session wrapped up successfully (memories were stored)
+    1 - Session wrapped up with warnings (zero stores detected)
+    2 - Memory system unreachable
+"""
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import time
+from datetime import datetime, timezone, timedelta
+from pathlib import Path
+from urllib.request import Request, urlopen
+from urllib.error import URLError, HTTPError
+
+# Configuration
+QDRANT_URL = os.environ.get("QDRANT_URL", "http://localhost:6333")
+PROJECT_DIR = Path(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+TMP_DIR = PROJECT_DIR / ".tmp"
+STALE_THRESHOLD_HOURS = 24
+
+
+def get_recent_memories(since_minutes: int = 60, project: str = None) -> dict:
+    """Query Qdrant for memories stored in the last N minutes."""
+    result = {"status": "ok", "memories": [], "count": 0}
+    cutoff = datetime.now(timezone.utc) - timedelta(minutes=since_minutes)
+    cutoff_iso = cutoff.isoformat()
+
+    try:
+        # Scroll through agent_memory collection and filter by timestamp
+        scroll_body = {
+            "limit": 100,
+            "with_payload": True,
+            "with_vector": False,
+        }
+
+        # Build filter: timestamp >= cutoff
+        filter_conditions = []
+        if project:
+            filter_conditions.append(
+                {"key": "project", "match": {"value": project}}
+            )
+
+        if filter_conditions:
+            scroll_body["filter"] = {"must": filter_conditions}
+
+        req = Request(
+            f"{QDRANT_URL}/collections/agent_memory/points/scroll",
+            data=json.dumps(scroll_body).encode(),
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with urlopen(req, timeout=10) as response:
+            data = json.loads(response.read().decode())
+
+        points = data.get("result", {}).get("points", [])
+
+        # Filter by timestamp client-side (Qdrant range filter on ISO strings)
+        recent = []
+        for point in points:
+            payload = point.get("payload", {})
+            ts = payload.get("timestamp", "")
+            if ts and ts >= cutoff_iso:
+                recent.append({
+                    "content": payload.get("content", "")[:200],
+                    "type": payload.get("type", "unknown"),
+                    "timestamp": ts,
+                    "tags": payload.get("tags", []),
+                    "agent_id": payload.get("agent_id", ""),
+                })
+
+        result["memories"] = recent
+        result["count"] = len(recent)
+
+    except (URLError, HTTPError) as e:
+        result["status"] = f"error: {e}"
+    except Exception as e:
+        result["status"] = f"error: {e}"
+
+    return result
+
+
+def verify_memory_stores(since_minutes: int = 60, project: str = None) -> dict:
+    """Check if the agent stored any decisions/learnings during the session."""
+    memories = get_recent_memories(since_minutes, project)
+
+    if memories["status"] != "ok":
+        return {
+            "status": memories["status"],
+            "stores_found": 0,
+            "warning": "Could not verify memory stores",
+        }
+
+    count = memories["count"]
+    types_stored = {}
+    for mem in memories["memories"]:
+        t = mem.get("type", "unknown")
+        types_stored[t] = types_stored.get(t, 0) + 1
+
+    warning = None
+    if count == 0:
+        warning = (
+            "ZERO memories stored this session. "
+            "Per protocol, you MUST store at least one decision/learning per task. "
+            "Run: python3 execution/memory_manager.py store --content '...' --type decision"
+        )
+
+    return {
+        "status": "ok",
+        "stores_found": count,
+        "types": types_stored,
+        "warning": warning,
+    }
+
+
+def summarize_accomplishments(memories: dict) -> list:
+    """Extract a concise list of accomplishments from recent memories."""
+    accomplishments = []
+    for mem in memories.get("memories", []):
+        content = mem.get("content", "").strip()
+        if content:
+            # Strip agent prefix if present (e.g., "[CLAUDE] ...")
+            if content.startswith("[") and "]" in content:
+                content = content[content.index("]") + 1:].strip()
+            accomplishments.append(content)
+    return accomplishments
+
+
+def broadcast_session(agent: str, accomplishments: list, project: str = None) -> dict:
+    """Call cross_agent_context.py store to log session accomplishments."""
+    if not accomplishments:
+        return {"status": "skipped", "reason": "no accomplishments to broadcast"}
+
+    # Summarize into a single broadcast message
+    summary = "; ".join(accomplishments[:5])
+    if len(accomplishments) > 5:
+        summary += f" (and {len(accomplishments) - 5} more)"
+
+    action = f"Session wrapup — accomplished: {summary}"
+
+    cross_agent_script = PROJECT_DIR / "execution" / "cross_agent_context.py"
+    if not cross_agent_script.exists():
+        return {"status": "error", "reason": "cross_agent_context.py not found"}
+
+    try:
+        cmd = [
+            "python3", str(cross_agent_script),
+            "store",
+            "--agent", agent,
+            "--action", action,
+        ]
+        if project:
+            cmd.extend(["--project", project])
+        cmd.extend(["--tags", "session-wrapup"])
+
+        proc = subprocess.run(
+            cmd,
+            capture_output=True, text=True, timeout=15,
+            cwd=str(PROJECT_DIR),
+        )
+        if proc.returncode == 0:
+            try:
+                return json.loads(proc.stdout)
+            except json.JSONDecodeError:
+                return {"status": "stored", "raw": proc.stdout.strip()}
+        else:
+            return {"status": "error", "stderr": proc.stderr.strip()}
+    except Exception as e:
+        return {"status": "error", "message": str(e)}
+
+
+def check_stale_tmp_files() -> list:
+    """Check .tmp/ for files older than STALE_THRESHOLD_HOURS."""
+    stale_files = []
+    if not TMP_DIR.exists():
+        return stale_files
+
+    cutoff = time.time() - (STALE_THRESHOLD_HOURS * 3600)
+
+    for path in TMP_DIR.rglob("*"):
+        if path.is_file():
+            try:
+                mtime = path.stat().st_mtime
+                if mtime < cutoff:
+                    age_hours = (time.time() - mtime) / 3600
+                    stale_files.append({
+                        "path": str(path.relative_to(PROJECT_DIR)),
+                        "age_hours": round(age_hours, 1),
+                        "size_bytes": path.stat().st_size,
+                    })
+            except OSError:
+                continue
+
+    # Sort by age descending
+    stale_files.sort(key=lambda f: f["age_hours"], reverse=True)
+    return stale_files
+
+
+def deregister_control_tower(agent: str, project: str = None) -> dict:
+    """Best-effort heartbeat update via control_tower.py to mark session end."""
+    try:
+        sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+        from control_tower import heartbeat
+        result = heartbeat(agent, task="session_ended", project=project)
+        return {"status": "ok", "agent": agent, "timestamp": result.get("timestamp")}
+    except ImportError:
+        return {"status": "skipped", "reason": "control_tower.py not importable"}
+    except Exception as e:
+        return {"status": "error", "message": str(e)}
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Session Close Protocol: review, verify, broadcast, cleanup"
+    )
+    parser.add_argument("--agent", default="claude",
+                        help="Agent name (default: claude)")
+    parser.add_argument("--project",
+                        help="Project name for Qdrant filter")
+    parser.add_argument("--since", type=int, default=60,
+                        help="Look back N minutes for session activity (default: 60)")
+    parser.add_argument("--json", action="store_true", dest="json_output",
+                        help="JSON output only")
+    parser.add_argument("--auto-broadcast", action="store_true",
+                        help="Automatically broadcast accomplishments to all agents")
+    args = parser.parse_args()
+
+    report = {
+        "session_wrapup": True,
+        "agent": args.agent,
+        "project": args.project,
+        "since_minutes": args.since,
+        "accomplishments": [],
+        "memories_stored_count": 0,
+        "memory_types": {},
+        "stale_tmp_files": [],
+        "broadcast_status": "not_requested",
+        "control_tower": {},
+        "warnings": [],
+    }
+
+    # Step 1: Review session activity
+    memories = get_recent_memories(args.since, args.project)
+    if memories["status"] != "ok":
+        report["warnings"].append(f"Could not query memories: {memories['status']}")
+    else:
+        report["accomplishments"] = summarize_accomplishments(memories)
+
+    # Step 2: Verify memory stores
+    verification = verify_memory_stores(args.since, args.project)
+    report["memories_stored_count"] = verification.get("stores_found", 0)
+    report["memory_types"] = verification.get("types", {})
+    if verification.get("warning"):
+        report["warnings"].append(verification["warning"])
+
+    # Step 3: Cross-agent broadcast (if requested)
+    if args.auto_broadcast:
+        broadcast_result = broadcast_session(
+            args.agent, report["accomplishments"], args.project
+        )
+        report["broadcast_status"] = broadcast_result.get("status", "unknown")
+        if broadcast_result.get("status") == "error":
+            report["warnings"].append(
+                f"Broadcast failed: {broadcast_result.get('message', broadcast_result.get('stderr', 'unknown'))}"
+            )
+    else:
+        report["broadcast_status"] = "not_requested"
+
+    # Step 4: Cleanup check for .tmp/
+    stale = check_stale_tmp_files()
+    report["stale_tmp_files"] = stale
+
+    # Step 5: Control Tower deregister (best-effort)
+    ct_result = deregister_control_tower(args.agent, args.project)
+    report["control_tower"] = ct_result
+
+    # Determine exit code
+    has_warnings = len(report["warnings"]) > 0
+    memory_unreachable = memories["status"] != "ok"
+
+    if memory_unreachable:
+        exit_code = 2
+    elif report["memories_stored_count"] == 0:
+        exit_code = 1
+    else:
+        exit_code = 0
+
+    # Output
+    if args.json_output:
+        print(json.dumps(report, indent=2))
+    else:
+        print()
+        if report["memories_stored_count"] > 0:
+            print(f"  Session wrapup for [{args.agent}] — {report['memories_stored_count']} memories stored")
+        else:
+            print(f"  Session wrapup for [{args.agent}] — no memories stored this session")
+
+        # Accomplishments
+        if report["accomplishments"]:
+            print(f"\n  Accomplishments ({len(report['accomplishments'])}):")
+            for i, acc in enumerate(report["accomplishments"][:10], 1):
+                print(f"    {i}. {acc}")
+            if len(report["accomplishments"]) > 10:
+                print(f"    ... and {len(report['accomplishments']) - 10} more")
+        else:
+            print("\n  No accomplishments recorded.")
+
+        # Memory types
+        if report["memory_types"]:
+            types_str = ", ".join(f"{k}: {v}" for k, v in report["memory_types"].items())
+            print(f"\n  Memory types: {types_str}")
+
+        # Stale files
+        if stale:
+            total_size = sum(f["size_bytes"] for f in stale)
+            size_mb = total_size / (1024 * 1024)
+            print(f"\n  Stale .tmp/ files: {len(stale)} files ({size_mb:.1f} MB)")
+            for f in stale[:5]:
+                print(f"    - {f['path']} ({f['age_hours']}h old, {f['size_bytes']} bytes)")
+            if len(stale) > 5:
+                print(f"    ... and {len(stale) - 5} more")
+        else:
+            print("\n  No stale .tmp/ files.")
+
+        # Broadcast
+        if args.auto_broadcast:
+            if report["broadcast_status"] in ("stored", "ok"):
+                print(f"\n  Broadcast: sent to other agents")
+            else:
+                print(f"\n  Broadcast: {report['broadcast_status']}")
+
+        # Control Tower
+        ct_status = report["control_tower"].get("status", "unknown")
+        if ct_status == "ok":
+            print(f"  Control Tower: session end registered")
+        elif ct_status == "skipped":
+            pass  # Silent skip
+        else:
+            print(f"  Control Tower: {ct_status}")
+
+        # Warnings
+        if report["warnings"]:
+            print()
+            for w in report["warnings"]:
+                print(f"  WARNING: {w}")
+
+        print()
+
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    main()