feat(automation): continual learning, agents-md-audit, shell entry points

.cursor/agents/agents-memory-updater.md

@@ -0,0 +1,47 @@
+---
+name: agents-memory-updater
+description: Mine high-signal transcript deltas, update `AGENTS.md`, and keep the incremental transcript index in sync.
+model: inherit
+---
+
+# AGENTS.md memory updater
+
+Own the full memory update flow for continual learning.
+
+## Trigger
+
+Use from `continual-learning` when transcript deltas may produce durable memory updates.
+
+## Workflow
+
+1. Read existing `AGENTS.md` first. If it does not exist, create it with only:
+   - `## Learned User Preferences`
+   - `## Learned Workspace Facts`
+2. Load the incremental index if present at `.cursor/hooks/state/continual-learning-index.json`.
+3. Inspect only transcript files under `~/.cursor/projects/<workspace-slug>/agent-transcripts/` that are new or have newer mtimes than the index.
+4. Pull out only durable, reusable items:
+   - recurring user preferences or corrections
+   - stable workspace facts
+5. Update `AGENTS.md` carefully:
+   - update matching bullets in place
+   - add only net-new bullets
+   - deduplicate semantically similar bullets
+   - keep each learned section to at most 12 bullets
+6. Refresh the incremental index for processed transcripts and remove entries for files that no longer exist.
+7. If the merge produces no `AGENTS.md` changes, leave `AGENTS.md` unchanged but still refresh the index.
+8. If no meaningful updates exist, respond exactly: `No high-signal memory updates.`
+
+## Guardrails
+
+- Use plain bullet points only.
+- Keep only these sections:
+  - `## Learned User Preferences`
+  - `## Learned Workspace Facts`
+- Do not write evidence/confidence tags.
+- Do not write process instructions, rationale, or metadata blocks.
+- Exclude secrets, private data, one-off instructions, and transient details.
+
+## Output
+
+- Updated `AGENTS.md` and `.cursor/hooks/state/continual-learning-index.json` when needed
+- Otherwise exactly `No high-signal memory updates.`

.cursor/skills/continual-learning/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: continual-learning
+description: Orchestrate continual learning by delegating transcript mining and AGENTS.md updates to `agents-memory-updater`.
+disable-model-invocation: true
+---
+
+# Continual Learning
+
+Keep `AGENTS.md` current by delegating the memory update flow to one subagent.
+
+## Trigger
+
+Use when the user asks to mine prior chats, maintain `AGENTS.md`, or run the continual-learning loop.
+
+## Workflow
+
+1. Call `agents-memory-updater`.
+2. Return the updater result.
+
+## Guardrails
+
+- Keep the parent skill orchestration-only.
+- Do not mine transcripts or edit files in the parent flow.
+- Do not bypass the subagent.

AGENTS.md

@@ -77,7 +77,10 @@ actions. Tag forms recognised include:
 - Fast unit tests: `python scripts/test_runner.py --unit`
 - Aria-specific unit tests: `pytest tests/unit/test_tags_to_actions.py`
 - Quick repo validation: `python scripts/fast_validate.py`
-- Repo automation agents: `python scripts/run_repo_agents.py` (writes `data_out/agents/status.json`; use `--run-agents` with `scripts/repo_health_automation.py`)
+- Repo automation agents: `python scripts/run_repo_agents.py` or `make agents` (writes `data_out/agents/status.json`; use `--run-agents` with `scripts/repo_health_automation.py`)
+- Shell wrapper: `./scripts/run_ai_automation.sh` (forwards to `run_repo_agents.py`)
+- Continual learning: run `/continual-learning` in Cursor to mine transcripts and update Learned sections below (delegates to `.cursor/agents/agents-memory-updater.md`)
+- Automation canvas: open `~/.cursor/projects/workspace/canvases/automation-status.canvas.tsx` beside chat for agent + memory metrics
 - System health: `curl http://localhost:7071/api/ai/status | jq`
 
 ## Conventions
