@oneie/claude 0.4.0 → 0.6.0

package/scripts/do-rank.py

@@ -0,0 +1,1160 @@
+#!/usr/bin/env python3
+"""do-rank.py — cross-plan priority ranker for /do.
+
+Read-only. Walks every text/*-todo.md, scores it on five traceable signals,
+and emits a dependency-aware queue: READY (ranked) · BLOCKED (with blocker) · DONE.
+
+No agents, no tokens — pure parse + graph. The input to do-fleet.sh.
+
+Signals:  score = 2*Strategic + 2*Leverage + 1*round(3*Proximity) + 2*Priority + 2*round(Momentum)
+  Strategic  — north-star keyword hits in tags+title (capped 6; agent economy is the vision)
+  Leverage   — how many OPEN plans TRANSITIVELY depend on this slug (keystones rank up)
+  Proximity  — checkbox completion ratio (SOFT — denominators include AC bullets)
+  Priority   — explicit `priority:` frontmatter, human override (0-3)
+  Momentum   — recent high-rubric closes (path strength) — warm proven work pulls the fleet
+  Readiness  — gate: all depends_on slugs must be DONE, else BLOCKED
+
+Fleet disjointness keys on SUBTREE dirs (containing dir of each deliverable file);
+do-fleet.sh reads them via `--dirs`. `--lint` flags phantom/unscoped deliverables.
+
+DONE = 0 open checkboxes OR a dated close in text/learnings.md.
+
+Usage:
+  do-rank.py                 human table
+  do-rank.py --json          machine queue for the fleet
+  do-rank.py --top N         the N highest READY slugs, one per line
+"""
+import json
+import re
+import signal
+import subprocess
+import sys
+from pathlib import Path
+
+# Exit cleanly when piped into head/etc. (closes our stdout early).
+try:
+    signal.signal(signal.SIGPIPE, signal.SIG_DFL)
+except (AttributeError, ValueError):
+    pass
+
+# Repo root = two levels up from .claude/scripts/
+ROOT = Path(__file__).resolve().parents[2]
+TEXT = ROOT / "text"
+LEARNINGS = TEXT / "learnings.md"
+
+# The local path tier — the on-disk mirror of `path.strength` for the task layer
+# (the same role tasks-seed.json plays for the on-chain tier; three-layer data model:
+# TypeDB truth → KV snapshot → local). `do-rank.py --mark <slug>` writes it; the
+# momentum loader reads it. This is the seam do-rank.py always named: when a slug has
+# live path strength here, it OVERRIDES the learnings.md count — so a mark() visibly
+# moves the next pick. Absent slug → fall back to learnings.md (no regression).
+# The loop closes here: close → mark → strength↑ → next rank picks it. See text/loop-plan.md.
+TASK_PATHS = TEXT / "task-paths.json"
+
+# North-star keywords (from vision.md / the economic-peer thesis). Weighted by pull.
+NORTH_STAR = {
+    "agent": 3, "economic": 3, "billing": 3, "payment": 3, "pay": 3, "x402": 3,
+    "substrate": 2, "auth": 2, "roles": 2, "authority": 2, "typedb": 2, "schema": 2,
+    "workflow": 2, "composition": 2, "inbox": 2, "channels": 2, "skill": 2,
+    "lifecycle": 1, "memory": 1, "analytics": 1, "tracking": 1,
+}
+
+EXCLUDE = {"template", "todo"}  # template-todo.md and this index's own todo.md
+
+# Real top-level dirs of the monorepo. The fleet's disjointness check keys on
+# the first two path segments of each `deliverables:` entry. Filtering to these
+# roots kills prose false-positives ("mark/warn", "SUI/ETH", "A/B") that the bare
+# dir1/dir2 regex otherwise turns into phantom file-locks. Keep in sync with
+# do-fleet.sh deliverable_dirs() — this is the canonical list.
+REPO_DIRS = {
+    "one.ie", "api", "packages", "channels", "schema", "sync", "backup",
+    "apps", "text", ".claude", "migrations", "oo", "pay", "scripts",
+}
+
+_DIR_TOKEN = re.compile(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_./-]+")
+
+
+def deliverable_dirs(text):
+    """Set of SUBTREE dirs a plan ships into, from its `deliverables:` block — the
+    containing dir of each declared file (the filename dropped), e.g.
+    `one.ie/web/src/lib/billing/expiry.ts` → `one.ie/web/src/lib/billing`.
+
+    This is the fleet's disjointness key: two plans are safe to run in parallel iff
+    their subtree sets don't overlap. Subtree (not `top/second`) is the granularity
+    that gives real parallelism — under `top/second` every one.ie/web plan collapsed
+    to a single token and serialized; under full-file two plans editing different
+    files in a tightly-coupled family (puck components) looked disjoint and clobbered.
+    The containing dir is the unit of coupling: same dir ⇒ treat as one lock.
+
+    do-fleet.sh consumes this via `do-rank.py --dirs <slug>` — ONE extractor, no
+    second markdown parser to drift. Empty set ⇒ the plan declares no parseable
+    deliverables (a fleet hazard, see waves view + `--lint`).
+    """
+    dirs = set()
+    for tok in deliverable_paths(text):
+        parts = tok.split("/")
+        # Drop the leaf if it names a file (has an extension); else the path IS a dir.
+        sub = "/".join(parts[:-1]) if "." in parts[-1] else tok
+        if sub:
+            dirs.add(sub)
+    return dirs
+
+
+def transitive_dependents(slug, direct, seen=None):
+    """All slugs that TRANSITIVELY depend on `slug`, walking the depends_on graph.
+    `direct` maps slug -> set of slugs that directly depend on it. The keystone
+    metric: namespace ← tasks-mine ← tasks-push ← tasks-bridge ⇒ 3 dependents, so
+    unblocking it frees the whole chain, not just the one child."""
+    if seen is None:
+        seen = set()
+    for child in direct.get(slug, ()):
+        if child not in seen:
+            seen.add(child)
+            transitive_dependents(child, direct, seen)
+    return seen
+
+
+def deliverable_paths(text):
+    """Every repo-root path token in the `deliverables:` block (full path, not the
+    top/second dir). The granularity-independent source — deliverable_dirs() and the
+    linter both derive from it. Path column only (before the em-dash), REPO_DIRS-rooted."""
+    m = re.search(r"^deliverables:\s*$(.*?)(?=^[a-z_]+:|^---\s*$|\Z)",
+                  text, re.MULTILINE | re.DOTALL)
+    if not m:
+        return []
+    out = []
+    for line in m.group(1).splitlines():
+        path_col = line.split("—", 1)[0]
+        for tok in _DIR_TOKEN.findall(path_col):
+            if tok.split("/")[0] in REPO_DIRS:
+                out.append(tok)
+    return out
+
+
+def lint_paths(text):
+    """Mechanical hygiene check on a plan's deliverable paths. Returns a list of
+    (token, reason) for paths that don't resolve on disk — the phantom-dir failure
+    (e.g. `api/invites` written for `one.ie/web/src/pages/api/invites/create.ts`)
+    that silently turns a plan into a fleet false-parallel.
+
+    A token is VALID when it (a) exists on disk as a file or dir, or (b) names a
+    NEW file (has an extension) up to ONE new directory level under a real parent —
+    i.e. its grandparent dir exists (a planned file, optionally in a new subdir of a
+    real package, like a new api/ask/gate/ route). Otherwise it's a phantom: a
+    URL-style route (`api/composio/connections`) or a wrong-rooted path
+    (`apps/pay/backend/...` when the package is `pay/backend/...`) — which silently
+    turns the plan into a fleet false-parallel, claiming a dir it never ships into."""
+    bad = []
+    for tok in deliverable_paths(text):
+        p = ROOT / tok
+        if p.exists():
+            continue
+        if "." in p.name and p.parent.parent.exists():  # planned file, real grandparent
+            continue
+        bad.append((tok, "no such path; not a planned file under a real dir — phantom/wrong-rooted"))
+    return bad
+
+
+# ── Tasks layer ────────────────────────────────────────────────────────────
+# Every todo is a task `thing` tagged from the world ontology + weighted. The
+# department tag is canonical (FN_TAGS in one.ie/web/src/lib/in/spaces.ts); the
+# build/infra lens is `builds` (tag `do-event`) — "engineering" is not yet a
+# first-class fn:* department (a one-line FN_TAGS add, deferred — see tasks-plan.md).
+# Design: text/tasks-plan.md.
+DEPT_TAG = {
+    "marketing": "marketing", "sales": "sales", "service": "service",
+    "education": "education", "builds": "builds",
+}
+# Keyword → department vote. Domain-specific depts win ties over the catch-all
+# `builds` (most substrate work is build work, so builds must not swallow everything).
+DEPT_KW = {
+    "marketing": ["marketing", "funnel", "campaign", "seo", "ads", "content",
+                  "newsletter", "social", "landing", "copy", "brand", "tracking",
+                  "analytics", "visitor", "lead", "showcase", "playbook"],
+    "sales": ["sales", "billing", "payment", "pay", "checkout", "stripe", "pricing",
+              "revenue", "invoice", "deal", "offer", "sell", "x402", "escrow", "crm",
+              "people", "contact", "invitation", "invite", "client"],
+    "service": ["service", "support", "chat", "inbox", "ticket", "booking", "help",
+                "channels", "conversation", "memory", "message", "sanitize"],
+    "education": ["education", "learning", "course", "tutorial", "skill", "certify",
+                  "competence", "docs", "rag"],
+    "builds": ["schema", "sdk", "api", "infra", "gateway", "auth", "roles", "workflow",
+               "migration", "typedb", "mcp", "cli", "system", "ui", "frontend", "react",
+               "astro", "deploy", "sync", "backup", "performance", "realtime", "do",
+               "agent", "composio", "oo", "rubrics", "features", "boq", "signal"],
+}
+_TIE_ORDER = ["sales", "marketing", "service", "education", "builds"]
+
+
+def classify_dept(slug, fm):
+    """Vote a todo into one canonical department from its slug + title + tags."""
+    hay = " ".join([slug, fm.get("title", "")] + fm.get("tags", [])).lower()
+    hay = re.sub(r"[^a-z0-9]+", " ", hay)
+    toks = set(hay.split())
+    scores = {d: sum(1 for kw in kws if kw in toks) for d, kws in DEPT_KW.items()}
+    best = max(scores.values())
+    if best == 0:
+        return "builds"  # no signal → it's substrate/build work
+    winners = [d for d in _TIE_ORDER if scores[d] == best]
+    return winners[0]
+
+
+def task_weight(p):
+    """1–100. New task = 50; proven work (momentum) + human priority earn more.
+    Derived every run from learnings.md — never frozen into a frontmatter."""
+    w = 50 + 10 * p["momentum"] + 3 * p["priority"]
+    return max(1, min(100, round(w)))
+
+
+def _task_tags(p):
+    """A task's full tag set: its department tag + freeform topic tags."""
+    return [DEPT_TAG[p["dept"]]] + [t for t in p["tags"] if t]
+
+
+def tag_combinations(active):
+    """Seed a weight for every co-occurring tag PAIR across active tasks.
+    new pair = 50; pairs that recur, and pairs on proven (momentum>0) work, earn
+    more. This weight is what a later cycle lets you STAKE on (see tasks-plan.md)."""
+    from itertools import combinations
+    count, proven = {}, {}
+    for p in active:
+        proven_hit = 1 if p["momentum"] > 0 else 0
+        for a, b in combinations(sorted(set(_task_tags(p))), 2):
+            count[(a, b)] = count.get((a, b), 0) + 1
+            proven[(a, b)] = proven.get((a, b), 0) + proven_hit
+    combos = []
+    for pair, c in count.items():
+        if c < 2:  # a pair seen once carries no signal yet — skip the long tail
+            continue
+        w = max(1, min(100, 50 + 5 * proven[pair] + 2 * (c - 1)))
+        combos.append({"tags": list(pair), "weight": w,
+                       "seen": c, "proven": proven[pair]})
+    combos.sort(key=lambda x: (-x["weight"], -x["seen"]))
+    return combos
+
+
+def tasks_view(active):
+    """Human-readable, department-grouped, weighted task list — the hero artifact,
+    appended to todo.md. active = ready + blocked (open work; done is excluded)."""
+    out = []
+    LABEL = {"builds": "builds (engineering)", "marketing": "marketing",
+             "sales": "sales", "service": "service", "education": "education"}
+    out.append("  TASKS — every todo is a tagged, weighted signal (new=50 · proven earns more)")
+    out.append("")
+    for dept in ["builds", "marketing", "sales", "service", "education"]:
+        rows = sorted([p for p in active if p["dept"] == dept],
+                      key=lambda x: -x["weight"])
+        if not rows:
+            continue
+        out.append(f"  ┌─ {DEPT_TAG[dept]:<14} {LABEL[dept]}")
+        for p in rows:
+            topics = " ".join(t for t in p["tags"][:4])
+            sub = f"·{len(p['cycles'])} sub" if p["cycles"] else ""
+            blk = " (blocked)" if p.get("waiting_on") else ""
+            out.append(f"  │  {p['weight']:>3}  {p['slug']:<22} {topics}{sub}{blk}")
+        out.append("  └─")
+    combos = tag_combinations(active)
+    if combos:
+        out.append("")
+        out.append("  TAG COMBINATIONS — seeded weights (the stakeable quantity → path-context.context-strength)")
+        for c in combos[:15]:
+            mark = " ✓proven" if c["proven"] else ""
+            out.append(f"    {c['weight']:>3}  {c['tags'][0]} + {c['tags'][1]:<16} (×{c['seen']}{mark})")
+    out.append("")
+    out.append("  → signal(receiver:\"tasks:announce\", payload:task, tags:task.tags); agents follow fn:*+topics, mark() moves weight")
+    out.append("  seed: do-rank.py --tasks-json > text/tasks-seed.json · design: text/tasks-plan.md")
+    return out
+
+
+def tasks_seed(active):
+    """The same data shaped to the substrate, so testnet seeding is a LOAD not a
+    reshape: task→thing+tag, combo-weight→path-context.context-strength, payload→signal."""
+    return {
+        "version": "testnet-seed-1",
+        "weightModel": {
+            "new": 50, "min": 1, "max": 100,
+            "formula": "clamp(50 + 10*momentum + 3*priority, 1, 100)",
+            "basis": "momentum = recency-weighted rubric-scaled closes from learnings.md",
+        },
+        "departments": DEPT_TAG,
+        "tasks": [
+            {
+                "tid": f"task:{p['slug']}",
+                "thingType": "task",
+                "name": p["title"] or p["slug"],
+                "tag": _task_tags(p),
+                "taskStatus": "blocked" if p.get("waiting_on") else "open",
+                "taskPriority": round(p["priority"] / 3, 2),
+                "weight": p["weight"],
+                "dept": p["dept"],
+                "subtasks": [
+                    {"tid": f"task:{p['slug']}:C{c}", "thingType": "task",
+                     "tag": _task_tags(p), "taskStatus": "open", "weight": 50}
+                    for c in p["cycles"]
+                ],
+                "waitingOn": p.get("waiting_on", []),
+            }
+            for p in active
+        ],
+        "tagCombinations": [
+            {"tags": c["tags"], "contextStrength": c["weight"],
+             "seen": c["seen"], "proven": c["proven"]}
+            for c in tag_combinations(active)
+        ],
+        "signal": {
+            "shape": "signal(sender, receiver, payload, tags)",
+            "receiver": "tasks:announce",
+            "routing": "tag-intersection fan-out (one.ie/web/src/lib/world-receivers.ts) + subscriptions:register (declared, not yet persisted)",
+            "note": "no tasks:* receiver wired yet — C3 in tasks-plan.md. weights here are what a stake would later move.",
+        },
+    }
+
+
+def pack_waves(ready):
+    """Greedily pack the score-sorted ready queue into file-disjoint fleet waves.
+
+    Each wave is a set of plans whose deliverable dirs don't overlap — the fleet
+    can run a whole wave in parallel without one plan clobbering another's tree.
+    A plan joins the first wave it doesn't collide with (preserves score order
+    within a wave). Plans with NO declared deliverables are NOT packed — the fleet
+    would treat them as conflict-free and parallelize them blindly, so they're
+    returned separately as a hazard list to be scoped before fleeting.
+    """
+    waves, unscoped = [], []
+    for p in ready:
+        dirs = p.get("_dirs", set())
+        if not dirs:
+            unscoped.append(p["slug"])
+            continue
+        for w in waves:
+            if not (w["dirs"] & dirs):
+                w["slugs"].append(p["slug"])
+                w["dirs"] |= dirs
+                break
+        else:
+            waves.append({"slugs": [p["slug"]], "dirs": set(dirs)})
+    return waves, unscoped
+
+
+def parse_frontmatter(text):
+    """Minimal YAML frontmatter parse — no pyyaml dependency."""
+    m = re.match(r"^---\n(.*?)\n---", text, re.DOTALL)
+    fm = {}
+    if not m:
+        return fm
+    body = m.group(1)
+    for key in ("title", "tier", "mode", "priority"):
+        km = re.search(rf"^{key}:\s*(.+)$", body, re.MULTILINE)
+        if km:
+            val = km.group(1)
+            val = re.sub(r"\s+#.*$", "", val)  # strip trailing YAML inline comment
+            fm[key] = val.strip().strip('"').strip("'")
+    # list fields: tags / depends_on — inline [a, b] form
+    for key in ("tags", "depends_on"):
+        km = re.search(rf"^{key}:\s*\[(.*?)\]", body, re.MULTILINE)
+        if km:
+            items = [x.strip().strip('"').strip("'") for x in km.group(1).split(",")]
+            fm[key] = [x for x in items if x]
+        else:
+            fm[key] = []
+    return fm
+
+
+def is_gated(text):
+    """A todo with a `build_gate:` frontmatter field is human-approval-required and is
+    EXCLUDED from ready/--top/fleet — so a blanket `do-fleet.sh --top N --go` (or do-auto
+    --next-cycle) can NEVER auto-launch a gated cycle (e.g. the real-money x402-settlement,
+    build_gate'd in ef92bd64). Detection is the presence of a non-empty build_gate line
+    INSIDE the `---` frontmatter (a build_gate mention in the body never gates). Scoped to
+    frontmatter because `parse_frontmatter` only parses an allowlist (title/tier/mode/
+    priority/tags/depends_on) — build_gate is not in it, so fm.get('build_gate') is always
+    None; we read the raw frontmatter instead. Excluded from ready, NOT deleted: a human who
+    approves still runs it by explicit slug (`/do <slug>`), which never reads --top."""
+    m = re.match(r"^---\n(.*?)\n---", text, re.DOTALL)
+    body = m.group(1) if m else ""
+    return bool(re.search(r"(?m)^build_gate:\s*\S", body))
+
+
+def checkbox_state(text):
+    done = len(re.findall(r"^\s*- \[[xX]\]", text, re.MULTILINE))
+    openb = len(re.findall(r"^\s*- \[ \]", text, re.MULTILINE))
+    return done, openb
+
+
+# ── Toxic classifier — the `guard` for the task queue ────────────────────────
+# Mirrors one.ie/web/src/lib/ingress.ts classify(): a cold+stale todo carrying a noise
+# signal is QUARANTINED (excluded from the live queue), not merely down-weighted —
+# score-0 plans (features/crx/people) can't be faded below path_momentum's 0 floor, so
+# exclusion is the ONLY way to remove them. NECESSARY gate (both must hold): momentum==0
+# (no close in the learnings window — cold) AND stale (untouched past STALE_DAYS by the
+# repo's own HEAD clock — engine.md Rule 2's external-deadline exception, used ONLY behind
+# the structural momentum gate). A warm plan (momentum>0, e.g. analytics) or a fresh one
+# (committed today, e.g. speed-channels) can NEVER be toxic, by construction. A large
+# open-box count is never sufficient on its own — that protects the most valuable plans,
+# which are the warm ones with the most open work. Both protections are locked by selftest.
+STALE_DAYS = 7
+MEGA_OPEN = 80
+MEGA_PROXIMITY = 0.15
+
+
+def is_toxic(momentum, done, openb, proximity, stale, has_deliverables=False):
+    """Reasons a todo is toxic (empty list ⇒ not toxic). Pure — unit-testable without git.
+    Necessary: cold (momentum==0) AND stale. Then any sufficient signal fires.
+    `empty` requires NO deliverables too: a plan that declares a `deliverables:` block is a
+    real build plan, not a stub — even if its checkboxes are in a form the ranker can't parse
+    (e.g. foundation-ui's backtick `[ ]`). Without this guard the hourly loop would fade a
+    real in-flight plan once it crossed STALE_DAYS — a silent, unattended false-positive."""
+    if momentum > 0 or not stale:
+        return []
+    reasons = []
+    if done + openb == 0 and not has_deliverables:
+        reasons.append("empty")           # no checkbox AND no deliverables — a doc/stub, not a plan
+    if done == 0 and openb > 0:
+        reasons.append("zero-progress")   # has work, never ticked one box
+    if openb > MEGA_OPEN and proximity < MEGA_PROXIMITY:
+        reasons.append("mega-stale")      # hundreds of boxes, <15% done — never converges
+    return reasons
+
+
+def repo_now():
+    """The repo's 'now' = HEAD commit unix time. Like learnings.md's ref=max(date), 'now'
+    is the newest commit, not the wall clock (engine.md Rule 2). None on git failure."""
+    try:
+        out = subprocess.run(["git", "-C", str(ROOT), "log", "-1", "--format=%ct"],
+                             capture_output=True, text=True, timeout=5)
+        ts = out.stdout.strip()
+        return int(ts) if ts else None
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return None
+
+
+def days_since_commit(path, now_ct):
+    """Days since `path`'s last commit, measured against repo HEAD time (now_ct).
+    Untracked / never-committed → None ⇒ NOT stale: a brand-new uncommitted file is the
+    opposite of abandoned (staleness measures 'committed then left to rot', not 'never
+    committed'). now_ct None / git failure → None too (no regression). Lazy: call only
+    where staleness actually gates a decision (momentum==0 todos · frontier plans)."""
+    if now_ct is None:
+        return None
+    try:
+        out = subprocess.run(["git", "-C", str(ROOT), "log", "-1", "--format=%ct", "--", str(path)],
+                             capture_output=True, text=True, timeout=5)
+        ts = out.stdout.strip()
+        if not ts:
+            return None
+        return (now_ct - int(ts)) // 86400
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return None
+
+
+def toxic_reasons(p, now_ct):
+    """Toxic reasons for a built plan dict. Lazy git staleness — only when momentum==0,
+    so the live queue's ~10 cold candidates trigger git, not all 196 todos."""
+    if p["momentum"] > 0:
+        return []
+    days = days_since_commit(TEXT / f"{p['slug']}-todo.md", now_ct)
+    stale = days is not None and days >= STALE_DAYS
+    openb = p["total_boxes"] - p["done_boxes"]
+    has_deliverables = bool(p.get("_dirs"))
+    return is_toxic(p["momentum"], p["done_boxes"], openb, p["proximity"], stale, has_deliverables)
+
+
+# ── fade — the decay verb for the task layer (C2) ────────────────────────────
+def _fade_one(strength, resistance, rate):
+    """One asymmetric decay step. Matches world.fade (engine.md): RESISTANCE DECAYS 2×
+    FASTER than strength — earned weight (good trails) persists, penalties (warnings) are
+    forgiven quickly so a warned plan can recover. Pure — selftest checks this without IO."""
+    r = max(0.0, min(1.0, rate))
+    return round(strength * (1 - r), 4), round(max(0.0, resistance * (1 - 2 * r)), 4)
+
+
+def fade_paths(rate=0.1):
+    """The `fade` verb for the task layer — the genuinely-hourly action. Decays LIVE path
+    weight: `strength` (from --mark / agent picks) cools so an old live mark drifts down
+    unless renewed; `resistance` heals 2× faster (forgiveness). `closed` is NOT touched —
+    it's reconciled from learnings.md by --sync-closes every render and already fades via
+    momentum_score's 30-day recency window, so fading it here would just be overwritten.
+    Returns the count of entries whose weight actually moved."""
+    paths = load_task_paths()
+    touched = 0
+    for e in paths.values():
+        s0, r0 = float(e.get("strength", 0)), float(e.get("resistance", 0))
+        s1, r1 = _fade_one(s0, r0, rate)
+        if s1 != s0 or r1 != r0:
+            e["strength"], e["resistance"] = s1, r1
+            touched += 1
+    TASK_PATHS.write_text(json.dumps(paths, indent=2, sort_keys=True) + "\n")
+    return touched
+
+
+# ── frontier — what's next past every armed todo (C4) ────────────────────────
+def frontier(now_ct, log):
+    """Designed-but-unarmed plans: `*-plan.md` slugs with NO `*-todo.md`. The edge past the
+    live queue — 'what's next after every todo is done or faded'. Two kinds are counted but
+    hidden, leaving only the genuine edge: (1) CLOSED — a plan whose close is recorded in
+    learnings.md (reuses plan_closed, the same close-rule the todo walk trusts — a documented-
+    shipped plan is built work, not a next move); (2) STALE — untouched ≥STALE_DAYS (the 2026
+    bulk-import backlog, import-noise). The rest rank by strategic pull (north-star keyword
+    weight), freshest first. Returns (fresh_rows[(strat, days, slug, title)], stale_count,
+    closed_count). The substrate's frontiers_global (TypeDB hypotheses) is the beyond."""
+    todo_slugs = {f.name[: -len("-todo.md")] for f in TEXT.glob("*-todo.md")}
+    fresh, stale, closed = [], 0, 0
+    for f in sorted(TEXT.glob("*-plan.md")):
+        slug = f.name[: -len("-plan.md")]
+        if slug in EXCLUDE or slug in todo_slugs:
+            continue
+        if plan_closed(slug, log):        # close recorded ⇒ shipped, not an edge (same rule as the todo walk)
+            closed += 1
+            continue
+        days = days_since_commit(f, now_ct)
+        if days is not None and days >= STALE_DAYS:
+            stale += 1
+            continue
+        fm = parse_frontmatter(f.read_text(errors="ignore"))
+        fresh.append((strategic_score(slug, fm), days if days is not None else 0,
+                      slug, fm.get("title", "")[:48]))
+    fresh.sort(key=lambda x: (-x[0], x[1], x[2]))
+    return fresh, stale, closed
+
+
+def _slug_matcher(slug):
+    r"""Match the slug as a WHOLE token. \b treats '-' as a boundary, so \binbox\b
+    wrongly matches 'inbox-simple' — cross-contaminating slug families (inbox*,
+    roles*, chat*) in both momentum and done-detection, silently dropping real
+    work. Forbid an adjacent word char OR hyphen on either side."""
+    return re.compile(rf"(?<![\w-]){re.escape(slug)}(?![\w-])")
+
+
+# A learnings line that records a PLAN-level close (not just a cycle). Covers the
+# real formats: "· <slug> PLAN · CLOSE", "· <slug> · plan · …", "all N cycles
+# shipped/closed", "kill-switch … GREEN/exits 0". Matched in the line's subject zone.
+_CLOSE_MARKER = re.compile(
+    r"\bPLAN\b.*\bCLOSE\b"
+    r"|\bplan\b.*\bclose\b"
+    r"|all \d+ cycles (?:shipped|closed)"
+    r"|kill-switch.*(?:GREEN|exits 0|green)",
+    re.IGNORECASE,
+)
+
+
+def plan_closed(slug, log):
+    """True if learnings.md records a PLAN-level close for this slug.
+
+    Per-slug + close-marker, so it's robust to the line format that the old
+    regex choked on (e.g. 'visitor-to-people PLAN · CLOSE'). Subject-zone match
+    avoids common-word false positives, same as momentum.
+    """
+    pat = _slug_matcher(slug)
+    for _d, _r, ln in log:
+        segs = ln.split("·")
+        subject = " ".join(segs[1:3]) if len(segs) > 1 else ln
+        if pat.search(subject) and _CLOSE_MARKER.search(ln):
+            return True
+    return False
+
+
+def strategic_score(slug, fm):
+    haystack = " ".join([slug, fm.get("title", "")] + fm.get("tags", [])).lower()
+    return sum(w for kw, w in NORTH_STAR.items() if kw in haystack)
+
+
+def load_learnings_log():
+    """Every dated cycle line: (date, rubric|None, line). The loop's own output.
+
+    MIGRATION TARGET: today this reads learnings.md (the file the loop appends to).
+    The end-state reads path.strength / rubric-* attributes from TypeDB — the
+    substrate the verbs already write. momentum() is the seam: swap this loader,
+    the scoring stays. (text/orchestrator-plan.md · the Sense→Close seam.)
+    """
+    from datetime import date
+    log = []
+    if not LEARNINGS.exists():
+        return log, None
+    ref = None
+    for ln in LEARNINGS.read_text(errors="ignore").splitlines():
+        dm = re.match(r"-\s*(\d{4})-(\d{2})-(\d{2})", ln)
+        if not dm:
+            continue
+        try:
+            d = date(int(dm.group(1)), int(dm.group(2)), int(dm.group(3)))
+        except ValueError:
+            continue
+        rm = re.search(r"rubric[=≈~]\s*(\d?\.\d+)", ln)
+        rub = float(rm.group(1)) if rm else None
+        log.append((d, rub, ln))
+        ref = d if ref is None or d > ref else ref
+    # newest entry = "now" → recency is relative + deterministic (no wall clock)
+    ref = max((d for d, _, _ in log), default=None)
+    return log, ref
+
+
+def load_task_paths():
+    """The local path-strength store: { 'task:<slug>': {strength, resistance, traversals} }.
+    Mirror of the substrate `path` for the task layer. Missing/corrupt → empty (no regression)."""
+    try:
+        return json.loads(TASK_PATHS.read_text())
+    except (FileNotFoundError, ValueError):
+        return {}
+
+
+def path_momentum(slug, paths):
+    """Momentum from path strength (the closed-loop source), on the same 0–3 scale as
+    learnings momentum so scoring is unchanged. Strength has two writers, both summed:
+      • `closed`  — reconciled from learnings.md closes by --sync-closes (idempotent)
+      • `strength`/`resistance` — LIVE marks (agent picks, manual --mark)
+    net = closed + strength − resistance. Returns None when this slug has no path yet →
+    caller falls back to learnings.md (bootstrap for never-closed, never-marked work)."""
+    e = paths.get(f"task:{slug}")
+    if not e:
+        return None
+    net = max(0.0, float(e.get("closed", 0)) + float(e.get("strength", 0)) - float(e.get("resistance", 0)))
+    return round(min(3.0, net / 2.0), 2)
+
+
+def sync_closes(log, ref):
+    """Reconcile the path store's `closed` field from learnings.md closes — the close
+    SIGNAL feeding path strength, idempotent (recompute, never increment, so the hook
+    can fire it on every learnings edit without double-counting). Live `strength`/
+    `resistance` from --mark are preserved untouched. learnings momentum is in 0–3
+    units; ×2 puts it in strength units (so path_momentum returns the same number for a
+    closed-but-unmarked slug — no regression — and live marks stack on top)."""
+    paths = load_task_paths()
+    touched = 0
+    for f in sorted(TEXT.glob("*-todo.md")):
+        slug = f.name[: -len("-todo.md")]
+        if slug in EXCLUDE:
+            continue
+        closed = round(momentum_score(slug, log, ref) * 2.0, 2)
+        key = f"task:{slug}"
+        if closed <= 0 and key not in paths:
+            continue
+        e = paths.get(key) or {"strength": 0.0, "resistance": 0.0, "traversals": 0}
+        if e.get("closed") != closed:
+            e["closed"] = closed
+            touched += 1
+        paths[key] = e
+    TASK_PATHS.write_text(json.dumps(paths, indent=2, sort_keys=True) + "\n")
+    return touched
+
+
+def mark_task(slug, outcome, amount):
+    """The `mark`/`warn` verb for the task layer — closes the loop by moving path strength.
+    success → strength += amount ; failure → resistance += amount. traversals always ++.
+    Writes the local path tier; the next `--tasks`/queue run reads it. Returns the entry."""
+    paths = load_task_paths()
+    key = f"task:{slug}"
+    e = paths.get(key) or {"strength": 0.0, "resistance": 0.0, "traversals": 0, "closed": 0.0}
+    if outcome == "failure":
+        e["resistance"] = round(float(e.get("resistance", 0)) + amount, 3)
+    else:
+        e["strength"] = round(float(e.get("strength", 0)) + amount, 3)
+    e["traversals"] = int(e.get("traversals", 0)) + 1
+    paths[key] = e
+    TASK_PATHS.write_text(json.dumps(paths, indent=2, sort_keys=True) + "\n")
+    return e
+
+
+def momentum_score(slug, log, ref):
+    """How warm + proven this plan is, from the loop's own closes.
+
+    Recency-weighted count of cycle lines mentioning the slug, scaled by their
+    rubric. Recent high-rubric closes ⇒ warm, proven, cheap to continue ⇒ pull
+    the fleet toward finishing it rather than starting cold. Capped at 3 to sit
+    on the same scale as the other signals. Zero if the plan has no closes.
+    """
+    if not log or ref is None:
+        return 0.0
+    pat = _slug_matcher(slug)
+    score = 0.0
+    for d, rub, ln in log:
+        # Match only the SUBJECT zone (the "DATE · slug · phase ·" head), not the
+        # prose tail — else common-word slugs ("clean", "people") false-match
+        # adjectives like "clean pattern" and inflate momentum. learnings.md puts
+        # the slug right after the date, before the 2nd separator.
+        segs = ln.split("·")
+        subject = " ".join(segs[1:3]) if len(segs) > 1 else ln
+        if not pat.search(subject):
+            continue
+        days = (ref - d).days
+        if days >= 30:            # older than the window contributes nothing
+            continue
+        recency = 1.0 - days / 30.0
+        quality = rub if rub is not None else 0.75
+        score += recency * quality
+    return round(min(3.0, score), 2)
+
+
+def selftest():
+    """Lock the three bugs found building the momentum gate. Pure, no mocks,
+    real learnings-shaped strings. Run: do-rank.py --selftest"""
+    from datetime import date
+    ref = date(2026, 6, 20)
+    fails = []
+
+    def check(name, cond):
+        if not cond:
+            fails.append(name)
+
+    # 1. hyphen boundary: slug 'inbox' must NOT match 'inbox-simple'
+    check("hyphen: inbox≠inbox-simple", not _slug_matcher("inbox").search("inbox-simple"))
+    check("hyphen: inbox==inbox", bool(_slug_matcher("inbox").search("· inbox · plan")))
+
+    # 2. plan_closed: detects 'PLAN · CLOSE' format, scoped to the right slug
+    vlog = [(ref, None, "- 2026-06-17 · visitor-to-people PLAN · CLOSE · all 5 cycles shipped; kill-switch exits 0")]
+    check("close: visitor-to-people DONE", plan_closed("visitor-to-people", vlog))
+    check("close: inbox NOT marked by inbox-simple",
+          not plan_closed("inbox", [(ref, None, "- 2026-06-20 · inbox-simple · plan · close GREEN")]))
+
+    # 3. momentum subject-zone: 'clean' as prose adjective must NOT count
+    plog = [(ref, 0.70, "- 2026-06-20 · plugins · C1 · INSERT OR IGNORE is the clean pattern · rubric=0.70")]
+    check("momentum: clean prose ignored", momentum_score("clean", plog, ref) == 0.0)
+    check("momentum: plugins subject counts", momentum_score("plugins", plog, ref) > 0.0)
+    # recency decay: a 40-day-old close contributes nothing
+    old = [(date(2026, 5, 1), 0.9, "- 2026-05-01 · sell · plan · x")]
+    check("momentum: stale close decays to 0", momentum_score("sell", old, ref) == 0.0)
+
+    # 4. lint_paths: phantom/wrong-rooted flagged; real + planned-new-file accepted.
+    # Uses real on-disk paths so the rule (exists OR leaf-file-with-real-grandparent)
+    # is checked against the actual repo, same culture as the rest of selftest.
+    real_dir = "one.ie/web/src/lib"           # a dir that exists
+    new_file = "one.ie/web/src/lib/in/zzz-not-real.ts"  # planned file, real grandparent
+    phantom_url = "api/composio/connections"  # URL-style route, fake top/second dir
+    fm_real = f"deliverables:\n  - lib: {real_dir} — x\n"
+    fm_new = f"deliverables:\n  - lib: {new_file} — x\n"
+    fm_bad = f"deliverables:\n  - api: {phantom_url} — x\n"
+    check("lint: real dir accepted", lint_paths(fm_real) == [])
+    check("lint: planned new file accepted", lint_paths(fm_new) == [])
+    check("lint: phantom url-route flagged", len(lint_paths(fm_bad)) == 1)
+
+    # 5. deliverable_dirs subtree granularity: a file → its CONTAINING dir (filename
+    # dropped); a bare dir → itself. This is the fleet's disjointness key.
+    fm_sub = ("deliverables:\n"
+              "  - lib: one.ie/web/src/lib/billing/expiry.ts — x\n"
+              "  - dir: channels/src — y\n")
+    check("dirs: file → parent subtree",
+          "one.ie/web/src/lib/billing" in deliverable_dirs(fm_sub))
+    check("dirs: filename dropped",
+          "one.ie/web/src/lib/billing/expiry.ts" not in deliverable_dirs(fm_sub))
+    check("dirs: bare dir kept", "channels/src" in deliverable_dirs(fm_sub))
+
+    # 6. transitive leverage: a→b→c chain ⇒ a has 2 dependents (b and c), not 1.
+    direct = {"a": {"b"}, "b": {"c"}, "c": set()}
+    check("leverage: transitive chain a→b→c == 2",
+          len(transitive_dependents("a", direct)) == 2)
+    check("leverage: leaf c == 0", len(transitive_dependents("c", direct)) == 0)
+
+    # 7. toxic classifier (the queue's guard): cold+stale+signal ⇒ toxic; warm OR fresh
+    # ⇒ NEVER toxic. The two protection cases (analytics warm, speed-channels fresh) are
+    # load-bearing — they lock that a large open-box count can't demote a valuable plan.
+    check("toxic: warm never toxic (analytics mom>0)", is_toxic(0.82, 33, 349, 0.09, True) == [])
+    check("toxic: fresh never toxic (speed not stale)", is_toxic(0.0, 0, 4, 0.0, False) == [])
+    check("toxic: empty cold stale (features)", "empty" in is_toxic(0.0, 0, 0, 0.0, True))
+    check("toxic: deliverables block ⇒ not empty (foundation-ui)",
+          "empty" not in is_toxic(0.0, 0, 0, 0.0, True, has_deliverables=True))
+    check("toxic: zero-progress cold stale (crx)", "zero-progress" in is_toxic(0.0, 0, 250, 0.0, True))
+    check("toxic: mega cold stale (people)", "mega-stale" in is_toxic(0.0, 30, 239, 0.11, True))
+
+    # 8. fade (C2): asymmetric decay — resistance decays 2× faster than strength (world.fade).
+    s1, r1 = _fade_one(1.0, 1.0, 0.1)
+    check("fade: strength ×(1-r)", s1 == 0.9)
+    check("fade: resistance 2× faster", r1 == 0.8)
+    check("fade: resistance falls faster than strength", r1 < s1)
+    check("fade: resistance floors at 0 (rate>0.5)", _fade_one(1.0, 1.0, 0.6)[1] == 0.0)
+
+    # 9. frontier (C4): every returned slug is a plan WITHOUT a todo (set difference holds).
+    # now_ct=None skips git staleness, empty log skips close-filtering → pure set-difference.
+    fr, _fstale, _fclosed = frontier(None, [])
+    todo_set = {f.name[: -len("-todo.md")] for f in TEXT.glob("*-todo.md")}
+    check("frontier: no returned slug has a todo", all(slug not in todo_set for _s, _d, slug, _t in fr))
+    check("frontier: queue-frontier itself excluded (has a todo)",
+          all(slug != "queue-frontier" for _s, _d, slug, _t in fr))
+
+    # 10. closed-plan filter (C5): frontier() reuses plan_closed (the todo walk's close-rule)
+    # to hide shipped plans — power-through-simplicity, one close-rule for both. Unit-test the
+    # reused detector directly: format match, no false positive, and the hyphen-family guard.
+    cl = [(None, None, "- 2026-06-30 · braindo PLAN · CLOSE · all 3 cycles shipped; kill-switch exits 0")]
+    check("plan_closed: recorded PLAN·CLOSE detected", plan_closed("braindo", cl) is True)
+    check("plan_closed: unrelated slug not matched", plan_closed("wallet", cl) is False)
+    check("plan_closed: hyphen-family not cross-matched (brain≠braindo)", plan_closed("brain", cl) is False)
+
+    # 11. gated exclusion (build_gate): a human-approval cycle is held OUT of ready/--top/
+    # fleet so a blanket do-fleet/do-auto run never auto-launches it (e.g. real-money
+    # x402-settlement). Detection is frontmatter-scoped: a build_gate in the BODY never
+    # gates (else any doc mentioning the field would vanish from the queue), and an empty
+    # build_gate line does not gate (requires a value). Locks the full is_gated contract.
+    check("gated: frontmatter build_gate ⇒ gated",
+          is_gated('---\ntitle: x\nbuild_gate: "human-approval"\n---\nbody') is True)
+    check("gated: no build_gate ⇒ not gated",
+          is_gated('---\ntitle: x\npriority: 2\n---\nbody') is False)
+    check("gated: build_gate in BODY only ⇒ not gated (frontmatter-scoped)",
+          is_gated('---\ntitle: x\n---\nbuild_gate: y in prose') is False)
+    check("gated: empty build_gate value ⇒ not gated (needs a reason)",
+          is_gated('---\ntitle: x\nbuild_gate:\n---\nbody') is False)
+
+    if fails:
+        print("SELFTEST FAIL:")
+        for f in fails:
+            print("  ✗", f)
+        sys.exit(1)
+    print("SELFTEST: 35/35 pass (hyphen-boundary · plan-close · momentum subject-zone · "
+          "decay · deliverables-lint · subtree-dirs · transitive-leverage · toxic-classifier · "
+          "deliverables-guard · fade-asymmetry · frontier-setdiff · frontier-closed-filter · "
+          "gated-exclusion)")
+
+
+def main():
+    args = sys.argv[1:]
+    as_json = "--json" in args
+    toxic_report = "--toxic" in args
+    tasks_human = "--tasks" in args
+    tasks_seed_out = "--tasks-json" in args
+    top_n = None
+    if "--top" in args:
+        i = args.index("--top")
+        top_n = int(args[i + 1])
+    if "--selftest" in args:
+        return selftest()
+
+    # `--dirs <slug>` — the subtree dirs a plan ships into, one per line. The SINGLE
+    # disjointness extractor: do-fleet.sh calls this instead of re-parsing markdown in
+    # bash, so the displayed waves and the fleet's live conflict check can never drift.
+    if "--dirs" in args:
+        i = args.index("--dirs")
+        slug = args[i + 1]
+        f = TEXT / f"{slug}-todo.md"
+        if f.exists():
+            for d in sorted(deliverable_dirs(f.read_text(errors="ignore"))):
+                print(d)
+        return
+
+    # `--lint` — mechanical deliverables hygiene across all OPEN plans. Flags phantom
+    # paths (under-qualified/wrong-rooted) that make a plan a fleet false-parallel, and
+    # plans with NO parseable deliverables (a fleet hazard). Exit 1 if any plan is dirty.
+    if "--lint" in args:
+        log, _ = load_learnings_log()
+        dirty = 0
+        for f in sorted(TEXT.glob("*-todo.md")):
+            slug = f.name[: -len("-todo.md")]
+            if slug in EXCLUDE:
+                continue
+            text = f.read_text(errors="ignore")
+            done_b, open_b = checkbox_state(text)
+            if (done_b + open_b > 0 and open_b == 0) or plan_closed(slug, log):
+                continue  # closed/done — not a live fleet candidate
+            bad = lint_paths(text)
+            scoped = bool(deliverable_paths(text))
+            if not bad and scoped:
+                continue
+            dirty += 1
+            print(f"\n  ✗ {slug}")
+            if not scoped:
+                print("      UNSCOPED — no parseable deliverable paths (fleet excludes it; not fleet-safe)")
+            for tok, why in bad:
+                print(f"      PHANTOM  {tok}  — {why}")
+        if dirty:
+            print(f"\n  {dirty} plan(s) need deliverables hygiene before fleeting. "
+                  f"Fix paths to repo-root-relative (one.ie/web/src/...).\n")
+            sys.exit(1)
+        print("  deliverables lint: all open plans scoped + all paths resolve ✓")
+        return
+
+    # `--sync-closes` — reconcile path strength from learnings.md closes (idempotent).
+    # The autonomous close→weight wire: the sync-priority-todo hook runs this on every
+    # learnings.md edit, so a cycle close moves the weight with no human in the loop.
+    if "--sync-closes" in args:
+        log, ref = load_learnings_log()
+        n = sync_closes(log, ref)
+        print(f"  synced closes → {n} task path(s) updated in {TASK_PATHS.name}")
+        return
+
+    # `--trails` — track the loop: show the trails outcomes have worn into the path
+    # store. A trail = accumulated path strength (closes + live marks) minus resistance.
+    # Strong trails are highways the next pick follows; resistance-heavy ones are fading.
+    if "--trails" in args:
+        paths = load_task_paths()
+        rows = []
+        for key, e in paths.items():
+            closed = float(e.get("closed", 0))
+            strength = float(e.get("strength", 0))
+            resistance = float(e.get("resistance", 0))
+            net = round(closed + strength - resistance, 2)
+            rows.append((net, key, closed, strength, resistance, int(e.get("traversals", 0))))
+        rows.sort(reverse=True)
+        print("\n  TRAILS — paths the loop has worn (weighed by outcome · close + live mark − resistance)\n")
+        if not rows:
+            print("  (no trails yet — a cycle close or a mark wears the first one)\n")
+            return
+        print(f"  {'NET':>5}  {'closed':>6} {'live':>5} {'resist':>6} {'×':>4}  TRAIL")
+        print(f"  {'-'*5}  {'-'*6} {'-'*5} {'-'*6} {'-'*4}  {'-'*30}")
+        for net, key, c, s, r, tv in rows[:25]:
+            band = "🛣 highway" if net >= 4 else "· trail" if net >= 2 else "  forming"
+            if r > c + s:
+                band = "✗ fading"
+            print(f"  {net:>5.1f}  {c:>6.1f} {s:>5.1f} {r:>6.1f} {tv:>4}  {key:<26} {band}")
+        print(f"\n  {len(rows)} trail(s). A close → --sync-closes wears it deeper; warn/--fail lets it fade.")
+        print(f"  These are the task-layer trails (text/task-paths.json); the substrate trail is claw_paths/path.strength.\n")
+        return
+
+    # `--mark <slug> [--fail] [--amount N]` — the mark/warn verb for the task layer.
+    # Closes the loop: moves path strength, then the next --tasks/queue run reads it.
+    if "--mark" in args:
+        i = args.index("--mark")
+        slug = args[i + 1]
+        outcome = "failure" if "--fail" in args else "success"
+        amount = 1.0
+        if "--amount" in args:
+            amount = float(args[args.index("--amount") + 1])
+        e = mark_task(slug, outcome, amount)
+        pm = path_momentum(slug, load_task_paths()) or 0.0
+        delta = round(10 * pm, 1)
+        print(f"  {outcome:>7}  task:{slug}  →  strength={e['strength']} resistance={e['resistance']} "
+              f"traversals={e['traversals']}")
+        print(f"  path-momentum={pm}  ⇒  weight gains +{delta} over base 50 on the next --tasks run")
+        return
+
+    # `--fade [--rate R]` — the fade verb for the task layer (C2). Asymmetric decay of LIVE
+    # weight (resistance 2× faster). The hourly action: unworked live marks cool, warnings
+    # heal. `closed` is left to --sync-closes (already recency-decayed). Default rate 0.1.
+    if "--fade" in args:
+        rate = 0.1
+        if "--rate" in args:
+            rate = float(args[args.index("--rate") + 1])
+        n = fade_paths(rate)
+        r = max(0.0, min(1.0, rate))
+        print(f"  faded {n} live task path(s) at rate {r}  →  strength ×{1 - r:.2f}, "
+              f"resistance ×{max(0.0, 1 - 2 * r):.2f} (engine.md: resistance decays 2× faster)")
+        print(f"  closed weight untouched (owned by --sync-closes · learnings 30-day recency window)")
+        return
+
+    # `--frontier` — what's next past every armed todo (C4): designed-but-unarmed plans,
+    # import-stale ones hidden, ranked by strategic pull. The 'after all done or toxic' edge.
+    if "--frontier" in args:
+        now_ct = repo_now()
+        flog, _fref = load_learnings_log()
+        fresh, stale, closed = frontier(now_ct, flog)
+        print(f"\n  FRONTIER — {len(fresh)} designed-but-unarmed plan(s) past the live queue "
+              f"(no todo yet; {closed} shipped/closed + {stale} import-stale hidden)\n")
+        if fresh:
+            print(f"  {'STRAT':>5}  {'AGE':>4}  SLUG")
+            print(f"  {'-' * 5}  {'-' * 4}  {'-' * 30}")
+            for strat, days, slug, title in fresh[:20]:
+                print(f"  {strat:>5}  {days:>3}d  {slug:<28} {title}")
+        print(f"\n  past these: the substrate's own frontiers_global (TypeDB hypotheses) — "
+              f"the migration target (not wired this cycle).\n")
+        return
+
+    log, ref = load_learnings_log()
+    task_paths = load_task_paths()
+    plans = {}
+
+    for f in sorted(TEXT.glob("*-todo.md")):
+        slug = f.name[: -len("-todo.md")]
+        if slug in EXCLUDE:
+            continue
+        text = f.read_text(errors="ignore")
+        fm = parse_frontmatter(text)
+        done_b, open_b = checkbox_state(text)
+        total = done_b + open_b
+        # DONE = all boxes ticked, OR a PLAN-level close in learnings.md, OR the
+        # todo's outcome line is already ticked ("[x] Plan outcome command exits 0").
+        # The last case catches plans where do-auto ticked the outcome but left
+        # stale sub-items unchecked — the ranker and do-auto must agree on "done".
+        outcome_ticked = bool(re.search(
+            r"-\s*\[x\].*(?:Plan outcome command exits 0|outcome.*exits 0)", text, re.IGNORECASE
+        ))
+        is_done = (total > 0 and open_b == 0) or plan_closed(slug, log) or outcome_ticked
+        pr_raw = re.match(r"\d+", str(fm.get("priority", "0")))
+        priority = int(pr_raw.group(0)) if pr_raw else 0
+        plans[slug] = {
+            "slug": slug,
+            "title": fm.get("title", ""),
+            "tier": fm.get("tier", "?"),
+            "tags": fm.get("tags", []),
+            "priority": priority,
+            "depends_on": fm.get("depends_on", []),
+            "done_boxes": done_b,
+            "total_boxes": total,
+            "is_done": is_done,
+            # build_gate: human-approval-required → never auto-selected (held out of ready/--top/fleet)
+            "gated": is_gated(text),
+            # strategic capped at 6 so the keyword heuristic can't drown out
+            # proven momentum — warm, clean-building work should pull, not buzzwords.
+            "strategic": min(strategic_score(slug, fm), 6),
+            "proximity": round(done_b / total, 2) if total else 0.0,
+            # momentum = LIVE path strength when this slug has been marked (the closed
+            # loop), else the learnings.md count (the bootstrap). A mark() here changes
+            # the next pick — that is the self-improving loop, proven on one entity.
+            "momentum": (lambda pm: pm if pm is not None else momentum_score(slug, log, ref))(
+                path_momentum(slug, task_paths)
+            ),
+            "_dirs": deliverable_dirs(text),
+            # subtasks = the plan's cycle ids, from cycle/wave headings (light parse)
+            "cycles": sorted(
+                set(re.findall(r"(?mi)^#{1,4}.*\bC(\d+)\b", text)), key=int
+            ),
+        }
+
+    # Leverage: how many OPEN plans transitively depend on each slug — unblocking a
+    # keystone frees its whole downstream chain, not just direct children. Example:
+    # namespace ← tasks-mine ← tasks-push ← tasks-bridge → namespace's leverage is 3,
+    # not 1, so the keystone ranks above plans that unblock nothing. Done plans don't
+    # count (nothing waits on them). Built by walking depends_on edges to a fixpoint.
+    direct = {s: set() for s in plans}  # slug -> set of slugs that directly depend on it
+    for p in plans.values():
+        for dep in p["depends_on"]:
+            if dep in plans:
+                direct[dep].add(p["slug"])
+
+    for p in plans.values():
+        deps = transitive_dependents(p["slug"], direct)
+        p["leverage"] = sum(1 for s in deps if not plans[s]["is_done"])
+        p["dept"] = classify_dept(p["slug"], {"title": p["title"], "tags": p["tags"]})
+        p["weight"] = task_weight(p)
+
+    now_ct = repo_now()  # the repo's HEAD time = "now" for staleness (no wall clock)
+    ready, blocked, done, faded, gated = [], [], [], [], []
+    for p in plans.values():
+        if p["is_done"]:
+            done.append(p["slug"])
+            continue
+        # GATED = build_gate: human-approval-required → held OUT of the auto-selection feed
+        # (ready/--top/fleet/do-auto) so no blanket run launches it; surfaced in its own
+        # bucket (visible, never deleted). Checked before toxic/blocked: a gated cycle is
+        # withheld regardless of warmth or deps — a human runs it by explicit slug or not at
+        # all. This is the do-fleet × build_gate safety gap: do-fleet feeds from --top, which
+        # had ZERO build_gate awareness, so a gated real-money cycle ranked like any other.
+        if p["gated"]:
+            gated.append(p)
+            continue
+        # Toxic = cold (momentum==0) + stale + a noise signal → QUARANTINE out of the
+        # live queue (a separate bucket, not a score penalty: a score-0 plan can't be
+        # faded lower, so exclusion is the only removal). Checked before blocked: cold
+        # noise is noise whether or not a dependency is also unmet.
+        tox = toxic_reasons(p, now_ct)
+        if tox:
+            p["toxic_reasons"] = tox
+            faded.append(p)
+            continue
+        unmet = [d for d in p["depends_on"]
+                 if d in plans and not plans[d]["is_done"]]
+        if unmet:
+            p["waiting_on"] = unmet
+            blocked.append(p)
+            continue
+        # The closed loop: momentum (what the loop LEARNED) now steers what it
+        # builds NEXT. 2·strategic + 2·leverage + 1·proximity + 2·priority + 2·momentum.
+        p["score"] = (2 * p["strategic"] + 2 * p["leverage"]
+                      + 1 * round(p["proximity"] * 3) + 2 * p["priority"]
+                      + 2 * round(p["momentum"]))
+        ready.append(p)
+
+    ready.sort(key=lambda x: (-x["score"], -x["momentum"], -x["priority"], x["slug"]))
+    blocked.sort(key=lambda x: x["slug"])
+
+    # active = open work (ready + blocked); done AND faded plans are not live tasks.
+    active = ready + blocked
+
+    if toxic_report:
+        # Read-only report — the `--toxic` deliverable. Nothing is written or deleted;
+        # this is purely a projection of file state, recomputed every run.
+        if not faded:
+            print("  no toxic todos — the live queue is clean ✓")
+            return
+        print(f"\n  TOXIC — {len(faded)} cold+stale todo(s) demoted from the live queue "
+              f"(read-only; nothing deleted)\n")
+        for p in sorted(faded, key=lambda x: x["slug"]):
+            print(f"  {p['slug']:<22} {', '.join(p['toxic_reasons'])}")
+        print(f"\n  gate: momentum==0 (no close in window) AND stale (≥{STALE_DAYS}d since commit) "
+              f"AND a noise signal. warm or fresh ⇒ never toxic.\n")
+        return
+
+    if tasks_seed_out:
+        print(json.dumps(tasks_seed(active), indent=2))
+        return
+    if tasks_human:
+        print("\n" + "\n".join(tasks_view(active)) + "\n")
+        return
+
+    if top_n is not None:
+        for p in ready[:top_n]:
+            print(p["slug"])
+        return
+
+    if as_json:
+        print(json.dumps({
+            "ready": [{k: p[k] for k in
+                       ("slug", "score", "strategic", "leverage", "proximity",
+                        "priority", "momentum", "tier", "title")} for p in ready],
+            "blocked": [{"slug": p["slug"], "waiting_on": p["waiting_on"]}
+                        for p in blocked],
+            "faded": [{"slug": p["slug"], "reasons": p["toxic_reasons"]}
+                      for p in sorted(faded, key=lambda x: x["slug"])],
+            "done": sorted(done),
+        }, indent=2))
+        return
+
+    # Human table
+    print(f"\n  PRIORITY QUEUE — {len(ready)} ready · {len(blocked)} blocked · "
+          f"{len(faded)} faded · {len(done)} done\n")
+    print(f"  {'SCORE':>5}  {'S':>2} {'L':>2} {'P':>4} {'Pr':>2} {'M':>4}  {'TIER':<8} SLUG")
+    print(f"  {'-'*5}  {'-'*2} {'-'*2} {'-'*4} {'-'*2} {'-'*4}  {'-'*8} {'-'*30}")
+    for p in ready[:40]:
+        print(f"  {p['score']:>5}  {p['strategic']:>2} {p['leverage']:>2} "
+              f"{p['proximity']:>4} {p['priority']:>2} {p['momentum']:>4}  "
+              f"{p['tier']:<8} {p['slug']}")
+    if blocked:
+        print(f"\n  BLOCKED ({len(blocked)}) — waiting on a dependency:")
+        for p in blocked:
+            print(f"    {p['slug']:<30} ← {', '.join(p['waiting_on'])}")
+
+    # GATED — build_gate: human-approval-required. Held OUT of ready/--top/fleet/do-auto so
+    # no blanket run auto-launches it (e.g. the real-money x402-settlement). Visible, never
+    # deleted; a human runs it by explicit slug after approving. Surfaced prominently because
+    # it is the safety signal — the operator must SEE what the fleet will not touch.
+    if gated:
+        print(f"\n  GATED ({len(gated)}) — build_gate: human-approval-required; held OUT of ready/--top/fleet (run only by explicit /do <slug>):")
+        for p in sorted(gated, key=lambda x: x["slug"]):
+            print(f"    {p['slug']:<30} {p['title'][:48]}")
+
+    # FADED — cold + stale + a noise signal. Demoted out of the live queue (NOT deleted);
+    # the file is untouched, this is recomputed every run. See `--toxic` for the gate.
+    if faded:
+        print(f"\n  FADED ({len(faded)}) — cold + stale, demoted from the live queue (not deleted):")
+        for p in sorted(faded, key=lambda x: x["slug"]):
+            print(f"    {p['slug']:<30} {', '.join(p['toxic_reasons'])}")
+
+    # FLEET WAVES — which ready plans are file-disjoint (safe to run in parallel).
+    # do-fleet.sh launches the top slots; this shows the human the natural batches.
+    waves, unscoped = pack_waves(ready)
+    if waves:
+        print(f"\n  FLEET WAVES — file-disjoint batches (do-fleet.sh --slots N --go):")
+        for i, w in enumerate(waves, 1):
+            print(f"    wave {i} ({len(w['slugs'])}):  {' · '.join(w['slugs'])}")
+    if unscoped:
+        print(f"\n  ⚠ UNSCOPED ({len(unscoped)}) — no deliverables: declared, NOT fleet-safe.")
+        print(f"    The fleet sees zero dirs ⇒ would parallelize these blindly and clobber")
+        print(f"    shared trees (e.g. one.ie/web). Add a deliverables: block before fleeting:")
+        for s in unscoped:
+            print(f"      {s}")
+    # FRONTIER — surfaces only when the live queue thins (everything done or faded). The
+    # answer to "what's next after they're all done or toxic": designed-but-unarmed plans.
+    if len(ready) <= 3:
+        fresh, fstale, fclosed = frontier(now_ct, log)
+        if fresh:
+            print(f"\n  FRONTIER — queue is thin; next designed-but-unarmed plans "
+                  f"({fclosed} shipped/closed + {fstale} import-stale hidden):")
+            for strat, days, slug, _title in fresh[:5]:
+                print(f"    {slug:<30} strat={strat} ({days}d since design)")
+            print(f"    → past these: frontiers_global (substrate hypotheses) · full list: do-rank.py --frontier")
+
+    print(f"\n  legend: S=strategic ×2 (cap 6) · L=leverage ×2 · P=proximity ×1 · Pr=priority ×2 · M=momentum ×2")
+    print(f"  M = the loop reading its own output: recent high-rubric closes from learnings.md")
+    print(f"  → warm, proven work pulls the fleet (cheaper to continue than start cold)")
+    print(f"  run with --json for the fleet, --top N for the top slugs\n")
+
+    # The tasks layer: every todo as a tagged, weighted signal (text/tasks-plan.md).
+    print("\n".join(tasks_view(active)))
+
+
+if __name__ == "__main__":
+    main()