exloop 0.2.0__tar.gz → 0.3.0__tar.gz

{exloop-0.2.0 → exloop-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: exloop
-Version: 0.2.0
+Version: 0.3.0
 Summary: Human-led exploration skills for any AI tool that reads SKILL.md: a persistent map, structured idea comparison, and a zero-dependency state helper.
 Project-URL: Repository, https://github.com/hzshen88/exloop
 Project-URL: Issues, https://github.com/hzshen88/exloop/issues
@@ -20,6 +20,8 @@ Description-Content-Type: text/markdown
 **Human-led exploration with a persistent map.** An AI companion that does not answer
 your question for you: it asks one or two honing questions, walks one edge at a time,
 keeps a map of where you have been, and offers the next step that is within reach. When
+you do not yet have enough language or background to form a question, it first offers one
+concrete foothold and lets your response set the direction. When
 several explanations are in play, Idea Lab helps draw, attack, compare, and check them
 without forcing an early winner. Both ship as skills for any AI tool that reads
 `SKILL.md` files — Claude Code, Codex, and the like.
@@ -69,7 +71,8 @@ explanations need to be made explicit, challenged, and distinguished.
 ## What is in the package
 
 - `skills/exloop/SKILL.md` with its references: the protocol (four events — started,
-  marked, pivoted, closed — and the map as their projection) and the state model.
+  marked, pivoted, closed — and the map as their projection), the state model, and a
+  bounded evidence-review method that returns source checks to the current exploration.
 - `skills/idea-lab/SKILL.md` with domain profiles for formal theory, empirical and causal
   research, simulation, engineering and product mechanisms, and interpretive research.
 - `skills/exloop/scripts/exploration_state.py`: the zero-dependency helper the skill

{exloop-0.2.0 → exloop-0.3.0}/README.md

@@ -3,6 +3,8 @@
 **Human-led exploration with a persistent map.** An AI companion that does not answer
 your question for you: it asks one or two honing questions, walks one edge at a time,
 keeps a map of where you have been, and offers the next step that is within reach. When
+you do not yet have enough language or background to form a question, it first offers one
+concrete foothold and lets your response set the direction. When
 several explanations are in play, Idea Lab helps draw, attack, compare, and check them
 without forcing an early winner. Both ship as skills for any AI tool that reads
 `SKILL.md` files — Claude Code, Codex, and the like.
@@ -52,7 +54,8 @@ explanations need to be made explicit, challenged, and distinguished.
 ## What is in the package
 
 - `skills/exloop/SKILL.md` with its references: the protocol (four events — started,
-  marked, pivoted, closed — and the map as their projection) and the state model.
+  marked, pivoted, closed — and the map as their projection), the state model, and a
+  bounded evidence-review method that returns source checks to the current exploration.
 - `skills/idea-lab/SKILL.md` with domain profiles for formal theory, empirical and causal
   research, simulation, engineering and product mechanisms, and interpretive research.
 - `skills/exloop/scripts/exploration_state.py`: the zero-dependency helper the skill

