#!/usr/bin/env python3
"""compose.py — leaf-to-root chain composition and subtree renders.

SUPERSEDED FOR REFOCUS: the public core reorientation trace lives at
../../refocusing/scripts/trace-to-root.py. This general composer remains the
compatibility surface for down/progress and historical up invocations.

  up   <start-dir> --name FILE [--name FILE ...] [--root DIR]
       Walk from start-dir up to root (default: filesystem stops at a dir
       containing .compose-root, or at --root). Emit the chain ROOT-FIRST
       (defaults, then overrides) with provenance headers, and a MISSING-LINK
       report for altitudes without the file — the scream is output, not error.

  down <root-dir> --name FILE [--name FILE ...] [--exclude GLOB ...]
       Gather every instance of the named files under root-dir.

  progress <root-dir> --name FILE [--name FILE ...] [--exclude GLOB ...]
       THE DERIVED PROGRESS VIEW (the PROGRESS.md prototype done right):
       count markdown checkboxes in the named files (the mark level), roll
       counts UP the tree, and print a walk-map-shaped tree with done/total
       per level. Never stored in any file — the render is the only home.
       Gather every instance of the named files under root-dir (the subtree
       render; run at the topology root = THE TRUNK RENDER). Sorted by path.

Composed output is GENERATED, NEVER EDITED (fragments are the source of truth).
Seals/locks bind to a render's bytes, not to fragments. Stdlib only.
"""
import argparse, os, sys, fnmatch, datetime, re, shutil, subprocess

# A SHELF holds instances of an altitude; it is not a position and carries no chain file.
# Both trees have them: missions/ slices/ (work) and rigs/ pods/ seats/ (topology). Without
# this list the trace reports every shelf as a gap and the audit tells you to scaffold one —
# which is litter that inflates the map to a clean-looking 5/5 while adding nothing. Extend
# with --shelf for a tree that names them differently.
SHELF_NAMES = {"missions", "slices", "seats", "pods", "rigs"}

_TPL_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "templates")
def _template_bytes(name):
    try:
        return open(os.path.join(_TPL_DIR, name), "rb").read()
    except OSError:
        return None

def read_state(path):
    """Detection is DETERMINISTIC-FIRST, declared-second — never memory-reliant:
    1. byte-identical to the shipped template  -> 'unseeded' (nobody had to remember anything)
    2. `status: UNSEEDED` marker on content that DIFFERS from the template -> 'conflicted':
       render the content AND scream — real work is never hidden behind a stale field,
       and the disagreement is its own reported state (third-state law).
    3. otherwise -> 'seeded'. Every residual failure mode shows too much plus a scream,
       never hides work and never silently trusts a field."""
    raw = open(path, "rb").read()
    tpl = _template_bytes(os.path.basename(path))
    body = raw.decode("utf-8", errors="replace")
    head = "\n".join(body.splitlines()[:15])
    marked = re.search(r"^status:\s*UNSEEDED", head, re.M)
    if tpl is not None and raw == tpl:
        m = re.search(r"^owners?:\s*(.+)$", head, re.M)
        return "unseeded", (m.group(1).strip() if m else "owner unknown — untouched scaffold")
    if marked:
        return "conflicted", body
    return "seeded", body

def hdr(title):
    return f"\n\n<!-- ═══ {title} ═══ -->\n\n## ⟦{title}⟧\n"

def frontmatter(payload):
    """Parse the frontmatter block ONCE. Returns (dict, note); note is set when there is
    nothing to read, so a caller can report the gap rather than silently skip it."""
    if not payload:
        return None, "no content"
    m = re.match(r"^---\n(.*?)\n---\n", payload, re.S)
    if not m:
        return None, "no frontmatter"
    try:
        import yaml
        return (yaml.safe_load(m.group(1)) or {}), None
    except Exception as e:
        return None, f"frontmatter did not parse ({e.__class__.__name__})"

def field_of(payload, field):
    """Extract ONE frontmatter field. Returns (value, note).
    A chain walked by FIELD composes intent without dragging bodies: three sentences
    unfurl, not three documents. A level whose file exists but lacks the field is a
    real gap and is reported as such — never silently skipped."""
    fm, note = frontmatter(payload)
    if fm is None:
        return None, note
    if field not in fm:
        return None, f"no `{field}:` field"
    v = fm[field]
    return (" ".join(str(v).split()) if v is not None else None), None

