@accelerationguy/accel 1.0.0

package/modules/momentum/src/framework/tasks/vector-hygiene.md

@@ -0,0 +1,160 @@
+<purpose>
+Structured Vector domain maintenance. Review staged proposals, flag stale rules, audit domain health, and keep Vector lean and accurate.
+</purpose>
+
+<user-story>
+As an AI builder, I want a guided Vector maintenance session, so that my domain rules stay relevant, staged proposals get decided on, and Vector doesn't become a dumping ground of stale rules.
+</user-story>
+
+<when-to-use>
+- Monthly (on configured cadence)
+- When pulse reports overdue Vector hygiene
+- When user says "vector hygiene", "review vector rules", "clean up vector"
+- Entry point routes here via /momentum:vector-hygiene
+</when-to-use>
+
+<steps>
+
+<step name="assess" priority="first">
+Gather Vector health data and present summary.
+
+1. Read `.accel/momentum/workspace.json` for `vector_hygiene` config (threshold, max rules, last run)
+2. Read `.accel/momentum/staging.json` for pending proposals (via `vector_get_staged`)
+3. For each domain file in `.vector/`:
+   - Count rules
+   - Parse metadata comments (`# Last reviewed:` lines)
+   - Flag rules where last_reviewed is older than `staleness_threshold_days`
+   - Flag domains exceeding `max_rules_per_domain`
+4. Present summary:
+   ```
+   Vector Hygiene Assessment
+   ━━━━━━━━━━━━━━━━━━━━━━
+   Staged proposals: {N} pending
+   Domains: {N} total, {N} with stale rules, {N} over max
+   Total rules: {N} across all domains
+   Last hygiene: {date or "never"}
+   ```
+
+**Wait for operator confirmation before proceeding.**
+</step>
+
+<step name="review_proposals">
+Process each pending staged proposal.
+
+For each pending proposal from `vector_get_staged`:
+1. Present:
+   ```
+   Proposal {id} — {domain}
+   Proposed: {date} | Source: {source}
+   Rule: "{rule_text}"
+   Rationale: {rationale}
+   ```
+2. Ask: "**Approve**, **Kill**, **Archive**, or **Defer**?"
+3. Execute:
+   - Approve → `vector_approve_proposal(id)` (writes rule to domain file with metadata)
+   - Kill → `vector_kill_proposal(id)`
+   - Archive → `vector_archive_proposal(id)`
+   - Defer → skip (stays pending for next hygiene)
+
+**After approval:** Add metadata comments above the new rule in the domain file:
+```
+# Rule added: {today}
+# Last reviewed: {today}
+# Source: {proposal.source}
+{DOMAIN}_RULE_{N}={rule_text}
+```
+
+Process one proposal at a time. Wait for response between each.
+</step>
+
+<step name="review_stale_rules">
+Review rules flagged as stale (last_reviewed > threshold).
+
+For each domain with stale rules:
+1. Present domain name and total rule count
+2. For each stale rule:
+   ```
+   [{DOMAIN}] Rule {N} — last reviewed {date} ({days} days ago)
+   "{rule_text}"
+   ```
+3. Ask: "**Keep** (update reviewed date), **Archive**, or **Kill**?"
+4. Execute:
+   - Keep → Update `# Last reviewed:` comment to today
+   - Archive → Remove rule from domain file, add to `.vector/archive/archived-rules.json` with context
+   - Kill → Remove rule from domain file (with "Are you sure?" confirmation)
+
+**When archiving:** Read `.vector/archive/archived-rules.json`, append:
+```json
+{
+  "domain": "DOMAIN",
+  "rule_number": N,
+  "rule_text": "the rule",
+  "added": "original-added-date",
+  "archived": "today",
+  "reason": "operator's reason"
+}
+```
+
+Then renumber remaining rules in the domain file to close gaps.
+
+Process one domain at a time.
+</step>
+
+<step name="review_domains">
+Quick domain health check — guided Q&A.
+
+1. List all active domains with rule counts
+2. Cross-reference with `.accel/momentum/ACTIVE.md` current projects:
+   - Any active projects missing a domain?
+   - Any domains for inactive/completed projects?
+3. Check recall phrases:
+   - "Do the recall phrases for {domain} still match how you talk about this work?"
+4. Check for domains over `max_rules_per_domain`:
+   - "Domain {X} has {N} rules (max: {max}). Any candidates to archive or consolidate?"
+5. Ask: "Any new domains to create? Any to deactivate?"
+
+**Guided Q&A — don't force changes, just surface questions.**
+</step>
+
+<step name="review_decisions">
+Quick check on per-domain decision health.
+
+1. List `.vector/decisions/*.json` files with counts
+2. Flag domains with 0 decisions (might be missing logging)
+3. Flag decisions older than 90 days (might be outdated)
+4. Ask: "Any decisions to review or archive?"
+
+**Brief pass — decisions are mostly self-maintaining.**
+</step>
+
+<step name="log">
+Record the hygiene session.
+
+1. Update `.accel/momentum/workspace.json` → `vector_hygiene.last_run` to today's date
+2. Update `.accel/momentum/STATE.md` → note Vector hygiene completed
+3. Report:
+   ```
+   Vector Hygiene Complete
+   ━━━━━━━━━━━━━━━━━━━━━
+   Proposals: {N} processed ({N} approved, {N} killed, {N} archived, {N} deferred)
+   Rules reviewed: {N} ({N} kept, {N} archived, {N} killed)
+   Domains: {N} active
+   Next hygiene due: {date based on cadence}
+   ```
+</step>
+
+</steps>
+
+<output>
+Vector domains reviewed and maintained. Staged proposals decided. Stale rules addressed. Domain health verified. Hygiene session logged to workspace.json.
+</output>
+
+<acceptance-criteria>
+- [ ] All pending proposals presented and decided (approve/kill/archive/defer)
+- [ ] Stale rules flagged and reviewed with operator
+- [ ] Domain health check completed (rule counts, recall phrases)
+- [ ] Archived rules moved to .vector/archive/archived-rules.json
+- [ ] workspace.json vector_hygiene.last_run updated
+- [ ] STATE.md updated with hygiene completion
+- [ ] Operator confirmed completion of each step
+</acceptance-criteria>

