@hobin/developer 0.1.1 → 0.1.2

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

@@ -0,0 +1,202 @@
+# Structural Movement
+
+Use this reference when duplication, parallel branches, repeated tests, code
+smells, or a model-code mismatch suggests movement but does not yet justify an
+abstraction or implementation plan.
+
+## Central Question
+
+What is actually moving in the evidence, and what smallest observation could
+distinguish incidental similarity from a durable concept?
+
+Structural movement is discovered from current behavior and pressure:
+
+```text
+correct-enough concrete behavior
+-> an actual requested change or accepted model mismatch
+-> a selected comparison and smallest meaningful difference
+-> a behavior-preserving observation experiment
+-> no-signal | horizontal | vertical | ambiguous
+```
+
+The final classification is this leaf's result. Performing the movement,
+approving the candidate, choosing its timing, and designing a later object model
+belong elsewhere.
+
+## Establish Observable Pressure
+
+Do not manufacture a future requirement. State the current request, invariant,
+or mismatch and identify where the existing arrangement resists it. Code that
+was appropriate for a previous requirement may become awkward only after new
+evidence arrives.
+
+A simple concrete implementation with temporary duplication can be a strong
+baseline when it is understandable and protected by relevant examples. Visible
+duplication without current pressure is not an instruction to refactor. Return
+`no-signal` when the behavior is cheap to change and no accepted claim is being
+inhibited.
+
+## Select The Comparison
+
+Choose two artifacts that are most alike by one meaningful basis:
+
+- responsibility or user-visible result;
+- domain vocabulary or data interpretation;
+- state transition or failure mode;
+- call shape, message sequence, or policy;
+- test scenario, UI state, or model element.
+
+Then name one smallest difference. Sameness locates a comparison; difference
+carries the design information. Comparing every duplicate at once usually hides
+which difference is incidental and which preserves product meaning.
+
+## Form A Falsifying Small Move
+
+Name the smallest behavior-preserving movement that would make the selected
+difference easier to inspect. Typical candidates align one branch, expression,
+parameter, message, local name, or test shape.
+
+The move is an observation experiment, not a command. Record:
+
+```text
+Baseline behavior: the claim intended to stay true
+Selected pair: the two comparable artifacts
+Smallest difference: one concrete distinction
+Proposed movement: one locally reversible alignment
+Relevant check: evidence that could detect behavior drift
+Revealing result: what would support or reject the suspected structure
+```
+
+If the relevant evidence is missing, return `needs-evidence`. Do not rewrite
+tests merely so a proposed refactor can remain green.
+
+## Horizontal Movement
+
+Classify movement as horizontal when alignment stays at the current level:
+
+- branches or expressions gain a consistent shape;
+- names, parameters, or messages become comparable;
+- no independent policy, invariant, or reason to change remains;
+- the movement stays local and reversible.
+
+A stable landing is useful evidence: the code is green, understandable, safe to
+pause, and newly comparable. It is not permission to continue toward a
+predetermined design. Re-select the closest pair from the new state.
+
+## Vertical Movement
+
+Classify a candidate as vertical only when a nameable unit survives horizontal
+alignment, such as:
+
+- a responsibility with its own reason to change;
+- a policy with independent cases;
+- an invariant-bearing representation boundary;
+- a role that several implementations can honor;
+- state or history with a clear owner;
+- a conversion or type transition with a caller contract.
+
+Return the concrete candidate, pressure, hidden detail, callers, invariant risk,
+and missing evidence. `abstraction-review` decides whether the candidate is
+stable. Similarity alone does not justify a helper, class, strategy, factory, or
+public interface.
+
+## Ambiguous Movement
+
+Return `ambiguous` when the selected difference may be either incidental or
+semantic and an accessible observation could change the answer. Name that
+observation precisely: another caller, representative case, diff, runtime trace,
+or accepted product rule.
+
+Do not hide uncertainty by selecting a more polished design. A useful ambiguous
+result makes the next evidence cheap to gather.
+
+## Model-Code Mismatch
+
+Structural pressure may also appear without textual duplication. Compare the
+accepted model with the implementation for:
+
+- forbidden cases that remain representable or reachable;
+- missing or conflicting decision branches;
+- transition rules that lose required history;
+- callers that fail to establish callee preconditions;
+- duplicated absence or default policy with no owner;
+- stale, retried, reordered, or concurrent events with no rule;
+- product and code vocabulary that name different concepts.
+
+Use a behavior-preserving movement only to expose the mismatch. When satisfying
+the model requires changed behavior, keep that behavior change explicit.
+
+## Worked Observation
+
+Baseline: tests protect verses 1, 2, and 0 in a simple formatter. A new accepted
+requirement adds verse 3. The Shameless Green change copies the verse-2 branch
+and changes two phrases. All tests are green.
+
+```text
+Pressure:
+  verse 3 is now accepted and exposes another parallel branch
+Selected pair:
+  verse 2 and verse 3 branches, closest by output responsibility
+Smallest difference:
+  the quantity and one noun phrase
+Observation move:
+  align the two branches into the same expression shape without extracting a
+  helper or changing output
+Relevant check:
+  exact output tests for verses 0 through 3
+```
+
+After alignment, suppose the only differences are `count` and a phrase selected
+from `count`. That is still horizontal movement: the branches are more directly
+comparable and the code is at a stable landing. Stop and re-observe.
+
+If a policy survives—such as a `ContainerDescription` that owns singular/plural
+wording and changes independently across several callers—report a vertical
+candidate with its callers and hidden policy. Do not create the object here.
+
+If verse 3 introduced a unique legal notice, the textual similarity was
+incidental. Report `no-signal` or a narrower horizontal result rather than
+forcing the notice into a generic formatter. An ambiguous result names the
+missing evidence, such as whether a second UI surface shares the wording rule.
+“Maybe we need a strategy” is not evidence.
+
+## Reporting Shape
+
+```text
+Pressure: current requirement, invariant, or model mismatch
+Baseline: current behavior and relevant evidence
+Selected pair: artifacts and comparison basis
+Smallest difference: one meaningful distinction
+Observation move: smallest behavior-preserving experiment
+Evidence: check and current gap
+Classification: no-signal | horizontal | vertical | ambiguous
+Candidate: only for vertical or ambiguous movement
+Handoff: implementation, abstraction-review, schedule, naming-judgment, or none
+```
+
+## Failure Checks
+
+The capability is being misused when:
+
+- duplication is treated as sufficient pressure;
+- a speculative future requirement selects the direction;
+- no pair or single difference is named;
+- the proposed experiment changes behavior;
+- a destination such as polymorphism or a factory is chosen in advance;
+- the leaf performs the edit instead of returning the observation;
+- horizontal similarity is promoted directly into a vertical abstraction;
+- line count or a static metric substitutes for change-cost evidence.
+
+## Source Trace
+
+- Sandi Metz, Katrina Owen, and TJ Stankus, *99 Bottles of OOP*, Second
+  Edition, version 2.2.2, 2024: chapters 1-4 on Shameless Green, listening to
+  change, points of attack, flocking, concentrating on difference, horizontal
+  movement, and stable landings.
+- Matthias Felleisen, Robert Bruce Findler, Matthew Flatt, and Shriram
+  Krishnamurthi, *How to Design Programs, Second Edition*, MIT Press, 2018:
+  deriving abstractions by comparing completed concrete designs and lifting
+  corresponding differences.
+- Kent Beck, *Tidy First?: A Personal Exercise in Empirical Software Design*,
+  O'Reilly Media, 2023: small behavior-preserving structural moves and the need
+  to keep them separate from behavior changes.

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 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."
+description: "Shape an implementable design surface from a requirement, invariant, problem model, existing code, or representative cases using data definitions, templates, wished interfaces, collaborations, checks, and a small implementation queue. Use when ownership, boundaries, data flow, recursion, state, composition, responsibility, variation, or implementation shape remains unresolved."
 ---
 
 # Sketch
