@hobin/developer 0.1.5 → 0.1.7

package/README.md

@@ -24,61 +24,51 @@ pi -e npm:@hobin/developer
 
 ## Quick start
 
-Start Pi, enable adaptive mode, and describe the product task normally:
+Start Pi, turn Developer on, and describe the product task normally:
 
 ```text
 /develop on
 The selected payment method disappears after navigating back to checkout. Find the cause and fix it.
 ```
 
-Most users should begin with `on`. Developer decides whether the next concrete
-question would benefit from a focused skill or is already justified as direct action. You
-do not need to call its internal protocol tools yourself.
-
-For a risky refactor where Pi should justify mutation before using its built-in
-edit, write, or shell tools:
-
-```text
-/develop strict
-Unify the duplicate schedule types and conversion logic without changing existing behavior.
-```
+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.
 
 ## Commands
 
 | Command | Effect |
 | --- | --- |
-| `/develop` | Open the interactive Developer control menu |
-| `/develop on` | Enable adaptive routing; tools stay active unless a `before-direct` question gate is open |
-| `/develop strict` | Gate shell execution behind an active route and structured artifact mutation behind a direct route |
+| `/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 |
 
 Explicit command arguments participate in Pi's completion UI. In interactive
-mode, turning Developer off while a route or unresolved question exists requires
+use, turning Developer off while a route or unresolved question exists requires
 confirmation. The historical session entries remain; only current protocol
 state is cleared.
 
-Start a non-interactive or preconfigured session in a mode with the extension
-flag:
+Start a non-interactive or preconfigured session with Developer enabled:
 
 ```sh
-pi --develop-mode on
-pi --develop-mode strict
+pi --develop
 ```
 
-## Modes
+## Activation and tool policy
 
-| Mode | Routing | Built-in mutation tools | Best fit |
-| --- | --- | --- | --- |
-| `on` | Adaptive | Unchanged except while a `before-direct` question gate is open | Normal product development |
-| `strict` | Adaptive | `bash` is available during skill/direct routes; Pi built-in `edit` and `write` require an active `direct` route and no `before-direct` gate | High-risk changes and workflow-discipline experiments |
-| `off` | Disabled | Developer makes no changes to the active set | Normal Pi behavior without the protocol |
+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.
 
-Strict mode and question gates are workflow-integrity controls, not a security
+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 direct-only. Shell commands are not parsed as a security language; skill
+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
@@ -89,16 +79,16 @@ disabled.
 Developer adds two model-facing protocol tools:
 
 1. `developer_route_question` opens one route for one concrete question.
-2. The route target is `direct` or one currently available Developer skill.
+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; a direct route declares one movement, its stable landing, and its narrow
+   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 direct routes remain valid. To prevent routing by momentum, a
-   direct route that follows a direct judgment must cite the previous landing
+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.
 
@@ -107,7 +97,7 @@ The conditional default topology is:
 ```text
 clarify when needed → model consequential cases
 → sketch the first feature implementation surface OR signal existing-code movement
-→ one direct green-to-green movement → re-route from evidence
+→ one implementation green-to-green movement → re-route from evidence
 → verify before completion
 ```
 
@@ -127,19 +117,31 @@ Each new route is chosen from the current question and evidence.
 
 Developer uses different Pi surfaces for different information:
 
-- The footer contains only global mode, protocol state, and current route target.
+- 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 a `SelectList` action menu.
-- `/develop status` opens a branch-grounded, read-only status panel with recent
-  route/judgment history and the alternatives recorded for consecutive direct work.
-- `/develop questions` uses stable internal question IDs. Selecting one opens an
-  answer/evidence editor and submits the resulting resolution request to Pi;
-  cancelling the editor leaves protocol state unchanged.
-- Selection and status overlays use most of the terminal, keep a stable rendered
-  height while navigating or scrolling, and remain bounded on small terminals.
-  They support mouse-wheel/trackpad scrolling, arrow keys, Page Up/Down, and
-  Home/End. Terminal mouse reporting is enabled only while the overlay is open
-  and is released when it closes.
+- `/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.
@@ -155,9 +157,9 @@ terminal components.
 | `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` | A direct stable landing must be re-observed and routed again |