package/modules/momentum/src/framework/templates/workspace-json.md

@@ -0,0 +1,96 @@
+# Workspace Manifest Template
+
+Output file: `.accel/momentum/workspace.json`
+
+```template
+{
+  "workspace": "{workspace-name}",
+  "created": "{YYYY-MM-DD}",
+  "groom_cadence": "{weekly|bi-weekly|monthly}",
+  "groom_day": "{day-of-week}",
+  "areas": {
+    "{area-name}": {
+      "type": "{working-memory|directory|config-cross-ref|system-layer|custom}",
+      "description": "[Human-readable purpose of this area]",
+      "paths": ["{file-or-directory-paths}"],
+      "groom": "{weekly|bi-weekly|monthly}",
+      "audit": {
+        "strategy": "{staleness|classify|cross-reference|dead-code|pipeline-status}",
+        "config": {}
+      }
+    }
+  },
+  "vector_hygiene": {
+    "proactive": true,
+    "cadence": "monthly",
+    "staleness_threshold_days": 60,
+    "max_rules_per_domain": 15,
+    "last_run": null
+  },
+  "surfaces": {
+    "{surface-name}": {
+      "file": "data/{name}.json",
+      "description": "[What this surface tracks]",
+      "hook": true,
+      "silent": true,
+      "schema": {
+        "id_prefix": "{PREFIX}",
+        "required_fields": ["{field1}", "{field2}"],
+        "priority_levels": ["{level1}", "{level2}"],
+        "status_values": ["{status1}", "{status2}"]
+      }
+    }
+  },
+  "satellites": {
+    "{project-name}": {
+      "path": "{relative-path-to-project}",
+      "engine": "{drive|custom|none}",
+      "state": "{path-to-state-file}",
+      "registered": "{YYYY-MM-DD}",
+      "groom_check": true,
+      "last_activity": null,
+      "phase_name": null,
+      "phase_number": null,
+      "phase_status": null,
+      "loop_position": "IDLE",
+      "handoff": false,
+      "last_plan_completed_at": null
+    }
+  }
+}
+```
+
+## Field Documentation
+
+| Field | Type | Description |
+|-------|------|------------|
+| workspace | string | Name of this workspace (typically the directory name) |
+| created | date | When Momentum was initialized in this workspace |
+| groom_cadence | enum | Default grooming frequency for the workspace |
+| groom_day | string | Preferred day for weekly grooming |
+| areas | object | Map of tracked workspace areas |
+| areas.*.type | enum | Classification of the area for audit strategy selection |
+| areas.*.paths | array | Files or directories this area tracks |
+| areas.*.groom | enum | Grooming frequency for this specific area (overrides default) |
+| areas.*.audit.strategy | enum | Which audit strategy to apply (see audit-strategies.md) |
+| areas.*.audit.config | object | Strategy-specific configuration |
+| vector_hygiene | object | Vector rule lifecycle management config (optional — only if Vector is installed) |
+| vector_hygiene.proactive | boolean | Auto-surface stale rules during groom |
+| vector_hygiene.cadence | enum | How often to run Vector hygiene |
+| vector_hygiene.staleness_threshold_days | number | Days before a rule is flagged as stale |
+| vector_hygiene.max_rules_per_domain | number | Soft cap per domain (warn, not enforce) |
+| surfaces | object | Registered data surfaces with schemas |
+| surfaces.*.file | string | Path to JSON file relative to .accel/momentum/ |
+| surfaces.*.hook | boolean | Whether a hook auto-injects this surface |
+| surfaces.*.silent | boolean | Whether hook output is passive (no proactive mentions) |
+| surfaces.*.schema | object | Validation schema for surface items |
+| surfaces.*.schema.id_prefix | string | Auto-generated ID prefix (e.g., "ACT", "BL") |
+| surfaces.*.schema.required_fields | array | Fields required on every item |
+| satellites | object | External projects tracked by Momentum but managed by their own engines |
+| satellites.*.engine | enum | What orchestration tool manages this project |
+| satellites.*.state | string | Path to the project's state file for health checks |
+| satellites.*.groom_check | boolean | Whether Momentum checks this project's health during groom (default: true) |
+| satellites.*.last_activity | string | ISO timestamp of last project activity (synced from drive.json) |
+| satellites.*.phase_name | string | Current phase name (synced from drive.json) |
+| satellites.*.loop_position | string | Drive loop state: IDLE, PLAN, APPLY, UNIFY |
+| satellites.*.handoff | boolean | Whether a handoff file exists for this project |

