exloop 0.1.0__py3-none-any.whl

exloop/skills/exloop/scripts/exploration_state.py

@@ -0,0 +1,763 @@
+#!/usr/bin/env python3
+"""Append-only workbench state for the exloop skill.
+
+One exploration lives in exactly one directory, `~/.exloop/explorations/<slug>/`,
+no matter which AI tool (Claude Code, Codex, WorkBuddy, ...) the person is using
+at the moment. The slug is chosen once at `init` and is the same name the archive
+folder will carry in the exloop repository. **Never derive it from a session or
+thread id** — that is how one exploration ended up scattered across
+`~/.codex/explorations/<thread>/` and `~/.workbuddy/explorations/<session>/`
+in 2026-08, and why the tool-specific defaults were removed.
+
+Where the record goes when the exploration ends is the **research repository** (the one
+`newlife start` creates): `archive --repo` puts it under `explorations/<slug>/process/`,
+`handoff --repo` under `questions/<slug>/origin/`. Not the exloop repository.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+MARK_KINDS = ("node", "got", "stuck", "abandoned", "surprise", "framework")
+NODE_STATES = {"node": "exploring", "got": "got", "stuck": "stuck", "abandoned": "abandoned", "framework": "framework"}
+SAFE_ID = re.compile(r"^[A-Za-z0-9._-]{1,160}$")
+
+
+class StateError(RuntimeError):
+    pass
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def state_root(raw: str | None) -> Path:
+    configured = raw or os.environ.get("EXLOOP_HOME")
+    root = Path(configured).expanduser() if configured else Path.home() / ".exloop" / "explorations"
+    return root.resolve()
+
+
+def exploration_id(raw: str | None) -> str:
+    value = raw or os.environ.get("EXLOOP_ID")
+    if not value:
+        raise StateError(
+            "No exploration id given. Pass --id <slug>, where the slug is the name the archive "
+            "folder will carry (YYYY-MM-DD-<two-to-four-english-words>, e.g. "
+            "2026-09-05-yield-input-or-outcome). The same slug is used from every tool; a "
+            "session or thread id must not be used, because it changes when the tool changes."
+        )
+    if not SAFE_ID.fullmatch(value):
+        raise StateError("Exploration ID may contain only letters, digits, dot, underscore, and hyphen.")
+    return value
+
+
+def state_paths(root: Path, ident: str) -> tuple[Path, Path, Path]:
+    directory = root / ident
+    return directory, directory / "events.jsonl", directory / "map.md"
+
+
+def read_events(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    events: list[dict[str, Any]] = []
+    with path.open("r", encoding="utf-8") as handle:
+        for number, line in enumerate(handle, start=1):
+            if not line.strip():
+                continue
+            try:
+                event = json.loads(line)
+            except json.JSONDecodeError as exc:
+                raise StateError(f"Invalid JSON in {path} line {number}: {exc}") from exc
+            if not isinstance(event, dict) or not isinstance(event.get("type"), str):
+                raise StateError(f"Invalid event object in {path} line {number}")
+            events.append(event)
+    return events
+
+
+def append_event(path: Path, event: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = json.dumps(event, ensure_ascii=False, separators=(",", ":")) + "\n"
+    with path.open("a", encoding="utf-8") as handle:
+        try:
+            import fcntl
+
+            fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+        except ImportError:
+            fcntl = None  # type: ignore[assignment]
+        handle.write(payload)
+        handle.flush()
+        os.fsync(handle.fileno())
+        if fcntl is not None:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+
+
+def atomic_write(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temp_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temp_name, path)
+    finally:
+        if os.path.exists(temp_name):
+            os.unlink(temp_name)
+
+
+def empty_map(ident: str) -> dict[str, Any]:
+    return {
+        "id": ident,
+        "root_question": "",
+        "question": "",
+        "started_at": "",
+        "nodes": {},
+        "surprises": [],
+        "pivots": [],
+        "closed": None,
+    }
+
+
+def fold_map(ident: str, events: list[dict[str, Any]]) -> dict[str, Any]:
+    result = empty_map(ident)
+    for event in events:
+        if event.get("id") != ident:
+            continue
+        event_type = event.get("type")
+        if event_type == "exploration/started":
+            question = str(event.get("question", ""))
+            result["root_question"] = question
+            result["question"] = question
+            result["started_at"] = str(event.get("at", ""))
+        elif event_type == "exploration/marked":
+            kind = event.get("kind")
+            if kind == "surprise":
+                note = event.get("note")
+                if isinstance(note, str) and note:
+                    result["surprises"].append(note)
+                continue
+            if kind not in NODE_STATES:
+                continue
+            ref = str(event.get("ref", ""))
+            if not ref:
+                continue
+            nodes: dict[str, dict[str, Any]] = result["nodes"]
+            node = nodes.get(ref)
+            if node is None:
+                node = {
+                    "ref": ref,
+                    "label": str(event.get("label") or ref),
+                    "state": NODE_STATES[kind],
+                    "notes": [],
+                }
+                nodes[ref] = node
+            else:
+                node["state"] = NODE_STATES[kind]
+                if event.get("label"):
+                    node["label"] = str(event["label"])
+            note = event.get("note")
+            if isinstance(note, str) and note and (not node["notes"] or node["notes"][-1] != note):
+                node["notes"].append(note)
+        elif event_type == "exploration/pivoted":
+            pivot = {
+                "from": str(event.get("from", "")),
+                "to": str(event.get("to", "")),
+                "why": str(event.get("why", "")),
+                "source": str(event.get("source", "human")),
+            }
+            result["pivots"].append(pivot)
+            result["question"] = pivot["to"]
+        elif event_type == "exploration/closed":
+            result["closed"] = {
+                "summary": str(event.get("summary", "")),
+                "at": str(event.get("at", "")),
+            }
+    return result
+
+
+def chunk_labels(labels: list[str], limit: int = 60) -> list[str]:
+    rows: list[str] = []
+    current: list[str] = []
+    for label in labels:
+        candidate = ", ".join([*current, label])
+        if current and len(candidate) > limit:
+            rows.append(", ".join(current))
+            current = []
+        current.append(label)
+    if current:
+        rows.append(", ".join(current))
+    return rows
+
+
+def render_map(result: dict[str, Any]) -> str:
+    lines = ["# Map of this exploration", ""]
+    root = result["root_question"]
+    current = result["question"]
+    if root and root != current:
+        lines.extend([f"Root question: {root}", f"Now pursuing: {current}"])
+    else:
+        lines.append(f"Current question: {current or '(not yet honed)'}")
+    lines.extend([f"Status: {'closed' if result['closed'] else 'open'}", ""])
+
+    nodes = list(result["nodes"].values())
+    by_state = {state: [node for node in nodes if node["state"] == state] for state in NODE_STATES.values()}
+
+    lines.append("## Boundary (the next step grows from here)")
+    if not by_state["stuck"]:
+        lines.append("- (none yet)")
+    for node in by_state["stuck"]:
+        first = node["notes"][0] if node["notes"] else ""
+        lines.append(f"- {node['label']} | stuck{f' | {first}' if first else ''}")
+        for note in node["notes"][1:]:
+            lines.append(f"  - later: {note}")
+    lines.append("")
+
+    if by_state["framework"]:
+        lines.append("## Frameworks honed (reusable)")
+        for node in by_state["framework"]:
+            note = node["notes"][-1] if node["notes"] else ""
+            lines.append(f"- {node['label']}{f' | {note}' if note else ''}")
+        lines.append("")
+
+    if by_state["exploring"]:
+        lines.append("## In progress")
+        for node in by_state["exploring"]:
+            note = node["notes"][-1] if node["notes"] else ""
+            lines.append(f"- {node['label']}{f' | {note}' if note else ''}")
+        lines.append("")
+
+    if by_state["got"]:
+        lines.append("## Already understood (no need to explain again)")
+        for row in chunk_labels([node["label"] for node in by_state["got"]]):
+            lines.append(f"- {row}")
+        lines.append("")
+
+    if by_state["abandoned"]:
+        lines.append("## Abandoned (do not recommend again)")
+        for node in by_state["abandoned"][-5:]:
+            note = node["notes"][-1] if node["notes"] else ""
+            lines.append(f"- {node['label']}{f' | {note}' if note else ''}")
+        lines.append("")
+
+    if result["surprises"]:
+        lines.append("## Surprises")
+        lines.extend(f"- {surprise}" for surprise in result["surprises"])
+        lines.append("")
+
+    if result["pivots"]:
+        lines.append("## Pivots (where the question changed)")
+        for pivot in result["pivots"]:
+            tag = " | (detected in review)" if pivot["source"] == "detected" else ""
+            lines.append(f"- from “{pivot['from']}” to “{pivot['to']}” | {pivot['why']}{tag}")
+        lines.append("")
+
+    if result["closed"]:
+        lines.append("## Closure")
+        summary = result["closed"]["summary"]
+        lines.append(f"- {summary or 'closed at the person’s request'}")
+        lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def ensure_active(result: dict[str, Any]) -> None:
+    if not result["started_at"]:
+        raise StateError("This exploration has not been initialized. Run init first.")
+    if result["closed"]:
+        raise StateError("This exploration is closed. Start an unrelated exploration with a different --id.")
+
+
+def refresh_map(ident: str, events_path: Path, map_path: Path) -> dict[str, Any]:
+    result = fold_map(ident, read_events(events_path))
+    atomic_write(map_path, render_map(result))
+    return result
+
+
+def command_init(args: argparse.Namespace) -> None:
+    root = state_root(args.root)
+    ident = exploration_id(args.id)
+    directory, events_path, map_path = state_paths(root, ident)
+    question = args.question.strip()
+    if not question:
+        raise StateError("The root question cannot be empty.")
+    events = read_events(events_path)
+    result = fold_map(ident, events)
+    if result["started_at"]:
+        if result["closed"]:
+            raise StateError("This id already holds a closed exploration; pick a different --id.")
+        if result["root_question"] != question:
+            raise StateError("This id already has another root question; record a pivot instead of overwriting it.")
+    else:
+        append_event(
+            events_path,
+            {"type": "exploration/started", "id": ident, "question": question, "at": now_iso()},
+        )
+    refresh_map(ident, events_path, map_path)
+    print(f"state_dir={directory}")
+    print(f"map={map_path}")
+
+
+def command_mark(args: argparse.Namespace) -> None:
+    root = state_root(args.root)
+    ident = exploration_id(args.id)
+    _, events_path, map_path = state_paths(root, ident)
+    result = fold_map(ident, read_events(events_path))
+    ensure_active(result)
+
+    note = args.note.strip() if args.note else ""
+    label = args.label.strip() if args.label else ""
+    ref_value = args.ref.strip() if args.ref else ""
+    if args.turn is not None and args.turn < 0:
+        raise StateError("Turn must be a non-negative integer.")
+
+    if args.kind == "surprise":
+        if not note:
+            raise StateError("A surprise requires --note.")
+        ref = ref_value or "-"
+    else:
+        if not ref_value:
+            raise StateError(f"A {args.kind} mark requires --ref.")
+        ref = ref_value
+
+    event: dict[str, Any] = {
+        "type": "exploration/marked",
+        "id": ident,
+        "kind": args.kind,
+        "ref": ref,
+        "at": now_iso(),
+    }
+    if label:
+        event["label"] = label
+    if note:
+        event["note"] = note
+    if args.turn is not None:
+        event["turn"] = args.turn
+    append_event(events_path, event)
+    refresh_map(ident, events_path, map_path)
+    print(f"recorded={args.kind}:{ref}")
+
+
+def command_pivot(args: argparse.Namespace) -> None:
+    root = state_root(args.root)
+    ident = exploration_id(args.id)
+    _, events_path, map_path = state_paths(root, ident)
+    result = fold_map(ident, read_events(events_path))
+    ensure_active(result)
+    target = args.to.strip()
+    reason = args.why.strip()
+    if not target:
+        raise StateError("A pivot target cannot be empty.")
+    if not reason:
+        raise StateError("A pivot requires a reason so the change remains interpretable.")
+    append_event(
+        events_path,
+        {
+            "type": "exploration/pivoted",
+            "id": ident,
+            "from": result["question"],
+            "to": target,
+            "why": reason,
+            "source": args.source,
+            "at": now_iso(),
+        },
+    )
+    refresh_map(ident, events_path, map_path)
+    print(f"pivoted_to={target}")
+
+
+def command_show(args: argparse.Namespace) -> None:
+    root = state_root(args.root)
+    ident = exploration_id(args.id)
+    _, events_path, map_path = state_paths(root, ident)
+    result = refresh_map(ident, events_path, map_path)
+    if not result["started_at"]:
+        raise StateError("This exploration has not been initialized. Run init first.")
+    print(render_map(result), end="")
+
+
+def command_close(args: argparse.Namespace) -> None:
+    root = state_root(args.root)
+    ident = exploration_id(args.id)
+    directory, events_path, map_path = state_paths(root, ident)
+    result = fold_map(ident, read_events(events_path))
+    ensure_active(result)
+    append_event(
+        events_path,
+        {
+            "type": "exploration/closed",
+            "id": ident,
+            "summary": (args.summary or "").strip(),
+            "at": now_iso(),
+        },
+    )
+    refresh_map(ident, events_path, map_path)
+    print(f"closed={directory}")
+
+
+def command_path(args: argparse.Namespace) -> None:
+    root = state_root(args.root)
+    ident = exploration_id(args.id)
+    directory, _, _ = state_paths(root, ident)
+    print(directory)
+
+
+def command_list(args: argparse.Namespace) -> None:
+    """List every exploration under the state root: slug, open/closed, start day, current question."""
+    root = state_root(args.root)
+    if not root.is_dir():
+        print(f"(no explorations under {root})")
+        return
+    for directory in sorted(p for p in root.iterdir() if p.is_dir()):
+        events_path = directory / "events.jsonl"
+        if not events_path.exists():
+            continue
+        result = fold_map(directory.name, read_events(events_path))
+        if not result["started_at"]:
+            continue
+        status = "closed" if result["closed"] else "open"
+        print(f"{directory.name}\t{status}\t{result['started_at'][:10]}\t{result['question']}")
+
+
+def _target(args: argparse.Namespace, ident: str, default_rel: str) -> Path:
+    """Where an archive or handoff lands: `--to <dir>` verbatim, or derived from `--repo`.
+
+    `--repo` is the research repository — the same one `newlife start` created and the
+    one that holds `questions/`. The archive goes to `explorations/<slug>/process/` there,
+    the handoff to `questions/<slug>/origin/`; same slug on both sides, so the two never
+    disagree about which exploration a question came from.
+    """
+    if args.to:
+        return Path(args.to).expanduser().resolve()
+    if args.repo:
+        return Path(args.repo).expanduser().resolve() / default_rel.format(slug=ident)
+    raise StateError("Pass --repo <research repository> (the usual case) or --to <directory>.")
+
+
+def render_readme_skeleton(result: dict[str, Any], ident: str) -> str:
+    """The four-section entry README the archive convention requires, all TODO.
+
+    Written only when the exploration folder is new. Conclusions must point at files;
+    the shortfalls section must never be empty — those are the convention's two hard
+    rules, and the skeleton says so where the person will write.
+    """
+    q = result["question"] or result["root_question"] or ident
+    return "\n".join([
+        f"# {q}",
+        "",
+        f"- **Started**: {result['started_at'][:10] or 'unknown'} · **Status**: "
+        f"{'closed' if result['closed'] else 'open'}",
+        f"- **Root question**: {result['root_question'] or '(none recorded)'}",
+        "- **Record**: `process/events.jsonl` and `process/map.md`, archived by exloop `archive`.",
+        "",
+        "## Conclusions",
+        "",
+        "(TODO — one per line, and each must point at a file under `artifacts/` or `process/`.",
+        "A conclusion that points nowhere is either unverified or should be deleted.)",
+        "",
+        "## Shortfalls / boundaries",
+        "",
+        "(TODO — never empty: what was not found, which results do not count as evidence,",
+        "which numbers await a recheck.)",
+        "",
+        "## Navigation",
+        "",
+        "| File | One line |",
+        "|---|---|",
+        "| `process/map.md` | the map at closure |",
+        "| `process/events.jsonl` | the raw event stream |",
+        "",
+    ])
+
+
+def command_archive(args: argparse.Namespace) -> None:
+    """Copy events.jsonl and map.md into an archive directory, verbatim.
+
+    The intended target is `<exloop repo>/explorations/<slug>/process/`. Existing files
+    with different content are not overwritten unless --force is given, so re-running
+    after more events were appended is safe to do deliberately and impossible to do
+    by accident.
+    """
+    root = state_root(args.root)
+    ident = exploration_id(args.id)
+    _, events_path, map_path = state_paths(root, ident)
+    result = fold_map(ident, read_events(events_path))
+    if not result["started_at"]:
+        raise StateError("This exploration has not been initialized. Run init first.")
+    atomic_write(map_path, render_map(result))
+    destination = _target(args, ident, "explorations/{slug}/process")
+    destination.mkdir(parents=True, exist_ok=True)
+    pairs = [(source, destination / source.name) for source in (events_path, map_path)]
+    # Check both before copying either: the two files land together or not at all, never half an archive.
+    for source, target in pairs:
+        if target.exists() and target.read_bytes() != source.read_bytes() and not args.force:
+            raise StateError(f"{target} exists with different content; pass --force to overwrite it.")
+    for source, target in pairs:
+        shutil.copyfile(source, target)
+        print(f"archived={target}")
+    # A fresh archive folder gets the convention's skeleton once; an existing README is
+    # the person's and is never touched.
+    if destination.name == "process":
+        folder = destination.parent
+        readme = folder / "README.md"
+        if not readme.exists():
+            readme.write_text(render_readme_skeleton(result, ident), encoding="utf-8")
+            (folder / "artifacts").mkdir(exist_ok=True)
+            print(f"skeleton={readme}  (four sections, all TODO; artifacts/ created)")
+
+
+def render_goal_draft(result: dict[str, Any], ident: str, at: str) -> str:
+    """A newlife `goal.md`-shaped draft with §1 / §3 / §4 pre-filled from the map.
+
+    The six anchors stay TODO on purpose: they are what the `newlife-goal` skill adds
+    (counterparty, attack layer, who changes behaviour, ...) and nothing in an exploration
+    map can supply them. Section headings match newlife's scaffolded `goal.md` so the text
+    can be pasted across section by section.
+    """
+    nodes = list(result["nodes"].values())
+    by_state = {state: [n for n in nodes if n["state"] == state] for state in NODE_STATES.values()}
+    q = result["question"] or result["root_question"] or "(question not yet honed)"
+    lines = [
+        f"# Goal — {q}",
+        "",
+        f"> Draft generated by exloop `handoff` from exploration `{ident}`, record as of {at}.",
+        "> **Everything below was seen during the exploration** and counts as exploratory for",
+        "> any later preregistration. The six anchors are left as TODO on purpose: fill them",
+        "> with the `newlife-goal` skill, then carry the sections over into `goal.md`",
+        "> (which `newlife init` scaffolds red). Anchor bodies must not contain `>`.",
+        "",
+        "<!--@evidence: literature_searched=TODO, sources=TODO, verdict=TODO-->",
+        "<!--@counterparty: TODO-->",
+        "<!--@attack_layer: TODO-->",
+        "<!--@decides: TODO-->",
+        "<!--@who_changes_behavior: TODO-->",
+        "<!--@size_estimate: impl_lines=TODO, criteria=TODO, failure_modes=TODO-->",
+        "",
+        "## 1. What this buys",
+        "",
+        "### Where the question came from (the exploration map)",
+        "",
+        f"- Root question: {result['root_question'] or '(none recorded)'}",
+    ]
+    for i, pivot in enumerate(result["pivots"], start=1):
+        tag = " (detected in review, not stated by the person)" if pivot["source"] == "detected" else ""
+        lines.append(f"- Pivot {i}: from “{pivot['from']}” to “{pivot['to']}” — why: {pivot['why']}{tag}")
+    lines.append(f"- Question at handoff: {q}")
+    lines.append("")
+    lines.append("### Surprises recorded (raw material for promoting an anomaly)")
+    lines.append("")
+    lines.extend(f"- {s}" for s in result["surprises"]) if result["surprises"] else lines.append("- (none recorded)")
+    lines.append("")
+    lines.append("### Frameworks named during the exploration (mechanism candidates)")
+    lines.append("")
+    if by_state["framework"]:
+        for n in by_state["framework"]:
+            note = n["notes"][-1] if n["notes"] else ""
+            lines.append(f"- {n['label']}{f' — {note}' if note else ''}")
+    else:
+        lines.append("- (none recorded)")
+    lines.extend([
+        "",
+        "## 2. Success criteria",
+        "",
+        "(A conjunction, independent of H1. Nothing in the map supplies these — write them.)",
+        "",
+        "## 3. Explicitly not doing",
+        "",
+        "Paths abandoned during the exploration, with the reason recorded at the time:",
+        "",
+    ])
+    if by_state["abandoned"]:
+        for n in by_state["abandoned"]:
+            note = n["notes"][-1] if n["notes"] else ""
+            lines.append(f"- {n['label']}{f' — {note}' if note else ''}")
+    else:
+        lines.append("- (none recorded)")
+    lines.extend([
+        "",
+        "## 4. Risks declared in advance",
+        "",
+        "Boundaries still open when the exploration was handed off (each is a place the",
+        "question could still turn out to be ill-posed):",
+        "",
+    ])
+    if by_state["stuck"]:
+        for n in by_state["stuck"]:
+            first = n["notes"][0] if n["notes"] else ""
+            lines.append(f"- {n['label']}{f' — {first}' if first else ''}")
+            for note in n["notes"][1:]:
+                lines.append(f"  - later: {note}")
+    else:
+        lines.append("- (none recorded)")
+    lines.extend([
+        "",
+        "## 5. Closeout judgement",
+        "",
+        "(Filled in afterwards: achieved / not_achieved / regressed / not_applicable.)",
+        "",
+    ])
+    return "\n".join(lines)
+
+
+def command_handoff(args: argparse.Namespace) -> None:
+    """Hand an exploration to a newlife question folder: raw record + a goal draft.
+
+    Writes `events.jsonl`, `map.md` and `goal-draft.md` into `--to`, normally
+    `<research repo>/questions/<slug>/origin/`. The raw record is copied verbatim; the
+    draft is rendered from the map. Refuses to overwrite a differing file unless --force.
+    """
+    root = state_root(args.root)
+    ident = exploration_id(args.id)
+    _, events_path, map_path = state_paths(root, ident)
+    events = read_events(events_path)
+    result = fold_map(ident, events)
+    if not result["started_at"]:
+        raise StateError("This exploration has not been initialized. Run init first.")
+    atomic_write(map_path, render_map(result))
+    destination = _target(args, ident, "questions/{slug}/origin")
+    if not (destination.parent / "goal.md").is_file():
+        raise StateError(
+            f"{destination.parent} is not a newlife question folder (no goal.md). Run "
+            f"`newlife init {ident}` in the research repository first; handoff writes into the "
+            f"origin/ of an existing question. (Writing first would make init refuse, because "
+            f"the folder would already exist.)"
+        )
+    destination.mkdir(parents=True, exist_ok=True)
+    # Stamp the draft with the record's own last event, not the wall clock: the same record
+    # then renders the same bytes, so re-running handoff is a no-op instead of a refusal,
+    # and a changed record is refused (without --force) exactly when it should be.
+    as_of = str(events[-1].get("at", "")) if events else ""
+    draft = render_goal_draft(result, ident, as_of).encode("utf-8")
+    payloads = [(destination / "events.jsonl", events_path.read_bytes()),
+                (destination / "map.md", map_path.read_bytes()),
+                (destination / "goal-draft.md", draft)]
+    for target, body in payloads:
+        if target.exists() and target.read_bytes() != body and not args.force:
+            raise StateError(f"{target} exists with different content; pass --force to overwrite it.")
+    for target, body in payloads:
+        target.write_bytes(body)
+        print(f"handed_off={target}")
+
+
+def command_self_test(_: argparse.Namespace) -> None:
+    ident = "self-test"
+    events = [
+        {"type": "exploration/started", "id": ident, "question": "root", "at": "t0"},
+        {"type": "exploration/marked", "id": ident, "kind": "stuck", "ref": "gap", "label": "Missing link", "note": "first", "at": "t1"},
+        {"type": "exploration/marked", "id": ident, "kind": "stuck", "ref": "gap", "note": "first", "at": "t2"},
+        {"type": "exploration/marked", "id": ident, "kind": "stuck", "ref": "gap", "note": "reversal", "at": "t3"},
+        {"type": "exploration/marked", "id": ident, "kind": "framework", "ref": "f", "label": "Reusable frame", "note": "mechanism", "at": "t4"},
+        {"type": "exploration/marked", "id": ident, "kind": "surprise", "ref": "-", "note": "counterintuitive", "at": "t5"},
+        {"type": "exploration/pivoted", "id": ident, "from": "root", "to": "focus", "why": "new human fact", "source": "human", "at": "t6"},
+        {"type": "exploration/closed", "id": ident, "summary": "done", "at": "t7"},
+    ]
+    result = fold_map(ident, events)
+    assert result["root_question"] == "root"
+    assert result["question"] == "focus"
+    assert result["nodes"]["gap"]["notes"] == ["first", "reversal"]
+    assert result["nodes"]["f"]["state"] == "framework"
+    assert result["surprises"] == ["counterintuitive"]
+    assert result["closed"]["summary"] == "done"
+    rendered = render_map(result)
+    assert "Root question: root" in rendered and "Now pursuing: focus" in rendered
+    assert "later: reversal" in rendered and "Frameworks honed" in rendered and "## Closure" in rendered
+    draft = render_goal_draft(result, ident, "t8")
+    assert draft.startswith("# Goal — focus")
+    assert draft.count("TODO") >= 6 and "<!--@counterparty: TODO-->" in draft
+    assert "Root question: root" in draft and "why: new human fact" in draft
+    assert "- counterintuitive" in draft and "Reusable frame — mechanism" in draft
+    assert "Missing link — first" in draft and "later: reversal" in draft
+    assert "## 3. Explicitly not doing" in draft and "## 5. Closeout judgement" in draft
+    skeleton = render_readme_skeleton(result, ident)
+    assert skeleton.startswith("# focus") and "## Shortfalls / boundaries" in skeleton
+    assert "process/events.jsonl" in skeleton and "TODO" in skeleton
+    print("self-test: ok")
+
+
+def add_common_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--id", help="Exploration slug (or EXLOOP_ID); the archive folder name, identical in every tool")
+    parser.add_argument("--root", help="State root (or EXLOOP_HOME); defaults to ~/.exloop/explorations")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    init_parser = subparsers.add_parser("init", help="Start or resume an exploration")
+    add_common_options(init_parser)
+    init_parser.add_argument("--question", required=True)
+    init_parser.set_defaults(func=command_init)
+
+    mark_parser = subparsers.add_parser("mark", help="Append a meaningful map mark")
+    add_common_options(mark_parser)
+    mark_parser.add_argument("--kind", required=True, choices=MARK_KINDS)
+    mark_parser.add_argument("--ref")
+    mark_parser.add_argument("--label")
+    mark_parser.add_argument("--note")
+    mark_parser.add_argument("--turn", type=int)
+    mark_parser.set_defaults(func=command_mark)
+
+    pivot_parser = subparsers.add_parser("pivot", help="Record a change of target")
+    add_common_options(pivot_parser)
+    pivot_parser.add_argument("--to", required=True)
+    pivot_parser.add_argument("--why", required=True)
+    pivot_parser.add_argument("--source", choices=("human", "detected"), default="human")
+    pivot_parser.set_defaults(func=command_pivot)
+
+    show_parser = subparsers.add_parser("show", help="Render and print the current map")
+    add_common_options(show_parser)
+    show_parser.set_defaults(func=command_show)
+
+    close_parser = subparsers.add_parser("close", help="Close an exploration explicitly")
+    add_common_options(close_parser)
+    close_parser.add_argument("--summary")
+    close_parser.set_defaults(func=command_close)
+
+    path_parser = subparsers.add_parser("path", help="Print the current state directory")
+    add_common_options(path_parser)
+    path_parser.set_defaults(func=command_path)
+
+    list_parser = subparsers.add_parser("list", help="List explorations under the state root")
+    list_parser.add_argument("--root", help="State root (or EXLOOP_HOME); defaults to ~/.exloop/explorations")
+    list_parser.set_defaults(func=command_list)
+
+    archive_parser = subparsers.add_parser("archive", help="Copy events.jsonl + map.md into an archive directory")
+    add_common_options(archive_parser)
+    archive_parser.add_argument("--repo", help="the research repository; the record goes to explorations/<slug>/process/ there")
+    archive_parser.add_argument("--to", help="an explicit target directory instead of --repo")
+    archive_parser.add_argument("--force", action="store_true", help="overwrite a target that exists with different content")
+    archive_parser.set_defaults(func=command_archive)
+
+    handoff_parser = subparsers.add_parser("handoff", help="Copy the record and write goal-draft.md into a newlife question's origin/")
+    add_common_options(handoff_parser)
+    handoff_parser.add_argument("--repo", help="the research repository; the record goes to questions/<slug>/origin/ there (run newlife init first)")
+    handoff_parser.add_argument("--to", help="an explicit origin/ directory instead of --repo")
+    handoff_parser.add_argument("--force", action="store_true", help="overwrite a target that exists with different content")
+    handoff_parser.set_defaults(func=command_handoff)
+
+    self_test_parser = subparsers.add_parser("self-test", help="Run deterministic projection checks")
+    self_test_parser.set_defaults(func=command_self_test)
+    return parser
+
+
+def main() -> int:
+    try:
+        args = build_parser().parse_args()
+        args.func(args)
+        return 0
+    except StateError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())