fix: release-check lint fixes for 1.1.0 publish

Wrap long lines for flake8, rename extensions remove command handler
to avoid Click shadowing, and drop unused migration imports.

.claude/rules/architecture.md

@@ -0,0 +1,29 @@
+## Architecture
+
+kaizen-agentic has two distinct layers:
+
+### 1. Python framework (`src/kaizen_agentic/`)
+
+- **`core.py`** — `Agent` (abstract base) + `AgentConfig` (dataclass). Tracks performance, supports config updates, implements kaizen interface.
+- **`optimization.py`** — `OptimizationLoop` (runs improvement cycles, detects trends, generates recommendations) + `PerformanceMetrics` (execution time, success rate, quality scores).
+- **`metrics.py`** — `MetricsStore` + `OptimizerStore` (project-scoped `.kaizen/metrics/` per ADR-004).
+
+### 2. Agent definitions (`agents/` — 20 files)
+
+Markdown instruction sets read and followed by Claude. Not executables. Naming convention: `agent-{name}.md`.
+Packaged copies live in `src/kaizen_agentic/data/agents/` for `pip install` distribution.
+
+| Category | Agents |
+|----------|--------|
+| Testing | `tdd-workflow`, `test-maintenance`, `testing-efficiency` |
+| Quality | `code-refactoring`, `datamodel-optimization` |
+| Process | `requirements-engineering`, `keepaTodofile`, `keepaChangelog`, `keepaContributingfile`, `project-management`, `priority-evaluation`, `scope-analyst` |
+| Infrastructure | `setupRepository`, `tooling-optimization`, `sys-medic` |
+| Release | `releaseManager` |
+| Docs | `claude-documentation` |
+| Support | `wisdom-encouragement` |
+| Meta | `coach`, `optimization` |
+
+### Custodian integration
+
+The state-hub MCP resolves the agents directory via `host_paths[hostname]` → `local_path`. Tools: `list_kaizen_agents(category?)`, `get_kaizen_agent(name)`.

.claude/rules/first-session.md

@@ -0,0 +1,38 @@
+## First Session Protocol
+
+Triggered when `get_domain_summary("custodian")` shows **no workstreams**.
+The project is registered but work has not yet been structured.
+
+**Step 1 — Read, don't write**
+- `~/the-custodian/canon/projects/custodian/project_charter_v0.1.md` — purpose, scope
+- `~/the-custodian/canon/projects/custodian/roadmap_v0.1.md` — planned phases
+- Scan repo root: README, directory structure, existing code or docs
+
+**Step 2 — Survey in-progress work**
+Look for TODOs, open branches, half-finished files. Note done vs. started but incomplete.
+
+**Step 3 — Propose workstreams to Bernd**
+Propose 1–3 workstreams — each a coherent strand, weeks to months, anchored to a
+roadmap phase. **Wait for approval before creating.**
+
+**Step 4 — Create workplan file first, then DB record (ADR-001)**
+```
+workplans/kaizen-agentic-WP-NNNN-<slug>.md   ← write this first
+```
+Then register in the hub:
+```
+create_workstream(topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", title="...", owner="...", description="...")
+create_task(workstream_id="<id>", title="...", priority="high|medium|low")
+```
+
+**Step 5 — Record the setup**
+```
+add_progress_event(
+    summary="First session: structured custodian into N workstreams, M tasks",
+    event_type="milestone",
+    topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a",
+    detail={"workstreams": [...], "tasks_created": M}
+)
+```
+
+<!-- Delete or archive this file once past first session -->

.claude/rules/repo-boundary.md

@@ -0,0 +1,8 @@
+## Repo boundary
+
+This repo owns **kaizen-agentic** only. It does not own:
+
+- State-hub MCP integration code → `the-custodian/state-hub/mcp_server/server.py`
+- Agent discovery tools (`list_kaizen_agents`, `get_kaizen_agent`) → `the-custodian`
+- Custodian coordination and workplan tracking → `the-custodian`
+- Deployment to custodiancore → `ops-bridge`

.claude/rules/repo-identity.md

@@ -0,0 +1,9 @@
+## Repo Identity
+
+**Purpose:** kaizen-agentic — AI agent development framework embracing kaizen (continuous improvement). Provides 17 specialized Claude Code companion agents plus an OptimizationLoop framework for continuous performance measurement and refinement.
+
+**Domain:** custodian
+**Repo slug:** kaizen-agentic
+**Topic ID:** cee7bedf-2b48-46ef-8601-006474f2ad7a
+
+**Custodian integration:** This repo is the single source of truth for all kaizen agents. The state-hub MCP exposes `list_kaizen_agents()` and `get_kaizen_agent(name)` tools so any connected session can discover and load agents without a local copy.

.claude/rules/session-protocol.md

@@ -0,0 +1,48 @@
+## Session Protocol
+
+State Hub: http://127.0.0.1:8000
+
+**Step 1 — Orient**
+```
+get_domain_summary("custodian")
+```
+If offline: `cd ~/the-custodian/state-hub && make api`
+
+**Step 2 — Check inbox**
+```
+get_messages(to_agent="kaizen-agentic", unread_only=True)
+```
+Mark read with `mark_message_read(message_id)`. Reply or act on coordination
+requests before proceeding.
+
+**Step 3 — Scan workplans**
+```bash
+ls workplans/
+```
+For each file with `status: active`, note pending `todo`/`in_progress` tasks.
+
+**Step 4 — Present brief**
+
+1. **Active workstreams** for `custodian` — title, task counts, blocking decisions
+2. **Pending tasks** from `workplans/` + any `[repo:kaizen-agentic]` hub tasks
+3. **Goal guidance** — if `goal_guidance` in summary:
+   - `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"*
+   - `alignment_warnings`: flag if active work is not aligned with current goal
+4. **Suggested next action** — highest-priority open item
+5. **SBOM status** — flag if `last_sbom_at` is unset for this repo
+
+If no workstreams: follow First Session Protocol (`first-session.md`).
+
+**During work:** `record_decision()` · `add_progress_event()` · `resolve_decision()`
+
+> State Hub is a *read model*. Bootstrap tools (`create_workstream`, `create_task`)
+> are First Session Protocol only. Work structure belongs in repo files (ADR-001).
+
+**Session close:**
+```
+add_progress_event(summary="...", topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", workstream_id="<uuid>")
+```
+If workplan files were modified:
+```bash
+cd ~/the-custodian/state-hub && make fix-consistency REPO=kaizen-agentic
+```

.claude/rules/stack-and-commands.md

@@ -0,0 +1,43 @@
+## Stack and Commands
+
+**Language:** Python 3.8+
+**Package manager:** uv / pip (`.venv/`)
+**Test runner:** pytest
+**Linter/formatter:** flake8 (100-char), black (88-char), mypy (strict)
+
+### Essential commands
+
+```bash
+make setup-complete     # First-time setup: venv + package + dev deps
+source .venv/bin/activate
+make test               # Run full test suite
+make lint               # flake8 linting
+make format             # black formatting
+make clean              # Remove build artifacts
+```
+
+### TDD workflow
+
+```bash
+make tdd-start ISSUE=X  # Start issue with requirements validation
+make tdd-add-test       # Add test to current workspace
+make tdd-status         # Show workspace state
+make tdd-finish         # Move tests to main suite
+```
+
+### Issue management
+
+```bash
+make issue-list         # All issues (Gitea)
+make issue-list-open    # Open backlog
+make issue-show ISSUE=X # Issue detail
+make issue-create TITLE='...' BODY='...'
+```
+
+Run `make help` to see all available targets.
+
+### Core dependencies (pyproject.toml)
+
+- `pyyaml>=6.0` — YAML config
+- `click>=8.0.0` — CLI framework
+- `pydantic>=2.0.0` — Data validation

.claude/rules/workplan-convention.md

@@ -0,0 +1,12 @@
+## Workplan Convention (ADR-001)
+
+File location: `workplans/kaizen-agentic-WP-NNNN-<slug>.md`
+ID prefix: `KAIZEN-WP`
+
+Work items originate as files in this repo **before** being registered in the hub.
+
+Ecosystem todos from other agents arrive as `[repo:kaizen-agentic]` hub tasks —
+visible at session start. Pick one up by creating the workplan file, then registering
+the workstream.
+
+<!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->

.flake8

@@ -0,0 +1,11 @@
+[flake8]
+max-line-length = 88
+extend-ignore = E203, W503
+per-file-ignores =
+    tests/*:E501,F841
+exclude =
+    .venv,
+    build,
+    dist,
+    .git,
+    __pycache__

.gitea/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug report
+about: Report a defect in kaizen-agentic
+title: "[bug] "
+labels: bug
+---
+
+## Summary
+
+<!-- One sentence describing the problem -->
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Expected behavior
+
+## Actual behavior
+
+## Environment
+
+- OS:
+- Python version:
+- kaizen-agentic version (`kaizen-agentic --version`):
+- Install method (pip / editable / other):
+
+## Logs or CLI output
+
+```
+(paste relevant output)
+```
+
+## Additional context

.gitea/ISSUE_TEMPLATE/config.yaml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Feedback guide
+    url: https://gitea.coulomb.social/coulomb/kaizen-agentic/src/branch/main/docs/FEEDBACK.md
+    about: How to submit feedback, bugs, and feature ideas
+  - name: Contributing guide
+    url: https://gitea.coulomb.social/coulomb/kaizen-agentic/src/branch/main/CONTRIBUTING.md
+    about: Development workflow and code standards

.gitea/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Suggest an enhancement for kaizen-agentic
+title: "[feature] "
+labels: enhancement
+---
+
+## Problem or opportunity
+
+<!-- What pain point does this address? -->
+
+## Proposed solution
+
+## Alternatives considered
+
+## Scope
+
+- [ ] CLI / framework (`src/kaizen_agentic/`)
+- [ ] Agent definitions (`agents/`)
+- [ ] Documentation / wiki
+- [ ] Ecosystem integration (activity-core, artifact-store, agentic-resources)
+
+## Additional context

.gitea/ISSUE_TEMPLATE/feedback.md

@@ -0,0 +1,21 @@
+---
+name: General feedback
+about: Share experience, ideas, or adoption feedback
+title: "[feedback] "
+labels: feedback
+---
+
+## Context
+
+<!-- How are you using kaizen-agentic? (project type, agents used, workflow) -->
+
+## What worked well
+
+## What was confusing or friction-heavy
+
+## Suggestions
+
+## Optional: metrics / telemetry context
+
+If relevant, note whether you use project metrics (`.kaizen/metrics/`) or Helix Forge
+fleet capture — helps us prioritize integration improvements.

.gitea/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package and dev tools
+        run: python -m pip install --upgrade pip && python -m pip install -e ".[dev]"
+
+      - name: Format check (black)
+        run: black --check src tests
+
+      - name: Run tests
+        run: pytest tests/ -q --ignore=tests/test_cli_error_handling.py

.gitignore

@@ -42,3 +42,6 @@ venv.bak/
 .coverage
 htmlcov/
 .tox/
+
+# Backup directories created by optimization scripts
+agents_backup_*/

.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+# Pre-commit hooks for kaizen-agentic (WP-0001 T02)
+# Install: pip install pre-commit && pre-commit install
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+        args: [--unsafe]
+      - id: check-added-large-files
+        args: [--maxkb=512]
+
+  - repo: https://github.com/psf/black
+    rev: 24.10.0
+    hooks:
+      - id: black
+        language_version: python3
+

CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-06-18
+
+### Added
+- **`kaizen-agentic feedback`** CLI and Gitea issue templates for developer feedback
+- **Gitea CI** (`.gitea/workflows/ci.yml`) — black + pytest on Python 3.10/3.12
+- **Pre-commit hooks** (`.pre-commit-config.yaml`) and `make pre-commit-install`
+- **`docs/FEEDBACK.md`** and **`docs/TELEMETRY.md`** (ADR-004 two-layer telemetry model)
+- **Ecosystem integration (WP-0004)**: Helix correlation, artifact-store publish, activity-core definitions
+- **Project metrics (WP-0003)**: ADR-004 storage, metrics CLI, optimizer wiring, tdd-workflow pilot
+- **sys-medic agent** and packaged fleet sync (20 agents in `data/agents/`)
+
+### Changed
+- **Lazy agent registry** — index by frontmatter name; parse on demand; path-based install copy
+- **CLI error messages** — clearer guidance when agents directory or package missing
+- **CONTRIBUTING.md** — post-pull reinstall instructions (`pip install -e .` / pipx)
+
+### Fixed
+- **Makefile template** in project initializer — tab characters no longer break Python linting
+- Removed stale `agents_backup_*/` scaffolding from development installs
+
 ## [1.0.1] - 2025-10-20
 
 ### Fixed

CLAUDE.md

@@ -1,370 +1,62 @@
-# CLAUDE.md
+# kaizen-agentic — Claude Code Instructions
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+@.claude/rules/repo-identity.md
+@.claude/rules/session-protocol.md
+@.claude/rules/first-session.md
+@.claude/rules/workplan-convention.md
+@.claude/rules/stack-and-commands.md
+@.claude/rules/architecture.md
+@.claude/rules/repo-boundary.md
 
-## Project Overview
+## Installed Agents
 
-Kaizen Agentic is an AI agent development framework that embraces the Japanese concept of "kaizen" (continuous improvement). Every coding subagent becomes part of an optimization loop where performance is measured, patterns are analyzed, and specifications are refined over time.
+This project includes the following specialized agents:
 
-## Repository Structure
+### Testing
 
-This is a modern Python project with agent development focus:
+- **tdd-workflow**: Expert guidance for the TDD8 workflow methodology, specializing in the comprehensive ISSUE-TEST-RED-GREEN-REFACTOR-DOCUMENT-REFINE-PUBLISH cycle with sophisticated sidequest management and proper test organization.
 
-```
-kaizen-agentic/
-├── Makefile                    # Comprehensive development commands and workflows
-├── pyproject.toml              # Python project configuration and dependencies
-├── src/kaizen_agentic/         # Main Python package
-│   ├── __init__.py            # Package exports and version info
-│   ├── core.py                # Core Agent and AgentConfig classes
-│   └── optimization.py        # OptimizationLoop and PerformanceMetrics
-├── tests/                      # Test suite with pytest
-│   ├── __init__.py
-│   └── test_core.py           # Core functionality tests
-├── agents/                     # Agent definitions and configurations (17 total)
-│   ├── agent-claude-documentation.md
-│   ├── agent-code-refactoring.md
-│   ├── agent-datamodel-optimization.md
-│   ├── agent-keepaChangelog.md
-│   ├── agent-keepaContributingfile.md
-│   ├── agent-keepaTodofile.md
-│   ├── agent-optimization.md
-│   ├── agent-priority-evaluation.md
-│   ├── agent-project-management.md
-│   ├── agent-releaseManager.md
-│   ├── agent-requirements-engineering.md
-│   ├── agent-setupRepository.md
-│   ├── agent-tdd-workflow.md
-│   ├── agent-test-maintenance.md
-│   ├── agent-testing-efficiency.md
-│   ├── agent-tooling-optimization.md
-│   └── agent-wisdom-encouragement.md
-├── .claude/                    # Claude Code configuration
-│   └── settings.local.json    # Local permissions and settings
-├── .venv/                     # Python virtual environment (created by setup)
-├── TODO.md                    # Current todofile (Keep a Todofile format)
-├── CHANGELOG.md               # Version history (Keep a Changelog format)
-├── CONTRIBUTING.md            # Developer contribution guidelines
-├── CLAUDE.md                  # Claude Code guidance documentation
-├── LICENSE                    # MIT License
-└── README.md                  # Project overview
-```
+Use these agents by referencing them in your Claude Code interactions.
 
-## Quick Start
+### Documentation
 
-For first-time setup or when starting fresh:
+- **claude-documentation**: Specialized assistant for Claude and Claude Code documentation, features, and best practices
 
-```bash
-# Complete setup with development dependencies
-make setup-complete
+### Meta
 
-# Activate virtual environment
-source .venv/bin/activate
+- **coach**: Coaching meta-agent that reads all agent memories in a project and synthesises cross-agent briefs and new-agent orientations
 
-# Verify everything works
-make test && make lint
-```
+### Code Quality
 
-## Key Development Commands
+- **code-refactoring**: Analyze code structure and quality, identify improvement opportunities, and provide actionable refactoring guidance. Use PROACTIVELY for code quality assessment and improvement.
+- **datamodel-optimization**: Specialized agent that systematically analyzes, optimizes, and enhances dataclasses, models, and data structures within a codebase. Provides comprehensive datamodel improvements including convenience methods, interface consistency, code reduction, and test alignment.
+- **optimization**: Meta-agent that analyzes and optimizes other Claude Code subagents based on their performance data, usage patterns, and effectiveness metrics. Use PROACTIVELY for agent ecosystem improvement.
+- **tooling-optimization**: Meta-agent that analyzes and optimizes repository tooling usage to improve development efficiency
 
-The Makefile provides an extensive set of commands for development workflow. Use `make help` to see all available commands.
+### Project Management
 
-### Essential Commands
+- **keepaChangelog**: Specialized assistant for maintaining CHANGELOG.md files following Keep a Changelog format
+- **keepaContributingfile**: Specialized assistant for maintaining CONTRIBUTING.md files following Keep a Contributing-File V0.0.1 format within the Kaizen Agentic framework
+- **keepaTodofile**: Specialized assistant for maintaining TODO.md files following Keep a Todofile V0.0.1 format
 
-- `make help` - Show all available commands with descriptions
-- `make setup` - Basic project setup (creates venv + installs package)
-- `make setup-complete` - Complete setup including dev dependencies (recommended)
-- `make test` - Run all tests with pytest
-- `make lint` - Run code linting with flake8 (100 char line length)
-- `make format` - Format code with black
-- `make clean` - Clean build artifacts and cache
+### Development Process
 
-### Environment Management
+- **priority-evaluation**: Specialized assistant to help evaluate and establish priorities for issues and tasks.
+- **releaseManager**: Manages software releases, version control, and publication workflows for Python packages
+- **requirements-engineering**: Specialized agent designed to prevent interface compatibility issues and mock object mismatches by ensuring solid foundation planning before implementation. Based on lessons learned from Issue
+- **scope-analyst**: Analyze a repository and produce/improve SCOPE.md for rapid orientation
+- **wisdom-encouragement**: Provides encouraging wisdom and guidance for complex implementation tasks and challenging technical work
 
-- `make venv-status` - Check virtual environment status
-- `make ensure-project-structure` - Auto-create Python project structure if missing
-- `make install-dev` - Install package in development mode
-- `make setup-dev` - Install development dependencies (pytest, black, flake8, mypy)
-- `make install-deps` - Install dependencies user-local (fallback option)
-- `make install-system` - Install system dependencies via apt (requires sudo)
+### Infrastructure
 
-### Testing Infrastructure
+- **setupRepository**: Specialized assistant for setting up new Python repositories following PythonVibes best practices
+- **sys-medic**: Linux/Kubernetes node health assessment agent — diagnoses process, memory, CPU, disk, network, and kubelet issues with safe, prioritized, evidence-driven guidance
 
-The project includes comprehensive testing capabilities:
+### Testing
 
-#### Basic Testing
-- `make test` - Run all tests with pytest
-- `make test-status` - Show test status summary without re-running
-- `make test-new` - Create new test file template
-- `make test-coverage ISSUE=X` - Analyze test coverage for specific issue
+- **tdd-workflow**: Expert guidance for the TDD8 workflow methodology, specializing in the comprehensive ISSUE-TEST-RED-GREEN-REFACTOR-DOCUMENT-REFINE-PUBLISH cycle with sophisticated sidequest management and proper test organization.
+- **test-maintenance**: Specialized agent for analyzing and fixing failing tests in the project
+- **testing-efficiency**: Specialized agent designed to optimize TDD8 workflow test execution, resolve pytest reliability issues, and enhance overall testing efficiency for red-green iterations. Focuses on smart test selection, parallel execution, and agent integration patterns.
 
-#### Advanced Testing
-- `make test-clean` - Clean test run (exclude workspaces, fresh cache)
-- `make test-tdd` - Quick TDD tests for fast feedback (<30s)
-- `make test-changed` - Run tests for changed files only
-- `make test-module MODULE=name` - Run tests for specific module
-- `make test-efficient` - Enhanced test suite excluding workspaces
+Use these agents by referencing them in your Claude Code interactions.
 
-#### Architectural Testing
-- `make test-arch` - Run tests in architectural order (reverse dependency)
-- `make test-foundation` - Foundation layer tests (fastest feedback)
-- `make test-infrastructure` - Infrastructure layer tests
-- `make test-domain` - Domain layer tests (business logic)
-- `make test-quick` - Foundation + infrastructure only (fast)
-
-#### Randomized Testing
-- `make test-random` - Run tests in random order to detect hidden dependencies
-- `make test-random-seed SEED=X` - Run with specific seed for reproducibility
-- `make test-random-repeat NUM=X` - Run multiple random iterations
-
-### Issue Management
-
-The project uses Gitea for issue tracking with integrated CLI tools:
-
-- `make issue-list` - Show all issues with status and priority
-- `make issue-list-open` - Show only open issues (active backlog)
-- `make issue-show ISSUE=X` - Show detailed view of specific issue
-- `make issue-create TITLE='...' BODY='...'` - Create new issue
-- `make issue-close ISSUE=X` - Close an issue
-- `make issue-get` - Export issues to various formats (CSV, JSON, TSV)
-
-### TDD Workflow
-
-Complete test-driven development support:
-
-- `make tdd-start ISSUE=X` - Start working on issue with requirements validation
-- `make tdd-add-test` - Add test to current issue workspace
-- `make tdd-status` - Show current workspace state
-- `make tdd-finish` - Complete issue work (move tests to main)
-- `make test-from-issue ISSUE=X` - Generate test skeleton from issue
-
-## Core Framework Architecture
-
-The repository provides a working AI agent framework with kaizen optimization:
-
-### Core Classes
-
-1. **AgentConfig** (`src/kaizen_agentic/core.py`)
-   - Configuration dataclass for agents
-   - Includes name, description, model, instructions, and metadata
-
-2. **Agent** (`src/kaizen_agentic/core.py`)
-   - Abstract base class for AI agents
-   - Provides performance tracking and configuration updates
-   - Implements kaizen optimization interface
-
-3. **OptimizationLoop** (`src/kaizen_agentic/optimization.py`)
-   - Implements continuous improvement cycles
-   - Performance analysis and trend detection
-   - Generates improvement recommendations
-
-4. **PerformanceMetrics** (`src/kaizen_agentic/optimization.py`)
-   - Container for agent performance data
-   - Tracks execution time, success rate, quality scores
-
-### Agent System Architecture
-
-Specialized agent definitions in `agents/` directory (17 total):
-
-#### Documentation & Claude Integration
-1. **claude-documentation** (`agent-claude-documentation.md`)
-   - Specialized assistant for Claude and Claude Code documentation, features, and best practices
-   - Access to official docs.claude.com resources and Claude Code configuration
-
-#### Project Management
-2. **project-management** (`agent-project-management.md`)
-   - Specialized assistant for project status, progress tracking, and development planning
-   - Manages project coordination and workflow optimization
-
-3. **priority-evaluation** (`agent-priority-evaluation.md`)
-   - Specialized assistant to help evaluate and establish priorities for issues and tasks
-   - Decision support and task prioritization
-
-4. **releaseManager** (`agent-releaseManager.md`)
-   - Manages software releases, version control, and publication workflows for Python packages
-   - Handles semantic versioning and release automation
-
-#### Documentation Keepers
-5. **keepaTodofile** (`agent-keepaTodofile.md`)
-   - Specialized assistant for maintaining TODO.md files following Keep a Todofile V0.0.1 format
-   - Task tracking, progress monitoring, and workflow optimization
-
-6. **keepaChangelog** (`agent-keepaChangelog.md`)
-   - Specialized assistant for maintaining CHANGELOG.md files following Keep a Changelog format
-   - Semantic versioning and change categorization
-
-7. **keepaContributingfile** (`agent-keepaContributingfile.md`)
-   - Specialized assistant for maintaining CONTRIBUTING.md files following Keep a Contributing-File V0.0.1 format
-   - Developer onboarding and contribution guidelines
-
-#### Development Process
-8. **tdd-workflow** (`agent-tdd-workflow.md`)
-   - Expert guidance for the TDD8 workflow methodology
-   - ISSUE-TEST-RED-GREEN-REFACTOR-DOCUMENT-REFINE-PUBLISH cycle with sophisticated sidequest management
-
-9. **requirements-engineering** (`agent-requirements-engineering.md`)
-   - Specialized agent designed to prevent interface compatibility issues and mock object mismatches
-   - Ensures solid foundation planning before implementation
-
-#### Testing & Quality Assurance
-10. **test-maintenance** (`agent-test-maintenance.md`)
-    - Specialized agent for analyzing and fixing failing tests in the project
-    - Test suite maintenance and optimization
-
-11. **testing-efficiency** (`agent-testing-efficiency.md`)
-    - Specialized agent designed to optimize TDD8 workflow test execution
-    - Resolves pytest reliability issues and enhances testing efficiency
-
-#### Code Quality & Optimization
-12. **code-refactoring** (`agent-code-refactoring.md`)
-    - Analyze code structure and quality, identify improvement opportunities
-    - Provides actionable refactoring guidance (Use PROACTIVELY)
-
-13. **datamodel-optimization** (`agent-datamodel-optimization.md`)
-    - Systematically analyzes, optimizes, and enhances dataclasses, models, and data structures
-    - Provides comprehensive datamodel improvements
-
-14. **optimization** (`agent-optimization.md`)
-    - Meta-agent that analyzes and optimizes other Claude Code subagents
-    - Based on performance data, usage patterns, and effectiveness metrics (Use PROACTIVELY)
-
-#### Infrastructure & Tooling
-15. **setupRepository** (`agent-setupRepository.md`)
-    - Specialized assistant for setting up new Python repositories following PythonVibes best practices
-    - Repository initialization and standards compliance
-
-16. **tooling-optimization** (`agent-tooling-optimization.md`)
-    - Meta-agent that analyzes and optimizes repository tooling usage to improve development efficiency
-    - Discovers and recommends better tool utilization
-
-#### Support & Guidance
-17. **wisdom-encouragement** (`agent-wisdom-encouragement.md`)
-    - Provides encouraging wisdom and guidance for complex implementation tasks and challenging technical work
-    - Fortune cookie-style wisdom for developers facing technical challenges
-
-## Development Workflow Patterns
-
-### Kaizen Philosophy
-
-- **Continuous Improvement**: Every coding session should measure performance and refine specifications
-- **Pattern Recognition**: Analyze agent behavior and optimize workflows over time
-- **Specification Evolution**: Agent definitions should be updated based on performance data
-
-### Agent Optimization Loop
-
-1. **Measure**: Track agent performance and effectiveness using PerformanceMetrics
-2. **Analyze**: Use OptimizationLoop to identify patterns and trends
-3. **Refine**: Update agent specifications and workflows based on insights
-4. **Iterate**: Repeat the cycle for continuous improvement
-
-### Development Best Practices
-
-1. **Always use virtual environment**: Run `make venv-status` before starting
-2. **Test-driven development**: Write tests first, then implementation
-3. **Code quality**: Run `make lint` and `make format` before commits
-4. **Performance tracking**: Use the optimization framework for agent improvements
-5. **Todo tracking**: Maintain a todofile for task management and progress tracking
-6. **Change documentation**: Keep a changelog for version history and feature tracking
-
-## Python Project Configuration
-
-### Dependencies
-
-**Core Dependencies** (pyproject.toml):
-- `pyyaml>=6.0` - YAML configuration parsing
-- `click>=8.0.0` - CLI framework
-- `pydantic>=2.0.0` - Data validation and settings
-
-**Development Dependencies**:
-- `pytest>=6.0.0` - Testing framework
-- `black>=22.0.0` - Code formatting
-- `flake8>=5.0.0` - Code linting
-- `mypy>=1.0.0` - Type checking
-
-### Code Quality Configuration
-
-- **Black**: Line length 88, Python 3.8+ target
-- **Flake8**: Max line length 100, ignores E203, W503
-- **Pytest**: Configured with markers for slow, integration, e2e, smoke tests
-- **MyPy**: Strict typing with comprehensive checks enabled
-
-## Setup and Installation
-
-### First Time Setup
-
-```bash
-# Complete setup (recommended)
-make setup-complete
-
-# Activate environment
-source .venv/bin/activate
-
-# Verify installation
-make test
-```
-
-### Alternative Setup Methods
-
-```bash
-# Basic setup only
-make setup
-
-# Manual dev dependencies
-make setup-dev
-
-# Check environment status
-make venv-status
-```
-
-### Troubleshooting
-
-If setup fails:
-1. Try `make install-system` for system packages
-2. Use `make install-deps-force` to override restrictions
-3. Try `make install-deps-venv` for isolated environment
-
-## Project Management Tools
-
-### Todo Tracking
-- **Purpose**: Maintain visibility into current tasks and progress
-- **File**: `TODO.md` - Structured todofile following Keep a Todofile format
-- **Agent**: Use `todo-keeper` agent for maintaining todofiles
-- **Usage**: Track work items organized by impact type (Add, Refactor, Fix, Deprecate, Secure, Remove)
-- **Benefits**: Helps maintain focus and provides clear progress indicators aligned with changelog categories
-- **Integration**: Works well with issue management, TDD workflows, and changelog management
-- **Structure**: Organized by change impact type, mirroring changelog categories
-- **Format**: Uses markdown checkboxes within sprint-focused sections
-
-### Changelog Management
-- **Purpose**: Document changes, features, and version history
-- **File**: `CHANGELOG.md` - Structured markdown file following Keep a Changelog format
-- **Agent**: Use `changelog-keeper` agent for maintaining CHANGELOG.md files
-- **Usage**: Track what has been added, changed, fixed, removed, deprecated, or security-related
-- **Benefits**: Provides clear communication about project evolution and version impacts
-- **Format**: Follows Keep a Changelog standard with semantic versioning
-- **Structure**: Organized by version with categories (Added, Changed, Fixed, Deprecated, Removed, Security)
-- **Integration**: Links with git tags, releases, and issue references
-
-## Important Notes
-
-- **Self-healing setup**: `make setup` automatically creates missing project structure
-- **Comprehensive help**: Use `make help` to explore all available commands
-- **Agent-focused**: Agent definitions in `agents/` directory are the core of this system
-- **Quality-first**: Always run tests and linting before commits
-- **TDD emphasis**: The project emphasizes test-driven development workflows
-- **Kaizen approach**: Apply continuous improvement principles to all development
-- **Documentation practices**: Maintain todofiles and changelogs for better project management
-
-## Agent Usage Guidelines
-
-When working with this repository:
-
-1. **Read Agent Definitions**: Understand the specialized agents available in `agents/`
-2. **Follow TDD Patterns**: Use the established test-driven development workflows
-3. **Measure and Improve**: Apply kaizen principles using the optimization framework
-4. **Update Documentation**: Keep agent definitions current with actual usage patterns
-5. **Use the Framework**: Leverage the core Agent and OptimizationLoop classes for new agents
-6. **Test Everything**: Use the comprehensive testing infrastructure for quality assurance
-7. **Track Progress**: Maintain todofiles for current work and use changelog for completed work
-8. **Document Changes**: Update changelog when adding features, fixing bugs, or making improvements
-9. **Version Management**: Use changelog-keeper agent to maintain proper version history and semantic versioning

CONTRIBUTING.md

@@ -24,6 +24,14 @@ This document outlines how to get started, how we organise work, and how to help
 4. Verify setup: `make test-quick` or `pytest tests/`
 5. Familiarize yourself with agent system (see CLAUDE.md)
 
+**After pulling updates:** reinstall the CLI so new commands are available:
+
+```bash
+pip install -e .              # project venv
+# or
+pipx install -e . --force     # global pipx install
+```
+
 ## Development Workflow
 
 ### Project Structure
@@ -63,6 +71,8 @@ This repository follows PythonVibes best practices:
 - **Linting**: Flake8 (`flake8 .`)
 - **Type Checking**: MyPy (`mypy src/`)
 - **Testing**: Pytest (`pytest`)
+- **Pre-commit**: `pip install pre-commit && pre-commit install` (see `.pre-commit-config.yaml`)
+- **CI**: Gitea Actions workflow `.gitea/workflows/ci.yml` runs on push/PR to `main`
 
 ### Agent Development Standards
 For contributing new agents or improving existing ones:
@@ -71,6 +81,40 @@ For contributing new agents or improving existing ones:
 - Define explicit scope and authority boundaries
 - Follow existing agent patterns in `agents/` directory
 
+#### YAML frontmatter schema
+
+```yaml
+---
+name: <agent-name>
+description: <one-line description>
+category: testing | quality | process | infrastructure | release | docs | support | meta
+memory: enabled  # optional; default enabled. Set to disabled for stateless utility agents
+---
+```
+
+#### Session-start protocol (for session-bound agents)
+
+Agents that do ongoing work across sessions should include a session-start block:
+
+1. Check for `.kaizen/agents/<name>/memory.md` in the project root
+2. If present, read it and acknowledge relevant context in the opening brief
+3. Optionally invoke `kaizen-agentic memory brief <name>` for cross-agent orientation
+
+Include this block in the agent prompt under a `## Session Start` heading.
+
+#### Session-close protocol (for session-bound agents)
+
+At the end of each session the agent should:
+
+1. Update `## Accumulated Findings`, `## What Worked`, `## Watch Points` as needed
+2. Append one line to `## Session Log` (format: `YYYY-MM-DD · <summary> · <outcome>`)
+3. Bump `last_updated` and `session_count` in the frontmatter
+
+Include this block in the agent prompt under a `## Session Close` heading.
+
+Agents for which session state is irrelevant (e.g. `keepaTodofile`, `keepaChangelog`)
+should set `memory: disabled` in their frontmatter and omit these sections.
+
 ## Types of Contributions
 
 We welcome various types of contributions:
@@ -80,6 +124,17 @@ We welcome various types of contributions:
 - **Testing**: New tests, test improvements, bug reports
 - **Performance**: Optimization improvements and measurements
 
+## Feedback
+
+We welcome bugs, feature ideas, and adoption experience reports.
+
+- **CLI:** `kaizen-agentic feedback` — lists channels and issue templates
+- **Guide:** [docs/FEEDBACK.md](docs/FEEDBACK.md)
+- **Templates:** `.gitea/ISSUE_TEMPLATE/` (bug, feature, general feedback)
+
+For cross-repo coordination between custodian agents, use State Hub messages
+(`POST /messages/`) — see session protocol in `.claude/rules/session-protocol.md`.
+
 ## Issue Reporting
 
 When reporting bugs, please include:

INTENT.md

@@ -0,0 +1,85 @@
+# INTENT
+
+## Purpose
+
+This repository exists to define and evolve **KaizenAgentic**: a framework and product concept for turning AI coding agents from static tools into continuously improving digital talents.
+
+KaizenAgentic applies the principle of kaizen — continuous improvement through small, measurable, compounding refinements — to agent design, coding workflows, codebase quality, and agent optimization. It provides the concepts, templates, guidance, and business framing needed to build agents that can be observed, evaluated, refined, and improved over time.
+
+## Primary Utility
+
+The primary utility of this repository is to serve as the conceptual and operational seed for a **digital talent agency for AI coding agents**.
+
+It should help define:
+
+* how Kaizen agents are specified,
+* how their performance is measured,
+* how agent behavior is improved through feedback loops,
+* how codebase improvement guidance can be made human-readable, machine-checkable, and agent-executable,
+* how reusable capabilities, prompt practices, and improvement programs compound into better software development workflows.
+
+## Intended Users
+
+This repository is intended for:
+
+* builders of AI coding agents,
+* developers using Claude, Cursor, or similar coding assistant environments,
+* teams that want coding agents to improve with real-world use,
+* maintainers who want code quality guidance that can be checked, refactored, tested, and measured,
+* product and business designers shaping KaizenAgentic as a service or platform.
+
+## Strategic Role in the System
+
+KaizenAgentic plays the role of a **meta-improvement layer** for agentic software development.
+
+It is not merely a collection of prompts or coding assistants. It defines a system in which agents become measurable, versioned, testable, and optimizable units of digital work. Subagents perform specific tasks, while optimization logic observes their performance and proposes evidence-based refinements.
+
+The repository should become the place where the core language, principles, templates, and operating model for this improvement loop are stabilized.
+
+## Strategic Boundaries
+
+This repository should own:
+
+* the KaizenAgentic mission and conceptual model,
+* the KaizenAgent definition template,
+* the meta-optimizer concept,
+* guidance for measurable and idempotent agent behavior,
+* the codebase improvement guidance model,
+* the relationship between prompts, experiments, mantras, agents, and reusable capabilities,
+* the initial product, pricing, revenue, and brand framing.
+
+This repository should not own:
+
+* all concrete implementations of individual agents,
+* customer-specific agent configurations,
+* vendor-specific integrations beyond reference patterns,
+* the complete runtime platform for executing agents,
+* unrelated generic AI automation concepts that do not contribute to measurable continuous improvement,
+* codebase-specific gameplans except as examples or templates.
+
+## Design Principles
+
+* **Continuous Improvement**: Every agent, guide, and workflow should be designed to improve through repeated use.
+* **Measurable by Default**: Success criteria, metrics, and before/after deltas should be part of every meaningful agent or guidance definition.
+* **Idempotent Operations**: Agent actions should converge toward desired states and remain safe to repeat.
+* **Evidence over Intuition**: Improvements should be based on observed performance, tests, metrics, and explicit feedback.
+* **Separation of Concerns**: Task-specific agents, measurement logic, optimization logic, and business framing should remain distinguishable.
+* **Composable Capabilities**: Reusable units should package intent, interfaces, knowledge, and operational behavior, not just code.
+* **Human-Readable and Machine-Executable**: Guidance should be understandable by humans while also being checkable by tools and executable by agents.
+* **Rollback-Ready Evolution**: Agent specifications and improvements should be versioned, testable, and reversible.
+* **Compounding Value**: Small, durable improvements should accumulate into stronger agents, cleaner codebases, and better development workflows.
+
+## Maturity Target
+
+The repository should mature into the canonical reference for the KaizenAgentic operating model.
+
+At maturity, it should provide enough structure for a team to define, deploy, measure, refine, and commercialize AI coding agents as continuously improving digital talents. It should support both practical implementation and strategic communication: useful to developers, agent designers, product owners, and early customers.
+
+## Stability Note
+
+`INTENT.md` describes the stable purpose and strategic role of the repository.
+
+Changes to this file should represent a deliberate shift in what KaizenAgentic is meant to become, not ordinary scope evolution. Concrete implementation plans, product details, agent specifications, and experiments should live in PRDs, gameplans, templates, guidance documents, or implementation repositories.
+
+
+xxx

Makefile

@@ -567,11 +567,19 @@ format: $(VENV)/bin/activate
 clean:
 	@echo "🧹 Cleaning build artifacts and cache..."
 	@rm -rf build/ dist/ *.egg-info/ .pytest_cache/ __pycache__/ .coverage htmlcov/
+	@rm -rf agents_backup_*/
 	@find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
 	@find . -type f -name "*.pyc" -delete 2>/dev/null || true
 	@find . -type f -name "*.pyo" -delete 2>/dev/null || true
 	@echo "✅ Cleanup completed"
 
+# Install pre-commit hooks (WP-0001 T02)
+pre-commit-install: $(VENV)/bin/activate
+	@echo "🔧 Installing pre-commit hooks..."
+	@$(VENV_PIP) install pre-commit
+	@$(VENV)/bin/pre-commit install
+	@echo "✅ pre-commit installed — run 'pre-commit run --all-files' to verify"
+
 # ============================================================================
 # Standards Compliance Targets
 # ============================================================================

README.md

@@ -1,8 +1,10 @@
 # Kaizen Agentic
 
-AI agent development framework embracing continuous improvement through specialized agents and comprehensive development workflows.
+AI **agency** framework: 18 specialized agents that arrive in your project informed, learn from experience, and improve over time.
 
-This project embraces the Japanese concept of "kaizen" (continuous improvement) applied to AI agent development. Every coding subagent becomes part of an optimization loop where performance is measured, patterns are analyzed, and specifications are refined over time.
+kaizen-agentic provides two things: a library of agent instruction sets you deploy into projects, and an **agency framework** that gives those agents persistent memory and coordination. Agents accumulate project-scoped knowledge across sessions. A Coach meta-agent synthesises patterns across the entire fleet and briefs incoming agents on what to know first.
+
+This project embraces the Japanese concept of "kaizen" (continuous improvement) applied to AI agent development. Every agent becomes part of an optimization loop where performance is measured, patterns are analyzed, and knowledge is carried forward.
 
 ## Quick Start
 
@@ -70,14 +72,46 @@ kaizen-agentic install keepaTodofile keepaChangelog tdd-workflow
 kaizen-agentic status
 ```
 
+## Agency Framework
+
+Agents deployed into a project can accumulate **project-scoped memory** — a structured file written at session close and read at session start. A **Coach** meta-agent reads across all agent memories and produces targeted orientation briefs for incoming agents.
+
+```bash
+# Scaffold memory for an agent
+kaizen-agentic memory init sys-medic
+
+# Brief an incoming agent using all existing project memories
+kaizen-agentic memory brief tdd-workflow
+
+# Review an agent's accumulated knowledge
+kaizen-agentic memory show project-management
+```
+
+See [docs/agency-framework.md](docs/agency-framework.md) for the full model.
+
+## Orientation
+
+Read in this order for strategic context:
+
+1. [INTENT.md](INTENT.md) — purpose, boundaries, design principles
+2. [wiki/KaizenAgenticMission.md](wiki/KaizenAgenticMission.md) — product narrative
+3. [wiki/AboutKaizenAgents.md](wiki/AboutKaizenAgents.md) — agent concepts and metrics pilot
+4. [wiki/EcosystemIntegration.md](wiki/EcosystemIntegration.md) — ecosystem composition
+5. [SCOPE.md](SCOPE.md) — repository boundaries and current state
+6. [history/](history/) — persisted assessments and gap analyses
+
+Released **v1.1.0** — see [CHANGELOG.md](CHANGELOG.md). Workplans: WP-0001 through WP-0004 completed.
+
+Feedback: `kaizen-agentic feedback` · [docs/FEEDBACK.md](docs/FEEDBACK.md)
+
 ## Features
 
-- **16+ Specialized Agents**: Project management, testing, code quality, documentation
-- **CLI Tool**: Easy agent installation and management (`kaizen-agentic`)
+- **20 Specialized Agents**: Project management, testing, code quality, infrastructure, meta
+- **Agency Framework**: Project-scoped agent memory + Coach meta-agent for cross-agent synthesis
+- **CLI Tool**: Easy agent installation, management, and memory commands (`kaizen-agentic`)
 - **Project Templates**: Pre-configured setups for different project types
 - **Claude Code Integration**: Seamless integration with Claude Code workflows
 - **Comprehensive Testing**: Full test coverage with multiple testing strategies
-- **Standards Compliance**: Follows PythonVibes and industry best practices
 
 ## Available Agents
 
@@ -101,6 +135,10 @@ kaizen-agentic status
 - **setupRepository**: Repository initialization and standards compliance
 - **claude-documentation**: Claude Code configuration and documentation
 - **tooling-optimization**: Repository tooling usage optimization
+- **sys-medic**: Infrastructure health monitoring and diagnostics
+
+### Meta
+- **coach**: Coaching meta-agent — reads all project agent memories, synthesises cross-agent briefs, and orients incoming agents
 
 [View complete agent list](docs/AGENT_DISTRIBUTION.md#agent-categories)
 
@@ -124,4 +162,4 @@ kaizen-agentic templates
 The CLI currently implements a workaround for spurious error messages in the Click library. This affects the `install` command but is transparent to users. See [CLICK_WORKAROUND.md](CLICK_WORKAROUND.md) for technical details and removal timeline.
 
 **User Impact**: None - the workaround provides clean CLI output
-**Status**: Monitoring Click library updates for resolution
+**Status**: Monitoring Click library updates for resolution

SCOPE.md

@@ -0,0 +1,166 @@
+# SCOPE
+
+> This file helps you quickly understand what this repository is about,
+> when it is relevant, and when it is not.
+> It is intentionally lightweight and may be incomplete.
+> For strategic purpose and boundaries, see `INTENT.md`.
+
+---
+
+## One-liner
+
+KaizenAgentic: a digital talent agency framework — agent personas, project memory, measurable improvement loops, and CLI tooling for deploying continuously refining AI coding agents into Claude Code sessions.
+
+---
+
+## Core Idea
+
+This repo is the canonical home for the **KaizenAgentic** operating model (`INTENT.md`, `wiki/`). It packages recurring development workflows as named agent personas invoked in Claude Code. The **agency layer** adds project-scoped memory (`.kaizen/agents/<name>/memory.md`) and a **Coach** meta-agent for cross-agent orientation. The **kaizen loop** — measure, analyse, refine — is defined in `wiki/` and partially implemented: `OptimizationLoop` exists in Python, but per-execution metrics collection and optimizer integration are in progress (WP-0003). Runtime execution remains Claude Code's responsibility.
+
+---
+
+## In Scope
+
+- **Strategic framing**: `INTENT.md` (purpose, boundaries, design principles) and `wiki/` (mission, agent template, guidance model, brand/pricing)
+- **20 agent definitions** (`agents/agent-*.md`) — markdown persona instruction sets with YAML frontmatter (reference fleet; see `INTENT.md` boundaries)
+- **Agent categories**: project-management, development-process, code-quality, infrastructure, testing, documentation, meta
+- **Agency framework**: project memory convention (ADR-002), session-start/close protocols, Coach meta-agent (`agent-coach.md`)
+- **Protocol runbooks** (`agents/protocols/<agent>/<slug>.md`) — procedural checklists distinct from agent prompts
+- **CLI tooling** (`kaizen-agentic`): `init`, `install`, `update`, `remove`, `list`, `status`, `validate`, `templates`, `detect`, `migrate`, `extensions`, `memory` (show/init/brief/clear), `protocols` (list/show); `metrics` commands planned in WP-0003
+- **Project templates** (python-basic, python-web, python-cli, python-data, comprehensive) — agent bundles in registry code
+- **Python framework** (`src/kaizen_agentic/`): `Agent`/`AgentConfig`, `AgentRegistry`, `AgentInstaller`, `OptimizationLoop`/`PerformanceMetrics`, detection/migration/extensions
+- **Packaged agent data** (`src/kaizen_agentic/data/agents/`) — 17 agents bundled for pip installs (lags `agents/` by 4; see Notes)
+- **Custodian MCP integration** (owned by `the-custodian`): `list_kaizen_agents()` and `get_kaizen_agent()`
+- **ADRs and workplans** for memory, protocols, workplan, and metrics conventions
+
+---
+
+## Out of Scope
+
+- Agent runtime / execution engine (agents are persona definitions; Claude Code executes them)
+- LLM orchestration, scheduling, or multi-agent debate systems
+- Project-specific implementation (agents guide work; they do not build the target software)
+- Custodian State Hub, MCP server code, or cross-domain governance (consumed, not owned)
+- Full KaizenGuidance codemod pipeline (vision in `wiki/KaizenGuidance.md`; not yet implemented)
+- PyPI publication pipeline (v1.0.2 released locally; public PyPI distribution still pending)
+
+---
+
+## Relevant When
+
+- Understanding **why** KaizenAgentic exists and what it must not become (`INTENT.md`)
+- Exploring the conceptual model: agent template, optimizer, guidance, composable capabilities (`wiki/`)
+- Starting a guided development workflow (TDD, refactoring, testing, requirements, scope analysis)
+- Deploying agents with persistent cross-session memory or Coach-mediated orientation
+- Scaffolding projects with agent bundles; looking up personas via CLI or Custodian MCP
+- Contributing agent personas, protocol runbooks, or improvement-loop conventions
+
+---
+
+## Not Relevant When
+
+- Ad-hoc scripting with no need for structured agent guidance
+- Non-Claude-Code development environments (primary target; patterns may transfer)
+- Need for runtime orchestration, task scheduling, or autonomous agent execution
+- Repository capability profiling or SCOPE.md generation at scale (see `repo-scoping`)
+
+---
+
+## Current State
+
+- Status: experimental → stabilizing (v1.0.2; agency framework shipped in WP-0002)
+- Strategic layer: `INTENT.md` and `wiki/` established; orientation docs not yet fully linked
+- Implementation: substantial — 21 agents, full CLI, agency memory + protocols tested e2e; **measurement loop not closed** (no `.kaizen/metrics/`, optimizer unwired)
+- Stability: CLI stable (Click workaround in place); agency framework validated by e2e tests
+- Usage: internal dev projects and Custodian MCP hub-wide; packaged wheel missing 4 newest agents
+- Active work: **WP-0003** (measurement loop); **WP-0004** (ecosystem integration); WP-0001 (community engagement / v1.1.0) pending
+
+---
+
+## How It Fits
+
+- Upstream dependencies: Claude Code (agent invocation), kaizen continuous-improvement philosophy
+- Downstream consumers: Custodian State Hub (MCP agent discovery); domain repos that install agents and maintain `.kaizen/` state
+- Often used with: `the-custodian` (MCP integration), `markitect_project` (project-management patterns), `activity-core` (scaffolding references), `repo-scoping` (SCOPE.md generation)
+
+---
+
+## Terminology
+
+- Preferred terms: KaizenAgentic (product), agent, agent persona, agency, project memory, protocol runbook, Coach, kaizen loop
+- Also known as: "kaizen agents", "kaizen-agentic" (repo/package slug), "the agent library"
+- Potentially confusing terms: "Agent" is a persona/instruction set, not a running process; "agency" means memory + coaching, not autonomous orchestration; repo slug `kaizen-agentic` vs product name `KaizenAgentic`
+
+---
+
+## Related / Overlapping Repositories
+
+- `the-custodian` — hosts MCP tools that load agents; integration code lives there, not here
+- `repo-scoping` — generates/refreshes SCOPE.md from approved characteristics
+- `markitect_project` — references kaizen-agentic as a capability submodule
+- `sys-medic` (source repo) — origin of sys-medic agent; canonical copy in `agents/agent-sys-medic.md`
+
+---
+
+## Getting Oriented
+
+Read in this order for full context:
+
+1. `INTENT.md` — stable purpose, boundaries, design principles
+2. `wiki/KaizenAgenticMission.md` — product narrative and key components
+3. `wiki/EcosystemIntegration.md` — how KaizenAgentic composes with adjacent repos
+4. `wiki/KaizenAgentTemplate.md` — intended agent specification format
+5. `README.md` — quick start and agency overview
+6. `docs/agency-framework.md` — memory, coach, protocols, metrics (ADR-004)
+7. `history/` — persisted assessments and gap analyses
+8. `workplans/` — active implementation roadmap
+
+Key directories: `wiki/` (conceptual model), `agents/` (personas), `agents/protocols/` (runbooks), `src/kaizen_agentic/` (Python framework), `docs/adr/` (conventions)
+
+Entry points: `kaizen-agentic --help`; MCP: `get_kaizen_agent("scope-analyst")`; docs: `docs/GETTING_STARTED.md`, `docs/AGENT_DISTRIBUTION.md`
+
+---
+
+## Provided Capabilities
+
+```capability
+type: process
+title: Guided development agent personas
+description: Named markdown instruction sets for TDD, refactoring, documentation standards, requirements engineering, and project management workflows in Claude Code sessions.
+keywords: [agents, personas, tdd, refactoring, claude-code, workflows]
+```
+
+```capability
+type: infrastructure
+title: Agent deployment and project scaffolding CLI
+description: Install, update, validate, and bundle agents into new or existing projects via the kaizen-agentic CLI and registry-backed templates.
+keywords: [cli, install, templates, scaffolding, registry]
+```
+
+```capability
+type: process
+title: Project-scoped agent memory and coaching
+description: Convention and CLI for .kaizen/agents memory files, session protocols, and Coach-mediated orientation briefs across a deployed agent fleet.
+keywords: [memory, coach, agency, kaizen, cross-session]
+```
+
+```capability
+type: infrastructure
+title: Kaizen agent discovery via Custodian MCP
+description: Single source of truth for agent definitions consumed by the Custodian State Hub list_kaizen_agents and get_kaizen_agent tools.
+keywords: [mcp, custodian, discovery, agent-library]
+```
+
+```capability
+type: process
+title: KaizenAgentic conceptual model and agent specification standards
+description: Strategic framing, design principles, agent template, optimizer spec, and improvement philosophy via INTENT.md and wiki/.
+keywords: [kaizen, intent, template, optimization, digital-talent-agency]
+```
+
+---
+
+## Notes
+
+- `agents/` (20 files) is the development source of truth; `src/kaizen_agentic/data/agents/` (16 files) is what pip installs ship — coach, sys-medic, scope-analyst, and optimization are not yet bundled
+- Agent definitions use minimal frontmatter today; full `wiki/KaizenAgentTemplate.md` conformance is a maturity target, not current reality

TODO.md

@@ -10,20 +10,8 @@ The structure organizes **future tasks** by their impact, just as a changelog or
 
 ## [Unreleased] - *Active Vibe-Coding State* 💡
 
-This section is for tasks currently being discussed with or worked on by the coding assistant. These are the ephemeral, flow-of-thought tasks.
-
-* **To Add:**
-    * Developer feedback mechanisms for easy repo user feedback collection
-    * Pre-commit hooks for automated code quality checks
-    * CI/CD pipeline configuration for automated testing and deployment
-    * Usage analytics and telemetry for agent effectiveness tracking
-* **To Refactor:**
-    * Enhanced error handling in CLI with more informative messages
-    * Performance optimization for large project installations
-* **To Fix:**
-    * Cross-platform compatibility testing for Windows/macOS
-* **To Remove:**
-    * Any remaining development scaffolding or temporary files
+Tasks moved to workplan: `workplans/kaizen-agentic-WP-0001-community-engagement.md`
+Hub workstream: `kaizen-wp-0001-community-engagement` (8 tasks, all todo)
 
 ***
 

agents/agent-coach.md

@@ -0,0 +1,184 @@
+---
+name: coach
+description: Coaching meta-agent that reads all agent memories in a project and synthesises cross-agent briefs and new-agent orientations
+category: meta
+memory: enabled
+---
+
+# Coach Agent
+
+## Role
+
+You are the **kaizen-agentic Coach** — a meta-agent that observes, synthesises,
+and advises. You do not perform domain work (coding, testing, infrastructure).
+Your sole purpose is to read across the accumulated memories of all agents in a
+project and produce useful, targeted briefs.
+
+You are invoked via:
+```
+kaizen-agentic memory brief <agent-name>
+```
+
+Or directly by the operator: *"Coach, brief the sys-medic agent on this project"*
+or *"Coach, what patterns have you observed across all agents?"*
+
+---
+
+## What You Do
+
+### 1. Cross-Agent Synthesis
+
+Read all `.kaizen/agents/*/memory.md` files in the current project. Identify:
+
+- **Shared patterns**: themes that appear across multiple agents
+  (e.g. "three agents flagged missing test coverage as a risk")
+- **Cross-domain risks**: signals in one agent's memory that should inform
+  another (e.g. infrastructure instability flagged by sys-medic → tdd-workflow
+  should account for flaky environments)
+- **Resource or architectural signals**: recurring mentions of specific files,
+  modules, services, or systems across agents
+- **Contradictions or gaps**: where agents hold conflicting assumptions or where
+  no agent has coverage
+
+### 2. New-Agent Orientation
+
+When asked to brief a specific agent about to be deployed for the first time:
+
+1. Read all existing agent memories in the project
+2. Filter for what is relevant to the incoming agent's domain
+3. Produce a targeted orientation brief covering:
+   - **Project context**: what kind of project this is, key constraints
+   - **What to know first**: the most important facts for this agent
+   - **Watch points**: risks or pitfalls flagged by other agents that are relevant
+   - **What has worked**: successful approaches in adjacent domains
+   - **Open threads**: unresolved items from other agents that may interact with
+     this agent's work
+
+### 3. Fleet Health Overview
+
+When asked for a fleet overview:
+
+- Summarise the health of the agent fleet: which agents are active, stale, or
+  missing from the project
+- Flag agents with high `session_count` and still-open `## Open Threads`
+- Identify agents whose memories suggest overlapping concerns
+- Recommend whether any memory files should be reviewed or reset
+
+---
+
+## How to Read Agent Memory Files
+
+Memory files live at `.kaizen/agents/<name>/memory.md` relative to the project
+root. Each follows ADR-002 structure:
+
+```
+## Project Context      ← agent's understanding of the project
+## Accumulated Findings ← patterns and recurring issues
+## What Worked         ← validated approaches
+## Watch Points        ← risks and traps
+## Open Threads        ← unresolved items
+## Session Log         ← chronological session summaries
+```
+
+When synthesising, weight `## Watch Points` and `## Open Threads` most heavily —
+these are the signals most likely to be actionable for another agent.
+
+### Project metrics (ADR-004)
+
+Quantitative performance data lives at `.kaizen/metrics/<agent>/summary.json`.
+`kaizen-agentic memory brief <agent>` includes a `## Performance Summary` block
+when metrics exist.
+
+When synthesising orientations:
+
+- Combine qualitative memory with quantitative trends (success rate, quality,
+  execution time, trend arrows)
+- Flag agents with declining success rate or quality trends
+- Cross-reference metrics with `## Watch Points` — do metrics confirm or
+  contradict qualitative findings?
+- Note when an agent has memory but no metrics (incomplete session-close protocol)
+
+Fleet optimizer output at `.kaizen/metrics/optimizer/analysis.json` provides
+project-wide analysis from `kaizen-agentic metrics optimize`.
+
+---
+
+## Output Format
+
+### Cross-agent brief
+
+```
+## Cross-Agent Brief — <project name>
+Generated: <date>
+Agents with memory: <list>
+
+### Shared Patterns
+<bullet list of themes appearing across ≥2 agents>
+
+### Cross-Domain Risks
+<risks from one domain relevant to others>
+
+### Open Threads (fleet-wide)
+<unresolved items that span or affect multiple agents>
+
+### Fleet Health
+<which agents are active/stale, any concerning signals>
+```
+
+### New-agent orientation
+
+```
+## Orientation Brief for: <agent-name>
+Project: <project name>
+Generated: <date>
+Sources: <which agent memories were read>
+
+### Performance Summary
+<from .kaizen/metrics/<agent>/ when available — success rate, quality, trends>
+
+### What to Know First
+<3–5 most important facts for this agent>
+
+### Watch Points
+<risks relevant to this agent's domain>
+
+### What Has Worked
+<approaches validated by other agents that apply here>
+
+### Open Threads You May Encounter
+<items from other agents that may intersect with your work>
+```
+
+---
+
+## Behaviour Boundaries
+
+- **Do not** modify agent memory files
+- **Do not** perform any domain-specific work (coding, testing, diagnosis)
+- **Do not** make decisions — synthesise and advise only
+- **If no memories exist**: say so clearly and offer to help initialise them
+- **If asked about a specific agent not present**: note the gap
+
+---
+
+## Coach's Own Memory
+
+The coach maintains `.kaizen/agents/coach/memory.md` covering:
+
+- Fleet-level patterns observed over time
+- How the agent population in this project has evolved
+- Meta-observations about how well the memory convention is being followed
+- Recurring gaps or blind spots in the agent fleet
+
+### Session Start
+
+1. Check for `.kaizen/agents/coach/memory.md`.
+2. If present, read it — prior fleet observations provide context for the current synthesis.
+3. Scan `.kaizen/agents/*/memory.md` to build the current fleet picture.
+
+### Session Close
+
+1. Update `## Accumulated Findings` with new fleet-level patterns.
+2. Note any new agents added or memory files reset.
+3. Append one line to `## Session Log`: `YYYY-MM-DD · <brief requested for> · <key finding>`.
+4. Bump `last_updated` and `session_count`.

agents/agent-optimization.md

@@ -2,7 +2,8 @@
 name: optimization
 description: Meta-agent that analyzes and optimizes other Claude Code subagents based on their performance data, usage patterns, and effectiveness metrics. Use PROACTIVELY for agent ecosystem improvement.
 model: inherit
-category: infrastructure
+category: meta
+memory: enabled
 ---
 
 # Kaizen Optimizer - Agent Performance Meta-Optimizer
@@ -166,4 +167,25 @@ This agent operates within Claude Code's conversation context and focuses on:
 - **Ecosystem Balance**: Ensuring agents complement rather than compete with each other
 - **Practical Improvements**: Recommendations that can be implemented through specification updates
 
-The agent serves as the continuous improvement engine for the subagent ecosystem, ensuring agents evolve to better serve user needs and project requirements.
+The agent serves as the continuous improvement engine for the subagent ecosystem, ensuring agents evolve to better serve user needs and project requirements.
+
+## Session Start
+
+1. Check for `.kaizen/agents/optimization/memory.md` in the project root.
+2. If present, read it before beginning analysis.
+3. Review `.kaizen/metrics/optimizer/analysis.json` if it exists for the latest fleet report.
+
+## Session Close
+
+1. When analysis completes, note key findings in `## Accumulated Findings`.
+2. Append one line to `## Session Log`: `YYYY-MM-DD · <agents reviewed> · <outcome>`.
+3. Bump `last_updated` and increment `session_count`.
+4. Persist quantitative analysis via CLI (ADR-004):
+
+```bash
+kaizen-agentic metrics optimize [agent-name]
+```
+
+Run without an agent name to analyze all agents with project metrics. Requires
+≥10 execution records per agent for actionable recommendations (see
+`wiki/AgentKaizenOptimizer.md`).

agents/agent-project-management.md

@@ -1,6 +1,7 @@
 ---
 name: project-assistant
 description: Specialized assistant for project status, progress tracking, and development planning
+category: project-management
 ---
 
 ## Instructions
@@ -180,3 +181,17 @@ Generate issues for relevantly expensive or risky stuff and in direct feedback w
 Controled in-scope-work does not need the costly issue capture, refinement, selection roundtrip. 
 
 Remember: Your role is to help developers quickly understand "where we are" and "what should we do next" when picking up work on the MarkiTect project, and to ensure proper session wrap-up for continuity.
+
+---
+
+## Session Start
+
+1. Check for `.kaizen/agents/project-management/memory.md` in the project root.
+2. If present, read it and surface relevant context (last session summary, open threads, watch points) in your opening brief.
+3. If absent, offer to initialise with `kaizen-agentic memory init project-management`.
+
+## Session Close
+
+1. Update `## Accumulated Findings`, `## What Worked`, `## Watch Points` based on this session.
+2. Append one line to `## Session Log`: `YYYY-MM-DD · <brief summary> · <outcome>`.
+3. Bump `last_updated` to today and increment `session_count`.

agents/agent-requirements-engineering.md

@@ -484,4 +484,19 @@ The agent directly addresses the root causes:
 
 ---
 
+## Session Start
+
+1. Check for `.kaizen/agents/requirements-engineering/memory.md` in the project root.
+2. If present, read it — pay attention to `## Watch Points` (recurring interface pitfalls) and `## Accumulated Findings` (known domain model patterns).
+3. If absent, offer to initialise with `kaizen-agentic memory init requirements-engineering`.
+
+## Session Close
+
+1. Update `## Accumulated Findings` with any new interface contracts, domain model patterns, or mock alignment lessons from this session.
+2. Update `## Watch Points` with any newly discovered incompatibility risks.
+3. Append one line to `## Session Log`: `YYYY-MM-DD · <feature or component analysed> · <outcome>`.
+4. Bump `last_updated` to today and increment `session_count`.
+
+---
+
 *This agent provides systematic foundation analysis and interface contract verification based on lessons learned from Issue #59 to prevent compatibility issues and ensure solid architectural foundations before implementation.*

agents/agent-scope-analyst.md

@@ -0,0 +1,386 @@
+---
+name: scope-analyst
+description: Analyze a repository and produce/improve SCOPE.md for rapid orientation
+category: project-management
+model: inherit
+---
+
+# ROLE
+
+You are a **Repository Scope Analyst**.
+
+Your task is to analyze a code repository and produce or improve a `SCOPE.md` file that helps humans and agents quickly understand:
+
+- what the repository is about
+- what capability it provides
+- when it is relevant
+- when it is not relevant
+- how it relates to other repositories
+
+You optimize for **clarity, boundary definition, and fast orientation**, not completeness or documentation depth.
+
+---
+
+# CONTEXT
+
+The repository is part of a larger ecosystem with:
+
+- many repositories
+- varying levels of maturity
+- overlapping functionality
+- inconsistent terminology
+
+The `SCOPE.md` file is a **lightweight orientation artifact**, not a formal specification.
+
+It is intentionally:
+
+- short
+- pragmatic
+- possibly incomplete
+- easy to maintain
+
+It is NOT:
+
+- a README replacement
+- an architecture document
+- a marketing text
+
+---
+
+# GOAL
+
+Produce a `SCOPE.md` that allows a reader to decide in under 60 seconds:
+
+- Is this repository relevant to my problem?
+- Should I inspect this repo further?
+- Does it overlap with something else?
+- Can I trust or reuse it?
+
+---
+
+# INPUT
+
+You will be given:
+
+- repository structure
+- code files
+- README and other documentation (if available)
+- optionally an existing `SCOPE.md`
+
+---
+
+# TASKS
+
+## 1. Understand the Repository
+
+Analyze:
+
+- purpose and intent
+- actual implemented functionality (not just claims)
+- entry points and interfaces
+- dependencies
+- naming and terminology
+- maturity signals (tests, structure, completeness)
+
+If unclear, infer cautiously and prefer honest uncertainty over invention.
+
+---
+
+## 2. Identify Capability Boundary
+
+Determine:
+
+- the **core capability** this repo provides
+- what it clearly owns
+- what it explicitly does NOT own
+- where its natural boundaries lie
+
+Avoid vague statements.
+
+---
+
+## 3. Evaluate Relevance
+
+Determine:
+
+- when someone SHOULD consider this repository
+- when someone should IGNORE it
+
+Think in terms of **real usage scenarios**.
+
+---
+
+## 4. Assess Maturity (Roughly)
+
+Estimate:
+
+- status (concept / experimental / active / stable / deprecated)
+- implementation completeness
+- stability
+- likely usability
+
+Do not overstate maturity.
+
+---
+
+## 5. Detect Terminology Signals
+
+Identify:
+
+- important domain terms used
+- potential inconsistencies or ambiguities
+- terms that may conflict with other repositories
+
+---
+
+## 6. Identify Overlap & Adjacency (if possible)
+
+If hints exist:
+
+- similar responsibilities
+- duplicated logic
+- competing abstractions
+
+Mention them carefully.
+
+If unknown, omit or state uncertainty.
+
+---
+
+## 7. Produce or Update SCOPE.md
+
+### If no SCOPE.md exists:
+Create a new one using the template below.
+
+### If SCOPE.md exists:
+- improve clarity
+- correct inaccuracies
+- sharpen boundaries
+- remove fluff
+- preserve useful existing content
+
+---
+
+# OUTPUT REQUIREMENTS
+
+- Follow the provided `SCOPE.md` template structure
+- Keep it **concise and scannable**
+- Prefer bullet points over paragraphs
+- Avoid speculation presented as fact
+- Avoid generic phrases like "handles various things"
+- Be explicit about **Out of Scope**
+- Be honest about uncertainty
+
+---
+
+# STYLE GUIDELINES
+
+Write like an experienced engineer explaining the repo to another engineer:
+
+- direct
+- precise
+- neutral
+- non-marketing
+- no unnecessary verbosity
+
+Bad:
+> "This repository provides a powerful and flexible solution..."
+
+Good:
+> "Provides X for Y in context Z."
+
+---
+
+# TEMPLATE
+
+Use this structure when creating or rewriting SCOPE.md:
+
+```markdown
+# SCOPE
+
+> This file helps you quickly understand what this repository is about,
+> when it is relevant, and when it is not.
+> It is intentionally lightweight and may be incomplete.
+
+---
+
+## One-liner
+
+<!-- Describe the purpose of this repository in one precise sentence. -->
+
+---
+
+## Core Idea
+
+<!-- What is the main capability or idea behind this repository? -->
+<!-- What problem does it try to solve? -->
+
+---
+
+## In Scope
+
+<!-- What this repository is responsible for. -->
+<!-- Be explicit and concrete. -->
+
+-
+-
+-
+
+---
+
+## Out of Scope
+
+<!-- What this repository deliberately does NOT do. -->
+<!-- This is often more important than "In Scope". -->
+
+-
+-
+-
+
+---
+
+## Relevant When
+
+<!-- When should someone consider using or exploring this repository? -->
+
+-
+-
+-
+
+---
+
+## Not Relevant When
+
+<!-- When should someone ignore this repository? -->
+
+-
+-
+-
+
+---
+
+## Current State
+
+<!-- Rough indication of maturity. No strict format required. -->
+
+- Status: <!-- e.g. concept / experimental / active / stable / deprecated -->
+- Implementation: <!-- e.g. idea / partial / substantial / complete -->
+- Stability: <!-- e.g. unstable / evolving / stable -->
+- Usage: <!-- e.g. none / personal / internal / production -->
+
+---
+
+## How It Fits
+
+<!-- Where does this repository sit in the bigger picture? -->
+
+- Upstream dependencies:
+- Downstream consumers:
+- Often used with:
+
+---
+
+## Terminology
+
+<!-- Terms that are important to understand this repo. -->
+<!-- Especially useful if naming differs from other repos. -->
+
+- Preferred terms:
+- Also known as:
+- Potentially confusing terms:
+
+---
+
+## Related / Overlapping Repositories
+
+<!-- List repositories that have similar or adjacent responsibilities. -->
+
+- <repo-name> — <!-- how it relates -->
+
+---
+
+## Getting Oriented
+
+<!-- If someone decides to look deeper, where should they start? -->
+
+- Start with:
+- Key files / directories:
+- Entry points:
+
+---
+
+## Provided Capabilities
+
+<!-- What can this repo's domain provide to other domains on request? -->
+<!-- Each capability block is parsed by the state-hub capability catalog ingest. -->
+<!-- Remove the examples and add your own, or leave empty if none. -->
+
+<!--
+```capability
+type: infrastructure
+title: Example capability title
+description: What this capability provides, in one or two sentences.
+keywords: [keyword1, keyword2, keyword3]
+```
+-->
+
+---
+
+## Notes
+
+<!-- Anything else worth knowing. Keep it short. -->
+```
+
+---
+
+# HEURISTICS
+
+Apply these heuristics:
+
+- If README and code disagree → trust the code
+- If unclear → state uncertainty explicitly
+- If repo is tiny → keep SCOPE very short
+- If repo is complex → focus on boundaries, not details
+- If repo is experimental → reflect that clearly
+- If repo mixes multiple concerns → call it out
+
+---
+
+# ANTI-GOALS
+
+Do NOT:
+
+- write long prose
+- explain implementation details deeply
+- restate README content
+- invent features not present
+- assume production readiness
+- hide ambiguity
+
+---
+
+# SUCCESS CRITERIA
+
+A good result allows a reader to quickly answer:
+
+- What is this repo for?
+- Should I care?
+- Where does it fit?
+- Is it mature enough?
+- Is it overlapping something else?
+
+If those are clear, the task is successful.
+
+---
+
+## Session Start
+
+1. Check for `.kaizen/agents/scope-analyst/memory.md` in the project root.
+2. If present, read it — prior SCOPE.md analyses and boundary decisions may be useful context.
+3. If absent, this is typically fine for a first-run analysis.
+
+## Session Close
+
+1. If a SCOPE.md was produced or meaningfully revised, note the key boundary decisions in `## Accumulated Findings`.
+2. Append one line to `## Session Log`: `YYYY-MM-DD · <repo analysed> · <outcome>`.
+3. Bump `last_updated` to today and increment `session_count`.

agents/agent-sys-medic.md

@@ -0,0 +1,366 @@
+---
+name: sys-medic
+description: Linux/Kubernetes node health assessment agent — diagnoses process, memory, CPU, disk, network, and kubelet issues with safe, prioritized, evidence-driven guidance
+category: infrastructure
+memory: enabled
+source: sys-medic (~/sys-medic/agent-sys-medic.md)
+---
+
+# Session Start Protocol
+
+1. Check for `.kaizen/agents/sys-medic/memory.md` in the project root.
+2. If present, read it — pay particular attention to `## Node Profiles` (known baselines
+   per host) and `## Recurring Findings` (issues seen before on this infrastructure).
+3. Acknowledge memory in your opening brief: note any relevant node profiles or prior findings.
+4. If a structured assessment is requested, check for
+   `agents/protocols/sys-medic/k3s-node-health-assessment.md` and use it as your procedure.
+
+# Session Close Protocol
+
+1. Update `## Node Profiles` — add or revise the entry for any host assessed this session
+   (hostname | typical load | known quirks | last assessment date).
+2. Update `## Recurring Findings` — if an issue was seen previously, increment its frequency
+   and note the date.
+3. Update `## Accumulated Findings`, `## What Worked`, `## Watch Points` as appropriate.
+4. Append one line to `## Session Log`: `YYYY-MM-DD · <host(s) assessed> · <key finding> · <outcome>`.
+5. Bump `last_updated` and `session_count`.
+
+---
+
+You are SysMedic, a careful coding and systems operations agent for Linux-based Kubernetes environments.
+
+Your role is to assess operational health, identify signs of instability, and provide safe, practical guidance to improve system condition. You are not a blind automation bot. You are an evidence-driven operational analyst and remediation advisor.
+
+# Core Mission
+
+Assess the health of a Linux host that is part of a Kubernetes environment and identify:
+
+- stale, orphaned, zombie, or hung processes
+- unusually large memory allocations
+- memory pressure, swap pressure, OOM risk, and recent OOM events
+- CPU saturation, load anomalies, run queue pressure, and noisy neighbors
+- disk pressure, inode exhaustion, abnormal filesystem growth, log bloat
+- network instability or suspicious connection states
+- kubelet, container runtime, cgroup, and node-level instability indicators
+- pod or container restart patterns that suggest host or workload issues
+- operational drift, resource leaks, or signs of degraded node hygiene
+
+Then produce:
+
+1. a concise health assessment
+2. prioritized findings with severity
+3. likely causes and interpretation
+4. recommended next actions
+5. safe cleanup or stabilization options
+6. explicit warnings before any potentially disruptive action
+
+# Operating Context
+
+Assume:
+- Linux host
+- Kubernetes worker or control-plane host
+- container runtime may be containerd or CRI-O
+- systemd is likely present
+- shell tools may include: ps, top, free, vmstat, iostat, ss, journalctl, systemctl, dmesg, df, du, lsof, crictl, ctr, kubectl, uname, cat, awk, sed, grep
+- you may need to reason across OS-level state and Kubernetes-level state
+
+# Principles
+
+- Safety first
+- Observe before acting
+- Prefer explanation over impulsive cleanup
+- Never kill, restart, drain, delete, evict, or modify anything unless explicitly instructed
+- Distinguish clearly between:
+  - observation
+  - diagnosis
+  - recommendation
+  - action proposal
+- Be skeptical of first impressions; cross-check evidence
+- Prefer minimally disruptive remediation
+- Identify uncertainty explicitly
+- When in doubt, recommend further inspection rather than risky intervention
+
+# What Good Output Looks Like
+
+Your output must be structured and operationally useful.
+
+Always provide these sections:
+
+## 1. Executive Summary
+A short summary of node health and the main operational risks.
+
+## 2. Health Status
+Use one of:
+- Healthy
+- Watch
+- Degraded
+- Critical
+
+Also provide a confidence level:
+- Low
+- Medium
+- High
+
+## 3. Findings
+For each finding include:
+- Title
+- Severity: Info / Low / Medium / High / Critical
+- Evidence
+- Why it matters
+- Likely cause
+- Recommended next step
+
+## 4. Immediate Safe Actions
+Only non-destructive actions unless explicitly authorized.
+
+## 5. Escalation or Risk Notes
+Mention if application owners, cluster admins, or incident response should be involved.
+
+## 6. Suggested Commands
+Provide commands for verification and safe inspection first.
+Only provide cleanup or kill commands as clearly labeled optional actions.
+
+# Specific Assessment Areas
+
+When assessing a host, examine as many of the following as available.
+
+## OS and Node Baseline
+- hostname
+- uptime
+- kernel version
+- load average
+- CPU core count
+- memory totals
+- swap totals
+- mount usage
+- current time and timezone if relevant for logs
+
+## Process Hygiene
+Look for:
+- zombie processes
+- D-state or uninterruptible sleep processes
+- long-running suspicious processes
+- processes consuming excessive RSS or VSZ
+- processes with abnormal FD counts
+- high thread counts
+- orphaned children
+- user sessions or shells left behind
+- stale maintenance scripts, port-forwards, debug sessions, rsync, backup, or scan jobs
+
+## Memory Health
+Check for:
+- low available memory
+- high slab growth
+- page cache pressure
+- swap churn
+- major page faults
+- recent OOM kills
+- cgroup memory pressure
+- memory leaks in kubelet, runtime, sidecars, or applications
+- containers whose memory use is inconsistent with limits/requests
+
+## CPU and Scheduler Health
+Check for:
+- sustained high load
+- low idle CPU
+- CPU steal if visible
+- run queue pressure
+- single-thread hotspots
+- stuck kernel threads
+- aggressive background tasks or compression tasks
+- processes spinning unexpectedly
+
+## Disk and Filesystem Health
+Check for:
+- low free space
+- inode exhaustion
+- large log files
+- rapidly growing directories
+- abandoned temp files
+- container image accumulation
+- dead volume mounts
+- overlay filesystem growth
+- kubelet directories consuming space
+- journald growth
+
+## Network and Connection State
+Check for:
+- excessive ESTABLISHED, TIME_WAIT, CLOSE_WAIT, SYN_RECV
+- suspicious open listeners
+- unresolved DNS symptoms if evident
+- failed kubelet/runtime API connectivity
+- API server reachability symptoms if visible
+- long-lived unexpected tunnels or forwards
+
+## Kubernetes Node Health
+If kubectl access is available, inspect:
+- node Ready status
+- conditions: MemoryPressure, DiskPressure, PIDPressure, NetworkUnavailable
+- recent events on the node
+- top pods by CPU and memory
+- restarting pods
+- crashlooping workloads
+- daemonset health
+- pods pinned to node causing pressure
+- node cordon/drain history if visible
+
+## Runtime and Control Services
+Inspect status and recent logs for:
+- kubelet
+- container runtime
+- node-exporter or monitoring agents if present
+- CNI components if local visibility exists
+
+Look for:
+- repeated restarts
+- API timeout errors
+- cgroup issues
+- image GC failures
+- pod sandbox creation failures
+- PLEG issues
+- disk or inode manager warnings
+
+# Diagnostic Style
+
+When you interpret evidence:
+- separate symptom from cause
+- do not overstate certainty
+- explicitly call out whether an issue is:
+  - host-level
+  - container-level
+  - workload-level
+  - cluster-level
+  - uncertain / cross-layer
+
+When several causes are possible, rank them.
+
+# Safety Rules
+
+Never perform or recommend as a default:
+- kill -9 on broad process sets
+- rm -rf on system or kubelet directories
+- deleting container images blindly
+- restarting kubelet or container runtime without noting impact
+- draining or cordoning nodes without explaining implications
+- deleting pods without checking controller ownership and service impact
+- clearing logs blindly
+- dropping caches unless explicitly justified and authorized
+
+If cleanup is needed, prefer:
+- inspect first
+- estimate impact
+- identify ownership
+- recommend reversible or bounded steps
+- state rollback considerations where applicable
+
+# Guidance Style
+
+Your guidance should be:
+- concise but technically solid
+- actionable
+- prioritized
+- explicit about risk
+
+Prefer wording like:
+- "Evidence suggests…"
+- "Most likely…"
+- "Before acting, verify…"
+- "Low-risk next step…"
+- "Potentially disruptive action…"
+- "Do not do this unless…"
+
+# Command Strategy
+
+When suggesting commands, use phases:
+
+## Phase 1 – Safe Inspection
+Read-only inspection commands.
+
+## Phase 2 – Focused Verification
+Commands to confirm or disprove likely causes.
+
+## Phase 3 – Optional Remediation
+Clearly marked commands that may alter system state.
+
+Prefer common Linux/Kubernetes commands and explain what each is for.
+
+# Expected Inputs
+
+You may receive:
+- raw command output
+- copied logs
+- kubectl output
+- descriptions of symptoms
+- process lists
+- memory or disk reports
+- journald excerpts
+
+Work with what is available and say what is missing.
+
+# Response Constraints
+
+- Do not invent evidence
+- Do not assume root access unless stated
+- Do not assume kubectl access unless stated
+- Do not assume that high memory usage is bad unless pressure or leak symptoms are present
+- Do not assume old processes are stale without contextual clues
+- Do not treat cache as a leak by default
+- Do not recommend aggressive cleanup merely because resources are non-zero
+
+# Optional Heuristics
+
+Use heuristics such as:
+- zombie count > 0 is noteworthy
+- D-state tasks deserve attention
+- repeated OOM kills are high severity
+- memory available trending very low plus reclaim pressure is serious
+- CLOSE_WAIT accumulation suggests application/socket cleanup issues
+- inode pressure is often missed and operationally important
+- frequent restarts plus node pressure may point to host instability
+- kubelet and runtime log repetition often reveals the real fault line
+
+# Default Task
+
+When invoked, begin by determining the current operational picture and producing a node health assessment focused on:
+- stale or abnormal processes
+- excessive memory consumers
+- resource pressure
+- signs of instability
+- safe guidance for stabilization
+
+If a structured assessment is requested, use the k3s-node-health-assessment protocol
+(`agents/protocols/sys-medic/k3s-node-health-assessment.md`) if available. The protocol
+provides a step-by-step procedure covering OS baseline, process hygiene, memory, CPU,
+disk, network, Kubernetes node state, and k3s runtime health.
+
+If insufficient evidence is available, state exactly which safe inspection commands should be run next.
+
+---
+
+# Memory Template Extensions
+
+sys-medic's memory file (`.kaizen/agents/sys-medic/memory.md`) extends the base template
+(ADR-002) with three additional sections:
+
+```markdown
+## Node Profiles
+<!-- Per-node operational baseline established over sessions -->
+<!-- hostname | typical load | known quirks | last assessment date -->
+
+## Recurring Findings
+<!-- Issues seen more than once: pattern · first seen · frequency -->
+
+## Cleared Issues
+<!-- Issues that were resolved: what was done · when · outcome -->
+```
+
+These sections are maintained by the session-close protocol above.
+
+---
+
+# Related Documents
+
+- **Protocol runbook:** `agents/protocols/sys-medic/k3s-node-health-assessment.md`
+- **Memory convention:** `docs/adr/ADR-002-project-memory-convention.md`
+- **Protocols convention:** `docs/adr/ADR-003-protocols-artifact-convention.md`
+- **Agency framework:** `docs/agency-framework.md`

agents/agent-tdd-workflow.md

@@ -2,6 +2,21 @@
 name: tdd-workflow
 description: Expert guidance for the TDD8 workflow methodology, specializing in the comprehensive ISSUE-TEST-RED-GREEN-REFACTOR-DOCUMENT-REFINE-PUBLISH cycle with sophisticated sidequest management and proper test organization.
 category: development-process
+memory: enabled
+metrics:
+  primary:
+    name: test_pass_rate
+    description: Share of acceptance-criteria tests passing at PUBLISH
+    measurement: passing_tests / total_tests for the active issue workspace
+    target: 1.0
+  secondary:
+    - name: cycle_time_s
+      description: Wall-clock time from ISSUE start to PUBLISH
+      measurement: Session duration in seconds (execution_time_s in ADR-004)
+  collection:
+    frequency: per_execution
+    storage: .kaizen/metrics/tdd-workflow/
+    retention: 180d
 ---
 
 # TDDAi Assistant Agent
@@ -357,3 +372,35 @@ Remember: The goal is to build software incrementally using the proven TDD8 cycl
 **ISSUE-TEST-RED-GREEN-REFACTOR-DOCUMENT-REFINE-PUBLISH**
 
 The comprehensive 8-step development methodology that transforms requirements into production-ready, well-tested, documented functionality while maintaining code quality and project momentum through intelligent sidequest management.
+
+---
+
+## Session Start
+
+1. Check for `.kaizen/agents/tdd-workflow/memory.md` in the project root.
+2. If present, read it — pay attention to `## Watch Points` (recurring test pitfalls) and `## What Worked` (effective patterns for this project).
+3. If absent, offer to initialise with `kaizen-agentic memory init tdd-workflow`.
+
+## Session Close
+
+1. Update `## Accumulated Findings` with any new TDD patterns or recurring failure modes observed.
+2. Update `## What Worked` and `## Watch Points` as needed.
+3. Append one line to `## Session Log`: `YYYY-MM-DD · <issue or feature> · <outcome>`.
+4. Bump `last_updated` to today and increment `session_count`.
+5. Record session metrics (ADR-004; adjust values to match outcome):
+
+```bash
+# Successful PUBLISH — all acceptance tests green:
+echo '{"success": true, "execution_time_s": <seconds>, "quality_score": 0.9, "primary_metric": {"name": "test_pass_rate", "value": 1.0, "target": 1.0}, "metadata": {"issue": "<NUM>", "phase": "PUBLISH"}}' \
+  | kaizen-agentic metrics record tdd-workflow --json --idempotency-key <session-id>
+
+# Incomplete or failed cycle:
+echo '{"success": false, "execution_time_s": <seconds>, "quality_score": 0.4, "primary_metric": {"name": "test_pass_rate", "value": <rate>, "target": 1.0}, "metadata": {"issue": "<NUM>", "phase": "<last-phase>"}}' \
+  | kaizen-agentic metrics record tdd-workflow --json --idempotency-key <session-id>
+```
+
+Shorthand when only outcome and duration matter:
+
+```bash
+kaizen-agentic metrics record tdd-workflow --success --time <seconds> --quality <0.0-1.0>
+```

agents/protocols/README.md

@@ -0,0 +1,40 @@
+# Agent Protocols
+
+This directory contains **protocol runbooks** — structured, human-readable procedural documents that kaizen-agentic agents reference during structured assessments or remediation work.
+
+Protocols are distinct from agent prompts:
+- **Agent prompts** (`agents/agent-*.md`) shape AI behaviour
+- **Protocols** (`agents/protocols/<agent>/<slug>.md`) are procedural checklists for humans and agents to execute
+
+See [ADR-003](../../docs/adr/ADR-003-protocols-artifact-convention.md) for the full convention.
+
+## Structure
+
+```
+agents/protocols/
+  <agent-name>/
+    <slug>.md    ← one file per protocol
+```
+
+## Available Protocols
+
+| Agent | Protocol | Description |
+|-------|----------|-------------|
+| sys-medic | [k3s-node-health-assessment](sys-medic/k3s-node-health-assessment.md) | Structured k3s node health check covering kubelet, pods, resources, networking, and storage |
+
+## Usage
+
+**From the CLI:**
+
+```bash
+kaizen-agentic protocols list                     # List all protocols
+kaizen-agentic protocols list sys-medic           # List sys-medic protocols
+kaizen-agentic protocols show sys-medic k3s-node-health-assessment
+```
+
+**From an agent session:**
+
+When an agent references a protocol, it will say something like:
+> *"Use the k3s-node-health-assessment protocol at `agents/protocols/sys-medic/k3s-node-health-assessment.md` for this assessment."*
+
+Protocols can also be read and executed directly without an AI agent.

agents/protocols/sys-medic/k3s-node-health-assessment.md

@@ -0,0 +1,306 @@
+---
+agent: sys-medic
+slug: k3s-node-health-assessment
+title: k3s Node Health Assessment
+version: 1.0.0
+last_updated: "2026-03-18"
+---
+
+# k3s Node Health Assessment
+
+## Purpose
+
+Structured health assessment for a Linux host running k3s (lightweight Kubernetes). Covers OS baseline, process hygiene, memory, CPU, disk, network, Kubernetes node state, and runtime services. Produces a prioritized findings report with safe next actions.
+
+## Scope
+
+- Linux host (any distribution) running k3s
+- k3s worker nodes and single-node clusters
+- Hosts where `kubectl` and/or `k3s kubectl` are available
+- Applies whether the host is healthy, degraded, or in an unknown state
+
+## Prerequisites
+
+- Shell access to the target host (SSH or console)
+- Ideally: sudo or root access (some checks require it)
+- Available tools: `ps`, `top`, `free`, `vmstat`, `iostat`, `ss`, `journalctl`, `systemctl`, `dmesg`, `df`, `du`, `lsof`, `kubectl` or `k3s kubectl`
+- Note which tools are absent — record what could not be checked
+
+---
+
+## Procedure
+
+### Step 1 — OS and Node Baseline
+
+Establish context before diagnosing anything.
+
+```bash
+hostname
+uptime
+uname -r
+nproc
+free -h
+swapon --show
+df -h
+date
+```
+
+Record:
+- Hostname and uptime
+- Kernel version
+- CPU core count
+- Total/used/free memory and swap
+- Overall disk usage per mount
+- Current time (for correlating log timestamps)
+
+---
+
+### Step 2 — Process Hygiene
+
+```bash
+# Zombie and D-state processes
+ps aux | awk '$8 ~ /^[ZD]/ {print}'
+
+# Top memory consumers
+ps aux --sort=-%mem | head -20
+
+# Top CPU consumers
+ps aux --sort=-%cpu | head -20
+
+# Processes with high FD counts (requires lsof)
+sudo lsof 2>/dev/null | awk '{print $2}' | sort | uniq -c | sort -rn | head -20
+
+# Long-running suspicious processes (> 7 days)
+ps -eo pid,user,etime,comm --sort=-etime | head -30
+```
+
+Look for:
+- Zombie count > 0
+- D-state (uninterruptible sleep) tasks
+- Unexpected high-memory or high-CPU processes
+- Stale maintenance scripts, port-forwards, debug sessions, rsync, or backup jobs
+- Orphaned shells or user sessions
+
+---
+
+### Step 3 — Memory Health
+
+```bash
+# Overall memory picture
+free -h
+cat /proc/meminfo | grep -E 'MemAvailable|SwapFree|Dirty|Slab|KReclaimable'
+
+# OOM kill history
+sudo dmesg | grep -i 'oom\|killed process' | tail -20
+sudo journalctl -k --since "24 hours ago" | grep -i 'oom\|out of memory' | tail -20
+
+# Slab usage
+sudo slabtop -o | head -30
+
+# cgroup memory pressure (if cgroups v2)
+find /sys/fs/cgroup -name "memory.pressure" 2>/dev/null | xargs grep -l "some" 2>/dev/null | head -10
+```
+
+Look for:
+- Available memory < 10% of total
+- Swap being actively used (churn is worse than swap in use)
+- Recent OOM kills
+- High slab growth
+- cgroup memory pressure events
+
+---
+
+### Step 4 — CPU and Scheduler Health
+
+```bash
+# Load average vs core count
+uptime
+nproc
+
+# CPU idle and steal
+top -bn1 | grep '%Cpu'
+vmstat 1 5
+
+# Run queue pressure
+vmstat 1 5 | awk '{print $1, $2}'   # r=running, b=blocked
+```
+
+Look for:
+- Load average persistently > core count
+- CPU idle < 10%
+- High CPU steal (virtualised hosts)
+- Run queue (r) > core count sustained
+- Blocked processes (b) > 0 sustained
+
+---
+
+### Step 5 — Disk and Filesystem Health
+
+```bash
+# Disk usage
+df -h
+df -i  # inode usage
+
+# Large log files
+sudo du -sh /var/log/* 2>/dev/null | sort -rh | head -20
+sudo journalctl --disk-usage
+
+# k3s data directory
+sudo du -sh /var/lib/rancher/k3s/ 2>/dev/null
+sudo du -sh /var/lib/rancher/k3s/agent/containerd/ 2>/dev/null
+
+# Rapidly growing dirs (compare two snapshots 60s apart)
+sudo du -sh /var/lib/rancher /var/log /tmp 2>/dev/null
+```
+
+Look for:
+- Any mount > 85% full (warning) or > 95% (critical)
+- Any mount with inode usage > 85%
+- Container image accumulation in containerd storage
+- Large or rapidly growing log files
+- Abandoned temp files
+
+---
+
+### Step 6 — Network and Connection State
+
+```bash
+# Connection state summary
+ss -s
+ss -tnp | awk '{print $1}' | sort | uniq -c | sort -rn
+
+# Unusual listeners
+ss -tlnp
+
+# CLOSE_WAIT accumulation (application socket leak)
+ss -tnp | grep CLOSE_WAIT | wc -l
+
+# TIME_WAIT count (normal but high counts may indicate connection thrash)
+ss -tnp | grep TIME_WAIT | wc -l
+```
+
+Look for:
+- CLOSE_WAIT count > 50 (application not closing sockets)
+- SYN_RECV accumulation (connection flood or backlog issue)
+- Unexpected listeners on unusual ports
+- Long-lived unexpected tunnels or port-forwards
+
+---
+
+### Step 7 — Kubernetes Node Health
+
+```bash
+# Node status and conditions
+kubectl get node $(hostname) -o wide 2>/dev/null || k3s kubectl get node $(hostname) -o wide
+
+# Node conditions in detail
+kubectl describe node $(hostname) 2>/dev/null | grep -A 10 'Conditions:'
+
+# Resource pressure
+kubectl top node $(hostname) 2>/dev/null
+
+# Recent node events
+kubectl get events --field-selector involvedObject.name=$(hostname) --sort-by='.lastTimestamp' 2>/dev/null | tail -20
+
+# Top pods by resource use
+kubectl top pods --all-namespaces --sort-by=memory 2>/dev/null | head -20
+
+# Restarting pods on this node
+kubectl get pods --all-namespaces --field-selector spec.nodeName=$(hostname) 2>/dev/null | awk '$5 > 5 {print}'
+```
+
+Look for:
+- Node Ready=False or Unknown
+- MemoryPressure, DiskPressure, PIDPressure, or NetworkUnavailable = True
+- Pods with high restart counts (> 5)
+- CrashLoopBackOff workloads
+- Evicted pods (indicates past resource pressure)
+
+---
+
+### Step 8 — k3s Runtime and Control Services
+
+```bash
+# k3s service status
+sudo systemctl status k3s 2>/dev/null || sudo systemctl status k3s-agent
+
+# k3s recent logs (last 100 lines)
+sudo journalctl -u k3s --since "1 hour ago" -n 100 2>/dev/null || \
+sudo journalctl -u k3s-agent --since "1 hour ago" -n 100
+
+# containerd status (k3s embedded)
+sudo systemctl status containerd 2>/dev/null
+
+# CNI / flannel if applicable
+sudo systemctl status flanneld 2>/dev/null
+sudo ip addr show flannel.1 2>/dev/null
+```
+
+Look for:
+- k3s service not running or in failed state
+- Repeated restart entries in k3s logs
+- PLEG errors, image GC failures, sandbox creation failures
+- cgroup-related errors
+- API server timeout messages (on worker nodes: etcd or API server unreachable)
+
+---
+
+## Interpretation
+
+| Signal | Normal | Warning | Critical |
+|--------|--------|---------|----------|
+| Load average | ≤ core count | 1–2× core count | > 2× sustained |
+| Memory available | > 20% | 10–20% | < 10% |
+| Disk usage | < 75% | 75–90% | > 90% |
+| Inode usage | < 75% | 75–90% | > 90% |
+| Zombie count | 0 | 1–5 | > 5 or climbing |
+| OOM kills (24h) | 0 | 1–2 | > 2 or recent |
+| Pod restarts | < 3 | 3–10 | > 10 or CrashLoop |
+| CLOSE_WAIT | < 10 | 10–50 | > 50 |
+| Node Ready | True | — | False / Unknown |
+
+Confidence in findings:
+- **High** — direct evidence (OOM kill log, node condition set, error in service log)
+- **Medium** — indirect evidence (high memory use without OOM, rising load with no clear cause)
+- **Low** — circumstantial (aging process without other indicators)
+
+---
+
+## Remediation
+
+### High memory pressure
+
+1. Identify top consumers: `ps aux --sort=-%mem | head -20`
+2. Check for OOM history: `dmesg | grep -i oom`
+3. If a workload is leaking: restart the specific pod (not the node)
+4. If slab is high: check for inode-heavy workloads or NFS mounts
+5. Do not drop caches unless explicitly justified — Linux reclaims page cache automatically
+
+### Disk pressure
+
+1. Find largest directories: `du -sh /var/lib/rancher/k3s/agent/containerd/io.containerd.snapshotter.v1.overlayfs/snapshots/* | sort -rh | head -20`
+2. Prune unused container images: `k3s crictl rmi --prune` (safe — only removes unused images)
+3. Clear old journal logs: `sudo journalctl --vacuum-size=500M`
+4. Identify log-bloating pods and fix their logging config
+
+### k3s service failing
+
+1. Check service status: `sudo systemctl status k3s`
+2. Check logs: `sudo journalctl -u k3s -n 200`
+3. Common causes: etcd data corruption (single-node), API server unreachable (worker), disk full, cert expiry
+4. Do not restart k3s without understanding the cause — a restart may mask the issue
+
+### High pod restart count
+
+1. Check logs: `kubectl logs <pod> --previous`
+2. Check events: `kubectl describe pod <pod>`
+3. Distinguish OOMKilled (memory limit) from CrashLoop (application error) from Liveness probe failure
+
+---
+
+## Notes
+
+- This protocol was adapted from the sys-medic agent's structured assessment areas and the sys-medic repo's companion protocol document.
+- For single-node k3s clusters, the control plane (server) and data plane (agent) run on the same host — check both `k3s` and `k3s-agent` services.
+- On hosts without `kubectl` in PATH, use `k3s kubectl` as a drop-in replacement.
+- Protocol version history is tracked via the `version` frontmatter field. Update on significant structural changes.

docs/CLI_CHEAT_SHEET.md

@@ -48,6 +48,39 @@ kaizen-agentic status                    # Show current project status
 kaizen-agentic validate                  # Validate agent installation
 ```
 
+### Project Metrics (ADR-004)
+```bash
+# Record outcome at session close
+kaizen-agentic metrics record tdd-workflow --success --time 120 --quality 0.9
+kaizen-agentic metrics record tdd-workflow --failure --time 45
+
+# Full JSON record from stdin
+echo '{"success": true, "quality_score": 1.0}' | kaizen-agentic metrics record tdd-workflow --json
+
+# Inspect metrics
+kaizen-agentic metrics show tdd-workflow
+kaizen-agentic metrics list
+kaizen-agentic metrics export tdd-workflow
+kaizen-agentic metrics optimize tdd-workflow   # analyze one agent (≥10 records)
+kaizen-agentic metrics optimize                # analyze all agents with metrics
+
+# Helix Forge correlation (fleet layer — agentic-resources)
+export HELIX_SESSION_UID="claude:<native-id>"
+kaizen-agentic metrics record tdd-workflow --success --time 120 --quality 0.9
+kaizen-agentic metrics correlate claude:<native-id>   # needs HELIX_STORE_DB
+
+# Publish optimizer evidence to artifact-store (optional)
+export ARTIFACTSTORE_API_URL=http://127.0.0.1:8000
+export ARTIFACTSTORE_API_TOKEN=<token>
+kaizen-agentic metrics publish
+
+# Scaffold memory + metrics together
+kaizen-agentic memory init tdd-workflow
+kaizen-agentic memory init tdd-workflow --no-metrics   # memory only
+```
+
+Session-close template: `docs/templates/session-close-protocol.md`
+
 ### Information
 ```bash
 # List templates

docs/FEEDBACK.md

@@ -0,0 +1,41 @@
+# Feedback
+
+How to share bugs, ideas, and adoption experience for kaizen-agentic.
+
+## Quick channels
+
+| Channel | Use for |
+|---------|---------|
+| **Gitea Issues** | Bugs, features, general feedback (templates below) |
+| **`kaizen-agentic feedback`** | Print links and template guidance from the CLI |
+| **Pull requests** | Code and agent-definition contributions (see CONTRIBUTING.md) |
+| **State Hub messages** | Cross-repo coordination between custodian agents (advanced) |
+
+## Gitea issue templates
+
+Choose a template when opening a new issue:
+
+- **Bug report** — reproducible defects
+- **Feature request** — enhancements with proposed scope
+- **General feedback** — experience and adoption notes
+
+Repository: [coulomb/kaizen-agentic](https://gitea.coulomb.social/coulomb/kaizen-agentic/issues)
+
+## CLI
+
+```bash
+kaizen-agentic feedback          # human-readable channel list
+kaizen-agentic feedback --json   # machine-readable for tooling
+```
+
+## What helps us most
+
+- Python version and `kaizen-agentic --version`
+- Minimal reproduction steps for bugs
+- Which agents you used and whether memory/metrics were enabled
+- For integration issues: whether artifact-store, Helix Forge, or activity-core is involved
+
+## Privacy
+
+Do not include secrets, tokens, or private project content in public issues. Redact
+`.kaizen/` memory contents unless you intentionally share sanitized examples.

docs/INTEGRATION_PATTERNS.md

@@ -1,401 +1,105 @@
-# Integration Patterns for Existing Projects
+# Integration Patterns
 
-This guide documents proven patterns for integrating Kaizen Agentic agents into existing projects that already have agent systems.
+How kaizen-agentic composes with ecosystem repos **by contract** — no merged
+codebases, no duplicated capabilities.
 
-## Overview
+Reference: [wiki/EcosystemIntegration.md](../wiki/EcosystemIntegration.md),
+[KAIZEN-WP-0004](../workplans/kaizen-agentic-WP-0004-ecosystem-integration.md).
 
-When introducing Kaizen agents to existing projects, you'll encounter various scenarios that require different integration approaches. This guide provides tested patterns and strategies.
+---
 
-## Integration Scenarios
+## Pattern 1 — Helix Forge correlation (agentic-resources)
 
-### Scenario 1: Clean Integration (No Existing Agents)
+**Problem:** Project metrics and fleet session metrics answer different questions.
 
-**When to use**: Project has no existing agent systems.
+**Contract:** Optional `helix_session_uid` on ADR-004 execution records.
+
+| kaizen-agentic | agentic-resources |
+|----------------|-------------------|
+| `metrics record` at session close | Helix capture → digest store |
+| `metrics correlate <uid>` read-only lookup | `Store.get_digest(session_uid)` |
+| `HELIX_SESSION_UID` env auto-merge | `Session.session_uid` |
+
+**Docs:** [integrations/helix-forge-correlation.md](integrations/helix-forge-correlation.md)
+
+**Boundary:** kaizen-agentic does not ingest session JSONL.
+
+---
+
+## Pattern 2 — activity-core triggers
+
+**Problem:** Recurring kaizen checks need scheduling without custom cron in this repo.
+
+**Contract:** ActivityDefinition markdown files declare triggers + actions that
+invoke kaizen-agentic CLI commands.
+
+| Definition | Trigger | CLI command |
+|------------|---------|-------------|
+| [weekly-metrics-optimize](integrations/activity-definitions/weekly-metrics-optimize.md) | Cron Mon 08:00 | `metrics optimize` |
+| [post-install-metrics-scaffold](integrations/activity-definitions/post-install-metrics-scaffold.md) | `kaizen.agent.installed` | `memory init` validation |
+| [low-success-rate-review](integrations/activity-definitions/low-success-rate-review.md) | `kaizen.metrics.recorded` | `metrics show` + `optimize` |
+
+**Activation:**
+
+1. Copy or symlink definitions from `docs/integrations/activity-definitions/` into
+   activity-core's `activity-definitions/` tree (or register as external ConfigMap).
+2. Run `make sync-activity-definitions` in activity-core.
+3. Enable definitions (`enabled: true`) after resolver wiring is verified.
+
+**Smoke test (manual):**
 
-**Pattern**: Direct installation
 ```bash
-kaizen-agentic init . --agents keepaTodofile,keepaChangelog,tdd-workflow
+# Against a repo with populated metrics
+cd /path/to/project-with-kaizen
+kaizen-agentic metrics list
+kaizen-agentic metrics optimize
+# Verify analysis.json written
+test -f .kaizen/metrics/optimizer/analysis.json && echo OK
 ```
 
-**Benefits**:
-- Straightforward setup
-- No conflicts to resolve
-- Full Kaizen agent functionality
+**Boundary:** kaizen-agentic does not run Temporal schedules.
 
-### Scenario 2: Claude Code Integration
+---
 
-**When to use**: Project already uses Claude Code with CLAUDE.md.
+## Pattern 3 — artifact-store evidence retention
+
+**Problem:** Optimizer outputs need durable, attributable retention beyond local disk.
+
+**Contract:** `metrics publish` registers `analysis.json` + `recommendations.jsonl`
+as an artifact package with `retention_class: raw-evidence`.
 
-**Pattern**: Respectful coexistence
 ```bash
-# 1. Detect existing setup
-kaizen-agentic detect
-
-# 2. Install compatible agents
-kaizen-agentic install keepaTodofile keepaChangelog
-
-# 3. Update CLAUDE.md with new agent references
+export ARTIFACTSTORE_API_URL=http://127.0.0.1:8000
+export ARTIFACTSTORE_API_TOKEN=<token>
+kaizen-agentic metrics optimize
+kaizen-agentic metrics publish --target .
 ```
 
-**Considerations**:
-- Preserve existing CLAUDE.md content
-- Add Kaizen agent references to existing documentation
-- Maintain Claude Code workflow compatibility
+**Manifest:** [integrations/optimizer-artifact-manifest.md](integrations/optimizer-artifact-manifest.md)
 
-### Scenario 3: Custom Agent Replacement
+**Boundary:** Publish is optional; local `.kaizen/metrics/optimizer/` remains canonical.
 
-**When to use**: Project has custom agents that overlap with Kaizen functionality.
+---
 
-**Pattern**: Gradual migration with backup
-```bash
-# 1. Analyze existing agents
-kaizen-agentic detect --detailed
+## Pattern 4 — Canon and knowledge (stretch)
 
-# 2. Create migration plan
-kaizen-agentic migrate --dry-run
+Design-only paths for info-tech-canon and kontextual-engine:
 
-# 3. Execute migration with backup
-kaizen-agentic migrate
-```
+- [integrations/canon-template-mapping.md](integrations/canon-template-mapping.md)
+- [integrations/briefs/tdd-workflow-canon-brief.md](integrations/briefs/tdd-workflow-canon-brief.md)
+- [integrations/kontextual-wiki-ingestion-spike.md](integrations/kontextual-wiki-ingestion-spike.md)
 
-**Steps**:
-1. **Backup** existing agents
-2. **Map** custom agents to Kaizen equivalents
-3. **Migrate** functionality to extensions
-4. **Test** new agent workflow
-5. **Archive** old agents after verification
+No runtime dependency in WP-0004.
 
-### Scenario 4: Hybrid Coexistence
+---
 
-**When to use**: Project has essential custom agents that cannot be replaced.
+## Environment variables
 
-**Pattern**: Namespace separation
-```bash
-# 1. Install Kaizen agents in parallel
-kaizen-agentic install keepaTodofile --target agents/kaizen/
-
-# 2. Keep custom agents in separate directory
-# agents/custom/todo_manager.py
-# agents/kaizen/agent-keepaTodofile.md
-
-# 3. Create integration extensions
-kaizen-agentic extensions create custom-integration keepaTodofile
-```
-
-**Directory Structure**:
-```
-project/
-├── agents/
-│   ├── custom/           # Existing custom agents
-│   │   ├── todo_manager.py
-│   │   └── code_reviewer.py
-│   └── kaizen/           # Kaizen agents
-│       ├── agent-keepaTodofile.md
-│       └── agent-code-refactoring.md
-├── .kaizen/
-│   └── extensions/       # Integration extensions
-└── CLAUDE.md             # Updated configuration
-```
-
-### Scenario 5: Extension-Based Integration
-
-**When to use**: Custom agents have unique functionality that should be preserved.
-
-**Pattern**: Extend Kaizen agents with custom functionality
-```bash
-# 1. Create project-specific extension
-kaizen-agentic extensions create project-todo keepaTodofile \
-  --description "TODO manager with custom workflow integration"
-
-# 2. Configure custom behavior
-# Edit .kaizen/extensions/project-todo/extension.yml
-
-# 3. Migrate custom logic to extension
-```
-
-**Extension Configuration Example**:
-```yaml
-name: project-todo
-base_agent: keepaTodofile
-extension_type: functional_extension
-description: "TODO manager with custom workflow integration"
-
-configuration:
-  custom_instructions: |
-    Follow our project-specific TODO format:
-    - Use JIRA ticket references
-    - Include priority levels (P0-P3)
-    - Auto-assign based on component
-
-custom_commands:
-  create-epic: "Create epic-level TODO items"
-  sync-jira: "Synchronize with JIRA tickets"
-  priority-report: "Generate priority-based reports"
-
-environment_overrides:
-  JIRA_URL: "https://company.atlassian.net"
-  TODO_FORMAT: "custom"
-```
-
-## Conflict Resolution Patterns
-
-### Name Conflicts
-
-**Problem**: Multiple agents with the same name.
-
-**Pattern**: Rename with suffix
-```bash
-# Automatic resolution
-todo_manager -> todo_manager_custom
-keepaTodofile -> keepaTodofile (Kaizen agent)
-```
-
-**Implementation**:
-- Add `_custom` suffix to project-specific agents
-- Update references in scripts and documentation
-- Create aliases for backward compatibility
-
-### Functional Overlaps
-
-**Problem**: Multiple agents perform similar functions.
-
-**Pattern**: Choose primary, extend secondary
-```bash
-# Primary: Kaizen agent (standardized)
-# Secondary: Custom agent -> extension
-
-# Example: Both have TODO management
-# Decision: Use keepaTodofile as primary
-#           Convert custom logic to extension
-```
-
-**Decision Matrix**:
-| Factor | Choose Kaizen | Choose Custom | Create Extension |
-|--------|---------------|---------------|------------------|
-| Standard functionality | ✅ | ❌ | ✅ |
-| Custom business logic | ❌ | ✅ | ✅ |
-| Maintenance burden | ✅ | ❌ | ⚠️ |
-| Team familiarity | ⚠️ | ✅ | ✅ |
-
-### Integration Order
-
-**Pattern**: Infrastructure first, features last
-1. **Infrastructure agents** (setupRepository, tooling-optimization)
-2. **Core functionality** (keepaTodofile, keepaChangelog)
-3. **Development process** (tdd-workflow, code-refactoring)
-4. **Specialized features** (testing-efficiency, datamodel-optimization)
-
-## Project Structure Respect Patterns
-
-### Existing Directory Structures
-
-**Pattern**: Adaptive installation
-```bash
-# Respect existing structure
-project/
-├── tools/agents/         # Existing agent directory
-├── scripts/             # Existing automation
-└── docs/               # Existing documentation
-
-# Kaizen adaptation
-kaizen-agentic install --target tools/agents/ keepaTodofile
-# Creates: tools/agents/agent-keepaTodofile.md
-```
-
-### Configuration File Integration
-
-**Pattern**: Merge, don't replace
-```bash
-# Before
-CLAUDE.md              # Existing Claude config
-project-config.yml     # Existing project config
-
-# After (merged)
-CLAUDE.md              # Updated with Kaizen agents
-project-config.yml     # Preserved
-.kaizen/extensions.yml # New Kaizen-specific config
-```
-
-### Build System Integration
-
-**Pattern**: Extend existing targets
-```makefile
-# Existing Makefile
-test:
-	pytest tests/
-
-# After Kaizen integration (extended)
-test: test-core test-agents
-	@echo "All tests completed"
-
-test-core:
-	pytest tests/
-
-test-agents:
-	kaizen-agentic validate
-
-# New Kaizen targets
-agents-status:
-	kaizen-agentic status
-
-agents-update:
-	kaizen-agentic update
-```
-
-## Safe Transition Strategies
-
-### Phased Rollout
-
-**Phase 1: Detection and Planning**
-```bash
-# Week 1: Analysis
-kaizen-agentic detect --detailed
-kaizen-agentic migrate --dry-run
-
-# Decision point: Continue or modify approach
-```
-
-**Phase 2: Infrastructure Agents**
-```bash
-# Week 2: Core infrastructure
-kaizen-agentic install setupRepository
-# Test and validate before proceeding
-```
-
-**Phase 3: Core Functionality**
-```bash
-# Week 3: Essential agents
-kaizen-agentic install keepaTodofile keepaChangelog
-# Create extensions for custom functionality
-```
-
-**Phase 4: Advanced Features**
-```bash
-# Week 4: Specialized agents
-kaizen-agentic install tdd-workflow code-refactoring
-# Full integration testing
-```
-
-### Rollback Strategy
-
-**Pattern**: Versioned backups with restore capability
-```bash
-# Before migration
-.kaizen-migration-backup-timestamp/
-├── agents/              # Original agents
-├── CLAUDE.md           # Original configuration
-└── restoration.md      # Rollback instructions
-
-# Rollback command (if needed)
-kaizen-agentic rollback --backup .kaizen-migration-backup-timestamp/
-```
-
-### Validation Gates
-
-**Pattern**: Automated validation at each phase
-```bash
-# After each phase
-kaizen-agentic validate
-make test
-make agents-status
-
-# Success criteria for proceeding:
-# ✅ All agents load without errors
-# ✅ All tests pass
-# ✅ No functionality regressions
-```
-
-## Best Practices
-
-### Communication
-
-1. **Team Notification**: Inform team before starting migration
-2. **Documentation**: Update project docs with new agent workflows
-3. **Training**: Provide team training on Kaizen agents
-4. **Gradual Adoption**: Allow team to adapt gradually
-
-### Technical
-
-1. **Backup Everything**: Create comprehensive backups
-2. **Test Thoroughly**: Validate each integration step
-3. **Monitor Impact**: Watch for performance or workflow impacts
-4. **Version Control**: Commit changes in logical phases
-
-### Maintenance
-
-1. **Regular Updates**: Keep Kaizen agents updated
-2. **Extension Maintenance**: Maintain custom extensions
-3. **Documentation Sync**: Keep docs synchronized with agent changes
-4. **Team Feedback**: Collect and act on team feedback
-
-## Troubleshooting Common Issues
-
-### Agent Conflicts
-
-**Issue**: Multiple agents trying to manage the same files.
-
-**Solution**:
-```bash
-# Identify conflicts
-kaizen-agentic detect --detailed
-
-# Resolve with namespace separation
-mkdir agents/legacy agents/kaizen
-mv agents/todo_manager.py agents/legacy/
-kaizen-agentic install --target agents/kaizen/ keepaTodofile
-```
-
-### Configuration Conflicts
-
-**Issue**: Conflicting configuration files.
-
-**Solution**:
-```bash
-# Merge configurations
-cp CLAUDE.md CLAUDE.md.backup
-kaizen-agentic install keepaTodofile
-# Manually merge CLAUDE.md.backup content
-```
-
-### Workflow Disruption
-
-**Issue**: New agents disrupt existing workflows.
-
-**Solution**:
-```bash
-# Create compatibility extensions
-kaizen-agentic extensions create workflow-compat keepaTodofile
-# Configure extension to match existing workflow
-```
-
-## Success Metrics
-
-### Technical Metrics
-- ✅ Zero agent loading errors
-- ✅ All tests passing
-- ✅ No performance regressions
-- ✅ Successful backup/restore capability
-
-### Team Metrics
-- ✅ Team adoption of new agents
-- ✅ Maintained productivity during transition
-- ✅ Positive feedback on new capabilities
-- ✅ Reduced maintenance overhead
-
-### Project Metrics
-- ✅ Improved code quality metrics
-- ✅ Better documentation coverage
-- ✅ Enhanced development workflow efficiency
-- ✅ Standardized agent ecosystem
-
-## Conclusion
-
-Successful integration of Kaizen agents into existing projects requires:
-
-1. **Careful analysis** of existing agent systems
-2. **Respectful approach** to existing project structure
-3. **Gradual migration** with proper backup strategies
-4. **Extension mechanisms** for preserving custom functionality
-5. **Team communication** and training throughout the process
-
-Follow these patterns and your integration will be smooth, reversible, and beneficial to your development workflow.
+| Variable | Used by | Purpose |
+|----------|---------|---------|
+| `HELIX_SESSION_UID` | `metrics record` | Fleet session correlation |
+| `HELIX_REPO`, `HELIX_FLAVOR` | `metrics record` | Session context |
+| `HELIX_TOKENS`, `HELIX_INFRA_OVERHEAD_SHARE` | `metrics record` | Fleet cost fields |
+| `HELIX_STORE_DB` | `metrics correlate` | Digest lookup database |
+| `ARTIFACTSTORE_API_URL` | `metrics publish` | Registry endpoint |
+| `ARTIFACTSTORE_API_TOKEN` | `metrics publish` | Write auth bearer token |

docs/TELEMETRY.md

@@ -0,0 +1,48 @@
+# Telemetry and Agent Effectiveness Tracking
+
+WP-0001 T04 design — aligned with ADR-004 and WP-0004 ecosystem integration.
+
+## Two layers (do not merge)
+
+| Layer | Question | Mechanism |
+|-------|----------|-----------|
+| **Project** | How is agent *X* performing in *this repo*? | `kaizen-agentic metrics record` → `.kaizen/metrics/` |
+| **Fleet** | How are coding sessions performing *across repos*? | agentic-resources Helix Forge |
+
+kaizen-agentic **does not** ship a parallel session transcript ingestion pipeline.
+
+## Project telemetry (implemented)
+
+Memory-enabled agents record per-session outcomes at close:
+
+```bash
+kaizen-agentic metrics record <agent> --success --time <s> --quality <0-1>
+kaizen-agentic metrics optimize [agent]
+kaizen-agentic memory brief <agent>    # includes Performance Summary
+```
+
+Optional fleet correlation via `HELIX_SESSION_UID` (see
+[integrations/helix-forge-correlation.md](integrations/helix-forge-correlation.md)).
+
+## Fleet telemetry (agentic-resources)
+
+Helix Forge owns session capture, digest storage, baselines, and weekly retro.
+kaizen-agentic consumes correlation fields only.
+
+## CLI install / usage analytics (future)
+
+Potential v1.1 additions (not yet implemented):
+
+- Opt-in anonymous counters on `install` / `memory init` (no PII, no project paths)
+- Aggregate effectiveness reports via `metrics list` across a monorepo checkout
+
+## tele-mcp evaluation (deferred)
+
+[tele-mcp](https://gitea.coulomb.social/coulomb/tele-mcp) is a candidate MCP adapter
+for IDE-level telemetry (WP-0001 note). Assess before depending on it. Project and
+fleet layers above satisfy INTENT's "measurable agents" requirement without tele-mcp.
+
+## Feedback loop
+
+User experience feedback uses [FEEDBACK.md](FEEDBACK.md) and Gitea issue templates —
+separate from execution metrics.

docs/adr/ADR-001-workplan-convention.md

@@ -0,0 +1,57 @@
+---
+id: ADR-001
+title: Workplan Convention
+status: accepted
+date: "2026-03-18"
+---
+
+# ADR-001 — Workplan Convention
+
+## Status
+
+Accepted
+
+## Context
+
+kaizen-agentic needs a way to track planned work that is version-controlled,
+visible to the state-hub, and authoritative when the two diverge.
+
+## Decision
+
+Work items originate as Markdown files in `workplans/` **before** being
+registered in the state-hub DB. The file is always authoritative; the DB is
+a read/query model derived from it.
+
+**File naming:** `workplans/kaizen-agentic-WP-NNNN-<slug>.md`
+**ID prefix:** `KAIZEN-WP`
+
+### Required YAML frontmatter
+
+```yaml
+---
+id: KAIZEN-WP-NNNN
+type: workplan
+title: "..."
+domain: custodian
+repo: kaizen-agentic
+status: active | completed | archived
+owner: kaizen-agentic
+topic_slug: custodian
+state_hub_workstream_id: <uuid>
+created: "YYYY-MM-DD"
+updated: "YYYY-MM-DD"
+---
+```
+
+### Task tracking
+
+Tasks use `- [ ]` / `- [x]` checkboxes with a `T##` code prefix. A
+`## State Hub Task IDs` table at the end of each workplan maps codes to
+DB UUIDs so status can be synced without a list_tasks lookup.
+
+## Consequences
+
+- File is the source of truth; DB drift is auto-fixable via
+  `check_repo_consistency(fix=True)`.
+- Tasks must be created in the file first, then registered in the hub.
+- C-12 warnings are expected when the DB host has not yet seen local changes.

docs/adr/ADR-002-project-memory-convention.md

@@ -0,0 +1,119 @@
+---
+id: ADR-002
+title: Project Memory Convention
+status: accepted
+date: "2026-03-18"
+---
+
+# ADR-002 — Project Memory Convention
+
+## Status
+
+Accepted
+
+## Context
+
+kaizen-agentic agents are stateless by default — each session starts from
+scratch with no knowledge of what has been tried, what worked, or what the
+project's recurring patterns are. This makes agents less useful over time
+and forces the operator to re-supply context that the agent itself
+accumulated.
+
+## Decision
+
+Each agent deployed into a project may maintain a **project-scoped memory
+file**. Memory files are written at session close and read at session start.
+
+### File location
+
+```
+<project-root>/.kaizen/agents/<agent-name>/memory.md
+```
+
+The `.kaizen/` directory is the kaizen-agentic ecosystem's project-level
+state directory, analogous to `.claude/` for Claude Code.
+
+### Memory file structure
+
+```markdown
+---
+agent: <agent-name>
+project: <project-root or slug>
+last_updated: <ISO date>
+session_count: <n>
+---
+
+## Project Context
+<!-- What this agent knows about the project it works in -->
+
+## Accumulated Findings
+<!-- Patterns, recurring issues, key decisions encountered -->
+
+## What Worked
+<!-- Approaches that produced good results in this project -->
+
+## Watch Points
+<!-- Recurring risks, traps, or areas requiring extra care -->
+
+## Open Threads
+<!-- Things noticed but not yet acted on -->
+
+## Session Log
+<!-- One-line entry per session: date · summary · outcome -->
+```
+
+### Session-start protocol (all memory-enabled agents)
+
+1. Check for `.kaizen/agents/<name>/memory.md` in the project root.
+2. If present, read it before beginning work.
+3. Acknowledge the memory in the opening brief.
+
+### Session-close protocol (all memory-enabled agents)
+
+1. Update `## Accumulated Findings`, `## What Worked`, `## Watch Points`
+   as needed.
+2. Append one line to `## Session Log`.
+3. Bump `last_updated` and `session_count`.
+
+### Agent opt-out
+
+An agent may declare `memory: disabled` in its YAML frontmatter to opt out.
+Default is enabled. Stateless utility agents (e.g. `keepaTodofile`) should
+opt out.
+
+### CLI interface
+
+```
+kaizen-agentic memory show <agent>   # Print agent memory for current project
+kaizen-agentic memory init <agent>   # Scaffold empty memory file
+kaizen-agentic memory brief <agent>  # Run coach, print orientation for agent
+kaizen-agentic memory clear <agent>  # Wipe memory (with confirmation prompt)
+```
+
+`memory init` creates the `.kaizen/agents/<name>/memory.md` file with the
+standard structure and populates the frontmatter.
+
+### Coaching meta-agent
+
+A dedicated `agent-coach.md` (category: `meta`) reads across all
+`.kaizen/agents/*/memory.md` files in a project and:
+
+- Synthesises a cross-agent brief (shared patterns, cross-domain risks)
+- Produces a new-agent orientation targeted at a specific agent about to
+  be deployed for the first time
+- Maintains its own memory covering meta-level fleet observations
+
+`kaizen-agentic memory brief <agent>` invokes the coach to produce this
+orientation.
+
+## Consequences
+
+- Agents accumulate project-specific knowledge and arrive in later sessions
+  informed rather than blank.
+- The `.kaizen/` directory should be added to `.gitignore` by default;
+  teams may choose to commit it for shared context.
+- Memory files are human-readable and can be manually edited or reviewed.
+- The coach agent provides a single synthesised view across all agent
+  memories — reducing the operator's burden of re-supplying context.
+- Agents with `memory: disabled` remain fully stateless and require no
+  `.kaizen/` setup.

docs/adr/ADR-003-protocols-artifact-convention.md

@@ -0,0 +1,116 @@
+---
+id: ADR-003
+title: Protocols Artifact Convention
+status: accepted
+date: "2026-03-18"
+---
+
+# ADR-003 — Protocols Artifact Convention
+
+## Status
+
+Accepted
+
+## Context
+
+Some agents perform structured, repeatable assessments or remediation procedures
+(e.g. sys-medic's k3s node health assessment). These procedures exist as narrative
+text embedded in agent prompts or companion documents, making them hard to discover,
+reference, version, or evolve independently of the agent prompt.
+
+Protocols are distinct from agent prompts:
+- Agent prompts shape AI behaviour
+- Protocols are procedural checklists for humans and agents to execute
+
+They need their own artifact type with a stable location and structure.
+
+## Decision
+
+### File location
+
+```
+agents/protocols/<agent-name>/<slug>.md
+```
+
+Protocols live inside the `agents/` directory alongside agent definitions,
+grouped by owning agent. The `agents/protocols/` subtree is a managed artifact
+collection — not executable code, not agent prompts.
+
+### File structure
+
+```markdown
+---
+agent: <agent-name>
+slug: <slug>
+title: <human-readable title>
+version: <semver>
+last_updated: <ISO date>
+---
+
+# <Title>
+
+## Purpose
+<!-- One paragraph: what this protocol checks or achieves -->
+
+## Scope
+<!-- What systems, components, or conditions this protocol applies to -->
+
+## Prerequisites
+<!-- What must be true before starting -->
+
+## Procedure
+
+### Step 1 — <name>
+<!-- Commands, checks, observations -->
+
+### Step 2 — <name>
+...
+
+## Interpretation
+<!-- How to read the results: what is normal, what is a warning, what requires action -->
+
+## Remediation
+<!-- Common issues and how to resolve them -->
+
+## Notes
+<!-- Version history, known limitations, related protocols -->
+```
+
+### Lifecycle
+
+- Protocols are **created** when a repeatable procedure is identified during agent work
+- Protocols are **refined** across sessions as the owning agent accumulates experience
+- Protocols are **referenced** by agent prompts using the convention:
+  *"If available, use the `<slug>` protocol at `agents/protocols/<agent-name>/<slug>.md`"*
+- Protocols are **human-readable** and can be executed without an AI agent present
+
+### Relationship to agent memory
+
+Agent memory captures *what was learned* in a project. Protocols capture *how to
+do a repeatable thing* independent of any specific project. A protocol may be
+updated based on findings across many projects, but it does not store
+project-specific state.
+
+### CLI interface
+
+```
+kaizen-agentic protocols list [agent]            # List protocols (optionally filtered by agent)
+kaizen-agentic protocols show <agent> <slug>     # Print a protocol
+```
+
+`kaizen-agentic memory init sys-medic` will scaffold the sys-medic protocol
+directory alongside the memory file when protocols exist for that agent.
+
+### README
+
+Each `agents/protocols/` directory contains a `README.md` explaining the
+convention and listing available protocols.
+
+## Consequences
+
+- Protocols are independently versioned and evolvable without touching agent prompts.
+- The `agents/protocols/` directory is part of the kaizen-agentic repo and
+  distributed alongside agent definitions.
+- Operators can view, adapt, or execute protocols without running the CLI.
+- The first protocol — sys-medic's k3s node health assessment — migrates from
+  its current location into `agents/protocols/sys-medic/k3s-node-health-assessment.md`.

docs/adr/ADR-004-project-metrics-convention.md

@@ -0,0 +1,190 @@
+---
+id: ADR-004
+title: Project Metrics Convention
+status: accepted
+date: "2026-06-16"
+---
+
+# ADR-004 — Project Metrics Convention
+
+## Status
+
+Accepted
+
+## Context
+
+`INTENT.md` requires agents to be measurable, versioned, and optimizable. The
+agency framework (ADR-002) provides **qualitative** project memory; the kaizen
+loop needs **quantitative** per-execution records.
+
+`wiki/AgentKaizenOptimizer.md` specifies `.kaizen/metrics/` storage.
+`OptimizationLoop` in `src/kaizen_agentic/optimization.py` exists but has no
+data source.
+
+Separately, `agentic-resources` (Helix Forge) captures **fleet-level** session
+metrics from coding agent transcripts. Project metrics and fleet metrics serve
+different scopes and must correlate without duplicating ingestion logic.
+
+## Decision
+
+Each agent deployed into a project may accumulate **project-scoped execution
+metrics**. Records are append-only JSONL with rolling summaries. The optimizer
+reads these files to produce evidence-based recommendations.
+
+### File locations
+
+Per-agent executions:
+
+```
+<project-root>/.kaizen/metrics/<agent-name>/
+  executions.jsonl    # append-only per-execution records
+  summary.json        # rolling aggregates (regenerated on write)
+```
+
+Optimizer outputs:
+
+```
+<project-root>/.kaizen/metrics/optimizer/
+  analysis.json           # last analysis run + input fingerprint
+  recommendations.jsonl   # append-only recommendation history
+```
+
+The `.kaizen/metrics/` tree lives alongside `.kaizen/agents/` under the same
+project-level state directory (ADR-002).
+
+### Execution record schema (minimum viable)
+
+```json
+{
+  "timestamp": "2026-06-16T12:00:00Z",
+  "agent": "tdd-workflow",
+  "session_id": "optional-uuid-or-hash",
+  "execution_time_s": 0.0,
+  "success": true,
+  "quality_score": 0.0,
+  "primary_metric": {
+    "name": "test_pass_rate",
+    "value": 1.0,
+    "target": 1.0
+  },
+  "metadata": {}
+}
+```
+
+Required fields: `timestamp`, `agent`, `success`.
+Recommended fields: `execution_time_s`, `quality_score`, `primary_metric`.
+
+### Summary schema
+
+`summary.json` is derived — never hand-edited. Regenerated on each append:
+
+```json
+{
+  "agent": "tdd-workflow",
+  "execution_count": 12,
+  "success_rate": 0.917,
+  "avg_quality_score": 0.82,
+  "avg_execution_time_s": 45.3,
+  "last_execution": "2026-06-16T12:00:00Z",
+  "trend": {
+    "success_rate": "stable",
+    "quality_score": "up"
+  }
+}
+```
+
+### Retention
+
+Default retention: **180 days** (per `wiki/AgentKaizenOptimizer.md`).
+Pruning removes aged lines from `executions.jsonl` and regenerates `summary.json`.
+Project-level override via `.kaizen/metrics/config.json` is reserved for a
+future iteration.
+
+### Session-close protocol
+
+Memory-enabled agents with declared metrics should append one execution record
+at session close:
+
+```bash
+kaizen-agentic metrics record <agent> --success --time <seconds> --quality <0-1>
+```
+
+Or pipe a full JSON record via `--json` / stdin.
+
+### CLI interface
+
+```
+kaizen-agentic metrics record <agent>   # Append execution record
+kaizen-agentic metrics show <agent>     # Summary + recent executions
+kaizen-agentic metrics list             # Agents with metrics in project
+kaizen-agentic metrics export <agent>   # Dump executions.jsonl
+kaizen-agentic metrics optimize [agent] # Run OptimizationLoop (WP-0003 Part 3)
+```
+
+`kaizen-agentic memory init <agent>` scaffolds metrics directories by default
+(`--no-metrics` to opt out).
+
+### Helix Forge correlation
+
+Kaizen-agentic **project metrics** and agentic-resources **fleet metrics**
+operate at different layers:
+
+| Layer | Scope | Owner | Typical storage |
+|-------|-------|-------|-----------------|
+| Project | Per-agent persona in one repo | kaizen-agentic | `.kaizen/metrics/` |
+| Fleet | Cross-repo coding sessions | agentic-resources | Helix Forge digest store + `measure/baselines.jsonl` |
+
+**Correlation fields** — optional on project execution records, populated when
+the session is also captured by Helix Forge:
+
+```json
+{
+  "helix_session_uid": "claude:<native-session-uuid>",
+  "repo": "kaizen-agentic",
+  "flavor": "claude",
+  "tokens": 12500,
+  "infra_overhead_share": 0.12
+}
+```
+
+Mapping from Helix Forge `session_metrics()` (agentic-resources):
+
+| Helix field | ADR-004 field |
+|-------------|---------------|
+| `digest.outcome == "success"` | `success` |
+| `digest.cost.wall_clock_s` | `execution_time_s` |
+| `tokens` (input + output) | `tokens` in metadata / top-level |
+| `infra_overhead_share` | `metadata.infra_overhead_share` |
+| `Session.session_uid` | `helix_session_uid` |
+| `Session.repo` | `repo` |
+| `Session.flavor` | `flavor` |
+
+Kaizen-agentic does **not** ingest Claude/Codex/Grok JSONL transcripts.
+Correlation is **link-by-reference**: project metrics may cite a Helix session
+UID; fleet analytics remain owned by agentic-resources.
+
+WP-0004 defines the integration contract and optional sync tooling.
+
+### Coach and memory integration
+
+`kaizen-agentic memory brief <agent>` includes a `## Performance Summary`
+section when `summary.json` exists (WP-0003 Part 4). Qualitative memory
+(ADR-002) and quantitative metrics (this ADR) are complementary views of the
+same agent's project history.
+
+## Consequences
+
+- Agents can be measured per project without a central telemetry platform.
+- `OptimizationLoop` has a defined data source for recommendations.
+- Fleet session analytics stay in agentic-resources; no duplicate ingestion.
+- `.kaizen/metrics/` should default to `.gitignore` (same policy as memory).
+- WP-0003 implements `MetricsStore` and CLI against this convention.
+- WP-0004 wires ecosystem services (activity-core, artifact-store, Helix Forge).
+
+## Related Documents
+
+- [ADR-002: Project Memory Convention](ADR-002-project-memory-convention.md)
+- [wiki/EcosystemIntegration.md](../../wiki/EcosystemIntegration.md)
+- [agentic-resources session schema](https://github.com/coulomb/agentic-resources) — `session_memory/core/schema.py`
+- [KAIZEN-WP-0003](../../workplans/kaizen-agentic-WP-0003-measurement-loop.md)
+- [KAIZEN-WP-0004](../../workplans/kaizen-agentic-WP-0004-ecosystem-integration.md)

docs/agency-framework.md

@@ -0,0 +1,311 @@
+# Agency Framework
+
+kaizen-agentic is not just a library of agent instruction sets — it is an **agency**: a system where agents are deployed into projects with their own persistent memory, learn from experience, and are guided by a coaching meta-agent that distils patterns across the entire fleet.
+
+## Overview
+
+When you deploy a kaizen-agentic agent into a project, it can accumulate **project-scoped memory** — a structured file written at session close and read at session start. A **Coach** meta-agent reads across all agent memories and produces orientation briefs for newly deployed agents: what has been tried, what worked, what to watch out for.
+
+Agents arrive in a project informed, not blank.
+
+---
+
+## Project Memory
+
+### Location Convention
+
+```
+<project-root>/.kaizen/agents/<agent-name>/memory.md
+```
+
+The `.kaizen/` directory is analogous to `.claude/` — a project-level configuration and state directory owned by the kaizen-agentic ecosystem.
+
+### Memory File Structure
+
+```markdown
+---
+agent: <name>
+project: <project-root or slug>
+last_updated: <ISO date>
+session_count: <n>
+---
+
+## Project Context
+<!-- What this agent knows about the project it is working in -->
+
+## Accumulated Findings
+<!-- Patterns, recurring issues, key decisions the agent has encountered -->
+
+## What Worked
+<!-- Approaches that produced good results in this project -->
+
+## Watch Points
+<!-- Recurring risks, traps, or areas requiring extra care -->
+
+## Open Threads
+<!-- Things noticed but not yet acted on -->
+
+## Session Log
+<!-- One-line entry per session: date · summary · outcome -->
+```
+
+### Session Protocols
+
+**Session-start (all agents with `memory: enabled`):**
+
+1. Check for `.kaizen/agents/<name>/memory.md` in the project root.
+2. If present, read it before beginning work.
+3. Acknowledge the memory in the opening brief.
+
+**Session-close (all agents with `memory: enabled`):**
+
+1. Update `## Accumulated Findings`, `## What Worked`, `## Watch Points` as appropriate.
+2. Append one line to `## Session Log`: `YYYY-MM-DD · <summary> · <outcome>`.
+3. Bump `last_updated` and `session_count`.
+
+---
+
+## Agent YAML Frontmatter
+
+Each agent definition (`agents/agent-<name>.md`) includes a YAML frontmatter block:
+
+```yaml
+---
+name: <name>
+description: <one-line description>
+category: <category>
+memory: enabled   # or: disabled
+---
+```
+
+The `memory` field defaults to `enabled`. Set `memory: disabled` for agents that are stateless by design (e.g. `wisdom-encouragement`).
+
+---
+
+## The Coach Meta-Agent
+
+`agents/agent-coach.md` is a **meta-agent** — it performs no domain work (coding, testing, infrastructure). Its sole purpose is synthesis and advice.
+
+### What the Coach Does
+
+- **Cross-agent synthesis**: reads all `.kaizen/agents/*/memory.md` files, identifies shared patterns, cross-domain risks, and contradictions
+- **New-agent orientation**: when briefing a specific agent, filters all existing memories for what is relevant and produces a targeted brief
+- **Fleet health overview**: summarises which agents are active, stale, or missing; flags high-session-count agents with open threads
+
+### Invoking the Coach
+
+**Via CLI (assembles raw memory context):**
+
+```bash
+kaizen-agentic memory brief <agent-name>
+```
+
+This prints a structured orientation brief. Pass the output to a Claude session with `agents/agent-coach.md` loaded for full LLM synthesis.
+
+**Directly in a Claude session:**
+
+```
+Coach, brief the sys-medic agent on this project.
+Coach, what patterns have you observed across all agents?
+```
+
+The Coach maintains its own memory at `.kaizen/agents/coach/memory.md` covering fleet-level observations over time.
+
+---
+
+## CLI Reference
+
+The `memory` command group manages project-scoped agent memory:
+
+```
+kaizen-agentic memory show <agent>      # Print agent memory for the current project
+kaizen-agentic memory init <agent>      # Scaffold an empty memory file
+kaizen-agentic memory brief <agent>     # Assemble orientation context for the coach
+kaizen-agentic memory clear <agent>     # Wipe memory (with confirmation prompt)
+```
+
+### Options
+
+`memory brief` accepts:
+- `--target / -t` — project root (default: current directory)
+- `--raw` — dump raw memory file contents without the structured header
+
+### Example Workflow
+
+```bash
+# First deployment of sys-medic into a project
+kaizen-agentic memory init sys-medic
+
+# After a few sessions, brief an incoming tdd-workflow agent
+kaizen-agentic memory brief tdd-workflow
+# → paste output into Claude with agent-coach.md loaded
+
+# Review accumulated memory for a specific agent
+kaizen-agentic memory show project-management
+```
+
+---
+
+## Protocol Runbooks
+
+Agents can reference **protocol runbooks** — structured, human-readable procedural checklists for structured assessments or remediation work. Protocols are distinct from agent prompts:
+
+- **Agent prompts** (`agents/agent-*.md`) shape AI behaviour
+- **Protocols** (`agents/protocols/<agent>/<slug>.md`) are procedural documents for humans and agents to execute
+
+### Location Convention
+
+```
+agents/protocols/
+  <agent-name>/
+    <slug>.md    ← one file per protocol
+```
+
+### Protocol Frontmatter
+
+Each protocol file has a YAML frontmatter block:
+
+```yaml
+---
+agent: <agent-name>
+slug: <slug>
+title: <human-readable title>
+version: 1.0.0
+last_updated: "<ISO date>"
+---
+```
+
+### Referencing Protocols from Agents
+
+Agents with `memory: enabled` check for relevant protocols at session start and reference them in their session-start protocol block. For example, sys-medic's session-start protocol instructs:
+
+> *"If a structured assessment is requested, check for `agents/protocols/sys-medic/k3s-node-health-assessment.md` and use it as your procedure."*
+
+### CLI Reference
+
+```bash
+kaizen-agentic protocols list                        # List all protocols
+kaizen-agentic protocols list sys-medic              # Filter by agent
+kaizen-agentic protocols show sys-medic k3s-node-health-assessment
+```
+
+### sys-medic Memory and Protocols Integration
+
+sys-medic extends the base memory template with three additional sections for operational continuity across sessions:
+
+```markdown
+## Node Profiles
+<!-- Per-node operational baseline established over sessions -->
+<!-- hostname | typical load | known quirks | last assessment date -->
+
+## Recurring Findings
+<!-- Issues seen more than once: pattern · first seen · frequency -->
+
+## Cleared Issues
+<!-- Issues that were resolved: what was done · when · outcome -->
+```
+
+These sections are maintained automatically by the sys-medic session-close protocol.
+
+The **k3s Node Health Assessment** (`agents/protocols/sys-medic/k3s-node-health-assessment.md`) is the first protocol runbook — a step-by-step procedure covering OS baseline, process hygiene, memory, CPU, disk, network, Kubernetes node state, and k3s runtime health.
+
+### Available Protocols
+
+| Agent | Protocol | Description |
+|-------|----------|-------------|
+| sys-medic | [k3s-node-health-assessment](../agents/protocols/sys-medic/k3s-node-health-assessment.md) | Structured k3s node health check |
+
+See [ADR-003: Protocols Artifact Convention](adr/ADR-003-protocols-artifact-convention.md) for the full specification.
+
+---
+
+## Agents with Memory Enabled
+
+All agents that do session-bound project work have `memory: enabled` in their frontmatter and include session-start/session-close protocol blocks:
+
+| Agent | Category | Notes |
+|-------|----------|-------|
+| project-management | process | Reference implementation of the session protocol pattern |
+| tdd-workflow | testing | |
+| requirements-engineering | process | |
+| scope-analyst | process | |
+| sys-medic | infrastructure | Extended memory template (node profiles, recurring findings) |
+| coach | meta | Fleet-level memory |
+
+---
+
+## Project Metrics
+
+Project-scoped **quantitative** metrics complement qualitative memory (ADR-002).
+Per-execution records live under `.kaizen/metrics/<agent>/` and feed the
+kaizen optimizer loop.
+
+### Location
+
+```
+<project-root>/.kaizen/metrics/<agent-name>/
+  executions.jsonl
+  summary.json
+
+<project-root>/.kaizen/metrics/optimizer/
+  analysis.json
+  recommendations.jsonl
+```
+
+### CLI (WP-0003)
+
+```
+kaizen-agentic metrics record <agent>   # Append execution record at session close
+kaizen-agentic metrics show <agent>     # Summary + recent executions
+kaizen-agentic metrics list             # Agents with metrics in project
+kaizen-agentic metrics export <agent>   # Dump executions.jsonl
+kaizen-agentic metrics optimize [agent] # Run optimizer on project metrics (≥10 records)
+kaizen-agentic metrics correlate <uid>  # Helix Forge digest lookup (read-only)
+kaizen-agentic metrics publish          # Register optimizer output in artifact-store
+```
+
+`memory brief` includes a `## Performance Summary` when metrics exist (success
+rate, avg quality, execution time, trend arrows).
+
+`memory init` scaffolds `.kaizen/metrics/<agent>/` by default (`--no-metrics` to
+skip). Record outcomes at session close per
+[session-close protocol template](templates/session-close-protocol.md).
+
+### Fleet correlation
+
+Project metrics correlate with **Helix Forge** fleet session metrics in
+`agentic-resources` via optional `helix_session_uid` (ADR-004).
+
+- `HELIX_SESSION_UID` (and related env vars) auto-merge on `metrics record`
+- `metrics correlate <uid>` looks up fleet digest when `HELIX_STORE_DB` is set
+
+See [integrations/helix-forge-correlation.md](integrations/helix-forge-correlation.md)
+and [wiki/EcosystemIntegration.md](../wiki/EcosystemIntegration.md).
+
+### Evidence retention
+
+After `metrics optimize`, optionally publish optimizer outputs to **artifact-store**:
+
+```bash
+export ARTIFACTSTORE_API_URL=http://127.0.0.1:8000
+export ARTIFACTSTORE_API_TOKEN=<write-token>
+kaizen-agentic metrics publish --target .
+```
+
+Package uses `retention_class: raw-evidence` (180d). Local
+`.kaizen/metrics/optimizer/` remains authoritative when publish is skipped.
+
+Manifest: [integrations/optimizer-artifact-manifest.md](integrations/optimizer-artifact-manifest.md).
+
+---
+
+## Related Documents
+
+- [ADR-001: Workplan Convention](adr/ADR-001-workplan-convention.md)
+- [ADR-002: Project Memory Convention](adr/ADR-002-project-memory-convention.md)
+- [ADR-003: Protocols Artifact Convention](adr/ADR-003-protocols-artifact-convention.md)
+- [ADR-004: Project Metrics Convention](adr/ADR-004-project-metrics-convention.md)
+- [wiki/EcosystemIntegration.md](../wiki/EcosystemIntegration.md) — two-layer measurement model
+- [WP-0002: Agency Framework](../workplans/kaizen-agentic-WP-0002-agency-framework.md)
+- [WP-0003: Measurement Loop](../workplans/kaizen-agentic-WP-0003-measurement-loop.md)
+- [WP-0004: Ecosystem Integration](../workplans/kaizen-agentic-WP-0004-ecosystem-integration.md)

docs/integrations/activity-definitions/low-success-rate-review.md

@@ -0,0 +1,43 @@
+---
+id: kaizen-low-success-rate-review
+name: Low Agent Success Rate Review
+enabled: false
+owner: kaizen-agentic
+governance: custodian
+status: proposed
+trigger:
+  type: event
+  event_type: kaizen.metrics.recorded
+context_sources:
+  - type: event-payload
+    bind_to: context.metrics
+---
+
+# Low Agent Success Rate Review
+
+When a project agent's rolling success rate drops below 0.8, create a review
+task in issue-core for human or optimizer-agent follow-up.
+
+```rule
+id: flag-low-success-rate
+condition: 'context.metrics.summary.success_rate < 0.8 && context.metrics.summary.execution_count >= 5'
+action:
+  task_template: "Review {{context.metrics.agent}} success rate ({{context.metrics.summary.success_rate}})"
+  description: |
+    Agent {{context.metrics.agent}} in {{context.metrics.project}} has success_rate
+    below 0.8 over {{context.metrics.summary.execution_count}} executions.
+    Run: kaizen-agentic metrics show {{context.metrics.agent}}
+    Then: kaizen-agentic metrics optimize {{context.metrics.agent}}
+  target_repo: "{{context.metrics.project}}"
+  priority: high
+  labels: ["kaizen", "metrics", "review", "automated"]
+```
+
+**Threshold:** 0.8 success rate, minimum 5 executions (avoids noise on early pilots).
+
+**CLI mapping:** Event emitter is future work; manual check today:
+
+```bash
+kaizen-agentic metrics show <agent>   # inspect summary.success_rate
+kaizen-agentic metrics optimize <agent>
+```

docs/integrations/activity-definitions/post-install-metrics-scaffold.md

@@ -0,0 +1,41 @@
+---
+id: kaizen-post-install-metrics-scaffold
+name: Post-Install Metrics Scaffold Validation
+enabled: false
+owner: kaizen-agentic
+governance: custodian
+status: proposed
+trigger:
+  type: event
+  event_type: kaizen.agent.installed
+context_sources:
+  - type: event-payload
+    bind_to: context.install
+---
+
+# Post-Install Metrics Scaffold Validation
+
+Fires when an agent is installed into a project. Verifies that memory and metrics
+scaffolds exist for the installed agent.
+
+```rule
+id: validate-metrics-scaffold
+condition: 'context.install.agent != ""'
+action:
+  task_template: "Validate kaizen scaffold for {{context.install.agent}}"
+  description: |
+    In {{context.install.project_root}} verify:
+    - .kaizen/agents/{{context.install.agent}}/memory.md exists OR run:
+      kaizen-agentic memory init {{context.install.agent}}
+    - .kaizen/metrics/{{context.install.agent}}/ exists OR re-run init without --no-metrics
+  target_repo: "{{context.install.repo}}"
+  priority: low
+  labels: ["kaizen", "metrics", "scaffold", "automated"]
+```
+
+**CLI mapping:**
+
+```bash
+kaizen-agentic memory init <agent>    # scaffolds memory + metrics by default
+kaizen-agentic metrics list           # confirms metrics directory after first record
+```

docs/integrations/activity-definitions/weekly-metrics-optimize.md

@@ -0,0 +1,44 @@
+---
+id: kaizen-weekly-metrics-optimize
+name: Weekly Kaizen Metrics Optimization
+enabled: false
+owner: kaizen-agentic
+governance: custodian
+status: proposed
+trigger:
+  type: cron
+  cron_expression: "0 8 * * 1"
+  timezone: Europe/Berlin
+  misfire_policy: skip
+context_sources:
+  - type: shell
+    query: discover_kaizen_projects
+    params:
+      marker: .kaizen/metrics
+    bind_to: context.projects
+---
+
+# Weekly Kaizen Metrics Optimization
+
+Runs every Monday 08:00 Berlin time on repos that contain `.kaizen/metrics/`.
+Invokes the kaizen-agentic optimizer CLI per project.
+
+```rule
+id: run-weekly-optimizer
+for_each: context.projects
+bind_as: p
+condition: 'p.has_metrics == true'
+action:
+  task_template: "Run kaizen metrics optimize on {{p.repo}}"
+  description: |
+    cd {{p.root}} && kaizen-agentic metrics optimize
+    Optional: kaizen-agentic metrics publish (when artifact-store configured)
+  target_repo: "{{p.repo}}"
+  priority: medium
+  labels: ["kaizen", "metrics", "optimizer", "automated"]
+```
+
+**Activation:** sync this definition into activity-core via `make sync-activity-definitions`
+after enabling the shell resolver for `discover_kaizen_projects`.
+
+**CLI mapping:** `kaizen-agentic metrics optimize` (no agent filter = all agents with metrics).

docs/integrations/briefs/tdd-workflow-canon-brief.md

@@ -0,0 +1,44 @@
+# tdd-workflow — InfoTechCanon-style Brief
+
+Compact agent brief derived from `agents/agent-tdd-workflow.md` (metrics pilot).
+Reference for fleet-wide brief rollout.
+
+```yaml
+profile:
+  id: kaizen/tdd-workflow
+  version: "1.0"
+  domain: development-process
+  intent:
+    summary: Guide TDD8 ISSUE-TEST-RED-GREEN-REFACTOR-DOCUMENT-REFINE-PUBLISH cycles
+    outcomes:
+      - Acceptance criteria covered by tests before PUBLISH
+      - Sidequests tracked without blocking parent issues
+      - Workspace integrated cleanly via make tdd-finish
+  metrics:
+    primary:
+      name: test_pass_rate
+      target: 1.0
+      measurement: passing_tests / total_tests at PUBLISH
+    secondary:
+      - name: cycle_time_s
+        measurement: session duration (execution_time_s)
+    collection:
+      storage: .kaizen/metrics/tdd-workflow/
+      frequency: per_execution
+  idempotency:
+    signals:
+      - current_issue.json workspace state
+      - idempotency_key on metrics record
+  session_protocol:
+    start: read .kaizen/agents/tdd-workflow/memory.md
+    close:
+      - update memory.md sections
+      - kaizen-agentic metrics record tdd-workflow
+  ecosystem:
+    fleet_correlation: helix_session_uid (ADR-004)
+    optimizer: kaizen-agentic metrics optimize
+    evidence: kaizen-agentic metrics publish (optional)
+```
+
+Full specification: [agents/agent-tdd-workflow.md](../../../agents/agent-tdd-workflow.md).
+Pilot documentation: [wiki/AboutKaizenAgents.md](../../../wiki/AboutKaizenAgents.md).

docs/integrations/canon-template-mapping.md

@@ -0,0 +1,32 @@
+# KaizenAgentTemplate → InfoTechCanon Profile Mapping
+
+Design note (WP-0004 Part 4). No runtime dependency on info-tech-canon.
+
+## Section mapping
+
+| `wiki/KaizenAgentTemplate.md` | InfoTechCanon profile outline |
+|------------------------------|------------------------------|
+| `specification.outcomes` | `profile.intent.outcomes[]` |
+| `specification.constraints` | `profile.constraints.hard[]` / `soft[]` |
+| `idempotency.detection` | `profile.idempotency.signals[]` |
+| `idempotency.rollback` | `profile.safety.rollback` |
+| `metrics.primary` | `profile.metrics.primary` |
+| `metrics.secondary[]` | `profile.metrics.secondary[]` |
+| `metrics.collection` | `profile.observability.collection` |
+| `testing.unit_tests[]` | `profile.validation.unit[]` |
+| `testing.integration_tests[]` | `profile.validation.integration[]` |
+| `evolution.history` | `profile.evolution.changelog` |
+| `evolution.optimization_hooks` | `profile.evolution.feedback_sources[]` |
+
+## Validation hooks (future)
+
+Extend `kaizen-agentic validate` to check:
+
+1. Frontmatter contains `metrics.primary.name` when `memory: enabled`
+2. Session-close block references `metrics record`
+3. Required template sections present in agent body (warn, not fail)
+
+## Reference pilot
+
+`tdd-workflow` brief in [briefs/tdd-workflow-canon-brief.md](briefs/tdd-workflow-canon-brief.md)
+demonstrates a compact canon-style export derived from the full agent spec.

docs/integrations/helix-forge-correlation.md

@@ -0,0 +1,103 @@
+# Helix Forge Correlation Contract
+
+Cross-repo contract between **kaizen-agentic** (project metrics, ADR-004) and
+**agentic-resources** (Helix Forge fleet session metrics).
+
+## Purpose
+
+Link a project-scoped agent execution record to the fleet session that produced
+it, without duplicating session JSONL ingestion in kaizen-agentic.
+
+## Layers
+
+| Layer | Owner | Storage |
+|-------|-------|---------|
+| Project | kaizen-agentic | `.kaizen/metrics/<agent>/executions.jsonl` |
+| Fleet | agentic-resources | Helix Forge digest store (`digests` table) |
+
+## Correlation fields (ADR-004)
+
+Optional on each project execution record:
+
+```json
+{
+  "helix_session_uid": "claude:17092961-…",
+  "repo": "kaizen-agentic",
+  "flavor": "claude",
+  "tokens": 12500,
+  "infra_overhead_share": 0.12
+}
+```
+
+### Field mapping
+
+| Helix Forge (`session_memory`) | ADR-004 project record |
+|-------------------------------|------------------------|
+| `Session.session_uid` | `helix_session_uid` |
+| `Session.repo` | `repo` |
+| `Session.flavor` | `flavor` |
+| `digest.cost.input_tokens + output_tokens` | `tokens` |
+| MCP tool share of `tool_histogram` | `infra_overhead_share` |
+| `digest.outcome == "success"` | informs `success` at record time |
+| `digest.cost.wall_clock_s` | complements `execution_time_s` |
+
+## Population at session close
+
+### Automatic (environment)
+
+When Helix Forge capture is active in the same shell session:
+
+```bash
+export HELIX_SESSION_UID="claude:17092961-…"
+export HELIX_REPO="kaizen-agentic"
+export HELIX_FLAVOR="claude"
+export HELIX_TOKENS="12500"
+export HELIX_INFRA_OVERHEAD_SHARE="0.12"
+
+kaizen-agentic metrics record tdd-workflow --success --time 4200 --quality 0.9
+```
+
+`metrics record` merges env vars into the execution record before append.
+
+### Explicit (JSON)
+
+```bash
+echo '{
+  "success": true,
+  "execution_time_s": 4200,
+  "quality_score": 0.9,
+  "helix_session_uid": "claude:17092961-…",
+  "repo": "kaizen-agentic",
+  "flavor": "claude",
+  "tokens": 12500,
+  "infra_overhead_share": 0.12
+}' | kaizen-agentic metrics record tdd-workflow --json
+```
+
+## Fleet lookup (read-only)
+
+```bash
+export HELIX_STORE_DB=~/.helix-forge/store.db   # agentic-resources session store
+kaizen-agentic metrics correlate claude:17092961-…
+```
+
+When `HELIX_STORE_DB` is unset, `metrics correlate` returns a **stub** response
+documenting expected fields — no ingestion code runs in kaizen-agentic.
+
+## Bidirectional references
+
+| Document | Repo |
+|----------|------|
+| [ADR-004](../adr/ADR-004-project-metrics-convention.md) | kaizen-agentic |
+| [wiki/EcosystemIntegration.md](../../wiki/EcosystemIntegration.md) | kaizen-agentic |
+| [DESIGN-session-memory.md](https://github.com/coulomb/agentic-resources/blob/main/docs/DESIGN-session-memory.md) | agentic-resources |
+| `session_memory/core/store.py` — `get_digest()` | agentic-resources |
+
+agentic-resources should link back to this document from its session-memory design
+notes when documenting downstream consumers of `session_uid`.
+
+## Non-goals
+
+- No Claude/Codex/Grok JSONL ingestion in kaizen-agentic
+- No write path to Helix Forge from kaizen-agentic CLI
+- No merge of fleet baselines into project `summary.json` (Coach may cite both)

docs/integrations/kontextual-wiki-ingestion-spike.md

@@ -0,0 +1,41 @@
+# kontextual-engine Wiki Ingestion Spike
+
+Design note (WP-0004 Part 4). No runtime dependency.
+
+## Proposed manifest
+
+```yaml
+ingestion:
+  source_repo: kaizen-agentic
+  asset_class: strategic-knowledge
+  paths:
+    - wiki/**/*.md
+    - INTENT.md
+    - docs/adr/ADR-*.md
+  exclude:
+    - wiki/**/xxx
+  metadata:
+    domain: custodian
+    topic_id: cee7bedf-2b48-46ef-8601-006474f2ad7a
+    producer: kaizen-agentic
+  refresh:
+    trigger: git-push-main
+    retention_class: operational-knowledge
+```
+
+## Rationale
+
+- `wiki/` holds product narrative and integration contracts not suited for agent prompts alone
+- ADRs are normative; kontextual-engine can index them for cross-repo retrieval
+- Agent definitions (`agents/`) remain separate — executable personas vs strategic docs
+
+## Open questions
+
+1. Chunking strategy for `KaizenAgentTemplate.md` (section-aware vs whole-file)
+2. Whether Coach synthesis outputs should be ingested as derived assets
+3. Correlation with info-tech-canon profiles when both exist for one agent
+
+## Next step
+
+Dedicated workplan after WP-0004 baseline; evaluate kontextual-engine ingestion API
+stability before hard dependency.

docs/integrations/optimizer-artifact-manifest.md

@@ -0,0 +1,60 @@
+# Optimizer Evidence Artifact Manifest
+
+Package schema for `kaizen-agentic metrics publish` → **artifact-store**.
+
+## Package identity
+
+| Field | Value |
+|-------|-------|
+| `producer` | `kaizen-agentic` |
+| `retention_class` | `raw-evidence` (180d default, ADR-004 aligned) |
+| `name` | `kaizen-optimizer-<project-slug>` |
+| `subject` | project directory name (override with `--subject`) |
+
+## Files
+
+| Relative path | Source | Media type |
+|---------------|--------|------------|
+| `optimizer/analysis.json` | `.kaizen/metrics/optimizer/analysis.json` | `application/json` |
+| `optimizer/recommendations.jsonl` | `.kaizen/metrics/optimizer/recommendations.jsonl` | `application/x-ndjson` |
+
+`recommendations.jsonl` is omitted from upload when absent (e.g. insufficient samples).
+
+## Metadata (`POST /packages`)
+
+```json
+{
+  "schema": "kaizen-agentic/optimizer-evidence/v1",
+  "project": "demo-app",
+  "project_root": "/path/to/demo-app",
+  "producer": "kaizen-agentic",
+  "retention_class": "raw-evidence",
+  "retention_days": 180,
+  "optimized_at": "2026-06-18",
+  "agents": ["tdd-workflow", "coach"],
+  "files": [
+    "optimizer/analysis.json",
+    "optimizer/recommendations.jsonl"
+  ]
+}
+```
+
+## Publish workflow
+
+```bash
+# 1. Ensure optimizer has run
+kaizen-agentic metrics optimize
+
+# 2. Publish (artifact-store must be reachable)
+export ARTIFACTSTORE_API_URL=http://127.0.0.1:8000
+export ARTIFACTSTORE_API_TOKEN=<write-token>
+kaizen-agentic metrics publish --target .
+```
+
+Local-only workflows skip publish; `.kaizen/metrics/optimizer/` remains authoritative.
+
+## Related
+
+- [artifact-store ingestion API](https://github.com/coulomb/artifact-store) — `POST /packages`, `/files`, `/finalize`
+- [ADR-004](../adr/ADR-004-project-metrics-convention.md)
+- [INTEGRATION_PATTERNS.md](../INTEGRATION_PATTERNS.md)

docs/templates/session-close-protocol.md

@@ -0,0 +1,33 @@
+# Session-Close Protocol Template
+
+Reference template for memory-enabled agents. Copy the **Session Close** block
+into `agents/agent-<name>.md` and adapt the metrics line to the agent.
+
+## Session Close
+
+1. Update `## Accumulated Findings`, `## What Worked`, and `## Watch Points` as needed.
+2. Append one line to `## Session Log`: `YYYY-MM-DD · <summary> · <outcome>`.
+3. Bump `last_updated` to today and increment `session_count` in memory frontmatter.
+4. Record session metrics (adjust flags to match outcome):
+
+```bash
+kaizen-agentic metrics record <agent-name> --success --time <seconds> --quality <0.0-1.0>
+# or on failure:
+kaizen-agentic metrics record <agent-name> --failure --time <seconds>
+```
+
+Optional: pass a full JSON record (ADR-004 schema) via stdin:
+
+```bash
+echo '{"success": true, "quality_score": 0.9, "primary_metric": {"name": "...", "value": 1.0, "target": 1.0}}' \
+  | kaizen-agentic metrics record <agent-name> --json
+```
+
+Use `--idempotency-key <session-id>` to avoid duplicate records if the close
+protocol runs more than once for the same session.
+
+## Pilot agents
+
+`tdd-workflow` is the reference implementation (WP-0003 Part 5). Other
+memory-enabled agents should adopt this block as the metrics CLI becomes available
+in their workflows.

history/2026-06-16-ecosystem-assessment.md

@@ -0,0 +1,172 @@
+# KaizenAgentic Ecosystem Assessment
+
+**Date:** 2026-06-16
+**Compared repos:** info-tech-canon, agentic-resources, activity-core, llm-connect, identity-canon, phase-memory, artifact-store, domain-tree, kontextual-engine, tele-mcp
+**Against:** `INTENT.md`, `wiki/`, WP-0003 measurement loop plan
+
+---
+
+## Strategic Insight
+
+INTENT's vision is **distributed across the ecosystem**, not missing from a single repo:
+
+| INTENT promise | Primary owner |
+|----------------|---------------|
+| Agent definitions + deployment | kaizen-agentic |
+| Project memory + Coach | kaizen-agentic |
+| Per-agent metrics + optimizer | kaizen-agentic (WP-0003) |
+| Session capture + fleet metrics | agentic-resources (Helix Forge) |
+| Scheduled improvement triggers | activity-core |
+| Evidence retention | artifact-store |
+| Rich memory graphs | phase-memory (future) |
+| Guidance as knowledge | kontextual-engine + info-tech-canon |
+| Semantic vocabulary | info-tech-canon, identity-canon |
+| Org placement | domain-tree |
+| Runtime telemetry MCP | tele-mcp (unassessed — not cloned) |
+
+KaizenAgentic matures by **stabilizing conventions and composing adjacent services**, consistent with INTENT boundaries.
+
+---
+
+## Per-Repo Assessment
+
+### agentic-resources — P0
+
+**Role:** AgentOps / Helix Forge — Capture → Detect → Curate → Distribute → Measure on coding sessions.
+
+**Use:** Fleet-level session metrics (`session_memory/measure/`), JSONL baselines, cross-agent adapters (Claude/Codex/Grok). Complements project-scoped `.kaizen/metrics/`.
+
+**Action:** ADR-004 correlation fields; WP-0004 integration; do not re-implement session ingestion here.
+
+### activity-core — P1
+
+**Role:** Event bridge — cron/NATS → task emission.
+
+**Use:** Scheduled `metrics optimize`, retention hygiene, metrics scaffold validation after agent install.
+
+**Action:** WP-0004 ActivityDefinitions after WP-0003 Part 2.
+
+### artifact-store — P1
+
+**Role:** Artifact registry + retention gateway.
+
+**Use:** Persist optimizer `analysis.json`, recommendations, e2e evidence packages.
+
+**Action:** WP-0004 pilot registration with `raw-evidence` retention class.
+
+### info-tech-canon — P2
+
+**Role:** Markdown-first semantic canon, agent briefs, patterns, profiles.
+
+**Use:** Map KaizenAgentTemplate → canon profiles; publish per-agent briefs; validation rules for `kaizen-agentic validate`.
+
+**Action:** WP-0004 Part 4 (later phase).
+
+### phase-memory — P2
+
+**Role:** Profile-driven memory graphs (ephemeral → rigid).
+
+**Use:** Upgrade path from flat `.kaizen/agents/*/memory.md`.
+
+**Action:** Future WP after WP-0004; no WP-0003 blocker.
+
+### kontextual-engine — P2
+
+**Role:** Knowledge operations engine.
+
+**Use:** Ingest `wiki/` and `agents/` as knowledge assets; KaizenGuidance catalog runtime.
+
+**Action:** WP-0004 Part 4 (guidance pilot).
+
+### llm-connect — P3
+
+**Role:** Provider-neutral LLM adapter.
+
+**Use:** Automated Coach/optimizer narration when LLM synthesis moves beyond CLI context assembly.
+
+**Action:** Reference pattern; adopt when WP-0003+ adds LLM-powered recommendations.
+
+### domain-tree — P3
+
+**Role:** Organizational domain tree (primary + secondary bindings).
+
+**Use:** Register kaizen-agentic and agent categories in org structure.
+
+**Action:** When capability catalog matures.
+
+### identity-canon — P3
+
+**Role:** Identity/agent terminology research.
+
+**Use:** Distinguish agent persona vs instance vs session actor for "digital talent agency" framing.
+
+**Action:** Glossary alignment in wiki.
+
+### tele-mcp — TBD
+
+**Status:** On Forgejo (`coulomb/tele-mcp`); not cloned; not in State Hub registry. Name suggests telemetry MCP.
+
+**Action:** Clone and assess before integration; candidate for WP-0001 T04 telemetry adapter.
+
+---
+
+## Two-Layer Measurement Model
+
+| Layer | Scope | Owner | Storage |
+|-------|-------|-------|---------|
+| **Fleet** | Cross-repo session outcomes | agentic-resources | Helix Forge store + `measure/baselines.jsonl` |
+| **Project** | Per-agent persona performance in one repo | kaizen-agentic | `.kaizen/metrics/<agent>/executions.jsonl` |
+
+Correlation via shared fields defined in ADR-004 (`helix_session_uid`, `repo`, `success`, `tokens`, `execution_time_s`).
+
+See `wiki/EcosystemIntegration.md` for integration contracts.
+
+---
+
+## Priority Matrix
+
+| Priority | Repo | WP |
+|----------|------|-----|
+| P0 | agentic-resources | WP-0004 Part 1 |
+| P1 | activity-core | WP-0004 Part 2 |
+| P1 | artifact-store | WP-0004 Part 3 |
+| P2 | info-tech-canon, kontextual-engine, phase-memory | WP-0004 Part 4 / future |
+| P3 | llm-connect, domain-tree, identity-canon | Adopt as needed |
+| TBD | tele-mcp | Assess when cloned |
+
+---
+
+## Follow-Up Workplans
+
+- **KAIZEN-WP-0003** — measurement loop (completed 2026-06-18)
+- **KAIZEN-WP-0004** — ecosystem integration (completed 2026-06-18)
+
+---
+
+## WP-0004 Outcomes (2026-06-18)
+
+### Part 1 — Helix Forge correlation
+
+- `HELIX_SESSION_UID` env auto-merge on `metrics record`
+- `kaizen-agentic metrics correlate <uid>` read-only adapter (sqlite or stub)
+- Contract: `docs/integrations/helix-forge-correlation.md`
+- Worked example in `wiki/EcosystemIntegration.md`
+
+### Part 2 — activity-core triggers
+
+- Three ActivityDefinition reference copies under `docs/integrations/activity-definitions/`
+- Activation contract: `docs/INTEGRATION_PATTERNS.md`
+
+### Part 3 — artifact-store evidence
+
+- `kaizen-agentic metrics publish` with `raw-evidence` retention class
+- Manifest: `docs/integrations/optimizer-artifact-manifest.md`
+
+### Part 4 — Canon and knowledge (stretch)
+
+- Template mapping: `docs/integrations/canon-template-mapping.md`
+- tdd-workflow canon brief: `docs/integrations/briefs/tdd-workflow-canon-brief.md`
+- kontextual-engine spike: `docs/integrations/kontextual-wiki-ingestion-spike.md`
+
+No hard dependencies on info-tech-canon, kontextual-engine, or agentic-resources
+runtime in kaizen-agentic — integration remains contract-based.

history/2026-06-16-intent-gap-analysis.md

@@ -0,0 +1,87 @@
+# KaizenAgentic Intent Gap Analysis
+
+**Date:** 2026-06-16
+**Scope:** `INTENT.md`, `wiki/`, codebase (`agents/`, `src/kaizen_agentic/`, `docs/`, workplans)
+**Author:** kaizen-agentic session assessment
+
+---
+
+## Executive Summary
+
+Kaizen-agentic is in a **two-layer state**: the strategic/conceptual layer (`INTENT.md`, `wiki/`) is well-developed; the operational layer (agents, CLI, agency framework) is substantial but implements a **deployment and memory** product more than a **measurable continuous-improvement engine**.
+
+The largest gap: the **measurement → optimization → specification refinement loop** described in INTENT is largely unbuilt. Addressed by **KAIZEN-WP-0003** (registered 2026-06-16).
+
+---
+
+## Alignment
+
+| INTENT asset | Status |
+|--------------|--------|
+| Mission and conceptual model | `wiki/` established |
+| KaizenAgent definition template | `wiki/KaizenAgentTemplate.md` — not enforced in agents |
+| Meta-optimizer concept | `wiki/AgentKaizenOptimizer.md` + `agent-optimization.md` — no data pipeline |
+| Idempotent/measurable principles | Documented; not in agent implementations |
+| Codebase improvement guidance | `wiki/KaizenGuidance.md` — vision only |
+| Prompts/experiments/mantras | `wiki/KaizenPrompting.md` — not operationalized |
+| Product/pricing/brand | `wiki/` complete |
+| Agency memory + Coach | WP-0002 shipped |
+| CLI deployment | Functional (21 agents) |
+
+---
+
+## Critical Gaps
+
+### 1. Kaizen loop not closed
+
+INTENT requires evidence-based refinement with before/after deltas. Reality: `OptimizationLoop` exists but is unwired; no `.kaizen/metrics/`; WP-0001 telemetry unstarted.
+
+### 2. Agent template not enforced
+
+Agents use minimal YAML frontmatter; `wiki/KaizenAgentTemplate.md` (metrics, idempotency, testing, evolution) is reference only.
+
+### 3. KaizenGuidance unbuilt
+
+No guide catalog, manifests, codemods, or Parse→Measure pipeline.
+
+### 4. Coach vs optimizer not integrated
+
+Qualitative memory (Coach) and quantitative optimization (optimizer) are separate paths.
+
+### 5. Agent implementation boundary undeclared
+
+INTENT says repo should not own all concrete agent implementations; 21 agents live here as reference fleet — interim state needs explicit policy.
+
+---
+
+## Design Principles Scorecard
+
+| Principle | Status |
+|-----------|--------|
+| Continuous Improvement | Partial (memory; no automated refinement) |
+| Measurable by Default | Gap |
+| Idempotent Operations | Gap |
+| Evidence over Intuition | Gap |
+| Separation of Concerns | Partial |
+| Composable Capabilities | Gap |
+| Human-Readable + Machine-Executable | Gap (guidance) |
+| Rollback-Ready Evolution | Partial |
+| Compounding Value | Partial (memory only) |
+
+---
+
+## Remediation Sequence
+
+1. **WP-0003** — metrics convention, CLI, optimizer wiring, Coach bridge (active)
+2. **WP-0004** — ecosystem integration (agentic-resources, activity-core, artifact-store)
+3. Future — KaizenGuidance catalog, phase-memory upgrade, full template conformance
+
+---
+
+## Related Artifacts
+
+- `SCOPE.md` — updated 2026-06-16
+- `workplans/kaizen-agentic-WP-0003-measurement-loop.md`
+- `history/2026-06-16-ecosystem-assessment.md`
+- `wiki/EcosystemIntegration.md`
+- `docs/adr/ADR-004-project-metrics-convention.md`

history/README.md

@@ -0,0 +1,11 @@
+# History
+
+Persisted assessments, gap analyses, and ecosystem reviews for KaizenAgentic.
+
+| Date | Document | Summary |
+|------|----------|---------|
+| 2026-06-16 | [2026-06-16-intent-gap-analysis.md](2026-06-16-intent-gap-analysis.md) | INTENT.md vs implementation gaps; remediation sequence |
+| 2026-06-16 | [2026-06-16-ecosystem-assessment.md](2026-06-16-ecosystem-assessment.md) | Cross-repo comparison (10 ecosystem repos) |
+
+These files are point-in-time records. Living conventions live in `INTENT.md`,
+`SCOPE.md`, `wiki/`, and `docs/adr/`.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kaizen-agentic"
-version = "1.0.2"
+version = "1.1.0"
 description = "AI agent development framework embracing continuous improvement (kaizen)"
 readme = "README.md"
 license = {file = "LICENSE"}
@@ -135,4 +135,4 @@ exclude_lines = [
 
 [tool.flake8]
 max-line-length = 88
-extend-ignore = ["E203", "W503"]
+extend-ignore = ["E203", "W503"]

registry/README.md

@@ -0,0 +1,12 @@
+# Capability Registry
+
+Markdown-first capability index for federation and reuse planning.
+
+## Authoring
+
+1. Copy a capability entry template (see reuse-surface `templates/capability-entry.template.md`).
+2. Add the row to `indexes/capabilities.yaml`.
+3. Run `reuse-surface validate` from a checkout with the CLI installed.
+4. Merge to `main` and verify publish with `reuse-surface establish --publish-check`.
+
+Federation contract: reuse-surface `docs/RegistryFederation.md`.

registry/indexes/capabilities.yaml

@@ -0,0 +1,4 @@
+version: 1
+updated: '2026-06-16'
+domain: helix_forge
+capabilities: []

src/kaizen_agentic/__init__.py

@@ -9,13 +9,14 @@ It also includes a comprehensive agent distribution system for sharing
 specialized agents across projects via CLI tools and package management.
 """
 
-__version__ = "1.0.2"
+__version__ = "1.1.0"
 __author__ = "Kaizen Agentic Team"
 
 from .core import Agent, AgentConfig
 from .optimization import OptimizationLoop, PerformanceMetrics
 from .registry import AgentRegistry, AgentDefinition, AgentCategory
 from .installer import AgentInstaller, ProjectInitializer, InstallationConfig
+from .metrics import MetricsStore
 
 __all__ = [
     "Agent",
@@ -28,4 +29,5 @@ __all__ = [
     "AgentInstaller",
     "ProjectInitializer",
     "InstallationConfig",
+    "MetricsStore",
 ]

src/kaizen_agentic/cli.py

@@ -1,7 +1,7 @@
 """Command-line interface for Kaizen Agentic agent management."""
 
+import json
 import sys
-import subprocess
 import contextlib
 import io
 import click
@@ -10,6 +10,14 @@ from typing import List, Optional
 
 from .registry import AgentRegistry, AgentCategory
 from .installer import AgentInstaller, ProjectInitializer, InstallationConfig
+from .integrations.artifact_store import (
+    default_api_token,
+    default_api_url,
+    publish_optimizer_evidence,
+)
+from .integrations.helix import HelixCorrelationAdapter, enrich_helix_correlation
+from .metrics import MetricsStore, OptimizerStore, performance_summary_markdown
+from .optimization import OptimizationLoop, MIN_SAMPLES_FOR_RECOMMENDATIONS
 
 
 def safe_cli_wrapper():
@@ -60,17 +68,22 @@ def safe_cli_wrapper():
     affected_commands = len(sys.argv) >= 2 and sys.argv[1] in ["install", "update"]
 
     try:
-        with contextlib.redirect_stderr(stderr_capture), contextlib.redirect_stdout(stdout_capture):
+        with contextlib.redirect_stderr(stderr_capture), contextlib.redirect_stdout(
+            stdout_capture
+        ):
             cli(standalone_mode=False)
     except click.UsageError as e:
         if affected_commands and "Got unexpected extra argument" in str(e):
             # This is the spurious error for install/update commands
             # Check if we got some stdout output indicating success
             captured_stdout = stdout_capture.getvalue()
-            success_indicators = ["Installing agents to:", "Updating all installed agents:"]
+            success_indicators = [
+                "Installing agents to:",
+                "Updating all installed agents:",
+            ]
             if any(indicator in captured_stdout for indicator in success_indicators):
                 # The command was actually executing, show the real output
-                print(captured_stdout, end='')
+                print(captured_stdout, end="")
                 sys.exit(0)
             else:
                 # This might be a real error
@@ -87,29 +100,51 @@ def safe_cli_wrapper():
 
         if e.code == 0:
             # Successful exit
-            print(captured_stdout, end='')
+            print(captured_stdout, end="")
         else:
             # Error exit - show both stdout and stderr unless it's the spurious error
             if affected_commands and "Got unexpected extra argument" in captured_stderr:
                 # Show only stdout for install/update commands with spurious errors
-                print(captured_stdout, end='')
-                success_indicators = ["Installing agents to:", "Updating all installed agents:"]
-                if any(indicator in captured_stdout for indicator in success_indicators):
+                print(captured_stdout, end="")
+                success_indicators = [
+                    "Installing agents to:",
+                    "Updating all installed agents:",
+                ]
+                if any(
+                    indicator in captured_stdout for indicator in success_indicators
+                ):
                     sys.exit(0)  # Override error exit if we see success indicators
             else:
                 # Show everything for other commands
-                print(captured_stdout, end='')
-                print(captured_stderr, end='', file=sys.stderr)
+                print(captured_stdout, end="")
+                print(captured_stderr, end="", file=sys.stderr)
             sys.exit(e.code)
     except Exception as e:
         print(f"Error: {e}")
         sys.exit(1)
 
     # If we get here, show captured output
-    print(stdout_capture.getvalue(), end='')
+    print(stdout_capture.getvalue(), end="")
     stderr_content = stderr_capture.getvalue()
-    if stderr_content and not (affected_commands and "Got unexpected extra argument" in stderr_content):
-        print(stderr_content, end='', file=sys.stderr)
+    if stderr_content and not (
+        affected_commands and "Got unexpected extra argument" in stderr_content
+    ):
+        print(stderr_content, end="", file=sys.stderr)
+
+
+_FEEDBACK_CHANNELS = {
+    "issues": "https://gitea.coulomb.social/coulomb/kaizen-agentic/issues",
+    "issue_templates": "https://gitea.coulomb.social/coulomb/kaizen-agentic/issues/new/choose",
+    "feedback_guide": (
+        "https://gitea.coulomb.social/coulomb/kaizen-agentic/"
+        "src/branch/main/docs/FEEDBACK.md"
+    ),
+    "contributing": (
+        "https://gitea.coulomb.social/coulomb/kaizen-agentic/"
+        "src/branch/main/CONTRIBUTING.md"
+    ),
+}
+
 
 @click.group()
 @click.version_option()
@@ -118,14 +153,43 @@ def cli():
     pass
 
 
-@cli.command()
+@cli.command("feedback")
+@click.option("--json", "as_json", is_flag=True, help="Emit machine-readable JSON")
+def feedback(as_json: bool):
+    """Show how to submit bugs, ideas, and adoption feedback."""
+    payload = {
+        "channels": _FEEDBACK_CHANNELS,
+        "templates": ["bug_report", "feature_request", "feedback"],
+        "cli_hint": (
+            "Use Gitea issue templates or State Hub messages "
+            "for cross-repo coordination"
+        ),
+    }
+    if as_json:
+        click.echo(json.dumps(payload, indent=2, sort_keys=True))
+        return
+
+    click.echo("Kaizen Agentic — feedback channels")
+    click.echo("=" * 40)
+    click.echo(f"Issues:          {_FEEDBACK_CHANNELS['issues']}")
+    click.echo(f"New issue:       {_FEEDBACK_CHANNELS['issue_templates']}")
+    click.echo(f"Feedback guide:  {_FEEDBACK_CHANNELS['feedback_guide']}")
+    click.echo(f"Contributing:    {_FEEDBACK_CHANNELS['contributing']}")
+    click.echo()
+    click.echo("Templates: bug report · feature request · general feedback")
+    click.echo(
+        "Tip: include Python version and `kaizen-agentic --version` in bug reports."
+    )
+
+
+@cli.command("list")
 @click.option(
     "--category",
     type=click.Choice([c.value for c in AgentCategory]),
     help="Filter by category",
 )
 @click.option("--verbose", "-v", is_flag=True, help="Show detailed information")
-def list(category: Optional[str], verbose: bool):
+def list_agents(category: Optional[str], verbose: bool):
     """List available agents."""
     registry = _get_registry()
 
@@ -739,11 +803,11 @@ def disable(name: str, target: str):
         click.echo(f"❌ Extension not found: {name}")
 
 
-@extensions.command()
+@extensions.command("remove")
 @click.argument("name")
 @click.option("--target", "-t", default=".", help="Target directory (default: current)")
 @click.confirmation_option(prompt="Are you sure you want to remove this extension?")
-def remove(name: str, target: str):
+def remove_extension(name: str, target: str):
     """Remove an extension."""
     from .extensions import ExtensionManager
 
@@ -756,6 +820,560 @@ def remove(name: str, target: str):
         click.echo(f"❌ Extension not found: {name}")
 
 
+@cli.group()
+def memory():
+    """Manage project-scoped agent memory (.kaizen/agents/<name>/memory.md)."""
+    pass
+
+
+@memory.command("show")
+@click.argument("agent_name")
+@click.option("--target", "-t", default=".", help="Project root (default: current)")
+def memory_show(agent_name: str, target: str):
+    """Print agent memory for the current project."""
+    memory_path = _memory_path(target, agent_name)
+
+    if not memory_path.exists():
+        click.echo(f"No memory found for agent '{agent_name}'.")
+        click.echo(f"  Expected: {memory_path}")
+        click.echo(f"  Run: kaizen-agentic memory init {agent_name}")
+        return
+
+    click.echo(memory_path.read_text())
+
+
+@memory.command("init")
+@click.argument("agent_name")
+@click.option("--target", "-t", default=".", help="Project root (default: current)")
+@click.option(
+    "--no-metrics",
+    is_flag=True,
+    help="Skip scaffolding .kaizen/metrics/<agent>/ (default: create metrics dir)",
+)
+def memory_init(agent_name: str, target: str, no_metrics: bool):
+    """Scaffold an empty memory file for an agent."""
+    memory_path = _memory_path(target, agent_name)
+
+    if memory_path.exists():
+        click.echo(f"Memory file already exists: {memory_path}")
+        return
+
+    memory_path.parent.mkdir(parents=True, exist_ok=True)
+    project_name = Path(target).resolve().name
+
+    content = f"""---
+agent: {agent_name}
+project: {project_name}
+last_updated: {_today()}
+session_count: 0
+---
+
+## Project Context
+<!-- What this agent knows about the project it works in -->
+
+## Accumulated Findings
+<!-- Patterns, recurring issues, key decisions encountered -->
+
+## What Worked
+<!-- Approaches that produced good results in this project -->
+
+## Watch Points
+<!-- Recurring risks, traps, or areas requiring extra care -->
+
+## Open Threads
+<!-- Things noticed but not yet acted on -->
+
+## Session Log
+<!-- One-line entry per session: date · summary · outcome -->
+"""
+    memory_path.write_text(content)
+    click.echo(f"Initialized memory for '{agent_name}': {memory_path}")
+
+    if not no_metrics:
+        metrics_dir = MetricsStore(Path(target), agent_name).scaffold()
+        click.echo(f"Initialized metrics for '{agent_name}': {metrics_dir}")
+
+    # For agents with protocols, note the protocol location
+    registry = _get_registry()
+    protocols_dir = registry.agents_dir / "protocols" / agent_name
+    if protocols_dir.exists():
+        slugs = [
+            f.stem for f in sorted(protocols_dir.glob("*.md")) if f.name != "README.md"
+        ]
+        if slugs:
+            click.echo(f"  Protocols available for '{agent_name}':")
+            for slug in slugs:
+                click.echo(f"    kaizen-agentic protocols show {agent_name} {slug}")
+
+
+@memory.command("brief")
+@click.argument("agent_name")
+@click.option("--target", "-t", default=".", help="Project root (default: current)")
+@click.option(
+    "--raw", is_flag=True, help="Dump raw memory files without synthesis header"
+)
+def memory_brief(agent_name: str, target: str, raw: bool):
+    """Print a coach-synthesised orientation for an agent.
+
+    Reads all agent memories in the project and formats an orientation brief
+    for the specified agent, following the coach agent (agents/agent-coach.md)
+    output format. Pass to a Claude session with the coach agent loaded for
+    full LLM synthesis.
+    """
+    project_root = Path(target).resolve()
+    kaizen_dir = project_root / ".kaizen" / "agents"
+    project_name = project_root.name
+
+    # Collect all agent memories
+    own_memory: Optional[str] = None
+    other_memories: dict = {}
+
+    if kaizen_dir.exists():
+        for agent_dir in sorted(kaizen_dir.iterdir()):
+            if not agent_dir.is_dir():
+                continue
+            mf = agent_dir / "memory.md"
+            if not mf.exists():
+                continue
+            if agent_dir.name == agent_name:
+                own_memory = mf.read_text()
+            else:
+                other_memories[agent_dir.name] = mf.read_text()
+
+    if raw:
+        if own_memory:
+            click.echo(f"=== {agent_name} ===\n{own_memory}")
+        for name, content in other_memories.items():
+            click.echo(f"=== {name} ===\n{content}")
+        return
+
+    from datetime import date as _date
+
+    today = _date.today().isoformat()
+    sources = ([agent_name] if own_memory else []) + list(other_memories.keys())
+
+    click.echo(f"## Orientation Brief for: {agent_name}")
+    click.echo(f"Project: {project_name}")
+    click.echo(f"Generated: {today}")
+    click.echo(f"Sources: {', '.join(sources) if sources else 'none'}")
+    click.echo()
+
+    metrics_store = MetricsStore(project_root, agent_name)
+    metrics_summary = metrics_store.read_summary()
+    if metrics_summary is None and metrics_store.executions_path.exists():
+        metrics_summary = metrics_store.write_summary()
+
+    if not sources and not metrics_summary:
+        click.echo("No agent memory files found in this project.")
+        click.echo(f"  Run: kaizen-agentic memory init {agent_name}")
+        click.echo("  Then load the coach agent (agents/agent-coach.md) for synthesis.")
+        return
+
+    performance_block = performance_summary_markdown(metrics_summary or {})
+    if performance_block:
+        click.echo(performance_block)
+
+    # Own memory section
+    if own_memory:
+        click.echo("### Your Memory")
+        click.echo(own_memory)
+    else:
+        click.echo(
+            f"### Your Memory\n(none — run: kaizen-agentic memory init {agent_name})\n"
+        )
+
+    # Cross-agent context
+    if other_memories:
+        click.echo("### Context From Other Agents")
+        click.echo("(Load coach agent for full synthesis. Raw content below.)\n")
+        for name, content in other_memories.items():
+            click.echo(f"--- {name} ---")
+            click.echo(content)
+    else:
+        click.echo(
+            "### Context From Other Agents\nNo other agent memories found in this project.\n"
+        )
+
+    click.echo("---")
+    click.echo(
+        "Tip: Load agents/agent-coach.md in your Claude session and pass this output"
+    )
+    click.echo("     for a full cross-agent synthesis and orientation brief.")
+
+
+@memory.command("clear")
+@click.argument("agent_name")
+@click.option("--target", "-t", default=".", help="Project root (default: current)")
+@click.confirmation_option(
+    prompt="This will permanently delete the agent memory. Continue?"
+)
+def memory_clear(agent_name: str, target: str):
+    """Wipe agent memory for the current project."""
+    memory_path = _memory_path(target, agent_name)
+
+    if not memory_path.exists():
+        click.echo(f"No memory found for agent '{agent_name}' — nothing to clear.")
+        return
+
+    memory_path.unlink()
+    click.echo(f"Cleared memory for '{agent_name}': {memory_path}")
+
+    # Remove empty parent directory
+    if not any(memory_path.parent.iterdir()):
+        memory_path.parent.rmdir()
+
+
+@cli.group()
+def metrics():
+    """Manage project-scoped agent metrics (.kaizen/metrics/<agent>/)."""
+    pass
+
+
+@metrics.command("record")
+@click.argument("agent_name")
+@click.option("--target", "-t", default=".", help="Project root (default: current)")
+@click.option(
+    "--success", "outcome_success", is_flag=True, help="Record successful execution"
+)
+@click.option(
+    "--failure", "outcome_failure", is_flag=True, help="Record failed execution"
+)
+@click.option("--time", "execution_time", type=float, help="Execution time in seconds")
+@click.option("--quality", type=float, help="Quality score 0.0–1.0")
+@click.option("--session-id", help="Optional session identifier")
+@click.option("--idempotency-key", help="Skip append if this key was already recorded")
+@click.option(
+    "--json", "json_input", is_flag=True, help="Read full record JSON from stdin"
+)
+def metrics_record(
+    agent_name: str,
+    target: str,
+    outcome_success: bool,
+    outcome_failure: bool,
+    execution_time: Optional[float],
+    quality: Optional[float],
+    session_id: Optional[str],
+    idempotency_key: Optional[str],
+    json_input: bool,
+):
+    """Append one execution record for an agent."""
+    store = MetricsStore(_project_root(target), agent_name)
+
+    if json_input:
+        payload = json.load(sys.stdin)
+        if not isinstance(payload, dict):
+            click.echo("Error: JSON input must be an object", err=True)
+            sys.exit(1)
+    else:
+        if outcome_success and outcome_failure:
+            click.echo("Error: use only one of --success or --failure", err=True)
+            sys.exit(1)
+        if not outcome_success and not outcome_failure:
+            click.echo(
+                "Error: specify --success or --failure (or use --json)", err=True
+            )
+            sys.exit(1)
+        payload = {"success": outcome_success}
+        if execution_time is not None:
+            payload["execution_time_s"] = execution_time
+        if quality is not None:
+            payload["quality_score"] = quality
+        if session_id:
+            payload["session_id"] = session_id
+
+    payload = enrich_helix_correlation(payload)
+
+    if store.append(payload, idempotency_key=idempotency_key):
+        click.echo(f"Recorded metrics for '{agent_name}'")
+    else:
+        click.echo(
+            f"Skipped duplicate record for '{agent_name}' (idempotency key exists)"
+        )
+
+
+@metrics.command("show")
+@click.argument("agent_name")
+@click.option("--target", "-t", default=".", help="Project root (default: current)")
+@click.option(
+    "--limit", "-n", default=5, show_default=True, help="Recent executions to show"
+)
+def metrics_show(agent_name: str, target: str, limit: int):
+    """Print metrics summary and recent executions for an agent."""
+    store = MetricsStore(_project_root(target), agent_name)
+
+    if not store.executions_path.exists():
+        click.echo(f"No metrics found for agent '{agent_name}'.")
+        click.echo(f"  Expected: {store.agent_dir}")
+        click.echo(f"  Run: kaizen-agentic memory init {agent_name}")
+        return
+
+    summary = store.read_summary() or store.write_summary()
+    click.echo(f"Metrics for '{agent_name}':")
+    click.echo("=" * 40)
+    click.echo(json.dumps(summary, indent=2))
+
+    records = store.read_executions()
+    if records:
+        click.echo("\nRecent executions:")
+        for record in records[-limit:]:
+            click.echo(json.dumps(record, sort_keys=True))
+
+
+@metrics.command("list")
+@click.option("--target", "-t", default=".", help="Project root (default: current)")
+def metrics_list(target: str):
+    """List agents with metrics in the current project."""
+    agents = MetricsStore.list_agents(_project_root(target))
+    if not agents:
+        click.echo("No agent metrics found in this project.")
+        click.echo("  Run: kaizen-agentic memory init <agent>")
+        return
+
+    click.echo("Agents with metrics:")
+    for name in agents:
+        store = MetricsStore(_project_root(target), name)
+        summary = store.read_summary()
+        count = summary["execution_count"] if summary else len(store.read_executions())
+        click.echo(f"  • {name} ({count} executions)")
+
+
+@metrics.command("optimize")
+@click.argument("agent_name", required=False)
+@click.option("--target", "-t", default=".", help="Project root (default: current)")
+@click.option(
+    "--min-samples",
+    default=MIN_SAMPLES_FOR_RECOMMENDATIONS,
+    show_default=True,
+    help="Minimum execution records required for recommendations",
+)
+def metrics_optimize(agent_name: Optional[str], target: str, min_samples: int):
+    """Run optimizer analysis on project metrics and write recommendations."""
+    project_root = _project_root(target)
+    agents = [agent_name] if agent_name else MetricsStore.list_agents(project_root)
+
+    if not agents:
+        click.echo("No agent metrics found to optimize.")
+        click.echo(
+            "  Record executions with: kaizen-agentic metrics record <agent> --success"
+        )
+        return
+
+    optimizer_store = OptimizerStore(project_root)
+    combined_reports = []
+
+    for name in agents:
+        store = MetricsStore(project_root, name)
+        records = store.read_executions()
+        loop = OptimizationLoop.from_metrics_store(store, min_samples=1)
+        report = loop.get_optimization_report_json()
+        report["sample_threshold"] = min_samples
+        report["meets_sample_threshold"] = len(records) >= min_samples
+        combined_reports.append(report)
+
+        click.echo(f"Agent: {name}")
+        click.echo("=" * 40)
+        click.echo(json.dumps(report, indent=2))
+
+        if len(records) >= min_samples:
+            optimizer_store.append_recommendations(
+                name,
+                report["recommendations"],
+                metrics_count=len(records),
+            )
+        else:
+            click.echo(
+                f"  Note: {len(records)} record(s) — "
+                f"need {min_samples} for actionable recommendations"
+            )
+        click.echo()
+
+    analysis_payload = {
+        "project": project_root.name,
+        "optimized_at": _today(),
+        "min_samples": min_samples,
+        "agents": combined_reports,
+    }
+    analysis_path = optimizer_store.write_analysis(analysis_payload)
+    click.echo(f"Wrote optimizer analysis: {analysis_path}")
+
+
+@metrics.command("correlate")
+@click.argument("session_uid")
+@click.option(
+    "--store-db",
+    envvar="HELIX_STORE_DB",
+    help="Helix Forge session-memory SQLite database path",
+)
+def metrics_correlate(session_uid: str, store_db: Optional[str]):
+    """Look up Helix Forge digest summary for a session UID (read-only)."""
+    adapter = HelixCorrelationAdapter(
+        store_db=Path(store_db).resolve() if store_db else None
+    )
+    if adapter.store_db is None:
+        adapter = HelixCorrelationAdapter.from_env()
+    summary = adapter.lookup(session_uid)
+    click.echo(json.dumps(summary, indent=2, sort_keys=True))
+
+
+@metrics.command("publish")
+@click.option("--target", "-t", default=".", help="Project root (default: current)")
+@click.option(
+    "--api-url",
+    default=default_api_url,
+    show_default=True,
+    help="artifact-store API base URL (ARTIFACTSTORE_API_URL)",
+)
+@click.option(
+    "--token",
+    default=default_api_token,
+    help="artifact-store bearer token (ARTIFACTSTORE_API_TOKEN)",
+)
+@click.option(
+    "--subject",
+    help="Package subject (default: project directory name)",
+)
+@click.option(
+    "--retention-class",
+    default="raw-evidence",
+    show_default=True,
+    help="artifact-store retention class",
+)
+def metrics_publish(
+    target: str,
+    api_url: str,
+    token: str,
+    subject: Optional[str],
+    retention_class: str,
+):
+    """Publish optimizer evidence to artifact-store (optional integration)."""
+    project_root = _project_root(target)
+    if not token:
+        click.echo(
+            "Error: artifact-store token required. Set ARTIFACTSTORE_API_TOKEN or --token.",
+            err=True,
+        )
+        sys.exit(1)
+    try:
+        result = publish_optimizer_evidence(
+            project_root,
+            api_url=api_url,
+            token=token,
+            subject=subject,
+            retention_class=retention_class,
+        )
+    except FileNotFoundError as exc:
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+    except RuntimeError as exc:
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+
+    click.echo(f"Published optimizer evidence package: {result.package_id}")
+    click.echo(f"  Files uploaded: {result.files_uploaded}")
+    click.echo(f"  Retention class: {result.retention_class}")
+    if result.manifest_digest:
+        click.echo(f"  Manifest digest: {result.manifest_digest}")
+
+
+@metrics.command("export")
+@click.argument("agent_name")
+@click.option("--target", "-t", default=".", help="Project root (default: current)")
+def metrics_export(agent_name: str, target: str):
+    """Dump executions.jsonl for an agent to stdout."""
+    store = MetricsStore(_project_root(target), agent_name)
+    if not store.executions_path.exists():
+        click.echo(f"No metrics found for agent '{agent_name}'.", err=True)
+        sys.exit(1)
+    click.echo(store.executions_path.read_text(encoding="utf-8"), nl=False)
+
+
+@cli.group()
+def protocols():
+    """Browse agent protocol runbooks (agents/protocols/<agent>/<slug>.md)."""
+    pass
+
+
+@protocols.command("list")
+@click.argument("agent_name", required=False)
+def protocols_list(agent_name: Optional[str]):
+    """List available protocols, optionally filtered by agent."""
+    registry = _get_registry()
+    protocols_dir = registry.agents_dir / "protocols"
+
+    if not protocols_dir.exists():
+        click.echo("No protocols directory found.")
+        return
+
+    found = []
+    agent_dirs = (
+        [protocols_dir / agent_name] if agent_name else sorted(protocols_dir.iterdir())
+    )
+    for agent_dir in agent_dirs:
+        if not agent_dir.is_dir() or agent_dir.name == "__pycache__":
+            continue
+        for protocol_file in sorted(agent_dir.glob("*.md")):
+            if protocol_file.name == "README.md":
+                continue
+            # Try to read title from frontmatter
+            title = protocol_file.stem.replace("-", " ").title()
+            try:
+                content = protocol_file.read_text()
+                for line in content.splitlines():
+                    if line.startswith("title:"):
+                        title = line.split(":", 1)[1].strip().strip('"')
+                        break
+            except Exception:
+                pass
+            found.append((agent_dir.name, protocol_file.stem, title))
+
+    if not found:
+        if agent_name:
+            click.echo(f"No protocols found for agent '{agent_name}'.")
+        else:
+            click.echo("No protocols found.")
+        return
+
+    click.echo("Available Protocols:")
+    click.echo("=" * 40)
+    current_agent = None
+    for agent, slug, title in found:
+        if agent != current_agent:
+            click.echo(f"\n  {agent}:")
+            current_agent = agent
+        click.echo(f"    • {slug}: {title}")
+
+
+@protocols.command("show")
+@click.argument("agent_name")
+@click.argument("slug")
+def protocols_show(agent_name: str, slug: str):
+    """Print a protocol runbook."""
+    registry = _get_registry()
+    protocol_path = registry.agents_dir / "protocols" / agent_name / f"{slug}.md"
+
+    if not protocol_path.exists():
+        click.echo(f"Protocol not found: {agent_name}/{slug}")
+        click.echo(f"  Expected: {protocol_path}")
+        click.echo(f"  Run: kaizen-agentic protocols list {agent_name}")
+        return
+
+    click.echo(protocol_path.read_text())
+
+
+def _project_root(target: str) -> Path:
+    return Path(target).resolve()
+
+
+def _memory_path(target: str, agent_name: str) -> Path:
+    return _project_root(target) / ".kaizen" / "agents" / agent_name / "memory.md"
+
+
+def _today() -> str:
+    from datetime import date
+
+    return date.today().isoformat()
+
+
 def _get_registry() -> AgentRegistry:
     """Get the agent registry."""
     # Try to find agents directory
@@ -778,14 +1396,20 @@ def _get_registry() -> AgentRegistry:
                 # Try relative to package
                 agents_dir = Path(kaizen_agentic.__file__).parent / "data" / "agents"
         except ImportError:
-            click.echo("Error: Could not find agents directory")
-            click.echo(
-                "Make sure you're in a kaizen-agentic project or have the package installed"
-            )
+            click.echo("Error: kaizen-agentic package is not installed.", err=True)
+            click.echo("  Fix: pip install -e .  (from repo root)", err=True)
+            click.echo("  Or: run from a project with an agents/ directory", err=True)
             sys.exit(1)
 
     if not agents_dir.exists():
-        click.echo(f"Error: Agents directory not found: {agents_dir}")
+        click.echo(f"Error: agents directory not found: {agents_dir}", err=True)
+        click.echo(
+            "  Fix: cd into a kaizen-agentic checkout or a project with agents/",
+            err=True,
+        )
+        click.echo(
+            "  Or: kaizen-agentic install <template>  to scaffold agents", err=True
+        )
         sys.exit(1)
 
     return AgentRegistry(agents_dir)

src/kaizen_agentic/data/agents/agent-coach.md

@@ -0,0 +1,184 @@
+---
+name: coach
+description: Coaching meta-agent that reads all agent memories in a project and synthesises cross-agent briefs and new-agent orientations
+category: meta
+memory: enabled
+---
+
+# Coach Agent
+
+## Role
+
+You are the **kaizen-agentic Coach** — a meta-agent that observes, synthesises,
+and advises. You do not perform domain work (coding, testing, infrastructure).
+Your sole purpose is to read across the accumulated memories of all agents in a
+project and produce useful, targeted briefs.
+
+You are invoked via:
+```
+kaizen-agentic memory brief <agent-name>
+```
+
+Or directly by the operator: *"Coach, brief the sys-medic agent on this project"*
+or *"Coach, what patterns have you observed across all agents?"*
+
+---
+
+## What You Do
+
+### 1. Cross-Agent Synthesis
+
+Read all `.kaizen/agents/*/memory.md` files in the current project. Identify:
+
+- **Shared patterns**: themes that appear across multiple agents
+  (e.g. "three agents flagged missing test coverage as a risk")
+- **Cross-domain risks**: signals in one agent's memory that should inform
+  another (e.g. infrastructure instability flagged by sys-medic → tdd-workflow
+  should account for flaky environments)
+- **Resource or architectural signals**: recurring mentions of specific files,
+  modules, services, or systems across agents
+- **Contradictions or gaps**: where agents hold conflicting assumptions or where
+  no agent has coverage
+
+### 2. New-Agent Orientation
+
+When asked to brief a specific agent about to be deployed for the first time:
+
+1. Read all existing agent memories in the project
+2. Filter for what is relevant to the incoming agent's domain
+3. Produce a targeted orientation brief covering:
+   - **Project context**: what kind of project this is, key constraints
+   - **What to know first**: the most important facts for this agent
+   - **Watch points**: risks or pitfalls flagged by other agents that are relevant
+   - **What has worked**: successful approaches in adjacent domains
+   - **Open threads**: unresolved items from other agents that may interact with
+     this agent's work
+
+### 3. Fleet Health Overview
+
+When asked for a fleet overview:
+
+- Summarise the health of the agent fleet: which agents are active, stale, or
+  missing from the project
+- Flag agents with high `session_count` and still-open `## Open Threads`
+- Identify agents whose memories suggest overlapping concerns
+- Recommend whether any memory files should be reviewed or reset
+
+---
+
+## How to Read Agent Memory Files
+
+Memory files live at `.kaizen/agents/<name>/memory.md` relative to the project
+root. Each follows ADR-002 structure:
+
+```
+## Project Context      ← agent's understanding of the project
+## Accumulated Findings ← patterns and recurring issues
+## What Worked         ← validated approaches
+## Watch Points        ← risks and traps
+## Open Threads        ← unresolved items
+## Session Log         ← chronological session summaries
+```
+
+When synthesising, weight `## Watch Points` and `## Open Threads` most heavily —
+these are the signals most likely to be actionable for another agent.
+
+### Project metrics (ADR-004)
+
+Quantitative performance data lives at `.kaizen/metrics/<agent>/summary.json`.
+`kaizen-agentic memory brief <agent>` includes a `## Performance Summary` block
+when metrics exist.
+
+When synthesising orientations:
+
+- Combine qualitative memory with quantitative trends (success rate, quality,
+  execution time, trend arrows)
+- Flag agents with declining success rate or quality trends
+- Cross-reference metrics with `## Watch Points` — do metrics confirm or
+  contradict qualitative findings?
+- Note when an agent has memory but no metrics (incomplete session-close protocol)
+
+Fleet optimizer output at `.kaizen/metrics/optimizer/analysis.json` provides
+project-wide analysis from `kaizen-agentic metrics optimize`.
+
+---
+
+## Output Format
+
+### Cross-agent brief
+
+```
+## Cross-Agent Brief — <project name>
+Generated: <date>
+Agents with memory: <list>
+
+### Shared Patterns
+<bullet list of themes appearing across ≥2 agents>
+
+### Cross-Domain Risks
+<risks from one domain relevant to others>
+
+### Open Threads (fleet-wide)
+<unresolved items that span or affect multiple agents>
+
+### Fleet Health
+<which agents are active/stale, any concerning signals>
+```
+
+### New-agent orientation
+
+```
+## Orientation Brief for: <agent-name>
+Project: <project name>
+Generated: <date>
+Sources: <which agent memories were read>
+
+### Performance Summary
+<from .kaizen/metrics/<agent>/ when available — success rate, quality, trends>
+
+### What to Know First
+<3–5 most important facts for this agent>
+
+### Watch Points
+<risks relevant to this agent's domain>
+
+### What Has Worked
+<approaches validated by other agents that apply here>
+
+### Open Threads You May Encounter
+<items from other agents that may intersect with your work>
+```
+
+---
+
+## Behaviour Boundaries
+
+- **Do not** modify agent memory files
+- **Do not** perform any domain-specific work (coding, testing, diagnosis)
+- **Do not** make decisions — synthesise and advise only
+- **If no memories exist**: say so clearly and offer to help initialise them
+- **If asked about a specific agent not present**: note the gap
+
+---
+
+## Coach's Own Memory
+
+The coach maintains `.kaizen/agents/coach/memory.md` covering:
+
+- Fleet-level patterns observed over time
+- How the agent population in this project has evolved
+- Meta-observations about how well the memory convention is being followed
+- Recurring gaps or blind spots in the agent fleet
+
+### Session Start
+
+1. Check for `.kaizen/agents/coach/memory.md`.
+2. If present, read it — prior fleet observations provide context for the current synthesis.
+3. Scan `.kaizen/agents/*/memory.md` to build the current fleet picture.
+
+### Session Close
+
+1. Update `## Accumulated Findings` with new fleet-level patterns.
+2. Note any new agents added or memory files reset.
+3. Append one line to `## Session Log`: `YYYY-MM-DD · <brief requested for> · <key finding>`.
+4. Bump `last_updated` and `session_count`.

src/kaizen_agentic/data/agents/agent-optimization.md

@@ -1,7 +1,9 @@
 ---
-name: agent-optimizer
+name: optimization
 description: Meta-agent that analyzes and optimizes other Claude Code subagents based on their performance data, usage patterns, and effectiveness metrics. Use PROACTIVELY for agent ecosystem improvement.
 model: inherit
+category: meta
+memory: enabled
 ---
 
 # Kaizen Optimizer - Agent Performance Meta-Optimizer
@@ -165,4 +167,25 @@ This agent operates within Claude Code's conversation context and focuses on:
 - **Ecosystem Balance**: Ensuring agents complement rather than compete with each other
 - **Practical Improvements**: Recommendations that can be implemented through specification updates
 
-The agent serves as the continuous improvement engine for the subagent ecosystem, ensuring agents evolve to better serve user needs and project requirements.
+The agent serves as the continuous improvement engine for the subagent ecosystem, ensuring agents evolve to better serve user needs and project requirements.
+
+## Session Start
+
+1. Check for `.kaizen/agents/optimization/memory.md` in the project root.
+2. If present, read it before beginning analysis.
+3. Review `.kaizen/metrics/optimizer/analysis.json` if it exists for the latest fleet report.
+
+## Session Close
+
+1. When analysis completes, note key findings in `## Accumulated Findings`.
+2. Append one line to `## Session Log`: `YYYY-MM-DD · <agents reviewed> · <outcome>`.
+3. Bump `last_updated` and increment `session_count`.
+4. Persist quantitative analysis via CLI (ADR-004):
+
+```bash
+kaizen-agentic metrics optimize [agent-name]
+```
+
+Run without an agent name to analyze all agents with project metrics. Requires
+≥10 execution records per agent for actionable recommendations (see
+`wiki/AgentKaizenOptimizer.md`).

src/kaizen_agentic/data/agents/agent-scope-analyst.md

@@ -0,0 +1,386 @@
+---
+name: scope-analyst
+description: Analyze a repository and produce/improve SCOPE.md for rapid orientation
+category: project-management
+model: inherit
+---
+
+# ROLE
+
+You are a **Repository Scope Analyst**.
+
+Your task is to analyze a code repository and produce or improve a `SCOPE.md` file that helps humans and agents quickly understand:
+
+- what the repository is about
+- what capability it provides
+- when it is relevant
+- when it is not relevant
+- how it relates to other repositories
+
+You optimize for **clarity, boundary definition, and fast orientation**, not completeness or documentation depth.
+
+---
+
+# CONTEXT
+
+The repository is part of a larger ecosystem with:
+
+- many repositories
+- varying levels of maturity
+- overlapping functionality
+- inconsistent terminology
+
+The `SCOPE.md` file is a **lightweight orientation artifact**, not a formal specification.
+
+It is intentionally:
+
+- short
+- pragmatic
+- possibly incomplete
+- easy to maintain
+
+It is NOT:
+
+- a README replacement
+- an architecture document
+- a marketing text
+
+---
+
+# GOAL
+
+Produce a `SCOPE.md` that allows a reader to decide in under 60 seconds:
+
+- Is this repository relevant to my problem?
+- Should I inspect this repo further?
+- Does it overlap with something else?
+- Can I trust or reuse it?
+
+---
+
+# INPUT
+
+You will be given:
+
+- repository structure
+- code files
+- README and other documentation (if available)
+- optionally an existing `SCOPE.md`
+
+---
+
+# TASKS
+
+## 1. Understand the Repository
+
+Analyze:
+
+- purpose and intent
+- actual implemented functionality (not just claims)
+- entry points and interfaces
+- dependencies
+- naming and terminology
+- maturity signals (tests, structure, completeness)
+
+If unclear, infer cautiously and prefer honest uncertainty over invention.
+
+---
+
+## 2. Identify Capability Boundary
+
+Determine:
+
+- the **core capability** this repo provides
+- what it clearly owns
+- what it explicitly does NOT own
+- where its natural boundaries lie
+
+Avoid vague statements.
+
+---
+
+## 3. Evaluate Relevance
+
+Determine:
+
+- when someone SHOULD consider this repository
+- when someone should IGNORE it
+
+Think in terms of **real usage scenarios**.
+
+---
+
+## 4. Assess Maturity (Roughly)
+
+Estimate:
+
+- status (concept / experimental / active / stable / deprecated)
+- implementation completeness
+- stability
+- likely usability
+
+Do not overstate maturity.
+
+---
+
+## 5. Detect Terminology Signals
+
+Identify:
+
+- important domain terms used
+- potential inconsistencies or ambiguities
+- terms that may conflict with other repositories
+
+---
+
+## 6. Identify Overlap & Adjacency (if possible)
+
+If hints exist:
+
+- similar responsibilities
+- duplicated logic
+- competing abstractions
+
+Mention them carefully.
+
+If unknown, omit or state uncertainty.
+
+---
+
+## 7. Produce or Update SCOPE.md
+
+### If no SCOPE.md exists:
+Create a new one using the template below.
+
+### If SCOPE.md exists:
+- improve clarity
+- correct inaccuracies
+- sharpen boundaries
+- remove fluff
+- preserve useful existing content
+
+---
+
+# OUTPUT REQUIREMENTS
+
+- Follow the provided `SCOPE.md` template structure
+- Keep it **concise and scannable**
+- Prefer bullet points over paragraphs
+- Avoid speculation presented as fact
+- Avoid generic phrases like "handles various things"
+- Be explicit about **Out of Scope**
+- Be honest about uncertainty
+
+---
+
+# STYLE GUIDELINES
+
+Write like an experienced engineer explaining the repo to another engineer:
+
+- direct
+- precise
+- neutral
+- non-marketing
+- no unnecessary verbosity
+
+Bad:
+> "This repository provides a powerful and flexible solution..."
+
+Good:
+> "Provides X for Y in context Z."
+
+---
+
+# TEMPLATE
+
+Use this structure when creating or rewriting SCOPE.md:
+
+```markdown
+# SCOPE
+
+> This file helps you quickly understand what this repository is about,
+> when it is relevant, and when it is not.
+> It is intentionally lightweight and may be incomplete.
+
+---
+
+## One-liner
+
+<!-- Describe the purpose of this repository in one precise sentence. -->
+
+---
+
+## Core Idea
+
+<!-- What is the main capability or idea behind this repository? -->
+<!-- What problem does it try to solve? -->
+
+---
+
+## In Scope
+
+<!-- What this repository is responsible for. -->
+<!-- Be explicit and concrete. -->
+
+-
+-
+-
+
+---
+
+## Out of Scope
+
+<!-- What this repository deliberately does NOT do. -->
+<!-- This is often more important than "In Scope". -->
+
+-
+-
+-
+
+---
+
+## Relevant When
+
+<!-- When should someone consider using or exploring this repository? -->
+
+-
+-
+-
+
+---
+
+## Not Relevant When
+
+<!-- When should someone ignore this repository? -->
+
+-
+-
+-
+
+---
+
+## Current State
+
+<!-- Rough indication of maturity. No strict format required. -->
+
+- Status: <!-- e.g. concept / experimental / active / stable / deprecated -->
+- Implementation: <!-- e.g. idea / partial / substantial / complete -->
+- Stability: <!-- e.g. unstable / evolving / stable -->
+- Usage: <!-- e.g. none / personal / internal / production -->
+
+---
+
+## How It Fits
+
+<!-- Where does this repository sit in the bigger picture? -->
+
+- Upstream dependencies:
+- Downstream consumers:
+- Often used with:
+
+---
+
+## Terminology
+
+<!-- Terms that are important to understand this repo. -->
+<!-- Especially useful if naming differs from other repos. -->
+
+- Preferred terms:
+- Also known as:
+- Potentially confusing terms:
+
+---
+
+## Related / Overlapping Repositories
+
+<!-- List repositories that have similar or adjacent responsibilities. -->
+
+- <repo-name> — <!-- how it relates -->
+
+---
+
+## Getting Oriented
+
+<!-- If someone decides to look deeper, where should they start? -->
+
+- Start with:
+- Key files / directories:
+- Entry points:
+
+---
+
+## Provided Capabilities
+
+<!-- What can this repo's domain provide to other domains on request? -->
+<!-- Each capability block is parsed by the state-hub capability catalog ingest. -->
+<!-- Remove the examples and add your own, or leave empty if none. -->
+
+<!--
+```capability
+type: infrastructure
+title: Example capability title
+description: What this capability provides, in one or two sentences.
+keywords: [keyword1, keyword2, keyword3]
+```
+-->
+
+---
+
+## Notes
+
+<!-- Anything else worth knowing. Keep it short. -->
+```
+
+---
+
+# HEURISTICS
+
+Apply these heuristics:
+
+- If README and code disagree → trust the code
+- If unclear → state uncertainty explicitly
+- If repo is tiny → keep SCOPE very short
+- If repo is complex → focus on boundaries, not details
+- If repo is experimental → reflect that clearly
+- If repo mixes multiple concerns → call it out
+
+---
+
+# ANTI-GOALS
+
+Do NOT:
+
+- write long prose
+- explain implementation details deeply
+- restate README content
+- invent features not present
+- assume production readiness
+- hide ambiguity
+
+---
+
+# SUCCESS CRITERIA
+
+A good result allows a reader to quickly answer:
+
+- What is this repo for?
+- Should I care?
+- Where does it fit?
+- Is it mature enough?
+- Is it overlapping something else?
+
+If those are clear, the task is successful.
+
+---
+
+## Session Start
+
+1. Check for `.kaizen/agents/scope-analyst/memory.md` in the project root.
+2. If present, read it — prior SCOPE.md analyses and boundary decisions may be useful context.
+3. If absent, this is typically fine for a first-run analysis.
+
+## Session Close
+
+1. If a SCOPE.md was produced or meaningfully revised, note the key boundary decisions in `## Accumulated Findings`.
+2. Append one line to `## Session Log`: `YYYY-MM-DD · <repo analysed> · <outcome>`.
+3. Bump `last_updated` to today and increment `session_count`.

src/kaizen_agentic/data/agents/agent-sys-medic.md

@@ -0,0 +1,366 @@
+---
+name: sys-medic
+description: Linux/Kubernetes node health assessment agent — diagnoses process, memory, CPU, disk, network, and kubelet issues with safe, prioritized, evidence-driven guidance
+category: infrastructure
+memory: enabled
+source: sys-medic (~/sys-medic/agent-sys-medic.md)
+---
+
+# Session Start Protocol
+
+1. Check for `.kaizen/agents/sys-medic/memory.md` in the project root.
+2. If present, read it — pay particular attention to `## Node Profiles` (known baselines
+   per host) and `## Recurring Findings` (issues seen before on this infrastructure).
+3. Acknowledge memory in your opening brief: note any relevant node profiles or prior findings.
+4. If a structured assessment is requested, check for
+   `agents/protocols/sys-medic/k3s-node-health-assessment.md` and use it as your procedure.
+
+# Session Close Protocol
+
+1. Update `## Node Profiles` — add or revise the entry for any host assessed this session
+   (hostname | typical load | known quirks | last assessment date).
+2. Update `## Recurring Findings` — if an issue was seen previously, increment its frequency
+   and note the date.
+3. Update `## Accumulated Findings`, `## What Worked`, `## Watch Points` as appropriate.
+4. Append one line to `## Session Log`: `YYYY-MM-DD · <host(s) assessed> · <key finding> · <outcome>`.
+5. Bump `last_updated` and `session_count`.
+
+---
+
+You are SysMedic, a careful coding and systems operations agent for Linux-based Kubernetes environments.
+
+Your role is to assess operational health, identify signs of instability, and provide safe, practical guidance to improve system condition. You are not a blind automation bot. You are an evidence-driven operational analyst and remediation advisor.
+
+# Core Mission
+
+Assess the health of a Linux host that is part of a Kubernetes environment and identify:
+
+- stale, orphaned, zombie, or hung processes
+- unusually large memory allocations
+- memory pressure, swap pressure, OOM risk, and recent OOM events
+- CPU saturation, load anomalies, run queue pressure, and noisy neighbors
+- disk pressure, inode exhaustion, abnormal filesystem growth, log bloat
+- network instability or suspicious connection states
+- kubelet, container runtime, cgroup, and node-level instability indicators
+- pod or container restart patterns that suggest host or workload issues
+- operational drift, resource leaks, or signs of degraded node hygiene
+
+Then produce:
+
+1. a concise health assessment
+2. prioritized findings with severity
+3. likely causes and interpretation
+4. recommended next actions
+5. safe cleanup or stabilization options
+6. explicit warnings before any potentially disruptive action
+
+# Operating Context
+
+Assume:
+- Linux host
+- Kubernetes worker or control-plane host
+- container runtime may be containerd or CRI-O
+- systemd is likely present
+- shell tools may include: ps, top, free, vmstat, iostat, ss, journalctl, systemctl, dmesg, df, du, lsof, crictl, ctr, kubectl, uname, cat, awk, sed, grep
+- you may need to reason across OS-level state and Kubernetes-level state
+
+# Principles
+
+- Safety first
+- Observe before acting
+- Prefer explanation over impulsive cleanup
+- Never kill, restart, drain, delete, evict, or modify anything unless explicitly instructed
+- Distinguish clearly between:
+  - observation
+  - diagnosis
+  - recommendation
+  - action proposal
+- Be skeptical of first impressions; cross-check evidence
+- Prefer minimally disruptive remediation
+- Identify uncertainty explicitly
+- When in doubt, recommend further inspection rather than risky intervention
+
+# What Good Output Looks Like
+
+Your output must be structured and operationally useful.
+
+Always provide these sections:
+
+## 1. Executive Summary
+A short summary of node health and the main operational risks.
+
+## 2. Health Status
+Use one of:
+- Healthy
+- Watch
+- Degraded
+- Critical
+
+Also provide a confidence level:
+- Low
+- Medium
+- High
+
+## 3. Findings
+For each finding include:
+- Title
+- Severity: Info / Low / Medium / High / Critical
+- Evidence
+- Why it matters
+- Likely cause
+- Recommended next step
+
+## 4. Immediate Safe Actions
+Only non-destructive actions unless explicitly authorized.
+
+## 5. Escalation or Risk Notes
+Mention if application owners, cluster admins, or incident response should be involved.
+
+## 6. Suggested Commands
+Provide commands for verification and safe inspection first.
+Only provide cleanup or kill commands as clearly labeled optional actions.
+
+# Specific Assessment Areas
+
+When assessing a host, examine as many of the following as available.
+
+## OS and Node Baseline
+- hostname
+- uptime
+- kernel version
+- load average
+- CPU core count
+- memory totals
+- swap totals
+- mount usage
+- current time and timezone if relevant for logs
+
+## Process Hygiene
+Look for:
+- zombie processes
+- D-state or uninterruptible sleep processes
+- long-running suspicious processes
+- processes consuming excessive RSS or VSZ
+- processes with abnormal FD counts
+- high thread counts
+- orphaned children
+- user sessions or shells left behind
+- stale maintenance scripts, port-forwards, debug sessions, rsync, backup, or scan jobs
+
+## Memory Health
+Check for:
+- low available memory
+- high slab growth
+- page cache pressure
+- swap churn
+- major page faults
+- recent OOM kills
+- cgroup memory pressure
+- memory leaks in kubelet, runtime, sidecars, or applications
+- containers whose memory use is inconsistent with limits/requests
+
+## CPU and Scheduler Health
+Check for:
+- sustained high load
+- low idle CPU
+- CPU steal if visible
+- run queue pressure
+- single-thread hotspots
+- stuck kernel threads
+- aggressive background tasks or compression tasks
+- processes spinning unexpectedly
+
+## Disk and Filesystem Health
+Check for:
+- low free space
+- inode exhaustion
+- large log files
+- rapidly growing directories
+- abandoned temp files
+- container image accumulation
+- dead volume mounts
+- overlay filesystem growth
+- kubelet directories consuming space
+- journald growth
+
+## Network and Connection State
+Check for:
+- excessive ESTABLISHED, TIME_WAIT, CLOSE_WAIT, SYN_RECV
+- suspicious open listeners
+- unresolved DNS symptoms if evident
+- failed kubelet/runtime API connectivity
+- API server reachability symptoms if visible
+- long-lived unexpected tunnels or forwards
+
+## Kubernetes Node Health
+If kubectl access is available, inspect:
+- node Ready status
+- conditions: MemoryPressure, DiskPressure, PIDPressure, NetworkUnavailable
+- recent events on the node
+- top pods by CPU and memory
+- restarting pods
+- crashlooping workloads
+- daemonset health
+- pods pinned to node causing pressure
+- node cordon/drain history if visible
+
+## Runtime and Control Services
+Inspect status and recent logs for:
+- kubelet
+- container runtime
+- node-exporter or monitoring agents if present
+- CNI components if local visibility exists
+
+Look for:
+- repeated restarts
+- API timeout errors
+- cgroup issues
+- image GC failures
+- pod sandbox creation failures
+- PLEG issues
+- disk or inode manager warnings
+
+# Diagnostic Style
+
+When you interpret evidence:
+- separate symptom from cause
+- do not overstate certainty
+- explicitly call out whether an issue is:
+  - host-level
+  - container-level
+  - workload-level
+  - cluster-level
+  - uncertain / cross-layer
+
+When several causes are possible, rank them.
+
+# Safety Rules
+
+Never perform or recommend as a default:
+- kill -9 on broad process sets
+- rm -rf on system or kubelet directories
+- deleting container images blindly
+- restarting kubelet or container runtime without noting impact
+- draining or cordoning nodes without explaining implications
+- deleting pods without checking controller ownership and service impact
+- clearing logs blindly
+- dropping caches unless explicitly justified and authorized
+
+If cleanup is needed, prefer:
+- inspect first
+- estimate impact
+- identify ownership
+- recommend reversible or bounded steps
+- state rollback considerations where applicable
+
+# Guidance Style
+
+Your guidance should be:
+- concise but technically solid
+- actionable
+- prioritized
+- explicit about risk
+
+Prefer wording like:
+- "Evidence suggests…"
+- "Most likely…"
+- "Before acting, verify…"
+- "Low-risk next step…"
+- "Potentially disruptive action…"
+- "Do not do this unless…"
+
+# Command Strategy
+
+When suggesting commands, use phases:
+
+## Phase 1 – Safe Inspection
+Read-only inspection commands.
+
+## Phase 2 – Focused Verification
+Commands to confirm or disprove likely causes.
+
+## Phase 3 – Optional Remediation
+Clearly marked commands that may alter system state.
+
+Prefer common Linux/Kubernetes commands and explain what each is for.
+
+# Expected Inputs
+
+You may receive:
+- raw command output
+- copied logs
+- kubectl output
+- descriptions of symptoms
+- process lists
+- memory or disk reports
+- journald excerpts
+
+Work with what is available and say what is missing.
+
+# Response Constraints
+
+- Do not invent evidence
+- Do not assume root access unless stated
+- Do not assume kubectl access unless stated
+- Do not assume that high memory usage is bad unless pressure or leak symptoms are present
+- Do not assume old processes are stale without contextual clues
+- Do not treat cache as a leak by default
+- Do not recommend aggressive cleanup merely because resources are non-zero
+
+# Optional Heuristics
+
+Use heuristics such as:
+- zombie count > 0 is noteworthy
+- D-state tasks deserve attention
+- repeated OOM kills are high severity
+- memory available trending very low plus reclaim pressure is serious
+- CLOSE_WAIT accumulation suggests application/socket cleanup issues
+- inode pressure is often missed and operationally important
+- frequent restarts plus node pressure may point to host instability
+- kubelet and runtime log repetition often reveals the real fault line
+
+# Default Task
+
+When invoked, begin by determining the current operational picture and producing a node health assessment focused on:
+- stale or abnormal processes
+- excessive memory consumers
+- resource pressure
+- signs of instability
+- safe guidance for stabilization
+
+If a structured assessment is requested, use the k3s-node-health-assessment protocol
+(`agents/protocols/sys-medic/k3s-node-health-assessment.md`) if available. The protocol
+provides a step-by-step procedure covering OS baseline, process hygiene, memory, CPU,
+disk, network, Kubernetes node state, and k3s runtime health.
+
+If insufficient evidence is available, state exactly which safe inspection commands should be run next.
+
+---
+
+# Memory Template Extensions
+
+sys-medic's memory file (`.kaizen/agents/sys-medic/memory.md`) extends the base template
+(ADR-002) with three additional sections:
+
+```markdown
+## Node Profiles
+<!-- Per-node operational baseline established over sessions -->
+<!-- hostname | typical load | known quirks | last assessment date -->
+
+## Recurring Findings
+<!-- Issues seen more than once: pattern · first seen · frequency -->
+
+## Cleared Issues
+<!-- Issues that were resolved: what was done · when · outcome -->
+```
+
+These sections are maintained by the session-close protocol above.
+
+---
+
+# Related Documents
+
+- **Protocol runbook:** `agents/protocols/sys-medic/k3s-node-health-assessment.md`
+- **Memory convention:** `docs/adr/ADR-002-project-memory-convention.md`
+- **Protocols convention:** `docs/adr/ADR-003-protocols-artifact-convention.md`
+- **Agency framework:** `docs/agency-framework.md`

src/kaizen_agentic/data/agents/agent-tdd-workflow.md

@@ -1,6 +1,22 @@
 ---
-name: tddai-assistant
+name: tdd-workflow
 description: Expert guidance for the TDD8 workflow methodology, specializing in the comprehensive ISSUE-TEST-RED-GREEN-REFACTOR-DOCUMENT-REFINE-PUBLISH cycle with sophisticated sidequest management and proper test organization.
+category: development-process
+memory: enabled
+metrics:
+  primary:
+    name: test_pass_rate
+    description: Share of acceptance-criteria tests passing at PUBLISH
+    measurement: passing_tests / total_tests for the active issue workspace
+    target: 1.0
+  secondary:
+    - name: cycle_time_s
+      description: Wall-clock time from ISSUE start to PUBLISH
+      measurement: Session duration in seconds (execution_time_s in ADR-004)
+  collection:
+    frequency: per_execution
+    storage: .kaizen/metrics/tdd-workflow/
+    retention: 180d
 ---
 
 # TDDAi Assistant Agent
@@ -356,3 +372,35 @@ Remember: The goal is to build software incrementally using the proven TDD8 cycl
 **ISSUE-TEST-RED-GREEN-REFACTOR-DOCUMENT-REFINE-PUBLISH**
 
 The comprehensive 8-step development methodology that transforms requirements into production-ready, well-tested, documented functionality while maintaining code quality and project momentum through intelligent sidequest management.
+
+---
+
+## Session Start
+
+1. Check for `.kaizen/agents/tdd-workflow/memory.md` in the project root.
+2. If present, read it — pay attention to `## Watch Points` (recurring test pitfalls) and `## What Worked` (effective patterns for this project).
+3. If absent, offer to initialise with `kaizen-agentic memory init tdd-workflow`.
+
+## Session Close
+
+1. Update `## Accumulated Findings` with any new TDD patterns or recurring failure modes observed.
+2. Update `## What Worked` and `## Watch Points` as needed.
+3. Append one line to `## Session Log`: `YYYY-MM-DD · <issue or feature> · <outcome>`.
+4. Bump `last_updated` to today and increment `session_count`.
+5. Record session metrics (ADR-004; adjust values to match outcome):
+
+```bash
+# Successful PUBLISH — all acceptance tests green:
+echo '{"success": true, "execution_time_s": <seconds>, "quality_score": 0.9, "primary_metric": {"name": "test_pass_rate", "value": 1.0, "target": 1.0}, "metadata": {"issue": "<NUM>", "phase": "PUBLISH"}}' \
+  | kaizen-agentic metrics record tdd-workflow --json --idempotency-key <session-id>
+
+# Incomplete or failed cycle:
+echo '{"success": false, "execution_time_s": <seconds>, "quality_score": 0.4, "primary_metric": {"name": "test_pass_rate", "value": <rate>, "target": 1.0}, "metadata": {"issue": "<NUM>", "phase": "<last-phase>"}}' \
+  | kaizen-agentic metrics record tdd-workflow --json --idempotency-key <session-id>
+```
+
+Shorthand when only outcome and duration matter:
+
+```bash
+kaizen-agentic metrics record tdd-workflow --success --time <seconds> --quality <0.0-1.0>
+```

src/kaizen_agentic/extensions.py

@@ -438,7 +438,10 @@ version: {extension.version}
         agent_content += "---\n\n"
         agent_content += f"# {extension.name}\n\n"
         agent_content += f"{extension.description}\n\n"
-        agent_content += f"This agent extends **{extension.base_agent}** with project-specific functionality.\n\n"
+        agent_content += (
+            f"This agent extends **{extension.base_agent}** "
+            f"with project-specific functionality.\n\n"
+        )
 
         if extension.configuration.get("custom_instructions"):
             agent_content += "## Custom Instructions\n\n"

src/kaizen_agentic/installer.py

@@ -47,16 +47,16 @@ class AgentInstaller:
         if config.create_backup and agents_dir.exists():
             self._create_backup(agents_dir)
 
-        # Install each agent
+        # Install each agent (copy by path — avoids parsing unrelated agents)
         for agent_name in resolved_agents:
             try:
-                agent = self.registry.get_agent(agent_name)
-                if not agent:
+                source_path = self.registry.get_agent_path(agent_name)
+                if not source_path:
                     results[agent_name] = "ERROR: Agent not found"
                     continue
 
                 target_path = agents_dir / f"agent-{agent_name}.md"
-                shutil.copy2(agent.file_path, target_path)
+                shutil.copy2(source_path, target_path)
                 results[agent_name] = "INSTALLED"
 
             except Exception as e:
@@ -520,106 +520,61 @@ __version__ = "0.1.0"
     def _create_makefile(self, project_dir: Path, project_name: str):
         """Create Makefile with standard targets."""
         package_name = project_name.replace("-", "_")
-        makefile_content = f"""# {project_name} - Makefile for development workflow
-# Generated by Kaizen Agentic
-
-.PHONY: help setup-complete setup-python setup-tools test lint format clean agents-status agents-update
-
-# Default target
-help:
-	@echo "Available targets:"
-	@echo "  setup-complete  - Complete development environment setup"
-	@echo "  setup-python    - Set up Python virtual environment and dependencies"
-	@echo "  setup-tools     - Install development tools"
-	@echo "  test           - Run test suite"
-	@echo "  lint           - Run code quality checks"
-	@echo "  format         - Format code with black"
-	@echo "  clean          - Clean build artifacts"
-	@echo "  agents-status  - Show installed agents status"
-	@echo "  agents-update  - Update agents to latest versions"
-
-# Virtual environment detection
-VENV := .venv
-PYTHON := $(VENV)/bin/python
-PIP := $(VENV)/bin/pip
-
-# Complete setup
-setup-complete: setup-python setup-tools
-	@echo "✅ Development environment setup complete!"
-	@echo "Next steps:"
-	@echo "  source $(VENV)/bin/activate  # Activate virtual environment"
-	@echo "  make test                    # Run tests"
-	@echo "  make lint                    # Check code quality"
-
-# Python environment setup
-setup-python: $(VENV)/bin/activate
-
-$(VENV)/bin/activate: pyproject.toml
-	python3 -m venv $(VENV)
-	$(PIP) install --upgrade pip
-	$(PIP) install -e ".[dev]"
-	touch $(VENV)/bin/activate
-
-# Development tools setup
-setup-tools: $(VENV)/bin/activate
-	@echo "Development tools installed via pyproject.toml"
-
-# Testing
-test: $(VENV)/bin/activate
-	$(PYTHON) -m pytest tests/ -v
-
-test-coverage: $(VENV)/bin/activate
-	$(PYTHON) -m pytest tests/ --cov=src/{package_name} --cov-report=html --cov-report=term-missing
-
-# Code quality
-lint: $(VENV)/bin/activate
-	$(PYTHON) -m flake8 src/ tests/
-	$(PYTHON) -m mypy src/
-
-format: $(VENV)/bin/activate
-	$(PYTHON) -m black src/ tests/
-
-format-check: $(VENV)/bin/activate
-	$(PYTHON) -m black --check src/ tests/
-
-# Cleanup
-clean:
-	rm -rf build/
-	rm -rf dist/
-	rm -rf *.egg-info/
-	rm -rf .pytest_cache/
-	rm -rf .coverage
-	rm -rf htmlcov/
-	find . -type d -name __pycache__ -exec rm -rf {{}} +
-	find . -type f -name "*.pyc" -delete
-
-# Agent management
-agents-status:
-	@if command -v kaizen-agentic >/dev/null 2>&1; then \\
-		kaizen-agentic status; \\
-	else \\
-		echo "kaizen-agentic not found. Install with: pip install kaizen-agentic"; \\
-	fi
-
-agents-update:
-	@if command -v kaizen-agentic >/dev/null 2>&1; then \\
-		kaizen-agentic update; \\
-	else \\
-		echo "kaizen-agentic not found. Install with: pip install kaizen-agentic"; \\
-	fi
-
-agents-list:
-	@if command -v kaizen-agentic >/dev/null 2>&1; then \\
-		kaizen-agentic list; \\
-	else \\
-		echo "kaizen-agentic not found. Install with: pip install kaizen-agentic"; \\
-	fi
-
-agents-validate:
-	@if command -v kaizen-agentic >/dev/null 2>&1; then \\
-		kaizen-agentic validate; \\
-	else \\
-		echo "kaizen-agentic not found. Install with: pip install kaizen-agentic"; \\
-	fi
-"""
-        (project_dir / "Makefile").write_text(makefile_content)
+        tab = "\t"
+        lines = [
+            f"# {project_name} - Makefile for development workflow",
+            "# Generated by Kaizen Agentic",
+            "",
+            ".PHONY: help setup-complete setup-python setup-tools test lint "
+            "format clean agents-status agents-update",
+            "",
+            "help:",
+            f'{tab}@echo "Available targets:"',
+            f'{tab}@echo "  setup-complete  - Complete development environment setup"',
+            f'{tab}@echo "  setup-python    - Set up Python virtual environment"',
+            f'{tab}@echo "  test           - Run test suite"',
+            f'{tab}@echo "  agents-status  - Show installed agents status"',
+            "",
+            "VENV := .venv",
+            "PYTHON := $(VENV)/bin/python",
+            "PIP := $(VENV)/bin/pip",
+            "",
+            "setup-complete: setup-python setup-tools",
+            f'{tab}@echo "Development environment setup complete"',
+            "",
+            "setup-python: $(VENV)/bin/activate",
+            "",
+            "$(VENV)/bin/activate: pyproject.toml",
+            f"{tab}python3 -m venv $(VENV)",
+            f"{tab}$(PIP) install --upgrade pip",
+            f'{tab}$(PIP) install -e ".[dev]"',
+            f"{tab}touch $(VENV)/bin/activate",
+            "",
+            "setup-tools: $(VENV)/bin/activate",
+            f'{tab}@echo "Development tools installed via pyproject.toml"',
+            "",
+            "test: $(VENV)/bin/activate",
+            f"{tab}$(PYTHON) -m pytest tests/ -v",
+            "",
+            "test-coverage: $(VENV)/bin/activate",
+            f"{tab}$(PYTHON) -m pytest tests/ --cov=src/{package_name} "
+            f"--cov-report=html --cov-report=term-missing",
+            "",
+            "lint: $(VENV)/bin/activate",
+            f"{tab}$(PYTHON) -m flake8 src/ tests/",
+            "",
+            "format: $(VENV)/bin/activate",
+            f"{tab}$(PYTHON) -m black src/ tests/",
+            "",
+            "clean:",
+            f"{tab}rm -rf build/ dist/ *.egg-info/ .pytest_cache/ .coverage htmlcov/",
+            "",
+            "agents-status:",
+            f"{tab}@command -v kaizen-agentic >/dev/null 2>&1 && kaizen-agentic status "
+            f'|| echo "kaizen-agentic not installed"',
+            "",
+            "agents-update:",
+            f"{tab}@command -v kaizen-agentic >/dev/null 2>&1 && kaizen-agentic update "
+            f'|| echo "kaizen-agentic not installed"',
+        ]
+        (project_dir / "Makefile").write_text("\n".join(lines) + "\n")

src/kaizen_agentic/integrations/__init__.py

@@ -0,0 +1,10 @@
+"""Ecosystem integration adapters (Helix Forge, artifact-store)."""
+
+from .artifact_store import publish_optimizer_evidence
+from .helix import HelixCorrelationAdapter, enrich_helix_correlation
+
+__all__ = [
+    "HelixCorrelationAdapter",
+    "enrich_helix_correlation",
+    "publish_optimizer_evidence",
+]

src/kaizen_agentic/integrations/artifact_store.py

@@ -0,0 +1,233 @@
+"""artifact-store publish adapter for optimizer evidence (WP-0004 Part 3)."""
+
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from urllib import error, parse, request
+
+from ..metrics import OptimizerStore
+
+ENV_API_URL = "ARTIFACTSTORE_API_URL"
+ENV_API_TOKEN = "ARTIFACTSTORE_API_TOKEN"
+DEFAULT_RETENTION_CLASS = "raw-evidence"
+PRODUCER = "kaizen-agentic"
+
+
+@dataclass
+class PublishResult:
+    package_id: str
+    manifest_digest: Optional[str]
+    files_uploaded: int
+    retention_class: str
+
+
+def build_optimizer_manifest(
+    project_root: Path,
+    *,
+    agents: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    """Manifest metadata for an optimizer evidence package."""
+    store = OptimizerStore(project_root)
+    analysis = {}
+    if store.analysis_path.exists():
+        analysis = json.loads(store.analysis_path.read_text(encoding="utf-8"))
+
+    return {
+        "schema": "kaizen-agentic/optimizer-evidence/v1",
+        "project": project_root.name,
+        "project_root": str(project_root.resolve()),
+        "producer": PRODUCER,
+        "retention_class": DEFAULT_RETENTION_CLASS,
+        "retention_days": 180,
+        "optimized_at": analysis.get("optimized_at"),
+        "agents": agents or [item.get("agent") for item in analysis.get("agents", [])],
+        "files": [
+            "optimizer/analysis.json",
+            "optimizer/recommendations.jsonl",
+        ],
+    }
+
+
+def publish_optimizer_evidence(
+    project_root: Path,
+    *,
+    api_url: str,
+    token: str,
+    subject: Optional[str] = None,
+    retention_class: str = DEFAULT_RETENTION_CLASS,
+) -> PublishResult:
+    """Register optimizer outputs as an artifact-store package."""
+    store = OptimizerStore(project_root)
+    if not store.analysis_path.exists():
+        raise FileNotFoundError(
+            f"No optimizer analysis at {store.analysis_path}. "
+            "Run: kaizen-agentic metrics optimize"
+        )
+
+    manifest = build_optimizer_manifest(project_root)
+    package_name = f"kaizen-optimizer-{project_root.name}"
+    package_subject = subject or project_root.name
+
+    created = _http_json(
+        "POST",
+        api_url,
+        "/packages",
+        token,
+        {
+            "name": package_name,
+            "producer": PRODUCER,
+            "subject": package_subject,
+            "retention_class": retention_class,
+            "metadata": manifest,
+        },
+    )
+    package_id = created["id"]
+
+    uploads = [
+        (
+            store.analysis_path,
+            "optimizer/analysis.json",
+            "application/json",
+        ),
+    ]
+    if store.recommendations_path.exists():
+        uploads.append(
+            (
+                store.recommendations_path,
+                "optimizer/recommendations.jsonl",
+                "application/x-ndjson",
+            )
+        )
+
+    for path, relative_path, media_type in uploads:
+        _http_multipart(
+            api_url,
+            f"/packages/{package_id}/files",
+            token,
+            fields={"relative_path": relative_path, "media_type": media_type},
+            file_field="file",
+            file_name=path.name,
+            file_content_type=media_type,
+            file_bytes=path.read_bytes(),
+        )
+
+    finalized = _http_json(
+        "POST",
+        api_url,
+        f"/packages/{package_id}/finalize",
+        token,
+        {},
+    )
+
+    return PublishResult(
+        package_id=package_id,
+        manifest_digest=finalized.get("manifest_digest"),
+        files_uploaded=len(uploads),
+        retention_class=retention_class,
+    )
+
+
+def default_api_url() -> str:
+    return os.environ.get(ENV_API_URL, "http://127.0.0.1:8000").rstrip("/")
+
+
+def default_api_token() -> str:
+    return os.environ.get(ENV_API_TOKEN, "")
+
+
+def _http_json(
+    method: str,
+    base_url: str,
+    path: str,
+    token: str,
+    payload: Dict[str, Any],
+) -> Dict[str, Any]:
+    body = json.dumps(payload).encode("utf-8") if payload else None
+    headers = {"Accept": "application/json"}
+    if body is not None:
+        headers["Content-Type"] = "application/json"
+    response = _http_bytes(method, base_url, path, token, body=body, headers=headers)
+    decoded = json.loads(response)
+    if not isinstance(decoded, dict):
+        raise ValueError(f"expected JSON object from {path}")
+    return decoded
+
+
+def _http_multipart(
+    base_url: str,
+    path: str,
+    token: str,
+    *,
+    fields: Dict[str, str],
+    file_field: str,
+    file_name: str,
+    file_content_type: str,
+    file_bytes: bytes,
+) -> Dict[str, Any]:
+    boundary = f"kaizen-{uuid.uuid4().hex}"
+    body = bytearray()
+    for name, value in fields.items():
+        body.extend(f"--{boundary}\r\n".encode("ascii"))
+        body.extend(
+            f'Content-Disposition: form-data; name="{_quote(name)}"\r\n\r\n'.encode()
+        )
+        body.extend(value.encode())
+        body.extend(b"\r\n")
+    body.extend(f"--{boundary}\r\n".encode("ascii"))
+    body.extend(
+        (
+            f'Content-Disposition: form-data; name="{_quote(file_field)}"; '
+            f'filename="{_quote(file_name)}"\r\n'
+            f"Content-Type: {file_content_type}\r\n\r\n"
+        ).encode()
+    )
+    body.extend(file_bytes)
+    body.extend(b"\r\n")
+    body.extend(f"--{boundary}--\r\n".encode("ascii"))
+
+    response = _http_bytes(
+        "POST",
+        base_url,
+        path,
+        token,
+        body=bytes(body),
+        headers={
+            "Content-Type": f"multipart/form-data; boundary={boundary}",
+            "Accept": "application/json",
+        },
+    )
+    decoded = json.loads(response)
+    if not isinstance(decoded, dict):
+        raise ValueError(f"expected JSON object from {path}")
+    return decoded
+
+
+def _http_bytes(
+    method: str,
+    base_url: str,
+    path: str,
+    token: str,
+    *,
+    body: Optional[bytes] = None,
+    headers: Optional[Dict[str, str]] = None,
+) -> bytes:
+    url = f"{base_url.rstrip('/')}/{path.lstrip('/')}"
+    effective_headers = dict(headers or {})
+    if token:
+        effective_headers["Authorization"] = f"Bearer {token}"
+    req = request.Request(url, data=body, headers=effective_headers, method=method)
+    try:
+        with request.urlopen(req, timeout=30) as resp:
+            return resp.read()
+    except error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"HTTP {exc.code} from {path}: {detail}") from exc
+
+
+def _quote(value: str) -> str:
+    return parse.quote(value, safe="")

src/kaizen_agentic/integrations/helix.py

@@ -0,0 +1,170 @@
+"""Helix Forge correlation adapter (ADR-004, agentic-resources)."""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+ENV_SESSION_UID = "HELIX_SESSION_UID"
+ENV_REPO = "HELIX_REPO"
+ENV_FLAVOR = "HELIX_FLAVOR"
+ENV_TOKENS = "HELIX_TOKENS"
+ENV_INFRA_SHARE = "HELIX_INFRA_OVERHEAD_SHARE"
+ENV_STORE_DB = "HELIX_STORE_DB"
+
+
+def enrich_helix_correlation(record: Dict[str, Any]) -> Dict[str, Any]:
+    """Apply optional Helix correlation fields from env or existing record."""
+    payload = dict(record)
+
+    uid = payload.get("helix_session_uid") or os.environ.get(ENV_SESSION_UID)
+    if uid:
+        payload["helix_session_uid"] = uid
+
+    repo = payload.get("repo") or os.environ.get(ENV_REPO)
+    if repo:
+        payload["repo"] = repo
+
+    flavor = payload.get("flavor") or os.environ.get(ENV_FLAVOR)
+    if flavor:
+        payload["flavor"] = flavor
+
+    tokens_raw = payload.get("tokens")
+    if tokens_raw is None and ENV_TOKENS in os.environ:
+        try:
+            tokens_raw = int(os.environ[ENV_TOKENS])
+        except ValueError:
+            pass
+    if tokens_raw is not None:
+        payload["tokens"] = int(tokens_raw)
+
+    infra = payload.get("infra_overhead_share")
+    if infra is None and ENV_INFRA_SHARE in os.environ:
+        try:
+            infra = float(os.environ[ENV_INFRA_SHARE])
+        except ValueError:
+            pass
+    if infra is not None:
+        payload["infra_overhead_share"] = float(infra)
+
+    return payload
+
+
+def digest_to_correlation_summary(
+    session_uid: str,
+    digest: Dict[str, Any],
+    *,
+    adapter: str,
+) -> Dict[str, Any]:
+    """Project a Helix digest into ADR-004 correlation summary fields."""
+    cost = digest.get("cost") or {}
+    input_tokens = int(cost.get("input_tokens") or 0)
+    output_tokens = int(cost.get("output_tokens") or 0)
+    wall_clock_s = cost.get("wall_clock_s")
+
+    summary: Dict[str, Any] = {
+        "helix_session_uid": session_uid,
+        "repo": digest.get("repo"),
+        "flavor": digest.get("flavor"),
+        "fleet_outcome": digest.get("outcome"),
+        "tokens": input_tokens + output_tokens,
+        "adapter": adapter,
+    }
+    if wall_clock_s is not None:
+        summary["wall_clock_s"] = float(wall_clock_s)
+
+    markers = digest.get("markers") or {}
+    tool_histogram = digest.get("tool_histogram") or {}
+    mcp_calls = sum(
+        count for tool, count in tool_histogram.items() if str(tool).startswith("mcp__")
+    )
+    total_calls = sum(tool_histogram.values()) or 0
+    if total_calls:
+        summary["infra_overhead_share"] = round(mcp_calls / total_calls, 3)
+    elif "infra_overhead_share" in digest:
+        summary["infra_overhead_share"] = digest["infra_overhead_share"]
+
+    if markers:
+        summary["markers"] = {
+            key: markers[key]
+            for key in ("errors", "retries", "test_runs")
+            if key in markers
+        }
+
+    return summary
+
+
+@dataclass
+class HelixCorrelationAdapter:
+    """Read-only lookup of Helix Forge session digests."""
+
+    store_db: Optional[Path] = None
+
+    @classmethod
+    def from_env(cls) -> "HelixCorrelationAdapter":
+        raw = os.environ.get(ENV_STORE_DB)
+        return cls(store_db=Path(raw).resolve() if raw else None)
+
+    def lookup(self, session_uid: str) -> Dict[str, Any]:
+        if self.store_db and self.store_db.exists():
+            digest = self._load_digest_sqlite(session_uid)
+            if digest is not None:
+                return digest_to_correlation_summary(
+                    session_uid,
+                    digest,
+                    adapter="helix-sqlite",
+                )
+            return {
+                "helix_session_uid": session_uid,
+                "adapter": "helix-sqlite",
+                "status": "not_found",
+                "message": f"No digest for session_uid in {self.store_db}",
+            }
+
+        return {
+            "helix_session_uid": session_uid,
+            "adapter": "stub",
+            "status": "not_configured",
+            "message": (
+                "Set HELIX_STORE_DB to an agentic-resources session-memory SQLite "
+                "database for live lookup. Correlation fields on project metrics "
+                "still work via HELIX_SESSION_UID at record time."
+            ),
+            "expected_fields": [
+                "helix_session_uid",
+                "repo",
+                "flavor",
+                "tokens",
+                "infra_overhead_share",
+                "fleet_outcome",
+                "wall_clock_s",
+            ],
+        }
+
+    def _load_digest_sqlite(self, session_uid: str) -> Optional[Dict[str, Any]]:
+        conn = sqlite3.connect(str(self.store_db))
+        try:
+            row = conn.execute(
+                "SELECT json FROM digests WHERE session_uid = ?",
+                (session_uid,),
+            ).fetchone()
+            if not row:
+                return None
+            digest = json.loads(row[0])
+            digest.setdefault("session_uid", session_uid)
+
+            session_row = conn.execute(
+                "SELECT json FROM sessions WHERE session_uid = ?",
+                (session_uid,),
+            ).fetchone()
+            if session_row:
+                session = json.loads(session_row[0])
+                digest.setdefault("repo", session.get("repo"))
+                digest.setdefault("flavor", session.get("flavor"))
+            return digest
+        finally:
+            conn.close()

src/kaizen_agentic/metrics.py

@@ -0,0 +1,278 @@
+"""Project-scoped agent metrics storage (ADR-004)."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+DEFAULT_RETENTION_DAYS = 180
+
+
+def _utc_now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _parse_timestamp(value: str) -> datetime:
+    normalized = value.replace("Z", "+00:00")
+    return datetime.fromisoformat(normalized)
+
+
+_TREND_ARROWS = {"up": "↑", "down": "↓", "stable": "→", "unknown": "?"}
+
+
+def performance_summary_markdown(summary: Dict[str, Any]) -> str:
+    """Format ADR-004 summary.json as a Coach brief markdown section."""
+    if not summary or summary.get("execution_count", 0) == 0:
+        return ""
+
+    trend = summary.get("trend", {})
+    success_trend = trend.get("success_rate", "unknown")
+    quality_trend = trend.get("quality_score", "unknown")
+
+    lines = [
+        "## Performance Summary",
+        "",
+        f"- Executions: {summary['execution_count']}",
+        (
+            f"- Success rate: {summary['success_rate']:.1%} "
+            f"({_TREND_ARROWS.get(success_trend, '?')} {success_trend})"
+        ),
+        f"- Avg quality: {summary['avg_quality_score']:.2f} "
+        f"({_TREND_ARROWS.get(quality_trend, '?')} {quality_trend})",
+        f"- Avg execution time: {summary['avg_execution_time_s']:.1f}s",
+    ]
+    if summary.get("last_execution"):
+        lines.append(f"- Last execution: {summary['last_execution']}")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _trend_direction(recent: List[float], prior: List[float]) -> str:
+    if not recent:
+        return "unknown"
+    if not prior:
+        return "stable"
+    recent_avg = sum(recent) / len(recent)
+    prior_avg = sum(prior) / len(prior)
+    delta = recent_avg - prior_avg
+    if abs(delta) < 0.05:
+        return "stable"
+    return "up" if delta > 0 else "down"
+
+
+@dataclass
+class MetricsStore:
+    """Append-only per-agent execution metrics under .kaizen/metrics/."""
+
+    project_root: Path
+    agent_name: str
+    retention_days: int = DEFAULT_RETENTION_DAYS
+
+    def __post_init__(self) -> None:
+        self.project_root = Path(self.project_root).resolve()
+        self.agent_dir = self.project_root / ".kaizen" / "metrics" / self.agent_name
+        self.executions_path = self.agent_dir / "executions.jsonl"
+        self.summary_path = self.agent_dir / "summary.json"
+
+    @classmethod
+    def list_agents(cls, project_root: Path) -> List[str]:
+        metrics_root = Path(project_root).resolve() / ".kaizen" / "metrics"
+        if not metrics_root.exists():
+            return []
+        agents = []
+        for child in sorted(metrics_root.iterdir()):
+            if child.is_dir() and (child / "executions.jsonl").exists():
+                agents.append(child.name)
+        return agents
+
+    def scaffold(self) -> Path:
+        """Create metrics directory for this agent."""
+        self.agent_dir.mkdir(parents=True, exist_ok=True)
+        if not self.executions_path.exists():
+            self.executions_path.write_text("", encoding="utf-8")
+        return self.agent_dir
+
+    def append(
+        self,
+        record: Dict[str, Any],
+        *,
+        idempotency_key: Optional[str] = None,
+    ) -> bool:
+        """Append an execution record. Returns False if idempotency_key duplicates."""
+        self.scaffold()
+
+        payload = dict(record)
+        payload.setdefault("agent", self.agent_name)
+        payload.setdefault("timestamp", _utc_now_iso())
+
+        if idempotency_key is not None:
+            if self._has_idempotency_key(idempotency_key):
+                return False
+            payload["idempotency_key"] = idempotency_key
+
+        if "success" not in payload:
+            raise ValueError("execution record requires 'success' field")
+
+        with self.executions_path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(payload, sort_keys=True))
+            handle.write("\n")
+
+        self.prune()
+        self.write_summary()
+        return True
+
+    def read_executions(self) -> List[Dict[str, Any]]:
+        if not self.executions_path.exists():
+            return []
+        records: List[Dict[str, Any]] = []
+        with self.executions_path.open(encoding="utf-8") as handle:
+            for line in handle:
+                line = line.strip()
+                if line:
+                    records.append(json.loads(line))
+        return records
+
+    def summarise(self) -> Dict[str, Any]:
+        records = self.read_executions()
+        if not records:
+            return {
+                "agent": self.agent_name,
+                "execution_count": 0,
+                "success_rate": 0.0,
+                "avg_quality_score": 0.0,
+                "avg_execution_time_s": 0.0,
+                "last_execution": None,
+                "trend": {
+                    "success_rate": "unknown",
+                    "quality_score": "unknown",
+                },
+            }
+
+        successes = [bool(r["success"]) for r in records]
+        success_rate = sum(successes) / len(successes)
+
+        quality_scores = [
+            float(r["quality_score"])
+            for r in records
+            if r.get("quality_score") is not None
+        ]
+        execution_times = [
+            float(r["execution_time_s"])
+            for r in records
+            if r.get("execution_time_s") is not None
+        ]
+
+        window = 5
+        recent_success = [1.0 if s else 0.0 for s in successes[-window:]]
+        prior_success = [1.0 if s else 0.0 for s in successes[:-window][-window:]]
+        recent_quality = quality_scores[-window:]
+        prior_quality = (
+            quality_scores[:-window][-window:] if len(quality_scores) > window else []
+        )
+
+        return {
+            "agent": self.agent_name,
+            "execution_count": len(records),
+            "success_rate": round(success_rate, 3),
+            "avg_quality_score": round(
+                sum(quality_scores) / len(quality_scores) if quality_scores else 0.0,
+                3,
+            ),
+            "avg_execution_time_s": round(
+                sum(execution_times) / len(execution_times) if execution_times else 0.0,
+                3,
+            ),
+            "last_execution": records[-1]["timestamp"],
+            "trend": {
+                "success_rate": _trend_direction(recent_success, prior_success),
+                "quality_score": _trend_direction(recent_quality, prior_quality),
+            },
+        }
+
+    def write_summary(self) -> Dict[str, Any]:
+        summary = self.summarise()
+        self.agent_dir.mkdir(parents=True, exist_ok=True)
+        self.summary_path.write_text(
+            json.dumps(summary, indent=2, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+        return summary
+
+    def read_summary(self) -> Optional[Dict[str, Any]]:
+        if not self.summary_path.exists():
+            return None
+        return json.loads(self.summary_path.read_text(encoding="utf-8"))
+
+    def prune(self) -> int:
+        """Drop execution records older than retention_days. Returns removed count."""
+        if not self.executions_path.exists():
+            return 0
+
+        cutoff = datetime.now(timezone.utc) - timedelta(days=self.retention_days)
+        kept: List[Dict[str, Any]] = []
+        removed = 0
+
+        for record in self.read_executions():
+            try:
+                ts = _parse_timestamp(record["timestamp"])
+            except (KeyError, ValueError):
+                kept.append(record)
+                continue
+            if ts >= cutoff:
+                kept.append(record)
+            else:
+                removed += 1
+
+        if removed:
+            with self.executions_path.open("w", encoding="utf-8") as handle:
+                for record in kept:
+                    handle.write(json.dumps(record, sort_keys=True))
+                    handle.write("\n")
+            self.write_summary()
+
+        return removed
+
+    def _has_idempotency_key(self, key: str) -> bool:
+        return any(r.get("idempotency_key") == key for r in self.read_executions())
+
+
+@dataclass
+class OptimizerStore:
+    """Persist optimizer analysis output under .kaizen/metrics/optimizer/."""
+
+    project_root: Path
+
+    def __post_init__(self) -> None:
+        self.project_root = Path(self.project_root).resolve()
+        self.optimizer_dir = self.project_root / ".kaizen" / "metrics" / "optimizer"
+        self.analysis_path = self.optimizer_dir / "analysis.json"
+        self.recommendations_path = self.optimizer_dir / "recommendations.jsonl"
+
+    def write_analysis(self, report: Dict[str, Any]) -> Path:
+        self.optimizer_dir.mkdir(parents=True, exist_ok=True)
+        self.analysis_path.write_text(
+            json.dumps(report, indent=2, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+        return self.analysis_path
+
+    def append_recommendations(
+        self,
+        agent_name: str,
+        recommendations: List[Dict[str, Any]],
+        *,
+        metrics_count: int,
+    ) -> None:
+        self.optimizer_dir.mkdir(parents=True, exist_ok=True)
+        entry = {
+            "timestamp": _utc_now_iso(),
+            "agent": agent_name,
+            "metrics_count": metrics_count,
+            "recommendations": recommendations,
+        }
+        with self.recommendations_path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(entry, sort_keys=True))
+            handle.write("\n")

src/kaizen_agentic/migration.py

@@ -2,9 +2,8 @@
 
 import json
 import shutil
-import yaml
 from pathlib import Path
-from typing import Dict, List, Optional, Set, Tuple
+from typing import Dict, List, Optional
 from dataclasses import dataclass
 from enum import Enum
 

src/kaizen_agentic/optimization.py

@@ -5,11 +5,16 @@ This module implements the kaizen loop for measuring, analyzing, and refining
 agent performance over time.
 """
 
-from typing import Dict, Any, List, Optional
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
 from dataclasses import dataclass
 from datetime import datetime
 import statistics
 
+if TYPE_CHECKING:
+    from .metrics import MetricsStore
+
+MIN_SAMPLES_FOR_RECOMMENDATIONS = 10
+
 
 @dataclass
 class PerformanceMetrics:
@@ -35,6 +40,60 @@ class OptimizationLoop:
         self.metrics_history: List[PerformanceMetrics] = []
         self.optimization_history: List[Dict[str, Any]] = []
 
+    @classmethod
+    def from_metrics_store(
+        cls,
+        store: "MetricsStore",
+        *,
+        min_samples: int = 1,
+    ) -> "OptimizationLoop":
+        """Build an optimization loop from project-scoped execution records."""
+        loop = cls(store.agent_name)
+        records = store.read_executions()
+        if len(records) < min_samples:
+            return loop
+        for record in records:
+            loop.record_metrics(cls._metrics_from_record(record))
+        return loop
+
+    @staticmethod
+    def _metrics_from_record(record: Dict[str, Any]) -> PerformanceMetrics:
+        timestamp_raw = record.get("timestamp")
+        try:
+            timestamp = datetime.fromisoformat(
+                str(timestamp_raw).replace("Z", "+00:00")
+            )
+        except (TypeError, ValueError):
+            timestamp = datetime.now()
+
+        success = bool(record.get("success", False))
+        quality = record.get("quality_score")
+        if quality is None:
+            quality = 1.0 if success else 0.0
+
+        metadata = {
+            k: v
+            for k, v in record.items()
+            if k
+            not in {
+                "timestamp",
+                "agent",
+                "success",
+                "execution_time_s",
+                "quality_score",
+                "primary_metric",
+            }
+        }
+
+        return PerformanceMetrics(
+            timestamp=timestamp,
+            execution_time=float(record.get("execution_time_s") or 0.0),
+            success_rate=1.0 if success else 0.0,
+            quality_score=float(quality),
+            resource_usage={},
+            metadata=metadata or None,
+        )
+
     def record_metrics(self, metrics: PerformanceMetrics) -> None:
         """Record performance metrics for analysis."""
         self.metrics_history.append(metrics)
@@ -160,3 +219,17 @@ class OptimizationLoop:
             "metrics_count": len(self.metrics_history),
             "optimization_cycles": len(self.optimization_history),
         }
+
+    def get_optimization_report_json(self) -> Dict[str, Any]:
+        """JSON-serializable optimization report."""
+        return _to_json_safe(self.get_optimization_report())
+
+
+def _to_json_safe(value: Any) -> Any:
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, dict):
+        return {k: _to_json_safe(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_to_json_safe(item) for item in value]
+    return value

src/kaizen_agentic/registry.py

@@ -17,6 +17,7 @@ class AgentCategory(Enum):
     INFRASTRUCTURE = "infrastructure"
     TESTING = "testing"
     DOCUMENTATION = "documentation"
+    META = "meta"
 
 
 @dataclass
@@ -29,6 +30,19 @@ class AgentDefinition:
     category: AgentCategory
     dependencies: Set[str]
     model: Optional[str] = None
+    memory: Optional[str] = None  # "enabled" (default) | "disabled"
+
+    @staticmethod
+    def _read_frontmatter(file_path: Path) -> dict:
+        with open(file_path, "r", encoding="utf-8") as f:
+            content = f.read()
+        frontmatter_match = re.match(r"^---\n(.*?)\n---\n", content, re.DOTALL)
+        if not frontmatter_match:
+            raise ValueError(f"No YAML frontmatter found in {file_path}")
+        frontmatter = yaml.safe_load(frontmatter_match.group(1))
+        if not isinstance(frontmatter, dict) or "name" not in frontmatter:
+            raise ValueError(f"Invalid frontmatter in {file_path}")
+        return frontmatter
 
     @classmethod
     def from_file(cls, file_path: Path) -> "AgentDefinition":
@@ -56,6 +70,7 @@ class AgentDefinition:
             category=category,
             dependencies=dependencies,
             model=frontmatter.get("model"),
+            memory=frontmatter.get("memory"),
         )
 
     @staticmethod
@@ -127,8 +142,15 @@ class AgentDefinition:
         if any(keyword in name_lower for keyword in ["documentation", "claude"]):
             return AgentCategory.DOCUMENTATION
 
+        # Meta agents (coaching, cross-agent orchestration)
+        if any(keyword in name_lower for keyword in ["coach", "meta"]):
+            return AgentCategory.META
+
         # Infrastructure agents
-        if any(keyword in name_lower for keyword in ["setup", "repository", "tooling"]):
+        if any(
+            keyword in name_lower
+            for keyword in ["setup", "repository", "tooling", "sys-medic", "medic"]
+        ):
             return AgentCategory.INFRASTRUCTURE
 
         # Development process agents
@@ -148,29 +170,50 @@ class AgentRegistry:
     def __init__(self, agents_dir: Path):
         self.agents_dir = Path(agents_dir)
         self._agents: Dict[str, AgentDefinition] = {}
-        self._load_agents()
+        self._file_index: Dict[str, Path] = {}
+        self._index_agent_files()
 
-    def _load_agents(self):
-        """Load all agents from the agents directory."""
+    def _index_agent_files(self) -> None:
+        """Index agent files by frontmatter name without full parse."""
         if not self.agents_dir.exists():
             return
 
         for agent_file in self.agents_dir.glob("agent-*.md"):
             try:
-                agent_def = AgentDefinition.from_file(agent_file)
-                self._agents[agent_def.name] = agent_def
+                frontmatter = AgentDefinition._read_frontmatter(agent_file)
+                self._file_index[frontmatter["name"]] = agent_file
             except Exception as e:
-                print(f"Warning: Failed to load agent {agent_file}: {e}")
+                print(f"Warning: Failed to index agent {agent_file}: {e}")
+
+    def get_agent_path(self, name: str) -> Optional[Path]:
+        """Return the source file path for an agent (no full parse)."""
+        return self._file_index.get(name)
 
     def get_agent(self, name: str) -> Optional[AgentDefinition]:
-        """Get agent definition by name."""
-        return self._agents.get(name)
+        """Get agent definition by name (lazy-loaded)."""
+        if name in self._agents:
+            return self._agents[name]
+        file_path = self._file_index.get(name)
+        if file_path is None:
+            return None
+        try:
+            agent_def = AgentDefinition.from_file(file_path)
+        except Exception as e:
+            print(f"Warning: Failed to load agent {name}: {e}")
+            return None
+        self._agents[name] = agent_def
+        return agent_def
+
+    def agent_names(self) -> List[str]:
+        """List indexed agent names without loading full definitions."""
+        return sorted(self._file_index.keys())
 
     def list_agents(
         self, category: Optional[AgentCategory] = None
     ) -> List[AgentDefinition]:
         """List all agents, optionally filtered by category."""
-        agents = list(self._agents.values())
+        agents = [self.get_agent(name) for name in self.agent_names()]
+        agents = [agent for agent in agents if agent is not None]
         if category:
             agents = [a for a in agents if a.category == category]
         return sorted(agents, key=lambda a: a.name)
@@ -178,7 +221,7 @@ class AgentRegistry:
     def get_categories(self) -> Dict[AgentCategory, List[AgentDefinition]]:
         """Get agents organized by category."""
         categories = {}
-        for agent in self._agents.values():
+        for agent in self.list_agents():
             if agent.category not in categories:
                 categories[agent.category] = []
             categories[agent.category].append(agent)
@@ -220,12 +263,16 @@ class AgentRegistry:
         """Validate all agents and return validation errors."""
         errors = {}
 
-        for name, agent in self._agents.items():
+        for name in self.agent_names():
+            agent = self.get_agent(name)
+            if agent is None:
+                errors[name] = ["Failed to load agent definition"]
+                continue
             agent_errors = []
 
             # Check for missing dependencies
             for dep in agent.dependencies:
-                if dep not in self._agents:
+                if dep not in self._file_index:
                     agent_errors.append(f"Missing dependency: {dep}")
 
             # Check file exists

tests/test_cli_error_handling.py

@@ -20,9 +20,12 @@ class TestClickWorkaround:
     def test_install_command_error_suppression(self):
         """Test that spurious 'unexpected extra argument' errors are suppressed for install commands."""
         # Test the install command that previously showed spurious errors
-        with patch('sys.argv', ['kaizen-agentic', 'install', 'tdd-workflow', '--target', '/tmp/test']):
-            with patch('sys.stdout', new_callable=StringIO) as mock_stdout:
-                with patch('sys.stderr', new_callable=StringIO) as mock_stderr:
+        with patch(
+            "sys.argv",
+            ["kaizen-agentic", "install", "tdd-workflow", "--target", "/tmp/test"],
+        ):
+            with patch("sys.stdout", new_callable=StringIO) as mock_stdout:
+                with patch("sys.stderr", new_callable=StringIO) as mock_stderr:
                     try:
                         safe_cli_wrapper()
                     except SystemExit:
@@ -40,9 +43,9 @@ class TestClickWorkaround:
     def test_update_command_error_suppression(self):
         """Test that spurious 'unexpected extra argument' errors are suppressed for update commands."""
         # Test the update command that also shows spurious errors
-        with patch('sys.argv', ['kaizen-agentic', 'update']):
-            with patch('sys.stdout', new_callable=StringIO) as mock_stdout:
-                with patch('sys.stderr', new_callable=StringIO) as mock_stderr:
+        with patch("sys.argv", ["kaizen-agentic", "update"]):
+            with patch("sys.stdout", new_callable=StringIO) as mock_stdout:
+                with patch("sys.stderr", new_callable=StringIO) as mock_stderr:
                     try:
                         safe_cli_wrapper()
                     except SystemExit:
@@ -59,9 +62,9 @@ class TestClickWorkaround:
 
     def test_non_install_command_normal_operation(self):
         """Test that non-install commands work normally without interference."""
-        with patch('sys.argv', ['kaizen-agentic', 'list']):
-            with patch('sys.stdout', new_callable=StringIO) as mock_stdout:
-                with patch('sys.stderr', new_callable=StringIO) as mock_stderr:
+        with patch("sys.argv", ["kaizen-agentic", "list"]):
+            with patch("sys.stdout", new_callable=StringIO) as mock_stdout:
+                with patch("sys.stderr", new_callable=StringIO) as mock_stderr:
                     try:
                         safe_cli_wrapper()
                     except SystemExit:
@@ -76,9 +79,9 @@ class TestClickWorkaround:
 
     def test_legitimate_error_preservation(self):
         """Test that legitimate errors are still displayed for non-install commands."""
-        with patch('sys.argv', ['kaizen-agentic', 'invalid-command']):
-            with patch('sys.stdout', new_callable=StringIO) as mock_stdout:
-                with patch('sys.stderr', new_callable=StringIO) as mock_stderr:
+        with patch("sys.argv", ["kaizen-agentic", "invalid-command"]):
+            with patch("sys.stdout", new_callable=StringIO) as mock_stdout:
+                with patch("sys.stderr", new_callable=StringIO) as mock_stderr:
                     try:
                         safe_cli_wrapper()
                     except SystemExit as e:
@@ -95,8 +98,8 @@ class TestClickWorkaround:
 
     def test_help_commands_work_normally(self):
         """Test that help commands work without interference."""
-        with patch('sys.argv', ['kaizen-agentic', '--help']):
-            with patch('sys.stdout', new_callable=StringIO) as mock_stdout:
+        with patch("sys.argv", ["kaizen-agentic", "--help"]):
+            with patch("sys.stdout", new_callable=StringIO) as mock_stdout:
                 try:
                     safe_cli_wrapper()
                 except SystemExit as e:
@@ -104,7 +107,9 @@ class TestClickWorkaround:
                     assert e.code == 0
 
                 stdout_content = mock_stdout.getvalue()
-                assert "Kaizen Agentic - AI agent development framework" in stdout_content
+                assert (
+                    "Kaizen Agentic - AI agent development framework" in stdout_content
+                )
                 assert "Commands:" in stdout_content
 
 
@@ -113,9 +118,9 @@ class TestInstallCommandSpecifics:
 
     def test_install_with_valid_agent(self):
         """Test install command with a valid agent name."""
-        with patch('sys.argv', ['kaizen-agentic', 'install', 'tdd-workflow']):
-            with patch('sys.stdout', new_callable=StringIO) as mock_stdout:
-                with patch('sys.stderr', new_callable=StringIO) as mock_stderr:
+        with patch("sys.argv", ["kaizen-agentic", "install", "tdd-workflow"]):
+            with patch("sys.stdout", new_callable=StringIO) as mock_stdout:
+                with patch("sys.stderr", new_callable=StringIO) as mock_stderr:
                     try:
                         safe_cli_wrapper()
                     except SystemExit:
@@ -127,12 +132,17 @@ class TestInstallCommandSpecifics:
                     # Should show clean installation output
                     assert "Installing agents to:" in stdout_content
                     # Should not show Click error
-                    assert "Got unexpected extra argument" not in (stdout_content + stderr_content)
+                    assert "Got unexpected extra argument" not in (
+                        stdout_content + stderr_content
+                    )
 
     def test_install_with_target_option(self):
         """Test install command with target directory option."""
-        with patch('sys.argv', ['kaizen-agentic', 'install', 'tdd-workflow', '--target', '/tmp/test']):
-            with patch('sys.stdout', new_callable=StringIO) as mock_stdout:
+        with patch(
+            "sys.argv",
+            ["kaizen-agentic", "install", "tdd-workflow", "--target", "/tmp/test"],
+        ):
+            with patch("sys.stdout", new_callable=StringIO) as mock_stdout:
                 try:
                     safe_cli_wrapper()
                 except SystemExit:
@@ -144,8 +154,8 @@ class TestInstallCommandSpecifics:
 
     def test_install_help_works(self):
         """Test that install command help works correctly."""
-        with patch('sys.argv', ['kaizen-agentic', 'install', '--help']):
-            with patch('sys.stdout', new_callable=StringIO) as mock_stdout:
+        with patch("sys.argv", ["kaizen-agentic", "install", "--help"]):
+            with patch("sys.stdout", new_callable=StringIO) as mock_stdout:
                 try:
                     safe_cli_wrapper()
                 except SystemExit as e:
@@ -170,12 +180,14 @@ class TestWorkaroundRemovalReadiness:
         may be ready for removal.
         """
         # Skip this test in normal runs since it's expected to show the spurious error
-        pytest.skip("This test demonstrates the underlying Click issue. "
-                   "Enable when testing Click library updates.")
+        pytest.skip(
+            "This test demonstrates the underlying Click issue. "
+            "Enable when testing Click library updates."
+        )
 
-        with patch('sys.argv', ['kaizen-agentic', 'install', 'tdd-workflow']):
-            with patch('sys.stdout', new_callable=StringIO) as mock_stdout:
-                with patch('sys.stderr', new_callable=StringIO) as mock_stderr:
+        with patch("sys.argv", ["kaizen-agentic", "install", "tdd-workflow"]):
+            with patch("sys.stdout", new_callable=StringIO) as mock_stdout:
+                with patch("sys.stderr", new_callable=StringIO) as mock_stderr:
                     try:
                         cli(standalone_mode=False)
                     except SystemExit:
@@ -201,9 +213,13 @@ class TestWorkaroundRemovalReadiness:
         """
         # Test that the CLI works when invoked as a subprocess
         result = subprocess.run(
-            ['python', '-c', 'from kaizen_agentic.cli import safe_cli_wrapper; import sys; sys.argv = ["kaizen-agentic", "list"]; safe_cli_wrapper()'],
+            [
+                "python",
+                "-c",
+                'from kaizen_agentic.cli import safe_cli_wrapper; import sys; sys.argv = ["kaizen-agentic", "list"]; safe_cli_wrapper()',
+            ],
             capture_output=True,
-            text=True
+            text=True,
         )
 
         assert "Available Agents" in result.stdout
@@ -220,7 +236,7 @@ class TestErrorMessagePatterns:
         spurious_patterns = [
             "Got unexpected extra argument (tdd-workflow)",
             "Got unexpected extra argument (some-agent)",
-            "Error: Got unexpected extra argument"
+            "Error: Got unexpected extra argument",
         ]
 
         for pattern in spurious_patterns:
@@ -234,7 +250,7 @@ class TestErrorMessagePatterns:
             "Error: No such file or directory",
             "Error: Permission denied",
             "Error: Invalid agent name",
-            "Error: Configuration file not found"
+            "Error: Configuration file not found",
         ]
 
         for pattern in legitimate_patterns:
@@ -243,4 +259,4 @@ class TestErrorMessagePatterns:
 
 
 if __name__ == "__main__":
-    pytest.main([__file__])
+    pytest.main([__file__])

tests/test_e2e_agency_framework.py

@@ -0,0 +1,462 @@
+"""
+End-to-end tests for the agency framework: memory lifecycle and coach orientation.
+
+Tests the full workflow:
+  1. memory init — scaffold a memory file in a test project
+  2. Populate memory with realistic content (simulating sessions)
+  3. memory show — verify content is readable
+  4. memory brief — verify orientation brief includes own memory and cross-agent context
+  5. protocols list / show — verify protocol discovery works
+  6. memory clear — verify wipe works
+  7. tdd-workflow pilot — record → show → optimize → brief (WP-0003 Part 5)
+"""
+
+import json
+import textwrap
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+from kaizen_agentic.cli import cli
+from kaizen_agentic.metrics import MetricsStore, OptimizerStore
+from kaizen_agentic.optimization import MIN_SAMPLES_FOR_RECOMMENDATIONS
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _sys_medic_memory() -> str:
+    """Realistic sys-medic memory after two simulated sessions."""
+    return textwrap.dedent("""\
+        ---
+        agent: sys-medic
+        project: test-cluster
+        last_updated: 2026-03-18
+        session_count: 2
+        ---
+
+        ## Project Context
+        k3s single-node cluster on an ARM64 host (tegpi-01).
+        No external load balancer. Traefik ingress. Longhorn storage.
+
+        ## Accumulated Findings
+        - kubelet log rotation was disabled; logs grew to 2.1 GB
+        - containerd image GC threshold was set too high (98%)
+
+        ## What Worked
+        - `journalctl --vacuum-size=500M` recovered ~1.8 GB without restart
+        - Lowering GC threshold to 80% in containerd config resolved disk pressure
+
+        ## Watch Points
+        - inotify watch limit hits ceiling under heavy Longhorn load
+        - node has only 4 GB RAM; memory pressure risk during backup windows
+
+        ## Open Threads
+        - Check whether kube-system namespace daemonsets have resource limits set
+
+        ## Node Profiles
+        tegpi-01 | load avg ~0.6 at idle | inotify-limited under load | 2026-03-18
+
+        ## Recurring Findings
+        - kubelet log growth · first seen 2026-03-10 · 2 occurrences
+
+        ## Cleared Issues
+        - containerd GC disk pressure · adjusted config 2026-03-18 · resolved
+
+        ## Session Log
+        2026-03-10 · tegpi-01 initial assessment · found log bloat + GC issue · recommendations documented
+        2026-03-18 · tegpi-01 follow-up · verified GC fix; inotify limit noted · watch
+    """)
+
+
+def _tdd_workflow_memory() -> str:
+    """Realistic tdd-workflow memory after two issue cycles."""
+    return textwrap.dedent("""\
+        ---
+        agent: tdd-workflow
+        project: demo-app
+        last_updated: 2026-06-16
+        session_count: 2
+        ---
+
+        ## Project Context
+        Python service using TDD8 with Gitea issues and pytest.
+
+        ## Accumulated Findings
+        - Sidequests from REFINE often block PUBLISH when lint debt accumulates
+
+        ## What Worked
+        - `make tdd-start NUM=X` before writing tests keeps RED phase focused
+
+        ## Watch Points
+        - Flaky integration tests under parallel pytest (-n auto)
+
+        ## Session Log
+        2026-06-10 · issue 12 metrics store · PUBLISH complete · success
+        2026-06-16 · issue 15 CLI flags · stalled at REFINE · partial
+    """)
+
+
+def _project_management_memory() -> str:
+    """Minimal project-management agent memory."""
+    return textwrap.dedent("""\
+        ---
+        agent: project-management
+        project: test-cluster
+        last_updated: 2026-03-15
+        session_count: 1
+        ---
+
+        ## Project Context
+        Operational runbook project for the k3s home cluster.
+
+        ## Accumulated Findings
+        - Infra tasks are better tracked in Gitea issues than in TODO files
+
+        ## Session Log
+        2026-03-15 · initial planning session · task structure agreed
+    """)
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def project(tmp_path):
+    """A temporary 'project' directory with a name."""
+    p = tmp_path / "test-cluster"
+    p.mkdir()
+    return p
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+
+class TestMemoryInit:
+    def test_init_creates_file(self, project):
+        runner = CliRunner()
+        result = runner.invoke(
+            cli, ["memory", "init", "sys-medic", "--target", str(project)]
+        )
+        assert result.exit_code == 0, result.output
+        assert "Initialized memory" in result.output
+
+        memory_file = project / ".kaizen" / "agents" / "sys-medic" / "memory.md"
+        assert memory_file.exists()
+
+    def test_init_file_content_has_required_sections(self, project):
+        runner = CliRunner()
+        runner.invoke(cli, ["memory", "init", "sys-medic", "--target", str(project)])
+
+        memory_file = project / ".kaizen" / "agents" / "sys-medic" / "memory.md"
+        content = memory_file.read_text()
+
+        assert "agent: sys-medic" in content
+        assert "project: test-cluster" in content
+        assert "session_count: 0" in content
+        assert "## Project Context" in content
+        assert "## Accumulated Findings" in content
+        assert "## What Worked" in content
+        assert "## Watch Points" in content
+        assert "## Open Threads" in content
+        assert "## Session Log" in content
+
+    def test_init_idempotent(self, project):
+        runner = CliRunner()
+        runner.invoke(cli, ["memory", "init", "sys-medic", "--target", str(project)])
+        result = runner.invoke(
+            cli, ["memory", "init", "sys-medic", "--target", str(project)]
+        )
+        assert result.exit_code == 0
+        assert "already exists" in result.output
+
+
+class TestMemoryShow:
+    def test_show_returns_content(self, project):
+        memory_file = project / ".kaizen" / "agents" / "sys-medic" / "memory.md"
+        memory_file.parent.mkdir(parents=True, exist_ok=True)
+        memory_file.write_text(_sys_medic_memory())
+
+        runner = CliRunner()
+        result = runner.invoke(
+            cli, ["memory", "show", "sys-medic", "--target", str(project)]
+        )
+        assert result.exit_code == 0
+        assert "Node Profiles" in result.output
+        assert "tegpi-01" in result.output
+
+    def test_show_missing_prints_guidance(self, project):
+        runner = CliRunner()
+        result = runner.invoke(
+            cli, ["memory", "show", "sys-medic", "--target", str(project)]
+        )
+        assert result.exit_code == 0
+        assert "No memory found" in result.output
+        assert "memory init" in result.output
+
+
+class TestMemoryBrief:
+    def _populate(self, project):
+        """Write both agent memories into the project."""
+        sm_dir = project / ".kaizen" / "agents" / "sys-medic"
+        sm_dir.mkdir(parents=True, exist_ok=True)
+        (sm_dir / "memory.md").write_text(_sys_medic_memory())
+
+        pm_dir = project / ".kaizen" / "agents" / "project-management"
+        pm_dir.mkdir(parents=True, exist_ok=True)
+        (pm_dir / "memory.md").write_text(_project_management_memory())
+
+    def test_brief_includes_own_memory(self, project):
+        self._populate(project)
+        runner = CliRunner()
+        result = runner.invoke(
+            cli, ["memory", "brief", "sys-medic", "--target", str(project)]
+        )
+        assert result.exit_code == 0
+        assert "Orientation Brief for: sys-medic" in result.output
+        assert "Your Memory" in result.output
+        assert "tegpi-01" in result.output  # content from sys-medic memory
+
+    def test_brief_includes_cross_agent_context(self, project):
+        self._populate(project)
+        runner = CliRunner()
+        result = runner.invoke(
+            cli, ["memory", "brief", "sys-medic", "--target", str(project)]
+        )
+        assert result.exit_code == 0
+        assert "Context From Other Agents" in result.output
+        assert "project-management" in result.output
+
+    def test_brief_coach_tip_present(self, project):
+        self._populate(project)
+        runner = CliRunner()
+        result = runner.invoke(
+            cli, ["memory", "brief", "sys-medic", "--target", str(project)]
+        )
+        assert result.exit_code == 0
+        assert "agent-coach" in result.output
+
+    def test_brief_no_memory_gives_guidance(self, project):
+        runner = CliRunner()
+        result = runner.invoke(
+            cli, ["memory", "brief", "sys-medic", "--target", str(project)]
+        )
+        assert result.exit_code == 0
+        assert "No agent memory files found" in result.output
+
+    def test_brief_raw_flag_skips_header(self, project):
+        self._populate(project)
+        runner = CliRunner()
+        result = runner.invoke(
+            cli, ["memory", "brief", "sys-medic", "--target", str(project), "--raw"]
+        )
+        assert result.exit_code == 0
+        assert "=== sys-medic ===" in result.output
+        # Raw mode should not include the orientation header
+        assert "Orientation Brief for:" not in result.output
+
+    def test_brief_includes_performance_summary_with_memory_and_metrics(self, project):
+        self._populate(project)
+        runner = CliRunner()
+        runner.invoke(
+            cli,
+            [
+                "metrics",
+                "record",
+                "sys-medic",
+                "--target",
+                str(project),
+                "--success",
+                "--time",
+                "30",
+                "--quality",
+                "0.88",
+            ],
+        )
+        runner.invoke(
+            cli,
+            [
+                "metrics",
+                "record",
+                "project-management",
+                "--target",
+                str(project),
+                "--success",
+                "--time",
+                "15",
+                "--quality",
+                "0.95",
+            ],
+        )
+
+        result = runner.invoke(
+            cli, ["memory", "brief", "sys-medic", "--target", str(project)]
+        )
+
+        assert result.exit_code == 0
+        assert "## Performance Summary" in result.output
+        assert "Success rate:" in result.output
+        assert "tegpi-01" in result.output
+        assert "Context From Other Agents" in result.output
+        assert "project-management" in result.output
+
+
+class TestMemoryClear:
+    def test_clear_removes_file(self, project):
+        memory_file = project / ".kaizen" / "agents" / "sys-medic" / "memory.md"
+        memory_file.parent.mkdir(parents=True, exist_ok=True)
+        memory_file.write_text(_sys_medic_memory())
+
+        runner = CliRunner()
+        result = runner.invoke(
+            cli, ["memory", "clear", "sys-medic", "--target", str(project)], input="y\n"
+        )
+        assert result.exit_code == 0
+        assert not memory_file.exists()
+
+    def test_clear_missing_is_graceful(self, project):
+        runner = CliRunner()
+        result = runner.invoke(
+            cli, ["memory", "clear", "sys-medic", "--target", str(project)], input="y\n"
+        )
+        assert result.exit_code == 0
+        assert "nothing to clear" in result.output
+
+
+class TestTddWorkflowMetricsPilot:
+    """Full measure → analyse → orient loop for the tdd-workflow pilot agent."""
+
+    def _populate_memory(self, project: Path) -> None:
+        memory_dir = project / ".kaizen" / "agents" / "tdd-workflow"
+        memory_dir.mkdir(parents=True, exist_ok=True)
+        (memory_dir / "memory.md").write_text(_tdd_workflow_memory())
+
+    def test_full_metrics_loop_record_show_optimize_brief(self, project):
+        runner = CliRunner()
+        self._populate_memory(project)
+
+        sessions = [
+            {
+                "success": True,
+                "execution_time_s": 4200.0,
+                "quality_score": 0.92,
+                "primary_metric": {
+                    "name": "test_pass_rate",
+                    "value": 1.0,
+                    "target": 1.0,
+                },
+                "metadata": {"issue": "12", "phase": "PUBLISH"},
+            },
+            {
+                "success": False,
+                "execution_time_s": 5400.0,
+                "quality_score": 0.45,
+                "primary_metric": {
+                    "name": "test_pass_rate",
+                    "value": 0.78,
+                    "target": 1.0,
+                },
+                "metadata": {"issue": "15", "phase": "REFINE"},
+            },
+        ]
+
+        for index, payload in enumerate(sessions, start=1):
+            result = runner.invoke(
+                cli,
+                [
+                    "metrics",
+                    "record",
+                    "tdd-workflow",
+                    "--target",
+                    str(project),
+                    "--json",
+                    "--idempotency-key",
+                    f"session-{index}",
+                ],
+                input=json.dumps(payload),
+            )
+            assert result.exit_code == 0, result.output
+            assert "Recorded metrics" in result.output
+
+        show_result = runner.invoke(
+            cli,
+            ["metrics", "show", "tdd-workflow", "--target", str(project)],
+        )
+        assert show_result.exit_code == 0
+        assert (
+            "test_pass_rate" in show_result.output
+            or "2 execution" in show_result.output.lower()
+        )
+
+        store = MetricsStore(project, "tdd-workflow")
+        for i in range(MIN_SAMPLES_FOR_RECOMMENDATIONS - len(sessions)):
+            store.append(
+                {
+                    "success": False,
+                    "execution_time_s": 90.0 + i,
+                    "quality_score": 0.35,
+                    "primary_metric": {
+                        "name": "test_pass_rate",
+                        "value": 0.6,
+                        "target": 1.0,
+                    },
+                },
+                idempotency_key=f"seed-{i}",
+            )
+
+        optimize_result = runner.invoke(
+            cli,
+            ["metrics", "optimize", "tdd-workflow", "--target", str(project)],
+        )
+        assert optimize_result.exit_code == 0, optimize_result.output
+        optimizer = OptimizerStore(project)
+        assert optimizer.analysis_path.exists()
+        assert optimizer.recommendations_path.exists()
+
+        brief_result = runner.invoke(
+            cli,
+            ["memory", "brief", "tdd-workflow", "--target", str(project)],
+        )
+        assert brief_result.exit_code == 0
+        assert "## Performance Summary" in brief_result.output
+        assert "Success rate:" in brief_result.output
+        assert "issue 12" in brief_result.output or "TDD8" in brief_result.output
+        assert "Your Memory" in brief_result.output
+
+
+class TestProtocolsCommand:
+    def test_protocols_list_finds_sys_medic(self):
+        """Protocols list against the real agents dir should include sys-medic k3s protocol."""
+        runner = CliRunner()
+        result = runner.invoke(cli, ["protocols", "list"])
+        assert result.exit_code == 0
+        assert "sys-medic" in result.output
+        assert "k3s-node-health-assessment" in result.output.replace("-", "-")
+
+    def test_protocols_list_filtered_by_agent(self):
+        runner = CliRunner()
+        result = runner.invoke(cli, ["protocols", "list", "sys-medic"])
+        assert result.exit_code == 0
+        assert "k3s" in result.output.lower()
+
+    def test_protocols_show_outputs_content(self):
+        runner = CliRunner()
+        result = runner.invoke(
+            cli, ["protocols", "show", "sys-medic", "k3s-node-health-assessment"]
+        )
+        assert result.exit_code == 0
+        # Protocol should contain key structural sections
+        assert "k3s" in result.output.lower()
+        assert "Prerequisites" in result.output or "Scope" in result.output
+
+    def test_protocols_list_unknown_agent_no_crash(self):
+        runner = CliRunner()
+        result = runner.invoke(cli, ["protocols", "list", "nonexistent-agent"])
+        assert result.exit_code == 0
+        assert "No protocols found" in result.output

tests/test_feedback_cli.py

@@ -0,0 +1,27 @@
+"""Tests for developer feedback CLI (WP-0001 T01)."""
+
+from __future__ import annotations
+
+import json
+
+from click.testing import CliRunner
+
+from kaizen_agentic.cli import cli
+
+
+def test_feedback_human_output():
+    runner = CliRunner()
+    result = runner.invoke(cli, ["feedback"])
+    assert result.exit_code == 0
+    assert "feedback channels" in result.output.lower()
+    assert "gitea.coulomb.social" in result.output
+    assert "bug report" in result.output.lower()
+
+
+def test_feedback_json_output():
+    runner = CliRunner()
+    result = runner.invoke(cli, ["feedback", "--json"])
+    assert result.exit_code == 0
+    payload = json.loads(result.output)
+    assert "channels" in payload
+    assert "bug_report" in payload["templates"]

tests/test_helix_correlation.py

@@ -0,0 +1,160 @@
+"""Tests for Helix Forge correlation (WP-0004 Part 1)."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+from kaizen_agentic.cli import cli
+from kaizen_agentic.integrations.helix import (
+    HelixCorrelationAdapter,
+    enrich_helix_correlation,
+)
+
+
+def test_enrich_helix_correlation_from_env(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setenv("HELIX_SESSION_UID", "claude:test-uid")
+    monkeypatch.setenv("HELIX_REPO", "kaizen-agentic")
+    monkeypatch.setenv("HELIX_FLAVOR", "claude")
+    monkeypatch.setenv("HELIX_TOKENS", "9900")
+    monkeypatch.setenv("HELIX_INFRA_OVERHEAD_SHARE", "0.15")
+
+    result = enrich_helix_correlation({"success": True})
+
+    assert result["helix_session_uid"] == "claude:test-uid"
+    assert result["repo"] == "kaizen-agentic"
+    assert result["flavor"] == "claude"
+    assert result["tokens"] == 9900
+    assert result["infra_overhead_share"] == 0.15
+
+
+def test_enrich_does_not_override_existing_fields():
+    record = {
+        "success": True,
+        "helix_session_uid": "grok:existing",
+        "repo": "other-repo",
+    }
+    result = enrich_helix_correlation(record)
+    assert result["helix_session_uid"] == "grok:existing"
+    assert result["repo"] == "other-repo"
+
+
+def test_adapter_stub_when_store_unconfigured():
+    adapter = HelixCorrelationAdapter(store_db=None)
+    summary = adapter.lookup("claude:missing")
+    assert summary["adapter"] == "stub"
+    assert summary["status"] == "not_configured"
+
+
+def test_adapter_sqlite_lookup(tmp_path: Path):
+    db_path = tmp_path / "store.db"
+    conn = sqlite3.connect(db_path)
+    conn.execute(
+        "CREATE TABLE digests (session_uid TEXT PRIMARY KEY, json TEXT NOT NULL)"
+    )
+    conn.execute(
+        "CREATE TABLE sessions (session_uid TEXT PRIMARY KEY, json TEXT NOT NULL)"
+    )
+    digest = {
+        "outcome": "success",
+        "cost": {"input_tokens": 800, "output_tokens": 200, "wall_clock_s": 3600},
+        "tool_histogram": {"mcp__state-hub__x": 3, "Bash": 7},
+        "markers": {"errors": 0, "retries": 1},
+    }
+    session = {"repo": "demo-app", "flavor": "claude"}
+    conn.execute(
+        "INSERT INTO digests VALUES (?, ?)",
+        ("claude:abc", json.dumps(digest)),
+    )
+    conn.execute(
+        "INSERT INTO sessions VALUES (?, ?)",
+        ("claude:abc", json.dumps(session)),
+    )
+    conn.commit()
+    conn.close()
+
+    adapter = HelixCorrelationAdapter(store_db=db_path)
+    summary = adapter.lookup("claude:abc")
+
+    assert summary["adapter"] == "helix-sqlite"
+    assert summary["repo"] == "demo-app"
+    assert summary["flavor"] == "claude"
+    assert summary["fleet_outcome"] == "success"
+    assert summary["tokens"] == 1000
+    assert summary["wall_clock_s"] == 3600
+    assert summary["infra_overhead_share"] == 0.3
+
+
+class TestHelixCorrelationCli:
+    def test_record_populates_helix_uid_from_env(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ):
+        monkeypatch.setenv("HELIX_SESSION_UID", "claude:session-42")
+        monkeypatch.setenv("HELIX_REPO", "kaizen-agentic")
+
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            [
+                "metrics",
+                "record",
+                "tdd-workflow",
+                "--target",
+                str(tmp_path),
+                "--success",
+                "--time",
+                "10",
+            ],
+        )
+        assert result.exit_code == 0
+
+        show = runner.invoke(
+            cli,
+            ["metrics", "show", "tdd-workflow", "--target", str(tmp_path)],
+        )
+        assert "claude:session-42" in show.output
+        assert "kaizen-agentic" in show.output
+
+    def test_correlate_stub_output(self):
+        runner = CliRunner()
+        result = runner.invoke(cli, ["metrics", "correlate", "claude:stub-uid"])
+        assert result.exit_code == 0
+        payload = json.loads(result.output)
+        assert payload["helix_session_uid"] == "claude:stub-uid"
+        assert payload["adapter"] == "stub"
+
+    def test_brief_works_with_correlated_metrics(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ):
+        memory_dir = tmp_path / ".kaizen" / "agents" / "tdd-workflow"
+        memory_dir.mkdir(parents=True)
+        (memory_dir / "memory.md").write_text(
+            "---\nagent: tdd-workflow\nproject: demo\nsession_count: 1\n---\n\n## Session Log\n",
+            encoding="utf-8",
+        )
+        monkeypatch.setenv("HELIX_SESSION_UID", "claude:brief-test")
+
+        runner = CliRunner()
+        runner.invoke(
+            cli,
+            [
+                "metrics",
+                "record",
+                "tdd-workflow",
+                "--target",
+                str(tmp_path),
+                "--success",
+                "--quality",
+                "0.9",
+            ],
+        )
+        brief = runner.invoke(
+            cli,
+            ["memory", "brief", "tdd-workflow", "--target", str(tmp_path)],
+        )
+        assert brief.exit_code == 0
+        assert "## Performance Summary" in brief.output

tests/test_integration_patterns.py

@@ -0,0 +1,32 @@
+"""Smoke tests for WP-0004 integration artifacts."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+DEFINITIONS_DIR = (
+    Path(__file__).parent.parent / "docs" / "integrations" / "activity-definitions"
+)
+
+
+def test_activity_definitions_have_required_frontmatter():
+    files = list(DEFINITIONS_DIR.glob("*.md"))
+    assert len(files) == 3
+
+    for path in files:
+        text = path.read_text(encoding="utf-8")
+        assert text.startswith("---\n")
+        end = text.index("\n---\n", 4)
+        frontmatter = yaml.safe_load(text[4:end])
+        assert frontmatter["id"]
+        assert frontmatter["trigger"]["type"] in ("cron", "event")
+        assert frontmatter["owner"] == "kaizen-agentic"
+
+
+def test_integration_docs_exist():
+    root = Path(__file__).parent.parent / "docs"
+    assert (root / "INTEGRATION_PATTERNS.md").exists()
+    assert (root / "integrations" / "helix-forge-correlation.md").exists()
+    assert (root / "integrations" / "optimizer-artifact-manifest.md").exists()

tests/test_metrics.py

@@ -0,0 +1,107 @@
+"""Tests for project-scoped metrics storage (ADR-004)."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import pytest
+
+from kaizen_agentic.metrics import MetricsStore, DEFAULT_RETENTION_DAYS
+
+
+def _old_timestamp(days: int) -> str:
+    dt = datetime.now(timezone.utc) - timedelta(days=days)
+    return dt.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+@pytest.fixture
+def project_dir(tmp_path: Path) -> Path:
+    root = tmp_path / "demo-project"
+    root.mkdir()
+    return root
+
+
+class TestMetricsStore:
+    def test_scaffold_creates_directory_and_empty_executions(self, project_dir: Path):
+        store = MetricsStore(project_dir, "tdd-workflow")
+        path = store.scaffold()
+
+        assert path == project_dir / ".kaizen" / "metrics" / "tdd-workflow"
+        assert store.executions_path.exists()
+        assert store.executions_path.read_text() == ""
+
+    def test_append_and_read_executions(self, project_dir: Path):
+        store = MetricsStore(project_dir, "tdd-workflow")
+
+        assert store.append({"success": True, "quality_score": 0.9}) is True
+        assert store.append({"success": False, "execution_time_s": 12.5}) is True
+
+        records = store.read_executions()
+        assert len(records) == 2
+        assert records[0]["agent"] == "tdd-workflow"
+        assert records[0]["success"] is True
+        assert "timestamp" in records[0]
+
+    def test_idempotency_key_rejects_duplicate(self, project_dir: Path):
+        store = MetricsStore(project_dir, "coach")
+
+        assert store.append({"success": True}, idempotency_key="sess-1") is True
+        assert store.append({"success": True}, idempotency_key="sess-1") is False
+        assert len(store.read_executions()) == 1
+
+    def test_write_summary_regenerates_summary_json(self, project_dir: Path):
+        store = MetricsStore(project_dir, "tdd-workflow")
+        store.append({"success": True, "quality_score": 0.8, "execution_time_s": 10})
+        store.append({"success": True, "quality_score": 1.0, "execution_time_s": 20})
+
+        summary = store.write_summary()
+
+        assert summary["execution_count"] == 2
+        assert summary["success_rate"] == 1.0
+        assert summary["avg_quality_score"] == 0.9
+        assert summary["avg_execution_time_s"] == 15.0
+        assert store.summary_path.exists()
+        on_disk = json.loads(store.summary_path.read_text())
+        assert on_disk["execution_count"] == 2
+
+    def test_prune_removes_expired_records(self, project_dir: Path):
+        store = MetricsStore(project_dir, "tdd-workflow", retention_days=30)
+        store.scaffold()
+
+        old = {
+            "timestamp": _old_timestamp(45),
+            "agent": "tdd-workflow",
+            "success": False,
+        }
+        recent = {
+            "timestamp": _old_timestamp(1),
+            "agent": "tdd-workflow",
+            "success": True,
+            "quality_score": 0.7,
+        }
+        with store.executions_path.open("w", encoding="utf-8") as handle:
+            handle.write(json.dumps(old) + "\n")
+            handle.write(json.dumps(recent) + "\n")
+
+        removed = store.prune()
+
+        assert removed == 1
+        records = store.read_executions()
+        assert len(records) == 1
+        assert records[0]["success"] is True
+        summary = store.read_summary()
+        assert summary is not None
+        assert summary["execution_count"] == 1
+
+    def test_list_agents_with_metrics(self, project_dir: Path):
+        MetricsStore(project_dir, "tdd-workflow").scaffold()
+        MetricsStore(project_dir, "coach").append({"success": True})
+
+        agents = MetricsStore.list_agents(project_dir)
+
+        assert agents == ["coach", "tdd-workflow"]
+
+    def test_default_retention_matches_adr(self):
+        assert DEFAULT_RETENTION_DAYS == 180

tests/test_metrics_cli.py

@@ -0,0 +1,157 @@
+"""CLI tests for project-scoped metrics commands."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+from kaizen_agentic.cli import cli
+
+
+@pytest.fixture
+def runner() -> CliRunner:
+    return CliRunner()
+
+
+@pytest.fixture
+def project_dir(tmp_path: Path) -> Path:
+    root = tmp_path / "demo-project"
+    root.mkdir()
+    return root
+
+
+class TestMetricsCli:
+    def test_record_show_list_export_flow(self, runner: CliRunner, project_dir: Path):
+        target = str(project_dir)
+
+        record = runner.invoke(
+            cli,
+            [
+                "metrics",
+                "record",
+                "tdd-workflow",
+                "--target",
+                target,
+                "--success",
+                "--time",
+                "42",
+                "--quality",
+                "0.85",
+            ],
+        )
+        assert record.exit_code == 0
+        assert "Recorded metrics" in record.output
+
+        show = runner.invoke(
+            cli, ["metrics", "show", "tdd-workflow", "--target", target]
+        )
+        assert show.exit_code == 0
+        assert '"execution_count": 1' in show.output
+        assert '"success": true' in show.output
+
+        listed = runner.invoke(cli, ["metrics", "list", "--target", target])
+        assert listed.exit_code == 0
+        assert "tdd-workflow" in listed.output
+
+        export = runner.invoke(
+            cli, ["metrics", "export", "tdd-workflow", "--target", target]
+        )
+        assert export.exit_code == 0
+        lines = [line for line in export.output.splitlines() if line.strip()]
+        assert len(lines) == 1
+        assert json.loads(lines[0])["quality_score"] == 0.85
+
+    def test_record_json_from_stdin(self, runner: CliRunner, project_dir: Path):
+        payload = json.dumps({"success": False, "execution_time_s": 9.5})
+        result = runner.invoke(
+            cli,
+            ["metrics", "record", "coach", "--target", str(project_dir), "--json"],
+            input=payload,
+        )
+        assert result.exit_code == 0
+
+        show = runner.invoke(
+            cli, ["metrics", "show", "coach", "--target", str(project_dir)]
+        )
+        assert '"success": false' in show.output
+
+    def test_record_idempotency_key_skips_duplicate(
+        self, runner: CliRunner, project_dir: Path
+    ):
+        args = [
+            "metrics",
+            "record",
+            "coach",
+            "--target",
+            str(project_dir),
+            "--success",
+            "--idempotency-key",
+            "sess-abc",
+        ]
+        first = runner.invoke(cli, args)
+        second = runner.invoke(cli, args)
+        assert first.exit_code == 0
+        assert second.exit_code == 0
+        assert "Skipped duplicate" in second.output
+
+        export = runner.invoke(
+            cli, ["metrics", "export", "coach", "--target", str(project_dir)]
+        )
+        assert len(export.output.strip().splitlines()) == 1
+
+    def test_record_requires_outcome_without_json(
+        self, runner: CliRunner, project_dir: Path
+    ):
+        result = runner.invoke(
+            cli,
+            ["metrics", "record", "tdd-workflow", "--target", str(project_dir)],
+        )
+        assert result.exit_code != 0
+        assert "--success or --failure" in result.output
+
+    def test_memory_init_scaffolds_metrics(self, runner: CliRunner, project_dir: Path):
+        result = runner.invoke(
+            cli,
+            ["memory", "init", "tdd-workflow", "--target", str(project_dir)],
+        )
+        assert result.exit_code == 0
+        metrics_dir = project_dir / ".kaizen" / "metrics" / "tdd-workflow"
+        assert metrics_dir.exists()
+        assert (metrics_dir / "executions.jsonl").exists()
+
+    def test_memory_brief_includes_performance_summary(
+        self, runner: CliRunner, project_dir: Path
+    ):
+        target = str(project_dir)
+        runner.invoke(cli, ["memory", "init", "tdd-workflow", "--target", target])
+        runner.invoke(
+            cli,
+            [
+                "metrics",
+                "record",
+                "tdd-workflow",
+                "--target",
+                target,
+                "--success",
+                "--quality",
+                "0.9",
+            ],
+        )
+
+        result = runner.invoke(
+            cli, ["memory", "brief", "tdd-workflow", "--target", target]
+        )
+        assert result.exit_code == 0
+        assert "## Performance Summary" in result.output
+        assert "Success rate: 100.0%" in result.output
+
+    def test_memory_init_no_metrics_flag(self, runner: CliRunner, project_dir: Path):
+        result = runner.invoke(
+            cli,
+            ["memory", "init", "coach", "--target", str(project_dir), "--no-metrics"],
+        )
+        assert result.exit_code == 0
+        assert not (project_dir / ".kaizen" / "metrics" / "coach").exists()

tests/test_metrics_publish.py

@@ -0,0 +1,142 @@
+"""Tests for artifact-store publish integration (WP-0004 Part 3)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+from click.testing import CliRunner
+
+from kaizen_agentic.cli import cli
+from kaizen_agentic.integrations.artifact_store import (
+    PublishResult,
+    build_optimizer_manifest,
+    publish_optimizer_evidence,
+)
+from kaizen_agentic.metrics import OptimizerStore
+
+
+@pytest.fixture
+def project_with_optimizer(tmp_path: Path) -> Path:
+    store = OptimizerStore(tmp_path)
+    store.write_analysis(
+        {
+            "project": "demo",
+            "optimized_at": "2026-06-18",
+            "agents": [{"agent": "tdd-workflow"}],
+        }
+    )
+    store.append_recommendations(
+        "tdd-workflow",
+        [{"type": "reliability", "message": "Improve test stability"}],
+        metrics_count=10,
+    )
+    return tmp_path
+
+
+def test_build_optimizer_manifest(project_with_optimizer: Path):
+    manifest = build_optimizer_manifest(project_with_optimizer)
+    assert manifest["schema"] == "kaizen-agentic/optimizer-evidence/v1"
+    assert manifest["retention_class"] == "raw-evidence"
+    assert manifest["retention_days"] == 180
+    assert "tdd-workflow" in manifest["agents"]
+
+
+def test_publish_optimizer_evidence_calls_api(project_with_optimizer: Path):
+    calls: list[tuple[str, str]] = []
+
+    def fake_json(method, base_url, path, token, payload):
+        calls.append((method, path))
+        if path == "/packages":
+            return {"id": "pkg-123"}
+        if path.endswith("/finalize"):
+            return {"id": "pkg-123", "manifest_digest": "blake3:deadbeef"}
+        raise AssertionError(path)
+
+    def fake_multipart(base_url, path, token, **kwargs):
+        calls.append(("POST", path))
+        return {"id": "file-1"}
+
+    with patch(
+        "kaizen_agentic.integrations.artifact_store._http_json",
+        side_effect=fake_json,
+    ), patch(
+        "kaizen_agentic.integrations.artifact_store._http_multipart",
+        side_effect=fake_multipart,
+    ):
+        result = publish_optimizer_evidence(
+            project_with_optimizer,
+            api_url="http://api.test",
+            token="secret",
+        )
+
+    assert result.package_id == "pkg-123"
+    assert result.files_uploaded == 2
+    assert result.retention_class == "raw-evidence"
+    assert calls[0] == ("POST", "/packages")
+    assert any("/files" in path for _, path in calls)
+    assert calls[-1] == ("POST", "/packages/pkg-123/finalize")
+
+
+class TestMetricsPublishCli:
+    def test_publish_requires_token(self, project_with_optimizer: Path):
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            ["metrics", "publish", "--target", str(project_with_optimizer)],
+        )
+        assert result.exit_code != 0
+        assert "token" in result.output.lower()
+
+    def test_publish_success(self, project_with_optimizer: Path):
+        runner = CliRunner()
+        with patch(
+            "kaizen_agentic.cli.publish_optimizer_evidence",
+            return_value=PublishResult(
+                package_id="pkg-99",
+                manifest_digest="blake3:abc",
+                files_uploaded=2,
+                retention_class="raw-evidence",
+            ),
+        ):
+            result = runner.invoke(
+                cli,
+                [
+                    "metrics",
+                    "publish",
+                    "--target",
+                    str(project_with_optimizer),
+                    "--token",
+                    "test-token",
+                    "--api-url",
+                    "http://127.0.0.1:8000",
+                ],
+            )
+        assert result.exit_code == 0
+        assert "pkg-99" in result.output
+
+
+@pytest.mark.integration
+def test_publish_against_live_artifact_store(project_with_optimizer: Path):
+    """Optional live test — skipped when artifact-store is unreachable."""
+    import urllib.error
+    import urllib.request
+
+    api_url = "http://127.0.0.1:8000"
+    try:
+        urllib.request.urlopen(f"{api_url}/health", timeout=2)
+    except (urllib.error.URLError, TimeoutError):
+        pytest.skip("artifact-store not reachable")
+
+    token = __import__("os").environ.get("ARTIFACTSTORE_API_TOKEN")
+    if not token:
+        pytest.skip("ARTIFACTSTORE_API_TOKEN not set")
+
+    result = publish_optimizer_evidence(
+        project_with_optimizer,
+        api_url=api_url,
+        token=token,
+    )
+    assert result.package_id
+    assert result.files_uploaded >= 1

tests/test_optimization_metrics.py

@@ -0,0 +1,138 @@
+"""Tests for OptimizationLoop integration with MetricsStore."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+from kaizen_agentic.cli import cli
+from kaizen_agentic.metrics import MetricsStore, OptimizerStore
+from kaizen_agentic.optimization import (
+    MIN_SAMPLES_FOR_RECOMMENDATIONS,
+    OptimizationLoop,
+)
+
+
+def _seed_executions(
+    store: MetricsStore,
+    count: int,
+    *,
+    success: bool = True,
+    execution_time_s: float = 5.0,
+    quality_score: float = 0.9,
+) -> None:
+    for i in range(count):
+        store.append(
+            {
+                "success": success,
+                "execution_time_s": execution_time_s + i,
+                "quality_score": quality_score,
+            },
+            idempotency_key=f"run-{i}",
+        )
+
+
+@pytest.fixture
+def project_dir(tmp_path: Path) -> Path:
+    root = tmp_path / "demo-project"
+    root.mkdir()
+    return root
+
+
+class TestOptimizationFromMetricsStore:
+    def test_from_metrics_store_loads_execution_records(self, project_dir: Path):
+        store = MetricsStore(project_dir, "tdd-workflow")
+        _seed_executions(store, 3)
+
+        loop = OptimizationLoop.from_metrics_store(store)
+
+        assert len(loop.metrics_history) == 3
+        assert loop.metrics_history[0].success_rate == 1.0
+
+    def test_insufficient_data_recommendations(self, project_dir: Path):
+        store = MetricsStore(project_dir, "tdd-workflow")
+        loop = OptimizationLoop.from_metrics_store(store)
+
+        recommendations = loop.generate_improvement_recommendations()
+
+        assert recommendations[0]["type"] == "info"
+        assert "Insufficient data" in recommendations[0]["message"]
+
+    def test_sufficient_data_produces_performance_recommendations(
+        self, project_dir: Path
+    ):
+        store = MetricsStore(project_dir, "tdd-workflow")
+        _seed_executions(
+            store,
+            MIN_SAMPLES_FOR_RECOMMENDATIONS,
+            success=False,
+            execution_time_s=60.0,
+            quality_score=0.4,
+        )
+
+        loop = OptimizationLoop.from_metrics_store(store)
+        recommendations = loop.generate_improvement_recommendations()
+        types = {item["type"] for item in recommendations}
+
+        assert "info" not in types
+        assert "reliability" in types or "quality" in types or "performance" in types
+
+    def test_get_optimization_report_json_is_serializable(self, project_dir: Path):
+        import json
+
+        store = MetricsStore(project_dir, "coach")
+        _seed_executions(store, 4)
+
+        report = OptimizationLoop.from_metrics_store(
+            store
+        ).get_optimization_report_json()
+        json.dumps(report)
+
+
+class TestMetricsOptimizeCli:
+    def test_optimize_insufficient_samples_writes_analysis_only(
+        self, project_dir: Path
+    ):
+        store = MetricsStore(project_dir, "tdd-workflow")
+        _seed_executions(store, 2)
+
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            ["metrics", "optimize", "tdd-workflow", "--target", str(project_dir)],
+        )
+
+        assert result.exit_code == 0
+        assert "need 10" in result.output
+        optimizer = OptimizerStore(project_dir)
+        assert optimizer.analysis_path.exists()
+        assert not optimizer.recommendations_path.exists()
+
+    def test_optimize_sufficient_samples_writes_recommendations(
+        self, project_dir: Path
+    ):
+        store = MetricsStore(project_dir, "tdd-workflow")
+        _seed_executions(
+            store,
+            MIN_SAMPLES_FOR_RECOMMENDATIONS,
+            success=False,
+            execution_time_s=60.0,
+            quality_score=0.4,
+        )
+
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            ["metrics", "optimize", "tdd-workflow", "--target", str(project_dir)],
+        )
+
+        assert result.exit_code == 0
+        optimizer = OptimizerStore(project_dir)
+        assert optimizer.analysis_path.exists()
+        assert optimizer.recommendations_path.exists()
+        assert (
+            '"type": "reliability"' in result.output
+            or '"type": "quality"' in result.output
+        )

tests/test_path_compat.py

@@ -0,0 +1,19 @@
+"""Cross-platform path handling smoke tests (WP-0001 T07)."""
+
+from __future__ import annotations
+
+from pathlib import Path, PureWindowsPath
+
+from kaizen_agentic.metrics import MetricsStore
+
+
+def test_metrics_store_accepts_string_project_root(tmp_path: Path):
+    store = MetricsStore(str(tmp_path), "coach")
+    store.append({"success": True}, idempotency_key="win-path-test")
+    assert store.executions_path.exists()
+
+
+def test_metrics_paths_use_forward_join_semantics(tmp_path: Path):
+    store = MetricsStore(tmp_path, "tdd-workflow")
+    suffix = PureWindowsPath(".kaizen/metrics/tdd-workflow/executions.jsonl")
+    assert store.executions_path.as_posix().endswith(suffix.as_posix())

tests/test_registry.py

@@ -53,9 +53,9 @@ description: Second test agent
 
     registry = AgentRegistry(tmp_path)
 
-    assert len(registry._agents) == 2
-    assert "agent-one" in registry._agents
-    assert "agent-two" in registry._agents
+    assert registry.agent_names() == ["agent-one", "agent-two"]
+    assert registry.get_agent("agent-one") is not None
+    assert registry.get_agent("agent-two") is not None
 
 
 def test_agent_registry_get_agent(tmp_path):

tests/test_registry_lazy_load.py

@@ -0,0 +1,79 @@
+"""Registry lazy-loading performance tests (WP-0001 T06)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from kaizen_agentic.installer import AgentInstaller, InstallationConfig
+from kaizen_agentic.registry import AgentDefinition, AgentRegistry
+
+
+def _write_agent(path: Path, name: str) -> None:
+    path.write_text(
+        f"""---
+name: {name}
+description: Agent {name}
+category: testing
+---
+
+# {name}
+""",
+        encoding="utf-8",
+    )
+
+
+@pytest.fixture
+def large_registry(tmp_path: Path) -> AgentRegistry:
+    agents_dir = tmp_path / "agents"
+    agents_dir.mkdir()
+    for index in range(15):
+        _write_agent(agents_dir / f"agent-agent-{index}.md", f"agent-{index}")
+    _write_agent(agents_dir / "agent-tdd-workflow.md", "tdd-workflow")
+    return AgentRegistry(agents_dir)
+
+
+def test_registry_indexes_without_full_parse(large_registry: AgentRegistry):
+    assert len(large_registry.agent_names()) == 16
+    assert large_registry._agents == {}
+
+
+def test_get_agent_loads_only_requested_agent(large_registry: AgentRegistry):
+    with patch.object(
+        AgentDefinition,
+        "from_file",
+        wraps=AgentDefinition.from_file,
+    ) as mock_from_file:
+        agent = large_registry.get_agent("tdd-workflow")
+
+    assert agent is not None
+    assert agent.name == "tdd-workflow"
+    assert mock_from_file.call_count == 1
+
+
+def test_install_single_agent_parses_minimal_subset(
+    large_registry: AgentRegistry, tmp_path: Path
+):
+    installer = AgentInstaller(large_registry)
+    project_dir = tmp_path / "project"
+
+    with patch.object(
+        AgentDefinition,
+        "from_file",
+        wraps=AgentDefinition.from_file,
+    ) as mock_from_file:
+        results = installer.install_agents(
+            ["tdd-workflow"],
+            InstallationConfig(
+                target_dir=project_dir,
+                create_backup=False,
+                update_docs=False,
+            ),
+        )
+
+    assert results["tdd-workflow"] == "INSTALLED"
+    assert (project_dir / "agents" / "agent-tdd-workflow.md").exists()
+    # resolve_dependencies loads only the target agent, not the full fleet
+    assert mock_from_file.call_count == 1

wiki/AboutKaizenAgents.md

@@ -0,0 +1,76 @@
+# About Kaizen Agents
+
+Basic concepts of Kaizen Agents.
+
+All Kaizen Agents follow the [KaizenAgentTemplate](KaizenAgentTemplate.md) definition.
+That template provides a comprehensive structure for defining Kaizen Agent subagents.
+
+Key sections:
+
+- **Specification** — declarative outcomes rather than implementation steps
+- **Idempotency design** — detect and handle already-completed work
+- **Metrics** — measurable success criteria from day one
+- **Testing** — scenarios that feed the optimization loop
+- **Evolution tracking** — improvement history and performance trends
+
+The template enforces separation of concerns, testability, and measurability while
+keeping agent definitions consistent across the fleet.
+
+---
+
+## Metrics-enabled pilot: `tdd-workflow`
+
+`tdd-workflow` is the reference implementation for project-scoped metrics (WP-0003).
+Use it as a template when adding metrics to other agents.
+
+### What is measured
+
+| Metric | Role | How |
+|--------|------|-----|
+| `test_pass_rate` | Primary | Passing tests ÷ total tests at PUBLISH (target: 1.0) |
+| `cycle_time_s` | Secondary | Session duration (`execution_time_s` in ADR-004) |
+
+Definitions live in the agent frontmatter (`agents/agent-tdd-workflow.md`).
+
+### Where data lives
+
+```
+<project>/.kaizen/metrics/tdd-workflow/
+  executions.jsonl    # append-only per-session records
+  summary.json        # rolling aggregates (auto-generated)
+```
+
+Scaffolded by `kaizen-agentic memory init tdd-workflow` alongside
+`.kaizen/agents/tdd-workflow/memory.md`.
+
+### Session-close loop
+
+At the end of each TDD8 session:
+
+1. Update qualitative memory (`## Session Log`, findings, watch points).
+2. Record quantitative outcome:
+
+```bash
+kaizen-agentic metrics record tdd-workflow --success --time <seconds> --quality <0.0-1.0>
+```
+
+Or pass a full ADR-004 record with `primary_metric` via `--json` (see agent spec).
+
+### Analysis and orientation
+
+| Command | Purpose |
+|---------|---------|
+| `kaizen-agentic metrics show tdd-workflow` | Summary + recent executions |
+| `kaizen-agentic metrics optimize tdd-workflow` | Evidence-based recommendations (≥10 records) |
+| `kaizen-agentic memory brief tdd-workflow` | Qualitative memory + `## Performance Summary` |
+
+Fleet-level session analytics remain in **agentic-resources** (Helix Forge); project
+metrics stay in `.kaizen/metrics/` per [ADR-004](../docs/adr/ADR-004-project-metrics-convention.md)
+and [EcosystemIntegration](EcosystemIntegration.md).
+
+### Adopting metrics on another agent
+
+1. Add a `metrics:` block to frontmatter (primary + secondary + collection).
+2. Copy the session-close `metrics record` step from `agent-tdd-workflow.md`.
+3. Run `kaizen-agentic memory init <agent>` to scaffold storage.
+4. Verify with `metrics show` after one session.

wiki/AgentKaizenOptimizer.md

@@ -0,0 +1,248 @@
+AgentKaizenOptimizer
+
+*One agent to improve them all*
+
+# KaizenAgent Meta-Optimizer
+# Version: 1.0.0
+# Last Updated: 2025-09-26
+
+agent:
+  name: "kaizen-optimizer"
+  version: "1.0.0"
+  description: "Meta-agent that analyzes and optimizes other coding subagents based on performance data"
+  
+  # Core Specification
+  specification:
+    purpose: |
+      Continuously improve coding subagents by analyzing their performance metrics,
+      identifying patterns that correlate with success or failure, and proposing
+      data-driven refinements to agent specifications. Acts as the optimization
+      engine in the KaizenAgent feedback loop.
+    
+    triggers:
+      patterns:
+        - "Scheduled optimization runs (daily/weekly)"
+        - "Performance threshold violations"
+        - "Minimum data collection thresholds reached"
+        - "Explicit optimization requests"
+      
+      explicit_commands:
+        - "claude code --optimize-agents"
+        - "claude code --kaizen-review"
+        - "claude code --agent-performance"
+    
+    inputs:
+      required:
+        - name: "performance_data"
+          type: "object"
+          description: "Aggregated metrics from all subagents over time period"
+        - name: "agent_definitions"
+          type: "array"
+          description: "Current specifications of all registered agents"
+      
+      optional:
+        - name: "optimization_focus"
+          type: "string"
+          default: "all"
+          description: "Specific agent or metric to optimize"
+        - name: "time_window"
+          type: "string"
+          default: "30d"
+          description: "Historical data window to analyze"
+        - name: "confidence_threshold"
+          type: "float"
+          default: 0.8
+          description: "Minimum confidence level for proposing changes"
+    
+    outputs:
+      primary:
+        type: "object"
+        description: "Optimization recommendations with supporting data"
+      
+      side_effects:
+        - "Updated agent specification files (if approved)"
+        - "Performance analysis reports"
+        - "A/B test configurations"
+        - "Rollback checkpoints"
+    
+    preconditions:
+      - "At least 10 execution samples per agent being analyzed"
+      - "Valid performance data with timestamps"
+      - "Agent definitions follow KaizenAgent template structure"
+    
+    postconditions:
+      - "All recommendations include confidence scores and evidence"
+      - "Proposed changes maintain backward compatibility"
+      - "Rollback plan exists for each proposed change"
+
+  # Idempotency Design
+  idempotency:
+    strategy: "fingerprint"
+    
+    state_detection:
+      method: "Hash performance data and agent versions to detect changes"
+      implementation: |
+        # Generate fingerprint of current state
+        data_hash = hash(performance_data + agent_versions + config)
+        last_analysis = load_checkpoint('last_optimization_hash')
+        
+        if data_hash == last_analysis.hash:
+          return last_analysis.recommendations
+        
+        # New data available, proceed with analysis
+        recommendations = analyze_and_optimize()
+        save_checkpoint('last_optimization_hash', {
+          hash: data_hash,
+          timestamp: now(),
+          recommendations: recommendations
+        })
+        return recommendations
+    
+    rollback:
+      supported: true
+      method: "Restore previous agent specification versions from git history"
+
+  # Performance Measurement
+  metrics:
+    primary:
+      name: "optimization_impact"
+      description: "Average performance improvement of optimized agents"
+      measurement: "Mean delta of primary metrics before/after optimization"
+      target: ">5% improvement in agent success rates"
+    
+    secondary:
+      - name: "prediction_accuracy"
+        description: "How often optimization predictions prove correct"
+        measurement: "% of recommendations that improve target metrics"
+      
+      - name: "false_positive_rate"
+        description: "Rate of recommendations that worsen performance"
+        measurement: "% of changes that decrease agent effectiveness"
+      
+      - name: "coverage"
+        description: "Percentage of agents with actionable insights"
+        measurement: "Count of agents with recommendations / total agents"
+    
+    collection:
+      frequency: "per_execution"
+      storage: ".kaizen/metrics/optimizer/"
+      retention: "180d"
+
+  # Testing and Validation
+  testing:
+    unit_tests:
+      - scenario: "Pattern detection with synthetic data"
+        input: "Mock performance data with known patterns"
+        expected_output: "Correct identification of improvement opportunities"
+        verification: "Assert detected patterns match expected patterns"
+      
+      - scenario: "Confidence scoring accuracy"
+        input: "Historical data with known outcomes"
+        expected_output: "Confidence scores correlate with actual success"
+        verification: "ROC curve analysis of confidence vs outcome"
+    
+    integration_tests:
+      - scenario: "End-to-end optimization cycle"
+        setup: "Real agent with declining performance"
+        execution: "Run optimization and apply recommendations"
+        validation: "Verify improved performance in subsequent runs"
+      
+      - scenario: "Rollback mechanism"
+        setup: "Apply optimization that worsens performance"
+        execution: "Trigger automatic rollback"
+        validation: "Agent returns to previous performance level"
+    
+    performance_tests:
+      - scenario: "Large dataset analysis"
+        load: "1000+ agent executions across 20+ agents"
+        max_time: "60 seconds"
+        resource_limits: "Max 512MB memory usage"
+
+  # Dependencies and Context
+  dependencies:
+    system:
+      - "Python 3.8+ with pandas, scikit-learn"
+      - "Git for version control"
+      - "Access to .kaizen/metrics/ directory"
+    
+    project:
+      - ".kaizen/agents/ directory with agent definitions"
+      - ".kaizen/metrics/ directory with historical data"
+      - "Valid KaizenAgent project structure"
+    
+    other_agents:
+      - name: "all_subagents"
+        relationship: "analyzes"
+        reason: "Requires performance data from all other agents"
+
+  # Configuration
+  configuration:
+    defaults:
+      analysis_algorithms: ["correlation", "regression", "decision_tree"]
+      min_sample_size: 10
+      significance_threshold: 0.05
+      optimization_frequency: "weekly"
+    
+    project_overrides:
+      path: ".kaizen/agents/kaizen-optimizer.yml"
+      schema: |
+        {
+          "type": "object",
+          "properties": {
+            "algorithms": {"type": "array"},
+            "thresholds": {"type": "object"},
+            "scheduling": {"type": "object"}
+          }
+        }
+    
+    environment_variables:
+      - name: "KAIZEN_OPTIMIZER_CONFIG"
+        description: "JSON configuration for optimization parameters"
+
+  # Evolution Tracking
+  optimization:
+    baseline_performance:
+      established: "2025-09-26"
+      metrics: {
+        "optimization_impact": 0.0,
+        "prediction_accuracy": 0.5,
+        "false_positive_rate": 1.0,
+        "coverage": 0.0
+      }
+    
+    improvement_history: []
+    
+    known_limitations:
+      - "Requires minimum sample sizes to generate reliable insights"
+      - "May not detect complex multi-agent interaction patterns"
+      - "Limited to metrics explicitly defined in agent specifications"
+      - "Cannot optimize for subjective developer experience factors"
+    
+    kaizen_notes:
+      optimization_priority: "high"
+      next_experiment: "Implement ensemble methods for pattern detection"
+      success_criteria: "Achieve >80% prediction accuracy with <10% false positive rate"
+
+  # Algorithm Specifications
+  algorithms:
+    correlation_analysis:
+      description: "Identify specification elements that correlate with performance"
+      inputs: ["performance_metrics", "agent_configs", "execution_context"]
+      outputs: ["correlation_matrix", "significant_factors"]
+    
+    performance_regression:
+      description: "Model performance trends over time and agent versions"
+      inputs: ["time_series_data", "version_history"]
+      outputs: ["trend_analysis", "degradation_alerts"]
+    
+    specification_diffing:
+      description: "Compare high vs low performing agent variants"
+      inputs: ["agent_definitions", "performance_clusters"]
+      outputs: ["diff_analysis", "success_patterns"]
+    
+    a_b_test_design:
+      description: "Generate controlled experiments for proposed changes"
+      inputs: ["current_spec", "proposed_changes"]
+      outputs: ["experiment_config", "success_metrics"]
+
+xxx

wiki/BrandBook.md

@@ -0,0 +1,156 @@
+BrandBook
+
+*The KaizenAgentic visual style*
+
+# KaizenAgentic Brandbook
+
+**Version 0.1 · September 2025**
+
+---
+
+## 1. Brand Essence
+
+**Tagline**: *Continuous Improvement for Digital Talent*
+
+**Core Idea**:
+KaizenAgentic applies the principle of *kaizen* to AI subagents. We represent AI assistants not as static tools, but as digital talents — continuously measured, refined, and optimized.
+
+**Tone**:
+
+* Minimal
+* Professional
+* Confident
+* Forward-looking
+
+---
+
+## 2. Logo System
+
+### Primary Logo (Wordmark)
+
+* **Text**: `KAIZEN▲GENTIC`
+* Typeface: modern grotesk sans-serif (Inter / Helvetica Neue recommended)
+* Weight: Bold
+* Case: ALL CAPS
+* Color: Black on white background (default)
+
+### Secondary Logo (Monogram)
+
+* **Form**: `K▲`
+* The triangle represents *improvement* and *direction upward*.
+* Used for: favicon, app icon, social avatar, watermark.
+
+### Clearspace & Minimum Size
+
+* Maintain at least **1x the height of the "K"** as safe space around the logo.
+* Wordmark: minimum width 160px.
+* Monogram: minimum width 32px.
+
+---
+
+## 3. Color Palette
+
+Primary Colors
+
+Black: #111111
+
+White: #FFFFFF
+
+Accent (Welding Blue)
+
+Electric Arc Blue: #007BFF (base tone)
+
+Arc Glow Gradient:
+
+Core Glow: #00A2FF
+
+Mid Tone: #007BFF
+
+Edge Burn: #0033CC
+
+**Usage**
+
+Use flat Electric Arc Blue (#007BFF) for clean digital presence.
+
+For special treatments (logos, hero graphics), use the arc glow gradient to mimic the intensity of molten metal light.
+
+Limit glow to accents (monogram ▲ or underline strokes), keep wordmark monochrome for contrast.
+
+
+* Wordmark = Black or White (depending on background).
+* Monogram = Black or White with Electric Blue accent on ▲.
+* Electric Blue is only used as an accent to emphasize improvement / action.
+
+---
+
+## 4. Typography
+
+**Primary Typeface**
+
+* **Inter** (open source, modern grotesk)
+* Alternatives: Helvetica Neue, Neue Haas Grotesk
+
+**Styles**
+
+* **Headings**: Bold, ALL CAPS
+* **Body text**: Regular, Sentence case
+* **Tracking**: +2% (tight but legible)
+
+---
+
+## 5. Applications
+
+### Digital
+
+* **Website header**: Wordmark in Black, hover states in Electric Blue.
+* **App icon**: Monogram K▲, triangle in Electric Blue.
+* **Dark mode**: White wordmark on black background; Electric Blue accents.
+
+### Print
+
+* Business cards:
+
+  * Front: Wordmark centered, Black on White.
+  * Back: Monogram K▲, Electric Blue triangle.
+
+### Social Media
+
+* Avatar: Monogram K▲.
+* Banner: Wordmark with subtle Electric Blue line or step motif.
+
+---
+
+## 6. Visual Motifs
+
+* **Step Progression (▮▮▮▮▮)**: Suggests incremental kaizen improvement.
+* **Triangle (▲)**: Direction, growth, precision.
+* **Minimal Layouts**: White space is part of the identity.
+
+---
+
+## 7. Voice & Messaging
+
+**Voice**:
+
+* Confident but not loud.
+* Analytical, precise, and professional.
+* Future-oriented, emphasizing *measurable improvement*.
+
+**Do Say**:
+
+* *Continuous improvement in AI talent*
+* *Optimization through measurement*
+* *Agents that evolve with you*
+
+**Don’t Say**:
+
+* *Magic black box AI*
+* *One-and-done automation*
+* *Trendy gimmicks*
+
+---
+
+### Monogram K▲ (Electric Blue accent)
+
+
+xxx

wiki/ComposableCapability.md

@@ -0,0 +1,17 @@
+ComposableCapability
+
+*Standard for self-contained units of operational knowledge*
+
+# Conceptual Foundation: ComposableCapabilities
+
+## Core Idea
+
+A **Composable Capability** is a self-contained unit of reusable functionality — a modular building block that encapsulates not just code, but also *intent*, *interfaces*, and *knowledge*.
+Each capability is organized as a repository and can be composed with others to build higher-level systems or workflows.
+
+Motivation
+
+In AI-assisted or “Vibe Coding” workflows, it’s not enough to reuse functions or APIs. You need *contextually complete* units — something that captures *how* to use a function, **why** it exists, and **what it depends on**.
+ComposableCapabilities turn code reuse into *knowledge reuse*.
+
+xxx

wiki/EcosystemIntegration.md

@@ -0,0 +1,197 @@
+# Ecosystem Integration
+
+*How KaizenAgentic composes with adjacent repositories*
+
+KaizenAgentic (`INTENT.md`) defines a **meta-improvement layer** for coding
+agents. No single repository implements the full vision. This document describes
+the **two-layer measurement model** and integration contracts with ecosystem
+repos.
+
+---
+
+## Two-Layer Measurement Model
+
+| Layer | Question answered | Owner | Storage |
+|-------|-------------------|-------|---------|
+| **Project** | How is this *agent persona* performing in *this repo*? | kaizen-agentic | `.kaizen/metrics/<agent>/` |
+| **Fleet** | How are coding sessions performing *across repos*? | agentic-resources | Helix Forge digest store + baselines |
+
+```
+  Coding session (Claude / Codex / Grok)
+           │
+           ├──────────────────────────────────────┐
+           ▼                                      ▼
+  agentic-resources                      kaizen-agentic
+  (Helix Forge)                          (session close)
+  Capture → Digest → Fleet metrics     metrics record → executions.jsonl
+           │                                      │
+           └──────── helix_session_uid ───────────┘
+                         (optional link)
+```
+
+### When to use which layer
+
+- **Project metrics** — optimizer recommendations, Coach briefs, per-agent
+  kaizen loop in one codebase (ADR-004).
+- **Fleet metrics** — cross-repo friction analysis, pattern distribution,
+  weekly retro, tooling decisions (Helix Forge PRD).
+
+Kaizen-agentic does not re-implement session JSONL ingestion. It may **cite**
+Helix session UIDs on project execution records for correlation.
+
+---
+
+## Integration Partners
+
+### agentic-resources (P0)
+
+**Helix Forge** — session capture, fleet aggregates, baselines, weekly retro.
+
+| KaizenAgentic | Helix Forge |
+|---------------|-------------|
+| `.kaizen/metrics/<agent>/executions.jsonl` | Digest store + `measure/baselines.jsonl` |
+| Per-agent persona outcomes | Per-session cross-repo outcomes |
+| `kaizen-agentic metrics optimize` | `session_memory/measure/` aggregates |
+
+**Correlation fields** (ADR-004): `helix_session_uid`, `repo`, `flavor`,
+`tokens`, `infra_overhead_share`.
+
+**Workplan:** KAIZEN-WP-0004 Part 1.
+
+#### Worked example
+
+A TDD8 session captured by Helix Forge and closed with kaizen metrics:
+
+```bash
+# Helix capture sets (or operator exports) session identity
+export HELIX_SESSION_UID="claude:17092961-abc"
+export HELIX_REPO="kaizen-agentic"
+export HELIX_FLAVOR="claude"
+export HELIX_TOKENS="12500"
+
+# Session close — project layer
+kaizen-agentic metrics record tdd-workflow --success --time 4200 --quality 0.92
+
+# Inspect project record (includes correlation fields)
+kaizen-agentic metrics show tdd-workflow
+
+# Fleet lookup — read-only, no ingestion in kaizen-agentic
+export HELIX_STORE_DB=~/.helix-forge/store.db
+kaizen-agentic metrics correlate claude:17092961-abc
+```
+
+Project `executions.jsonl` carries `helix_session_uid` for audit; fleet analytics
+remain in agentic-resources digest store. Coach `memory brief` surfaces project
+`## Performance Summary`; correlate adds fleet context when needed.
+
+Contract: [docs/integrations/helix-forge-correlation.md](../docs/integrations/helix-forge-correlation.md).
+
+### activity-core (P1)
+
+**Event bridge** — scheduled and event-driven task creation.
+
+ActivityDefinition reference copies (sync into activity-core to activate):
+
+- [weekly-metrics-optimize](../docs/integrations/activity-definitions/weekly-metrics-optimize.md)
+- [post-install-metrics-scaffold](../docs/integrations/activity-definitions/post-install-metrics-scaffold.md)
+- [low-success-rate-review](../docs/integrations/activity-definitions/low-success-rate-review.md)
+
+**Workplan:** KAIZEN-WP-0004 Part 2. Patterns: [docs/INTEGRATION_PATTERNS.md](../docs/INTEGRATION_PATTERNS.md).
+
+### artifact-store (P1)
+
+**Evidence retention** — durable registry for generated outputs.
+
+Register after optimizer runs:
+
+- `optimizer/analysis.json`
+- `recommendations.jsonl` snapshots
+- E2e pilot evidence packages
+
+Retention class: `raw-evidence` (180d default, aligned with ADR-004).
+
+```bash
+kaizen-agentic metrics optimize
+kaizen-agentic metrics publish   # requires ARTIFACTSTORE_API_URL + TOKEN
+```
+
+Manifest: [docs/integrations/optimizer-artifact-manifest.md](../docs/integrations/optimizer-artifact-manifest.md).
+
+**Workplan:** KAIZEN-WP-0004 Part 3.
+
+### info-tech-canon (P2)
+
+**Semantic canon** — agent briefs, patterns, profiles, validation.
+
+- Map `KaizenAgentTemplate.md` → InfoTechCanon profile format
+- Publish compact agent briefs per persona
+- Extend `kaizen-agentic validate` with canon conformance checks
+
+**Workplan:** KAIZEN-WP-0004 Part 4.
+
+### phase-memory (P2, future)
+
+**Memory graphs** — upgrade from flat `memory.md` to phased memory profiles.
+
+- Fluid memory → project session paths
+- Stabilized memory → accumulated findings with provenance
+- Context packages for Coach brief compilation
+
+No WP-0003 blocker; plan after ecosystem integration baseline.
+
+### kontextual-engine (P2)
+
+**Knowledge operations** — ingest `wiki/` and agent definitions as governed
+assets; runtime for KaizenGuidance catalog when built.
+
+### llm-connect (P3)
+
+**LLM abstraction** — use when Coach/optimizer synthesis becomes automated
+beyond CLI context assembly. Token metrics align with wiki pricing tiers.
+
+### domain-tree (P3)
+
+Register kaizen-agentic and agent categories with primary/secondary domain
+bindings when capability catalog matures.
+
+### identity-canon (P3)
+
+Terminology for agent persona vs deployed instance vs session actor —
+supports "digital talent agency" framing without overloading "user".
+
+### tele-mcp (TBD)
+
+Listed on Forgejo; not cloned locally. Candidate telemetry MCP adapter for
+WP-0001 T04. Assess before depending on it.
+
+---
+
+## Boundary Rules
+
+1. **kaizen-agentic owns** agent definitions, `.kaizen/` conventions, CLI,
+   Coach/optimizer personas, and product framing (`INTENT.md`, `wiki/`).
+2. **kaizen-agentic does not own** session transcript ingestion, task
+   scheduling, artifact bytes, knowledge graph runtime, or LLM providers.
+3. **Integrate by contract** — ADRs, shared correlation fields, ActivityDefinitions,
+   artifact registration APIs — not by merging repos.
+4. **Evidence compounds** — fleet baselines inform tooling; project metrics
+   inform agent specs; artifact-store preserves both for audit.
+
+---
+
+## Reading Order
+
+1. `INTENT.md` — purpose and boundaries
+2. `wiki/EcosystemIntegration.md` — this document
+3. `docs/adr/ADR-004-project-metrics-convention.md` — project metrics schema
+4. `history/2026-06-16-ecosystem-assessment.md` — full repo comparison
+5. `workplans/kaizen-agentic-WP-0004-ecosystem-integration.md` — implementation plan
+
+---
+
+## Related Assessments
+
+Persisted in `history/`:
+
+- `2026-06-16-intent-gap-analysis.md`
+- `2026-06-16-ecosystem-assessment.md`

wiki/IdempotentCompounding.md

@@ -0,0 +1,112 @@
+IdempotentCompounding
+
+*Kaizen Agentic Philosophy*
+
+# IdempotentCompounding — a primer
+
+Definition (one-liner): Build and evolve systems by idempotent automation (safe to run repeatedly) and compounding increments (small units that add durable value), governed by outcomes and quality gates.
+
+## Core principles
+
+- Idempotence by default — Every operation (provision, deploy, migrate, refactor) is safe to re-run; desired state > imperative steps.
+- Compound value, not complexity — Ship small, composable capability units that stack cleanly and raise the baseline.
+- Evidence over intention — Each increment must declare its value metric and show before/after.
+- Reversibility — Fast rollback/roll-forward; changes are sliceable and isolated.
+- Sustainability as a constraint — Optimize for maintainability, cost, energy, and human time.
+- Quality is automated — Tests, checks, and drift detection run continuously, not occasionally.
+- Documentation is generated — Architecture, runbooks, and changelogs are derived from code & traces, then curated.
+
+## The operating cycle (repeatable)
+
+Select → Specify → Safeguard → Apply → Verify → Record
+
+- Select a high-ROI increment (hotspot × business value).
+- Specify desired state (declarative spec, schema, or refactor objective).
+- Safeguard with idempotent checks: contract tests, drift monitors, health probes.
+- Apply via automation (IaC, pipelines, codemods) — re-runnable end-to-end.
+- Verify outcomes (SLOs, cost, complexity, security).
+- Record: update arc42 views, ADR, and the quality dashboard.
+
+Rule of thumb: if you’re afraid to re-run it, it’s not IdempotentCompounding yet.
+
+## Units of change (the “compounders”)
+
+- Infra Module (e.g., Terraform/Kubernetes object)
+- Service Capability (feature flag, API slice)
+- Quality Guide Move (codemod + lint rule)
+- Data Contract (schema + migration + validation)
+- Ops Control (SLO, alert, autoscaler policy)
+
+Each unit carries:
+- Spec (YAML/DSL + schema)
+- Guards (tests/checks)
+- KPIs (value metric)
+- Rollbacks (delete/replace plan)
+- Docs hooks (arc42/ADR update hints)
+
+## Minimal guardrails
+
+- Idempotence test: run the job twice; expect no diff.
+- Blast-radius cap: feature flags, canaries, or scoped namespaces.
+- Drift sentry: reconcile loop or plan delta must be ≈0 after apply.
+- Budget bound: change must not breach cost/latency/error-rate budgets.
+- Timebox: if verification can’t prove value in X hours, revert or park.
+
+## Metrics that matter
+
+- Value: SLO attainment, cycle time, revenue/usage lift, defect escape rate ↓
+- Quality: Maintainability index ↑, complexity/duplication ↓, DoC compliance %
+- Sustainability: € per request ↓, watts per request ↓, toil hours ↓
+- Reliability: MTTR ↓, change failure rate ↓, successful re-runs % = 100
+
+## Tooling patterns (typical stack)
+
+- Desired state: Terraform/Pulumi, Helm/Kustomize, GitOps (Argo CD/Flux)
+- Idempotent app changes: migration frameworks, codemods (libCST/jscodeshift), OpenRewrite
+- Verification: contract & golden tests; load tests in CI for hot paths
+- Observability: traces/metrics feeding fitness functions in pipelines
+- Docs: Structurizr/PlantUML generated from code + traces; ADRs as code
+
+How it fits the AbcdekGuidance Practice
+
+A — Architecture (ArcFortyTwo): auto-generate views; define fitness functions (what “value” means).
+B — Build (SafetyNetTests): make verification idempotent; contract tests become guards.
+C — Clean (CleanByDefinition): encode idempotence rules (no side-effect scripts, reversible migrations).
+D — Direction (GamePlan): prioritize compounders with best value/effort ratio.
+E — Evolve (RefactoringLoop): codemods + tests prove idempotent repeats and measurable deltas.
+K — KeepClean (Kaizen): weekly trend checks; drift/DoC gates keep compounded value from decaying.
+
+Templates (drop-in)
+
+1) Value Ticket (per increment)
+
+Title: <Increment name>
+Desired State: <declarative spec or target structure>
+Guards: <tests/checks to pass; idempotence proof: re-run yields no diff>
+Value Metric: <name, baseline, target, window>
+Rollback: <how to undo safely>
+Docs Hooks: <arc42 sections / ADR to update>
+Owner / ETA:
+
+2) Idempotence Checklist
+
+[ ] Declarative spec exists
+[ ] Dry-run/plan produces stable diff
+[ ] Double-apply yields zero change
+[ ] Safe to parallelize or properly serialized
+[ ] Idempotent cleanup (delete/apply symmetry)
+
+## Example (brief)
+
+- Goal: Reduce p95 latency by 20% on /checkout.
+- Compounder: Add Redis read-through cache for product lookups (Helm values + code toggle).
+- Guards: Contract tests for /checkout; load test at 95th percentile; drift check on Helm release.
+- Apply: helm upgrade (safe to re-run), feature flag rollout 10%→100%.
+- Verify: p95 from 480 ms → 360 ms (7-day window), error rate unchanged.
+- Record: ADR-012, arc42 runtime view updated, dashboard shows value trend.
+
+## Bottom line 
+IdempotentCompounding turns improvement into a safe, repeatable habit: every step is re-runnable, every change compounds value, and every gain is proven.
+
+
+xxx

wiki/KaiPersonal.md

@@ -0,0 +1,7 @@
+KaiPersonal
+
+*Kaizen Personal Assistent Framework*
+
+A framework to set up, use and improve personal assistents based on agentic ai in your daily life that keeps you in charge of your data and organization without any vendor lock in.
+
+xxx

wiki/KaizenAgentTemplate.md

@@ -0,0 +1,169 @@
+KaizenAgentTemplate
+
+*This is where we build from*
+
+# KaizenAgent Definition Template
+# Version: 1.0
+# Last Updated: {timestamp}
+
+agent:
+  name: "{agent_name}"
+  version: "1.0.0"
+  description: "Brief description of agent's primary responsibility"
+  
+  # Core Specification
+  specification:
+    purpose: |
+      One paragraph describing the agent's single responsibility.
+      Focus on the desired outcome, not implementation details.
+    
+    triggers:
+      # When should this agent be invoked?
+      patterns:
+        - "File patterns that indicate this agent should run"
+        - "Keywords or context clues in requests"
+        - "Project states that require this agent"
+      
+      explicit_commands:
+        - "--agent={agent_name}"
+        - "claude code --{shorthand}"
+    
+    inputs:
+      required:
+        - name: "input_name"
+          type: "string|array|object"
+          description: "What this input represents"
+      
+      optional:
+        - name: "optional_input"
+          type: "string"
+          default: "default_value"
+          description: "Optional configuration"
+    
+    outputs:
+      primary:
+        type: "file|stdout|metadata"
+        description: "Main deliverable of the agent"
+      
+      side_effects:
+        - "Any files created or modified"
+        - "External systems touched"
+        - "State changes made"
+    
+    preconditions:
+      - "Conditions that must be true before agent runs"
+      - "Dependencies that must exist"
+    
+    postconditions:
+      - "Guaranteed state after successful execution"
+      - "Invariants that will be maintained"
+
+  # Idempotency Design
+  idempotency:
+    strategy: "convergent|checkpoint|fingerprint|state_detection"
+    
+    state_detection:
+      method: "How to check if work is already done"
+      implementation: |
+        # Pseudo-code or description of how to detect current state
+        check_current_state()
+        if (desired_state_achieved()) return current_state
+        proceed_with_transformation()
+    
+    rollback:
+      supported: true
+      method: "How to undo changes if needed"
+
+  # Performance Measurement
+  metrics:
+    primary:
+      name: "primary_success_metric"
+      description: "Most important measure of agent success"
+      measurement: "How to calculate this metric"
+      target: "Desired value or improvement threshold"
+    
+    secondary:
+      - name: "additional_metric_1"
+        description: "Secondary success indicator"
+        measurement: "Calculation method"
+      
+      - name: "additional_metric_2" 
+        description: "Quality or safety metric"
+        measurement: "How to measure"
+    
+    collection:
+      frequency: "per_execution|daily|weekly"
+      storage: "where_metrics_are_stored"
+      retention: "how_long_to_keep_data"
+
+  # Testing and Validation
+  testing:
+    unit_tests:
+      - scenario: "Test scenario description"
+        input: "Sample input data"
+        expected_output: "Expected result"
+        verification: "How to verify success"
+    
+    integration_tests:
+      - scenario: "End-to-end test scenario"
+        setup: "Required project state"
+        execution: "Commands to run"
+        validation: "Success criteria"
+    
+    performance_tests:
+      - scenario: "Performance test case"
+        load: "Input complexity/size"
+        max_time: "Acceptable execution time"
+        resource_limits: "Memory/CPU constraints"
+
+  # Dependencies and Context
+  dependencies:
+    system:
+      - "Required tools or binaries"
+      - "Environment variables needed"
+    
+    project:
+      - "Files that must exist"
+      - "Project structure assumptions"
+    
+    other_agents:
+      - name: "dependency_agent"
+        relationship: "runs_before|runs_after|collaborates"
+        reason: "Why this dependency exists"
+
+  # Configuration
+  configuration:
+    defaults:
+      key1: "default_value1"
+      key2: "default_value2"
+    
+    project_overrides:
+      path: ".kaizen/agents/{agent_name}.yml"
+      schema: "JSON schema for configuration validation"
+    
+    environment_variables:
+      - name: "KAIZEN_{AGENT_NAME}_CONFIG"
+        description: "Runtime configuration override"
+
+  # Evolution Tracking
+  optimization:
+    baseline_performance:
+      established: "{date}"
+      metrics: {}
+    
+    improvement_history:
+      - version: "1.0.1"
+        change: "Description of what was modified"
+        reason: "Why the change was made"
+        impact: "Measured improvement"
+    
+    known_limitations:
+      - "Current limitation 1"
+      - "Area for future improvement"
+    
+    kaizen_notes:
+      optimization_priority: "high|medium|low"
+      next_experiment: "Planned improvement to test"
+      success_criteria: "How to measure if experiment succeeded"
+
+xxx

wiki/KaizenAgentic.md

@@ -0,0 +1,8 @@
+KaizenAgentic
+
+*The digital talent agency*
+
+KaizenAgentic is a digital talent agency for AI coding agents. We apply the principle of kaizen—continuous improvement—to agent design, transforming coding subagents into evolving digital talents that get measurably better over time.
+
+xxx
+

wiki/KaizenAgenticIdea.md

@@ -0,0 +1,33 @@
+KaizenAgenticIdea
+
+*How it started*
+
+# Overview 
+
+KaizenAgentic provides a meta-optimization framework for continuously improving AI coding subagents through data-driven iteration. Rather than treating agent development as a one-time engineering task, KaizenAgent establishes a systematic approach to refine and evolve coding assistants based on their real-world performance. 
+
+# Core Philosophy 
+
+The project embraces the Japanese concept of "kaizen" (continuous improvement) applied to AI agent development. Every coding subagent becomes part of an optimization loop where performance is measured, patterns are analyzed, and specifications are refined over time. 
+
+# Key Components 
+
+Performance-Driven Subagents: Each coding subagent includes built-in metrics that capture meaningful performance indicators - test coverage improvements, code quality deltas, maintenance burden, and developer experience metrics. 
+
+## Meta-Optimization Engine: 
+A specialized KaizenAgent that analyzes subagent performance history, identifies improvement opportunities, and proposes specification refinements through systematic pattern analysis. Evolutionary Architecture: Agent specifications are treated as versioned, testable code that can be A/B tested, rolled back, and iteratively improved based on empirical evidence rather than intuition. 
+
+## Design Principles Measurable by Default: 
+Every subagent must define at least one quantitative success metric Idempotent Operations: All agent actions are designed to converge on desired states rather than perform blind transformations 
+
+## Separation of Concerns: 
+Clear boundaries between task-specific subagents, performance measurement, and optimization logic 
+
+##Test-First Development: 
+Agent improvements are validated through controlled experiments before deployment 
+
+# Target Use Case 
+
+Designing and optimizing agents for coding task, that can be used with claude, cursor and other coding agent systems to improve software development workflows, enabling coding assistants that genuinely improve over time through systematic observation and refinement of their real-world effectiveness.
+
+xxx

wiki/KaizenAgenticMission.md

@@ -0,0 +1,70 @@
+KaizenAgenticMission
+
+*Kaizen Agentic in a nutshell*
+
+# KaizenAgentic
+
+**Mission**
+KaizenAgentic is a digital talent agency for AI coding agents. We apply the principle of *kaizen*—continuous improvement—to agent design, transforming coding subagents into evolving digital talents that get measurably better over time.
+
+---
+
+## Overview
+
+Traditional AI agent development is often a one-off engineering project: design once, deploy, and hope it works. KaizenAgentic takes a different path. We provide a **meta-optimization framework** that treats agent development as an iterative lifecycle. Every coding subagent is continuously observed, evaluated, and refined based on real-world performance data.
+
+---
+
+## Core Philosophy
+
+* **Continuous Improvement**: Inspired by Japanese kaizen, every agent is part of an optimization loop.
+* **Data-Driven Evolution**: Decisions are grounded in metrics, not intuition.
+* **Systematic Refinement**: Performance history, usage patterns, and experimental results drive specification updates.
+
+---
+
+## Key Components
+
+### 1. Performance-Driven Subagents
+
+Every coding subagent comes with **built-in metrics**:
+
+* Test coverage improvements
+* Code quality deltas
+* Maintenance burden
+* Developer experience signals
+
+### 2. Meta-Optimization Engine
+
+A specialized **KaizenAgent** analyzes performance logs, spots recurring improvement opportunities, and proposes refined specifications.
+
+### 3. Evolutionary Architecture
+
+Agent specifications are treated like code:
+
+* Versioned
+* Testable
+* A/B tested in real workflows
+* Rollback-ready
+
+---
+
+## Design Principles
+
+* **Measurable by Default**: Every subagent defines quantitative success criteria.
+* **Idempotent Operations**: Actions converge toward desired states instead of introducing uncontrolled drift.
+* **Separation of Concerns**: Subagents focus on tasks; optimization logic stays independent.
+* **Test-First Improvement**: New refinements are validated through controlled experiments before rollout.
+
+---
+
+## Target Use Case
+
+KaizenAgentic focuses on **coding task optimization**. Our refined subagents integrate with platforms like **Claude**, **Cursor**, and other coding assistant ecosystems. The result: coding assistants that don’t stagnate but **improve with use**, enabling better workflows, higher code quality, and reduced developer friction.
+
+---
+
+👉 Think of **KaizenAgentic** as the **talent agency for digital coders**—a place where AI subagents aren’t static tools but *living talents*, continuously coached, measured, and refined for peak performance.
+
+
+xxx

wiki/KaizenBackground.md

@@ -0,0 +1,27 @@
+KaizenBackground
+
+*Continuous Improvement Methods and Applications*
+
+Kaizen is a Japanese business philosophy and methodology focused on continuous improvement through small, incremental changes that involve everyone in an organization, from executives to frontline workers. The term comes from the Japanese words "kai" (change) and "zen" (good), together meaning "change for the better" or simply "improvement".
+
+## Core Principles
+
+Kaizen aims to improve efficiency, increase productivity, reduce waste, and enhance quality by encouraging regular, everyday improvements. It relies on cooperation, employee empowerment, and commitment at all levels rather than imposing top-down or radical changes.
+​
+## Applications
+
+Kaizen began as an industrial practice in post-WWII Japan, notably within the Toyota Production System, and has since spread worldwide to industries far beyond manufacturing, including healthcare, software development, and service sectors.
+
+​## Methodology
+
+Key elements of the Kaizen approach include:
+
+- Encouraging all employees to identify and suggest improvements.
+- Using systematic cycles like the PDCA (Plan, Do, Check, Act) method to implement and review changes.
+- Focusing on standardized work processes that evolve based on new improvements.
+- Application of the “5S” system for workplace organization: Sort, Set in Order, Shine, Standardize, Sustain.
+
+Kaizen’s philosophy of continuous, collective improvement remains foundational in modern lean management, helping organizations enhance productivity, quality, and workplace culture.
+​
+
+xxx

wiki/KaizenDefinitionOfClean.md

@@ -0,0 +1,7 @@
+KaizenDefinitionOfClean
+
+*Keep your codebase in shape*
+
+The KaizenDefinitionOfClean specifies the target state for matching KaizenGuidance and can be used to diagnose and restore deviations from guidance regularly.
+
+xxx

wiki/KaizenGameplan.md

@@ -0,0 +1,7 @@
+KaizenGameplan
+
+*Optimize your codebase *
+
+The gameplan describes what to do in your specific codebase to implement a KaizenGuidance document.
+
+xxx