+| `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 direct work |
+| `blocked` | A question is unavailable or explicitly gates implementation work |
 
 These are routing states, not product-completion claims. In particular:
 
@@ -169,14 +171,26 @@ Pending questions receive stable internal IDs, but users do not type them. Each
 question records:
 
 - `resolutionOwner`: `agent`, `user`, or `environment`;
-- `gate`: `none`, `before-direct`, or `before-completion`;
-- `resolutionCriteria`: the observable evidence or answer that closes it.
-
-Selecting `/develop questions` opens an owner-specific editor: user questions
-ask for the required decision, agent questions ask Pi to investigate, and
-environment questions request access or an external observation. Submitting the
-editor focuses the question in branch state; an explicit ID, focus, or exact
-question match associates the next route. Selection alone never closes it.
+- `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
@@ -184,12 +198,17 @@ 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-direct` question blocks both direct
-routes and Pi built-in mutation tools even in adaptive mode. A
+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.
@@ -235,7 +254,7 @@ 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 direct path. Small, settled judgments do not
+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.
@@ -253,35 +272,34 @@ disabled, or replaced through resource configuration.
 
 ## State, branches, and compaction
 
-Mode 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 mode, route, question gates,
-framing debt, and verification debt explicit; transition guards reject a direct
-route while a `before-direct` question remains.
+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.
 
 ```text
 developerMachine (parallel)
-├── mode: off | on | strict
-├── route: idle | judgment | direct
+├── activation: disabled | enabled
+├── route: idle | judgment | implementation
 ├── questions: clear | open
-├── directGate: clear | blocked
+├── implementationGate: clear | blocked
 ├── completionGate: clear | blocked
 ├── checkpoint: ready | required
 ├── framing: clear | required
 └── verification: current | required
 ```
 
-Judgment routes carry the `execute` tag, direct routes carry `execute` and
-`mutate`, and question/debt regions expose blocking tags. Every direct judgment
+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 direct-transition
+`ready`. Tool availability, runtime call guards, status, and implementation-transition
 eligibility are derived from the same machine snapshot.
 
-The current event contract is `developer/v4`. Legacy `developer/v1` through
-`developer/v3` routing history can be replayed. Legacy questions receive
-conservative owner, gate, and resolution-criteria defaults rather than guessed
-product decisions.
+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.
 
 Developer deliberately leaves compaction ownership to Pi. It does not trigger,
 cancel, or replace threshold/overflow compaction, so it cannot override the
@@ -322,8 +340,8 @@ pinning, and security behavior.
 extensions/
 ├── developer.ts    # command, protocol tools, events, and Pi integration
 ├── machine.ts      # XState v5 parallel regions, guards, transitions, and tags
-├── references/     # direct execution profiles loaded through tool results
-├── state.ts        # developer/v4 event normalization and branch replay
+├── 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
@@ -349,26 +367,50 @@ Load the workspace package into Pi without installing it:
 pi -e ./packages/developer
 ```
 
-Launch the isolated modal fixture in a new Ghostty window for visual QA:
+Launch the isolated surface fixture in a new Ghostty window for visual QA:
 
 ```sh
 ./packages/developer/scripts/ghostty-tui-qa.sh
 ```
 
-Choose **Inspect status** or **Revisit an open question**, then resize the window
-while the modal is open. The fixture disables discovered extensions, skills,
-tools, sessions, and network startup so it cannot mutate Developer state or call
-a model.
+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. `eval` launches
 the real Pi RPC surface without a model and covers package resources, commands,
