@oneie/claude 0.6.0 → 0.8.0

package/scripts/do-rank.py

@@ -25,10 +25,13 @@ Usage:
   do-rank.py --top N         the N highest READY slugs, one per line
 """
 import json
+import os
 import re
 import signal
 import subprocess
 import sys
+import urllib.parse
+import urllib.request
 from pathlib import Path
 
 # Exit cleanly when piped into head/etc. (closes our stdout early).
@@ -93,6 +96,19 @@ def deliverable_dirs(text):
     dirs = set()
     for tok in deliverable_paths(text):
         parts = tok.split("/")
+        # `text/` is the ONE family where the containing-dir rule is wrong. The
+        # coupling argument above holds for code (two plans in one component family
+        # clobber each other); it does not hold here, because text/ is one flat dir
+        # of per-slug documents — `text/<slug>-docs.md` is named after the plan that
+        # owns it, so two plans there edit two different files BY CONSTRUCTION and
+        # cannot collide. Keying them to the shared `text` dir made every plan with a
+        # `doc:` deliverable mutually exclusive with every other: measured 2026-08-31,
+        # it serialized all four lifecycle children (and voice-agents, identity,
+        # playbook-run, agent-wallet-guardian) behind one another for no real conflict.
+        # File granularity here, containing-dir everywhere else.
+        if parts[0] == "text" and len(parts) == 2 and "." in parts[-1]:
+            dirs.add(tok)
+            continue
         # 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:
@@ -118,7 +134,12 @@ 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)",
+    # The key line may carry a trailing YAML comment — `deliverables:   # note`.
+    # It legally does in 12 tracked plans INCLUDING text/template-todo.md, the
+    # file every new plan is copied from, so a `\s*$` anchor here made plans
+    # born unscoped: the block never matched, zero paths came back, and the
+    # fleet read that as "declares no dirs" and refused to pack them.
+    m = re.search(r"^deliverables:[ \t]*(?:#[^\n]*)?$(.*?)(?=^[a-z_]+:|^---\s*$|\Z)",
                   text, re.MULTILINE | re.DOTALL)
     if not m:
         return []
@@ -261,11 +282,284 @@ def tasks_view(active):
             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("  → signal(receiver:\"tasks:announce\", payload:task, tags:task.tags) — live; 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
 
 
+# Which doc-family suffixes an agent should load to work a task, in read order.
+# The promise first (the contract), then how/what, then the cycles, then the spec.
+_CONTEXT_SUFFIXES = ("", "-plan", "-features", "-ui", "-todo", "-docs")
+
+
+def task_context_for(p):
+    """Build the context a picked-up task carries — the keystone for auto-pickup.
+
+    Returns (notes, context_docs):
+      • notes       — human prose description → `thing.notes` (shown on the row / detail).
+                      Fallback chain: title em-dash detail → outcome_asserts → title.
+      • context_docs— the doc *stems* that exist for this slug → `thing.task-context`
+                      (multi-valued, one per stem). An agent reads these files to know
+                      HOW to do the work — literally "get context" for `/do <slug>`.
+    """
+    slug, title = p["slug"], (p.get("title") or p["slug"])
+    # detail = the part after the em-dash / en-dash in the title ("Tasks — the loop…")
+    m = re.match(r"^\s*(.+?)\s+[—–-]\s+(.+)$", title)
+    detail = m.group(2).strip() if m else title.strip()
+    asserts = (p.get("outcome_asserts") or "").strip()
+    notes = detail
+    if asserts and asserts.lower() not in detail.lower():
+        notes = f"{detail}\n\nDone when: {asserts}" if detail else asserts
+    docs = [f"{slug}{sfx}" for sfx in _CONTEXT_SUFFIXES
+            if (TEXT / f"{slug}{sfx}.md").exists()]
+    return notes, docs
+
+
+def _gateway_key():
+    """Same lookup as do-signal.sh's _gateway_key() — first file that has it wins.
+
+    GATEWAY_API_KEY, not SERVER_SECRET: /api/ask/<receiver> decides isServiceCaller off
+    env.GATEWAY_API_KEY (one.ie/web/src/pages/api/ask/[...receiver].ts). Presenting
+    SERVER_SECRET there resolves to no service caller, no ctx.ownerSlug, and every
+    tasks:* resolver answers {error:"workspace required"} — which this fetch used to
+    swallow as an empty board, so the ranker silently ran file-only forever."""
+    # UPDATE 2026-07-26 — prefer the WORLD key. The service-caller path described above is
+    # real but fragile: it grants identity only when the receiver's request schema declares
+    # `workspace`/`slug`, because /api/ask reads the nomination off validation.payload —
+    # i.e. AFTER zod, which strips undeclared keys. tasks:mine and tasks:everywhere did not
+    # declare it, so GATEWAY_API_KEY could never address them (fixed in 73dbeca7a, live only
+    # after a one-prod deploy).
+    #
+    # A world key (`one-`/`osk_`) has no such dependency: verifyWorldKey resolves it to an
+    # actual actor, so ctx.ownerSlug comes from the key itself and no nomination is needed.
+    # It is what the MCP server has always used (ONEIE_API_KEY — packages/mcp/src/env.ts)
+    # and it reads the board TODAY. Verified 2026-07-26: POST /api/ask/tasks:everywhere
+    # returns ok:true with the world key and "forbidden: authentication required" with
+    # GATEWAY_API_KEY. World key first; GATEWAY_API_KEY stays as the fallback.
+    candidates = [os.environ.get("DO_ENV_FILE", "")] if os.environ.get("DO_ENV_FILE") else []
+    candidates += [str(ROOT / "one.ie/web/.env"), str(ROOT / "one.ie/web/.secrets.generated.local"),
+                   str(ROOT / "one.ie/web/.dev.vars")]
+    # An explicit env var wins over any file — how a fleet/CI run injects its own identity.
+    for var in ("ONEIE_API_KEY", "ONE_API_KEY", "GATEWAY_API_KEY"):
+        if os.environ.get(var):
+            return os.environ[var].strip()
+
+    # Rank by KEY GENERATION, not by which file we happened to read first. Both `one-` and
+    # legacy `osk_` authenticate (ok:true either way), but they resolve to DIFFERENT actors —
+    # and on 2026-07-26 the `osk_` key in one.ie/web/.env resolved to an actor that could see
+    # nothing, so every board read came back green-and-empty while the operator's own board
+    # showed 11 open tasks. A green empty read is the worst failure this script has: it is
+    # indistinguishable from "no work queued". So: modern world key > legacy > service secret.
+    found = {"one-": "", "osk_": "", "gw": ""}
+
+    def offer(tok):
+        if tok.startswith("one-"):
+            found["one-"] = found["one-"] or tok
+        elif tok.startswith("osk_"):
+            found["osk_"] = found["osk_"] or tok
+
+    # The working credential lives in the MCP server config, not in any repo .env — that is
+    # what the MCP tools authenticate with, and it is the one proven to read the board.
+    # Read it in place; never copy key bytes into a repo file.
+    mcp_cfg = Path.home() / ".claude.json"
+    if mcp_cfg.exists():
+        try:
+            def walk(o):
+                if isinstance(o, dict):
+                    for k, v in o.items():
+                        if k in ("ONEIE_API_KEY", "ONE_API_KEY") and isinstance(v, str) and v.strip():
+                            offer(v.strip())
+                        else:
+                            walk(v)
+                elif isinstance(o, list):
+                    for v in o:
+                        walk(v)
+            walk(json.loads(mcp_cfg.read_text(errors="ignore")))
+        except Exception:
+            pass  # a malformed config must never break ranking
+
+    for f in candidates:
+        p = Path(f)
+        if not p.exists():
+            continue
+        for line in p.read_text(errors="ignore").splitlines():
+            for var in ("ONEIE_API_KEY=", "ONE_API_KEY="):
+                if line.startswith(var):
+                    offer(line.split("=", 1)[1].strip().strip('"'))
+            if line.startswith("GATEWAY_API_KEY=") and not found["gw"]:
+                found["gw"] = line.split("=", 1)[1].strip().strip('"')
+
+    return found["one-"] or found["osk_"] or found["gw"]
+
+
+def fetch_tasks_everywhere(timeout=None):
+    """Board-origin open tasks — the substrate half of the ranked queue (tasks-do C2).
+
+    Returns (rows, reason): rows is the raw `tasks:everywhere` list, reason is "" on a
+    real answer or a SHORT diagnostic on any degrade. The ranker still never crashes and
+    still falls back to file-only — but the caller can now tell "no key configured" from
+    "auth rejected" from "the board is genuinely empty" (closed-loop rule: no silent
+    returns). TASKS_EVERYWHERE marker below is what the demo gate greps for."""
+    # tasks:everywhere is a four-phase read (actor groups → task scan → strength reads);
+    # measured 10.9s against a warm dev server. The old 5s default meant that even a
+    # correctly-authenticated ranker timed out every time — the auth bug was masking a
+    # latency bug.
+    #
+    # Two budgets, because this script has two very different callers. The SessionStart
+    # hook and the *-todo.md PostToolUse hook run it on EVERY session open and EVERY plan
+    # edit; blocking those for 25s to enrich a ranking that degrades gracefully is a bad
+    # trade, so hook-driven runs get a short budget and fall back to file-only. An explicit
+    # queue read (/do next, the fleet) waits for the real answer.
+    if timeout is None:
+        default = "4" if os.environ.get("DO_RANK_HOOK") else "25"
+        timeout = float(os.environ.get("DO_RANK_BOARD_TIMEOUT", default))
+    secret = _gateway_key()
+    if not secret:
+        return [], "no GATEWAY_API_KEY in one.ie/web/.env"  # TASKS_EVERYWHERE: file-only fallback
+    url = os.environ.get("DO_SIGNAL_URL", "https://one.ie") + "/api/ask/tasks:everywhere"
+    # `workspace` is load-bearing, not decoration: /api/ask reads the service caller's
+    # nominated slug off payload.slug|payload.workspace and that becomes ctx.ownerSlug.
+    # Omit it and tasks:everywhere answers {ok:false,error:"forbidden: authentication
+    # required"} because a service call carries no session actor of its own.
+    ws = os.environ.get("CC_TASKS_WORKSPACE", "one")
+    body = json.dumps({"data": {"limit": 200, "workspace": ws}}).encode()
+    req = urllib.request.Request(
+        url, data=body, method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {secret}",
+            # Cloudflare answers the default urllib UA with 403 "error code: 1010"
+            # (browser-integrity block) before the Worker ever runs. curl gets through,
+            # which is why do-signal.sh never hit this and the ranker always did.
+            "User-Agent": "one-do-rank/1.0 (+https://one.ie)",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            payload = json.loads(r.read().decode())
+    except urllib.error.HTTPError as e:  # TASKS_EVERYWHERE: fetch failed — file-only fallback
+        detail = "CF bot block (UA rejected)" if e.code == 403 else ""
+        return [], f"HTTP {e.code}{' — ' + detail if detail else ''}"
+    except Exception as e:  # TASKS_EVERYWHERE: fetch failed — file-only fallback
+        return [], f"unreachable ({type(e).__name__})"
+    if not isinstance(payload, dict):
+        return [], "malformed response (not an object)"
+    # /api/ask wraps every answer: {outcome, result:{ok, tasks}, signalId, receiver}.
+    # Reading ok/tasks off the TOP level (as this did) makes even a good answer look
+    # like a failure — the merge could never have fired, key or no key.
+    inner = payload.get("result")
+    inner = inner if isinstance(inner, dict) else payload
+    if not inner.get("ok"):
+        err = str(inner.get("error") or payload.get("error") or payload.get("outcome") or "unknown")
+        hint = ""
+        if "authentication" in err or err == "workspace required":
+            # This used to read "local key may not match prod", which is WRONG and cost two
+            # sessions chasing a secret that was never broken (73dbeca7a). A `forbidden` here
+            # is almost never the key: /api/ask resolves a service caller's workspace from
+            # validation.payload.slug|workspace — i.e. AFTER zod has run — and z.object()
+            # strips any key the request schema doesn't declare. If the receiver's schema
+            # omits `workspace`, `nominated` is undefined, ctx.ownerSlug stays empty, and you
+            # get this exact error no matter which key you present. Browser calls are immune
+            # (locals.slug supplies the workspace), so it fails only for the harness.
+            hint = (
+                " — check the RECEIVER SCHEMA before the key: /api/ask reads the nominated"
+                " workspace off validation.payload (post-zod), so a receiver whose request"
+                " schema omits `workspace` can never be addressed by a service caller."
+                " Verify the key separately against a receiver that DOES declare it."
+            )
+        return [], f"receiver refused: {err}{hint}"
+    rows = inner.get("tasks", [])
+    if not isinstance(rows, list):
+        return [], "malformed response (tasks is not a list)"
+    # tasks:everywhere answers "workspaces I BELONG TO" — assignment/follow/ownership. A key
+    # whose actor belongs to nothing (the MCP bootstrap agent is one) gets ok:true and an
+    # empty list while the operator's own board is full. That green-empty read is worse than
+    # a refusal: it is indistinguishable from "no work queued", and it is exactly how the
+    # ranker ran file-only for months. So an empty answer is not accepted as the final word —
+    # fall back to the WORKSPACE BOARD read, which is what /u/<slug>/tasks and the MCP
+    # tasks_list tool both make (GET /api/things?type=task&workspace=…). Verified 2026-07-26:
+    # everywhere → 0 rows, board → 11.
+    if not rows:
+        board, why = fetch_workspace_board(timeout=timeout)
+        if board:
+            return board, ""
+        if why:
+            return [], f"everywhere empty; board read also failed ({why})"
+    return rows, ""
+
+
+def fetch_workspace_board(timeout=None, workspace=None):
+    """The workspace board — every task on it, not just what this actor subscribes to.
+
+    Same read the /u/<slug>/tasks page and the MCP tasks_list tool make. Returns
+    (rows, reason) on the same contract as fetch_tasks_everywhere: no silent returns."""
+    if timeout is None:
+        timeout = float(os.environ.get("DO_RANK_BOARD_TIMEOUT", "25"))
+    secret = _gateway_key()
+    if not secret:
+        return [], "no world key"
+    ws = workspace or os.environ.get("CC_TASKS_WORKSPACE", "one")
+    base = os.environ.get("DO_SIGNAL_URL", "https://one.ie")
+    q = urllib.parse.urlencode({"type": "task", "workspace": ws, "status": "open", "limit": 200})
+    req = urllib.request.Request(
+        f"{base}/api/things?{q}", method="GET",
+        headers={
+            "Authorization": f"Bearer {secret}",
+            # Cloudflare 403s the default urllib UA before the Worker runs.
+            "User-Agent": "one-do-rank/1.0 (+https://one.ie)",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            payload = json.loads(r.read().decode())
+    except urllib.error.HTTPError as e:
+        return [], f"HTTP {e.code}"
+    except Exception as e:
+        return [], f"unreachable ({type(e).__name__})"
+    rows = payload.get("things") if isinstance(payload, dict) else None
+    if not isinstance(rows, list):
+        return [], "malformed response (things is not a list)"
+    return rows, ""
+
+
+def board_task_entry(row):
+    """Shape one tasks:everywhere row as a plan-like dict — the same keys tasks_view()/
+    tasks_seed() already read off a local todo's `plans[slug]` entry, so a board-created
+    task renders in the SAME ranked list with no second code path."""
+    tags = [t for t in (row.get("tags") or []) if not t.startswith(("workspace:", "@"))]
+    slug_tag = next((t[len("slug:"):] for t in tags if t.startswith("slug:")), "")
+    slug = slug_tag or str(row.get("id", "")).split(":", 1)[-1]
+    dept = classify_dept(slug, {"title": row.get("name", ""), "tags": tags})
+    weight = row.get("weight")
+    weight = max(1, min(100, round(weight))) if isinstance(weight, (int, float)) else 50
+    return {
+        "slug": slug, "title": row.get("name", slug), "outcome_asserts": "",
+        "tier": "?", "tags": tags, "priority": row.get("priority", 0) or 0,
+        "depends_on": [], "done_boxes": 0, "total_boxes": 0, "is_done": False,
+        "gated": False, "strategic": 0, "proximity": 0.0, "momentum": 0.0,
+        "_dirs": [], "cycles": [], "dept": dept, "leverage": 0,
+        "weight": weight, "waiting_on": [], "_board_origin": True,
+    }
+
+
+def merge_board_tasks(active, plans):
+    """Merge tasks:everywhere rows into the local `active` list. A board row carrying a
+    `slug:` tag that matches a local todo file is authoritative — the local file entry is
+    dropped (task-paths.json becomes a cache, not a second source of truth); a row with no
+    local match is a pure board-created task and is simply added. Empty/failed fetch is a
+    no-op — file-only ranking, unchanged."""
+    rows, reason = fetch_tasks_everywhere()
+    if not rows:
+        why = reason or "board is empty (0 open tasks)"
+        print(f"[do-rank] tasks:everywhere: 0 rows — {why} — file-only fallback", file=sys.stderr)
+        return active
+    board_entries = [board_task_entry(r) for r in rows]
+    matched_slugs = {e["slug"] for e in board_entries if e["slug"] in plans}
+    print(f"[do-rank] tasks:everywhere: merged {len(board_entries)} row(s), "
+          f"{len(matched_slugs)} superseding a local todo", file=sys.stderr)
+    return [p for p in active if p["slug"] not in matched_slugs] + board_entries
+
+
 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."""