@@ -20,13 +20,40 @@ What design surface makes this intent implementable?
 
 ## 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.
+Read [the data-driven design reference](references/data-driven-design.md) when
+the information model, data variants, traversal, recursion, examples, or tests
+should determine the function skeleton. Read it when a proposed sketch jumps
+from prose to helpers without deriving cases and a template from the data.
+
+Within that capability, read [the data-shape template catalog](references/data-shape-template-catalog.md)
+when atomic, itemized, structured, recursive, intertwined, multi-input, output,
+or interactive data must derive a template. Read
+[composition, generative recursion, and accumulators](references/composition-generative-recursion-and-accumulators.md)
+for wished auxiliaries, abstraction from completed functions, generated
+subproblems and termination, or an invariant-bearing accumulator.
+
+Read [the abstraction, composition, and state reference](references/abstraction-composition-and-state.md)
+when wishful top-level design, representation independence, abstraction
+barriers, compositional interfaces, module assumptions, environmental process
+boundaries, state/history ownership, or levels of language carry consequential
+judgment.
+
+Within that capability, read [abstraction barriers and closure](references/abstraction-barriers-and-closure.md)
+for a representation or combination boundary,
+[processes, state, and time](references/processes-state-and-time.md) for runtime
+shape, history, identity, streams, concurrency, or order, and
+[generic operations and languages](references/generic-operations-and-languages.md)
+for additive representations, coercion, symbolic data, a DSL, or an evaluator.
+
+Read [the responsibility and variation reference](references/responsibility-and-variation.md)
+when real change pressure exposes repeated arguments, data clumps, conditional
+dispatch, misplaced knowledge, role substitution, object creation, factory
+tradeoffs, or test-unit boundaries.
+
+Read multiple references only when their questions genuinely combine: for
+example, data shape may derive the operational skeleton while abstraction and
+responsibility evidence determine its boundaries. A small local design whose
+purpose, cases, data flow, and first item are already clear needs none.
 
 ## Output
 

