@tduyng/pi-autoresearch 0.0.2 → 0.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +47 -57
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,45 +1,37 @@
1
1
  # @tduyng/pi-autoresearch
2
2
 
3
- An autonomous experiment loop for pi that costs nothing until you type `/autoresearch`.
4
- Two tools and one log. The model reads the benchmark, decides keep or discard, and the tools do the
5
- bookkeeping: commit, revert, scope, script hash, noise floor, and one line of context back.
3
+ An experiment loop you turn on with one command. Measure, read the number, keep or discard, and let the tools handle git, scope, and the noise floor.
6
4
 
7
- ## Cold start
5
+ ## What it costs
8
6
 
9
- Nothing is registered at load: no tool, no skill, no system prompt block. The extension adds one slash
10
- command. The tools are registered and declared to the model only when `/autoresearch` runs, and removed on
11
- `off`, `clear`, or when `max_runs` is reached.
7
+ Nothing at cold start. No tool, no skill, no system prompt block: the extension adds one slash command, and that is free until typed. The two tools are declared to the model only while `/autoresearch` runs, and removed on `off`, `clear`, or when `max_runs` is reached.
8
+
9
+ The saving is the second half of every optimization loop. Editing a benchmark, committing a regression, and re-reading a whole log by hand are the parts that cost turns, and all three are one line of bookkeeping here.
12
10
 
13
11
  ## The loop
14
12
 
15
- ```
13
+ ```text
16
14
  edit -> run_experiment -> read the output -> log_experiment -> repeat
