--- summary: "Overview and quickstart for monorepo package @tryinget/pi-autoresearch." read_when: - "Starting work in this package workspace." - "Looking for the current pi-autoresearch package surface and boundary." system4d: container: "Monorepo package for the governed pi-autoresearch experiment-loop capability." compass: "Keep the operator affordance obvious while preserving explicit boundaries to Prompt Vault, AK, and ontology." engine: "Scaffold the package shell -> land the bounded runtime kernel -> bind upstream control planes later." fog: "The main risk is recreating the upstream monolith before the package seams are explicit and tested." --- # @tryinget/pi-autoresearch Monorepo package for the governed `pi-autoresearch` capability in Pi. - Workspace path: `packages/pi-autoresearch` - Release component key: `pi-autoresearch` - Extension entry: `extensions/pi-autoresearch.ts` - Current phase: `supervised_dogfood_internal_alpha` - Vision / end-state anchor: [docs/project/vision.md](./docs/project/vision.md) - Product posture anchor: [docs/project/product-posture.md](./docs/project/product-posture.md) - Canonical dogfood playbook: [docs/project/dogfood-playbook.md](./docs/project/dogfood-playbook.md) - Benchmark matrix runbook: [docs/project/benchmark-matrix-runbook.md](./docs/project/benchmark-matrix-runbook.md) ## Why this package exists This package is the local runtime home for the future `pi-autoresearch` experiment loop described in: - [pi-autoresearch RFC](../../docs/project/pi-autoresearch-rfc.md) - [pi-autoresearch foundation status](../../docs/project/pi-autoresearch-foundation-status.md) - [pi-autoresearch architecture correction](../../docs/project/pi-autoresearch-architecture-correction.md) - [pi-autoresearch runtime machine and event-ledger status](../../docs/project/2026-04-16-pi-autoresearch-runtime-machine-and-ledger-status.md) - [Prompt Vault template set](../../docs/project/pi-autoresearch-prompt-vault-template-set.md) - [Prompt Vault rollout](../../docs/project/pi-autoresearch-prompt-vault-rollout.md) - [Ontology concept set](../../docs/project/pi-autoresearch-ontology-concept-set.md) The package started as a small shell and still preserves the recognizable `/autoresearch` operator surface while avoiding a premature re-import of the upstream monolith. The current boundary is now more specific: the package is the runtime owner for the executable experiment-loop machine, while AK and Prompt Vault remain separate durable-truth owners. The long-term destination is captured in [docs/project/vision.md](./docs/project/vision.md): autonomous in execution, governed in authority. ## Current public surface ### Command - `/autoresearch` - may also be launched through the package-owned extension-originated `pi.sendUserMessage` bridge for the exact ASC self-evolution campaign-start prompt; this bridge executes the package-owned plan-only campaign-start front door directly and opens the result editor; it is not a general slash-command parser - with no objective, opens/reports the bounded runtime overview - with `dashboard`, opens a read-only operator dashboard in the editor with current posture, metric contract, candidate decision summary, candidate policy, and next legal surfaces - with `next` or `candidate next`, first surfaces open matrix candidate-review posture when packet inventory is waiting for owner review; otherwise inspects current candidate posture and prepares the recommended reviewable next call: bind when no candidate exists, plan keep/discard/rewind when evidence points there, or the next runtime/finalize call when more samples/rebaseline/finalize is needed - with `bind` or `bind current`, prepares a reviewable `autoresearch_candidate_bind({ ... })` call to inspect a candidate worktree and prepare the exact measurement run call - with `measure` or `measure current`, inspects the candidate worktree and prepares the exact reviewable `autoresearch_runtime_run({ ...candidate metadata... })` measurement call only when candidate intake readiness is `ready`; otherwise it falls back to the `autoresearch_candidate_bind({ ... })` intake review call - with `candidate`, `decision`, `keep`, `discard`, or `rewind`, prepares a reviewable `autoresearch_candidate_decision({ ... })` call for status or plan-only lifecycle decisions - with `open candidates`, opens a read-only open candidate-review posture summary with counts, sample cell inventory, explicit discovered candidate-result packet paths, the exact owner-review call seeded with those paths, and the post-fan-in finalizer/token-request handoff for candidates found useful; this does not keep/discard/finalize, merge/reset worktrees, or write evidence - with `integrate candidates`, opens a read-only useful-candidate integration handoff: first run owner review over explicit candidate-result packet paths, then request the `post_fanin_finalizer` / `finalize_post_fanin` token for selected useful lanes; it does not apply patches, merge, promote, cleanup worktrees, or write evidence - with `review` or `review keep|discard|rewind`, opens the final owner decision surface after measured packet inventory is complete; it shows a read-only candidate-decision overlay selector before the editor checklist when TUI overlays are available, and falls back to the editor otherwise - with `learning`, `learning export`, or `learning handoff`, prepares the exact `autoresearch_runtime_status({ action: "learning_export" })` call for review so the returned packet path can be handed to the owner-routed KES adapter - with `overlay` or `fullscreen`, opens a read-only live TUI dashboard overlay with periodic refresh and recent-run table - with `export`, writes `.autoresearch/autoresearch-dashboard.html` as measured packet inventory inspection (candidate-result packets, selected lanes, open candidate-review cells, exported counts, and `export_visibility_blockers` before owner review), opens it in the browser when possible, and refreshes the file every ~2s for the current Pi session; `export off` stops the refresher - with `widget on|off`, shows or hides the persistent above-editor status widget for the current session; the widget labels candidate runs, final kept runs, and `checks-failed` receipts separately so historical failed checks are not confused with promotion/finalization state - with `run|loop|go|start `, executes the first bounded foreground autoresearch campaign directly (`runMode: "bounded_loop"`, three-iteration/default 30-minute budget, peer lane planned only) so the operator can give one explicit start instruction and step away until budget/gates stop it - with any other objective, prepares a reviewable `autoresearch_campaign_start({ ... })` tool call in the editor - keeps durable authority explicit: direct first-entrypoint runs stay bounded/local and still do not secretly spawn peers, commit, merge/delete worktrees, write AK/KES evidence, or promote candidates - `$$ autoresearch ` / `$$ ar ` through the declared `@tryinget/pi-trigger-adapter` package seam - registers the picker lazily through the lightweight adapter; it does not probe the heavier `@tryinget/pi-interaction` umbrella package - opens the picker for plan-only, governed setup plan, baseline, or bounded-loop campaign-start modes when the shared pi-interaction input runtime is active - replaces the editor text with the exact `autoresearch_campaign_start({ ... })` call selected by the operator - degrades to the deterministic input fallback if picker registration cannot initialize, while validation treats a missing required adapter link as install drift - `$$ autoresearch next` / `$$ ar next` - deterministically inserts open candidate-review posture with explicit candidate-result packet paths and a finalizer handoff when matrix packet inventory is waiting; otherwise inserts the recommended next candidate call using the same read-only candidate-decision posture as the dashboard - remains review-first; no benchmark, worktree command, or durable promotion is executed automatically - `$$ autoresearch integrate candidates` / `$$ ar integrate candidates` - deterministically inserts the useful-candidate integration handoff with explicit review and post-fan-in finalizer calls - remains token-gated; no patch application, merge, cleanup, evidence write, or promotion is executed automatically - `$$ autoresearch bind|measure [current|]` / `$$ ar bind|measure [current|]` - when the shared pi-interaction input runtime is active, opens a candidate-bind/measure picker that inserts either the exact `autoresearch_candidate_bind({ ... })` inspection call or the exact `autoresearch_runtime_run({ ...candidate metadata... })` measurement call selected by the operator - also has a deterministic input fallback so candidate intake/measurement does not get mistaken for a campaign objective - remains review-first; the bind path is read-only/plan-only, and the measure path only prepares the run call for review rather than executing it automatically when intake readiness is `ready` - `$$ autoresearch candidate` / `$$ ar candidate` and `$$ autoresearch keep|discard|rewind` - when the shared pi-interaction input runtime is active, opens a candidate-decision picker for status, keep, discard, or rewind planning - decorates direct and currently recommended choices when runtime receipts make that possible - replaces the editor text with the exact `autoresearch_candidate_decision({ ... })` call selected by the operator - also has a deterministic input fallback so non-slash `$$ autoresearch ...` is not captured by PTX's `$$ /template` namespace - remains read-only/plan-only; no worktree command or durable promotion is applied by the picker/fallback ### Tools - `autoresearch_campaign_start` - is the supervised campaign front door from one bounded optimization objective - composes existing autoplan/setup/loop surfaces instead of inventing a second runtime - supports `runMode: "plan_only" | "baseline" | "bounded_loop"` - supports `setupMode: "autoplan" | "prompt_vault_setup"`; governed setup uses the package-owned Prompt Vault decision runner and typed parser - reports campaign name, metric contract, scope, candidate lifecycle policy, warnings/gates, current machine state, and the next exact tool call - supports a policy-only `candidatePolicy` for worktree-based keep/discard/rewind choices; default keep preserves the branch, default discard suggests cleanup after receipt review, and default rewind resets the candidate worktree to base - keeps Replay Fabric as observer/history/recovery-clue projection and ASC rewind as live Pi/session recovery; neither becomes the candidate accept/discard executor - does not auto-spawn peers, commit, merge/delete worktrees, write AK/KES/evidence, or perform durable promotion - `autoresearch_candidate_bind` - is the read-only / plan-only candidate intake planner - inspects a controller-verified candidate worktree/path, detects git worktree status, same-repository posture, branch/ref, HEAD, optional or inferred base-ref resolution, changed files, and a diff summary - infers a conservative base ref from `merge-base(HEAD, upstream|main|master)` when `candidateBaseRef` is omitted, while warning the operator to verify before destructive rewind planning - prepares the exact `autoresearch_runtime_run({ ... candidateWorktree, candidateBranch, candidateBaseRef, candidateDiffSummary, candidateFilesChanged ... })` call needed to bind and measure the candidate - reports intake readiness as `ready`, `needs_review`, or `blocked`, with reasons when the candidate is on trunk, shares the controller cwd, lacks a resolved base, has no detected files, is broad, or is not a usable worktree - defaults `candidateWorktree` to `cwd` so `/autoresearch bind current` supports the common current-worktree handoff - slash and dollar bind shortcuts omit placeholder base refs so the planner can infer a reviewable base instead of treating `""` as literal input - surfaces read-only git preflight commands and warnings when the worktree or base ref is missing - does not run benchmarks, merge, delete/reset worktrees, spawn peers, write AK/KES/evidence, or promote - `autoresearch_candidate_decision` - is the read-only / plan-only candidate lifecycle decision workbench - supports `action: "status" | "plan_keep" | "plan_discard" | "plan_rewind"` - consumes current runtime status, segment closeout, and candidate-result evidence to summarize candidate source, worktree, branch/ref/base, changed files, and diff summary when bound - when `autoresearch_runtime_run` receives a real existing `candidateWorktree`, benchmark and checks commands execute from that candidate worktree while receipts remain in the controller cwd - reports empirical posture, promotion readiness, confidence/noise interpretation, checks status, baseline-drift risk, and live candidate artifact posture before suggesting a lifecycle decision - recommends keep, discard, rewind, rebaseline, collect more samples, re-bind/re-measure a stale visible candidate artifact, finalize, or no candidate bound yet - returns exact next tool calls and plan-only git commands such as `git -C reset --hard ` without applying them - keeps worktree lifecycle as the candidate primitive; Replay Fabric remains observer/history/recovery-clue only, ASC rewind remains live Pi/session recovery only, and durable promotion remains external - refuses to turn receipt-only visible candidate-peer evidence into keep/finalize guidance when the referenced candidate worktree and branch are gone; it surfaces `rebind_candidate` instead so stale packets are not mistaken for live promotion material - does not merge, delete worktrees, reset worktrees, spawn peers, write AK/KES/evidence, or promote - `autoresearch_runtime_status` - returns the current bounded-runtime status - supports `action: "dashboard"` for a compact read-only operator dashboard that is easier to scan than the full diagnostic status and now includes the same candidate decision summary/next legal surface plus a unified Authority handoff section for closeout, `ak_evidence`/suggested `evidence_record(...)`, `learning_export` -> owner-routed KES adapter, and `oracle_evidence_export` -> DSPx owner preflight calls - can build a package-local segment closeout packet (`action: "closeout"`, packet kind `autoresearch.closeout.v1`) summarizing runs, hypotheses, candidate bindings, empirical decision, timing interpretation, recommended action, Oracle-ready evidence readiness, and the adapter/evidence boundary before external promotion - can build a non-mutating Oracle-ready evidence packet (`action: "oracle_evidence"`, packet kind `autoresearch.oracle_evidence.v1`) and locally export it for DSPx owner preflight (`action: "oracle_evidence_export"`, default `.autoresearch/oracle_evidence.json`) with run-level empirical records; export is an explicit local write unavailable in read profile, constrained under `cwd/.autoresearch/`, and overwrite-gated; it does not write Oracle Postgres, migrate local `coordinates.db`, write AK/KES, choose winners, or promote - can build a non-mutating exact-task AK evidence packet (`action: "ak_evidence"`, `akTaskId`, packet kind `autoresearch.ak_evidence.v1`) with a suggested explicit `evidence_record(...)` controller call; it does not mutate AK itself - can build an adapter-ready learning/KMS packet (`action: "learning"`, packet kind `autoresearch.learning.v1`) and locally export that packet for owner-routed KES/notes handoff (`action: "learning_export"`, default `.autoresearch/learning.json`); export is an explicit local write unavailable in read profile, constrained under `cwd/.autoresearch/`, and overwrite-gated; it does not write AK/KES, external authority, or promotion state - can build a candidate-result packet (`action: "candidate_result"`, packet kind `autoresearch.candidate_result.v1`) and locally export it for owner-visible candidate-wave review (`action: "candidate_result_export"`, default `.autoresearch/candidate-result.json`); exports under `.autoresearch/candidate-wave/` include a default-discovery aggregate `review_candidate_wave` call seed, while explicit packet paths remain available when planned-but-missing lanes should appear as `missing_packet`; export is an explicit local write unavailable in read profile, constrained under `cwd/.autoresearch/`, and overwrite-gated, and it does not mutate candidate lifecycle, worktrees, AK/KES/evidence, or promotion state. Matrix dashboard/export discovery now surfaces an explicit open candidate-review posture so packet counts are visible as review inventory rather than live keep/finalize authority. The runtime also has a production cleanup surface (`action: "candidate_inventory_cleanup_plan"` then `action: "candidate_inventory_cleanup_apply"` with `operatorConfirmation: "ARCHIVE STALE AUTORESEARCH CANDIDATES"`) that archives both root runtime receipts and matrix/candidate packet projections under a fresh safe-slug `.autoresearch/closed-candidates/