package/modules/momentum/src/hooks/_template.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""
+Momentum Hook Template — Canonical reference for data surface injection hooks.
+
+THIS IS A TEMPLATE, NOT A RUNNABLE HOOK.
+Copy this file, rename it to {surface}-hook.py, and customize the marked sections.
+
+=== CONTRACT ===
+Every data surface hook MUST follow this contract:
+  1. Reads ONE JSON file from .accel/momentum/data/{SURFACE_NAME}.json
+  2. Outputs a compact XML-tagged block to stdout
+  3. Wraps output in <{SURFACE_NAME}-awareness> tags
+  4. Includes a BEHAVIOR directive block
+  5. Exits cleanly (exit 0) — never crashes, never blocks
+
+=== DO ===
+  - Read the JSON file using absolute paths (Path(__file__).resolve())
+  - Format a compact summary: IDs, one-line descriptions, grouped by priority/status
+  - Include item count summaries
+  - Include the behavioral directive (passive by default)
+  - Handle missing/empty/malformed files gracefully (output nothing, exit 0)
+  - Keep output compact — hooks fire every prompt, token cost matters
+
+=== DO NOT ===
+  - Never write to any file
+  - Never make network calls
+  - Never import heavy dependencies (sys, json, pathlib ONLY)
+  - Never read multiple data files (one hook = one surface)
+  - Never include full item details in injection (that's what MCP tools are for)
+  - Never include dynamic logic that changes based on time of day, session count, etc.
+
+=== TRIGGERS ===
+Register in .claude/settings.json under UserPromptSubmit:
+  {
+    "type": "command",
+    "command": "python3 /absolute/path/to/.accel/momentum/hooks/{surface}-hook.py"
+  }
+"""
+
+import sys
+import json
+from pathlib import Path
+
+# ============================================================
+# CONFIGURATION — CUSTOMIZE THIS
+# ============================================================
+
+SURFACE_NAME = "example"  # CHANGE THIS: your surface name (e.g., "active", "backlog")
+
+# ============================================================
+# PATH RESOLUTION — DO NOT CHANGE
+# ============================================================
+
+HOOK_DIR = Path(__file__).resolve().parent
+WORKSPACE_ROOT = HOOK_DIR.parent           # .accel/momentum/hooks/ → .accel/momentum/ → workspace root is parent of .accel/momentum/
+# Fix: .accel/momentum/hooks/_template.py → .accel/momentum/ is parent, workspace root is parent of .accel/momentum/
+WORKSPACE_ROOT = HOOK_DIR.parent.parent
+DATA_FILE = WORKSPACE_ROOT / ".accel/momentum" / "data" / f"{SURFACE_NAME}.json"
+
+# ============================================================
+# BEHAVIORAL DIRECTIVE — CUSTOMIZE IF NEEDED
+# ============================================================
+
+BEHAVIOR_DIRECTIVE = f"""BEHAVIOR: This context is PASSIVE AWARENESS ONLY.
+Do NOT proactively mention these items unless:
+  - User explicitly asks (e.g., "what should I work on?", "what's next?")
+  - A deadline is within 24 hours AND user hasn't acknowledged it this session
+For details on any item, use momentum_get_item("{SURFACE_NAME}", id)."""
+
+
+def main():
+    # --- Read hook input from stdin (Claude Code provides session context) ---
+    try:
+        input_data = json.loads(sys.stdin.read())
+        session_id = input_data.get("session_id", "")
+    except (json.JSONDecodeError, OSError):
+        session_id = ""
+
+    # --- Guard: file must exist ---
+    if not DATA_FILE.exists():
+        sys.exit(0)
+
+    # --- Read and parse JSON ---
+    try:
+        data = json.loads(DATA_FILE.read_text())
+    except (json.JSONDecodeError, OSError):
+        sys.exit(0)
+
+    # ============================================================
+    # ITEM EXTRACTION — CUSTOMIZE THIS
+    # ============================================================
+    # Default expects: { "items": [ { "id": "...", "title": "...", ... }, ... ] }
+    # Adjust the key and field names to match your surface's schema.
+
+    items = data.get("items", [])
+
+    if not items:
+        sys.exit(0)
+
+    # ============================================================
+    # SUMMARY FORMATTING — CUSTOMIZE THIS
+    # ============================================================
+    # Build compact summary lines. Keep it SHORT — one line per item max.
+    # Group by status/priority if your schema supports it.
+    # Example format: "- [ID] Title (status)"
+
+    lines = []
+    for item in items:
+        item_id = item.get("id", "?")
+        title = item.get("title", "untitled")
+        status = item.get("status", "")
+        status_suffix = f" ({status})" if status else ""
+        lines.append(f"- [{item_id}] {title}{status_suffix}")
+
+    # --- Output ---
+    if lines:
+        count = len(items)
+        summary = "\n".join(lines)
+        print(f"""<{SURFACE_NAME}-awareness items="{count}">
+{summary}
+
+{BEHAVIOR_DIRECTIVE}
+</{SURFACE_NAME}-awareness>""")
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/modules/momentum/src/hooks/active-hook.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""
+Momentum Hook v2: active-hook-v2.py
+Source: .accel/momentum/data/projects.json (Mission Control unified project management)
+Output: <active-awareness> compact summary grouped by priority
+Filters: items with status NOT in [backlog, archived]
+
+Drop-in replacement for active-hook.py. Swap in settings.json when ready.
+Legacy active-hook.py reads from .accel/momentum/data/active.json (unchanged).
+"""
+
+import sys
+import json
+from pathlib import Path
+from datetime import date, datetime
+
+SURFACE_NAME = "active"
+
+HOOK_DIR = Path(__file__).resolve().parent
+WORKSPACE_ROOT = HOOK_DIR.parent.parent
+DATA_FILE = WORKSPACE_ROOT / ".accel/momentum" / "data" / "projects.json"
+
+BEHAVIOR_DIRECTIVE = f"""BEHAVIOR: This context is PASSIVE AWARENESS ONLY.
+Do NOT proactively mention these items unless:
+  - User explicitly asks (e.g., "what should I work on?", "what's next?")
+  - A deadline is within 24 hours AND user hasn't acknowledged it this session
+For details on any item, use momentum_get_project(id)."""
+
+PRIORITY_ORDER = ["urgent", "high", "medium", "low", "ongoing", "deferred"]
+
+# Staleness thresholds (days since last update)
+STALE_THRESHOLDS = {
+    "urgent": 3,
+    "high": 5,
+    "medium": 7,
+    "low": 14,
+    "ongoing": 14,
+    "deferred": 30,
+}
+
+# Statuses that are NOT active (excluded from active view)
+EXCLUDED_STATUSES = {"backlog", "archived", "completed"}
+
+# Types to exclude from active awareness (checked via MCP during grooms)
+EXCLUDED_TYPES = {"initiative"}
+
+
+def days_since_update(item):
+    """Calculate days since last update. Uses updated_at (ISO datetime)."""
+    ts = item.get("updated_at") or item.get("created_at")
+    if not ts:
+        return None
+    try:
+        d = date.fromisoformat(ts[:10])
+        return (date.today() - d).days
+    except (ValueError, TypeError):
+        return None
+
+
+def main():
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, OSError):
+        pass
+
+    if not DATA_FILE.exists():
+        sys.exit(0)
+
+    try:
+        data = json.loads(DATA_FILE.read_text())
+    except (json.JSONDecodeError, OSError):
+        sys.exit(0)
+
+    items = data.get("items", [])
+    if not items:
+        sys.exit(0)
+
+    # Filter: only active items (not backlog, archived, completed), exclude initiatives
+    active_items = [i for i in items if i.get("status") not in EXCLUDED_STATUSES and i.get("type") not in EXCLUDED_TYPES]
+    if not active_items:
+        sys.exit(0)
+
+    # Group by priority
+    groups = {}
+    for item in active_items:
+        p = item.get("priority", "medium")
+        groups.setdefault(p, []).append(item)
+
+    # Workload balance header
+    blocked_count = sum(1 for i in active_items if i.get("blocked_by"))
+    ongoing_count = sum(1 for i in active_items if i.get("priority") == "ongoing")
+    deferred_count = sum(1 for i in active_items if i.get("status") == "deferred")
+    working_count = len(active_items) - ongoing_count - deferred_count
+    lines = [f"Load: {working_count} active | {blocked_count} blocked | {ongoing_count} ongoing | {deferred_count} deferred"]
+
+    for priority in PRIORITY_ORDER:
+        group = groups.get(priority, [])
+        if not group:
+            continue
+        lines.append(f"[{priority.upper()}]")
+        for item in group:
+            item_id = item.get("id", "?")
+            title = item.get("title", "untitled")
+            status = item.get("status", "")
+            category = item.get("category", "")
+            cat_tag = f"({category}) " if category else ""
+            parts = [f"- [{item_id}] {cat_tag}{title}"]
+            if status:
+                parts[0] += f" ({status})"
+            # Drive signal (phase, loop, plan age, handoff) — only if drive data has real values
+            drive_info = item.get("drive")
+            if drive_info and drive_info.get("is_drive_project") and drive_info.get("phase"):
+                drive_parts = []
+                p_phase = drive_info.get("phase", "?")
+                p_completed = drive_info.get("completed_phases", "?")
+                p_total = drive_info.get("total_phases", "?")
+                p_loop = drive_info.get("loop_position", "?")
+                drive_parts.append(f"Phase {p_completed}/{p_total} ({p_phase})")
+                drive_parts.append(str(p_loop))
+                # Plan age
+                last_plan = drive_info.get("last_plan_completed_at") or drive_info.get("last_update")
+                if last_plan:
+                    try:
+                        lp = last_plan.replace("Z", "+00:00")
+                        if "T" in lp:
+                            lp_date = datetime.fromisoformat(lp).date() if hasattr(datetime, 'fromisoformat') else date.fromisoformat(lp[:10])
+                        else:
+                            lp_date = date.fromisoformat(lp)
+                        age = (date.today() - lp_date).days
+                        drive_parts.append(f"plan {age}d ago")
+                    except (ValueError, TypeError):
+                        pass
+                # Handoff flag
+                p_handoff = drive_info.get("handoff")
+                if isinstance(p_handoff, dict) and p_handoff.get("present"):
+                    drive_parts.append("HANDOFF")
+                elif isinstance(p_handoff, bool) and p_handoff:
+                    drive_parts.append("HANDOFF")
+                parts.append(f"  Drive: {' | '.join(drive_parts)}")
+
+            # Revenue signal
+            rev = item.get("revenue")
+            if rev and rev.get("amount"):
+                rev_type = rev.get("type", "")
+                parts.append(f"  REV: {rev['amount']} ({rev_type})")
+
+            blocked = item.get("blocked_by")
+            if blocked:
+                parts.append(f"  BLOCKED: {blocked}")
+            next_action = item.get("next")
+            if next_action and priority != "ongoing":
+                parts.append(f"  NEXT: {next_action}")
+            deadline = item.get("due_date")
+            if deadline:
+                parts.append(f"  DUE: {deadline}")
+            days = days_since_update(item)
+            threshold = STALE_THRESHOLDS.get(priority, 7)
+            if days is not None:
+                if days >= threshold:
+                    parts.append(f"  STALE: {days}d since update (threshold: {threshold}d)")
+                else:
+                    parts.append(f"  updated: {days}d ago")
+            lines.append("\n".join(parts))
+
+    if lines:
+        count = len(active_items)
+        summary = "\n".join(lines)
+        print(f"""<{SURFACE_NAME}-awareness items="{count}">
+{summary}
+
+{BEHAVIOR_DIRECTIVE}
+</{SURFACE_NAME}-awareness>""")
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/modules/momentum/src/hooks/backlog-hook.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""
+Momentum Hook v2: backlog-hook-v2.py
+Source: .accel/momentum/data/projects.json (Mission Control unified project management)
+Output: <backlog-awareness> compact summary grouped by priority
+Filters: only items with status "backlog"
+
+Drop-in replacement for backlog-hook.py. Swap in settings.json when ready.
+Legacy backlog-hook.py reads from .accel/momentum/data/backlog.json (unchanged).
+"""
+
+import sys
+import json
+from pathlib import Path
+from datetime import date
+
+SURFACE_NAME = "backlog"
+
+HOOK_DIR = Path(__file__).resolve().parent
+WORKSPACE_ROOT = HOOK_DIR.parent.parent
+DATA_FILE = WORKSPACE_ROOT / ".accel/momentum" / "data" / "projects.json"
+
+BEHAVIOR_DIRECTIVE = f"""BEHAVIOR: This context is PASSIVE AWARENESS ONLY.
+Do NOT proactively mention these items unless:
+  - User explicitly asks (e.g., "what's in the backlog?", "what's queued?")
+  - A review_by date has passed AND user hasn't acknowledged it this session
+For details on any item, use momentum_get_project(id)."""
+
+PRIORITY_ORDER = ["high", "medium", "low"]
+
+# Staleness thresholds (days since last update)
+STALE_THRESHOLDS = {
+    "high": 7,
+    "medium": 14,
+    "low": 30,
+}
+
+
+def days_since_update(item):
+    """Calculate days since last update. Uses updated_at (ISO datetime)."""
+    ts = item.get("updated_at") or item.get("created_at")
+    if not ts:
+        return None
+    try:
+        d = date.fromisoformat(ts[:10])
+        return (date.today() - d).days
+    except (ValueError, TypeError):
+        return None
+
+
+def main():
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, OSError):
+        pass
+
+    if not DATA_FILE.exists():
+        sys.exit(0)
+
+    try:
+        data = json.loads(DATA_FILE.read_text())
+    except (json.JSONDecodeError, OSError):
+        sys.exit(0)
+
+    items = data.get("items", [])
+    if not items:
+        sys.exit(0)
+
+    # Filter: only backlog items
+    backlog_items = [i for i in items if i.get("status") == "backlog"]
+    if not backlog_items:
+        sys.exit(0)
+
+    # Group by priority
+    groups = {}
+    for item in backlog_items:
+        p = item.get("priority", "medium")
+        groups.setdefault(p, []).append(item)
+
+    lines = []
+    for priority in PRIORITY_ORDER:
+        group = groups.get(priority, [])
+        if not group:
+            continue
+        lines.append(f"[{priority.upper()}]")
+        for item in group:
+            item_id = item.get("id", "?")
+            title = item.get("title", "untitled")
+            review_by = item.get("review_by")
+            entry = f"- [{item_id}] {title}"
+            if review_by:
+                entry += f" [review by: {review_by}]"
+            days = days_since_update(item)
+            threshold = STALE_THRESHOLDS.get(priority, 14)
+            if days is not None:
+                if days >= threshold:
+                    entry += f" STALE: {days}d"
+                else:
+                    entry += f" ({days}d ago)"
+            lines.append(entry)
+
+    if lines:
+        count = len(backlog_items)
+        summary = "\n".join(lines)
+        print(f"""<{SURFACE_NAME}-awareness items="{count}">
+{summary}
+
+{BEHAVIOR_DIRECTIVE}
+</{SURFACE_NAME}-awareness>""")
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()