@hobin/developer 0.1.1 → 0.1.3

package/skills/sketch/references/generic-operations-and-languages.md

@@ -0,0 +1,134 @@
+# Generic Operations And Languages
+
+Use this reference when several representations must coexist additively, or
+when ordinary data and functions are becoming a small language with its own
+evaluation semantics.
+
+## Two Axes Of Generic Operations
+
+Write the matrix before choosing classes, visitors, multimethods, or a registry:
+
+| Representation | `charge` | `refund` | `describe` |
+| --- | --- | --- | --- |
+| Card | method | method | method |
+| Bank transfer | method | unsupported | method |
+| Store credit | method | method | method |
+
+There are two independent pressures:
+
+- horizontal: higher-level operations should not know representation fields;
+- vertical: adding a representation should not require editing every old
+  representation package.
+
+One possible data-directed surface is:
+
+```text
+register(kind, operation, method)
+applyGeneric(operation, taggedValue, ...args)
+```
+
+Specify duplicate registration, missing method, load order, type transitions,
+and error visibility. Then add a fake representation. Existing callers and old
+representation modules should remain unchanged. If only two stable variants
+exist, a local conditional may be cheaper and clearer.
+
+## Coercion And Meaning Preservation
+
+For mixed representations, draw paths:
+
+```text
+Integer -> Rational -> Decimal
+Money(USD) -X-> Money(EUR) without an exchange-rate context
+```
+
+For each edge state preserved meaning and lost ability: precision, identity,
+order, metadata, or capability. Choose direct operation, coercion, canonical
+representation, or explicit rejection. A convenient path that silently loses
+meaning is not genericity.
+
+## Symbolic Data Boundary
+
+When code inspects formulas, queries, or rules, represent notation as data:
+
+```text
+Expr = Number(value) | Variable(name) | Sum(left, right) | Product(left, right)
+```
+
+Algorithms use predicates/selectors/constructors or pattern matching on this
+semantic definition, not string indexes. Constructors may own simplification:
+
+```text
+makeSum(0, x) -> x
+makeSum(x, 0) -> x
+makeSum(x, y) -> Sum(x, y)
+```
+
+That policy must be explicit because it changes the representation while
+preserving intended expression meaning.
+
+## When Data Becomes A Language
+
+A rule table, query builder, workflow schema, or configuration is a language
+only when it has:
+
+```text
+primitives: smallest valid expressions
+combination: how expressions form larger expressions
+abstraction: how recurring expressions receive reusable names
+validation: well-formed versus invalid programs
+evaluation: what an expression means in an environment
+errors: parse, validation, runtime, and unsupported behavior
+evolution: versioning, migrations, and compatibility
+```
+
+Worked policy DSL sketch:
+
+```text
+Policy = Allow(Role) | HasTag(Tag) | All(List<Policy>) | Any(List<Policy>)
+
+evaluate(Allow("admin"), env) = env.user.role == "admin"
+evaluate(All([]), env) = true
+evaluate(All([p, ...rest]), env) = evaluate(p, env) && evaluate(All(rest), env)
+```
+
+Define invalid states, such as an unknown role or empty `Any`, rather than
+letting a host-language exception become language semantics.
+
+## Evaluator Boundary
+
+Keep the evaluator contract distinct from syntax:
+
+```text
+evaluate : Program x Environment -> Result | LanguageError
+```
+
+State evaluation order, scope, effects, termination limits, and resource
+budgets. A mathematically equivalent rewrite may not preserve host-language
+short-circuiting, effects, or exceptions.
+
+Do not build a DSL when ordinary typed data plus functions keep policy more
+visible. The evaluator, migrations, debugging tools, and error messages are
+product code, not free infrastructure.
+
+## Artifact
+
+```text
+Variant-operation matrix:
+Representation barrier:
+Registration/dispatch and unsupported policy:
+Conversion graph and preserved meaning:
+Language primitives/combinations/abstractions:
+Validation and evaluator contract:
+Errors, effects, versioning, and limits:
+Fake variant or example program check:
+Simpler ordinary-data alternative:
+```
+
+## Source Trace
+
+- *Structure and Interpretation of Computer Programs*, Second Edition,
+  sections 2.4-2.5 and chapters 4-5: multiple representations, generic
+  operations, data-directed programming, symbolic data, metalinguistic
+  abstraction, evaluators, and explicit machines.
+- Hillel Wayne, *Logic for Programmers*, version 0.14.0, May 4, 2026:
+  model/runtime distinctions and ability-guarantee tradeoffs.