@@ -282,6 +576,11 @@ def tasks_seed(active):
                 "tid": f"task:{p['slug']}",
                 "thingType": "task",
                 "name": p["title"] or p["slug"],
+                # context = what the task IS + which docs load it, so an agent (or a
+                # human) that picks it up knows the goal and where to read. notes →
+                # thing.notes (prose); contextDocs → thing.task-context (doc stems).
+                "notes": task_context_for(p)[0],
+                "contextDocs": task_context_for(p)[1],
                 "tag": _task_tags(p),
                 "taskStatus": "blocked" if p.get("waiting_on") else "open",
                 "taskPriority": round(p["priority"] / 3, 2),
@@ -305,7 +604,7 @@ def tasks_seed(active):
             "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.",
+            "note": "tasks:* receivers are LIVE (one.ie/web/src/lib/resolvers/tasks.ts) — create/claim/status/link/launch and the announce fan-out. This seed is the bulk-load shape; weights here are what a stake moves.",
         },
     }
 
@@ -343,7 +642,11 @@ def parse_frontmatter(text):
     if not m:
         return fm
     body = m.group(1)
-    for key in ("title", "tier", "mode", "priority"):
+    # outcome_asserts is a single-line quoted string that describes what "done" looks
+    # like in the reader's language — the richest one-line description a task can carry.
+    # Pulled here (not just title/tier/mode/priority) so tasks_seed can hand an agent
+    # real context: what the task IS, not just its name. See § "context on task".
+    for key in ("title", "tier", "mode", "priority", "outcome_asserts"):
         km = re.search(rf"^{key}:\s*(.+)$", body, re.MULTILINE)
         if km:
             val = km.group(1)
