@firatcand/roster 0.1.0 → 1.0.0

package/templates/scaffold/dreamer/README.md

@@ -9,7 +9,7 @@ Cross-domain pattern detection matters. A lesson observed in Twitter automation
 ## Files
 
 - `agent.md` — orchestrator contract
-- `subagents/` — pattern-detector, lesson-drafter, promotion-arbiter
+- `subagents/` — pattern-detector, lesson-drafter
 - `playbook/` — the dreamer's own lessons (lessons about how to learn)
 - `logs/` — its own runs
 - `state.md` — last processed cutoff
@@ -17,7 +17,7 @@ Cross-domain pattern detection matters. A lesson observed in Twitter automation
 
 ## Invocation
 
-Nightly via cron (`scripts/cron/wrappers/dreamer-nightly.sh`).
+Nightly via the native desktop scheduler. Register with `roster schedule install` — each fire spawns a fresh CLI session in the workspace, loads `CONTEXT.md`, invokes the `roster-orchestrator` skill, and dispatches the dreamer in isolated subagent context. See `conventions.md` § Schedules for the model.
 
 On-demand from a session: "Run the dreamer on the last week's outreach runs across all projects."
 

package/templates/scaffold/dreamer/agent.md

@@ -45,7 +45,6 @@ Typically scheduled nightly via cron or `/schedule`. When invoked without a plan
 
 - `pattern-detector.md` — finds patterns across runs+feedback
 - `lesson-drafter.md` — drafts a single lesson in schema format
-- `promotion-arbiter.md` — decides project vs global scope for validated lessons
 
 ## Tools and bindings
 

package/templates/scaffold/dreamer/plans/nightly-reflection.yaml

@@ -1,11 +1,9 @@
 plan: nightly-reflection
 description: |
-  Reads runs and feedback across all agents and projects since the last
-  cutoff, detects patterns, drafts lesson candidates, surfaces them for HITL
-  approval via Slack #admin, and writes approved lessons to the relevant
-  playbook directories. Promotes project-scoped lessons to global when the
-  pattern is observed in 2+ projects. Updates dreamer/state.md with the new
-  cutoff and a summary.
+  Reads runs and feedback across all agents since the last cutoff, detects
+  patterns, drafts lesson candidates, surfaces them for HITL approval via
+  Slack #admin, and writes approved lessons to each agent's playbook.
+  Updates dreamer/state.md with the new cutoff and a summary.
 
 inputs:
   mode:
@@ -14,7 +12,7 @@ inputs:
     description: nightly | weekly | on-demand. Selects how aggressively to scan and how to weight evidence.
   scope:
     required: false
-    description: Limit to one project (slug) or one agent (function/agent) — useful for on-demand runs.
+    description: Limit to one agent (function/agent) — useful for on-demand runs.
   since:
     required: false
     description: ISO timestamp cutoff. If omitted, uses last_processed_through from dreamer/state.md.
@@ -24,7 +22,6 @@ outputs:
   candidates_drafted: integer
   candidates_approved: integer
   lessons_written: integer
-  lessons_promoted: integer
   conflicts_surfaced: integer
 
 steps:
@@ -35,9 +32,9 @@ steps:
 
   - id: identify_material
     description: |
-      Walk every agent's <function>/<agent>/projects/<project>/log/runs/<YYYY-MM>/
-      and log/feedback/<YYYY-MM>/ for files newer than the cutoff. Match runs
-      to feedback by filename. Apply ${inputs.scope} filter if provided.
+      Walk every agent's <function>/<agent>/log/runs/<YYYY-MM>/ and
+      log/feedback/<YYYY-MM>/ for files newer than the cutoff. Match runs to
+      feedback by filename. Apply ${inputs.scope} filter if provided.
 
   - id: detect_patterns
     subagent: pattern-detector
@@ -62,52 +59,41 @@ steps:
     description: |
       For each candidate that meets threshold or extends an existing lesson,
       draft a lesson in schema format with frontmatter (id, source: dreamer,
-      scope: project|global, status: candidate, agent, created). Place drafts
-      in dreamer/pending/.
+      status: candidate, agent, created). Place drafts in
+      <function>/<agent>/pending/.
     args:
       input_from: accumulate_evidence
 