package/skills/sketch/references/processes-state-and-time.md

@@ -0,0 +1,171 @@
+# Processes, State, And Time
+
+Use this reference when returned values alone do not describe correctness. The
+same procedure text can generate recursive, iterative, tree-shaped, delayed, or
+stateful processes with different time, space, order, and failure behavior.
+
+## Procedure Versus Process
+
+Trace a representative execution:
+
+```text
+procedure: retry(operation, 3)
+process:
+  attempt 1 -> retryable failure -> wait 100 ms
+  attempt 2 -> retryable failure -> wait 200 ms
+  attempt 3 -> success
+```
+
+Record:
+
+```text
+result
+work generated at each step
+deferred work or stack growth
+state retained or duplicated
+time/space scale
+ordering and failure surface
+```
+
+A recursive tree walk and an iterative queue walk may return the same nodes but
+have different stack, ordering, and memory contracts. A fluent one-line pipeline
+may materialize three full collections. Short procedure text is not evidence of
+a cheap or simple process.
+
+## State Means History Matters
+
+Compare two calls with identical explicit input:
+
+```text
+account.withdraw(40) -> Accepted
+account.withdraw(40) -> Rejected
+```
+
+If prior interactions explain the difference, state is part of the contract.
+Fill:
+
+```text
+required history: accepted deposits and withdrawals
+sufficient summary: current balance
+owner: account instance
+writers: deposit and withdraw
+identity: two equal balances may be different accounts
+aliases: references that observe the same mutation
+order law: sufficient-funds check and balance update are one transition
+```
+
+Local state is modular when it hides a coherent history behind a small
+interface. It is hazardous when aliases, retries, concurrency, or persistence
+make the history owner unclear.
+
+## Explicit State Machine Alternative
+
+Represent time as data when transitions need review, replay, or distribution:
+
+```text
+Payment = Created | Authorizing(attempt) | Authorized(id) | Failed(reason)
+
+transition(Created, Authorize) -> Authorizing(1)
+transition(Authorizing(n), Retryable) -> Authorizing(n + 1)
+transition(Authorizing(_), Approved(id)) -> Authorized(id)
+transition(Authorized(_), Approved(_)) -> invalid or idempotent policy
+```
+
+State the unchanged part of each transition and cover stale, duplicate,
+reordered, retried, and concurrent events. A correct enum is not a correct
+history model.
+
+## Event Order And Atomicity
+
+For concurrent withdrawal, the forbidden interleaving is:
+
+```text
+A reads 100
+B reads 100
+A writes 20 after withdrawing 80
+B writes 20 after withdrawing 80
+```
+
+Both calls appear accepted although 160 was withdrawn. The order law is not
+“serialize everything”; it is:
+
+```text
+read balance -> check funds -> write next balance
+```
+
+must behave as one protected transition for a given account. Choose a lock,
+transaction, queue, compare-and-swap loop, or merge policy only after stating
+that law and its waiting/fairness cost.
+
+## Streams And Logs
+
+An explicit stream/log represents successive states or events:
+
+```text
+events -> fold(transition, initialState) -> currentState
+```
+
+It improves replay, audit, time travel, merge reasoning, and functional
+composition. It also creates retention, ordering, identity, versioning, and
+reconstruction-cost obligations. Choose it when history is product evidence,
+not merely because mutation is unfashionable.
+
+For delayed streams also record demand:
+
+```text
+producer pace
+consumer pace
+buffer/backpressure
+single-use versus replayable
+failure and cancellation
+```
+
+## Pull, Transform, Push Process Check
+
+```text
+pull: where external time and failure enter
+transform: domain computation and its data contract
+push: effect interpretation, idempotency, and partial failure
+apex: coordinator that owns the whole process outcome
+```
+
+The separation is false when pull retries silently alter transform semantics or
+push performs an unreported partial success. Conversely, splitting one atomic
+transaction into these phases may violate the actual invariant.
+
+## Process/State Artifact
+
+```text
+Procedure promise:
+Representative process trace:
+Shape and time/space cost:
+Required history and sufficient summary:
+State or log owner and writers:
+Identity and alias behavior:
+Order/atomicity law:
+Retry, stale, duplicate, and concurrency policy:
+Alternative representation considered:
+Evidence and residual risk:
+```
+
+## Failure Diagnosis
+
+- Result tests pass but stack, buffering, or order matters: add a process-shaped
+  verifier.
+- Same call changes but no history is named: revise the state contract.
+- A state machine lists states but not events and next states: derive the
+  transition relation.
+- All work is serialized: narrow the protected order law.
+- A log is proposed without replay/audit/merge pressure: local state may be the
+  smaller honest model.
+- A pipeline stage hides effects: expose the phase or rename the process
+  honestly.
+
+## Source Trace
+
+- *Structure and Interpretation of Computer Programs*, Second Edition,
+  chapters 1 and 3: procedure/process distinction, state and assignment,
+  identity and sharing, concurrency, constraints, delayed evaluation, and
+  streams.
+- Zachary Tellman, *Elements of Clojure*, 2019: units of computation and the
+  construction of pull-transform-push processes.

