opencode-codeops 1.4.0

package/scripts/codeops-migrate.sh

@@ -0,0 +1,355 @@
+#!/usr/bin/env bash
+#
+# codeops-migrate.sh — deterministic flat→nested CodeOps migration engine.
+#
+# This is the single, unit-testable source of truth for the migration ALGORITHM (see
+# plans/codeops-v2-layout/03-02-setup-codeops.md, PF-003). The setup_codeops skill owns the
+# conversational UX (preview, confirmation, reporting) and DELEGATES the path arithmetic and the
+# git mv apply to this script — so there is no prose-vs-script drift. scripts/migration-check.sh
+# asserts this engine's move map, warnings, refusals, and idempotency against a fixture copy.
+#
+# It computes the move map from a flat-layout repo (today: one flat repo == one feature-set), scans
+# for hazards (plans absent from the roadmap; links pointing out of the planning tree), refuses to
+# run on a non-git or dirty tree, rejects/normalizes path-traversal slugs, is idempotent (a marker
+# means "already migrated"), and applies via `git mv` (history preserved), writing the marker and
+# the seeded portfolio roadmap LAST so an interrupted run never leaves a false "migrated" marker.
+#
+# Security: never executes repo data; the feature slug is sanitized so it can never escape
+# codeops/features/. All mutation requires an explicit --yes; absent that, it only previews.
+#
+# Usage:
+#   codeops-migrate.sh --dry-run     # compute + print the move map + warnings; change nothing
+#   codeops-migrate.sh --yes         # apply the migration via git mv (no interactive prompt)
+#   codeops-migrate.sh               # same as --dry-run (safe default; never mutates without --yes)
+# Exit: 0 = success / no-op; 1 = refusal (not a git repo, dirty tree); 2 = bad usage.
+
+set -uo pipefail
+
+DRY=0
+YES=0
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY=1 ;;
+    --yes)     YES=1 ;;
+    -h|--help)
+      grep -E '^# ' "$0" | sed 's/^# \{0,1\}//'
+      exit 0 ;;
+    *)
+      printf 'ERROR: unknown argument: %s\n' "$arg" >&2
+      exit 2 ;;
+  esac
+done
+
+# Apply only on an explicit --yes that is not paired with --dry-run (preview always wins).
+APPLY=0
+if [[ "$YES" -eq 1 && "$DRY" -eq 0 ]]; then
+  APPLY=1
+fi
+
+HAVE_PY3=0
+command -v python3 >/dev/null 2>&1 && HAVE_PY3=1
+
+# slugify <text> — lowercase, collapse every non-alphanumeric run to a single '-', trim '-'.
+# This sanitizes the feature slug so it can never contain '/', '..', or be absolute (Security).
+slugify() {
+  if [[ "$HAVE_PY3" -eq 1 ]]; then
+    python3 - "$1" <<'PY'
+import re, sys
+s = re.sub(r'[^a-z0-9]+', '-', sys.argv[1].lower()).strip('-')
+print(s)
+PY
+  else
+    printf '%s' "$1" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//'
+  fi
+}
+
+# -----------------------------------------------------------------------------
+# Preconditions: must be a git repo; idempotent if already migrated; refuse if dirty.
+# -----------------------------------------------------------------------------
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || {
+  printf 'ERROR: not inside a git repository (git is required for git mv).\n' >&2
+  exit 1
+}
+cd "$ROOT"
+
+if [[ -f codeops/.codeops.yml ]]; then
+  printf 'codeops-migrate: already migrated (codeops/.codeops.yml present) — nothing to do (no-op).\n'
+  exit 0
+fi
+
+# Is there any flat-layout content to migrate at all?
+shopt -s nullglob
+plan_dirs=(plans/*/)
+has_flat=0
+[[ -d requirements ]] && has_flat=1
+[[ -f plans/00-roadmap.md ]] && has_flat=1
+[[ ${#plan_dirs[@]} -gt 0 ]] && has_flat=1
+if [[ "$has_flat" -eq 0 ]]; then
+  printf 'codeops-migrate: no flat-layout artifacts found; nothing to migrate.\n'
+  printf '  (For a fresh repo use the setup_codeops scaffold to create the codeops/ skeleton.)\n'
+  exit 0
+fi
+
+# Migration must run on a clean tree so the whole move lands as one reviewable commit.
+if [[ -n "$(git status --porcelain)" ]]; then
+  printf 'ERROR: working tree is dirty — migration must run on a clean tree so it lands as a\n' >&2
+  printf '       single reviewable commit. Commit or stash your changes first, then re-run.\n' >&2
+  exit 1
+fi
+
+# A non-directory named `codeops` makes every apply step impossible — refuse up front with a
+# clear message instead of failing step-by-step (AR #18).
+if [[ -e codeops && ! -d codeops ]]; then
+  printf 'ERROR: `codeops` exists but is not a directory — the nested layout cannot be created.\n' >&2
+  printf '       Move or remove it, then re-run.\n' >&2
+  exit 1
+fi
+
+# -----------------------------------------------------------------------------
+# Derive the feature slug (roadmap header → else repo dir name), then sanitize.
+# -----------------------------------------------------------------------------
+slug=""
+slug_src=""
+if [[ -f plans/00-roadmap.md ]]; then
+  header="$(grep -E '^> \*\*Feature-Set\*\*:' plans/00-roadmap.md | head -1 | sed -E 's/^> \*\*Feature-Set\*\*:[[:space:]]*//')"
+  if [[ -n "$header" ]]; then
+    slug="$(slugify "$header")"
+    slug_src="roadmap-header"
+  fi
+fi
+if [[ -z "$slug" ]]; then
+  slug="$(slugify "$(basename "$ROOT")")"
+  slug_src="dir-name"
+fi
+# Final safety net: a slug must be a single safe path component.
+if [[ -z "$slug" || "$slug" == *"/"* || "$slug" == *".."* ]]; then
+  printf 'ERROR: could not derive a safe feature slug (got: %q).\n' "$slug" >&2
+  exit 1
+fi
+
+# -----------------------------------------------------------------------------
+# Compute the move map (no file changes here).
+# -----------------------------------------------------------------------------
+moves=()   # each entry: "src|dst"
+[[ -d requirements ]] && moves+=("requirements/|codeops/features/$slug/requirements/")
+for d in plans/*/; do
+  name="$(basename "$d")"
+  [[ "$name" == "_archive" ]] && continue
+  moves+=("plans/$name/|codeops/features/$slug/plans/$name/")
+done
+[[ -f plans/00-roadmap.md ]] && moves+=("plans/00-roadmap.md|codeops/features/$slug/00-roadmap.md")
+if [[ -d plans/_archive ]]; then
+  for a in plans/_archive/*/; do
+    aname="$(basename "$a")"
+    moves+=("plans/_archive/$aname/|codeops/_archive/$aname/")
+  done
+  # Loose FILES directly under plans/_archive/ move too — leaving them behind would strand a
+  # residual plans/ tree after the marker is written (AR #18).
+  for af in plans/_archive/*; do
+    [[ -f "$af" ]] || continue
+    moves+=("$af|codeops/_archive/$(basename "$af")")
+  done
+fi
+
+# -----------------------------------------------------------------------------
+# Hazard scan → warnings (never block; the user resolves these by hand after the move).
+# -----------------------------------------------------------------------------
+warnings=()
+# (a) plan folders on disk but not referenced in the roadmap.
+if [[ -f plans/00-roadmap.md ]]; then
+  for d in plans/*/; do
+    name="$(basename "$d")"
+    [[ "$name" == "_archive" ]] && continue
+    if ! grep -qF "$name" plans/00-roadmap.md; then
+      warnings+=("plan-not-in-roadmap: plans/$name/ is on disk but not referenced in the roadmap")
+    fi
+  done
+fi
+# (a2) loose files directly under plans/ that are NOT the roadmap and NOT inside a plan dir.
+#      The move map only relocates plan dirs + plans/00-roadmap.md, so these would otherwise be
+#      left behind in a surviving plans/ after the marker is written — a half-migrated state. We
+#      cannot guess a feature target for a stray file, so we surface it (never silently orphan it).
+for f in plans/*; do
+  [[ -f "$f" ]] || continue
+  [[ "$(basename "$f")" == "00-roadmap.md" ]] && continue
+  warnings+=("loose-file-not-migrated: $f is directly under plans/ and is left in place (move it by hand)")
+done
+# (a3) loose files directly under plans/_archive/ ARE migrated (into codeops/_archive/), but get
+#      surfaced so the user knows an unusual artifact was found and relocated.
+if [[ -d plans/_archive ]]; then
+  for af in plans/_archive/*; do
+    [[ -f "$af" ]] || continue
+    warnings+=("archive-loose-file: $af is a loose file under plans/_archive/ — it will be moved to codeops/_archive/$(basename "$af")")
+  done
+fi
+# (b) relative links in plan docs that point OUT of the planning tree (into source, etc.).
+#     A structure-preserving move keeps intra-codeops links valid; only out-of-tree links can
+#     break, so we surface them as warnings rather than silently rewriting them (AR #16).
+if [[ "$HAVE_PY3" -eq 1 && -d plans ]]; then
+  while IFS= read -r line; do
+    [[ -n "$line" ]] && warnings+=("$line")
+  done < <(python3 - "$ROOT" <<'PY'
+import os, re, sys
+root = sys.argv[1]
+plans = os.path.join(root, "plans")
+link_re = re.compile(r'\]\(([^)]+)\)')
+inside = ("plans" + os.sep, "requirements" + os.sep)
+for dirpath, _dirs, files in os.walk(plans):
+    for fn in files:
+        if not fn.endswith(".md"):
+            continue
+        fp = os.path.join(dirpath, fn)
+        rel = os.path.relpath(fp, root)
+        try:
+            text = open(fp, encoding="utf-8", errors="replace").read()
+        except OSError:
+            continue
+        for m in link_re.finditer(text):
+            tgt = m.group(1).strip()
+            if tgt.startswith(("http://", "https://", "#", "mailto:")):
+                continue
+            if not tgt.startswith(".."):
+                continue
+            norm = os.path.normpath(os.path.join(os.path.dirname(rel), tgt))
+            if not (norm.startswith(inside) or norm in ("plans", "requirements")):
+                print(f"source-relative-link: {rel} -> {tgt}")
+PY
+  )
+fi
+
+# -----------------------------------------------------------------------------
+# Print the preview (always — dry-run, default, and as the apply log).
+# -----------------------------------------------------------------------------
+if [[ "$APPLY" -eq 1 ]]; then
+  printf 'codeops-migrate: applying flat → nested migration (git mv)\n'
+else
+  printf 'codeops-migrate: dry-run preview (no changes will be made)\n'
+fi
+printf 'SLUG: %s (source: %s)\n' "$slug" "$slug_src"
+for m in "${moves[@]}"; do
+  printf 'MOVE %s -> %s\n' "${m%%|*}" "${m##*|}"
+done
+printf 'CREATE codeops/.codeops.yml\n'
+printf 'CREATE codeops/codeops.json\n'
+printf 'CREATE codeops/00-roadmap.md\n'
+for w in "${warnings[@]:-}"; do
+  [[ -n "$w" ]] && printf 'WARN %s\n' "$w"
+done
+
+if [[ "$APPLY" -ne 1 ]]; then
+  [[ "$DRY" -eq 0 ]] && printf '\n(preview only; re-run with --yes to apply)\n'
+  exit 0
+fi
+
+# -----------------------------------------------------------------------------
+# Apply: git mv each mapping, then write the marker + seeded portfolio LAST.
+#
+# Every step is failure-checked (AR #18): the FIRST failed step aborts the apply with a
+# non-zero exit, the marker is NEVER written after a failure (so the idempotency guard can
+# never brick a retry on a half-migrated tree), and the report names the failing step.
+# `set -e` is deliberately not relied on — explicit checks avoid its conditional/subshell
+# pitfalls and give a named failure.
+# -----------------------------------------------------------------------------
+fail_apply() {
+  printf '\ncodeops-migrate: FAILED at step: %s\n' "$1" >&2
+  printf '  The migration did NOT complete and NO layout marker was written.\n' >&2
+  printf '  Inspect with "git status"; undo any partial moves with "git reset --hard",\n' >&2
+  printf '  fix the cause, then re-run.\n' >&2
+  exit 1
+}
+step() {
+  local desc="$1"; shift
+  "$@" || fail_apply "$desc"
+}
+
+step "mkdir codeops/features/$slug/plans" mkdir -p "codeops/features/$slug/plans"
+[[ -d plans/_archive ]] && step "mkdir codeops/_archive" mkdir -p codeops/_archive
+
+[[ -d requirements ]] && step "git mv requirements" git mv requirements "codeops/features/$slug/requirements"
+for d in plans/*/; do
+  name="$(basename "$d")"
+  [[ "$name" == "_archive" ]] && continue
+  step "git mv plans/$name" git mv "plans/$name" "codeops/features/$slug/plans/$name"
+done
+[[ -f plans/00-roadmap.md ]] && step "git mv plans/00-roadmap.md" git mv plans/00-roadmap.md "codeops/features/$slug/00-roadmap.md"
+if [[ -d plans/_archive ]]; then
+  for a in plans/_archive/*/; do
+    [[ -d "$a" ]] || continue
+    aname="$(basename "$a")"
+    step "git mv plans/_archive/$aname" git mv "plans/_archive/$aname" "codeops/_archive/$aname"
+  done
+  for af in plans/_archive/*; do
+    [[ -f "$af" ]] || continue
+    step "git mv $af" git mv "$af" "codeops/_archive/$(basename "$af")"
+  done
+fi
+# Remove the now-empty flat directories left behind by the moves.
+find plans requirements -type d -empty -delete 2>/dev/null || true
+
+# Marker — written LAST, and only after every move step succeeded, so neither an interrupted
+# nor a FAILED run can leave a false "already migrated" flag.
+# integrationBranch names where features integrate and derived files (portfolio roadmap, AGENTS.md)
+# regenerate — so parallel feature worktrees don't collide. Resolve the repo default: origin/HEAD,
+# else the current branch, else main. Consumers auto-detect the same default when the key is absent.
+integration_branch="$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##')"
+[[ -n "$integration_branch" ]] || integration_branch="$(git symbolic-ref --quiet --short HEAD 2>/dev/null)"
+[[ -n "$integration_branch" ]] || integration_branch="main"
+cat > codeops/codeops.json <<'JSON' || fail_apply "write codeops/codeops.json"
+{
+  "schema": 1,
+  "mode": "strict",
+  "artifacts": {"layout": "nested", "root": "codeops"},
+  "quality": {
+    "independentReview": true,
+    "minimumReviewers": 1,
+    "stopOnMajorFinding": true
+  },
+  "metrics": {"enabled": false}
+}
+JSON
+# Seeded portfolio roadmap — one row for the migrated feature. The roadmap skill refines the
+# stage/progress on the next /update_roadmap; this is a valid starting point.
+today="$(date '+%Y-%m-%d')"
+cat > codeops/00-roadmap.md <<PORTFOLIO || fail_apply "write codeops/00-roadmap.md"
+# Portfolio Roadmap: $(basename "$ROOT")
+
+> **Status**: Active
+> **Last Updated**: $today
+> **Features**: 0 / 1 done
+> **CodeOps Artifact Schema**: 1
+
+## Legend
+
+⬜ Backlog · 🔄 In progress · ✅ Done · ⛔ Blocked · ⏸️ Deferred · 📦 Archived
+
+## Features
+
+| Feature | Roadmap | Stage Summary | Progress | Status | Last Updated |
+|---------|---------|---------------|----------|--------|--------------|
+| $slug | [→](features/$slug/00-roadmap.md) | migrated from flat layout | — | 🔄 | $today |
+
+## Archived
+
+| Feature | Roadmap | Completed | Last Updated |
+|---------|---------|-----------|--------------|
+| — | — | — | — |
+PORTFOLIO
+
+# The presence marker is the commit point. Write it only after every required
+# artifact exists, so a failed or interrupted run cannot report completion.
+cat > codeops/.codeops.yml <<YML || fail_apply "write codeops/.codeops.yml"
+# CodeOps layout marker. Presence of this file opts the repo into the nested layout.
+# Sole writer: the setup_codeops skill (via codeops-migrate.sh). Schema: _shared/layout-convention.md
+codeopsLayout: nested
+layoutVersion: "3.0.0"
+integrationBranch: ${integration_branch}
+conventions:
+  rdIdScope: per-feature
+  taskIdPrefix: "T"
+  maintenanceFeature: _maintenance
+  archiveDir: codeops/_archive
+YML
+
+printf '\ncodeops-migrate: applied. Review with "git status" / "git diff --staged" and commit.\n'
+printf '  %d warning(s) above may need a manual follow-up (e.g. source-relative links).\n' "${#warnings[@]}"
+exit 0

package/scripts/codeops-roadmap-compact.sh

@@ -0,0 +1,232 @@
+#!/usr/bin/env bash
+#
+# codeops-roadmap-compact.sh — deterministic roadmap slimming engine.
+#
+# CodeOps Artifact Schema: 1
+#
+# The roadmap skill's `compact` action owns the JUDGMENT (rewriting a verbose table cell down to a
+# terse phrase); this script owns the MECHANICAL, testable, safety-critical half (the same
+# prose-vs-script division as codeops-roadmap-sync.sh / codeops-migrate.sh). For every roadmap in
+# the repo it:
+#   - removes the `## Notes` running-log section (heading-anchored: from the `## Notes` line through
+#     the line before the next `## ` heading, or EOF) — the one destructive op;
+#   - flags oversized Tracker/Features table cells to stdout as a worklist for the `compact` action.
+# It NEVER rewrites a table cell, never touches a header line or the Tracker/Features tables, and
+# never executes repo data. Because deleting the Notes log is only reversible through git, apply
+# refuses to run on a non-git or dirty tree (mirrors codeops-migrate.sh) so a clean, recoverable
+# commit always precedes any mutation.
+#
+# Usage:
+#   codeops-roadmap-compact.sh            # apply: strip Notes sections in place; print flagged cells
+#   codeops-roadmap-compact.sh --dry-run  # preview strips + flags; change nothing
+#   codeops-roadmap-compact.sh --check    # report only; exit 1 if any roadmap still carries a
+#                                         #   `## Notes` section or an oversized cell
+#   codeops-roadmap-compact.sh -h|--help  # this usage
+# Exit: 0 = success / clean / no-op; 1 = refusal (not a git repo, or dirty tree) OR drift found
+#       under --check; 2 = bad usage; 3 = python3 unavailable.
+
+set -uo pipefail
+
+MODE="apply"
+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
+}
+
+# -----------------------------------------------------------------------------
+# Git safety. Apply DELETES the Notes log, so it must run on a clean, recoverable tree (mirrors
+# codeops-migrate.sh:67-99). --check / --dry-run write nothing, so they may report on any tree.
+# All modes operate from the git root when there is one, so relative roadmap paths are stable.
+# -----------------------------------------------------------------------------
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
+if [[ "$MODE" == "apply" ]]; then
+  if [[ -z "$ROOT" ]]; then
+    printf 'ERROR: not inside a git repository — compact deletes the Notes log, which is only\n' >&2
+    printf '       recoverable via git. Run it inside the repository.\n' >&2
+    exit 1
+  fi
+  cd "$ROOT" || { printf 'ERROR: cannot enter repo root %s\n' "$ROOT" >&2; exit 1; }
+  if [[ -n "$(git status --porcelain)" ]]; then
+    printf 'ERROR: working tree is dirty — compact must run on a clean tree so the removed notes\n' >&2
+    printf '       stay recoverable via git. Commit or stash your changes first, then re-run.\n' >&2
+    exit 1
+  fi
+else
+  [[ -n "$ROOT" ]] && cd "$ROOT"
+fi
+
+# 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
+
+MODE="$MODE" LAYOUT="$layout" python3 - <<'PY'
+import glob, os, re, sys
+
+mode = os.environ["MODE"]       # apply | check | dry
+layout = os.environ["LAYOUT"]   # flat | nested
+
+# ---------------------------------------------------------------------------
+# Roadmap discovery (current repo only; every 00-roadmap.md incl. _archive/).
+# ---------------------------------------------------------------------------
+def discover():
+    paths = []
+    if layout == "flat":
+        if os.path.isfile("plans/00-roadmap.md"):
+            paths.append("plans/00-roadmap.md")
+        paths += sorted(glob.glob("plans/_archive/*/00-roadmap.md"))
+    else:
+        if os.path.isfile("codeops/00-roadmap.md"):
+            paths.append("codeops/00-roadmap.md")
+        paths += sorted(glob.glob("codeops/features/*/00-roadmap.md"))
+        paths += sorted(glob.glob("codeops/_archive/*/00-roadmap.md"))
+    return paths
+
+# ---------------------------------------------------------------------------
+# Notes-section removal (heading-anchored). Removes the block from a `## Notes` heading through the
+# line before the next `## ` heading (or EOF). Every other line — headers, `## Tracker`,
+# `## Features`, `## Archived` — is left byte-for-byte unchanged. When something was removed the
+# trailing blank run at EOF is collapsed to a single newline so the file stays a clean POSIX text
+# file. Returns (new_text, removed_bool, removed_block_text).
+# ---------------------------------------------------------------------------
+NOTES_HEADING = re.compile(r'^##[ \t]+Notes[ \t]*$')
+ANY_H2 = re.compile(r'^##[ \t]')
+
+def strip_notes(text):
+    lines = text.splitlines(keepends=True)
+    out, removed_block = [], []
+    i, n, removed = 0, len(lines), False
+    while i < n:
+        bare = lines[i].rstrip('\r\n')
+        if NOTES_HEADING.match(bare):
+            removed = True
+            removed_block.append(lines[i]); i += 1
+            while i < n and not ANY_H2.match(lines[i].rstrip('\r\n')):
+                removed_block.append(lines[i]); i += 1
+        else:
+            out.append(lines[i]); i += 1
+    result = "".join(out)
+    if removed:
+        result = result.rstrip('\n') + '\n'
+    return result, removed, "".join(removed_block)
+
+# ---------------------------------------------------------------------------
+# Fat-cell flagging (report only — the engine never rewrites a cell). Parses every pipe table
+# (a header row immediately followed by a `---` separator), then flags any DATA-row cell — skipping
+# the first (id/feature) column — whose trimmed content is oversized: > 200 chars, or an embedded
+# line break, or more than one sentence (>= 2 mid-cell `. ` / `; ` breaks). The column name comes
+# from the table's own header row, so the check is layout- and rename-agnostic.
+# ---------------------------------------------------------------------------
+SEP_CELL = re.compile(r'^:?-{1,}:?$')
+SENTENCE_BREAK = re.compile(r'[.;] ')
+
+def split_cells(line):
+    return [c.strip() for c in line.strip().strip('|').split('|')]
+
+def is_separator(line):
+    if not line.lstrip().startswith('|'):
+        return False
+    cells = split_cells(line)
+    return bool(cells) and all(SEP_CELL.match(c) for c in cells if c)
+
+def cell_is_fat(cell):
+    if len(cell) > 200:
+        return True
+    if '<br' in cell.lower() or '\n' in cell:
+        return True
+    if len(SENTENCE_BREAK.findall(cell)) >= 2:
+        return True
+    return False
+
+def flag_cells(text, path):
+    flags = []
+    lines = text.splitlines()
+    i, n = 0, len(lines)
+    while i < n:
+        line = lines[i]
+        if line.lstrip().startswith('|') and i + 1 < n and is_separator(lines[i + 1]):
+            header = split_cells(line)
+            j = i + 2
+            while j < n and lines[j].lstrip().startswith('|'):
+                if not is_separator(lines[j]):
+                    cells = split_cells(lines[j])
+                    row_id = cells[0] if cells else ''
+                    for c in range(1, len(cells)):
+                        if cell_is_fat(cells[c]):
+                            col = header[c] if c < len(header) else f'col{c}'
+                            flags.append(f"FLAG {path}:{row_id}:{col} ({len(cells[c])} chars)")
+                j += 1
+            i = j
+        else:
+            i += 1
+    return flags
+
+# ---------------------------------------------------------------------------
+# Drive the roadmaps per mode.
+# ---------------------------------------------------------------------------
+roadmaps = discover()
+stripped = 0
+flag_count = 0
+drift = 0
+
+for path in roadmaps:
+    try:
+        text = open(path, encoding='utf-8').read()
+    except OSError as e:
+        print(f"WARN: cannot read {path}: {e}", file=sys.stderr)
+        continue
+    new_text, removed, block = strip_notes(text)
+    flags = flag_cells(new_text, path)
+
+    if mode == 'apply':
+        if removed:
+            try:
+                open(path, 'w', encoding='utf-8').write(new_text)
+            except OSError as e:
+                print(f"ERROR: failed to write {path}: {e}", file=sys.stderr)
+                sys.exit(1)
+            print(f"STRIP {path}: ## Notes ({len(block.encode('utf-8'))} bytes)")
+            stripped += 1
+        for f in flags:
+            print(f)
+            flag_count += 1
+    elif mode == 'dry':
+        if removed:
+            print(f"WOULD-STRIP {path}: ## Notes ({len(block.encode('utf-8'))} bytes)")
+        for f in flags:
+            print(f)
+    else:  # check
+        if removed:
+            print(f"NOTES {path}: ## Notes section present")
+            drift += 1
+        for f in flags:
+            print(f)
+            drift += 1
+
+if mode == 'apply':
+    if stripped:
+        tail = f"; {flag_count} cell(s) flagged for trimming (see FLAG lines above)." if flag_count else "."
+        print(f"compact: stripped the Notes log from {stripped} roadmap(s){tail}")
+    else:
+        print("compact: all roadmaps already lean — nothing to do.")
+    sys.exit(0)
+elif mode == 'dry':
+    print("(dry-run: nothing written)")
+    sys.exit(0)
+else:  # check
+    if drift:
+        print(f"compact: {drift} issue(s) found — run the roadmap compact action to slim these.")
+        sys.exit(1)
+    print("compact: all roadmaps already lean.")
+    sys.exit(0)
+PY