opencode-codeops 1.4.0

package/scripts/codeops-roadmap-sync.sh

@@ -0,0 +1,275 @@
+#!/usr/bin/env bash
+#
+# codeops-roadmap-sync.sh — deterministic roadmap counter/cascade recomputation.
+#
+# CodeOps Artifact Schema: 1
+#
+# The roadmap skill owns stage JUDGMENT; this script owns the ARITHMETIC (the prose-vs-script
+# division, same as codeops-migrate.sh). It recomputes, from disk:
+#   - each roadmap's header `> **Progress**: D / T (P%)` — counting only top-level `RD-*` rows at
+#     ✅ Done / total `RD-*` rows (`T-*` task rows and `↳ DEF-n` sub-rows are excluded);
+#   - nested layout only: each feature's portfolio row `Progress` (`D/T RDs`) and rolled-up
+#     `Status`, and the portfolio header `> **Features**: X / Y done`.
+# Roll-up precedence: any ⛔ → ⛔; all RDs Done with an open `## Open follow-ons` row → 🔄; all RDs
+# Done and none open → ✅; any 🔄 → 🔄; else ⬜.
+# It rewrites a computed value only when the existing value is the engine's own computed shape (a
+# trailing ` · …` / ` (…)` annotation is preserved verbatim); a hand-maintained value (e.g. `n/a`,
+# free text) is left untouched and reported as informational HELD, and that row's Status is not
+# re-rolled. It never infers or changes a Stage cell, never touches Notes or prose, and never
+# executes repo data. Execution-plan checklists and plan metadata are the authoritative inputs;
+# roadmaps remain derived views.
+#
+# Usage:
+#   codeops-roadmap-sync.sh            # rewrite the computed values in place
+#   codeops-roadmap-sync.sh --check    # report drift, change nothing; exit 1 on drift
+#   codeops-roadmap-sync.sh --dry-run  # print the would-be updates, change nothing
+# Exit: 0 = in sync / updated / only HELD; 1 = drift found (--check) or write failure; 2 = bad
+#       usage; 3 = python3 unavailable. HELD (preserved hand-maintained values) is informational
+#       and never sets a non-zero exit.
+
+set -uo pipefail
+
+MODE="write"
+for arg in "$@"; do
+  case "$arg" in
+    --check)   MODE="check" ;;
+    --dry-run) MODE="dry" ;;
+    -h|--help) grep -E '^# ' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) printf 'ERROR: unknown argument: %s\n' "$arg" >&2; exit 2 ;;
+  esac
+done
+
+command -v python3 >/dev/null 2>&1 || {
+  printf 'ERROR: python3 is required for roadmap parsing.\n' >&2
+  exit 3
+}
+
+# Layout detection — the canonical grep from _shared/layout-convention.md.
+layout="flat"
+if [[ -f codeops/.codeops.yml ]] && grep -Eq '^codeopsLayout:[[:space:]]*nested[[:space:]]*$' codeops/.codeops.yml; then
+  layout="nested"
+fi
+
+today="$(date '+%Y-%m-%d')"
+
+MODE="$MODE" LAYOUT="$layout" TODAY="$today" python3 - <<'PY'
+import glob, os, re, sys
+
+mode = os.environ["MODE"]          # write | check | dry
+layout = os.environ["LAYOUT"]      # flat | nested
+today = os.environ["TODAY"]
+
+drift = []      # stale COMPUTED values — a real correction (--check exits 1; write applies it)
+held = []       # preserved hand-maintained values — informational, never an error
+changed = []    # files rewritten (write mode)
+
+# Computed-value shapes. Group 1 is the token the engine owns and may rewrite; group 2 is a
+# free-text annotation the engine must preserve verbatim. Patterns are linear — an anchored greedy
+# tail with no nested quantifiers — so untrusted cell text cannot cause pathological backtracking.
+FEATURE_PROGRESS = re.compile(r'^(\d+ / \d+ \(\d+%\))(.*)$')   # per-feature "> **Progress**:" value
+PORTFOLIO_PROG   = re.compile(r'^(\d+/\d+ RDs)(.*)$')          # portfolio Progress cell
+FEATURES_HDR     = re.compile(r'^(\d+ / \d+ done)(.*)$')       # portfolio "> **Features**:" value
+
+def parse_rows(text):
+    """Top-level tracker rows as (id, stage, status) — skips header/separator/`↳` sub-rows."""
+    rows = []
+    in_table = False
+    for line in text.splitlines():
+        if re.match(r'\|\s*ID\s*\|', line):
+            in_table = True
+            continue
+        if in_table:
+            if not line.startswith('|'):
+                in_table = False
+                continue
+            cells = [c.strip() for c in line.strip().strip('|').split('|')]
+            if not cells or set(cells[0]) <= {'-', ' '}:
+                continue
+            rid = cells[0]
+            if rid.startswith('↳') or rid in ('—', '-', ''):
+                continue
+            stage = cells[4] if len(cells) > 4 else ''
+            status = cells[5] if len(cells) > 5 else ''
+            rows.append((rid, stage, status))
+    return rows
+
+def is_rd_row(rid):
+    """A top-level requirement row. `T-*` tasks and any non-RD id never count toward the fraction."""
+    return bool(re.match(r'RD-\d', rid))
+
+def progress_of(text):
+    """(done, total, pct, rows) — the fraction counts only `RD-*` rows; `rows` keeps every parsed
+    top-level row (incl. `T-*`) for the roll-up's status scan."""
+    rows = parse_rows(text)
+    rd_rows = [r for r in rows if is_rd_row(r[0])]
+    total = len(rd_rows)
+    done = sum(1 for _, stage, status in rd_rows if '✅' in status or stage.startswith('Done'))
+    pct = round(done / total * 100) if total else 0
+    return done, total, pct, rows
+
+def has_open_followon(text):
+    """True iff an `## Open follow-ons` section holds a table whose last column header is `Status`
+    and at least one data row's Status cell contains no ✅. A section whose table is not
+    `Status`-last is ignored (fail-safe — no false hold). A pure parse — it never affects the RD
+    fraction, only the roll-up."""
+    in_sec = False
+    valid = False                                    # a `Status`-last header row was seen
+    for line in text.splitlines():
+        if re.match(r'^##\s+Open follow-ons\s*$', line):
+            in_sec = True
+            valid = False
+            continue
+        if in_sec and line.startswith('## '):
+            break                                    # the next section ends it
+        if in_sec and line.startswith('|'):
+            cells = [c.strip() for c in line.strip().strip('|').split('|')]
+            if not cells or set(cells[-1]) <= {'-', ' '}:
+                continue                             # separator row
+            if cells[-1] == 'Status':
+                valid = True                         # header row: last column is `Status`
+                continue
+            if not valid or not cells[-1]:
+                continue                             # no `Status`-last header yet, or empty cell
+            if '✅' not in cells[-1]:
+                return True
+    return False
+
+def replace_header(text, key, new_line):
+    """Unconditionally replace a `> **Key**: …` line — used for the computed Last Updated stamp.
+    The replacement is a literal callable so data-derived text is never read as a regex template."""
+    pat = re.compile(r'(?m)^> \*\*' + re.escape(key) + r'\*\*:.*$')
+    if pat.search(text):
+        return pat.sub(lambda _m: new_line, text, count=1)
+    return text
+
+def sub_computed_header(text, key, computed_token, regex, path):
+    """Rewrite a computed header (`Progress` / `Features`) only when its value is the engine's own
+    computed shape and the token is stale, preserving any trailing free-text suffix. A value that
+    is not the computed shape is left untouched and reported HELD."""
+    pat = re.compile(r'(?m)^> \*\*' + re.escape(key) + r'\*\*: (.*)$')
+    m = pat.search(text)
+    if not m:
+        drift.append(f"{path}: header line '> **{key}**:' not found (malformed — skipped)")
+        return text, False
+    value = m.group(1)
+    cm = regex.match(value)
+    if not cm:
+        held.append(f"{path}: {key} '{value}' (hand-maintained)")
+        return text, False
+    if cm.group(1) == computed_token:
+        return text, False                           # in sync (suffix already preserved in place)
+    drift.append(f"{path}: {key} token '{cm.group(1)}' — computed '{computed_token}'")
+    new_line = f"> **{key}**: {computed_token}{cm.group(2)}"
+    return pat.sub(lambda _m: new_line, text, count=1), True
+
+def sync_feature_roadmap(path):
+    """Sync one flat/per-feature roadmap header; return (done, total, rows, feat_open)."""
+    text = open(path, encoding='utf-8').read()
+    done, total, pct, rows = progress_of(text)
+    feat_open = has_open_followon(text)
+    token = f"{done} / {total} ({pct}%)"
+    text2, did = sub_computed_header(text, 'Progress', token, FEATURE_PROGRESS, path)
+    if did and mode == 'write':
+        text2 = replace_header(text2, 'Last Updated', f"> **Last Updated**: {today}")
+        try:
+            open(path, 'w', encoding='utf-8').write(text2)
+            changed.append(path)
+        except OSError as e:
+            print(f"ERROR: failed to write {path}: {e}", file=sys.stderr)
+            sys.exit(1)
+    return done, total, rows, feat_open
+
+def roll_up(done, total, rows, feat_open):
+    """Feature Status from its rows. `⛔` on any blocked row wins; otherwise all RDs Done holds at
+    `🔄` when a follow-on is open, else `✅`; else `🔄` if any row is executing; else `⬜`."""
+    statuses = [s for _, _, s in rows]
+    if any('⛔' in s for s in statuses):
+        return '⛔'
+    if total and done == total and feat_open:
+        return '🔄'
+    if total and done == total:
+        return '✅'
+    if any('🔄' in s for s in statuses):
+        return '🔄'
+    return '⬜'
+
+if layout == 'flat':
+    path = 'plans/00-roadmap.md'
+    if not os.path.isfile(path):
+        print('codeops-roadmap-sync: no roadmap found (flat layout) — nothing to sync.')
+        sys.exit(0)
+    sync_feature_roadmap(path)
+else:
+    features = {}
+    for path in sorted(glob.glob('codeops/features/*/00-roadmap.md')):
+        feat = path.split('/')[2]
+        features[feat] = sync_feature_roadmap(path)
+    # Portfolio cascade.
+    ppath = 'codeops/00-roadmap.md'
+    if os.path.isfile(ppath):
+        text = open(ppath, encoding='utf-8').read()
+        lines = text.splitlines()
+        out, in_features, feature_rows_total, feature_rows_done = [], False, 0, 0
+        for line in lines:
+            if line.startswith('## Features'):
+                in_features = True
+            elif line.startswith('## ') and in_features:
+                in_features = False
+            if in_features and line.startswith('|'):
+                cells = [c.strip() for c in line.strip().strip('|').split('|')]
+                feat = cells[0] if cells else ''
+                if feat in features and len(cells) >= 6:
+                    done, total, rows, feat_open = features[feat]
+                    cm = PORTFOLIO_PROG.match(cells[3])
+                    if not cm:
+                        # Hand-maintained cell (n/a, free text): preserve it, do NOT re-roll this
+                        # row's Status, and exclude it from the computed Features tally.
+                        held.append(f"{ppath}: row '{feat}' Progress '{cells[3]}' (hand-maintained)")
+                    else:
+                        roll = roll_up(done, total, rows, feat_open)
+                        new_token = f"{done}/{total} RDs"
+                        if cm.group(1) != new_token or cells[4] != roll:
+                            drift.append(f"{ppath}: row '{feat}' is '{cells[3]}'/'{cells[4]}' "
+                                         f"— computed '{new_token}'/'{roll}'")
+                            cells[3] = new_token + cm.group(2)
+                            cells[4] = roll
+                            cells[5] = today if mode == 'write' else cells[5]
+                            line = '| ' + ' | '.join(cells) + ' |'
+                        feature_rows_total += 1
+                        feature_rows_done += 1 if roll == '✅' else 0
+            out.append(line)
+        text2 = '\n'.join(out) + ('\n' if text.endswith('\n') else '')
+        feat_token = f"{feature_rows_done} / {feature_rows_total} done"
+        text2, _ = sub_computed_header(text2, 'Features', feat_token, FEATURES_HDR, ppath)
+        if mode == 'write' and text2 != text:
+            text2 = replace_header(text2, 'Last Updated', f"> **Last Updated**: {today}")
+            try:
+                open(ppath, 'w', encoding='utf-8').write(text2)
+                changed.append(ppath)
+            except OSError as e:
+                print(f"ERROR: failed to write {ppath}: {e}", file=sys.stderr)
+                sys.exit(1)
+    else:
+        drift.append(f"{ppath}: portfolio roadmap missing in nested layout")
+
+if held:
+    print('codeops-roadmap-sync: preserved hand-maintained values:')
+    for h in held:
+        print(f'  HELD {h}')
+
+if drift:
+    print('codeops-roadmap-sync: drift detected:')
+    for d in drift:
+        print(f'  DRIFT {d}')
+    if mode == 'check':
+        sys.exit(1)
+    if mode == 'dry':
+        print('(dry-run: nothing written)')
+        sys.exit(0)
+    print(f'codeops-roadmap-sync: updated {len(changed)} file(s): ' + ', '.join(changed))
+    sys.exit(0)
+else:
+    if not held:
+        print('codeops-roadmap-sync: all counters in sync — nothing to do.')
+    sys.exit(0)
+PY