package/skills/sketch/references/responsibility-and-variation.md

@@ -0,0 +1,245 @@
+# Responsibility And Variation
+
+Use this reference when a real change exposes misplaced knowledge, repeated
+arguments, data clumps, conditional dispatch, type transitions, object creation,
+or uncertainty about which collaboration should absorb variation.
+
+## Begin With The Change
+
+Do not design toward classes, polymorphism, or a factory in advance. State the
+accepted change and show where the current code resists it. A smell identifies a
+point of attack, not the final architecture.
+
+Keep a simple concrete solution when it remains understandable and cheap to
+change. A more elaborate design is justified by localized future change, not by
+lower line count or the prestige of a pattern.
+
+## Inventory Responsibilities
+
+Describe what the current unit:
+
+- knows;
+- calculates or decides;
+- coordinates;
+- creates;
+- sends to collaborators;
+- changes for independent reasons.
+
+Write wishful pseudocode in messages rather than field manipulation. A message
+asks a receiver that owns relevant knowledge to do work. Repeatedly pulling data
+out of one object so another can decide what it means is evidence of misplaced
+responsibility.
+
+## Smells As Design Evidence
+
+Inspect smells on the accepted change path:
+
+- a value repeatedly passed through methods that already belong to one concept;
+- several fields or parameters that move as a data clump;
+- conditionals that select behavior by a stable domain variant;
+- methods that mostly inspect another unit's data;
+- a coordinator that both chooses a variant and implements each variant;
+- object construction mixed into domain collaboration;
+- a chain of navigation that exposes collaborator structure.
+
+The sketch should show how one concrete movement would make the change local.
+Do not clean unrelated smells to make the design look complete.
+
+## Extracting A Responsibility
+
+A candidate unit is credible when data and behavior form a coherent concept with
+its own reason to change. State:
+
+```text
+Responsibility: what the unit owns
+Knowledge: data or history required to fulfill it
+Messages: minimal caller-visible protocol
+Hidden detail: mechanics callers stop knowing
+Creation: who constructs or selects it
+Representative change: change that becomes local
+Rejected placement: why the old owner was wrong
+```
+
+Move callers gradually when old and new forms can coexist. The implementation
+protocol owns those edits; this reference only shapes the target collaboration.
+
+Immutability often makes an extracted value easier to share and reason about,
+but it is not mandatory when identity or local history is the product model.
+
+## Variation And Substitution
+
+Use polymorphism only when variants share a real role and callers can send the
+same message without knowing the concrete type. State the role contract and
+unsupported cases.
+
+A subtype or implementation must preserve caller expectations. A special case
+that raises, changes return meaning, or requires stronger preconditions may not
+belong under the common role. Model old and new contracts before claiming safe
+substitution.
+
+Conditionals are not categorically wrong. Keep them when the variation is local,
+finite, readable, and unlikely to grow independently. Replace them when new
+accepted variants repeatedly force old behavior owners to change.
+
+## Type Transitions
+
+When one domain value leads to another kind of value, model the transition as a
+domain relation rather than scattered numeric or string manipulation. State:
+
+- current type and next type;
+- operation or event causing the transition;
+- preserved meaning;
+- boundary or terminal behavior;
+- whether the target selects itself or a collaborator decides.
+
+Transitions that violate a common role may require a narrower protocol or an
+explicit result type instead of inheritance.
+
+## Object Creation And Factories
+
+Creation policy belongs at a boundary where variant information is available.
+Keep domain collaborators dependent on the role they use, not on class-name or
+registration mechanics.
+
+Factory designs form a continuum: a concrete conditional, configurable mapping,
+registration, self-registration, or automatic discovery each moves knowledge
+and adds operational cost. Compare:
+
+- who knows available variants;
+- how a new variant is introduced;
+- unsupported and duplicate registration behavior;
+- load order, reflection, naming, and deployment assumptions;
+- testability and failure visibility.
+
+Choose the least powerful mechanism that satisfies real extension pressure.
+Pushing construction to the edge often removes the need for an elaborate
+factory inside the domain.
+
+## Dependency Direction And Navigation
+
+High-level product behavior should depend on stable roles rather than concrete
+variant mechanics. Inject a dependency when it represents a caller-chosen
+collaborator, not merely to make every object configurable.
+
+Long navigation chains reveal structural knowledge. Prefer asking the first
+meaningful collaborator for the domain result, but do not add forwarding methods
+that only hide an unchanged data path. The receiving responsibility must become
+more coherent.
+
+## Tests As Role Evidence
+
+Choose units to test by public responsibility and cost of failure, not by one
+test file per class. Use integration evidence for collaborations and focused
+unit evidence for stable role contracts or difficult cases.
+
+Fakes are useful when they express the same role without importing irrelevant
+context. Tests that echo implementation structure, duplicate the same behavior
+at every layer, or preserve obsolete context inhibit redesign.
+
+## Complete Example: Move Discount Knowledge
+
+Accepted change: subscriptions now support a partner discount in addition to a
+student discount. Current `Checkout` receives `student`, `partner`, `country`,
+and `subtotal`, then selects and calculates every discount itself.
+
+### Inventory the current owner
+
+```text
+Checkout knows:
+  customer flags, discount precedence, formulas, country exclusions
+Checkout decides:
+  which discount applies
+Checkout coordinates:
+  pricing, payment, receipt
+Checkout changes when:
+  discount policy, payment flow, or receipt flow changes
+```
+
+The problem is not the conditional alone. Discount knowledge and behavior have
+a different reason to change from checkout coordination.
+
+### Write wished messages
+
+```text
+discount = discountPolicy.for(customer, country)
+payable = discount.applyTo(subtotal)
+checkout.charge(payable)
+```
+
+Candidate responsibility:
+
+```text
+Responsibility: choose and apply the accepted discount policy
+Knowledge: eligibility, precedence, exclusions, calculation
+Messages: for(customer, country); applyTo(money)
+Hidden detail: flags and formula selection
+Creation: composition root supplies current policy set
+Representative change: add partner eligibility and formula locally
+```
+
+If student and partner discounts share `applyTo(Money) -> Money` with the same
+preconditions and result meaning, they may honor one role. If partner discount
+requires an asynchronous provider lookup, it cannot silently substitute for a
+pure discount. The boundary may instead return an eligibility decision or move
+the lookup to the pull phase.
+
+A local finite rule table may remain clearer than a class per discount. Add a
+factory or registry only if creation or extension pressure is real. Constructing
+the policy set at the edge keeps `Checkout` independent without inventing
+discovery.
+
+Smallest implementation surface:
+
+```text
+1. characterize current student behavior with responsibility-level examples
+2. introduce DiscountPolicy behind the existing result
+3. move one policy calculation while keeping Checkout behavior green
+4. add partner behavior through the same caller-visible contract
+5. inspect whether the role remains coherent; stop at the stable landing
+```
+
+This reference shapes the collaboration. The direct execution protocol owns the
+sender-by-sender mutation, and `abstraction-review` decides whether the candidate
+is stable enough to keep.
+
+## Sketch Output
+
+```text
+Change pressure: accepted change exposing the design issue
+Current responsibility inventory: knows, decides, coordinates, creates
+Point of attack: concrete smell on the change path
+Wished messages: collaboration in domain language
+Candidate ownership: data, behavior, hidden detail, reason to change
+Variation model: role, variants, substitution and unsupported cases
+Creation boundary: selection knowledge and factory tradeoff
+Checks: behavior, role, integration, and pass-but-wrong cases
+First item: smallest implementation step
+Deferred: patterns or variants not yet supported by evidence
+```
+
+## Failure Checks
+
+- a pattern or class hierarchy is selected before the change is stated;
+- responsibility is inferred from duplicated syntax alone;
+- an extracted object has no knowledge or reason to change of its own;
+- polymorphism hides incompatible contracts;
+- a factory solves hypothetical discovery or registration needs;
+- dependency injection adds configuration without isolating real variation;
+- navigation is hidden by forwarding methods without moving responsibility;
+- tests freeze current internals rather than verify roles and behavior.
+
+## Source Trace
+
+- Sandi Metz, Katrina Owen, and TJ Stankus, *99 Bottles of OOP*, Second
+  Edition, version 2.2.2, 2024: chapters 3-9 on listening to change, smells and
+  points of attack, responsibility extraction, argument removal, immutability,
+  Liskov substitution, conditional-to-polymorphic movement, type transitions,
+  factories, wishful pseudocode, dependency inversion, Law of Demeter, creation
+  at the edge, and responsibility-focused testing.
+- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
+  Interpretation of Computer Programs*, Second Edition, MIT Press, 1996:
+  multiple representations, generic operations, data-directed programming, and
+  additivity.
+- Zachary Tellman, *Elements of Clojure*, 2019: indirection cost, module
+  assumptions, and the distinction between cohesive components and adaptable
+  interfaces.

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