package/skills/sketch/references/abstraction-barriers-and-closure.md

@@ -0,0 +1,160 @@
+# Abstraction Barriers And Closure
+
+Use this reference to design a truthful level of language. A barrier separates
+programs that *use* a concept from code that *represents* it. Closure determines
+whether the concept's combination mechanism can build values at every useful
+scale.
+
+## Wishful Decomposition
+
+Start with the result in domain vocabulary:
+
+```text
+checkout(cart, customer):
+  priced = priceCart(cart, customer.pricingContext)
+  payable = applyCredits(priced, customer.credits)
+  return authorizePayment(payable.total, customer.paymentMethod)
+```
+
+For each wished operation state:
+
+```text
+caller-visible result
+normal and failure examples
+details the caller should stop knowing
+owner of validation/invariant
+smallest replacement or behavior check
+```
+
+Wishful code exposes possible units; it does not prove they deserve public
+interfaces.
+
+## Build A Data Barrier
+
+Use this construction rule:
+
+1. Name the domain value and interpretation.
+2. List only supported constructors, selectors, predicates, and domain
+   operations.
+3. State laws callers may rely on.
+4. Identify the one owner of validation, normalization, and simplification.
+5. Write two materially different representations.
+6. Rewrite one real caller using only the public vocabulary.
+7. Search for remaining representation primitives outside the owner.
+
+Worked rational-like value:
+
+```text
+Rate = conversion relationship between two quantities
+
+makeRate(numerator, denominator)
+numeratorOf(rate)
+denominatorOf(rate)
+multiplyRate(left, right)
+
+law: denominatorOf(makeRate(n, d)) > 0
+law: Rate(1, 2) and Rate(2, 4) have equal domain meaning
+```
+
+Representation A reduces at construction. Representation B stores raw terms and
+reduces at selection. `multiplyRate` must not change between them. The barrier
+preserves freedom to decide *when* normalization happens.
+
+Reject the barrier when no choice is hidden, callers still require raw layout,
+or the public operations are just field aliases with no stable laws.
+
+## Procedures As Values
+
+A higher-order boundary is justified when the varying role has a stable
+contract.
+
+```text
+aggregate(items, base, project, combine)
+```
+
+Here `project` and `combine` are values the algorithm can receive without
+knowing their bodies. Record their preconditions, effects, error behavior, and
+cost assumptions. Passing a callback does not make hidden mutation or retries
+irrelevant.
+
+## Closure
+
+Suppose a UI layout language has:
+
+```text
+Panel = Text(content) | Image(src) | Row(List<Panel>) | Column(List<Panel>)
+```
+
+`Row` and `Column` accept `Panel` values and produce `Panel`, so primitive and
+compound panels combine uniformly:
+
+```text
+Column([
+  Text("Order"),
+  Row([Image("item.png"), Text("2 × mug")])
+])
+```
+
+Closure check:
+
+```text
+unit predicate: what counts as Panel
+closed constructors/combinators: Panel... -> Panel
+observers/finalizers: Panel -> outside world
+invalid nesting: combinations forbidden by product meaning or cost
+```
+
+Rendering is a finalizer `Panel -> Pixels`; pretending it is another `Panel`
+would blur the boundary. Do not make every method chainable. Preserve closure
+only for the central composition unit.
+
+## Conventional Interfaces
+
+A conventional interface lets independently designed stages exchange a shared
+shape:
+
+```text
+enumerateOrders : Query -> Sequence<Order>
+eligible        : Sequence<Order> -> Sequence<Order>
+invoice         : Sequence<Order> -> Sequence<Invoice>
+sum             : Sequence<Invoice> -> Money
+```
+
+The shared sequence contract enables composition, but record whether stages are
+eager or lazy, ordered or unordered, finite or unbounded, single-use or
+replayable. “Iterable” alone may hide operationally incompatible processes.
+
+## Barrier Review Artifact
+
+```text
+Domain meaning:
+Use-level operations:
+Representation-level operations:
+Concrete representations A and B:
+Laws and invariant owner:
+Real caller rewritten:
+Leak search:
+Closure unit and closed operations:
+Observers/finalizers:
+Operational assumptions:
+Decision or unresolved evidence:
+```
+
+## Failure Diagnosis
+
+- A new representation changes every caller: the barrier is too low or leaked.
+- Public operations mention JSON keys, indexes, providers, or library types: the
+  use level is contaminated by representation.
+- A combinator result needs a second assembly API: closure is missing or the
+  units are not genuinely uniform.
+- A closed API includes I/O as if it returned the same value world: split the
+  finalizer.
+- A conventional interface hides eager materialization or ordering: add the
+  operational contract or choose a different interface.
+
+## Source Trace
+
+- *Structure and Interpretation of Computer Programs*, Second Edition,
+  sections 1.1-1.3 and 2.1-2.2: black-box procedures, wishful thinking,
+  higher-order procedures, data abstraction, abstraction barriers, closure, and
+  conventional interfaces.

