@hobin/developer 0.1.8 → 0.1.9

package/README.md

@@ -1,12 +1,19 @@
-# @hobin/developer
+# Developer for Pi
 
-Adaptive product-development judgment for [Pi](https://pi.dev).
+Developer helps [Pi](https://pi.dev) stop guessing, choose the right design or
+review method, make one justified change, and show the evidence behind it.
 
-Developer combines a small, branch-aware coordination extension with ten
-independent skills. It routes one concrete question or green-to-green movement
-at a time, records the resulting evidence, and preserves unresolved questions.
-Its default topology gives feature work a useful backbone without turning every
-task into a fixed lifecycle.
+Use it when a task may hide product rules, consequential cases, ownership,
+compatibility, structural timing, or pass-but-wrong verification. Developer:
+
+- turns consequential uncertainty into explicit questions;
+- routes Pi to one of ten focused judgment skills;
+- loads deeper references only when an observable trigger calls for them;
+- keeps implementation, unresolved questions, and verification evidence visible
+  on the current session branch.
+
+Developer is adaptive rather than phase-driven. It does not force every task
+through a fixed plan, design, implementation, and review sequence.
 
 ## Install
 
@@ -22,308 +29,225 @@ Try it for one run without installing:
 pi -e npm:@hobin/developer
 ```
 
-## Quick start
-
-Start Pi, turn Developer on, and describe the product task normally:
+Start Pi and enable Developer:
 
 ```text
 /develop on
-The selected payment method disappears after navigating back to checkout. Find the cause and fix it.
 ```
 
-Developer decides whether the next concrete question would benefit from a focused
-skill or is already justified as implementation action. You do not need to call
-its internal protocol tools yourself. While Developer is on, Pi's built-in shell
-and artifact tools follow the active route.
+Run `pi list` if you want to confirm that the package is installed.
 
-## Commands
+## Try it
 
-| Command | Effect |
-| --- | --- |
-| `/develop` | Open the non-overlay Developer settings surface |
-| `/develop on` | Enable adaptive routing and route-bound access to Pi built-in `bash`, `edit`, and `write` |
-| `/develop status` | Inspect current branch state in a read-only panel |
-| `/develop questions` | Choose an unresolved question, answer it or request investigation, and submit it to Pi |
-| `/develop off` | Disable the protocol and clear current protocol state |
+Describe the product task normally. You do not need to name a skill or call an
+internal protocol tool.
+
+```text
+/develop on
+The selected payment method disappears after navigating back to checkout.
+Find the cause and fix it.
+```
 
-Explicit command arguments participate in Pi's completion UI. In interactive
-use, turning Developer off while a route or unresolved question exists requires
-confirmation. The historical session entries remain; only current protocol
-state is cleared.
+Depending on what the repository already establishes, Developer may ask for a
+missing product decision, inspect the relevant behavior, route a focused model
+or sketch, permit one implementation movement, and require evidence before the
+changed work is treated as complete.
 
-Start a non-interactive or preconfigured session with Developer enabled:
+Other useful first requests:
 
-```sh
-pi --develop
+```text
+Add scheduled invoice delivery.
+Clarify any missing product rules before editing.
 ```
 
-## Activation and tool policy
-
-Developer has one boolean setting: on or off. When on, adaptive routing and the
-route-bound tool policy always apply. Pi built-in `bash` is available during
-skill and implementation routes; built-in `edit` and `write` require an active
-`implementation` route and no `before-implementation` gate. When off, Developer
-clears current protocol state and restores only tools that it withheld.
-
-The tool policy and question gates are workflow-integrity controls, not a security
-sandbox. A skill route receives the shell execution lane needed for repository
-inspection and verifier execution, while structured `edit`/`write` mutation
-remains implementation-only. Shell commands are not parsed as a security language; skill
-contracts prohibit artifact mutation, and adversarial evaluation checks the
-workspace boundary. Developer recognizes Pi built-ins from their provenance,
-preserves unrelated active tools, and does not force-enable tools the user
-disabled.
-
-Before Pi tears down a session runtime, Developer releases its route-bound tool
-delta so a reload, session replacement, or later extension instance does not
-inherit orphaned restrictions. After that release, the package records a
-reload-safe lifecycle marker. If an in-process reload finds older Developer
-history without a later release marker, Developer stays off and requires a full
-Pi process restart. Neither `/reload` nor `/develop off` → `on` can safely infer
-which built-ins the user originally enabled.
-
-## How a request runs
-
-Developer adds two model-facing protocol tools:
-
-1. `developer_route_question` opens one route for one concrete question.
-2. The route target is `implementation` or one currently available Developer skill.
-3. A skill route returns the exact Pi-discovered `SKILL.md` instructions and canonical
-   path; an implementation route declares one movement, its stable landing, and its narrow
-   verification. A behavior-preserving structural route also loads the focused
-   execution profile based on flocking-style movement and small tidyings.
-4. `developer_record_judgment` closes the route with a status, result, evidence,
-   artifacts, and any newly opened questions. Developer then routes again from
-   the stable landing before another movement.
-5. Consecutive implementation routes remain valid. To prevent routing by momentum, a
-   implementation route that follows an implementation judgment must cite the previous landing
-   evidence and record the plausible skill routes reconsidered plus why they add
-   no useful judgment at that point.
-
-The conditional default topology is:
+```text
+This parser change is green, but the conditionals are spreading.
+Decide whether structural work belongs now.
+```
 
 ```text
-clarify when needed → model consequential cases
-→ sketch the first feature implementation surface OR signal existing-code movement
-→ one implementation green-to-green movement → re-route from evidence
-→ verify before completion
+The tests pass after this cache rewrite.
+Check what they do not prove before calling it done.
 ```
 
-This is not a mandatory phase sequence. A stage may be not applicable and new
-evidence may route backward or sideways. One guard is deliberate: a resolved
-model cannot flow straight into mutation. New feature work receives an initial
-`sketch`; existing-code structural work receives a `signal` first.
-
-Product code is still read, edited, executed, and tested with Pi's normal tools.
-Developer's tools only route and record judgment; they do not implement product
-changes themselves.
-
-There is never a required order such as `specify → model → sketch → verify`.
-Each new route is chosen from the current question and evidence.
-
-## What the TUI shows
-
-Developer uses different Pi surfaces for different information:
-
-- The footer contains only activation, protocol state, and current route target.
-- A compact widget appears only while a route or unresolved question exists.
-- `/develop` uses Pi's `SettingsList` semantics: the `Developer` row shows
-  and toggles the current On/Off value, `Status` opens branch details,
-  `History · N` opens complete route/judgment records when present, and
-  `Open questions · N` appears only when unresolved questions exist.
-- `/develop status` opens a non-overlay, branch-grounded, read-only status panel
-  with recent route/judgment history and the alternatives recorded for
-  consecutive implementation work.
-- `/develop questions` uses stable internal question IDs. A sole question opens
-  directly; multiple questions use one selector. Every open question, regardless
-  of owner or gate, first shows a complete non-overlay decision brief: context is
-  rendered as Markdown, then blocked work, gate, resolution criteria, and every
-  structured field/option appear before Continue or Leave open controls.
-  Cancelling the first field or editor returns to that brief; leaving the brief
-  returns to the parent without changing protocol state.
-- A newly opened, answerable user question that gates implementation work is pushed
-  to the same explanation-first brief before the judgment tool returns. The user
-  may continue only after reviewing the explanation or leave it open. Structured
-  responses then collect each option/detail and provide review/edit before submission.
-  The answer still requires a focused judgment and explicit `question_updates`.
-- Developer custom surfaces leave mouse ownership with the terminal: wheel/trackpad
-  scrolls normal-buffer content, drag selects text, and Cmd+C copies it. Wheel input
-  never changes the selected control; arrow keys do. Potentially long surfaces render
-  complete content rather than hiding it behind an application-owned viewport.
-- Protocol tool rows show compact status by default and higher-contrast evidence
-  details when expanded with the user's configured Pi keybinding. They render
-  without Pi's default full tool-row background.
-
-RPC, JSON, and print modes keep the same protocol semantics without depending on
-terminal components.
-
-## Protocol states
+## Why Developer
 
-| State | Meaning |
+Ordinary coding requests often contain decisions that look like implementation
+details but are actually product, model, boundary, or evidence questions.
+
+| Before | With Developer |
 | --- | --- |
-| `idle` | No active route and no unresolved Developer question |
-| `needs-judgment` | One route is active and must be closed with a judgment |
-| `needs-evidence` | At least one agent- or environment-owned evidence question remains open |
-| `needs-answer` | At least one user-owned answer or decision remains open |
-| `needs-routing` | An implementation stable landing must be re-observed and routed again |
-| `needs-verification` | Changed artifacts still need a resolved verify judgment |
-| `blocked` | A question is unavailable or explicitly gates implementation work |
-
-These are routing states, not product-completion claims. In particular:
-
-- `idle` does not mean the user's task is finished.
-- A resolved `specify` judgment is not user acceptance.
-- A resolved `verify` judgment is not timeless proof after later changes.
-
-Pending questions receive stable internal IDs, but users do not type them. Each
-question records:
-
-- `resolutionOwner`: `agent`, `user`, or `environment`;
-- `gate`: `none`, `before-implementation`, or `before-completion`;
-- `resolutionCriteria`: the observable evidence or answer that closes it;
-- `context`: Markdown explanation rendered before answer controls for every open
-  question; required for user-owned `before-implementation` and `before-completion`
-  questions, optional for other and legacy questions;
-- optional user-owned `responseSpec`: a bounded `choice-form` with required
-  single-choice fields and optional per-option detail prompts.
-
-A producer should use `response_spec` when a user must answer finite decisions
-such as A, B1–B4, C, and so on. Each decision becomes one field; the TUI does not
-infer controls by parsing Markdown. Options such as A3 or G3 that need additional
-input declare `detail_prompt`. Missing or malformed replay data falls back to the
-freeform editor without dropping the pending question.
-
-Selecting `/develop questions` always opens the explanation brief before any
-structured control or owner-specific editor. User questions then ask for the
-required decision, agent questions ask Pi to investigate, and environment
-questions request access or an external observation. Submitting
-focuses the question in branch state; an explicit ID, focus, or exact question
-match associates the next route. Selection alone never closes it.
-
-Every judgment rechecks all pending questions. `question_updates` can resolve an
-unfocused question when implementation, tests, inspection, user input, or an
-environment observation naturally supplies its criteria. A focused question
-must receive an explicit update: resolve or dismiss it with concrete basis,
-retain it as open or blocked, or close the broad parent while opening narrower
-children. Resolved and not-applicable updates remove the question with recorded
-basis; open or blocked updates preserve its identity. A `before-implementation` question blocks both implementation
-routes and Pi built-in artifact tools while Developer is on. A
-`before-completion` question allows investigation and implementation but keeps
-the protocol non-idle and prevents verification debt from being cleared as a
-completion claim.
-
-A resolved or not-applicable judgment may preserve a distinct follow-up question:
-finishing the routed judgment does not imply that no later work was discovered.
-It may not reopen its own normalized question under a resolved status; that route
-must remain needs-evidence/blocked or explicitly refine a focused parent instead.
-
-When a judgment replaces a broad unresolved question with more specific evidence
-questions, only the actionable children remain. Equivalent question wording is
-deduplicated while preserving the existing identity.
+| Vague requests decide product behavior | Unknowns become owned questions |
+| Green tests stand in for claims | Evidence is matched to each claim |
+| Refactoring follows taste or momentum | Structure follows observed pressure |
+| All methods enter context | Only triggered methods load |
+| Branches lose rationale | Evidence replays with its branch |
+
+Developer coordinates judgment; Pi still reads, edits, runs, and tests the
+product with its normal tools.
+
+## How it works
+
+Developer follows a small adaptive loop:
+
+```text
+Discover → Load → Derive → Act → Check → Learn
+```
+
+1. **Discover** the current unresolved question from the request, repository,
+   and latest evidence.
+2. **Load** one focused skill, plus only the deeper references whose triggers
+   actually apply.
+3. **Derive** an inspectable artifact such as a case table, boundary map, wished
+   interface, review card, timing matrix, or evidence matrix.
+4. **Act** through one justified implementation movement when mutation is the
+   right next step.
+5. **Check** the changed claim with an appropriate observer and verifier.
+6. **Learn** from the stable landing, preserve remaining questions, and route
+   again rather than continuing by momentum.
+
+This is not a mandatory phase sequence. A simple task can move directly to
+implementation. New evidence can route backward or sideways. Consecutive
+implementation movements are allowed when the previous landing is re-observed
+and the plausible judgment routes add no useful information.
+
+## Common workflows
+
+| Need | Developer helps Pi… |
+| --- | --- |
+| Clarify a feature | Separate meaning, constraints, examples, and blockers |
+| Model behavior | Enumerate cases, contracts, transitions, and guarantees |
+| Shape code | Expose data, interfaces, collaboration, state, and checks |
+| Inspect a design | Identify structural movement and model-code mismatch |
+| Review an abstraction | Keep, revise, split, reject, or defer the candidate |
+| Time a refactor | Separate behavior work and judge the cost of delay |
+| Name code | Preserve domain meaning and expose effects or multiple senses |
+| Verify completion | Match evidence to claims and find pass-but-wrong risks |
+| Challenge a claim | Run finite adversarial checks with an explicit stop |
+| Clarify a decision | Choose the smallest useful visual surface |
 
 ## Skills
 
-Pi may match these skills automatically, Developer may route a question to one,
-or the user may invoke one directly with `/skill:<name>`.
+Developer may route these skills automatically. You can also invoke any one
+directly with `/skill:<name>`.
 
 | Skill | Helps decide |
 | --- | --- |
-| `specify` | Product meaning, scope, invariants, risks, and blocking unknowns |
-| `model` | Condition spaces, contracts, replacement, transitions, guarantees, and verification targets |
-| `sketch` | Inspectable code/pseudocode skeletons, case and interface tables, boundary/flow maps, state, responsibility, and variation |
-| `signal` | Evidence-backed structural movement and model-code mismatch |
-| `naming-judgment` | Domain sense, honest effects, and change-preserving names |
-| `abstraction-review` | Whether a candidate should be kept, revised, split, rejected, or deferred |
-| `schedule` | Behavior/structure timing: now, after, or never |
-| `verify` | Verifier selection, evidence relevance, and pass-but-wrong risk |
-| `visualize` | The smallest visual surface that lowers judgment cost |
-| `adversarial-eval` | Finite, escalating attempts to falsify a skill or implementation claim |
-
-Each leaf chooses a surface that matches its inspection problem instead of
-returning undifferentiated prose: contract and scope tables for `specify`, case
-or transition models for `model`, code/interface/check surfaces for `sketch`,
-artifact comparisons for `signal`, rename maps for `naming-judgment`, review
-cards and boundaries for `abstraction-review`, timing matrices for `schedule`,
-evidence matrices for `verify`, escalation matrices for `adversarial-eval`, and
-a completed visual artifact for `visualize` when a visual is warranted. Simple
-judgments may remain compact when prose is genuinely clearer.
-
-Skill judgment results preserve those surfaces as Markdown. Expanded protocol
-rows render tables and code blocks through Pi's Markdown component rather than
-flattening them into dim text.
-
-Pi's loaded resource metadata is authoritative. If package configuration filters
-or disables a skill, Developer cannot route to it even if its file exists in the
-npm package.
-
-Several skills link to detailed capability documents under their own
-`references/` directory. Pi loads the `SKILL.md` instructions on demand; the
-instructions say when each reference is worth reading and resolve it relative to
-the skill directory. A reference may synthesize several sources because the
-leaf's question, not a book title, owns the capability. Each source-derived
-reference includes a source trace, and [SOURCES.md](./SOURCES.md) maps the full
-book coverage across leaves and the implementation path. Small, settled judgments do not
-need the extra context.
-
-Primary references retain the capability's core insight and one complete case.
-When a question has materially different derivation rules, the skill routes a
-more focused supporting reference—for example, data-shape templates separately
-from generative recursion, or representation barriers separately from state and
-time. This follows Pi's documented progressive-disclosure structure: supporting
-files stay relative to their skill and load only when the unresolved question
-needs them. `SOURCES.md` also records the reference-quality contract used to
-prevent source summaries from replacing executable judgment recipes.
-
-Developer treats Pi's loaded `systemPromptOptions.skills` metadata as the skill
-SSOT. It does not rescan the package and cannot route a skill Pi filtered,
-disabled, or replaced through resource configuration.
-
-## State, branches, and compaction
-
-Activation changes are stored as Pi custom session entries. Routes and judgments
-are stored in tool-result details. Developer replays the current branch through
-an XState v5 machine on startup and tree navigation, so a fork inherits only the
-events on its branch. Parallel machine regions keep activation, route, question gates,
-framing debt, and verification debt explicit; transition guards reject an implementation
-route while a `before-implementation` question remains.
+| `specify` | Product meaning, scope, invariants, and blockers |
+| `model` | Cases, contracts, transitions, guarantees, and checks |
+| `sketch` | Data, interfaces, collaboration, flow, state, and code shape |
+| `signal` | Structural movement and model-code mismatch |
+| `naming-judgment` | Stable domain meaning, effects, and multiple senses |
+| `abstraction-review` | Whether to keep, revise, split, reject, or defer |
+| `schedule` | Whether structural work belongs now, after, or never |
+| `verify` | What evidence proves and what pass-but-wrong risk remains |
+| `visualize` | Which visual surface materially lowers judgment cost |
+| `adversarial-eval` | Which finite checks could falsify a claim |
+
+Each skill produces an artifact suited to its question instead of defaulting to
+undifferentiated prose. Simple judgments remain compact when prose is genuinely
+clearer.
 
-```text
-developerMachine (parallel)
-├── activation: disabled | enabled
-├── route: idle | judgment | implementation
-├── questions: clear | open
-├── implementationGate: clear | blocked
-├── completionGate: clear | blocked
-├── checkpoint: ready | required
-├── framing: clear | required
-└── verification: current | required
+## Commands
+
+| Command | Effect |
+| --- | --- |
+| `/develop` | Open Developer settings |
+| `/develop on` | Enable adaptive routing and route-bound tool access |
+| `/develop status` | Inspect current branch state and recent route history |
+| `/develop questions` | Review or investigate an unresolved question |
+| `/develop off` | Disable Developer and clear current protocol state |
+
+Start a preconfigured session with Developer enabled:
+
+```sh
+pi --develop
 ```
 
-Judgment routes carry the `execute` tag, implementation routes carry `execute` and
-`mutate`, and question/debt regions expose blocking tags. Every implementation judgment
-moves the checkpoint to `required`; the next accepted route returns it to
-`ready`. Tool availability, runtime call guards, status, and implementation-transition
-eligibility are derived from the same machine snapshot.
-
-The current event contract is `developer/v5`. Earlier protocol entries are not
-replayed; this breaking contract uses `target`, `implementation`, and
-`before-implementation` consistently across tools, events, and machine state.
-A process started on the current package may open a branch containing those
-entries, but hot-reloading directly from a pre-handoff runtime is rejected with
-a restart instruction so its in-memory tool ownership cannot be mistaken for
-user configuration.
-
-Developer deliberately leaves compaction ownership to Pi. It does not trigger,
-cancel, or replace threshold/overflow compaction, so it cannot override the
-user's Pi settings or race another extension. Configure earlier compaction with
-Pi's `compaction.reserveTokens` and `compaction.keepRecentTokens` settings when
-a large-context model reaches its limit too abruptly.
-
-Each new agent turn receives current protocol state, and route results place
-identity and recovery metadata before potentially long skill instructions. That
-makes the active route recoverable after Pi compacts normally. Tool output is
-checked against Pi's standard size limits before state changes are committed.
-At most twenty pending questions may remain in current state.
+Turning Developer off while work or questions remain asks for confirmation in
+interactive mode. Historical session entries remain; only current protocol state
+is cleared.
+
+## Questions and visible state
+
+Developer keeps consequential unknowns explicit instead of silently turning them
+into assumptions. A question records who can resolve it, what evidence or answer
+would close it, and whether it blocks implementation or completion.
+
+`/develop questions` shows the explanation before answer controls. User-owned
+questions accept an answer, agent-owned questions can be sent back to Pi for
+investigation, and environment-owned questions identify access or observations
+that must come from outside the session.
+
+The footer shows activation and the current route. A compact widget appears only
+while a route or unresolved question exists. `/develop status` and
+`/develop questions` expose the details without requiring users to remember
+internal IDs.
+
+Visible routing states include:
+
+| State | Meaning |
+| --- | --- |
+| `idle` | No active route or unresolved Developer question |
+| `needs-judgment` | Current route still needs a recorded result |
+| `needs-evidence` | Agent or environment evidence is still required |
+| `needs-answer` | A user decision is still required |
+| `needs-routing` | An implementation landing must be routed again |
+| `needs-verification` | Changed artifacts still need verification |
+| `blocked` | A required answer, observation, or access is unavailable |
+
+These are routing states, not timeless product-completion claims. In particular,
+`idle` does not mean that the user's task is complete, and later changes can
+invalidate an earlier verification judgment.
+
+## Tool boundaries
+
+While Developer is on:
+
+- Pi's built-in `bash` is available for repository inspection and verification
+  during skill and implementation routes;
+- built-in `edit` and `write` require an active implementation route with no
+  unresolved before-implementation gate;
+- unrelated tools and user-disabled tools keep their existing configuration;
+- product changes still happen through Pi's normal tools, not through
+  Developer's coordination tools.
+
+These controls protect workflow integrity. They are **not a security sandbox**:
+shell commands are not parsed as a security language, and Pi packages run with
+the access of the Pi process. Review the package before installation and use an
+external sandbox when you need an operating-system security boundary.
+
+## References and auditability
+
+A skill's always-needed method lives in `SKILL.md`. Conditional derivations live
+in `references/*.md`, while `reference-policy.json` maps an observable trigger
+to one question, required reference set, expected artifact, stop condition, and
+handoff boundary.
+
+During a Developer route, selected references are loaded through a dedicated
+trace rather than an ordinary file read. A resolved judgment connects each
+relied-upon reference to the observed trigger, applied rule, and resulting
+artifact.
+Reference and policy hashes make that application replayable on the current
+branch; they do not by themselves prove source fidelity.
+
+See [Reference routing](./REFERENCE_ROUTING.md) for the runtime contract and
+policy schema.
+
+## Branches, compaction, and reloads
+
+Routes, judgments, questions, and activation changes are stored in Pi session
+entries and replayed from the current branch. A fork therefore inherits only its
+own branch history.
+
+Developer leaves compaction to Pi. Current route and recovery metadata are
+placed where the normal Pi compactor can preserve them. Configure Pi's
+compaction settings if you want an earlier threshold.
+
+Developer restores only the built-in tool changes it owns when a session runtime
+shuts down. If a hot reload encounters older Developer history without a safe
+release marker, restart the Pi process rather than guessing the user's original
+tool configuration.
 
 ## Update, configure, and remove
 
@@ -341,27 +265,8 @@ Use a project-local install when a repository should declare the package in
 pi install -l npm:@hobin/developer
 ```
 
-Pi packages execute with Pi's system access. Review the extension and skills
-before installation. See the [Pi package
-documentation](https://pi.dev/docs/latest/packages) for package scope, filtering,
-pinning, and security behavior.
-
-## Package contents
-
-```text
-extensions/
-├── developer.ts    # command, protocol tools, events, and Pi integration
-├── machine.ts      # XState v5 parallel regions, guards, transitions, and tags
-├── references/     # implementation profiles loaded through tool results
-├── state.ts        # developer/v5 event normalization and branch replay
-├── skills.ts       # loaded-skill filtering and instruction rendering
-├── tool-policy.ts  # machine-derived execution and mutation access policy
-└── tui.ts          # selectors, widget, status panel, and prompt preparation
-skills/             # ten independently loadable Pi skills
-SOURCES.md          # source-to-capability maintenance trace
-evals/              # model-dependent scenarios and workspace assertions
-tests/              # deterministic state, policy, extension, and TUI tests
-```
+See the [Pi package documentation](https://pi.dev/docs/latest/packages) for
+package scope, filtering, pinning, and security behavior.
 
 ## Development
 
@@ -379,76 +284,14 @@ Load the workspace package into Pi without installing it:
 pi -e ./packages/developer
 ```
 
-Launch the isolated surface fixture in a new Ghostty window for visual QA:
-
-```sh
-./packages/developer/scripts/ghostty-tui-qa.sh
-```
-
-Choose each independent scenario from the QA menu:
-
-1. **Activation + confirm/cancel** — toggle Off/On on the same Settings surface;
-   cancel destructive Off and verify the row stays On, then confirm it and verify
-   the route/questions clear before toggling On again.
-2. **Settings / Status / History / Questions** — open a History judgment,
-   drag-select detail text and paste it elsewhere, then verify one-level Escape
-   from detail → History → Settings → scenario menu with parent focus restored.
-3. **Custom answer + Korean IME** — choose **Write another answer…**, then check
-   composition, validation, review/edit, and preset/custom provenance.
-4. **Resize / scroll / mouse cleanup** — repeatedly resize long Status and
-   History detail surfaces between wide and narrow layouts; check native mouse
-   wheel scrolling, border alignment, drag selection, Cmd+C, and paste elsewhere.
-5. **Unicode + compact overlay footprint** — inspect `◆`, `→`, `↑↓`, `·`, `…`,
-   and Korean glyph alignment, untouched background, and content-bounded overlays.
-
-Across Developer surfaces, Ghostty owns the mouse: the wheel scrolls terminal
-scrollback, ordinary drag selects text, and `Cmd+C` copies it. Wheel movement
-never changes the selected list target; use `↑`/`↓` for selection. Potentially
-long lists render every row as non-overlay surfaces, while complete two-choice
-interruptions remain compact overlays.
-
-Each scenario creates a fresh in-memory model. Activation events use the same
-`applyDeveloperEvent` reducer and `DeveloperSettingsBinding` contract as the
-production surface; no state is shared between scenario runs. The fixture does
-not append entries, submit answers, register tools, mutate active tools, restore
-sessions, start network work, or send model messages. Prepared answers are shown
-only as a character count.
-
-`check` validates package structure and deterministic behavior, including
-reload migration detection and shutdown restoration of Developer-owned tool
-deltas. `eval` launches the real Pi RPC surface without a model and covers
-package resources, commands, activation state, and route-bound tool gating.
-These are release-gating checks.
-
-Model-dependent runs are probabilistic evaluations rather than binary tests:
-
-```sh
-PI_CODING_AGENT_DIR=~/.pi/agent \
-DEVELOPER_EVAL_FIXTURE=agent-before-implementation-evidence-gate \
-DEVELOPER_EVAL_TRIALS=5 \
-pnpm --filter @hobin/developer eval:live
-```
+`check` validates package structure and deterministic behavior. `eval` exercises
+the real Pi RPC surface without a model. Model-dependent evaluations are
+probabilistic and must not be interpreted as proof from a single successful
+sample.
 
-Use `eval:live:json` for the JSON transport. Each report separates the hard
-admissibility envelope from routing quality: structurally valid runs must use an
-admissible route, preserve mutation/question/completion invariants, satisfy
-hidden artifact checks, include required semantic terms, and end in a declared
-outcome. Among accepted runs, `preferredFirstTargets` measures better versus
-merely admissible routing. Reports include acceptance and preference rates,
-95% Wilson intervals, inadmissible results, rejected protocol attempts, budget
-exhaustion, and environment failures. Any accepted inadmissible result makes the
-evaluation command fail; ordinary admissible preference variation remains a
-rate. A single model sample is not release evidence.
-
-Live fixtures classify terminal outcomes as `settled-unchanged`, `pending`,
-`changed-paused`, or `changed-verified`. An eval-only observer compares
-product-file snapshots around bash/edit/write calls and rejects artifact changes
-outside an implementation route. Dedicated fixtures sample a deliberately paused implementation
-landing and an agent-owned before-implementation question resolved through a non-implementation
-bash evidence route; their structural guarantees also have deterministic machine,
-extension, trace, filesystem, and outcome tests. RPC and JSON runners share
-route, tool-call, tool-error, wall-clock, and no-progress budgets and preserve a
-trace for diagnosis.
+The published npm package contains the runtime extension, skills, user-facing
+documentation, and license. Source audits, evaluation fixtures, scripts, and
+tests remain repository-only maintenance evidence.
 
 ## License