@@ -11,10 +11,11 @@ addition to visible behavior.
 - Verifier Ladder
 - Execution Versus Relevance
 - Pass-But-Wrong Search
+- Test Design And Cost
 - Structural Degradation
 - Feedback Classification
 - Residual Risk And Stop Checks
-- Compact Example
+- Complete Evidence Example
 
 ## Claim Before Check
 
@@ -104,6 +105,31 @@ current checks while violating the intended meaning. Look for:
 When a plausible shape remains cheap to test, add the smallest distinguishing
 fixture. Otherwise record it as residual risk instead of broadening the claim.
 
+## Test Design And Cost
+
+Tests are design evidence only when their boundary and maintenance cost remain
+useful. Prefer tests that expose public responsibility and product meaning over
+tests that echo private method structure.
+
+Choose the unit by the claim:
+
+- focused examples for stable responsibility and boundary cases;
+- role or contract tests when several implementations must substitute;
+- integration tests for collaborations, creation, persistence, and wiring;
+- properties when many examples share a generatable rule;
+- stateful fixtures when history, retry, order, or identity matters.
+
+Do not require one test layer per class. Loose coupling may make a smaller unit
+economical to test, while simple forwarding or framework glue may be better
+covered by a larger behavior check. Fakes should remove irrelevant context while
+preserving the collaborator role; mocks that restate call internals create an
+echo chamber.
+
+Delete or reorganize tests only when the remaining evidence still supports the
+same claims. Redundancy is sometimes cheap insurance and sometimes obsolete
+context that prevents a design from moving. State which claim each retained test
+protects.
+
 ## Structural Degradation
 
 Behavior may pass while the change weakens the code's ability to preserve the