-mode state, and strict tool gating. These are release-gating checks.
+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-direct-evidence-gate \
+DEVELOPER_EVAL_FIXTURE=agent-before-implementation-evidence-gate \
 DEVELOPER_EVAL_TRIALS=5 \
 pnpm --filter @hobin/developer eval:live
 ```
@@ -377,7 +419,7 @@ 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, `preferredFirstOwners` measures better versus
+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
@@ -387,8 +429,8 @@ 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 a direct route. Dedicated fixtures sample a deliberately paused direct
-landing and an agent-owned before-direct question resolved through a non-direct
+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

package/SOURCES.md

@@ -2,8 +2,8 @@
 
 Developer is organized around questions the agent must answer, not around books.
 This maintainer document records how source material is decomposed across leaf
-skills and the direct execution path. It is not a Pi runtime resource or a
-required workflow.
+skills and the implementation path. It is not a Pi runtime resource or a required
+workflow.
 
 ## Ownership Rule
 
@@ -17,7 +17,7 @@ A source idea belongs where its observable job is performed:
 - timing goes to `schedule`;
 - names go to `naming-judgment`;
 - claim-to-evidence judgment goes to `verify`;
-- already-justified mutation goes to the `direct` route.
+- already-justified mutation goes to the `implementation` route.
 
 No source implies a mandatory route order. Several leaves may use different
 parts of the same source because they answer different questions.
@@ -51,8 +51,8 @@ capability boundary.
 | Source | Capability extracted | Primary owner | Supporting owner or execution path |
 | --- | --- | --- | --- |
 | *99 Bottles of OOP*, ch. 1-2 | simple concrete baseline, Shameless Green, cost-effective and intention-revealing tests | `verify` | `signal`, `schedule` |
-| *99 Bottles of OOP*, ch. 3-4 | real change pressure, point of attack, closest pair, smallest difference, horizontal movement | `signal` | `direct` behavior-preserving protocol |
-| *99 Bottles of OOP*, ch. 4-5 | stable landings, responsibility-derived names, argument and data movement | `abstraction-review`, `naming-judgment` | `direct` behavior-preserving protocol |
+| *99 Bottles of OOP*, ch. 3-4 | real change pressure, point of attack, closest pair, smallest difference, horizontal movement | `signal` | `implementation` behavior-preserving protocol |
+| *99 Bottles of OOP*, ch. 4-5 | stable landings, responsibility-derived names, argument and data movement | `abstraction-review`, `naming-judgment` | `implementation` behavior-preserving protocol |
 | *99 Bottles of OOP*, ch. 5-8 | responsibility separation, messages, type transitions, polymorphism, dependency direction, object creation at the edge, factory tradeoffs | `sketch`, `abstraction-review` | `model`, `schedule` |
 | *99 Bottles of OOP*, ch. 9 | unit boundaries, context independence, role verification, obsolete-test removal | `verify` | `sketch` |
 | *How to Design Programs* | information analysis, data definitions, examples, templates, structural and generative recursion, accumulators, iterative refinement | `sketch` | `model`, `verify`, `signal`, `abstraction-review` |
@@ -63,10 +63,10 @@ capability boundary.
 | *Logic for Programmers*, ch. 4-6 | partial specifications, properties, contracts, replacement, proof limits | `model`, `verify` | `abstraction-review` |
 | *Logic for Programmers*, ch. 7-12 | relational constraints, decision tables, domain/time/system models, solvers, logic programming | `model` | `verify` |
 | *Elements of Clojure*: Names | narrow and consistent sense, honest effects and scope crossing | `naming-judgment` | `model` |
-| *Elements of Clojure*: Idioms | language-specific conventions and explicit operational semantics | project conventions or `direct` | generalized only when the semantic lesson survives the language |
+| *Elements of Clojure*: Idioms | language-specific conventions and explicit operational semantics | project conventions or `implementation` | generalized only when the semantic lesson survives the language |
 | *Elements of Clojure*: Indirection | abstraction cost, module environment/model/interface/assumptions, principled versus adaptable systems | `sketch`, `abstraction-review` | `schedule` |
 | *Elements of Clojure*: Composition | units of computation and pull-transform-push process boundaries | `sketch` | `naming-judgment`, `verify` |
-| *Tidy First?* | separate behavior from structure, small tidyings, optionality, reversibility, first/after/later/never | `schedule` | `direct` behavior-preserving protocol, `signal` |
+| *Tidy First?* | separate behavior from structure, small tidyings, optionality, reversibility, first/after/later/never | `schedule` | `implementation` behavior-preserving protocol, `signal` |
 
 ## Intentionally Not Imported As Universal Rules
 
@@ -94,7 +94,7 @@ When adding or revising a source-derived reference, record:
 ```text
 Source location: book, edition/version, chapter or section
 Capability: the question or action the idea improves
-Owner: one leaf or the direct path
+Owner: one leaf or the implementation path
 Boundary: what the owner must not absorb
 Observable effect: the artifact, decision, or safer execution behavior expected
 ```