def _cut_at_boundary(s, n):
    """Cut to at most n characters without splitting a token.

    Prefer paragraph, line, then word boundaries. Drop a single unbroken token
    that exceeds the budget; a partial path or identifier looks valid but is not."""
    if len(s) <= n:
        return s
    head = s[:n]
    if s[n:n + 1].isspace():                 # n already sits on a boundary
        return head.rstrip()
    for sep, floor in (("\n\n", n // 2), ("\n", n // 2), (" ", 0)):
        i = head.rfind(sep)
        if i > floor:
            return head[:i].rstrip()
    return ""                                # one unbroken token — drop it, never cut into it


def _short(s, n=52):
    s = " ".join(str(s).split())
    if len(s) <= n:
        return s
    return _cut_at_boundary(s, n - 1).rstrip(" ,;:.-—") + "…"

_ARTIFACT_KEYS = ("outputs", "output", "artifacts", "artifact")


def dep_artifacts(dep_dir, names, dep_fm):
    """WHAT THE DEPENDENCY HANDS YOU — the file, not the fact that it is done.

    Frontmatter first if the node declares it (`outputs:`/`output:`/`artifacts:`/`artifact:`),
    because a declaration outranks a guess. Otherwise the directory itself: everything beside
    the node file, which for a built slice IS its output (MAP.md, PROOF.md, the script). No
    prose parsing — a `## Output` section is written for humans and reading it would make the
    trace confidently wrong exactly where it is trying to stop being that."""
    for k in _ARTIFACT_KEYS:
        v = (dep_fm or {}).get(k)
        if v:
            return [" ".join(str(x).split()) for x in (v if isinstance(v, list) else [v])], "declared"
    try:
        entries = sorted(os.listdir(dep_dir))
    except OSError:
        return [], "unreadable"
    out = [e + ("/" if os.path.isdir(os.path.join(dep_dir, e)) else "")
           for e in entries if not e.startswith(".") and e not in set(names)]
    return out, "on disk"


def blocking_state(payload, lvl, names):
    """Return leaf status and dependency facts beside its intent, or None.

    Intent alone does not say whether work may start or where dependency outputs
    live. Resolve dependencies on disk and report state, absolute path, and
    artifacts; leave ancestors to carry purpose."""
    fm, _ = frontmatter(payload)
    if not fm:
        return None
    parts = []
    if fm.get("status") is not None:
        parts.append(f"status: {_short(fm['status'], 88)}")
    deps = fm.get("depends")
    if deps:
        shelf = os.path.dirname(lvl)
        lines = ["depends:"]
        for dep in (deps if isinstance(deps, list) else [deps]):
            dep = " ".join(str(dep).split())
            dep_dir = os.path.join(shelf, dep)
            if not os.path.isdir(dep_dir):
                lines.append(f"    {dep} — ⚠ UNRESOLVED: no directory `{dep}` under {shelf}"
                             f" (nothing to point you at — check the id)")
                continue
            state, dfm = None, None
            for n in names:
                cand = os.path.join(dep_dir, n)
                if os.path.isfile(cand):
                    st, body = read_state(cand)
                    dfm = frontmatter(body)[0] if st != "unseeded" else None
                    state = _short((dfm or {}).get("status") or st)
                    break
            lines.append(f"    {dep} ({state})" if state else
                         f"    {dep} (⚠ no {'/'.join(names)} — state unknown)")
            lines.append(f"      path: {os.path.abspath(dep_dir)}")
            arts, how = dep_artifacts(dep_dir, names, dfm)
            if arts:
                shown = arts[:8]
                more = f" (+{len(arts) - 8} more)" if len(arts) > 8 else ""
                lines.append(f"      artifacts ({how}): " + " · ".join(shown) + more)
            else:
                lines.append(f"      artifacts: ⚠ none found — the dependency has produced no"
                             f" output file yet")
        parts.append("\n".join(lines))   # lines 2+ carry their own indent; the caller indents line 1
    return "\n  ".join(parts) or None


def operates_on(payload):
    """Return the roots a work node declares it operates on.

    The tree being walked need not be the tree the work changes. This cannot be
    inferred safely, so render `operates_on` verbatim and omit it when unstated."""
    fm, _ = frontmatter(payload)
    if not fm:
        return None
    roots = fm.get("operates_on")
    if not roots:
        return None
    return [" ".join(str(r).split()) for r in (roots if isinstance(roots, list) else [roots])]


# Preserve contract and scope sections ahead of rationale and history when the
# leaf body exceeds its cap. Unknown headings remain middle priority so new shapes
# degrade without being silently privileged or discarded.
_PRI_CONTRACT = re.compile(
    r"(done when|what done looks like|scope fence|outputs?\b|inputs?\b|depends on|"
    r"what must be built|how we will know|acceptance|payload|deliverable)", re.I)
_PRI_DISCUSSION = re.compile(
    r"^(why\b|the problem|the evidence|the finding|result\b|also\b|related\b|triage\b|"
    r"background\b|history\b|what is already done|new evidence|measured\b|answered\b|"
    r"where this spec was wrong|notes for|the counter-argument|the asset|the mechanism|"
    r"this mission is the acceptance criteria)", re.I)


def _priority(heading):
    """0 = preamble (never dropped) · 1 = contract · 2 = unclassified · 3 = discussion."""
    if heading is None:
        return 0
    if _PRI_CONTRACT.search(heading):
        return 1
    if _PRI_DISCUSSION.match(heading):
        return 3
    return 2


def _sections(body):
    """Split a node body at LEVEL-2 headings into [(heading|None, chunk), ...].

    Chunk 0 is the preamble — the `# Title` and its lede — and carries heading None. `###`
    stays inside its parent section: in these specs it is a sub-step of the section above it,
    and splitting there would let half a section survive its own heading."""
    starts = [m.start() for m in re.finditer(r"^## +.*$", body, re.M)]
    if not starts:
        return [(None, body)]
    out = [(None, body[:starts[0]])]
    for i, s in enumerate(starts):
        chunk = body[s:starts[i + 1] if i + 1 < len(starts) else len(body)]
        out.append((chunk.splitlines()[0].lstrip("# ").strip(), chunk))
    return out


def leaf_body(payload, cap):
    """Render the leaf body, truncating by semantic priority rather than position.

    Ancestors can compose by stable intent fields, but the leaf carries the nouns,
    boundaries, outputs, and completion conditions. When over budget, retain
    contract and scope sections before explanatory history."""
    if not payload:
        return None
    m = re.match(r"^---\n.*?\n---\n", payload, re.S)
    body = (payload[m.end():] if m else payload).strip()
    if not body:
        return None
    if len(body) <= cap:
        return body
    secs = _sections(body)
    if len(secs) == 1:                     # headingless prose — nothing to prioritise
        kept = _cut_at_boundary(body, cap)
        return (kept + "\n\n[… " + str(len(body) - len(kept)) + " more chars, no further "
                "headings — prose tail]" + "\n(read the node file for these)")
    # Drop the lowest-priority, largest sections first to preserve more short,
    # decisive sections. The title and lede preamble are never candidates.
    keep, size = set(range(len(secs))), len(body)
    for i in sorted(range(1, len(secs)), key=lambda i: (-_priority(secs[i][0]), -len(secs[i][1]))):
        if size <= cap:
            break
        keep.discard(i)
        size -= len(secs[i][1])
    kept = "".join(secs[i][1] for i in sorted(keep)).rstrip()
    if len(kept) > cap:                    # preamble alone overflows; cut it safely, never mid-token
        kept = _cut_at_boundary(kept, cap)
    dropped = [secs[i][0] for i in range(1, len(secs)) if i not in keep]
    # Name omitted headings so truncation is visible to the reader.
    tail = ("\n\nOMITTED FROM THIS RENDER — " + str(len(body) - len(kept)) + " chars, sections: "
            + " · ".join(dropped) if dropped else
            "\n\n[… " + str(len(body) - len(kept)) + " more chars, no further headings — prose tail]")
    return kept + tail + "\n(read the node file for these)"


def resolve_roots():
    """Resolve work and topology roots from configuration or explicit environment.

    A library copy may derive topology from its own real path; a projected plugin
    copy must be configured rather than guessing. Resolution follows environment,
    configuration, then derived location."""
    out = {}
    out["work_root"] = os.environ.get("OPENRIG_WORKSPACE_ROOT") or rig_config("workspace.root")

    t = os.environ.get("OPENRIG_TOPOLOGY_ROOT") or rig_config("workspace.topology_root")
    if not t:
        # Resolve symlinks before walking upward; otherwise a projection ascends
        # its own tree rather than the shared-docs source.
        here = os.path.realpath(__file__)
        for _ in range(6):                       # scripts/ skill/ skills/ skill-canon/ -> shared-docs/
            here = os.path.dirname(here)
            cand = os.path.join(here, "rigs")
            if os.path.isdir(cand):
                t = cand
                break
    out["topology_root"] = t
    return out


def rig_config(key):
    if not shutil.which("rig"):
        return None
    try:
        p = subprocess.run(["rig", "config", "get", key], capture_output=True, text=True, timeout=10)
        v = (p.stdout or "").strip()
        return v if p.returncode == 0 and v else None
    except Exception:
        return None


def compose_up(start, names, root, field=None, prefer=False, shelves=None, leaf_cap=2400):
    shelves = SHELF_NAMES | set(shelves or ())
    start = os.path.abspath(start); root = os.path.abspath(root) if root else None
    levels = []
    d = start
    while True:
        levels.append(d)
        if root and os.path.samefile(d, root): break
        if not root and os.path.exists(os.path.join(d, ".compose-root")): break
        parent = os.path.dirname(d)
        if parent == d: break
        d = parent
    levels.reverse()  # root first: defaults, then overrides
    out = [f"<!-- GENERATED by compose.py up · {datetime.datetime.now().isoformat(timespec='minutes')} -->",
           f"<!-- start: {start} · altitudes: {sum(1 for d in levels if os.path.basename(d) not in shelves)} ({len(levels)} path segments) · chains: {', '.join(names)}" + (f" · FIELD: {field}" if field else "") + " -->",
           "<!-- Composed view — never edit; edit the fragments. -->"]
    GLYPH = {"seeded": "✓ seeded", "unseeded": "⟂ UNSEEDED", "conflicted": "⚠ stale marker",
             "absent": "✗ absent", "shelf": "· shelf"}
    missing, unseeded = [], []
    # --prefer turns the --name list into ONE chain resolved per level by precedence
    # (first match wins) instead of N independent chains. A tree mid-rename is the normal
    # case, not an exception: SPEC.md is the current node filename and README.md the legacy
    # one, and a trace that cannot span both reports a chain as broken when it is merely mixed.
    # Validate the start node against configured tree roots. Merely sitting below
    # workspace.root is insufficient because fixtures may look structurally valid.
    _cfg = [c for c in (rig_config("workspace.slices_root"),
                        resolve_roots().get("topology_root")) if c]
    _here = os.path.abspath(start)
    _root_warning = None
    if _cfg and not any(_here == os.path.abspath(c) or _here.startswith(os.path.abspath(c) + os.sep)
                        for c in _cfg):
        _root_warning = ("  ⚠ THIS IS NOT A CONFIGURED TREE. Trees on this instance: "
                         + " · ".join(_cfg) + "\n    A walk renders just as cleanly from a stray or"
                         " fixture tree — verify before acting on it.")
    groups = [list(names)] if prefer else [[n] for n in names]
    for group in groups:
        name = group[0]
        out.append(f"\n\n# CHAIN: {' → '.join(group)} (root → leaf)"
                   + (" · precedence: first match wins per level" if len(group) > 1 else ""))
        # pass 1 — collect the state of every level (this IS the trace; the map derives from it)
        chain, hits = [], {}
        for lvl in levels:
            p = None
            for n in group:
                cand = os.path.join(lvl, n)
                if os.path.isfile(cand):
                    p, hits[lvl] = cand, n
                    break
            where = os.path.relpath(lvl, levels[0]) or '.'
            # A SHELF is a path segment, not an altitude. The chain has three rungs — project,
            # mission, slice — and rendering `missions/` and `slices/` as rungs implies five.
            # Any file living at a shelf is ordinary folder documentation, NOT a chain link:
            # ignore it rather than flagging it. `README.md` does double duty as a legacy node
            # name and as a plain readme, and only the level it sits at can tell them apart.
            is_shelf = os.path.basename(lvl) in shelves
            if is_shelf:
                state, payload, p = "shelf", None, None
                hits.pop(lvl, None)
            elif p:
                state, payload = read_state(p)
            else:
                state, payload = "absent", None
            # Resolve the field HERE so the map can tell the truth. A map keyed on file
            # presence says ✓ for a level that composes nothing — the exact reading that
            # lets a trace certify the drift it exists to catch.
            fval, fnote = (field_of(payload, field) if (field and state == "seeded") else (None, None))
            chain.append((lvl, where, state, payload, fval, fnote))
        # TRACE — derived orientation tree (never stored in files; the render is the only home)
        # The map shows ALTITUDES as rungs; shelves fold into the next rung's path so the tree
        # depth equals the number of levels that actually carry intent.
        rungs, pending = [], []
        for idx, row in enumerate(chain):
            if row[2] == "shelf" and idx != len(chain) - 1:
                pending.append(os.path.basename(row[0]) or row[0])
                continue
            label = "/".join(pending + [os.path.basename(row[0]) or row[0]])
            rungs.append((label, row)); pending = []
        leads = [("" if i == 0 else "   " * (i - 1) + "└─ ") + rungs[i][0] + "/" for i in range(len(rungs))]
        width = max(len(l) for l in leads) + 2
        # Name the walked root and chain so readers do not confuse the tree being
        # shown with the tree the work will change.
        out.append(f"\nTRACE · root {levels[0]} · chain {' → '.join(group)}")
        # Warn on an unconfigured root: an arbitrary lookalike tree can render a
        # clean chain.
        if _root_warning:
            out.append(_root_warning)
        for i, (_label, (lvl, where, state, payload, fval, fnote)) in enumerate(rungs):
            note = f" (owner: {payload})" if state == "unseeded" and payload else ""
            here = "   ← you are here" if i == len(rungs) - 1 else ""
            glyph = f"⟂ no {field}" if (field and state == "seeded" and not fval) else GLYPH[state]
            # In precedence mode, name WHICH file answered at each level — a mixed tree is
            # readable state, not noise, and hiding it is how a rename looks like corruption.
            via = f" [{hits[lvl]}]" if len(group) > 1 and lvl in hits and state != "shelf" else ""
            out.append(f"  {leads[i]:<{width}}{glyph}{via}{note}{here}")
        # pass 2 — contents, states collapsed per the three-state rules
        found = 0
        for lvl, where, state, payload, fval, fnote in chain:
            if state == "shelf":
                continue          # a path segment, not a position — contributes nothing, flags nothing
            elif state == "unseeded":
                out.append(f"\n⟂ {name} @ {where} — UNSEEDED (scaffold only, not rendered; seed it: {payload})")
                unseeded.append(f"{name} @ {where} (owner: {payload})")
            elif state == "conflicted":
                found += 1
                out.append(hdr(f"{name} @ {where} — ⚠ carries status: UNSEEDED but content differs from template"))
                out.append(payload.rstrip())
                unseeded.append(f"{name} @ {where} — MARKER/CONTENT DISAGREE: rendered anyway; owner should clear the stale status line")
            elif state == "seeded":
                found += 1
                if field:
                    if fval:
                        out.append(f"\n{where}:  {fval}")
                    else:
                        out.append(f"\n{where}:  ⚠ {fnote}")
                        unseeded.append(f"{name} @ {where} — {fnote}")
                    # The leaf is the only level whose answer is an ACTION. Compose its
                    # blocking state here or the walk certifies the next step it never read.
                    if lvl == chain[-1][0]:
                        blocked = blocking_state(payload, lvl, group)
                        if blocked:
                            out.append(f"  {blocked}")
                        roots = operates_on(payload)
                        if roots:
                            out.append("  operates on: " + " · ".join(roots))
                        # ...and the only altitude that SPECIFIES. See leaf_body().
                        lb = leaf_body(payload, leaf_cap) if leaf_cap else None
                        if lb:
                            out.append(f"\n─── {where} · node body ───")
                            out.append(lb)
                else:
                    out.append(hdr(f"{name} @ {where}"))
                    out.append(payload.rstrip())
            else:
                missing.append(f"{name} @ {where}")
        if not found:
            out.append(f"\n⚠ NO seeded instances of {name} on this walk.")
    if unseeded or missing:
        out.append("\n\n# ⚠ CHAIN AUDIT (the walk screams once, here — never by breaking, never by template litter)")
        if unseeded:
            out.append("UNSEEDED (file exists, template only — the owner writes the first true version):")
            out += [f"- {m}" for m in unseeded]
        if missing:
            out.append("ABSENT (no file at a POSITION — scaffold it, or report to the level owner if absence looks wrong):")
            out += [f"- {m}" for m in missing]
    return "\n".join(out)

def compose_down(root, names, excludes):
    root = os.path.abspath(root)
    hits = []
    for dirpath, dirs, files in os.walk(root):
        dirs[:] = [x for x in dirs if not x.startswith(".") and x != "node_modules"
                   and not any(fnmatch.fnmatch(os.path.join(dirpath, x), g) for g in excludes)]
        for name in names:
            if name in files:
                hits.append(os.path.join(dirpath, name))
    hits.sort()
    out = [f"<!-- GENERATED by compose.py down · {datetime.datetime.now().isoformat(timespec='minutes')} -->",
           f"<!-- root: {root} · files: {len(hits)} · chains: {', '.join(names)} -->",
           "<!-- Subtree render (trunk render at a tree root). Never edit. -->"]
    unseeded = []
    for p in hits:
        state, payload = read_state(p)
        rel = os.path.relpath(p, root)
        if state == "unseeded":
            unseeded.append(f"{rel} (owner: {payload})")
        elif state == "conflicted":
            out.append(hdr(f"{rel} — ⚠ stale UNSEEDED marker on real content"))
            out.append(payload.rstrip())
            unseeded.append(f"{rel} — MARKER/CONTENT DISAGREE: rendered anyway; clear the stale status line")
        else:
            out.append(hdr(rel))
            out.append(payload.rstrip())
    if unseeded:
        out.append("\n\n# ⚠ UNSEEDED under this root (scaffold only — collapsed, not rendered)")
        out += [f"- {u}" for u in unseeded]
    if not hits:
        out.append("\n⚠ no chain files under this root — unfurl first?")
    return "\n".join(out)

def compose_progress(root, names, excludes):
    import collections
    root = os.path.abspath(root)
    direct = collections.defaultdict(lambda: [0, 0])   # dir -> [done, total] from its own files
    for dirpath, dirs, files in os.walk(root):
        dirs[:] = [x for x in dirs if not x.startswith(".") and x != "node_modules"
                   and not any(fnmatch.fnmatch(os.path.join(dirpath, x), g) for g in excludes)]
        for name in names:
            if name in files:
                txt = open(os.path.join(dirpath, name), encoding="utf-8", errors="replace").read()
                done = len(re.findall(r"^\s*[-*] \[[xX]\]", txt, re.M))
                open_ = len(re.findall(r"^\s*[-*] \[ \]", txt, re.M))
                if done + open_:
                    direct[dirpath][0] += done
                    direct[dirpath][1] += done + open_
    agg = collections.defaultdict(lambda: [0, 0])       # dir -> rolled-up [done, total]
    for d, (dn, tt) in direct.items():
        cur = d
        while True:
            agg[cur][0] += dn; agg[cur][1] += tt
            if os.path.samefile(cur, root): break
            cur = os.path.dirname(cur)
    out = [f"<!-- GENERATED by compose.py progress · {datetime.datetime.now().isoformat(timespec='minutes')} -->",
           "<!-- Derived from the mark level at render time. Never store this in a file. -->",
           f"\nPROGRESS MAP ({', '.join(names)} — checkbox = the one mark level; everything above derives):"]
    if not agg:
        out.append("  (no checkboxes found in the named files under this root — nothing is marked here)")
        return "\n".join(out)
    keys = sorted(agg, key=lambda d: os.path.relpath(d, root))
    leads = []
    for d in keys:
        rel = os.path.relpath(d, root)
        depth = 0 if rel == "." else rel.count(os.sep) + 1
        label = os.path.basename(root) if rel == "." else os.path.basename(d)
        leads.append(("" if depth == 0 else "   " * (depth - 1) + "└─ ") + label)
    width = max(len(l) for l in leads) + 2
    for i, d in enumerate(keys):
        dn, tt = agg[d]
        pct = 100 * dn // tt if tt else 0
        glyph = "✓" if dn == tt else ("◐" if dn else "○")
        own = " ·" if d in direct else "  "   # · = has marks of its own (vs pure roll-up)
        out.append(f"  {leads[i]:<{width}}{glyph} {dn}/{tt} ({pct}%){own}")
    return "\n".join(out)

if __name__ == "__main__":
    ap = argparse.ArgumentParser()
    ap.add_argument("mode", choices=["up", "down", "progress", "roots"])
    ap.add_argument("path", nargs="?")
    ap.add_argument("--name", action="append")
    ap.add_argument("--root", default=None)
    ap.add_argument("--prefer", action="store_true",
                    help="treat --name as a PRECEDENCE list (first match wins per level) rather "
                         "than separate chains — for a tree mid-rename: --name SPEC.md --name README.md --prefer")
    ap.add_argument("--exclude", action="append", default=[])
    ap.add_argument("--field", default=None, help="compose ONE frontmatter field up the chain (e.g. --field intent) instead of whole bodies")
    ap.add_argument("--leaf-cap", type=int, default=2400, metavar="N",
                    help="with --field: also render the LEAF's body, capped at N chars (0 = off). "
                         "Ancestors compress; the leaf is where the nouns are.")
    ap.add_argument("--shelf", action="append", default=[],
                    help=f"extra directory name that HOLDS instances rather than being a position, so "
                         f"its absence of a chain file is correct (defaults: {', '.join(sorted(SHELF_NAMES))})")
    a = ap.parse_args()
    if a.mode == "roots":
        r = resolve_roots()
        for k in ("work_root", "topology_root"):
            v = r.get(k)
            if v:
                print(f"{k}={v}")
            else:
                key = "workspace.root" if k == "work_root" else "workspace.topology_root"
                print(f"# {k} UNRESOLVED — set it: rig config set {key} <path>", file=sys.stderr)
        sys.exit(0 if all(r.values()) else 3)
    if not a.name:
        ap.error("--name is required for up/down/progress")
    if a.mode == "up":
        print(compose_up(a.path, a.name, a.root, a.field, prefer=a.prefer, shelves=a.shelf, leaf_cap=a.leaf_cap))
    elif a.mode == "down":
        print(compose_down(a.path, a.name, a.exclude))
    else:
        print(compose_progress(a.path, a.name, a.exclude))

#!/usr/bin/env bash
# scaffold.sh topology <root> --node <relpath> [--node <relpath> ...]
# scaffold.sh work     <root> --node <relpath> [--node <relpath> ...]
# Creates missing chain files from templates at root + each named node dir.
# NEVER overwrites an existing file (brownfield-safe by construction; greenfield
# and brownfield are the same command with different starting states).
# Never deletes anything. Reports created vs existing.
set -euo pipefail
MODE="${1:?usage: scaffold.sh <topology|work> <root> --node <relpath> ...}"
ROOT="${2:?root dir required}"; shift 2
HERE="$(cd "$(dirname "$0")" && pwd)"; TPL="$HERE/../templates"
case "$MODE" in
  # Chains carry knowledge about a POSITION. SOP.md is knowledge about a KIND and now ships
  # in the rig's mode plugin (openrig-lab | openrig-factory | openrig-hq) — it is NOT a chain
  # and must not be scaffolded onto the tree. CULTURE.md ships with OpenRig.
  topology) FILES=(LEARNED.md) ; ROOT_FILES=(LEARNED.md) ;;
  # SPEC.md is the authored node (intent: in frontmatter). NOTES.md is the LIVED file — the
  # scaffold creates its surface only; lived entries are never generated or projected. PROGRESS is derived;
  # PROOF.md is authored by the prover when there is something to prove.
  work)     FILES=(SPEC.md NOTES.md) ; ROOT_FILES=(SPEC.md NOTES.md) ;;
  *) echo "mode must be topology|work" >&2; exit 2 ;;