package/scripts/codeops_outcomes.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""Record and summarize opt-in, content-free CodeOps outcome events."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import sys
+from collections import Counter
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+EVENTS = {
+    "task-verified", "verification-run", "review-completed", "finding-escaped",
+    "rework-cycle", "scope-drift", "assumption-invalidated", "runtime-ambiguity",
+    "recovery-attempt",
+}
+STAGES = {"requirements", "specification", "planning", "execution", "verification", "review", "recovery"}
+RESULTS = {"pass", "fail", "resolved", "blocked", "accurate", "inaccurate"}
+
+
+def config_for(root: Path) -> dict[str, Any]:
+    path = root / "codeops" / "codeops.json"
+    if not path.is_file():
+        return {}
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return value if isinstance(value, dict) else {}
+
+
+def enabled(root: Path) -> bool:
+    return config_for(root).get("metrics", {}).get("enabled") is True
+
+
+def default_store() -> Path:
+    override = os.environ.get("CODEOPS_DATA_DIR")
+    # OpenCode keeps its user data under ~/.local/share/opencode; the override
+    # lets projects and tests redirect the store without touching the default.
+    base = (
+        Path(override).expanduser()
+        if override
+        else Path.home() / ".local" / "share" / "opencode" / "codeops"
+    )
+    return base / "outcomes.jsonl"
+
+
+def project_id(root: Path) -> str:
+    return hashlib.sha256(str(root.resolve()).encode()).hexdigest()[:12]
+
+
+def emit(args: argparse.Namespace) -> int:
+    root = Path(args.root).resolve()
+    if not enabled(root):
+        print("CodeOps outcomes disabled; no event recorded.", file=sys.stderr)
+        return 0
+    if args.event not in EVENTS or args.stage not in STAGES or args.result not in RESULTS:
+        print("Invalid event, stage, or result enum.", file=sys.stderr)
+        return 2
+    event = {
+        "schema": 1,
+        "timestamp": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "project": project_id(root),
+        "event": args.event,
+        "stage": args.stage,
+        "result": args.result,
+        "count": args.count,
+    }
+    if args.duration_ms is not None:
+        event["duration_ms"] = args.duration_ms
+    store = Path(args.store).expanduser()
+    store.parent.mkdir(parents=True, exist_ok=True)
+    with store.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(event, separators=(",", ":"), sort_keys=True) + "\n")
+    print("Outcome event recorded.")
+    return 0
+
+
+def read_events(store: Path, project: str | None) -> list[dict[str, Any]]:
+    if not store.is_file():
+        return []
+    events: list[dict[str, Any]] = []
+    for line_number, line in enumerate(store.read_text(encoding="utf-8").splitlines(), 1):
+        try:
+            value = json.loads(line)
+        except json.JSONDecodeError:
+            print(f"Ignoring malformed event at line {line_number}.", file=sys.stderr)
+            continue
+        if isinstance(value, dict) and value.get("schema") == 1 and (project is None or value.get("project") == project):
+            events.append(value)
+    return events
+
+
+def report(args: argparse.Namespace) -> int:
+    root = Path(args.root).resolve()
+    project = None if args.all_projects else project_id(root)
+    events = read_events(Path(args.store).expanduser(), project)
+    by_event = Counter(event.get("event") for event in events)
+    by_result = Counter(event.get("result") for event in events)
+    totals = Counter()
+    for event in events:
+        totals[event.get("event")] += int(event.get("count", 1))
+    payload = {
+        "events": len(events),
+        "by_event": dict(sorted(by_event.items())),
+        "by_result": dict(sorted(by_result.items())),
+        "totals": dict(sorted(totals.items())),
+    }
+    if args.as_json:
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        print(f"CodeOps outcome events: {len(events)}")
+        for event, count in sorted(totals.items()):
+            print(f"{event}: {count}")
+        if not events:
+            print("No local outcome evidence is available for this scope.")
+    return 0
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.set_defaults(store=str(default_store()))
+    sub = parser.add_subparsers(dest="command", required=True)
+    emit_parser = sub.add_parser("emit")
+    emit_parser.add_argument("--root", default=".")
+    emit_parser.add_argument("--store", default=str(default_store()))
+    emit_parser.add_argument("--event", required=True, choices=sorted(EVENTS))
+    emit_parser.add_argument("--stage", required=True, choices=sorted(STAGES))
+    emit_parser.add_argument("--result", required=True, choices=sorted(RESULTS))
+    emit_parser.add_argument("--count", type=int, default=1)
+    emit_parser.add_argument("--duration-ms", type=int)
+    report_parser = sub.add_parser("report")
+    report_parser.add_argument("--root", default=".")
+    report_parser.add_argument("--store", default=str(default_store()))
+    report_parser.add_argument("--all-projects", action="store_true")
+    report_parser.add_argument("--json", action="store_true", dest="as_json")
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    duration = getattr(args, "duration_ms", None)
+    if getattr(args, "count", 1) < 1 or (duration is not None and duration < 0):
+        print("count must be positive and duration must be non-negative.", file=sys.stderr)
+        return 2
+    return emit(args) if args.command == "emit" else report(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/codeops_plan.py

@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+"""Derive CodeOps plan progress directly from Markdown artifacts.
+
+This module is intentionally a read-only parser. Markdown remains authoritative;
+the helper has no state store, transition API, revision counter, lock, or journal.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+
+IMPLEMENTS_RE = re.compile(r"^>[ \t]*\*\*Implements\*\*:[ \t]*(.+?)[ \t]*$", re.MULTILINE)
+TARGET_RE = re.compile(
+    r"(?<![A-Za-z0-9_-])(?:[A-Za-z0-9_][A-Za-z0-9_-]*/)?"
+    r"(?:RD-(?:[A-Za-z0-9]+-)*\d+|T-\d+|REQ-[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*)"
+    r"(?![A-Za-z0-9_-])"
+)
+TASK_RE = re.compile(r"^-\s*\[([ xX~!])\]\s+(.+?)\s*$", re.MULTILINE)
+BLOCKED_REASON_RE = re.compile(r"(?:blocked|reason)\s*:\s*\S", re.IGNORECASE)
+_PROGRESS_WIDTH = 10
+_PROGRESS_FILLED = "█"
+_PROGRESS_EMPTY = "░"
+
+
+@dataclass(frozen=True)
+class Task:
+    """One authoritative Markdown checklist task and its derived state."""
+
+    marker: str
+    text: str
+
+    @property
+    def state(self) -> str:
+        """Return the stable user-facing state represented by the task marker."""
+        return {" ": "not-started", "~": "verification-pending", "x": "verified", "!": "blocked"}[
+            self.marker.lower()
+        ]
+
+
+@dataclass(frozen=True)
+class PlanStatus:
+    """Read-only lifecycle, progress, and diagnostics derived for one plan."""
+
+    plan: str
+    implements: tuple[str, ...]
+    lifecycle: str
+    total: int
+    not_started: int
+    verification_pending: int
+    verified: int
+    blocked: int
+    next_task: str | None
+    problems: tuple[str, ...]
+
+
+def parse_implements(index_text: str) -> tuple[str, ...]:
+    """Return ordered, de-duplicated requirement or tracker targets for a plan."""
+    match = IMPLEMENTS_RE.search(index_text)
+    if not match:
+        return ()
+    return tuple(dict.fromkeys(TARGET_RE.findall(match.group(1))))
+
+
+def parse_tasks(execution_text: str) -> tuple[Task, ...]:
+    """Parse only the four authoritative execution checklist markers."""
+    return tuple(Task(marker.lower(), text.strip()) for marker, text in TASK_RE.findall(execution_text))
+
+
+def next_task(tasks: tuple[Task, ...]) -> Task | None:
+    """Resume verification first, otherwise start the first untouched task."""
+    return next((task for task in tasks if task.marker == "~"), None) or next(
+        (task for task in tasks if task.marker == " "), None
+    )
+
+
+def lifecycle(tasks: tuple[Task, ...]) -> str:
+    """Derive the plan's Ready/Executing/Done/Blocked lifecycle from its checklist."""
+    if any(task.marker == "!" for task in tasks):
+        return "Blocked"
+    if tasks and all(task.marker == "x" for task in tasks):
+        return "Done"
+    if any(task.marker in {"~", "x"} for task in tasks):
+        return "Executing"
+    return "Ready"
+
+
+def render_progress(verified: int, total: int) -> str:
+    """Render verified task progress with both visual and textual context.
+
+    The bar deliberately rounds filled cells down so it never visually suggests that a completion
+    threshold has been reached early. The accompanying rounded percentage and exact fraction make
+    the display understandable when block glyphs are unavailable or difficult to distinguish.
+
+    Args:
+        verified: Number of tasks whose verification passed.
+        total: Total number of tasks in the checklist.
+
+    Returns:
+        A single user-facing progress line containing ten cells, counts, and percentage.
+
+    Raises:
+        ValueError: If either count is negative or verified exceeds total.
+        TypeError: If either count is not an integer.
+
+    Example:
+        >>> render_progress(1, 3)
+        'Progress: [███░░░░░░░] 1/3 tasks (33%)'
+    """
+    if isinstance(verified, bool) or not isinstance(verified, int):
+        raise TypeError("verified must be an integer")
+    if isinstance(total, bool) or not isinstance(total, int):
+        raise TypeError("total must be an integer")
+    if verified < 0 or total < 0:
+        raise ValueError("task counts cannot be negative")
+    if verified > total:
+        raise ValueError("verified tasks cannot exceed total tasks")
+
+    filled = (verified * _PROGRESS_WIDTH // total) if total else 0
+    percentage = round(verified / total * 100) if total else 0
+    cells = (_PROGRESS_FILLED * filled) + (_PROGRESS_EMPTY * (_PROGRESS_WIDTH - filled))
+    return f"Progress: [{cells}] {verified}/{total} tasks ({percentage}%)"
+
+
+def inspect_plan(plan_dir: Path, root: Path | None = None) -> PlanStatus:
+    """Inspect one plan directory without mutating it."""
+    index_path = plan_dir / "00-index.md"
+    execution_path = plan_dir / "99-execution-plan.md"
+    problems: list[str] = []
+    index_text = index_path.read_text(encoding="utf-8") if index_path.is_file() else ""
+    execution_text = execution_path.read_text(encoding="utf-8") if execution_path.is_file() else ""
+    if not index_path.is_file():
+        problems.append("missing required 00-index.md")
+    if not execution_path.is_file():
+        problems.append("missing required 99-execution-plan.md")
+    implements = parse_implements(index_text)
+    if not implements:
+        problems.append("00-index.md must declare one or more requirement or tracker targets in **Implements**")
+    tasks = parse_tasks(execution_text)
+    if not tasks:
+        problems.append("99-execution-plan.md contains no execution tasks")
+    for task in tasks:
+        if task.marker == "!" and not BLOCKED_REASON_RE.search(task.text):
+            problems.append(f"blocked task lacks a visible 'Blocked: <reason>': {task.text}")
+    counts = {marker: sum(task.marker == marker for task in tasks) for marker in (" ", "~", "x", "!")}
+    candidate = next_task(tasks)
+    display = str(plan_dir.resolve())
+    if root is not None:
+        try:
+            display = plan_dir.resolve().relative_to(root.resolve()).as_posix()
+        except ValueError:
+            pass
+    return PlanStatus(
+        plan=display,
+        implements=implements,
+        lifecycle=lifecycle(tasks),
+        total=len(tasks),
+        not_started=counts[" "],
+        verification_pending=counts["~"],
+        verified=counts["x"],
+        blocked=counts["!"],
+        next_task=candidate.text if candidate else None,
+        problems=tuple(problems),
+    )
+
+
+def discover_plans(root: Path) -> tuple[Path, ...]:
+    """Discover flat and nested plan directories by their execution plan."""
+    paths = set((root / "plans").glob("*/99-execution-plan.md"))
+    paths.update((root / "codeops" / "features").glob("*/plans/*/99-execution-plan.md"))
+    return tuple(sorted(path.parent for path in paths))
+
+
+def rd_delivery(statuses: tuple[PlanStatus, ...]) -> dict[str, str]:
+    """Derive each RD's delivery state from its implementing plan or plans."""
+    grouped: dict[str, list[str]] = {}
+    for status in statuses:
+        for rd_id in status.implements:
+            if not rd_id.rsplit("/", 1)[-1].startswith("RD-"):
+                continue
+            grouped.setdefault(rd_id, []).append(status.lifecycle)
+    result: dict[str, str] = {}
+    for rd_id, states in grouped.items():
+        if "Blocked" in states:
+            result[rd_id] = "Blocked"
+        elif states and all(state == "Done" for state in states):
+            result[rd_id] = "Done"
+        elif any(state == "Executing" for state in states):
+            result[rd_id] = "Executing"
+        else:
+            result[rd_id] = "Ready"
+    return result
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command-line parser for read-only plan inspection."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", type=Path, default=Path.cwd())
+    parser.add_argument("--plan", type=Path, help="inspect one plan directory")
+    output = parser.add_mutually_exclusive_group()
+    output.add_argument("--json", action="store_true")
+    output.add_argument(
+        "--progress-bar",
+        action="store_true",
+        help="render verified task progress as an accessible ten-cell bar",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Inspect selected plans and write the requested read-only representation to stdout."""
+    args = build_parser().parse_args(argv)
+    root = args.root.resolve()
+    plan_dirs = (args.plan if args.plan.is_absolute() else root / args.plan,) if args.plan else discover_plans(root)
+    statuses = tuple(inspect_plan(path, root) for path in plan_dirs)
+    payload = {"plans": [asdict(status) for status in statuses], "requirements": rd_delivery(statuses)}
+    if args.json:
+        print(json.dumps(payload, indent=2))
+    elif args.progress_bar:
+        for status in statuses:
+            print(render_progress(status.verified, status.total))
+    else:
+        for status in statuses:
+            progress = f"{status.verified}/{status.total} verified"
+            print(f"{status.plan}: {status.lifecycle} ({progress})")
+            if status.next_task:
+                print(f"  next: {status.next_task}")
+            for problem in status.problems:
+                print(f"  ERROR: {problem}")
+    return 1 if any(status.problems for status in statuses) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())