@@ -153,7 +179,7 @@ Verification is complete enough when:
 Do not claim total correctness from a finite evidence set. State the strongest
 claim justified now.
 
-## Compact Example
+## Complete Evidence Example
 
 ```text
 Claim: recurring schedules without an end date remain valid.
@@ -166,4 +192,36 @@ 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."
+Now attempt a wrong implementation that always emits `recurring-open` whenever
+`endDate` is absent. It passes the open-recurring row but also misclassifies a
+one-time schedule whose UI omitted an optional display field. Add a one-time row
+with the same absence shape but a different recurrence discriminator. This
+fixture fails the plausible wrong rule while remaining at the public conversion
+boundary.
+
+Map the broader completion claim:
+
+| Claim | Verifier | What it can still miss |
+| --- | --- | --- |
+| semantic variants convert correctly | focused table test | persisted legacy shapes not in the table |
+| public type accepts intended callers | typecheck plus real caller build | runtime external input |
+| legacy saved schedules remain readable | migration fixture through persistence adapter | unknown production corruption |
+| UI shows the converted meaning | interaction test or manual run | timezone/environment variance |
+| package contains the changed source | packed-tarball inspection and fresh install | registry propagation delay |
+
+If only the first row is executed, report only the first claim. The correct
+result is a narrower supported statement, not an unqualified “done.”
+
+## Source Trace
+
+- Hillel Wayne, *Logic for Programmers*, version 0.14.0, May 4, 2026:
+  strong and weak tests, partial specifications, structural properties,
+  property-based testing, contracts, and proof limitations.
+- Sandi Metz, Katrina Owen, and TJ Stankus, *99 Bottles of OOP*, Second
+  Edition, version 2.2.2, 2024: chapters 2 and 9 on cost-effective tests,
+  avoiding implementation echo, choosing units, unit versus integration tests,
+  context independence, fakes, role verification, and obsolete-test removal.
+- Matthias Felleisen, Robert Bruce Findler, Matthew Flatt, and Shriram
+  Krishnamurthi, *How to Design Programs, Second Edition*, MIT Press, 2018:
+  representative examples and tests as successive constraints in a design
+  recipe.