@hobin/developer 0.1.1 → 0.1.3

package/README.md

@@ -3,9 +3,10 @@
 Adaptive product-development judgment for [Pi](https://pi.dev).
 
 Developer combines a small, branch-aware coordination extension with ten
-independent skills. It routes one concrete question at a time, records the
-resulting evidence, and preserves unresolved questions without turning product
-development into a fixed lifecycle.
+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.
 
 ## Install
 
@@ -86,10 +87,26 @@ 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.
 3. A skill route returns the exact Pi-discovered `SKILL.md` instructions and canonical
-   path; a direct route keeps implementation tools available for the justified
-   action.
+   path; a direct 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.
+   artifacts, and any newly opened questions. Developer then routes again from
+   the stable landing before another movement.
+
+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
+→ verify before completion
+```
+
+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
@@ -129,8 +146,12 @@ These are routing states, not product-completion claims. In particular:
 - A resolved `specify` judgment is not user acceptance.
 - A resolved `verify` judgment is not timeless proof after later changes.
 
-Pending questions receive stable IDs. A later route revisits one by passing the
-exact ID; wording similarity is never used as identity.
+Pending questions receive stable internal IDs, but users do not type them.
+Selecting `/develop questions` focuses the question in branch state; the next
+route automatically associates that focus. A sole pending question or an exact
+question match is also associated automatically. Resolved and not-applicable
+judgments remove the associated question immediately; needs-evidence and blocked
+judgments retain the same identity.
 
 ## Skills
 
@@ -140,12 +161,12 @@ or the user may invoke one directly with `/skill:<name>`.
 | Skill | Helps decide |
 | --- | --- |
 | `specify` | Product meaning, scope, invariants, risks, and blocking unknowns |
-| `model` | Logic for Programmers-style condition spaces, guarantees, and verification targets |
-| `sketch` | SICP-style abstraction barriers and HtDP-style data-directed design recipes |
-| `signal` | Flocking-style small structural movement and model-code mismatch |
-| `naming-judgment` | Elements of Clojure-style domain sense and change-preserving names |
+| `model` | Condition spaces, contracts, replacement, transitions, guarantees, and verification targets |
+| `sketch` | Data-driven skeletons, abstraction and composition boundaries, 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` | Tidy First-style behavior/structure timing: now, after, or never |
+| `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 |
@@ -154,10 +175,27 @@ 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 documents under their own `references/`
-directory. Pi loads the `SKILL.md` instructions on demand; the instructions say
-when the additional reference is worth reading and resolve it relative to the
-skill directory. Small, already-settled judgments do not need the extra context.
+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 direct 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
 
@@ -166,8 +204,9 @@ stored in tool-result details. Developer reconstructs state from the current
 session branch on startup and tree navigation, so a fork inherits only the
 events on its branch.
 
-The current event contract is `developer/v2`. Legacy `developer/v1` routing
-history can be replayed, but removed inferred fields are not revived.
+The current event contract is `developer/v3`. Legacy `developer/v1` and
+`developer/v2` routing history can be replayed, but new framing and verification
+obligations are not retroactively inferred.
 
 Developer uses Pi's normal compaction. Each new agent turn receives current
 protocol state, and route results place identity and recovery metadata before
@@ -201,11 +240,13 @@ pinning, and security behavior.
 ```text
 extensions/
 ├── developer.ts    # command, protocol tools, events, and Pi integration
+├── references/     # direct execution profiles loaded through tool results
 ├── state.ts        # replayable developer/v2 branch state
-├── skills.ts       # Pi-native skill discovery and instruction loading
+├── skills.ts       # loaded-skill filtering and instruction rendering
 ├── tool-policy.ts  # strict-mode active-tool reconciliation
 └── 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
 ```

package/SOURCES.md

@@ -0,0 +1,104 @@
+# Source-to-Capability Trace
+
+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.
+
+## Ownership Rule
+
+A source idea belongs where its observable job is performed:
+
+- product meaning and change pressure go to `specify`;
+- cases, rules, contracts, and transitions go to `model`;
+- implementable boundaries and collaborations go to `sketch`;
+- visible structural movement goes to `signal`;
+- candidate stability goes to `abstraction-review`;
+- timing goes to `schedule`;
+- names go to `naming-judgment`;
+- claim-to-evidence judgment goes to `verify`;
+- already-justified mutation goes to the `direct` route.
+
+No source implies a mandatory route order. Several leaves may use different
+parts of the same source because they answer different questions.
+
+## Runtime Reference Quality
+
+`SKILL.md` owns discovery, the core question, output, completion, and conditional
+routing. A reference loaded through that route must be usable without reopening
+the original source or reconstructing unstated steps.
+
+Match detail to the reference's job:
+
+- a concept or design reference needs the core insight, input, derivation rule,
+  completed example, counterexample or failure diagnosis, output, and boundary;
+- a recipe card needs a trigger, input artifact, construction rule, output
+  artifact, observable stop, and repair direction;
+- a diagnostic table needs a symptom, evidence path, repair artifact, and
+  re-check;
+- a worked-example file needs enough context to show why the decision follows,
+  not only a polished final answer;
+- a mutation protocol needs an entry contract, safe intermediate states,
+  evidence rhythm, reroute conditions, and a stable landing.
+
+Split a reference when independent questions would otherwise make it expensive
+to load, but keep the central insight and one complete example in the primary
+reference. Splitting by chapter title or merely to shorten a file is not a
+capability boundary.
+
+## Capability Matrix
+
+| 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. 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` |
+| *Structure and Interpretation of Computer Programs*, ch. 1-2 | procedural abstraction, process shape, higher-order composition, data abstraction, closure, conventional interfaces, multiple representations | `sketch`, `abstraction-review` | `model` |
+| *Structure and Interpretation of Computer Programs*, ch. 3 | state, identity, history, concurrency, streams, constraint propagation | `model`, `sketch` | `abstraction-review`, `verify` |
+| *Structure and Interpretation of Computer Programs*, ch. 4-5 | language/evaluator boundaries and explicit execution machinery | `sketch`, `abstraction-review` | imported only when a real DSL, interpreter, compiler, or runtime boundary exists |
+| *Logic for Programmers*, ch. 2-3 | predicates, sets, quantifiers, logical refactoring, runtime-semantic caveats | `model` | `verify` |
+| *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*: 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` |
+
+## Intentionally Not Imported As Universal Rules
+
+Source coverage does not mean copying every example or language idiom into every
+task. The following remain contextual:
+
+- Ruby class and factory shapes from *99 Bottles* are evidence about
+  responsibility and variation, not a destination for every design.
+- Scheme evaluators, register machines, and compiler details from SICP are used
+  only for tasks that actually expose those runtime or language boundaries.
+- Clojure-specific arities, option maps, atoms, macros, and interop idioms stay
+  subordinate to the target project's language and conventions.
+- Logic solvers, formal proof, TLA+, Prolog, and answer-set programming are
+  selected only when the modeled uncertainty and risk justify their cost.
+- HtDP recipes are adapted to existing repositories; they do not require adding
+  pedagogical comments, signatures, or templates to production code.
+
+These exclusions prevent a respected source from becoming a framework-shaped
+answer imposed on unrelated product work.
+
+## Reassembly Check
+
+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
+Boundary: what the owner must not absorb
+Observable effect: the artifact, decision, or safer execution behavior expected
+```
+
+Create a new leaf only when a recurring question has a distinct input, output,
+completion condition, and boundary that no existing owner can express. A new
+source, technique, or vocabulary is not by itself evidence for a new leaf.