@hobin/developer 0.1.0 → 0.1.1

package/README.md

@@ -140,13 +140,13 @@ or the user may invoke one directly with `/skill:<name>`.
 | Skill | Helps decide |
 | --- | --- |
 | `specify` | Product meaning, scope, invariants, risks, and blocking unknowns |
-| `model` | Predicates, cases, rules, forbidden states, transitions, and objectives |
-| `sketch` | Data definitions, wished interfaces, representative cases, and checks |
-| `signal` | Repetition, difference, structural pressure, and model-code mismatch |
-| `naming-judgment` | Stable domain meaning and names that preserve change boundaries |
+| `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 |
 | `abstraction-review` | Whether a candidate should be kept, revised, split, rejected, or deferred |
-| `schedule` | Whether a structural change belongs now, after, or never |
-| `verify` | Whether current evidence actually supports an implementation claim |
+| `schedule` | Tidy First-style 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,6 +154,11 @@ 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.
+
 ## State, branches, and compaction
 
 Mode changes are stored as Pi custom session entries. Routes and judgments are

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "@hobin/developer",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Adaptive product-development reasoning and evidence for Pi.",
   "type": "module",
-  "keywords": ["pi-package", "pi", "developer", "skills"],
+  "keywords": [
+    "pi-package",
+    "pi",
+    "developer",
+    "skills"
+  ],
   "license": "MIT",
   "author": {
     "name": "dev-hobin",
@@ -21,23 +26,32 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["extensions", "skills", "README.md", "LICENSE"],
+  "files": [
+    "extensions",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
   "engines": {
     "node": ">=22.19.0"
   },
-  "scripts": {
-    "check": "node scripts/check-package.mjs && node --test tests/*.test.ts",
-    "eval": "node scripts/eval-rpc.mjs",
-    "eval:json": "node scripts/eval-json.mjs"
-  },
   "pi": {
-    "extensions": ["./extensions/developer.ts"],
-    "skills": ["./skills"]
+    "extensions": [
+      "./extensions/developer.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
+  },
+  "scripts": {
+    "check": "node scripts/check-package.mjs && node --test tests/*.test.ts",
+    "eval": "node scripts/eval-rpc.mjs",
+    "eval:json": "node scripts/eval-json.mjs"
   }
-}
+}

package/skills/abstraction-review/SKILL.md

@@ -76,7 +76,7 @@ human-owned.
 Do not discover structural movement, create the original design surface, decide
 timing, implement the change, or perform final completion review.
 
-## References
+## Reference Routing
 
 - Read [the field card](references/field-card.md) for substantial or auditable
   reviews.

package/skills/model/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: model
-description: "Model the condition space behind a requirement, invariant, bug, policy, workflow, or code behavior using cases, predicates, rules, forbidden states, transitions, objectives, guarantee placement, and verification targets. Use when correctness depends on combinations, absence or default semantics, state, time, or policy interaction."
+description: "Model the condition space behind a requirement, invariant, bug, policy, workflow, or code behavior using cases, predicates, rules, forbidden states, transitions, objectives, guarantee placement, and verification targets. Use when correctness depends on combinations, absence or default semantics, state, time, or policy interaction, including requests to apply Logic for Programmers-style condition modeling."
 ---
 
 # Model
@@ -69,7 +69,7 @@ Keep provisional rules visibly provisional.
 Do not decide product scope, design the implementation surface, schedule
 structural work, mutate artifacts, or make the final evidence judgment.
 
-## References
+## Reference Routing
 
 Read [the problem-modeling reference](references/problem-modeling.md) for
 policy-heavy, stateful, optimization, safety-critical, or otherwise complex

package/skills/model/references/problem-modeling.md

@@ -18,6 +18,7 @@ task ownership.
 - Verification Target Derivation
 - Stop Checks
 - AI Delegation Boundary
+- Conceptual Lineage
 
 ## Core Question
 
@@ -260,3 +261,14 @@ only a procedure. Provide:
 - verification: counterexamples, gates, and accepted evidence.
 
 AI helpers are not solvers. Their output must still be checked against the model.
+
+## Conceptual Lineage
+
+This reference adapts the practical progression in Hillel Wayne's *Logic for
+Programmers*: make predicates and domains explicit, turn implications into
+counterexamples, choose representations that expose the real decision space,
+and place guarantees where they can be checked. It extends that lineage with a
+problem-shape router, explicit guarantee placement, and an AI delegation
+boundary for product-development work.
+
+- Logic for Programmers: https://leanpub.com/logic

package/skills/naming-judgment/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: naming-judgment
-description: "Review or create code names by separating stable domain meaning from the current implementation. Use when variables, functions, types, modules, components, APIs, fields, or abstractions are generic, misleading, filler-like, implementation-shaped, or carrying multiple product senses."
+description: "Review or create code names by separating stable domain meaning from the current implementation. Use when variables, functions, types, modules, components, APIs, fields, or abstractions are generic, misleading, filler-like, implementation-shaped, or carrying multiple product senses, including requests to apply Elements of Clojure-style naming judgment."
 ---
 
 # Naming Judgment
@@ -71,7 +71,7 @@ Do not implement the rename, promote a new abstraction, invent product meaning,
 rename external conventions, or replace every short name with a longer one.
 Reuse does not prove that a generic name is sound.
 
-## References
+## Reference Routing
 
 Read [the naming reference](references/elements-of-clojure-naming.md) for
 subtle, disputed, or recurring naming pressure.

package/skills/schedule/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: schedule
-description: "Decide whether a concrete structural change or reviewed abstraction candidate belongs now, after, or never using invariant pressure, evidence, reversibility, nested-work pressure, and cost of delay. Use when the candidate is concrete and the consequential question is timing."
+description: "Decide whether a concrete structural change or reviewed abstraction candidate belongs now, after, or never using invariant pressure, evidence, reversibility, nested-work pressure, and cost of delay. Use when the candidate is concrete and timing is consequential, including requests to apply Tidy First-style behavior-versus-structure sequencing."
 ---
 
 # Schedule
@@ -18,6 +18,15 @@ When should this candidate be done: now, after, or never?
 - Current invariant pressure and nested-work pressure
 - Reversibility, cost of delay, risk if done now, and risk if delayed
 
+## Reference Routing
+
+Read [the structural change timing reference](references/structural-change-timing.md)
+when a behavior change and structural change compete, when `now` would remove
+meaningful implementation freedom, or when reversibility, nested work, and cost
+of delay point in different directions. Also read it when an `after` decision
+needs an observable reopen condition. A small, reversible candidate whose
+timing follows directly from the current invariant does not need the reference.
+
 ## Output
 
 Lead with the user's current risk and cost of delay; keep timing labels secondary.

package/skills/schedule/references/structural-change-timing.md

@@ -0,0 +1,150 @@
+# Structural Change Timing
+
+Use this reference when a concrete refactor or abstraction candidate competes
+with a behavior change, and timing depends on reversibility, optionality,
+invariant pressure, or the cost of delay.
+
+## Contents
+
+- Behavior And Structure
+- Timing Vocabulary
+- Decision Procedure
+- Guarantee And Ability Tradeoff
+- Reversibility And Cost Of Delay
+- Nested Work Pressure
+- Reopen Conditions
+- Failure Checks
+- Conceptual Lineage
+
+## Behavior And Structure
+
+Separate two kinds of change before deciding timing:
+
+- behavior change alters what the system does for a user, caller, or policy;
+- structural change alters how the code is arranged while intending to preserve
+  behavior.
+
+The same diff may contain both. Split them conceptually even when they are
+committed together. A structural candidate belongs now only when its timing can
+be justified by the current behavior or invariant—not merely by aesthetic
+preference.
+
+## Timing Vocabulary
+
+This skill uses three outcomes:
+
+- `now`: perform the structural move before or as part of accepted work because
+  it protects the invariant, exposes a needed verification point, or unblocks a
+  safe implementation;
+- `after`: preserve the option but let accepted behavior proceed first;
+- `never`: reject the candidate for the current scope because it is speculative,
+  harmful, or has no evidence-backed pressure.
+
+Kent Beck's broader vocabulary sometimes separates `later` from `after`. Here,
+`after` covers both immediate follow-up and evidence-triggered deferral. The
+reopen condition makes the distinction explicit.
+
+## Decision Procedure
+
+Ask in order:
+
+1. What is the smallest concrete structural candidate?
+2. Which current claim, invariant, caller, or implementation step depends on it?
+3. What evidence shows the candidate is stable enough to act on?
+4. What guarantee does doing it now provide?
+5. What implementation freedom or alternate representation would it remove?
+6. Can a smaller type, contract, test, validation, adapter, or local movement
+   provide the same guarantee?
+7. How reversible is the move if the model changes?
+8. What cost grows if the move is delayed?
+9. What nested work does doing it now create?
+
+Choose `now` when the accepted work is otherwise blocked, unsafe, or difficult
+to verify for a concrete reason. Choose `after` when the move is plausible and
+reversible but not required. Choose `never` when the pressure is cosmetic,
+unrelated, low-confidence, or contradicted by current evidence.
+
+## Guarantee And Ability Tradeoff
+
+Every structure buys a guarantee by removing some ability. Examples:
+
+- a narrower type prevents invalid states but rejects flexible inputs;
+- a shared policy centralizes decisions but removes caller variation;
+- an abstraction barrier protects representation but restricts direct access;
+- normalization simplifies consumers but may erase source distinctions;
+- persistent history enables temporal guarantees but adds storage and ordering
+  obligations.
+
+State both sides. A claimed guarantee is not enough when the lost ability is a
+real product requirement. A claimed flexibility is not enough when it permits a
+modeled forbidden case.
+
+## Reversibility And Cost Of Delay
+
+Prefer earlier structural work when delaying it creates irreversible or rapidly
+growing cost:
+
+- data is persisted in a representation that will be expensive to migrate;
+- public callers begin depending on an accidental contract;
+- several implementations will duplicate the same invariant-bearing policy;
+- tests are impossible to write at the current boundary;
+- the next accepted step compounds hidden state or ownership.
+
+Prefer deferral when the move is cheap to add later, current examples are too
+few, the domain vocabulary is unstable, or the candidate would close several
+valid implementation paths.
+
+Do not confuse large effort with irreversibility. A large but isolated movement
+may remain reversible; a one-line public contract can be difficult to undo.
+
+## Nested Work Pressure
+
+Structural work often discovers more structural work. Count that pressure:
+
+- new public concepts;
+- migrations or compatibility layers;
+- cross-package coordination;
+- new lifecycle or state ownership;
+- additional verification infrastructure;
+- unrelated cleanup required only to make the candidate look complete.
+
+Bias toward `after` when the candidate opens a chain of nested work without
+protecting the current invariant. If a small prerequisite is genuinely needed,
+schedule that prerequisite rather than the full idealized architecture.
+
+## Reopen Conditions
+
+An `after` decision must state observable evidence that reopens it, such as:
+
+- a second caller needs the same contract;
+- another branch repeats the same stable policy;
+- a new requirement reaches the blocked extension point;
+- a performance or migration threshold is crossed;
+- an accepted verifier cannot observe the claim through the current boundary.
+
+Do not use calendar time alone unless timing itself changes the risk. A reopen
+condition should be detectable from code, requirements, evidence, or product
+priority.
+
+## Failure Checks
+
+The timing judgment is weak when:
+
+- the candidate is still only a smell or vague aspiration;
+- `now` means only "the code is messy";
+- `after` has no reopen condition;
+- `never` silently means "not in this task";
+- behavior and structure have not been separated;
+- the guarantee gained is named but the ability lost is ignored;
+- large nested work is hidden inside a small-sounding abstraction;
+- timing substitutes for product prioritization that only a human can decide.
+
+## Conceptual Lineage
+
+This reference adapts Kent Beck's distinction between behavior and structure,
+and his timing vocabulary of first, after, later, and never. The package reduces
+the vocabulary to `now`, `after`, and `never` while preserving reversibility,
+optionality, and cost-of-delay reasoning.
+
+- Structure and behavior: https://newsletter.kentbeck.com/p/structure-and-behavior
+- First, after, later, never: https://newsletter.kentbeck.com/p/first-after-later-never

package/skills/signal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: signal
-description: "Inspect requirements, code, diffs, tests, UI states, names, or recent changes for observable structural movement and classify it as absent, horizontal, vertical, or ambiguous. Use when evidence suggests duplication, model-code mismatch, boundary pressure, or an emerging refactoring candidate."
+description: "Inspect requirements, code, diffs, tests, UI states, names, or recent changes for observable structural movement and classify it as absent, horizontal, vertical, or ambiguous. Use when evidence suggests duplication, model-code mismatch, boundary pressure, or an emerging refactoring candidate, including requests for flocking-style small behavior-preserving refactoring."
 ---
 
 # Signal
@@ -18,6 +18,15 @@ What structural movement is actually visible in the evidence?
 - Invariant or condition model when available
 - Known callers when shared helpers, APIs, or boundaries are involved
 
+## Reference Routing
+
+Read [the flocking and structural movement reference](references/flocking-and-structural-movement.md)
+when duplication, parallel branches, similar tests, repeated UI states,
+conditionals, or a recent refactor need a behavior-preserving next move. Also
+read it when the horizontal/vertical distinction is consequential or the
+available checks may not keep a small movement green. A direct, evidence-backed
+observation with no proposed movement does not need the reference.
+
 ## Output
 
 Lead with the observed code or product pressure; keep signal labels secondary.

package/skills/signal/references/flocking-and-structural-movement.md

@@ -0,0 +1,157 @@
+# Flocking And Structural Movement
+
+Use this reference when duplication, parallel branches, similar tests, repeated
+UI states, conditionals, or a recent refactor create pressure for structural
+movement and the safest next move is not obvious.
+
+## Contents
+
+- Change Pressure
+- The Flocking Cycle
+- Evidence That Keeps The Move Green
+- Horizontal And Vertical Movement
+- Model-Code Mismatch
+- Small-Step Discipline
+- Failure Checks
+- Reporting Shape
+- Conceptual Lineage
+
+## Change Pressure
+
+Start with the current requirement or invariant. Ask whether the existing code
+is already open to the change. If it is, similarity alone does not justify a
+refactor. If it is not, locate the smallest part of the code whose present shape
+blocks or obscures the change.
+
+Structural movement should answer an observed pressure:
+
+- two paths express the same responsibility differently;
+- a stable domain difference is hidden in incidental branching;
+- a default or absence policy is duplicated;
+- a modeled transition is represented as an unrelated current-state check;
+- callers repeat knowledge that should belong behind a boundary;
+- names describe mechanics while the model describes meaning.
+
+## The Flocking Cycle
+
+Work with one selected pair at a time:
+
+1. Select the two things most alike.
+2. State why they are alike: responsibility, vocabulary, transition, failure
+   mode, model element, or user-visible outcome.
+3. Find the smallest meaningful difference between only those two things.
+4. Choose the simplest behavior-preserving move that removes or exposes that
+   difference.
+5. Run the smallest relevant check.
+6. Observe the new shape before choosing another pair.
+7. Delete newly unused code only after the replacement is exercised.
+
+Possible small moves include matching an expression or name, aligning a branch,
+introducing a temporary parameter or adapter, moving one responsibility, or
+calling the new shape before deleting the old one.
+
+If the proposed move changes behavior, touches many unrelated sites, or creates
+a public concept, it is no longer a routine flocking step. Split it or return a
+vertical/ambiguous candidate for review.
+
+## Evidence That Keeps The Move Green
+
+"Behavior preserving" is a claim, not a visual impression. Name the evidence:
+
+- focused tests for the affected responsibility;
+- a characterization test for legacy behavior;
+- typecheck, build, or contract evidence for an interface movement;
+- a representative UI or integration check;
+- a diff inspection showing only structural change;
+- an explicit residual when no cheap verifier exists.
+
+Lower confidence when evidence cannot distinguish the original and moved
+behavior. Do not use a broad green suite as proof when it never exercises the
+selected difference.
+
+## Horizontal And Vertical Movement
+
+Keep movement horizontal when it aligns already-related code inside the current
+abstraction level and leaves no stable new concept behind.
+
+Treat movement as vertical only when, after the difference is understood, a
+nameable concept remains:
+
+- a policy with its own cases;
+- an invariant-bearing boundary;
+- a responsibility with distinct reasons to change;
+- a conversion or representation barrier;
+- state/history ownership;
+- a caller contract shared across uses.
+
+Similarity is not enough. Two pieces may look alike while changing for
+different reasons. Conversely, a vertical concept may first appear as a stable
+difference rather than as duplicated text.
+
+For a vertical or ambiguous candidate, state its pressure, contract-shaped
+meaning, hidden detail, invariant risk, concrete evidence, and evidence still
+needed. Do not promote or schedule it here.
+
+## Model-Code Mismatch
+
+When a problem model exists, check whether code and model disagree:
+
+- a forbidden case remains representable or reachable;
+- a decision space has a missing or conflicting branch;
+- a transition rule sees only the current state and loses history;
+- a caller does not establish a callee precondition;
+- a type admits invalid states without a boundary check;
+- progress or retry behavior is absent from a temporal requirement;
+- a ranking or objective is hidden in incidental ordering;
+- product vocabulary and code vocabulary point to different concepts.
+
+A mismatch may justify structural review even without textual duplication.
+
+## Small-Step Discipline
+
+Keep each move reversible and locally explainable. After every green move,
+reselect the comparison instead of executing a predetermined refactoring plan.
+The newly aligned code may reveal that the next difference is meaningful and
+should remain.
+
+When a move fails its check, revert or repair that move before continuing. Do
+not stack more structural guesses on top of ambiguous evidence.
+
+## Failure Checks
+
+The observation is not ready when:
+
+- no selected pair is named;
+- "duplicate" is the only similarity basis;
+- the smallest difference is actually several differences;
+- the move has no behavior-preserving evidence;
+- a helper is proposed before its stable concept can be stated;
+- line count or static complexity is treated as the only improvement measure;
+- product scope is expanded during structural observation;
+- timing is decided before a concrete candidate exists.
+
+## Reporting Shape
+
+Keep the result auditable:
+
+```text
+Pressure: the requirement, invariant, or mismatch driving observation
+Selected pair: the two most alike artifacts and why
+Smallest difference: one concrete distinction
+Smallest move: one behavior-preserving experiment
+Evidence: the check that keeps the move green
+Classification: no-signal | horizontal | vertical | ambiguous
+Candidate: only for vertical or ambiguous movement
+Missing evidence: what could change the classification
+```
+
+## Conceptual Lineage
+
+This reference adapts the flocking rules and small, behavior-preserving
+refactoring discipline presented by Sandi Metz, Katrina Owen, and TJ Stankus in
+*99 Bottles of OOP*. It extends the comparison with model-code mismatch and
+explicit evidence because the skill must judge real product changes, not only
+remove duplication.
+
+- 99 Bottles of OOP: https://sandimetz.com/99bottles
+- JavaScript sample: https://sandimetz.com/99bottles-sample-js

package/skills/sketch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sketch
-description: "Shape an implementable design surface from a requirement, invariant, problem model, existing code, or representative cases using data definitions, templates, wishful top-level design, interfaces, checks, and a small implementation queue. Use when behavior is understood but ownership, boundaries, data flow, or implementation shape remains unresolved."
+description: "Shape an implementable design surface from a requirement, invariant, problem model, existing code, or representative cases using data definitions, templates, wishful top-level design, interfaces, checks, and a small implementation queue. Use when ownership, boundaries, data flow, or implementation shape remains unresolved, including requests to apply SICP-style wishful thinking or abstraction barriers and HtDP-style design recipes."
 ---
 
 # Sketch
@@ -18,6 +18,16 @@ What design surface makes this intent implementable?
 - Representative normal, boundary, forbidden, and product-meaning cases
 - Constraints and verification targets
 
+## Reference Routing
+
+Read [the design recipe and abstraction barriers reference](references/design-recipe-and-abstraction-barriers.md)
+when data shape, traversal, representation, ownership, or wished interfaces
+carry consequential design judgment. Also read it when a proposed sketch is
+mostly a file-edit plan, when representative cases do not shape the template,
+or when an abstraction barrier needs a concrete stop check. A small local design
+whose purpose, cases, data flow, and first implementation item are already clear
+does not need the reference.
+
 ## Output
 
 Lead with the user's product language; keep design labels secondary.

package/skills/sketch/references/design-recipe-and-abstraction-barriers.md

@@ -0,0 +1,169 @@
+# Design Recipe And Abstraction Barriers
+
+Use this reference when a sketch must do more than name files or helpers: the
+data shape, ownership, traversal, representation boundary, or wished interfaces
+must carry part of the design judgment.
+
+## Contents
+
+- Design Pressure
+- Data Definitions And Templates
+- Wishful Top-Level Design
+- Wished Interfaces As Barriers
+- Representative Cases And Checks
+- Deferred Abstractions
+- Failure Checks
+- Compact Example
+- Conceptual Lineage
+
+## Design Pressure
+
+A useful sketch preserves a chain of reasoning:
+
+```text
+accepted intent
+-> purpose
+-> data or state definitions
+-> representative cases
+-> data-shaped template
+-> wishful top level
+-> wished interfaces and checks
+-> smallest implementation item
+```
+
+Do not start with a file list. A file list records placement after the design is
+known; it does not explain why the design has that shape.
+
+## Data Definitions And Templates
+
+A data definition does more than repeat a type name. State:
+
+- what domain information the data represents;
+- which values are valid members;
+- which values are excluded or impossible;
+- which variants, lifecycle states, or ownership boundaries matter;
+- which fields are available at each branch or traversal point.
+
+Derive the template from that definition. The template should expose the
+structural inventory an implementation must handle:
+
+- one branch for each meaningfully different variant;
+- selectors or fields available in each branch;
+- recursive or collection traversal positions;
+- state transitions and the old/new values they require;
+- ownership handoffs and conversion boundaries.
+
+Merging two branches is allowed only when the accepted intent treats them the
+same. Omitting a branch requires an explicit reason, such as an upstream
+guarantee that makes the state unreachable.
+
+The template is not final code. It is the smallest skeleton that makes missing
+cases, hidden state, and accidental representation choices visible.
+
+## Wishful Top-Level Design
+
+Write the top-level operation as if the right lower-level operations already
+existed. Use the vocabulary of the product contract and problem model rather
+than storage, framework, DOM, transport, or mutation mechanics.
+
+Wishful top-level design should reveal:
+
+- the order of domain operations;
+- which decisions belong at the top level;
+- which details callers should not need to know;
+- which missing concepts need names and contracts;
+- where evidence can check the result.
+
+Do not invent a helper only to shorten code. A wished operation earns a name
+when its purpose and caller-facing assumption can be stated without describing
+its body.
+
+## Wished Interfaces As Barriers
+
+Treat each wished interface as a proposed abstraction barrier. Record:
+
+- purpose: what callers obtain or may assume;
+- input and output shape;
+- contract: preconditions, postconditions, and meaningful failure;
+- owner: the component or layer responsible for the guarantee;
+- hidden detail: representation or mechanism callers must not depend on;
+- stop check: the smallest evidence that would falsify the contract.
+
+An interface is too weak when callers still inspect the hidden representation.
+It is too broad when unrelated policy or lifecycle decisions are bundled behind
+one name. It is speculative when no representative case needs the boundary.
+
+## Representative Cases And Checks
+
+Choose cases before implementation shape hardens. Include only cases that
+distinguish meaningful behavior:
+
+- a normal case;
+- each relevant data variant;
+- a boundary or absence/default case;
+- a forbidden or impossible case;
+- a product-meaning case that a mechanically plausible implementation could
+  get wrong.
+
+Map cases to evidence. Unit examples are not always enough: a type, contract,
+property check, runtime validation, state-transition check, UI inspection, or
+human acceptance may carry the guarantee more directly.
+
+## Deferred Abstractions
+
+Separate three things:
+
+1. design artifacts needed to understand the current change;
+2. implementation items needed to make the accepted behavior real;
+3. abstraction candidates that the sketch noticed but current evidence has not
+   earned.
+
+For each deferred candidate, state the pressure that would reopen it. Do not
+promote it merely because the wished top level uses a convenient name.
+
+## Failure Checks
+
+A sketch is too shallow when:
+
+- it can be reduced to "edit these files" without losing information;
+- the data definition is a type name with no valid/excluded members;
+- the template does not mirror the important variants or traversal shape;
+- wished helpers expose no caller contract or hidden detail;
+- the top level speaks in framework or storage vocabulary;
+- examples all follow the happy path;
+- checks prove execution but not the accepted meaning;
+- deferred ideas silently enter the implementation queue.
+
+Return to product clarification or modeling when the purpose, valid members, or
+case outcomes cannot be stated without guessing.
+
+## Compact Example
+
+For a form-to-domain conversion, do not begin with `add mapper.ts`.
+
+```text
+Purpose: convert editable form state into valid schedule content.
+Data variants: one-time | recurring; optional end date; local date/time input.
+Cases: one-time, recurring without end, recurring with end, invalid interval.
+Template: branch by schedule kind, normalize shared time fields, validate the
+variant, construct domain content.
+Wishful top level: validate(form) -> normalize(form) -> makeScheduleContent(...)
+Barrier: makeScheduleContent hides the domain representation and rejects
+impossible combinations.
+Checks: one table row per meaningful variant and forbidden combination.
+```
+
+The concrete functions may change after repository inspection. The design
+pressure should remain stable.
+
+## Conceptual Lineage
+
+This reference adapts procedural abstraction, data abstraction, wishful
+thinking, and abstraction barriers from Abelson and Sussman's *Structure and
+Interpretation of Computer Programs*, together with the data-directed design
+recipe from Felleisen, Findler, Flatt, and Krishnamurthi's *How to Design
+Programs*. It uses those ideas as design judgment, not as a mandatory phase
+sequence.
+
+- SICP: https://mitpress.mit.edu/sites/default/files/sicp/full-text/book/book.html
+- HtDP: https://htdp.org/2026-5-28/Book/index.html

package/skills/verify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: verify
-description: "Judge what claims are supported by code, tests, diffs, command results, UI states, implementation reports, invariants, or problem models. Use when completion, correctness, coverage, or pass-but-wrong risk depends on mapping current evidence to a concrete claim."
+description: "Judge what claims are supported by code, tests, diffs, command results, UI states, implementation reports, invariants, or problem models. Use when completion, correctness, verifier selection, coverage, source compatibility, structural degradation, or pass-but-wrong risk depends on mapping current evidence to a concrete claim."
 ---
 
 # Verify
@@ -18,6 +18,15 @@ What claims does the available evidence support?
 - Invariant, model, accepted decisions, and verification targets when available
 - Relevant counterexamples and source provenance
 
+## Reference Routing
+
+Read [the verifier selection and pass-but-wrong reference](references/verifier-selection-and-pass-but-wrong.md)
+when several claims need different evidence, a passing command may not exercise
+the accepted meaning, source compatibility matters, or behavior can pass while
+structure degrades. Also read it before a consequential completion claim whose
+verifier relevance or residual risk is unclear. A narrow claim with direct,
+relevant evidence does not need the reference.
+
 ## Output
 
 Lead with the user's claim and observed evidence; keep verification labels secondary.

package/skills/verify/references/verifier-selection-and-pass-but-wrong.md

@@ -0,0 +1,169 @@
+# Verifier Selection And Pass-But-Wrong Risk
+
+Use this reference when a completion claim depends on several kinds of evidence,
+a passing check may not exercise the claim, or structural correctness matters in
+addition to visible behavior.
+
+## Contents
+
+- Claim Before Check
+- Evidence Map
+- Verifier Ladder
+- Execution Versus Relevance
+- Pass-But-Wrong Search
+- Structural Degradation
+- Feedback Classification
+- Residual Risk And Stop Checks
+- Compact Example
+
+## Claim Before Check
+
+State the claim before selecting a verifier. "Tests pass" is an observation;
+"the conversion rejects every impossible schedule variant" is a claim.
+
+Split broad completion statements into independently checkable claims:
+
+- product behavior;
+- forbidden and boundary cases;
+- type or API contract;
+- transition and history behavior;
+- compatibility with the requested source or version;
+- representation or abstraction boundary;
+- operational property such as performance, ordering, or idempotency.
+
+If a claim cannot be stated, return to specification or modeling rather than
+choosing a convenient command.
+
+## Evidence Map
+
+For each claim record:
+
+```text
+Claim: the narrow statement under review
+Verifier: command, inspection, fixture, or human acceptance
+Observation: what actually happened
+Relevance: why the observation bears on the claim
+Counterexample coverage: meaningful wrong shapes exercised or omitted
+Residual: uncertainty that remains
+```
+
+Evidence may be direct, supporting, weak, contradicted, unavailable, or
+human-owned. Do not merge unavailable evidence with passing evidence.
+
+## Verifier Ladder
+
+Prefer the cheapest verifier that can actually falsify the claim:
+
+| Verifier | Best fit |
+| --- | --- |
+| static inspection or focused diff | locality, wiring, ownership, stale code, representation boundary |
+| typecheck, lint, build, manifest check | syntax, imports, compile-time contracts, packaging |
+| focused example test | one concrete behavior or regression |
+| table or parameterized test | finite meaningful cases and boundaries |
+| property or metamorphic check | many examples share a stable rule |
+| integration or UI check | composition, rendering, persistence, external boundaries |
+| state-transition or concurrency fixture | history, ordering, retry, stale events, idempotency |
+| performance or resource measurement | runtime shape is part of the claim |
+| model, solver, or exhaustive check | small critical rule space justifies exhaustive reasoning |
+| human acceptance | the remaining question is policy, meaning, or visual judgment |
+
+Use a stronger verifier when a weaker one can pass under a plausible wrong
+implementation. Use a weaker verifier when it is the only practical evidence,
+but narrow the claim and record the residual.
+
+## Execution Versus Relevance
+
+A verifier execution proves only that the verifier ran and produced an
+observation. Check relevance separately:
+
+- Did the fixture reach the changed branch?
+- Did assertions inspect the product meaning or only absence of an exception?
+- Did the build use the source and version requested by the user?
+- Did a UI snapshot expose interaction and state changes or only initial pixels?
+- Did a broad suite include the new boundary case?
+- Did the manual inspection examine the actual generated artifact?
+
+A green but irrelevant verifier creates a `verifier-gap`; it does not support
+the broader claim.
+
+## Pass-But-Wrong Search
+
+For every consequential claim, imagine at least one implementation that passes
+current checks while violating the intended meaning. Look for:
+
+- missing branches whose fixtures never occur;
+- fallback/default behavior that silently selects product policy;
+- assertions that accept both the intended and an unintended value;
+- mocks that bypass the real boundary;
+- tests coupled to the implementation rather than the contract;
+- source/version mismatch;
+- current-state checks that miss invalid transitions;
+- correct result with wrong ordering, mutation, sharing, or complexity;
+- public API compatibility tested without real consumers.
+
+When a plausible shape remains cheap to test, add the smallest distinguishing
+fixture. Otherwise record it as residual risk instead of broadening the claim.
+
+## Structural Degradation
+
+Behavior may pass while the change weakens the code's ability to preserve the
+same guarantee. Inspect for:
+
+- duplicated invariant or absence/default policy;
+- representation details leaking through a caller contract;
+- generic abstraction without stable examples or a nameable purpose;
+- hidden state, history, ordering, or ownership;
+- vocabulary drifting away from the accepted model;
+- a local fix that makes the next accepted requirement harder or unsafe;
+- tests passing only because they mirror the new implementation.
+
+Structural degradation is evidence for structural observation or abstraction
+review. It does not automatically require refactoring now.
+
+## Feedback Classification
+
+Use a small, stable taxonomy:
+
+- `pass`: the evidence supports the narrow claim;
+- `implementation-fail`: relevant evidence contradicts the accepted claim;
+- `model-or-spec-fail`: evidence shows the accepted meaning or case model is
+  wrong or incomplete;
+- `verifier-gap`: the check is missing or irrelevant to the claim;
+- `blocked-environment`: the required source or environment was not exercised;
+- `pass-but-wrong-risk`: current evidence passes while a plausible wrong shape
+  remains;
+- `structural-degradation`: behavior passes but structure weakens a relevant
+  boundary or guarantee.
+
+Classification describes the observation. The caller decides whether to
+repair, remodel, add evidence, ask a human, accept residual risk, or continue.
+
+## Residual Risk And Stop Checks
+
+Verification is complete enough when:
+
+- every stated claim is supported, narrowed, or explicitly unverified;
+- each important forbidden or boundary case has evidence or a residual;
+- actual source and version match the requested target;
+- plausible pass-but-wrong shapes were attempted or recorded;
+- structural claims have more than behavioral evidence when needed;
+- human-owned acceptance is distinguished from mechanical checks;
+- another verifier would cost more than the information it is expected to add.
+
+Do not claim total correctness from a finite evidence set. State the strongest
+claim justified now.
+
+## Compact Example
+
+```text
+Claim: recurring schedules without an end date remain valid.
+Verifier: focused table test with one-time, recurring-open, recurring-bounded,
+and invalid-interval rows.
+Observation: all rows produce the expected domain result.
+Relevance: each semantic variant crosses the new conversion boundary.
+Pass-but-wrong search: a mapper could still ignore timezone normalization.
+Residual: timezone behavior remains unverified and is not included in the
+supported claim.
+```
+
+The correct result is a narrower supported claim, not an unqualified "done."