@@ -599,15 +902,22 @@ def load_task_paths():
 
 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:
+    learnings momentum so scoring is unchanged. Strength has three writers, all 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)."""
+      • `prod.strength`/`prod.resistance` — production outcomes pulled in by
+        outcome-pull.ts (text/self-improving-outcome.md): a settled promise, a /do
+        cycle that really closed in a live workspace, or a graded delivery. Full
+        overwrite per pull, never accumulated — see outcome-pull.ts's merge law.
+    net = closed + strength − resistance + prod.strength − prod.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)))
+    prod = e.get("prod") or {}
+    net = max(0.0, float(e.get("closed", 0)) + float(e.get("strength", 0)) - float(e.get("resistance", 0))
+              + float(prod.get("strength", 0)) - float(prod.get("resistance", 0)))
     return round(min(3.0, net / 2.0), 2)
 
 
@@ -684,6 +994,100 @@ def momentum_score(slug, log, ref):
     return round(min(3.0, score), 2)
 
 
+# The eight-field close-line vector (text/rubrics.md § Code Rubric — eight dimensions).
+# Fixed field order, self-labeling short codes → the full dimension name do-rank prints.
+DIM_FIELDS = [
+    ("sec", "security"),
+    ("simp", "simplicity"),
+    ("struct", "structure"),
+    ("speed", "speed"),
+    ("integ", "integration"),
+    ("reuse", "code-reuse"),
+    ("test", "test-coverage"),
+    ("ux", "ux"),
+]
+_VECTOR_RE = re.compile(
+    r"\[sec(\d*\.\d+)\s+simp(\d*\.\d+)\s+struct(\d*\.\d+)\s+speed(\d*\.\d+)\s+"
+    r"integ(\d*\.\d+)\s+reuse(\d*\.\d+)\s+test(\d*\.\d+)\s+ux(\d*\.\d+)\]"
+)
+
+
+def parse_vector(line):
+    """The eight-field close-line vector, if present: {dim_name: float}. None for a
+    close-line with no vector (every close before the self-improving-ratchet plan —
+    back-compat: those still count toward the composite trend only)."""
+    m = _VECTOR_RE.search(line)
+    if not m:
+        return None
+    return {name: float(v) for (_short, name), v in zip(DIM_FIELDS, m.groups())}
+
+
+def trailing_median(values):
+    """Median of a list of floats; 0.0 for an empty list (no prior closes yet)."""
+    if not values:
+        return 0.0
+    s = sorted(values)
+    n = len(s)
+    mid = n // 2
+    return s[mid] if n % 2 else round((s[mid - 1] + s[mid]) / 2.0, 4)
+
+
+def _slope(points):
+    """Least-squares slope of value-over-day-offset. 0.0 with fewer than 2 points
+    (insufficient data to trend — printed as flat, not a false rising/slipping)."""
+    n = len(points)
+    if n < 2:
+        return 0.0
+    xs = [p[0] for p in points]
+    ys = [p[1] for p in points]
+    mx = sum(xs) / n
+    my = sum(ys) / n
+    num = sum((x - mx) * (y - my) for x, y in zip(xs, ys))
+    den = sum((x - mx) ** 2 for x in xs)
+    return round(num / den, 4) if den else 0.0
+
+
+def ratchet_trend(log, ref, window_days=30):
+    """Per-dimension trend over the momentum module's own recency window — reuses
+    load_learnings_log's ledger, no second parser. Returns (dims, composite):
+      dims      — [(short, name, last_value|None, slope, 'rising'|'flat'|'slipping'), ...]
+                  in DIM_FIELDS order; last_value is None until the first vectored close.
+      composite — (last_composite|None, trailing_median, 'rising'|'flat'|'slipping') —
+                  the gate C3 reads: composite-ratchet = composite ≥ max(0.65, median).
+    """
+    if ref is None:
+        return [], (None, None, "flat")
+
+    window = [(d, rub, parse_vector(ln)) for d, rub, ln in log if (ref - d).days < window_days]
+    window.sort(key=lambda t: t[0])  # oldest → newest, so slope reads left-to-right in time
+    composites = [rub for _d, rub, _v in window if rub is not None]
+    vectored = [(d, rub, v) for d, rub, v in window if v is not None]
+
+    dims = []
+    for short, name in DIM_FIELDS:
+        if not vectored:
+            dims.append((short, name, None, 0.0, "flat"))
+            continue
+        origin = vectored[0][0]
+        pts = [((d - origin).days, v[name]) for d, _rub, v in vectored]
+        slope = _slope(pts)
+        last_val = pts[-1][1]
+        label = "rising" if slope > 0.01 else "slipping" if slope < -0.01 else "flat"
+        dims.append((short, name, last_val, slope, label))
+
+    last_composite = vectored[-1][1] if vectored else (composites[-1] if composites else None)
+    median = trailing_median(composites)
+    if last_composite is None or not composites:
+        direction = "flat"
+    elif last_composite > median:
+        direction = "rising"
+    elif last_composite < median:
+        direction = "slipping"
+    else:
+        direction = "flat"
+    return dims, (last_composite, median, direction)
+
+
 def selftest():
     """Lock the three bugs found building the momentum gate. Pure, no mocks,
     real learnings-shaped strings. Run: do-rank.py --selftest"""
@@ -736,6 +1140,18 @@ def selftest():
     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))
+    # text/ file granularity — two plans' docs must NOT collapse to one `text` lock.
+    fm_t1 = "deliverables:\n  - doc: text/alpha-docs.md — x\n"
+    fm_t2 = "deliverables:\n  - doc: text/beta-docs.md — x\n"
+    check("dirs: text/ keeps the filename",
+          "text/alpha-docs.md" in deliverable_dirs(fm_t1))
+    check("dirs: text/ does not collapse to the bare dir",
+          "text" not in deliverable_dirs(fm_t1))
+    check("dirs: two text/ docs are disjoint",
+          not (deliverable_dirs(fm_t1) & deliverable_dirs(fm_t2)))
+    # RED half — the old behaviour must be genuinely gone, not merely untested.
+    check("dirs: text/ nested path still uses its containing dir",
+          "text/world" in deliverable_dirs("deliverables:\n  - doc: text/world/homepage-text.md — x\n"))
 
     # 6. transitive leverage: a→b→c chain ⇒ a has 2 dependents (b and c), not 1.
     direct = {"a": {"b"}, "b": {"c"}, "c": set()}
@@ -791,15 +1207,65 @@ def selftest():
     check("gated: empty build_gate value ⇒ not gated (needs a reason)",
           is_gated('---\ntitle: x\nbuild_gate:\n---\nbody') is False)
 
+    # 12. ratchet-trend (C2): per-dimension rising/flat/slipping from vectored closes,
+    # plus composite-vs-trailing-median direction. Pure synthetic vectors, deterministic —
+    # security climbs .70→.80→.90 (rising), speed falls .70→.60→.50 (slipping), simplicity
+    # holds flat at .70 throughout.
+    rlog = [
+        (date(2026, 6, 1), 0.70,
+         "- 2026-06-01 · x · c · a [sec.70 simp.70 struct.70 speed.70 integ.70 reuse.70 test.70 ux.70]"),
+        (date(2026, 6, 10), 0.75,
+         "- 2026-06-10 · x · c · b [sec.80 simp.70 struct.70 speed.60 integ.70 reuse.70 test.70 ux.70]"),
+        (date(2026, 6, 19), 0.85,
+         "- 2026-06-19 · x · c · c [sec.90 simp.70 struct.70 speed.50 integ.70 reuse.70 test.70 ux.70]"),
+    ]
+    rdims, (rcomp, rmed, rdir) = ratchet_trend(rlog, date(2026, 6, 19))
+    rd = {name: (label, slope) for _short, name, _val, slope, label in rdims}
+    check("ratchet: security rising", rd["security"][0] == "rising" and rd["security"][1] > 0)
+    check("ratchet: speed slipping", rd["speed"][0] == "slipping" and rd["speed"][1] < 0)
+    check("ratchet: simplicity flat (no change)", rd["simplicity"][0] == "flat")
+    check("ratchet: composite above trailing median ⇒ rising", rcomp == 0.85 and rdir == "rising")
+    check("ratchet: no closes ⇒ empty dims, no crash", ratchet_trend([], None)[0] == [])
+    check("ratchet: parse_vector back-compat (no vector ⇒ None)",
+          parse_vector("- 2026-06-01 · x · c · plain rubric=0.80") is None)
+
+    # 13. outcome-weight (self-improving-outcome): path_momentum() folds prod.strength/
+    # prod.resistance in alongside closed/live — a slug the world MARKED (prod.strength)
+    # ranks strictly above an identical slug the world WARNED (prod.resistance), same
+    # closed/local strength/resistance otherwise. Load-bearing assertion, not a label
+    # grep — this is the exact trap this family already hit once (a green string with no
+    # real check behind it). See text/self-improving-outcome-plan.md § Pre-mortem.
+    marked_paths = {"task:x": {"closed": 1.0, "strength": 0.0, "resistance": 0.0,
+                                "prod": {"strength": 2.0, "resistance": 0.0}}}
+    warned_paths = {"task:x": {"closed": 1.0, "strength": 0.0, "resistance": 0.0,
+                                "prod": {"strength": 0.0, "resistance": 2.0}}}
+    check("outcome-weight: prod.strength raises momentum above an identical warned slug",
+          path_momentum("x", marked_paths) > path_momentum("x", warned_paths))
+    check("outcome-weight: no prod key ⇒ unchanged behaviour (back-compat)",
+          path_momentum("x", {"task:x": {"closed": 1.0, "strength": 0.0, "resistance": 0.0}}) == 0.5)
+
+    # 14. provenance (self-improving-outcome): --trails' NET calc surfaces prod+/prod-
+    # separately from closed/live/resist, so the operator can see WHY a rank moved (world
+    # vs. local). Exercise the same arithmetic --trails prints, not just path_momentum.
+    prov_entry = {"closed": 0.0, "strength": 0.0, "resistance": 0.0,
+                  "prod": {"strength": 1.5, "resistance": 0.4}}
+    prov_prod = prov_entry.get("prod") or {}
+    prov_net = round(float(prov_entry.get("closed", 0)) + float(prov_entry.get("strength", 0))
+                      - float(prov_entry.get("resistance", 0))
+                      + float(prov_prod.get("strength", 0)) - float(prov_prod.get("resistance", 0)), 2)
+    check("provenance: --trails NET includes prod+/prod- terms", prov_net == 1.1)
+    check("provenance: prod+/prod- readable independent of closed/live/resist",
+          float(prov_prod.get("strength", 0)) == 1.5 and float(prov_prod.get("resistance", 0)) == 0.4)
+
     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 · "
+    print("SELFTEST: 45/45 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)")
+          "gated-exclusion · ratchet-trend · outcome-weight · provenance)")
 
 
 def main():
@@ -808,6 +1274,7 @@ def main():
     toxic_report = "--toxic" in args
     tasks_human = "--tasks" in args
     tasks_seed_out = "--tasks-json" in args
+    task_context_out = "--task-context-json" in args  # backfill source: context for ALL plans
     top_n = None
     if "--top" in args:
         i = args.index("--top")
@@ -815,6 +1282,24 @@ def main():
     if "--selftest" in args:
         return selftest()
 
+    # `--worktags <slug>` — the plan's task-vocabulary tags (dept + topics), comma-joined,
+    # one line. do-auto.sh passes these to the cycle-close do-event so the reputation harvest
+    # credits the SAME tag-nodes real tasks carry (text/reputation.md § Slice A). Self-contained
+    # (one frontmatter read) so the emit stays cheap.
+    if "--worktags" in args:
+        i = args.index("--worktags")
+        slug = args[i + 1] if i + 1 < len(args) else ""
+        f = TEXT / f"{slug}-todo.md"
+        if not f.exists():
+            f = TEXT / f"{slug}-plan.md"
+        tags = []
+        if f.exists():
+            fm = parse_frontmatter(f.read_text(errors="ignore"))
+            dept = classify_dept(slug, {"title": fm.get("title", ""), "tags": fm.get("tags", [])})
+            tags = _task_tags({"dept": dept, "tags": fm.get("tags", [])})
+        print(",".join(t for t in tags if t))
+        return
+
     # `--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.
@@ -827,6 +1312,21 @@ def main():
                 print(d)
         return
 
+    # `--board-check` — the one failure mode source-greps cannot catch. do-tasks-wire-check.sh
+    # asserts the SHAPE of the board read; this actually performs it. A key that doesn't match
+    # the deployed worker's GATEWAY_API_KEY passes every static check and still leaves the
+    # ranker file-only forever — which is exactly how the original break hid for months.
+    # Deliberately NOT part of any promise `proof:` (a contract must not depend on the network);
+    # run it explicitly when the board looks empty.
+    if "--board-check" in args:
+        target = os.environ.get("DO_SIGNAL_URL", "https://one.ie")
+        rows, reason = fetch_tasks_everywhere()
+        if reason:
+            print(f"[board-check] RED — {target}: {reason}", file=sys.stderr)
+            return 1
+        print(f"[board-check] OK — {target}: {len(rows)} open task(s) readable")
+        return 0
+
     # `--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.
@@ -868,8 +1368,11 @@ def main():
         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.
+    # store. A trail = accumulated path strength (closes + live marks + prod outcomes)
+    # minus resistance. Strong trails are highways the next pick follows; resistance-
+    # heavy ones are fading. `prod+`/`prod-` (self-improving-outcome) show provenance —
+    # what production confirmed, separate from local closes/marks — so the operator can
+    # tell WHY a rank moved, not just that it did.
     if "--trails" in args:
         paths = load_task_paths()
         rows = []
@@ -877,21 +1380,25 @@ def main():
             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))))
+            prod = e.get("prod") or {}
+            prod_strength = float(prod.get("strength", 0))
+            prod_resistance = float(prod.get("resistance", 0))
+            net = round(closed + strength - resistance + prod_strength - prod_resistance, 2)
+            rows.append((net, key, closed, strength, resistance, int(e.get("traversals", 0)), prod_strength, prod_resistance))
         rows.sort(reverse=True)
-        print("\n  TRAILS — paths the loop has worn (weighed by outcome · close + live mark − resistance)\n")
+        print("\n  TRAILS — paths the loop has worn (weighed by outcome · close + live mark + prod − 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]:
+        print(f"  {'NET':>5}  {'closed':>6} {'live':>5} {'resist':>6} {'×':>4} {'prod+':>5} {'prod-':>5}  TRAIL")
+        print(f"  {'-'*5}  {'-'*6} {'-'*5} {'-'*6} {'-'*4} {'-'*5} {'-'*5}  {'-'*30}")
+        for net, key, c, s, r, tv, ps, pr in rows[:25]:
             band = "🛣 highway" if net >= 4 else "· trail" if net >= 2 else "  forming"
-            if r > c + s:
+            if r + pr > c + s + ps:
                 band = "✗ fading"
-            print(f"  {net:>5.1f}  {c:>6.1f} {s:>5.1f} {r:>6.1f} {tv:>4}  {key:<26} {band}")
+            print(f"  {net:>5.1f}  {c:>6.1f} {s:>5.1f} {r:>6.1f} {tv:>4} {ps:>5.1f} {pr:>5.1f}  {key:<26} {band}")
         print(f"\n  {len(rows)} trail(s). A close → --sync-closes wears it deeper; warn/--fail lets it fade.")
+        print(f"  prod+/prod- come from outcome-pull.ts (production D1, session-cadence) — provenance, never local.")
         print(f"  These are the task-layer trails (text/task-paths.json); the substrate trail is claw_paths/path.strength.\n")
         return
 
@@ -943,6 +1450,80 @@ def main():
               f"the migration target (not wired this cycle).\n")
         return
 
+    # `--ratchet` (C2, self-improving-ratchet) — read-only projection: each of the eight
+    # rubric dimensions' 30-day trend (rising/flat/slipping), reusing load_learnings_log +
+    # the momentum recency window. Composite vs its trailing median is the number C3's W4
+    # gate reads (composite-ratchet: composite ≥ max(0.65, median)) — this prints it, the
+    # gate (C3) enforces it. Answers "are we getting better?" as a command, not a vibe.
+    if "--ratchet" in args:
+        rlog, rref = load_learnings_log()
+        dims, (last_composite, median, direction) = ratchet_trend(rlog, rref)
+        n_vectored = sum(1 for _d, _r, ln in rlog if parse_vector(ln) is not None)
+        print(f"\n  RATCHET — eight dimensions (30-day trend, n={n_vectored} vectored close(s))\n")
+        if n_vectored == 0:
+            print("  no vectored closes yet — the eight-field vector starts accumulating from")
+            print("  the first close-line carrying `[sec.. simp.. …]` (text/rubrics.md § the")
+            print("  close-line vector). Composite-only trend is not shown here — use the")
+            print("  existing momentum/toxic reports for that.\n")
+            return
+        arrow = {"rising": "▲", "flat": "▬", "slipping": "▼"}
+        for short, name, last_val, slope, label in dims:
+            val_s = f"{last_val:.2f}" if last_val is not None else " n/a"
+            warn_s = "  ⚠ warn" if label == "slipping" else ""
+            print(f"    {name:<13} {arrow[label]} {label:<9} {val_s}  ({slope:+.2f}){warn_s}")
+        comp_s = f"{last_composite:.2f}" if last_composite is not None else "n/a"
+        med_s = f"{median:.2f}" if median else "n/a"
+        print(f"\n  composite {comp_s}  {arrow.get(direction, '▬')}  "
+              f"(trailing median {med_s} — gate floor; no regression)\n")
+        return
+
+    # `--ratchet-json` (C3 rescope, self-improving-ratchet) — machine-readable sibling of
+    # `--ratchet`: the one source of truth for the trailing numbers so w4-rubric.ts shells
+    # out instead of re-implementing a vector-regex parser in TypeScript. Read-only, no
+    # exit-code contract — safe under any C3 rescope option.
+    if "--ratchet-json" in args:
+        import json as _json
+        rlog, rref = load_learnings_log()
+        dims, (last_composite, median, direction) = ratchet_trend(rlog, rref)
+        n_vectored = sum(1 for _d, _r, ln in rlog if parse_vector(ln) is not None)
+        print(_json.dumps({
+            "last_composite": last_composite,
+            "trailing_median": median,
+            "direction": direction,
+            "n": len(rlog),
+            "n_vectored": n_vectored,
+            "dims": [
+                {"short": short, "name": name, "last_value": last_val, "slope": slope, "label": label}
+                for short, name, last_val, slope, label in dims
+            ],
+        }))
+        return
+
+    # `--ratchet-dry-run` (C3 rescope calibration receipt) — replays every close against
+    # the trailing median of ITS OWN priors (not the current median), and counts how many
+    # would fail a strict `composite ≥ median-of-priors` gate. This is the number the W2
+    # escape check argued from prose; this prints it from the real ledger so the author's
+    # rescope decision (warn vs block vs rewrite-the-escape) is made on a receipt, not an
+    # estimate. Never touches an exit code.
+    if "--ratchet-dry-run" in args:
+        rlog, _rref = load_learnings_log()
+        chron = sorted(((d, rub) for d, rub, _ln in rlog if rub is not None), key=lambda t: t[0])
+        reblocked = []
+        for i, (d, rub) in enumerate(chron):
+            priors = [r for _d, r in chron[:i]]
+            if len(priors) < 2:
+                continue
+            med = trailing_median(priors)
+            if rub < med:
+                reblocked.append((d, rub, med))
+        print(f"\n  RATCHET DRY-RUN — {len(chron)} composite-bearing close(s), "
+              f"{len(reblocked)} would fail composite ≥ median-of-priors\n")
+        for d, rub, med in reblocked[-15:]:
+            print(f"    {d}  composite={rub:.2f}  <  median-of-priors={med:.2f}")
+        print(f"\n  {len(reblocked)}/{len(chron) - 2 if len(chron) > 2 else 0} eligible closes "
+              f"would have been re-blocked by a hard median gate.\n")
+        return
+
     log, ref = load_learnings_log()
     task_paths = load_task_paths()
     plans = {}
@@ -968,6 +1549,7 @@ def main():
         plans[slug] = {
             "slug": slug,
             "title": fm.get("title", ""),
+            "outcome_asserts": fm.get("outcome_asserts", ""),
             "tier": fm.get("tier", "?"),
             "tags": fm.get("tags", []),
             "priority": priority,
@@ -1053,6 +1635,10 @@ def main():
 
     # active = open work (ready + blocked); done AND faded plans are not live tasks.
     active = ready + blocked
+    # C2 — rank FROM tasks:everywhere too: board-created tasks (never a todo file) join
+    # the same list; a substrate row whose slug: tag matches a local plan wins (see
+    # merge_board_tasks docstring). No-op on fetch failure — file-only, unchanged.
+    active = merge_board_tasks(active, plans)
 
     if toxic_report:
         # Read-only report — the `--toxic` deliverable. Nothing is written or deleted;
@@ -1071,6 +1657,16 @@ def main():
     if tasks_seed_out:
         print(json.dumps(tasks_seed(active), indent=2))
         return
+    if task_context_out:
+        # Context for EVERY plan (done/blocked/ready), keyed by tid — the backfill reads
+        # this to add notes + task-context to tasks already seeded into TypeDB (which the
+        # forward `seed-tasks-typedb.ts` skips because they exist). Idempotent by design.
+        contexts = []
+        for p in sorted(plans.values(), key=lambda x: x["slug"]):
+            notes, docs = task_context_for(p)
+            contexts.append({"tid": f"task:{p['slug']}", "notes": notes, "contextDocs": docs})
+        print(json.dumps({"version": "context-backfill-1", "contexts": contexts}, indent=2))
+        return
     if tasks_human:
         print("\n" + "\n".join(tasks_view(active)) + "\n")
         return
@@ -1096,6 +1692,24 @@ def main():
     # Human table
     print(f"\n  PRIORITY QUEUE — {len(ready)} ready · {len(blocked)} blocked · "
           f"{len(faded)} faded · {len(done)} done\n")
+
+    # RATCHET — C4: one compact line surfacing C2's eight-dimension trend so the
+    # operator sees "are we getting better?" at session start without running
+    # --ratchet. Reuses `log`/`ref` (already computed above) + ratchet_trend();
+    # the full 8-row table stays behind --ratchet. Degrades to a "no data" line
+    # (still carrying the word "ratchet") when no vectored closes exist yet.
+    r_dims, (r_comp, r_med, r_dir) = ratchet_trend(log, ref)
+    if r_comp is None:
+        print("  RATCHET  no vectored closes yet — trend starts at the first "
+              "[sec.. simp.. …] close\n")
+    else:
+        r_arrow = {"rising": "▲", "flat": "▬", "slipping": "▼"}.get(r_dir, "▬")
+        n_slip = sum(1 for _sh, _nm, _lv, _sl, label in r_dims if label == "slipping")
+        slip_s = f"  ·  {n_slip} dim(s) slipping ⚠" if n_slip else ""
+        r_med_s = f"{r_med:.2f}" if r_med else "n/a"
+        print(f"  RATCHET  composite {r_comp:.2f} {r_arrow}  "
+              f"(median {r_med_s}){slip_s}\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]:
@@ -1157,4 +1771,6 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    # `or 0` so every path that returns None (the vast majority) still exits 0 — only a
+    # mode that deliberately returns a non-zero int (e.g. --board-check RED) sets a code.
+    sys.exit(main() or 0)