esac
NODES=()
while [[ $# -gt 0 ]]; do case "$1" in --node) NODES+=("$2"); shift 2;; *) echo "unknown arg $1" >&2; exit 2;; esac; done
place(){ # $1=dir $2=file
  mkdir -p "$1"
  if [[ -e "$1/$2" ]]; then echo "  exists : $1/$2"
  else cp "$TPL/$2" "$1/$2"; echo "  CREATED: $1/$2 (template — UNSEEDED; the real owner seeds it)"; fi
}
echo "scaffold $MODE @ $ROOT"
touch "$ROOT/.compose-root" 2>/dev/null || true
for f in "${ROOT_FILES[@]}"; do place "$ROOT" "$f"; done
for n in ${NODES[@]+"${NODES[@]}"}; do for f in "${FILES[@]}"; do place "$ROOT/$n" "$f"; done; done
echo "done. Rules: existing files untouched; UNSEEDED templates await their owners; seat LEARNED.md is SELF-seeded (the audit) — never bulk-filled."

#!/usr/bin/env bash
# trace-due.sh <seat-dir> [work-dir ...]
# Deterministic due-check for the alignment trace. Exit 0 + reason when DUE;
# exit 1 SILENTLY when not (the no-op path is the point: schedulers may fire
# this on cadence; the ACTION stays evidence-gated — fixed-cadence traces were
# empirically falsified; see SKILL.md §4).
set -euo pipefail
SEAT_DIR="${1:?usage: trace-due.sh <seat-dir> [work-dir ...]}"; shift || true
STAMP="$SEAT_DIR/.last-trace"
MIN_HOURS="${TRACE_MIN_HOURS:-6}"      # never due more often than this
FORCE_HOURS="${TRACE_FORCE_HOURS:-72}" # due regardless of activity after this
now=$(date +%s)
if [[ ! -f "$STAMP" ]]; then
  # never traced: due only if the seat shows any life at all
  if [[ -n "$(find "$SEAT_DIR" "$@" -type f -newermt '-7 days' -print -quit 2>/dev/null)" ]]; then
    echo "DUE: no trace on record and recent activity exists"; exit 0
  fi
  exit 1
fi
last=$(stat -f %m "$STAMP" 2>/dev/null || stat -c %Y "$STAMP")  # BSD then GNU; date -r means different things on the two OSes
age_h=$(( (now - last) / 3600 ))
(( age_h < MIN_HOURS )) && exit 1
if (( age_h >= FORCE_HOURS )); then
  echo "DUE: ${age_h}h since last trace (force threshold ${FORCE_HOURS}h)"; exit 0
fi
# due only if meaningful work accumulated since the stamp
for d in "$SEAT_DIR" "$@"; do
  if [[ -n "$(find "$d" -type f -newer "$STAMP" ! -name '.last-trace' -print -quit 2>/dev/null)" ]]; then
    echo "DUE: ${age_h}h since last trace and new activity under $d"; exit 0
  fi
done
exit 1

#!/usr/bin/env bash
# trace-stamp.sh <seat-dir>  — record that a trace was performed now.
set -euo pipefail
touch "${1:?usage: trace-stamp.sh <seat-dir>}/.last-trace"
echo "stamped: $1/.last-trace ($(date '+%Y-%m-%d %H:%M %Z'))"

#!/usr/bin/env bash
# trunk-diff.sh <root-dir> <state-file> [--name FILE ...]
# The governance pull loop: render the subtree, diff against your PREVIOUS
# render, update state. Reading the diff = updating your mental model of a
# changing topology without reading everything or being told anything.
set -euo pipefail
ROOT="${1:?usage: trunk-diff.sh <root-dir> <state-file> [--name FILE ...]}"
STATE="${2:?state-file required}"; shift 2
NAMES=("$@"); [[ ${#NAMES[@]} -eq 0 ]] && NAMES=(--name CULTURE.md --name SOP.md --name LEARNED.md --name SPEC.md --name PLAYBOOK.md --name INTENT.md)
HERE="$(cd "$(dirname "$0")" && pwd)"
NEW="$(mktemp)"
python3 "$HERE/compose.py" down "$ROOT" "${NAMES[@]}" | grep -v '^<!-- GENERATED' > "$NEW"
if [[ -f "$STATE" ]]; then
  if diff -u "$STATE" "$NEW"; then echo "── no changes since your last render ──"; fi
else
  echo "── first render (no previous state); full content is the baseline ──"
fi
mv "$NEW" "$STATE"

---
seat: <pod>-<member>@<rig>            # or rig/pod/fleet coords at higher altitudes
template: <path-or-name of SOP.md this refines> @ <version/sha>
owners: self (sole direct writer) · <orchestrator/PM> (by proposal) · hierarchy (boundaries only, marked)
updated: <YYYY-MM-DD from the clock command — never mental math>
status: UNSEEDED  # the first real occupant replaces this line with: seeded-by-self <date>
---
# LEARNED — <instance coords>
<!-- Size is soft guidance: keep the file as small as honestly covers the job.
     Before handover or clear, distill LESSONS into HOW I WORK and retain needed context. -->

## MY JOB HERE
<!-- This instance's actual function, in operational terms. If you cannot write
     this section yourself, say so to your orchestrator — that discovery is the
     audit working, not a failure. -->

## STANDING DUTIES
<!-- One per line: DUTY — cadence — surface. These survive handovers ONLY if
     enumerated here. -->
- 

## HOW I WORK
<!-- Learned SOP bullets. EVERY bullet carries its reason — a rule without its
     why is scripture and will be misapplied. -->
- 

## GATES & AUTHORITIES
<!-- What I hold (granted in writing, cite the grant). What I must never infer. -->
- 

## KEY RELATIONSHIPS
<!-- who I hand to · who gates me · whose funnel I feed -->
- 

## TRIGGER POINTERS
<!-- situation → read this. Attach pointers to MOMENTS, not to boot. -->
- 

## LESSONS (dated, newest first)
<!-- Distill into HOW I WORK at deposit boundaries; preserve necessary reasons
     and archive superseded material. Attention is the budget, not a hard line cap. -->
- 

---
node: <mission | slice>
updated: <YYYY-MM-DD>
---
# NOTES — <node>
<!-- The working record: what actually happened doing this work. Append-only,
     dated entries, newest first. Corrections annotated, never swapped.
     Seat-specific learnings do NOT belong here — they go to that seat's
     LEARNED.md (this file is the WORK's memory, not the worker's). -->

# Legacy pointer — use SOP.md

The procedure template is [SOP.md](SOP.md). Use it for new chain files; this
PLAYBOOK.md pointer preserves the old address. Edit the current template.

---
kind: <seat-type | pod-type | rig-type | fleet>
owner: <spec author>                   # instances NEVER edit this file
updated: <YYYY-MM-DD>
status: UNSEEDED
---
# SOP — <kind>
<!-- The TEMPLATE half: how this KIND of thing does its job, anywhere it is
     instantiated. Absorbs the static role file at seat altitude. Instance-local
     knowledge belongs in LEARNED.md beside this, never here. -->

## PURPOSE
<!-- what this kind exists to do -->

## CORE LOOP
<!-- the job's shape: inputs → work → outputs/handoffs -->

## DEFAULT PRACTICES
<!-- each with its reason attached -->
- 

## BOUNDARIES
<!-- what this kind never does; where its authority ends -->
- 

---
node: <project | mission | slice>
intent: >-
  <ONE sentence: what this node is FOR. This composes UP the chain, so write it to be
   read from below by someone standing on a slice. Say the purpose, never the location —
   "deferred features land here" is a routing rule and orients nobody.>
id: <OPR.x.y[.n] — minted by the PM; omit if unminted>
stage: wip
# stage: wip | provisional | established | canonical | superseded | retired
status: UNSEEDED
---

<!-- ONE authored file per work node. README.md and IMPLEMENTATION-PRD.md fold into this.
     PROOF.md stays separate and is good. PROGRESS.md is the authored acceptance checklist:
     checkbox items are stored marks; every roll-up above them is derived, never hand-authored.
     Legacy README.md nodes stay valid indefinitely; nothing is forced to migrate.

     PROJECT nodes carry stable intent. MISSION nodes carry intent and proportional
     mission-level specification in this same authored file, organizing slices and
     giving them shared scope. SLICE nodes carry concrete implementation scope.
     Keep body depth proportional; do not repeat all slice details at mission level.

     WHATEVER BODY YOU DO WRITE, two tests per sentence:
       PORTABILITY — if it would read correctly on a stranger's machine it is knowledge
         about a KIND; it belongs in the operating-model skill, not on the tree.
       VOLATILITY — a SHA, a count, a status, a roster: write the COMMAND that derives it,
         never the answer. A value here is stale by the next fold.
     And check the tree: traps and how-we-work live in LEARNED.md on the topology tree,
     not here. This file is what is being BUILT.

     Follow the selected mission-slice-sop and any explicit operating-mode overlay.
     Use the required sections for that work; the generic body below is a starting
     shape, not an additional gate or a requirement for every mission. -->

# <name>

## What must be built

<!-- The change itself, at the altitude a builder can act on. -->

## Why this is the shape

<!-- The reasoning a reader would otherwise have to reconstruct — especially any option
     considered and rejected. This is the part that survives you. -->

## How we will know it works

<!-- Verified by EFFECT: run it, look at the result. Name the command and what it should
     print, not the feeling of being done. -->

## Scope fences

<!-- What this deliberately does NOT include, so it neither swallows the release nor grows
     during the build. Fences written after the fact are excuses; written now they hold. -->