@@ -94,6 +97,8 @@ The startup update script installs Python deps into `.venv` (Python 3.12). Use `
 - **Aria web UI** (flagship, port 8080): `.venv/bin/python apps/aria/server.py --port 8080` (or `make start`). The root page `/` is a static stage demo with **no command box**; the natural-language command UI is at **`/auto-execute.html`** (text input + "Execute Actions" → `POST /api/aria/execute`). Backend command/execute endpoints work via curl regardless (see AGENTS.md API table). `ARIA_RENDER_MODE` defaults to `ue5` but the browser falls back to Three.js, so the stage still renders without UE5.
 - **Azure Functions API** (port 7071): `func host start --port 7071` (or `make start-functions`). The `func` CLI (v4) is preinstalled in the VM snapshot at `~/.npm-global/bin` but is **not on the default PATH** — prepend it: `export PATH="$HOME/.npm-global/bin:$PATH"`. If `func` is ever missing, reinstall with `npm install -g azure-functions-core-tools@4 --unsafe-perm true`, then run `npm config delete prefix` to avoid an nvm/npmrc conflict. On startup the host logs `AzureWebJobsStorage ... Unhealthy` because Azurite isn't running; this is **expected and non-fatal** — HTTP-triggered endpoints (`/api/ai/status`, `/api/chat`, `/api/tts`, etc.) still respond. A lightweight fallback `make start-local-status` serves only `/api/ai/status`.
 - **Tests/lint:** `.venv/bin/python scripts/test_runner.py --unit` is the fast suite. All ~2700 unit tests now pass (0 failures, 50 skipped) — previous devcontainer-path failures were fixed in the automation runner PR. `make lint` (ruff + black) currently reports many pre-existing findings across the repo — treat lint failures as code-quality state, not an environment problem.
+- **Repo agents:** `make agents` or `./scripts/run_ai_automation.sh` runs all inspection agents; `make agents-dry` previews without writing status files.
+- **Continual learning:** invoke `/continual-learning` in Cursor chat (skill at `.cursor/skills/continual-learning/SKILL.md`) to update Learned sections via the `agents-memory-updater` subagent.
 
 ## Learned User Preferences
 

Makefile

@@ -29,7 +29,8 @@ GRADIO_SHARE ?= false
 
 .PHONY: all install install-qai dev start stop build test test-unit test-integration \
 	lint format type-check clean docker-build docker-dev start-gradio \
-	start-local-status start-functions-clean restart-functions-clean start-qai validate-mcp validate-mcp-json help
+	start-local-status start-functions-clean restart-functions-clean start-qai validate-mcp validate-mcp-json \
+	agents agents-dry ai-automation help
 
 # Default target
 all: lint test
@@ -145,6 +146,21 @@ validate-mcp:
 validate-mcp-json:
 	@$(PYTHON) scripts/validate_mcp_setup.py --json
 
+# ---------------------------------------------------------------------------
+# Repository inspection agents
+# ---------------------------------------------------------------------------
+
+## Run all repository inspection agents
+agents:
+	$(PYTHON) scripts/run_repo_agents.py
+
+## Preview agent results without writing data_out/agents/*
+agents-dry:
+	$(PYTHON) scripts/run_repo_agents.py --dry-run
+
+## Alias for agents
+ai-automation: agents
+
 # ---------------------------------------------------------------------------
 # Code quality
 # ---------------------------------------------------------------------------

docs/guides/REPO_AUTOMATION_GUIDE.md

@@ -232,6 +232,7 @@ Use `scripts/run_repo_agents.py` when you need deterministic repository checks t
 | `status-freshness` | Inspect `data_out/**/status.json` for stale, failed, timestamp-less, or unparseable runs | A health file has not updated within the configured max age |
 | `marker-audit` | Scan source-like files for `TODO`, `FIXME`, `HACK`, `XXX`, and `BUG` markers | Maintenance marker counts by file and marker type |
 | `docstring-audit` | Measure Python module/class/function docstring coverage | Public functions missing docstrings in audited paths |
+| `agents-md-audit` | Validate `AGENTS.md` Learned sections for structure, bullet limits, and secret patterns | Missing sections, over-limit bullets, or stale referenced dates |
 
 ### Contract and outputs
 
@@ -262,9 +263,16 @@ python scripts/run_repo_agents.py --agent status-freshness --json
 
 # Fail a CI/check step when any agent warns or errors
 python scripts/run_repo_agents.py --fail-on-warning
+
+# Shell wrapper (uses .venv/bin/python)
+./scripts/run_ai_automation.sh --json
+
+# Makefile shortcuts
+make agents
+make agents-dry
 ```
 
-`repo_health_automation.py --run-agents` inserts the agent runner before the integration contract gate. This is useful after orchestrator, status-file, or documentation-maintenance changes because it records repository inspection results in the same health-cycle status payload.
+`repo_health_automation.py --run-agents` inserts the agent runner **after** the integration contract gate. This is useful after orchestrator, status-file, or documentation-maintenance changes because it records repository inspection results in the same health-cycle status payload.
 
 ## Operational Smoke Flow
 

scripts/README.md

@@ -93,7 +93,7 @@ python .\scripts\repo_health_automation.py --watch --interval 300 --strict-endpo
 - `--strict-endpoints` — run integration gate in strict endpoint mode
 - `--full-pytest` — include `pytest tests -q --maxfail=1 --tb=short`
 - `--auto-fix-ruff` — run `ruff check --fix` on changed `.py` files before checks
-- `--run-agents` — run `scripts/run_repo_agents.py` before the integration contract gate
+- `--run-agents` — run `scripts/run_repo_agents.py` after the integration contract gate
 - `--continue-on-fail` — continue all steps even after a failed step
 
 **Status output:**
@@ -111,6 +111,7 @@ python .\scripts\repo_health_automation.py --watch --interval 300 --strict-endpo
 | `status-freshness` | Stale, failed, unparseable, or timestamp-less `data_out/**/status.json` files | `scripts/agents/status_freshness_agent.py` |
 | `marker-audit` | `TODO`, `FIXME`, `HACK`, `XXX`, and `BUG` markers in source-like files | `scripts/agents/marker_audit_agent.py` |
 | `docstring-audit` | Module/class/function docstring coverage for Python paths, defaulting to `shared` and `scripts/agents` | `scripts/agents/docstring_audit_agent.py` |
+| `agents-md-audit` | Structure and hygiene of `AGENTS.md` Learned sections (bullet limits, secrets, stale dates) | `scripts/agents/agents_md_audit_agent.py` |
 
 **Result contract:** Every agent returns an `AgentResult` with `name`, `status`, `summary`, `findings`, `metrics`, and `timestamp`. Valid statuses are `ok`, `warning`, and `error`; only `ok` makes `AgentResult.ok` true.
 
@@ -119,9 +120,14 @@ python .\scripts\repo_health_automation.py --watch --interval 300 --strict-endpo
 ```powershell
 # Run all registered agents and write status files
 python .\scripts\run_repo_agents.py
+make agents
 
 # Preview without writing data_out/agents/*
 python .\scripts\run_repo_agents.py --dry-run
+make agents-dry
+
+# Shell wrapper
+./scripts/run_ai_automation.sh --json
 
 # Run one agent, emit aggregate JSON, and fail CI on warnings
 python .\scripts\run_repo_agents.py --agent status-freshness --json --fail-on-warning