-  - id: arbitrate_promotion
-    subagent: promotion-arbiter
-    description: |
-      For any project lesson validated in 2+ projects, decide whether to
-      promote to global scope. Returns project vs global designation per
-      candidate.
-    args:
-      input_from: draft_lessons
-
   - id: hitl_routing
     description: |
-      Post all candidates and promotions to Slack #admin (channel from
+      Post all candidates to Slack #admin (channel from
       SLACK_HITL_CHANNEL_ADMIN env var) as threaded messages, one per
       candidate. Format: "Candidate lesson <id>: <title>. Approve / Reject /
       Defer." TTL 7 days. If Slack unavailable, queue candidates locally in
-      dreamer/pending/ and retry next run.
+      <function>/<agent>/pending/ and retry next run.
     approval: slack
 
   - id: apply_approvals
     description: |
-      On approval, write the lesson to the correct location:
-        - Project-scoped: <function>/<agent>/projects/<project>/playbook/L-...md
-          with scope: project
-        - Promoted to global: <function>/<agent>/playbook/L-...md with
-          scope: global AND mark project lesson promoted_to_global: true
-        - Retired: update existing lesson's status: retired with reason
-      All dreamer-written lessons get source: dreamer in frontmatter.
-      Respect human-written lessons (source: human) — never modify or
-      supersede without explicit HITL approval.
+      On approval, move the candidate file from <function>/<agent>/pending/
+      to <function>/<agent>/playbook/L-...md. There is no scope decision;
+      v1 has a single playbook per agent. All dreamer-written lessons get
+      source: dreamer in frontmatter. Respect human-written lessons
+      (source: human) — never modify or supersede without explicit HITL
+      approval. Retired candidates update an existing lesson's status:
+      retired with reason.
 
   - id: update_state
     description: |
       Write timestamp + summary to dreamer/state.md:
         last_processed_through: <ISO timestamp>
-        last_run_summary: drafted N, approved M, written K, promoted P
+        last_run_summary: drafted N, approved M, written K
 
   - id: write_run_log
     description: |
       Write run details to dreamer/logs/<YYYY-MM>/<YYYY-MM-DD-HHMM>.md
-      including: material processed (counts by project and agent), patterns
-      detected, lesson candidates drafted (Slack thread links), promotion
-      candidates, approvals applied, conflicts surfaced.
+      including: material processed (counts by agent), patterns detected,
+      lesson candidates drafted (Slack thread links), approvals applied,
+      conflicts surfaced.
 
 approval_channel: slack

package/templates/scaffold/dreamer/subagents/lesson-drafter.md

@@ -9,20 +9,17 @@ Take a candidate pattern and draft a lesson file in the schema defined in `conve
 - `pattern` (object): output from pattern-detector
 - `existing_lesson` (object, optional): if extending an existing lesson, the current version
 - `agent` (string): which agent
-- `project` (string): which project sourced it
 
 ## Output
 
 ```yaml
 suggested_filename: L-2026-04-26-001.md
-suggested_path: <function>/<agent>/projects/<project>/playbook/   # or <function>/<agent>/playbook/
+suggested_path: <function>/<agent>/playbook/
 status: candidate
 lesson_markdown: |
   ---
   id: L-2026-04-26-001
   source: dreamer
-  scope: project                # or global
-  project: _demo              # or "—" if scope=global
   agent: sdr
   ...full frontmatter per conventions...
   ---
@@ -31,7 +28,6 @@ lesson_markdown: |
 
   ## Pattern observed
   ## Recommendation
