tmux-agent 0.1.0

package/.codex/skills/speckit/scripts/bash/spec-registry-graph.sh

@@ -0,0 +1,399 @@
+#!/usr/bin/env bash
+
+# Render a dependency graph from one or more spec-registry.json files.
+#
+# A "Spec Group" is any spec directory that contains `spec-registry.json`.
+# You can pass group ids (e.g. 046) or registry file paths.
+#
+# Usage:
+#   spec-registry-graph.sh <group|registry.json>... [--all] [--focus <id>] [--direction upstream|downstream|both] [--format mermaid|text] [--json]
+#
+# Examples:
+#   spec-registry-graph.sh 046
+#   spec-registry-graph.sh 046 --focus 050
+#   spec-registry-graph.sh --all --focus 045 --direction downstream
+
+set -euo pipefail
+
+JSON_MODE=false
+ALL=false
+FOCUS=""
+DIRECTION="both"
+FORMAT="mermaid"
+SOURCES=()
+
+usage() {
+  cat << 'EOF'
+Usage:
+  spec-registry-graph.sh <group|registry.json>... [--all] [--focus <id>] [--direction upstream|downstream|both] [--format mermaid|text] [--json]
+
+Args:
+  <group|registry.json>   Group spec id (e.g., 046 or 046-core-ng-roadmap) OR a direct path to spec-registry.json
+
+Options:
+  --all                   Scan all `specs/*/spec-registry.json` and merge as one graph
+  --focus <id>            Only render the dependency closure around this spec id (e.g. 045 / 045-xxx / specs/045-*/...)
+  --direction <dir>       Closure direction for --focus: upstream | downstream | both (default: both)
+  --format <fmt>          Output format: mermaid | text (default: mermaid). Ignored in --json mode.
+  --json                  Output machine JSON: nodes/edges/conflicts
+  --help, -h              Show help
+
+Notes:
+  - Edge direction: `A dependsOn B` renders as `B --> A` (B must be done before A).
+  - Nodes referenced in dependsOn but not defined in any loaded registry are shown as "external".
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --json)
+      JSON_MODE=true
+      shift
+      ;;
+    --all)
+      ALL=true
+      shift
+      ;;
+    --focus)
+      if [[ $# -lt 2 || "${2:-}" == --* ]]; then
+        echo "ERROR: --focus requires a value." >&2
+        exit 1
+      fi
+      FOCUS="$2"
+      shift 2
+      ;;
+    --direction)
+      if [[ $# -lt 2 || "${2:-}" == --* ]]; then
+        echo "ERROR: --direction requires a value." >&2
+        exit 1
+      fi
+      DIRECTION="$2"
+      shift 2
+      ;;
+    --format)
+      if [[ $# -lt 2 || "${2:-}" == --* ]]; then
+        echo "ERROR: --format requires a value." >&2
+        exit 1
+      fi
+      FORMAT="$2"
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    --*)
+      echo "ERROR: Unknown option '$1'. Use --help for usage information." >&2
+      exit 1
+      ;;
+    *)
+      SOURCES+=("$1")
+      shift
+      ;;
+  esac
+done
+
+if [[ "$ALL" != true && ${#SOURCES[@]} -eq 0 ]]; then
+  echo "ERROR: Provide at least one <group|registry.json>, or use --all." >&2
+  usage >&2
+  exit 1
+fi
+
+case "$DIRECTION" in
+  upstream|downstream|both) ;;
+  *)
+    echo "ERROR: Invalid --direction: $DIRECTION (use upstream|downstream|both)" >&2
+    exit 1
+    ;;
+esac
+
+case "$FORMAT" in
+  mermaid|text) ;;
+  *)
+    echo "ERROR: Invalid --format: $FORMAT (use mermaid|text)" >&2
+    exit 1
+    ;;
+esac
+
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CHECK="$SCRIPT_DIR/check-prerequisites.sh"
+source "$SCRIPT_DIR/common.sh"
+
+repo_root="$(get_repo_root)"
+
+REGISTRIES=()
+
+if [[ "$ALL" == true ]]; then
+  shopt -s nullglob
+  for f in "$repo_root/specs"/*/spec-registry.json; do
+    REGISTRIES+=("$f")
+  done
+  shopt -u nullglob
+fi
+
+for s in "${SOURCES[@]}"; do
+  if [[ -f "$s" && "$s" == *.json ]]; then
+    REGISTRIES+=("$s")
+    continue
+  fi
+
+  paths_json="$("$CHECK" --json --paths-only --feature "$s")"
+  feature_dir="$(python3 -c 'import json,sys; print(json.load(sys.stdin)["FEATURE_DIR"])' <<<"$paths_json")"
+  registry_json="$feature_dir/spec-registry.json"
+  if [[ ! -f "$registry_json" ]]; then
+    echo "ERROR: spec-registry.json not found for group '$s' at $registry_json" >&2
+    echo "Hint: add a machine-readable registry file (SSoT) under the group feature directory." >&2
+    exit 1
+  fi
+  REGISTRIES+=("$registry_json")
+done
+
+if [[ ${#REGISTRIES[@]} -eq 0 ]]; then
+  echo "ERROR: No registry files found." >&2
+  exit 1
+fi
+
+python3 - "$repo_root" "$JSON_MODE" "$FORMAT" "$FOCUS" "$DIRECTION" "${REGISTRIES[@]}" << 'PY'
+from __future__ import annotations
+
+import json
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+
+Format = Literal["mermaid", "text"]
+Direction = Literal["upstream", "downstream", "both"]
+
+
+repo_root = Path(sys.argv[1])
+json_mode = sys.argv[2].lower() == "true"
+fmt: Format = sys.argv[3]  # type: ignore[assignment]
+focus_raw = sys.argv[4].strip()
+direction: Direction = sys.argv[5]  # type: ignore[assignment]
+registry_files = [Path(p) for p in sys.argv[6:]]
+
+
+def normalize_id(raw: str) -> str:
+    raw = raw.strip()
+    if raw.startswith("specs/"):
+        raw = raw[len("specs/") :]
+    raw = raw.strip().strip("/")
+
+    m = re.match(r"^(?P<prefix>\d{3})", raw)
+    return m.group("prefix") if m else raw
+
+
+@dataclass
+class Node:
+    id: str
+    defined: bool = False
+    dir: str | None = None
+    status: str | None = None
+    groups: set[str] = field(default_factory=set)
+
+
+@dataclass(frozen=True)
+class Edge:
+    dep: str
+    target: str
+
+
+nodes: dict[str, Node] = {}
+edges: set[Edge] = set()
+conflicts: list[dict[str, Any]] = []
+
+
+def get_node(node_id: str) -> Node:
+    if node_id not in nodes:
+        nodes[node_id] = Node(id=node_id)
+    return nodes[node_id]
+
+
+def load_registry(path: Path) -> dict[str, Any]:
+    data = json.loads(path.read_text(encoding="utf-8", errors="replace"))
+    if not isinstance(data, dict):
+        raise ValueError(f"registry must be a JSON object: {path}")
+    return data
+
+
+for registry_file in registry_files:
+    data = load_registry(registry_file)
+    group = str(data.get("group") or registry_file.parent.name)
+    entries = data.get("entries", [])
+    if not isinstance(entries, list):
+        raise ValueError(f"entries must be a list: {registry_file}")
+
+    for entry in entries:
+        if isinstance(entry, str):
+            entry_id = normalize_id(entry)
+            n = get_node(entry_id)
+            n.groups.add(group)
+            continue
+
+        if not isinstance(entry, dict):
+            continue
+
+        entry_id = normalize_id(str(entry.get("id") or entry.get("dir") or ""))
+        if not entry_id:
+            continue
+
+        entry_dir = entry.get("dir")
+        entry_status = entry.get("status")
+        entry_deps = entry.get("dependsOn", [])
+
+        if entry_deps is None:
+            entry_deps = []
+        if not isinstance(entry_deps, list):
+            entry_deps = []
+
+        n = get_node(entry_id)
+        n.groups.add(group)
+
+        if n.defined and (n.dir != entry_dir or n.status != entry_status):
+            conflicts.append(
+                {
+                    "id": entry_id,
+                    "existing": {"dir": n.dir, "status": n.status, "groups": sorted(n.groups)},
+                    "incoming": {"dir": entry_dir, "status": entry_status, "group": group, "file": str(registry_file)},
+                }
+            )
+
+        if not n.defined:
+            n.defined = True
+            n.dir = str(entry_dir) if isinstance(entry_dir, str) else None
+            n.status = str(entry_status) if isinstance(entry_status, str) else None
+
+        for dep in entry_deps:
+            if dep is None:
+                continue
+            dep_id = normalize_id(str(dep))
+            if not dep_id:
+                continue
+            get_node(dep_id)
+            edges.add(Edge(dep=dep_id, target=entry_id))
+
+
+def build_adj(edges_set: set[Edge]) -> tuple[dict[str, set[str]], dict[str, set[str]]]:
+    upstream: dict[str, set[str]] = {}
+    downstream: dict[str, set[str]] = {}
+    for e in edges_set:
+        upstream.setdefault(e.target, set()).add(e.dep)
+        downstream.setdefault(e.dep, set()).add(e.target)
+    return upstream, downstream
+
+
+up, down = build_adj(edges)
+
+
+def closure(start: str, *, direction: Direction) -> set[str]:
+    seen: set[str] = set()
+    queue: list[str] = [start]
+    while queue:
+        cur = queue.pop(0)
+        if cur in seen:
+            continue
+        seen.add(cur)
+        if direction in ("upstream", "both"):
+            for nxt in sorted(up.get(cur, set())):
+                if nxt not in seen:
+                    queue.append(nxt)
+        if direction in ("downstream", "both"):
+            for nxt in sorted(down.get(cur, set())):
+                if nxt not in seen:
+                    queue.append(nxt)
+    return seen
+
+
+focus_id = normalize_id(focus_raw) if focus_raw else ""
+if focus_id:
+    keep = closure(focus_id, direction=direction)
+    nodes = {k: v for k, v in nodes.items() if k in keep}
+    edges = {e for e in edges if e.dep in keep and e.target in keep}
+
+
+def mermaid_id(spec_id: str) -> str:
+    # Mermaid node ids should be identifiers; we prefix with "S" and keep digits.
+    safe = re.sub(r"[^0-9A-Za-z_]", "_", spec_id)
+    if not safe:
+        safe = "unknown"
+    if safe[0].isdigit():
+        safe = "S" + safe
+    return safe
+
+
+def sort_key(n: Node) -> tuple[int, str]:
+    # Prefer numeric ids first.
+    m = re.match(r"^(\d{3})$", n.id)
+    if m:
+        return (0, m.group(1))
+    return (1, n.id)
+
+
+sorted_nodes = sorted(nodes.values(), key=sort_key)
+sorted_edges = sorted(edges, key=lambda e: (e.dep, e.target))
+
+
+if json_mode:
+    payload = {
+        "focus": focus_id or None,
+        "direction": direction,
+        "registries": [str(p) for p in registry_files],
+        "nodes": [
+            {
+                "id": n.id,
+                "defined": n.defined,
+                "dir": n.dir,
+                "status": n.status,
+                "groups": sorted(n.groups),
+            }
+            for n in sorted_nodes
+        ],
+        "edges": [{"dep": e.dep, "target": e.target} for e in sorted_edges],
+        "conflicts": conflicts,
+    }
+    print(json.dumps(payload, ensure_ascii=False))
+    raise SystemExit(0)
+
+
+if fmt == "text":
+    for n in sorted_nodes:
+        deps = sorted(up.get(n.id, set()))
+        status = n.status or ("external" if not n.defined else "")
+        deps_str = ",".join(deps) if deps else "-"
+        print(f"{n.id}\t{status}\tdependsOn:{deps_str}")
+    raise SystemExit(0)
+
+
+# mermaid
+print("graph TD")
+
+for n in sorted_nodes:
+    mid = mermaid_id(n.id)
+    label = n.id
+    if n.status:
+        label = f"{label} · {n.status}"
+    elif not n.defined:
+        label = f"{label} · external"
+    # Use double quotes via Mermaid bracket syntax.
+    print(f'  {mid}["{label}"]')
+
+for e in sorted_edges:
+    a = mermaid_id(e.dep)
+    b = mermaid_id(e.target)
+    print(f"  {a} --> {b}")
+
+# style external nodes
+externals = [n for n in sorted_nodes if not n.defined]
+if externals:
+    print("")
+    print("  classDef external stroke-dasharray: 5 5;")
+    for n in externals:
+        print(f"  class {mermaid_id(n.id)} external;")
+
+if conflicts:
+    print("")
+    print(f"%% WARNING: registry conflicts detected: {len(conflicts)} (use --json to inspect)")
+PY

package/.specify/memory/constitution.md

@@ -0,0 +1,67 @@
+# Project Constitution (Spec Kit)
+
+> This file captures project-level hard constraints, governance, and quality gates. Customize it for your project. If it conflicts with reality, treat this file as the source of truth and update templates and workflows accordingly.
+
+## I. Parallel Development Safety (Non-Negotiable)
+
+- Assume the working tree may contain unrelated, uncommitted changes from other parallel tasks.
+- Prohibit destructive Git commands unless explicitly requested by the user:
+  - `git restore` / `git checkout -- <path>` / `git reset` / `git clean` / `git stash`
+- Do not run VCS write operations unless explicitly requested by the user:
+  - `git add` / `git commit` / `git push` / `git rebase` / `git merge` / `git cherry-pick`
+- Use read-only commands for inspection (e.g., `git status` / `git diff`).
+
+## II. Spec-Driven Artifact Boundaries (`.specify/` + `specs/`)
+
+- Feature directory: `specs/<NNN-*>/`
+  - `spec.md`: requirements and success criteria (WHAT/WHY). Avoid implementation details (HOW).
+  - `plan.md`: implementation approach and landing spots (HOW), including key decisions, risks, and validation strategy.
+  - `tasks.md`: executable task breakdown (dependencies/order/parallel markers). Check items off during implementation.
+- If there is conflict or ambiguity: fix `spec.md` / `plan.md` first, then change code, to avoid spec/implementation drift.
+
+## II.a CLI Context Compatibility (Tmux In/Out)
+
+- CLI commands SHOULD be usable both inside and outside tmux.
+- If a command depends on an attached tmux client or “inside tmux” context (e.g., current client defaults, `display-popup`):
+  - It MUST detect the required context and refuse to run when the context is missing.
+  - It MUST provide an actionable error (how to supply an explicit target like `--session`, or run inside tmux).
+- Default targeting rules MUST be explicit, deterministic, and overridable (avoid silent fallbacks that can cause mis-targeting).
+
+## II.b LLM-Friendly CLI Output Contract (Non-Negotiable)
+
+- stdout MUST be consumable by automation (humans/LLMs/shell pipelines):
+  - If `--json` is supported, it MUST output single-line JSON to stdout and nothing else.
+  - Explanatory text and debug output MUST NOT be mixed into stdout (use stderr).
+- Errors MUST be actionable:
+  - stderr MUST start with `Error:` for user-visible failures.
+  - Exit code MUST be non-zero on failure.
+  - Tracebacks/stacks MUST NOT be printed for expected user errors.
+- IDs MUST be native and stable:
+  - Do not invent synthetic identifiers; prefer tmux native IDs (pane/window ids) with indexes only as convenience within a defined scope.
+  - Any write action MUST resolve and lock the stable native ID before performing side effects; ambiguity MUST fail with zero side effects.
+
+## III. Quality Gates (Must Be Explicit and Executed Before Shipping)
+
+- Each feature must state which gates will be run and what counts as “pass” in `plan.md` (project-specific):
+  - typecheck / lint / test / build / e2e / contract tests
+- For high-risk changes (security, data consistency, payments, permissions, etc.): include regression validation and a clear failure mitigation/rollback strategy.
+
+## IV. Performance & Observability (Enforced When Applicable)
+
+- If this feature touches performance-sensitive paths or external performance boundaries: define budgets and a baseline in `plan.md`, and record reproducible evidence under `specs/<id>/perf/`.
+- Key flows must have diagnosable signals (logs/metrics/traces or equivalent events), including:
+  - Correlation identifiers (requestId/sessionId/entityId, etc.)
+  - PII/sensitive data policy
+  - Toggles and cost model (overhead when enabled/disabled)
+
+## V. Breaking Changes Policy (Must Choose Explicitly)
+
+> Define whether breaking changes are allowed and how migrations are handled.
+
+- Policy: `semver`
+- If introducing a breaking change: include migration steps and a blast radius checklist in `plan.md` and the PR/change notes.
+
+## VI. Template Locations (Optional)
+
+- Default templates: `.specify/templates/*`
+- If you want `$speckit` to be self-contained within the repo: mirror a copy into `.codex/skills/speckit/assets/templates/*` (keep them updated together to avoid drift).

package/.specify/templates/agent-file-template.md

@@ -0,0 +1,28 @@
+# [PROJECT NAME] Development Guidelines
+
+Auto-generated from all feature plans. Last updated: [DATE]
+
+## Active Technologies
+
+[EXTRACTED FROM ALL PLAN.MD FILES]
+
+## Project Structure
+
+```text
+[ACTUAL STRUCTURE FROM PLANS]
+```
+
+## Commands
+
+[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES]
+
+## Code Style
+
+[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE]
+
+## Recent Changes
+
+[LAST 3 FEATURES AND WHAT THEY ADDED]
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->

package/.specify/templates/checklist-template.md

@@ -0,0 +1,49 @@
+# [CHECKLIST TYPE] Checklist: [FEATURE NAME]
+
+**Purpose**: [Brief description of what this checklist covers]
+**Created**: [DATE]
+**Feature**: [Link to spec.md or relevant documentation]
+
+**Note**: This checklist is generated by the `$speckit checklist` stage based on feature context and requirements.
+
+<!--
+  ============================================================================
+  IMPORTANT: The checklist items below are SAMPLE ITEMS for illustration only.
+
+  The $speckit checklist stage MUST replace these with actual items based on:
+  - User's specific checklist request
+  - Feature requirements from spec.md
+  - Technical context from plan.md
+  - Implementation details from tasks.md
+
+  DO NOT keep these sample items in the generated checklist file.
+  ============================================================================
+-->
+
+## [Category 1]
+
+- [ ] CHK001 First checklist item with clear action
+- [ ] CHK002 Second checklist item
+- [ ] CHK003 Third checklist item
+
+## [Category 2]
+
+- [ ] CHK004 Another category item
+- [ ] CHK005 Item with specific criteria
+- [ ] CHK006 Final item in this category
+
+## Performance & Observability _(if applicable)_
+
+- [ ] CHK0XX Performance budget + baseline measurement recorded (env/tool documented)
+- [ ] CHK0XX No critical regression (or justified in Complexity Tracking)
+- [ ] CHK0XX Logs/metrics/traces updated for key flows; PII/overhead reviewed
+- [ ] CHK0XX Diagnostics include stable identifiers to correlate requests/sessions/entities
+- [ ] CHK0XX Data consistency boundaries documented (transaction/atomicity/ordering as applicable)
+- [ ] CHK0XX Breaking change declared and migration note linked (per project policy)
+
+## Notes
+
+- Check items off as completed: `[x]`
+- Add comments or findings inline
+- Link to relevant resources or documentation
+- Items are numbered sequentially for easy reference

package/.specify/templates/plan-template.md

@@ -0,0 +1,126 @@
+# Implementation Plan: [FEATURE]
+
+**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
+**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
+
+**Note**: This template is copied into `specs/[###-feature-name]/plan.md` by the
+Speckit plan workflow (`setup-plan.sh`).
+
+## Summary
+
+[Extract from feature spec: primary requirement + technical approach from research]
+
+## Technical Context
+
+<!--
+  ACTION REQUIRED: Replace the content in this section with the technical details
+  for the project. The structure here is presented in advisory capacity to guide
+  the iteration process.
+-->
+
+**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]  
+**Primary Dependencies**: [e.g., React, Next.js, FastAPI, Postgres, Redis or NEEDS CLARIFICATION]  
+**Storage**: [if applicable, e.g., files / N/A]  
+**Testing**: [e.g., Vitest, Jest, Pytest, Go test or NEEDS CLARIFICATION]  
+**Target Platform**: [e.g., Node.js 20+, browsers, iOS/Android]  
+**Project Type**: [single repo / monorepo / packages + apps]  
+**Performance Goals**: [budgets + measurement method (benchmark/profile) or NEEDS CLARIFICATION]  
+**Constraints**: [include diagnostics overhead budgets if applicable]  
+**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
+
+## Constitution Check
+
+_GATE: Must pass before implementation. Re-check after Phase 1 design._
+
+- Answer the following BEFORE starting implementation, and re-check after Phase 1:
+  - What user value is delivered, and how is it validated (acceptance scenarios / SC-*)?
+  - What public/external surfaces change (API/CLI/UI/config), and what is the compatibility policy?
+  - What docs/specs must be updated first (docs-first where applicable) to avoid drift?
+  - What are the key risks (security, data loss, privacy, performance) and mitigations?
+  - If performance-sensitive: what budgets/baselines exist, and how are regressions prevented?
+  - What diagnostics/observability signals are required for triage (logs/metrics/traces)?
+  - What quality gates will be run before merge (typecheck / lint / test / build), and what counts as “pass”?
+
+## Perf Evidence Plan (IF APPLICABLE)
+
+> If this feature touches performance-sensitive paths or external performance boundaries: this section must be filled. Otherwise mark it as `N/A`.
+
+- Baseline semantics: before/after code change OR A/B strategy (choose one)
+- envId: <os-arch.cpu.runtime-version>
+- tool: <benchmark/profile tool name>
+- collect (before): `specs/<id>/perf/before.<envId>.<tag>.<ext>`
+- collect (after): `specs/<id>/perf/after.<envId>.<tag>.<ext>`
+- diff: `specs/<id>/perf/diff.before__after.<ext>` (if applicable)
+- Failure policy: if results are not comparable (env/tool changes, insufficient sample size, high variance) → re-run or narrow the scope; do not draw hard conclusions when not comparable.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/[###-feature]/
+├── plan.md              # This file ($speckit plan output)
+├── research.md          # Phase 0 output ($speckit plan)
+├── data-model.md        # Phase 1 output ($speckit plan)
+├── quickstart.md        # Phase 1 output ($speckit plan)
+├── contracts/           # Phase 1 output ($speckit plan)
+├── notes/               # Optional: handoff notes / entry points ($speckit notes)
+└── tasks.md             # Phase 2 output ($speckit tasks - NOT created by $speckit plan)
+```
+
+### Source Code (repository root)
+
+<!--
+  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
+  for this feature. Delete unused options and expand the chosen structure with
+  real paths (e.g., apps/admin, packages/something). The delivered plan must
+  not include Option labels.
+-->
+
+```text
+# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
+src/
+├── models/
+├── services/
+├── cli/
+└── lib/
+
+tests/
+├── contract/
+├── integration/
+└── unit/
+
+# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
+backend/
+├── src/
+│   ├── models/
+│   ├── services/
+│   └── api/
+└── tests/
+
+frontend/
+├── src/
+│   ├── components/
+│   ├── pages/
+│   └── services/
+└── tests/
+
+# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
+api/
+└── [same as backend above]
+
+ios/ or android/
+└── [platform-specific structure: feature modules, UI flows, platform tests]
+```
+
+**Structure Decision**: [Document the selected structure and reference the real
+directories captured above]
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+| Violation                  | Why Needed         | Simpler Alternative Rejected Because |
+| -------------------------- | ------------------ | ------------------------------------ |
+| [e.g., 4th project]        | [current need]     | [why 3 projects insufficient]        |
+| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient]  |