17
15
  ```
18
16
 
19
- `run_experiment` snapshots the working tree, runs `.auto/measure.sh`, parses `METRIC name=value` lines, runs
20
- the optional checks, and returns the output, the metrics, the changed files, the noise advice, and the
21
- scope violations. It does not touch git history.
17
+ `run_experiment` snapshots the working tree, runs `.auto/measure.sh`, parses `METRIC name=value` lines, runs the optional checks, and returns the output, the metrics, the changed files, the noise advice, and the scope violations. It does not touch git history.
22
18
 
23
- `log_experiment` takes `status: keep | discard | crash | checks_failed` and the model's reasoning in `asi`.
24
- A `keep` commits the files the run touched with a conventional subject built from the description. Every
25
- other status restores those files. A run inside the noise band, a crash, or a scope violation is reported,
26
- not auto-decided: the model chooses.
19
+ `log_experiment` takes `status: keep | discard | crash | checks_failed` and the model's reasoning in `asi`. A `keep` commits the files the run touched with a conventional subject built from the description. Every other status restores those files. A run inside the noise band, a crash, or a scope violation is reported rather than decided, because a rule cannot know whether the diff caused the gain.
27
20
 
28
21
  ## What it adds over the usual loop
29
22
 
30
23
  | Mechanism | Why |
31
24
  | --- | --- |
32
- | Model owns keep or discard | a rule cannot know whether the diff caused the gain, or whether simpler code is worth 1% |
33
- | Full benchmark output | phase timings and errors reach the model, so the next hypothesis comes from data |
34
- | Noise floor from median absolute deviation | advice that separates jitter from a real win; confidence never overrides the model |
35
- | Pending measurement | one run between the two tools, crash-safe on disk, so a restart can still log it |
36
- | Scope globs in frontmatter | a keep cannot touch files outside the declared scope |
37
- | Benchmark script hash | editing the benchmark to move the number voids the comparison; `/autoresearch rebaseline` starts a new segment |
38
- | Worktree lock and dirty baseline | one loop per worktree, and files another session left dirty are never committed or reverted |
39
- | Finalize in temporary worktrees | kept runs become branches without moving HEAD under another session |
40
- | Compaction digest from disk | the prompt body, recent runs, dead ends and ideas survive a context reset, no LLM call |
41
- | Conventional commits | `type(scope): summary`, at most 72 characters, one `Metric:` trailer, built by the tool from validated parts |
42
- | Lazy tool registration | zero tokens at cold start |
25
+ | Model owns keep or discard | A rule cannot tell whether 1% came from the diff, or whether simpler code is worth 1% |
26
+ | Full benchmark output | Phase timings and errors reach the model, so the next hypothesis comes from data |
27
+ | Noise floor from median absolute deviation | Advice that separates jitter from a real win, and confidence never overrides the model |
28
+ | Pending measurement | One run between the tools, crash-safe on disk, so a restart can still log it |
29
+ | Scope globs in frontmatter | A keep cannot touch files outside the declared scope |
30
+ | Benchmark script hash | Editing the benchmark to move the number voids the comparison |
31
+ | Worktree lock and dirty baseline | One loop per worktree, and files another session left dirty are never committed |
32
+ | Finalize in temporary worktrees | Kept runs become branches without moving HEAD under another session |
33
+ | Compaction digest from disk | Prompt, recent runs, dead ends, and ideas survive a reset with no model call |
34
+ | Conventional commits | `type(scope): summary`, at most 72 characters, one `Metric:` trailer, built from validated parts |
43
35
 
44
36
  ## Files
45
37
 
@@ -64,49 +56,47 @@ What is optimized, the constraints, and what a good change looks like.
64
56
 
65
57
  | File | Purpose |
66
58
  | --- | --- |
67
- | `.auto/prompt.md` | frontmatter config plus the objective and what has been tried |
68
- | `.auto/measure.sh` | benchmark, prints `METRIC name=value` |
69
- | `.auto/log.jsonl` | append-only record |
70
- | `.auto/checks.sh` | optional correctness checks, run after a passing benchmark |
71
- | `.auto/ideas.md` | optional backlog of ideas not tried yet |
72
- | `.auto/pending.json` | the run waiting for a decision |
73
- | `.auto/lock.json` | the session that owns this worktree |
59
+ | `.auto/prompt.md` | Frontmatter config, the objective, and what has been tried |
60
+ | `.auto/measure.sh` | The benchmark, printing `METRIC name=value` |
61
+ | `.auto/log.jsonl` | Append-only record |
62
+ | `.auto/checks.sh` | Optional correctness checks, run after a passing benchmark |
63
+ | `.auto/ideas.md` | Optional backlog of ideas not tried |
64
+ | `.auto/pending.json` | The run waiting for a decision |
65
+ | `.auto/lock.json` | The session that owns this worktree |
74
66
 
75
- `.auto/` is added to the repository's common `.git/info/exclude` on the first run, so none of it lands in a
76
- commit, including from a linked worktree.
67
+ `.auto/` is added to the repository's `.git/info/exclude` on the first run, including from a linked worktree, so none of it lands in a commit.
77
68
 
78
- Run it in an interactive pi session or through RPC. `pi -p` exits as soon as the slash command returns,
79
- before the loop's first turn, so a print run cannot drive the loop.
69
+ Run it in an interactive session or through RPC. `pi -p` exits as soon as the slash command returns, before the loop's first turn, so a print run cannot drive it.
80
70
 
81
71
  ## Commands
82
72
 
83
73
  | Command | Effect |
84
74
  | --- | --- |
85
- | `/autoresearch <goal>` | start a session, or resume the one in `.auto/` |
86
- | `/autoresearch status` | print the digest |
87
- | `/autoresearch off` | stop and remove the tools |
88
- | `/autoresearch rebaseline` | accept a changed benchmark script as a new baseline |
89
- | `/autoresearch finalize` | split kept runs into independent branches from the merge-base |
90
- | `/autoresearch clear` | delete the log and stop |
75
+ | `/autoresearch <goal>` | Start a session, or resume the one in `.auto/` |
76
+ | `/autoresearch status` | Print the digest |
77
+ | `/autoresearch off` | Stop and remove the tools |
78
+ | `/autoresearch rebaseline` | Accept a changed benchmark script as a new baseline |
79
+ | `/autoresearch finalize` | Split kept runs into independent branches from the merge-base |
80
+ | `/autoresearch clear` | Delete the log and stop |
91
81
 
92
- `finalize` groups kept runs by file overlap and creates one branch per group from the merge-base in
93
- temporary worktrees. The current worktree is never checked out to another branch. It verifies that the
94
- union of the branches matches the original branch before reporting.
82
+ `finalize` groups kept runs by file overlap and creates one branch per group from the merge-base in temporary worktrees. The current worktree is never checked out to another branch, and the union of the branches is verified against the original before it reports.
95
83
 
96
84
  ## Worktrees and other sessions
97
85
 
98
- One loop owns a worktree at a time. `/autoresearch` takes `.auto/lock.json`, and a second session in the same
99
- worktree is refused before it can run anything. Files that were already dirty when the loop started are
100
- recorded in the lock and never committed or reverted.
86
+ One loop owns a worktree at a time: `/autoresearch` takes `.auto/lock.json` and refuses a second session before it can run anything. Files that were already dirty when the loop started are recorded in the lock and never committed or reverted.
101
87
 
102
- For a second loop on the same repository, use a separate git worktree. Each worktree has its own `.auto/`,
103
- its own branch, and its own log. The first run on trunk creates `autoresearch/<name>-<timestamp>` in a git
104
- worktree at `~/worktrees/<repo>/autoresearch-<name>-<timestamp>`, and the shared checkout stays on trunk. Start
105
- pi in that directory to run the loop. An existing feature branch is used as it is.
88
+ For a second loop, use a separate git worktree, which gets its own `.auto/`, branch, and log. The first run on trunk creates `autoresearch/<name>-<timestamp>` in a worktree at `~/worktrees/<repo>/autoresearch-<name>-<timestamp>` and leaves the shared checkout on trunk. An existing feature branch is used as it is.
106
89
 
107
90
  ## Compaction and restarts
108
91
 
109
- While the loop is active, `session_before_compact` replaces pi's LLM summary with a deterministic digest
110
- built from `.auto/`: the prompt body, the recent runs, kept runs, dead ends, ideas, and any pending
111
- measurement. After a restart of the same session, the loop re-arms from the session's activation entry and
112
- sends one short resume message. A fresh session never auto-activates.
92
+ While the loop is active, `session_before_compact` replaces pi's model summary with a deterministic digest built from `.auto/`: the prompt body, recent runs, kept runs, dead ends, ideas, and any pending measurement. No model call, no lost history.
93
+
94
+ After a restart of the same session the loop re-arms from the session's activation entry and sends one short resume message. A fresh session never auto-activates.
95
+
96
+ ## Install
97
+
98
+ ```bash
99
+ pi install npm:@tduyng/pi-autoresearch
100
+ ```
101
+
102
+ Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-autoresearch`
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@tduyng/pi-autoresearch",
3
- "version": "0.0.2",
4
- "description": "Autonomous experiment loop with zero cold-start cost: measure, decide, commit or revert, with scope and benchmark guards.",
3
+ "version": "0.0.3",
4
+ "description": "Autonomous experiment loop that costs nothing until you type /autoresearch: measure, decide, commit or revert, with scope and benchmark guards.",
5
5
  "keywords": [
6
6
  "pi",
7
7
  "pi-package",