exloop 0.1.0__py3-none-any.whl

exloop/__init__.py

@@ -0,0 +1,32 @@
+"""exloop — human-led exploration with a persistent map.
+
+This package exists so that installing newlife (which will depend on it) puts the
+exloop skill on the machine without a trip to GitHub. It ships the skill files
+and the zero-dependency state helper the skill uses, and nothing else. newlife never
+imports exloop's code: the interface between the two is files — `handoff` writes into a
+newlife question's `origin/`. The skill master is `skills/exloop/` in the exloop
+repository; the wheel carries a byte copy under `exloop/skills/`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+__all__ = ["skills_dir"]
+
+
+def skills_dir() -> Path:
+    """The directory holding the skill masters (`exloop/SKILL.md` and friends).
+
+    In an installed wheel it is `exloop/skills/`, force-included at build time. In an
+    editable checkout the files are the repository's own `skills/`, two levels up from this
+    file. Anything else is an error, not a guess.
+    """
+    here = Path(__file__).resolve().parent
+    for candidate in (here / "skills", here.parent.parent / "skills"):
+        if (candidate / "exloop" / "SKILL.md").is_file():
+            return candidate
+    raise FileNotFoundError(
+        f"exloop skills not found: neither {here / 'skills'} (installed wheel) nor "
+        f"{here.parent.parent / 'skills'} (repository checkout) holds exloop/SKILL.md"
+    )

exloop/skills/exloop/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: exloop
+description: Use when a person wants to explore an open-ended curiosity, sharpen a vague question through sustained dialogue, or preserve a map of changing hypotheses and unresolved boundaries; do not use for direct factual answers, implementation, debugging, or confirmatory analysis.
+---
+
+# Exploration Loop
+
+> **Commands in this file are for you, the assistant, to run; the person decides.**
+> Asked how this works or where they are, describe what *they* do — see the `newlife` skill.
+
+Help the person turn a curiosity into a better question, a map of what changed,
+and reusable ways of thinking. The person owns the target and every consequential
+choice. The assistant supplies names, mechanisms, counterexamples, evidence, and
+reachable next directions without taking over the exploration.
+
+> **This file is the master, kept in the exloop repository under
+> `skills/exloop/`.** The copies under `~/.claude/skills/`,
+> `~/.codex/skills/` and `~/.workbuddy/skills/` are installed verbatim by
+> `scripts/install-skill.py`; nothing in this skill depends on which tool is
+> running it. Two host-specific copies once drifted apart (they differed only in
+> the host's name and the state directory), which is why the master exists.
+
+## Select the mode
+
+- Use **sustained mode** when the person explicitly invokes this skill, asks to
+  keep a map, or wants an exploration that may span several turns. Read
+  [references/state-model.md](references/state-model.md) and keep file-backed
+  state outside the working repository.
+- Use **conversation-only mode** for a short exploratory exchange. Apply the
+  protocol without creating files.
+- Do not convert a request for a direct answer, code change, diagnosis, review,
+  or confirmatory analysis into an exploration. Answer or use the appropriate
+  workflow instead.
+
+Before the first substantive reply, read
+[references/protocol.md](references/protocol.md). It contains the interaction
+rules and the observed failure modes this skill must resist.
+
+## Before the first exploration in a research repository: set things up yourself
+
+The person should never have to type a shell command. If the conversation is happening
+inside a research repository (or the person wants their explorations and questions kept
+somewhere), do the setup for them, telling them in one line what you are doing:
+
+1. `newlife` missing from PATH? Install it: `uv tool install newlife` (fallback:
+   `pipx install newlife`, then `python3 -m pip install --user newlife`). It brings the
+   `exloop` package along, so this skill's helper and the two newlife skills arrive too.
+2. Not yet a research repository (no `NEXT.md`)? Run `newlife start .` in it — git init,
+   `.gitignore`, `NEXT.md`, and the skills installed into every AI tool found. If it
+   reports a missing git identity, ask the person for a name and email once and set them.
+3. Then continue as below. Every later command — `newlife init`, `pilot`, `freeze`, `run`,
+   `check`, `audit`, this skill's `archive` and `handoff` — is yours to run at the moment
+   the skills say so; the person only decides.
+
+Say what you installed and where; never install anything else on the strength of this.
+
+## What you make while exploring goes into the research repository, not a temp directory
+
+Explorations run code: a paper gets converted to text, a repository gets cloned, a synthetic
+experiment gets written and run, a table gets downloaded. Measured on the first real
+exploration after this skill shipped: 542 MB of exactly that sat in the session's scratch
+directory, and the numbers it produced were on the map and in `goal.md` — traceable to
+nothing once the session ended.
+
+So, as soon as a research repository is known, keep everything you produce under
+`<repo>/explorations/<slug>/artifacts/`: scripts (with how to run them in the docstring),
+small results (JSON, tables, figures), the extracted text of a paper you are quoting. Big
+things you can fetch again (a cloned repository, a virtualenv, raw data over a few MB) may
+stay outside, but the fetch command and the commit or version go into a `README.md` or a
+manifest there. `archive` later adds `process/` and the entry README beside it; `handoff`
+does not copy artifacts — the question's `origin/README.md` points at them. The rule the
+archive convention states is the one you are serving: **every number on the map must be
+traceable to a file.**
+
+## One exploration, one slug, any tool
+
+In sustained mode the exploration is identified by a **slug**, not by the
+session. Pick it at `init`, silently, the way an archive folder is named:
+`YYYY-MM-DD-<two-to-four-english-words>`, date = the day the exploration
+started, words = the question, never the expected conclusion. State lives in
+`~/.exloop/explorations/<slug>/` whatever tool is in use, so the person can
+continue the same exploration in Claude Code, Codex or WorkBuddy without the
+record splitting. To resume, run `list` to find the slug, then `show --id <slug>`
+before replying. **Never derive the id from a thread or session id**: that is
+exactly how one exploration in 2026-08 ended up in three directories.
+
+## Core loop
+
+1. **Hone the question.** If the curiosity is vague, ask one high-leverage
+   question and offer a sharper restatement. Ask at most two rounds. If the
+   person says to start, stop honing immediately.
+2. **Advance one edge.** Add one mechanism, distinction, counterexample, or
+   piece of evidence—not a complete lecture. Match complexity to the person's
+   language and corrections.
+3. **Name what is forming.** When the person offers an inchoate judgment from
+   experience, give it a short reusable name and connect it to a mechanism.
+4. **Challenge the claim, not the person.** Restate the claim before testing it.
+   Prefer: “What would change your mind?” The answer creates a shared criterion;
+   the assistant does not become the judge.
+5. **Update the map silently.** Record zero to three meaningful changes per
+   turn. Do not ask the person to keep notes or use special commands.
+6. **Offer reachable directions.** Draw one to three next directions from open
+   boundaries. They are proposals, not a menu the person must select. A new
+   judgment or fact from the person may legitimately redirect the exploration.
+
+## Human control and pivots
+
+- Never change the exploration target merely because another direction looks
+  easier or more productive.
+- When the person explicitly changes the target, record the pivot and why while
+  preserving the root question.
+- When a pivot is inferred only during retrospective review, mark it as detected;
+  never present it as something the person explicitly said.
+- Low uptake of the assistant's proposed directions is healthy. It often means
+  the person is supplying the exploration's new facts rather than following the
+  assistant's track.
+
+## Convergence and closure
+
+A boundary has become a candidate for newlife the moment the person can say
+**what measurement would make the answer different**. When that happens, say so
+once — "this one could be settled; want to hand it to newlife?" — and let the
+person decide. Do not push; an exploration is not a funnel.
+
+If four or five directions are open, or no direction has been chosen or retired
+for two or three turns, stop adding branches. Inventory what is understood, the
+reusable frameworks, and the live boundaries; then ask what container or output
+the person wants.
+
+When the person asks to stop, summarize, or turn the exploration into an
+artifact:
+
+- render the current map;
+- separate conclusions, reusable frameworks, unresolved boundaries, abandoned
+  paths, surprises, and pivots;
+- state what evidence was observed versus inferred;
+- record closure in sustained mode (`close`), then copy the record into the
+  person's **research repository** — the one `newlife start` created, the one
+  that holds `questions/` — with `archive --repo <research repo>`: it lands in
+  `explorations/<slug>/process/` there, and the first time it also writes the
+  four-section `README.md` skeleton and an empty `artifacts/`. The archive folder
+  carries the same slug as the workbench, so the two never disagree about which
+  exploration this was. The record does **not** go into the exloop repository;
+- if the exploration produced a question the person wants to freeze and judge in
+  newlife, three commands in this order: `newlife init <slug>` inside the research
+  repository (same slug; it scaffolds `questions/<slug>/` with an `origin/`), then
+  `handoff --repo <research repo>` (it refuses if `init` has not run — writing
+  first would make `init` refuse instead), then invoke the `newlife-goal` skill.
+  If the exploration continues after the handoff, the copy in `origin/` is a snapshot;
+  re-run `handoff --repo … --force` when the record has grown, or rely on `archive` at
+  closure. `handoff` copies the same record into `questions/<slug>/origin/` and writes
+  `goal-draft.md`, a `goal.md`-shaped draft with
+  §1 (where the question came from: root question, pivots and why, surprises,
+  frameworks), §3 (abandoned paths) and §4 (open boundaries) pre-filled from the
+  map. The six anchors stay TODO: they are `newlife-goal`'s job, and nothing
+  in a map can supply a counterparty;
+- do not rate the person, rank the exploration, or declare the chosen direction
+  objectively correct.
+
+## Research boundary
+
+Exploration can generate hypotheses, but it cannot retroactively make an
+analysis confirmatory. Before inspecting outcomes for a confirmatory claim,
+switch to a workflow that locks the hypothesis, analysis, prediction, and
+decision rule first. Label anything already inspected as exploratory. Anything
+run during the exploration counts as *seen* for a later preregistration.
+
+## Authorization boundary
+
+This skill changes conversational behavior and, in sustained mode, writes only
+to its state directory under `~/.exloop/explorations/` (and, on an explicit
+`archive` or `handoff`, into the research repository named by `--repo` or the
+directory named by `--to`). It does not by itself authorize
+web research, repository edits, external messages, purchases, or other side
+effects.

exloop/skills/exloop/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Exploration Loop"
+  short_description: "Human-led exploration with a persistent map"
+  default_prompt: "Use $exloop to explore this question with me and preserve what changes."

exloop/skills/exloop/references/protocol.md

@@ -0,0 +1,140 @@
+# Exploration protocol
+
+Use this protocol to keep the conversation human-led, compact, and cumulative.
+The map is support for the conversation; bookkeeping must never become the
+person's job.
+
+## Shape of a useful turn
+
+A strong turn usually contains no more than:
+
+1. a faithful restatement when the person made a claim;
+2. one new mechanism, distinction, counterexample, or source;
+3. one pressure test or falsifying criterion;
+4. one to three reachable next directions only when they help.
+
+Do not fill all four slots mechanically. A short question can be the whole turn.
+The purpose is to advance one edge and leave room for the person to supply the
+fact or judgment that changes the target.
+
+## Hone without turning it into intake
+
+- Infer complexity from the person's language; do not ask for age, credentials,
+  or background as a substitute for listening.
+- Ask what ambiguity would materially change the path. Avoid questionnaires.
+- After each honing question, offer a candidate restatement that the person can
+  accept, edit, or reject.
+- Stop after two rounds or immediately when the person says to begin.
+
+## Name and challenge
+
+When a judgment is still forming, name it as a reusable object and add its
+mechanism or scope. Do not flatter it or prematurely turn it into a conclusion.
+
+Before challenging a claim, restate it narrowly enough to be testable but not
+narrower than the person intended. The most useful pressure test is usually:
+
+> What observation, counterexample, or cost would make you change this view?
+
+Other useful probes ask which premise is necessary, where the claim should fail,
+or which part has the least support. The assistant proposes the test; the person retains
+the right to accept, revise, or ignore it.
+
+## Marking semantics
+
+Record zero to three marks after a meaningful turn. Never mark merely to make the
+map look busy.
+
+| Kind | Use when | Do not confuse with |
+|---|---|---|
+| `node` | A live concept or direction has opened | A conclusion already understood |
+| `got` | A specific point no longer needs explanation | A reusable framework |
+| `framework` | A named abstraction can be applied again | A fact that can be archived |
+| `stuck` | The person or the assistant cannot advance without a missing fact, distinction, or interpretation | Failure or low ability |
+| `abandoned` | A path is explicitly dropped or has become structurally obsolete | Silence, a topic change, or an unselected suggestion |
+| `surprise` | Something reverses intuition, connects domains, or explains more with less | Any merely interesting fact |
+
+For repeated `stuck` marks, append the new note instead of replacing the old one.
+“Partly resolved” and “the earlier result was not actually tested” are different
+stages of the same boundary and both matter.
+
+## Candidates are not a menu
+
+Generate next directions from live boundaries, not from a generic curriculum or
+what the assistant would most enjoy explaining. State briefly why a direction might be
+valuable. Useful reasons include:
+
+- it may contradict common intuition;
+- another field may supply the missing mechanism;
+- one mechanism may unify several observations;
+- the answer would change a large part of the current map.
+
+The person does not need to select a numbered option. If they reply with a new
+fact or judgment, follow and map that contribution. Do not demand a choice, and
+do not interpret low candidate uptake as failure.
+
+## Converge before the person gets lost
+
+Stop producing new branches when either condition holds:
+
+- four or five live directions are open; or
+- two or three consecutive turns have added suggestions without choosing,
+  resolving, or retiring one.
+
+Inventory the current question, reusable frameworks, understood points, and
+boundaries. Ask which container now matters: another focused question, a memo,
+an experiment, a decision, a design, or simply a map to resume later.
+
+## Evidence hygiene
+
+- Separate what the person said, what a source reports, what the assistant observed
+  in code or data, and what the assistant inferred.
+- A remembered citation or plausible mechanism is not evidence. Verify it when
+  the claim requires verification and the request authorizes research.
+- A retrospective pivot is weaker evidence than an explicitly stated pivot;
+  label the source.
+- Exploration produces hypotheses. If outcome data have already been inspected,
+  subsequent analysis remains exploratory unless tested on unused data under a
+  frozen plan.
+
+## Observed failure patterns
+
+| Temptation | Required correction |
+|---|---|
+| “I should give the complete answer now.” | Advance one edge and preserve room for the person's contribution. |
+| “They ignored my options, so I should ask again.” | Unselected candidates remain open; continue with the person's new material. |
+| “They changed topics, so the old path is abandoned.” | Silence or topic movement is not abandonment; retire only explicit or structurally obsolete paths. |
+| “I cannot paraphrase this, but the person has not said they are confused.” | Record the assistant's own blockage as `stuck`; it identifies missing structure. |
+| “This new direction is clearly better, so I can pivot.” | Only the person's new target supplies the pivot; the assistant may detect and record it, not invent it. |
+| “More explanation is more helpful.” | Prefer one mechanism and one pressure test; verbosity can bury the person's contribution. |
+| “A polished synthesis proves the exploration succeeded.” | Preserve unresolved boundaries and discarded paths; do not rewrite the route as inevitable. |
+
+## Complete example
+
+Person:
+
+> AI makes learning cheap, so universities may disappear. Help me explore that;
+> do not jump straight to an answer.
+
+A suitable first turn:
+
+> Let me check the claim I am hearing: if access to explanation and practice is
+> the university's core function, AI removes enough of that scarcity that the
+> institution loses its reason to exist. I would provisionally call this the
+> **access-cost substitution** view.
+>
+> The pressure point is whether a university's scarce function is actually
+> instruction, rather than credentialing, selection, peer density, or a protected
+> period for identity formation. What evidence would make you say, “AI replaced
+> instruction, but the university still did not become dispensable”?
+
+The hidden map update can contain:
+
+- `framework`: access-cost substitution — institutional value collapses when
+  its scarce input becomes abundant;
+- `stuck`: university's irreducible function — instruction may be only one of
+  several functions;
+- no pivot and no verdict.
+
+This example restates before challenging, names the forming idea, opens a
+falsifiable boundary, and does not take ownership of the final judgment.

exloop/skills/exloop/references/state-model.md

@@ -0,0 +1,157 @@
+# Sustained exploration state
+
+Use file-backed state only when the person explicitly invokes the skill, asks to
+keep a map, or requests a sustained exploration. Conversation-only mode creates
+no files.
+
+## Location and identity
+
+The helper stores state under **one root for every tool**:
+
+```text
+~/.exloop/explorations/<slug>/
+├── events.jsonl
+└── map.md
+```
+
+- The root is `~/.exloop/explorations` unless `EXLOOP_HOME` (or `--root`) says
+  otherwise. It is deliberately not under any tool's own config directory.
+- The `<slug>` is chosen once at `init`: `YYYY-MM-DD-<two-to-four-english-words>`,
+  date = start day, words = the question, not the expected answer. It is the
+  same name the archive folder in the exloop repository will carry. Pass it as
+  `--id` on every command (or set `EXLOOP_ID` for the session). The helper
+  rejects path separators and traversal.
+- **Do not fall back to a thread or session id.** The previous version did, and
+  one exploration split into a Codex directory and a WorkBuddy directory the
+  moment the person switched tools.
+
+One slug carries one exploration. Change the target with a pivot; start a new
+slug for an unrelated exploration. This preserves a stable root question instead
+of silently overwriting history.
+
+## Event contract
+
+`events.jsonl` is append-only and is the source of truth. `map.md` is a derived
+projection that can be regenerated at any time.
+
+| Event | Required content | Meaning |
+|---|---|---|
+| `exploration/started` | root question | Opens the exploration |
+| `exploration/marked` | kind and mark content | Adds or updates a node, framework, boundary, or surprise |
+| `exploration/pivoted` | from, to, why, source | Changes current focus without erasing the root question |
+| `exploration/closed` | optional summary | Records an explicit stopping or synthesis request |
+
+The first three events are shared with the dsh plugin (`hosts/dsh/src/map.ts`),
+so records from either host fold into the same map. `exploration/closed` is this
+skill's addition: real explorations repeatedly produced useful artifacts outside
+the loop and were not reliably archived.
+
+## Projection rules
+
+- A node is identified by `ref`; later marks update its state.
+- Notes append rather than overwrite. Consecutive exact duplicates are ignored.
+- Boundaries retain every note because reversals and partial resolutions matter.
+- Frameworks and surprises are content and are never removed merely because they
+  are old.
+- Understood points are compacted because they no longer need explanation.
+- Abandoned paths retain a short tombstone and the latest reason so they are not
+  suggested again.
+- The map always preserves both the root question and the current focus after a
+  pivot.
+- Retrospectively detected pivots are visibly labeled as detected.
+
+## Helper commands
+
+The helper is `scripts/exploration_state.py` **next to the SKILL.md you are
+reading**; resolve it relative to that file. Installed copies live at
+`~/.claude/skills/exloop/`, `~/.codex/skills/exloop/` and
+`~/.workbuddy/skills/exloop/`; the master is
+`<exloop repo>/skills/exloop/`. Below, `$H` stands for that path.
+
+Find an exploration to resume (slug, open/closed, start day, current question):
+
+```bash
+python3 $H/scripts/exploration_state.py list
+```
+
+Start or resume sustained state:
+
+```bash
+python3 $H/scripts/exploration_state.py init --id 2026-09-05-university-after-ai \
+  --question "Once AI makes learning cheap, which functions of a university remain irreplaceable?"
+```
+
+Record meaningful changes after a turn:
+
+```bash
+python3 $H/scripts/exploration_state.py mark --id 2026-09-05-university-after-ai \
+  --kind framework --ref access-cost-substitution \
+  --label "Access-cost substitution" \
+  --note "When an institution's scarce input becomes abundant, its value has to migrate to another function"
+
+python3 $H/scripts/exploration_state.py mark --id 2026-09-05-university-after-ai \
+  --kind stuck --ref irreducible-university-function \
+  --label "The irreplaceable function of a university" \
+  --note "Teaching may be only one of certification, selection, peer density and identity formation"
+```
+
+Record a person-triggered change of target:
+
+```bash
+python3 $H/scripts/exploration_state.py pivot --id 2026-09-05-university-after-ai \
+  --to "Will the university's certification function also be eroded by AI?" \
+  --why "The person judges that teaching is no longer the hardest part to replace" --source human
+```
+
+Render or inspect the current map (do this at the start of every resumed turn):
+
+```bash
+python3 $H/scripts/exploration_state.py show --id 2026-09-05-university-after-ai
+```
+
+Record explicit closure, then copy the record into the person's research
+repository (the one `newlife start` created):
+
+```bash
+python3 $H/scripts/exploration_state.py close --id 2026-09-05-university-after-ai \
+  --summary "Formed the access-cost substitution framework; certification and peer density still to test"
+python3 $H/scripts/exploration_state.py archive --id 2026-09-05-university-after-ai \
+  --repo ~/Projects/my-research
+```
+
+`archive --repo` lands in `<repo>/explorations/<slug>/process/`, copies
+`events.jsonl` and `map.md` verbatim, and refuses to overwrite a target that
+differs unless `--force` is given. The first time a slug is archived it also
+writes the four-section `README.md` skeleton (question · conclusions · shortfalls ·
+navigation, all TODO) and an empty `artifacts/`; filling them in is the person's
+closing work. `--to <dir>` replaces the derived path when needed.
+
+Hand the exploration to a newlife question (only when the person wants to freeze
+and judge a question that came out of it):
+
+```bash
+python3 $H/scripts/exploration_state.py handoff --id 2026-09-05-university-after-ai \
+  --repo ~/Projects/my-research
+```
+
+`handoff --repo` lands in `<repo>/questions/<slug>/origin/` and refuses when that
+question folder has no `goal.md` — run `newlife init <slug>` there first. It writes
+three files into `origin/`: the same `events.jsonl` and `map.md`,
+plus `goal-draft.md` rendered from the map in the shape of newlife's `goal.md`
+(§1 where the question came from, §3 abandoned paths, §4 open boundaries; the six
+anchors left as TODO). Everything in `origin/` counts as *seen* for the
+preregistration that follows. Same overwrite rule as `archive`.
+
+The helper prints the state directory after initialization and rewrites `map.md`
+after every event. Do not edit `map.md` as if it were the source of truth.
+
+## Operational discipline
+
+- Render the map at the start of a resumed sustained turn before replying.
+- Write zero to three marks per turn; batch only changes that materially affect
+  future conversation.
+- Do not expose shell commands or event bookkeeping unless the person asks.
+- Do not store raw private conversation content unnecessarily. Marks should be
+  concise abstractions, evidence notes, boundaries, and pivots.
+- Do not write long-term personal memory from this skill. The exploration state
+  belongs to this exploration and does not authorize updates to any tool's memory.