package/skills/sketch/references/abstraction-composition-and-state.md

@@ -0,0 +1,184 @@
+# Abstraction, Composition, And State
+
+Use this reference when a sketch must choose a level of language, hide a
+representation, compose reusable units, expose the process a procedure creates,
+or place history. The core insight is not “add an abstraction.” It is:
+
+> Let each level speak only through the vocabulary immediately below it, so a
+> representation, process, or state choice can change without forcing every
+> caller to change.
+
+An abstraction is real only when it hides a consequential choice and leaves a
+smaller, truthful contract.
+
+## Complete Example: A Representation Barrier
+
+Requirement: calculate and display the duration of a schedule while accepting
+several storage formats.
+
+### Wishful use
+
+```text
+label(schedule) = formatDuration(duration(schedule))
+```
+
+The top level speaks about schedules and durations, not tuples, JSON keys, or
+date-library objects.
+
+### Public vocabulary and law
+
+```text
+makeSchedule(start, end, timezone) -> Schedule
+startOf(schedule)                  -> Instant
+endOf(schedule)                    -> Instant
+timezoneOf(schedule)               -> Timezone
+
+law: endOf(makeSchedule(s, e, z)) == e
+law: startOf(makeSchedule(s, e, z)) == s
+invariant: e is not earlier than s
+```
+
+### Two representations
+
+```text
+Representation A: { start, end, timezone }
+Representation B: [timezone, epochStart, epochEnd]
+```
+
+`duration` is written only with `startOf` and `endOf`. Switching A to B should
+change constructors/selectors and boundary adapters, not `duration` or `label`.
+That replacement test is what makes the barrier concrete. A `Schedule` type
+whose callers still read `.epochEnd` is only a new name for a leaked
+representation.
+
+### Where policy lives
+
+Validation and normalization belong to the constructor or an explicit external
+adapter. The selectors do not invent fallback timezones. If callers need raw
+source distinctions, the barrier must preserve them or expose a separate source
+view; normalization is a loss of ability as well as a gain in guarantees.
+
+## Three-Level Sketch
+
+For consequential designs, write the levels explicitly:
+
+```text
+product level:
+  label, reschedule, overlaps
+
+domain representation level:
+  makeSchedule, startOf, endOf, timezoneOf
+
+mechanism level:
+  JSON fields, database columns, date-library values
+```
+
+Check every dependency arrow. Product operations may use the domain vocabulary;
+only the representation owner may use mechanism details. Add another level only
+when it introduces meaningful primitives, combinations, or reusable names.
+
+## Select The Specific Reference
+
+| Unresolved question | Read | Required output |
+| --- | --- | --- |
+| wished top level, representation barrier, higher-order unit, closure, or conventional interface | [Abstraction Barriers And Closure](abstraction-barriers-and-closure.md) | level map, public operations/laws, hidden representation, replacement and closure checks |
+| process shape, cost, state/history, identity, concurrency, streams, or event order | [Processes, State, And Time](processes-state-and-time.md) | process trace/cost or explicit history owner and ordering law |
+| multiple representations, generic operations, registration, symbolic data, DSL, evaluator, or runtime boundary | [Generic Operations And Languages](generic-operations-and-languages.md) | variant-operation matrix or language vocabulary plus evaluator contract |
+
+Read [Responsibility And Variation](responsibility-and-variation.md) instead when
+the main question is who should own knowledge, collaboration, creation, or a
+changing role.
+
+## Modules As Models
+
+A module is a useful model of an environment, not merely a folder. Fill:
+
+```text
+environment: real context and change pressure
+model: represented facets and deliberately ignored facts
+interface: sense exposed to users
+assumptions: environmental facts required for the model to remain useful
+```
+
+Example:
+
+```text
+module: ExchangeRateQuote
+environment: provider responses, currencies, timestamps, outages
+model: base, quote, rate, observedAt
+ignored: provider request IDs and transport headers
+interface: convert(amount), age(now)
+assumptions: rate is positive; observedAt uses a comparable clock
+```
+
+If a caller needs provider headers to decide freshness, either freshness is
+owned by the wrong layer or the model omitted a required fact.
+
+A coherent **principled component** may share assumptions internally and use
+weak indirection. An **adaptable system** needs stronger interfaces between
+components with different assumptions or replacement pressure. Do not impose
+plugin-style indirection inside every cohesive unit, and do not expose internals
+between independently evolving units.
+
+## Pull, Transform, Push
+
+Many processes can be sketched as:
+
+```text
+pull: acquire and validate external information
+transform: compute a context-light domain result
+push: interpret effects or update the environment
+```
+
+Example:
+
+```text
+pullOrders() -> Orders
+planNotifications(Orders) -> List<Notification>
+sendNotifications(List<Notification>) -> DeliveryReport
+```
+
+This split is useful when failures, retries, and tests differ by phase. Reject it
+when one atomic transaction or shared-state invariant is the actual product
+boundary.
+
+## Sketch Output
+
+```text
+Top level: product operations written wishfully
+Levels: vocabulary and allowed dependency direction
+Barrier: public operations/laws, hidden choice, invariant owner
+Replacement: alternative implementation that should leave callers unchanged
+Composition: primitives, combinators, closure boundary, finalizers
+Process: generated work, cost, time, failure, and ordering
+Module: environment, model, interface, assumptions
+State: history owner or explicit stream/log
+Checks: leak, replacement, closure, trace, and order evidence
+```
+
+## Failure Diagnosis
+
+| Symptom | Return to |
+| --- | --- |
+| wished function merely renames a mechanism | product vocabulary and hidden choice |
+| callers assemble or inspect raw representation | barrier operations and leak check |
+| composed result cannot be combined again | closure boundary and finalizer split |
+| short code creates unexplained stack/buffer/order cost | process trace |
+| module boundary follows directories only | environment/model/interface/assumptions |
+| same call changes after prior interactions | history placement |
+| new variant edits every old package | generic operation axes |
+| configuration syntax has no evaluator/error semantics | ordinary data/functions or language contract |
+
+## Source Trace
+
+- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
+  Interpretation of Computer Programs*, Second Edition, MIT Press, 1996:
+  black-box abstraction, data-abstraction barriers, closure, conventional
+  interfaces, procedure/process distinction, generic operations, state,
+  streams, and metalinguistic abstraction.
+- Zachary Tellman, *Elements of Clojure*, 2019: modules as models,
+  environment/model/interface/assumptions, principled versus adaptable systems,
+  units of computation, and process construction.
+- Hillel Wayne, *Logic for Programmers*, version 0.14.0, May 4, 2026:
+  ability-guarantee tradeoffs and the separation of mathematical models from
+  runtime semantics.