-  ## Why this might be project-specific
   ## Retirement criteria
 ```
 
@@ -43,9 +39,8 @@ None.
 
 - Use the exact schema in `conventions.md`. Don't invent fields.
 - Always set `source: dreamer`.
-- Default to `scope: project` unless explicitly handling a promotion case.
 - Cite evidence in body, not just frontmatter.
-- Body has 4 sections: pattern, recommendation, scope reasoning, retirement criteria. That's it.
+- Body has 3 sections: pattern, recommendation, retirement criteria. That's it.
 
 ## Quality bar
 

package/templates/scaffold/{projects/_demo/guidelines → guidelines}/asset-links.md

@@ -1,3 +1,7 @@
+> **Example content — replace with your project's actuals.**
+> This file ships filled with an illustrative brand ("Acme Corp") so you can
+> see the expected shape. Overwrite freely; no agent will warn if you do.
+
 # Asset Links — Acme Corp
 
 ## Brand

package/templates/scaffold/{projects/_demo/guidelines → guidelines}/brand-book.md

@@ -1,3 +1,7 @@
+> **Example content — replace with your project's actuals.**
+> This file ships filled with an illustrative brand ("Acme Corp") so you can
+> see the expected shape. Overwrite freely; no agent will warn if you do.
+
 # Brand Book — Acme Corp
 
 ## Logo

package/templates/scaffold/{projects/_demo/guidelines → guidelines}/messaging.md

@@ -1,3 +1,7 @@
+> **Example content — replace with your project's actuals.**
+> This file ships filled with an illustrative brand ("Acme Corp") so you can
+> see the expected shape. Overwrite freely; no agent will warn if you do.
+
 # Messaging — Acme Corp
 
 ## Headline value props

package/templates/scaffold/{projects/_demo/guidelines → guidelines}/voice.md

@@ -1,3 +1,7 @@
+> **Example content — replace with your project's actuals.**
+> This file ships filled with an illustrative brand ("Acme Corp") so you can
+> see the expected shape. Overwrite freely; no agent will warn if you do.
+
 # Voice — Acme Corp
 
 ## Adjectives describing the brand voice

package/templates/scaffold/logs/cron/.gitkeep

@@ -0,0 +1 @@
+# Cron log directory

package/templates/scaffold/ops/EXPERT.md

@@ -11,7 +11,7 @@ Ops advisor for an early-stage solo founder running an agent team. Cover automat
 
 ## Scope
 
-- **Critique**: Audit `scripts/cron/crontab`, `scripts/cron/wrappers/*`, agent `config/default.yaml` files, `.env` patterns, and ops-related project guidelines when they exist. State the principle being violated. Score risk: data loss > silent failure > cost > polish.
+- **Critique**: Audit `roster/<function>/schedules.yaml`, `.roster/schedule-specs/`, agent `config/default.yaml` files, `.env` patterns, and ops-related project guidelines when they exist. State the principle being violated. Score risk: data loss > silent failure > cost > polish.
 - **Generate guidelines**: Produce or refine ops-related guideline files when a project demands them — `projects/<project>/guidelines/ops-runbook.md`, cron schedule specs, retry/idempotency contracts, secret-rotation procedures. Default to producing directly when context is sufficient; otherwise interview, then write.
 - **Guide**: Scheduling decisions, secrets management, deployment patterns, observability strategy, failure-mode reasoning. Strategic output — files only when the task asks for substrate.
 
@@ -22,16 +22,16 @@ You do **NOT** produce tactical artifacts (specific cron wrapper shell scripts,
 On invocation, read in this order:
 
 1. `projects/<project>/CLAUDE.md` — project identity and what runs against it
-2. `scripts/cron/crontab` and `scripts/cron/wrappers/` — current automation surface
+2. `roster/<function>/schedules.yaml` and `.roster/schedule-specs/` — current automation surface (Phase 2.5 native-scheduler model; see `conventions.md` § Schedules and [ADR-0001](../../docs/adr/0001-scheduling-architecture.md))
 3. The relevant agent's `agent.md` and `config/default.yaml` — tool bindings, schedules, caps
 4. `projects/<project>/state.md` — current focus
-5. `logs/cron/*` for recent failures, if a reliability question
+5. `logs/cron/*` for recent `roster schedule install --tool codex --via cron` failures, if a reliability question
 
 Identify gaps. Ask only about gaps. Don't re-ask what's already in substrate. If no project is named and the question is repo-wide, say so before proceeding.
 
 ## What you cover
 
-- Scheduling (cron, Claude Code `/schedule`, GitHub Actions scheduled workflows)
+- Scheduling (native desktop scheduler via `roster schedule install`, the `roster schedule install --tool codex --via cron` crontab path, GitHub Actions scheduled workflows)
 - Secrets management (`.env`, env-var conventions, rotation, SOPS or similar when justified)
 - Deployment patterns (script-based, GitHub Actions, manual checklists)
 - Observability (`logs/cron/`, structured logging, alerting thresholds, "did it run" verification)
@@ -62,7 +62,7 @@ When a task spans skills (e.g., "design the cron + monitoring + alert chain for
 ## Behavior rules
 
 - **Idempotency first.** Every operation must be safe to re-run. If it isn't, name the guard.
-- **Observability is non-negotiable.** If you can't tell whether it ran, it didn't. Logs land in `logs/cron/<job>-<YYYY-MM-DD>.log` per `conventions.md`.
+- **Observability is non-negotiable.** If you can't tell whether it ran, it didn't. For `--via cron` installs (Codex-only — `roster schedule install --tool codex --via cron`), stdout/stderr lands in `logs/cron/<job>.log` per `conventions.md` § Schedules. For UI-handoff installs (Claude Scheduled Tasks, Codex Automations), the scheduler owns the log surface — check the host app's run history.
 - **Cost-aware.** Name the cost of every recommendation — dollars, time, on-call burden.
 - **Name failure modes.** Don't ship a recommendation without stating what happens when it fails.
 - **Stay in your lane.** Reusable substrate and patterns. One-off incident response and per-run remediations are agent work, not expert work.

package/templates/scaffold/scripts/audit-agent.sh

@@ -0,0 +1,326 @@
+#!/usr/bin/env bash
+# audit-agent.sh — checks agent structure completeness, reports issues with suggested fixes
+# Usage: bash scripts/audit-agent.sh <function> <agent>
+
+set -euo pipefail
+
+if [ $# -ne 2 ]; then
+  echo "Usage: $0 <function> <agent>"
+  exit 1
+fi
+
+FN="$1"
+AGENT="$2"
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+AGENT_DIR="$ROOT/$FN/$AGENT"
+
+source "$ROOT/scripts/lib/functions.sh"
+
+if ! is_valid_function "$FN"; then
+  echo "ERROR: '$FN' is not a registered function." >&2
+  echo "Registered functions:" >&2
+  read_functions | sed 's/^/  - /' >&2
+  exit 1
+fi
+
+if [ ! -d "$AGENT_DIR" ]; then
+  echo "ERROR: Agent '$FN/$AGENT' not found at $AGENT_DIR"
+  exit 1
+fi
+
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+RUN_TIME=$(date +%Y-%m-%d-%H%M)
+LOG_DIR="$ROOT/chief-of-staff/logs/$(date +%Y-%m)"
+mkdir -p "$LOG_DIR"
+REPORT="$LOG_DIR/audit-$FN-$AGENT-$RUN_TIME.md"
+
+FAILURES=()
+WARNINGS=()
+PASSED=()
+
+# === agent.md required sections ===
+if [ ! -f "$AGENT_DIR/agent.md" ]; then
+  FAILURES+=("[$FN/$AGENT/agent.md] missing")
+else
+  REQUIRED_SECTIONS=("## Purpose" "## Inputs" "## Plans" "## Subagents" "## Outputs" "## Approval" "## Lessons protocol")
+  MISSING=()
+  for section in "${REQUIRED_SECTIONS[@]}"; do
+    if ! grep -qF "$section" "$AGENT_DIR/agent.md"; then
+      MISSING+=("$section")
+    fi
+  done
+  if [ ${#MISSING[@]} -gt 0 ]; then
+    FAILURES+=("[$FN/$AGENT/agent.md] missing required sections: ${MISSING[*]}")
+    FAILURES+=("  → Suggested fix: add the missing sections per conventions.md § 'Agent contract'")
+  else
+    PASSED+=("[$FN/$AGENT/agent.md] all required sections present")
+  fi
+
+  # ## Tools and bindings is required ONLY for agents that use external tools.
+  # Missing → warning, not failure (agents reading only workspace guidelines
+  # don't need it). The chief-of-staff create-agent guided flow adds the
+  # section when the user names tools.
+  if ! grep -qF "## Tools and bindings" "$AGENT_DIR/agent.md"; then
+    WARNINGS+=("[$FN/$AGENT/agent.md] '## Tools and bindings' not declared — fine for tool-less agents; required if this agent calls external APIs")
+  fi
+
+  # Steps section should NOT be present anymore — workflows live in plans/
+  if grep -qE '^## Steps' "$AGENT_DIR/agent.md"; then
+    WARNINGS+=("[$FN/$AGENT/agent.md] still has a '## Steps' section — workflow logic should live in plans/<plan>.yaml, not agent.md")
+    WARNINGS+=("  → Suggested fix: extract workflow steps into a plan file under $FN/$AGENT/plans/ and remove the section from agent.md")
+  fi
+fi
+
+# === plans/ directory ===
+PLANS_DIR="$AGENT_DIR/plans"
+if [ ! -d "$PLANS_DIR" ]; then
+  WARNINGS+=("[$FN/$AGENT/plans/] missing — agent has no plans declared")
+  WARNINGS+=("  → Suggested fix: mkdir $PLANS_DIR && add at least one .yaml plan file")
+else
+  PLAN_COUNT=$(find "$PLANS_DIR" -maxdepth 1 -name '*.yaml' -type f 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$PLAN_COUNT" -eq 0 ]; then
+    WARNINGS+=("[$FN/$AGENT/plans/] empty — agent has no plans declared")
+    WARNINGS+=("  → Suggested fix: add at least one .yaml plan to $PLANS_DIR")
+  else
+    PASSED+=("[$FN/$AGENT/plans/] $PLAN_COUNT plan(s)")
+    for plan in "$PLANS_DIR"/*.yaml; do
+      [ -f "$plan" ] || continue
+      REL="${plan#$ROOT/}"
+      if command -v python3 >/dev/null 2>&1; then
+        if ! python3 -c "import yaml; yaml.safe_load(open('$plan'))" 2>/dev/null; then
+          FAILURES+=("[$REL] YAML parse error")
+        else
+          PASSED+=("[$REL] valid YAML")
+        fi
+      fi
+    done
+  fi
+fi
+
+# === Slash command file ===
+SLASH_CMD="$ROOT/.claude/commands/$AGENT.md"
+if [ ! -f "$SLASH_CMD" ]; then
+  WARNINGS+=("[.claude/commands/$AGENT.md] missing — slash command not registered")
+  WARNINGS+=("  → Suggested fix: scaffold via 'bash scripts/new-agent.sh' template, or copy from another agent's slash command file")
+else
+  PASSED+=("[.claude/commands/$AGENT.md] present")
+fi
+
+# README
+if [ ! -f "$AGENT_DIR/README.md" ]; then
+  FAILURES+=("[$FN/$AGENT/README.md] missing")
+else
+  PASSED+=("[$FN/$AGENT/README.md] present")
+fi
+
+# config.yaml — agent config (guideline refs + tool bindings).
+# Schema check: single-document mapping with agent=$FN/$AGENT, plans_dir,
+# guideline_refs (mapping), tools (mapping). Drift here breaks the runtime
+# loader (Phase 2) and `chief-of-staff create-agent` reuse.
+if [ ! -f "$AGENT_DIR/config.yaml" ]; then
+  FAILURES+=("[$FN/$AGENT/config.yaml] missing")
+  FAILURES+=("  → Suggested fix: add config.yaml at agent root with at least 'agent: $FN/$AGENT' and 'plans_dir: ./plans/'")
+elif command -v python3 >/dev/null 2>&1; then
+  CFG_RC=0
+  CFG_MSG="$(AGENT_EXPECT="$FN/$AGENT" CFG_PATH="$AGENT_DIR/config.yaml" python3 - <<'PYEOF' 2>&1
+import os, sys
+try:
+    import yaml
+except ImportError:
+    sys.stderr.write("pyyaml-missing")
+    sys.exit(2)
+expect = os.environ["AGENT_EXPECT"]
+path = os.environ["CFG_PATH"]
+with open(path) as f:
+    try:
+        doc = yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        sys.stderr.write(f"yaml-parse-error: {e}")
+        sys.exit(1)
+if not isinstance(doc, dict):
+    sys.stderr.write("not-a-mapping")
+    sys.exit(1)
+errs = []
+agent = doc.get("agent")
+if agent != expect:
+    errs.append(f"agent field is {agent!r}, expected {expect!r}")
+if "plans_dir" not in doc:
+    errs.append("missing plans_dir")
+gr = doc.get("guideline_refs")
+if gr is not None and not isinstance(gr, dict):
+    errs.append("guideline_refs is not a mapping")
+tools = doc.get("tools")
+if tools is not None and not isinstance(tools, dict):
+    errs.append("tools is not a mapping")
+if errs:
+    sys.stderr.write("; ".join(errs))
+    sys.exit(1)
+PYEOF
+)" || CFG_RC=$?
+  if [ $CFG_RC -eq 0 ]; then
+    PASSED+=("[$FN/$AGENT/config.yaml] valid (schema)")
+  elif [ $CFG_RC -eq 2 ]; then
+    PASSED+=("[$FN/$AGENT/config.yaml] present (schema not validated, pyyaml missing)")
+  else
+    FAILURES+=("[$FN/$AGENT/config.yaml] $CFG_MSG")
+    FAILURES+=("  → Suggested fix: open the file and ensure it is a single YAML mapping with 'agent: $FN/$AGENT', 'plans_dir', a 'guideline_refs:' mapping, and a 'tools:' mapping (may be empty)")
+  fi
+else
+  PASSED+=("[$FN/$AGENT/config.yaml] present (schema not validated, python3 missing)")
+fi
+
+# .mcp.json valid JSON
+if [ ! -f "$AGENT_DIR/.mcp.json" ]; then
+  WARNINGS+=("[$FN/$AGENT/.mcp.json] missing (no agent-scoped MCPs configured)")
+else
+  if command -v python3 >/dev/null 2>&1; then
+    if ! python3 -c "import json; json.load(open('$AGENT_DIR/.mcp.json'))" 2>/dev/null; then
+      FAILURES+=("[$FN/$AGENT/.mcp.json] invalid JSON")
+      FAILURES+=("  → Suggested fix: validate with: python3 -c 'import json; json.load(open(\"$AGENT_DIR/.mcp.json\"))'")
+    else
+      PASSED+=("[$FN/$AGENT/.mcp.json] valid JSON")
+    fi
+  else
+    PASSED+=("[$FN/$AGENT/.mcp.json] present (JSON not validated, python3 missing)")
+  fi
+fi
+
+# .claude/settings.json
+if [ ! -f "$AGENT_DIR/.claude/settings.json" ]; then
+  WARNINGS+=("[$FN/$AGENT/.claude/settings.json] missing")
+else
+  if command -v python3 >/dev/null 2>&1; then
+    if ! python3 -c "import json; json.load(open('$AGENT_DIR/.claude/settings.json'))" 2>/dev/null; then
+      FAILURES+=("[$FN/$AGENT/.claude/settings.json] invalid JSON")
+    else
+      PASSED+=("[$FN/$AGENT/.claude/settings.json] valid JSON")
+    fi
+  else
+    PASSED+=("[$FN/$AGENT/.claude/settings.json] present")
+  fi
+fi
+
+# subagents/ exists
+if [ ! -d "$AGENT_DIR/subagents" ]; then
+  WARNINGS+=("[$FN/$AGENT/subagents/] missing (may be intentional for very simple agents)")
+else
+  # Check each subagent has required sections
+  for sub in "$AGENT_DIR/subagents"/*.md; do
+    [ -f "$sub" ] || continue
+    BASENAME=$(basename "$sub")
+    [ "$BASENAME" = "_template.md" ] && continue
+    REL="${sub#$ROOT/}"
+    SUB_REQUIRED=("## Role" "## Inputs" "## Output" "## Tools" "## Boundaries" "## Quality bar")
+    SUB_MISSING=()
+    for section in "${SUB_REQUIRED[@]}"; do
+      if ! grep -qF "$section" "$sub"; then
+        SUB_MISSING+=("$section")
+      fi
+    done
+    if [ ${#SUB_MISSING[@]} -gt 0 ]; then
+      WARNINGS+=("[$REL] missing sections: ${SUB_MISSING[*]}")
+    else
+      PASSED+=("[$REL] all subagent sections present")
+    fi
+  done
+fi
+
+# playbook/ exists
+if [ ! -d "$AGENT_DIR/playbook" ]; then
+  WARNINGS+=("[$FN/$AGENT/playbook/] missing")
+else
+  PASSED+=("[$FN/$AGENT/playbook/] present")
+fi
+
+# Flat-shape directories
+for d in logs/runs logs/feedback pending; do
+  if [ ! -d "$AGENT_DIR/$d" ]; then
+    WARNINGS+=("[$FN/$AGENT/$d/] missing")
+  fi
+done
+
+# asset-references.md at agent root
+if [ ! -f "$AGENT_DIR/asset-references.md" ]; then
+  WARNINGS+=("[$FN/$AGENT/asset-references.md] missing")
+fi
+
+# === Status ===
+if [ ${#FAILURES[@]} -gt 0 ]; then
+  STATUS="fail"
+elif [ ${#WARNINGS[@]} -gt 0 ]; then
+  STATUS="warn"
+else
+  STATUS="pass"
+fi
+
+count_items() {
+  local arr=("$@")
+  local n=0
+  for item in "${arr[@]}"; do
+    if ! [[ "$item" =~ ^[[:space:]]*→ ]]; then
+      n=$((n+1))
+    fi
+  done
+  echo $n
+}
+
+N_FAIL=0
+for item in "${FAILURES[@]:-}"; do
+  [ -z "$item" ] && continue
+  [[ "$item" =~ ^[[:space:]]+→ ]] && continue
+  N_FAIL=$((N_FAIL + 1))
+done
+N_WARN=0
+for item in "${WARNINGS[@]:-}"; do
+  [ -z "$item" ] && continue
+  [[ "$item" =~ ^[[:space:]]+→ ]] && continue
+  N_WARN=$((N_WARN + 1))
+done
+N_PASS=${#PASSED[@]}
+
+# Write report
+{
+  echo "---"
+  echo "operation: audit-agent"
+  echo "function: $FN"
+  echo "agent: $AGENT"
+  echo "ran: $TIMESTAMP"
+  echo "status: $STATUS"
+  echo "---"
+  echo ""
+  echo "# Audit: $FN/$AGENT"
+  echo ""
+  echo "## Summary"
+  echo "- $N_PASS passed"
+  echo "- $N_WARN warnings"
+  echo "- $N_FAIL failures"
+  echo ""
+  if [ $N_FAIL -gt 0 ]; then
+    echo "## Failures"
+    for line in "${FAILURES[@]}"; do
+      echo "- $line"
+    done
+    echo ""
+  fi
+  if [ $N_WARN -gt 0 ]; then
+    echo "## Warnings"
+    for line in "${WARNINGS[@]}"; do
+      echo "- $line"
+    done
+    echo ""
+  fi
+  if [ $N_PASS -gt 0 ]; then
+    echo "## Passed"
+    for line in "${PASSED[@]}"; do
+      echo "- $line"
+    done
+  fi
+} > "$REPORT"
+
+echo "Audit: $FN/$AGENT — $STATUS"
+echo "  Passed: $N_PASS, Warnings: $N_WARN, Failures: $N_FAIL"
+[ $N_FAIL -gt 0 ] && {
+  echo "Failures:"
+  for line in "${FAILURES[@]}"; do echo "  $line"; done
+}
+echo "Full report: $REPORT"