{exloop-0.2.0 → exloop-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "exloop"
-version = "0.2.0"
+version = "0.3.0"
 description = "Human-led exploration skills for any AI tool that reads SKILL.md: a persistent map, structured idea comparison, and a zero-dependency state helper."
 readme = "README.md"
 license = "Apache-2.0"

{exloop-0.2.0 → exloop-0.3.0}/skills/exloop/SKILL.md

@@ -36,23 +36,21 @@ 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
+## Set up only the persistence the person requested
 
-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:
+The person should never have to type a shell command. Conversation-only exploration needs
+no setup. Sustained exploration uses the helper already shipped with exloop; initialize its
+map and continue without installing NewLife.
 
-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.
+If the person explicitly asks to establish the full NewLife research workflow, install a
+compatible NewLife package and run `newlife start .` in the named repository. Say what will
+be installed and where before changing the environment. A request to explore, keep an
+exloop map, verify a source, or archive into an existing research repository does not by
+itself authorize another package or host-wide skill installation.
 
-Say what you installed and where; never install anything else on the strength of this.
+Run exloop's own helper commands when their documented trigger occurs. Offer `newlife init`
+and formal handoff only when NewLife is available and the person chooses to formalize the
+boundary.
 
 ## What you make while exploring goes into the research repository, not a temp directory
 
@@ -86,12 +84,21 @@ exactly how one exploration in 2026-08 ended up in three directories.
 
 ## Core loop
 
+Before step one, check whether the person can enter the question yet. If they want to
+explore but lack the language, background or current state to form a usable question, use
+the **receive — offer one foothold — return direction** move in
+[the protocol](references/protocol.md). This is a conditional opening move, not a new stage,
+profile or state transition. Skip it when the person already has a direction or wants a
+direct answer.
+
 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.
+   language and corrections. When a material factual or novelty claim needs a
+   source, use [the bounded evidence review](references/evidence-review.md) and
+   return its evidence to this same edge; lookup is not a stage transition.
 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.
@@ -159,8 +166,8 @@ artifact:
   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
+  person's named **research repository** — including one created by `newlife start` —
+  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

exloop-0.3.0/skills/exloop/references/evidence-review.md

@@ -0,0 +1,63 @@
+# Bounded evidence review
+
+Use this reference when a claim inside an exploration materially depends on a source,
+prior method, factual precedent, or novelty judgment. It is an operation inside the current
+conversation or exploration, not a new stage.
+
+## Start with a bounded question
+
+Write down, in one sentence each:
+
+- the exact claim to check;
+- what current choice or candidate route the answer could change;
+- what would count as enough evidence for that choice.
+
+If the request already supplies these, use them. Do not interview the person again. If the
+claim is incidental and cannot change the work, mark it unverified and continue rather than
+opening an unbounded survey.
+
+## Gather evidence in this order
+
+1. Check the current repository, cited artifact and prior work already supplied. Preserve
+   exact paths, versions and dates.
+2. When external lookup is authorized and needed, prefer primary sources: the paper for a
+   scientific claim, official documentation or source code for a technical claim, and the
+   original dataset/registry for a data claim.
+3. Read enough of the method and limitations to test the exact claim. A title, abstract,
+   search snippet or secondary paraphrase is not evidence for a precise implementation or
+   boundary claim.
+4. Seek the strongest relevant counterexample or conflicting source. Explain differences
+   in population, mechanism, implementation, measurement or date rather than averaging
+   incompatible evidence into one confidence label.
+5. Record what was directly observed, what is inferred, and what remains unknown. “No
+   source found” means unresolved, never novel or false.
+
+For a broad question, split independent searches only when the available host and the
+person's request allow delegation. Sequential work is equally valid. Report every
+pre-specified branch, including disconfirming evidence; do not search variants until one
+supports the favored route.
+
+## Return to the caller
+
+Return a compact evidence packet:
+
+```markdown
+**Claim checked:** <exact claim>
+**Finding:** supported | contradicted | mixed | unresolved
+**Evidence:** <source, version/date, and the fact it establishes>
+**Limits:** <what the evidence does not establish>
+**Effect on the current exploration:** <which route/assumption changed, or none>
+```
+
+Then resume the question or comparison that requested the check. Do not create a formal
+question, analysis plan, preregistration, repository edit or new persistent ledger merely
+because the lookup finished. Those actions require their own request or transition.
+
+## Provenance
+
+This bounded form adapts the useful source-grounding and anti-cherry-picking principles in
+K-Dense's Science-Superpowers `surveying-prior-work` and
+`dispatching-parallel-investigations`, pinned for this integration at commit
+`ccc1b2d41a389b2d6dadf1945603f81d66c5e85e` (MIT). The text and stage boundaries here are
+specific to exloop and were rewritten for its single-state workflow.
+

{exloop-0.2.0 → exloop-0.3.0}/skills/exloop/references/protocol.md

@@ -17,6 +17,25 @@ 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.
 
+## Make the question enterable when needed
+
+Use this opening move only when the person wants to explore but lacks the language,
+background or current state needed to form a usable question:
+
+1. **Receive.** Reflect the curiosity or difficulty without classifying the person. If they
+   explicitly sound tired or overwhelmed, reduce the ambition of the turn and leave stopping
+   as a valid path.
+2. **Offer one foothold.** Give one concrete example, distinction or minimal model they can
+   inspect. Supply only enough common ground for them to participate, not a prerequisite
+   lecture.
+3. **Return direction.** Ask what in that foothold feels alive, strange or connected to
+   their experience. Treat their answer, correction or rejection as the source of the
+   direction, then enter the ordinary exploration loop.
+
+Do not use an intake questionnaire, assign a readiness level, persist a deficit judgment or
+require a research-shaped question. Skip this move when the person already has a direction
+or only wants a direct answer.
+
 ## Hone without turning it into intake
 
 - Infer complexity from the person's language; do not ask for age, credentials,
@@ -105,6 +124,7 @@ an experiment, a decision, a design, or simply a map to resume later.
 | “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. |
+| “They cannot answer my honing question, so I should diagnose their readiness or ask for background.” | Offer one concrete foothold, let their response supply direction, and keep any inference temporary and correctable. |
 | “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. |

{exloop-0.2.0 → exloop-0.3.0}/skills/exloop/references/state-model.md

@@ -109,8 +109,8 @@ Render or inspect the current map (do this at the start of every resumed turn):
 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):
+Record explicit closure, then copy the record into the person's named research
+repository (which may be one `newlife start` created):
 
 ```bash
 python3 $H/scripts/exploration_state.py close --id 2026-09-05-university-after-ai \

{exloop-0.2.0 → exloop-0.3.0}/skills/exloop/scripts/exploration_state.py

@@ -9,8 +9,8 @@ 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/`,
+Where the record goes when the exploration ends is the person's named **research repository**
+(including one created by `newlife start`): `archive --repo` puts it under `explorations/<slug>/process/`,
 `handoff --repo` under `questions/<slug>/origin/`. Not the exloop repository.
 """
 
@@ -431,8 +431,8 @@ def command_list(args: argparse.Namespace) -> None:
 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,
+    `--repo` is the person's named research repository. 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.
     """

{exloop-0.2.0 → exloop-0.3.0}/skills/idea-lab/SKILL.md

@@ -17,8 +17,9 @@ their original idea merely because another route is easier to formalize.
 - For a short exchange, use this pattern in conversation only.
 - **REQUIRED SUB-SKILL:** Use `exloop` when the person asks for sustained
   exploration, a persistent map, or a handoff into a research repository.
-- Use `surveying-prior-work` when source verification, prior art, or a novelty
-  judgment becomes material.
+- When source verification, prior art, or a novelty judgment becomes material,
+  follow [the bounded evidence review](../exloop/references/evidence-review.md),
+  then return to this comparison. It does not advance the workflow.
 - Hand off to `newlife-goal` only when the person can say what observation or
   measurement would make the answer different.