@hobin/developer 0.1.8 → 0.1.9

package/skills/abstraction-review/references/recipe-cards.md

@@ -1,322 +0,0 @@
-# Abstraction Review Recipe Cards
-
-Use this deck when the review needs a construction rule, not only a layer name.
-Each card must produce an artifact and a stop check.
-
-Read [the worked examples](worked-examples.md) when a card's compact rule is not
-enough to calibrate a real candidate. When a stop check fails, use
-[the repair table](repair-table.md) instead of polishing the same surface.
-
-## Contents
-
-- Pocket Deck
-- Procedure -> Process Reality Check
-- Movement Pattern Extraction
-- Responsibility Boundary
-- Invariant Iteration
-- Data Abstraction Boundary
-- Closure Composition Unit
-- Dispatch Registration
-- Meaning-Preserving Path
-- Notation As Data
-- History Placement
-- Event Order Protection
-
-## Pocket Deck
-
-| Card | Trigger | Fill first | Derive | Stop | Repair if fails |
-| --- | --- | --- | --- | --- | --- |
-| Procedure -> Process Reality Check | Result is plausible but process shape is unclear | procedure text, sample input, expected result | trace deferred work, state updates, duplicated work, cost | result, shape, and cost are all explainable | move to Law or Time |
-| Movement Pattern Extraction | Similar cases move together but differ in stable roles | concrete cases side by side, common movement, varying roles | keep common movement as body; lift stable variation roles to parameters, callbacks, or strategies | old cases become simple calls and new case is expressible | split, inline, or return to Language |
-| Responsibility Boundary | Knowledge and behavior appear owned by the wrong unit | current owners, messages, data, callers, change reasons | group knowledge with behavior and state the smallest role contract | representative change becomes local without context leaks | split, inline, or return to Model |
-| Invariant Iteration | Recursion or state should become a stable transition | original meaning, state variables, transition candidate | write `processed meaning + remaining meaning = original meaning` using the domain operation | initial, step, and final checks pass | return to Run trace or reduce state variables |
-| Data Abstraction Boundary | Caller knows raw representation | domain value, operations, representation candidates | create constructor, selector, predicate, and operation vocabulary | caller code stops touching raw representation | move to Unit or Engine |
-| Closure Composition Unit | Operation results cannot feed later operations | candidate unit, operation list, preserved meaning | mark closed operations vs observers/finalizers | closed operations build larger values of the same unit | move final effect outside the unit |
-| Dispatch Registration | New type/provider/case changes old branches | variant axis, operation axis, current branches | turn each branch into `(variant, operation) -> method` | fake variant is added by registration only | choose axes again or use Meaning-Preserving Path |
-| Meaning-Preserving Path | Mixed worlds need operation without hidden loss | source worlds, operation, candidate paths | draw direct/coerce/canonicalize/reject graph | legal path, loss, and unsupported cases are explicit | narrow preserved meaning or reject |
-| Notation As Data | String/index manipulation stands in for semantic rules | expression cases, parts, transformations | make predicate/selector/constructor vocabulary | rewrite rule ignores raw layout | move to Boundary or Engine |
-| History Placement | Same call depends on history | behavior, required history, interaction model | choose pure, local state, or stream/log placement | hidden summary or explicit history matches contract | move to Event Order or Boundary |
-| Event Order Protection | Interleaving changes correctness | events, shared meaning, possible interleavings | state order law and protected region or merge policy | forbidden interleaving is blocked for a stated reason | narrow order law or return to History |
-
-## Card Details
-
-### Procedure -> Process Reality Check
-
-Use when code is textually simple but execution may grow the wrong process.
-
-Output artifact:
-
-```text
-process trace:
-  input -> stage -> stage -> result
-shape:
-  recursive / iterative / tree / delayed / stateful
-cost note:
-  time, space, duplicated work, hidden order
-```
-
-Promote only if the abstraction promise includes the real process shape, not
-just the returned value.
-
-### Movement Pattern Extraction
-
-Use when abstraction pressure comes from repeated movement, not from a single
-interface wish.
-
-Input artifact:
-
-```text
-cases:
-  two or more concrete functions, workflows, tests, or traces
-common movement:
-  steps that move together across cases
-variation roles:
-  stable differences such as predicate, term, next, combine, strategy, policy
-```
-
-Derivation:
-
-```text
-body:
-  keep the common movement
-parameters:
-  lift stable variation roles
-name:
-  describe the concept, not the implementation trick
-```
-
-Output artifact:
-
-```text
-abstraction candidate:
-  name, signature, body skeleton
-role table:
-  case -> variation role values
-process note:
-  whether the generated process/cost changes
-```
-
-Stop check: each old case is a simple call, and at least one realistic new case
-can be expressed without adding a new option that exposes internals.
-
-Reject if the cases only look textually similar but carry different
-responsibilities. Split if variation roles are not stable.
-
-### Responsibility Boundary
-
-Use when repeated arguments, data clumps, feature envy, conditional behavior, or
-several change reasons suggest that knowledge and behavior have the wrong owner.
-
-Input artifact:
-
-```text
-current owners:
-  unit -> knowledge, behavior, coordination, creation
-messages:
-  callers -> requests -> receivers
-pressure:
-  representative accepted change and affected path
-candidate:
-  knowledge and behavior proposed to move together
-```
-
-Derivation:
-
-1. group behavior with the knowledge needed to answer its messages;
-2. separate domain responsibility from coordination and object creation;
-3. state the smallest caller-visible role contract;
-4. identify old context callers should stop knowing;
-5. test a representative change against old and candidate ownership.
-
-Output artifact:
-
-```text
-responsibility: name and reason to change
-knowledge: data or history it owns
-messages: minimal protocol
-hidden context: mechanics removed from callers
-creation boundary: who selects or constructs it
-rejected alternatives: inline, split, or different owner
-```
-
-Stop check: the representative change is local to a coherent owner, callers use
-messages rather than extracting its knowledge, and the candidate does not need
-unrelated context from the old host. Reject or split when the candidate is only
-a bag of moved methods, a generic service, or a pattern-shaped destination.
-
-### Invariant Iteration
-
-Use when state variables or accumulators need meaning.
-
-Output artifact:
-
-```text
-invariant:
-  what state variables preserve
-initial:
-  why the invariant starts true
-transition:
-  why one step keeps it true
-final:
-  why termination exposes the answer
-```
-
-If the invariant is hard to state, decide `revise-model`. If it is true but
-expensive, review representation or operation placement.
-
-### Data Abstraction Boundary
-
-Use when callers know too much.
-
-Output artifact:
-
-```text
-public handles:
-  constructors / selectors / predicates / generic operations
-representation law:
-  what callers may trust
-hidden freedom:
-  internal details that may change
-creation policy:
-  validation / normalization / simplification location
-```
-
-If no detail is hidden, reject or inline. If policy is hidden in consumers,
-decide `revise-surface`.
-
-### Closure Composition Unit
-
-Use when the goal is an algebra of reusable pieces.
-
-Output artifact:
-
-```text
-unit predicate:
-  what belongs to the world
-closed operations:
-  unit -> unit, unit x unit -> unit
-observers/finalizers:
-  unit -> outside
-illegal move:
-  operation that leaks or breaks the unit
-```
-
-Do not make everything chainable. Preserve the central unit and move final
-effects to an explicit boundary.
-
-### Dispatch Registration
-
-Use when variation should be additive.
-
-Output artifact:
-
-```text
-table:
-  variants x operations
-registration:
-  register(variant, operation, method)
-lookup:
-  applyGeneric(operation, value...)
-unsupported:
-  explicit missing capability policy
-```
-
-Stop check: add a fake variant. Existing callers and existing variant packages
-should not know its representation.
-
-### Meaning-Preserving Path
-
-Use when values cross worlds.
-
-Output artifact:
-
-```text
-conversion graph:
-  source -> target paths
-preserved meaning:
-  what must survive conversion
-policy:
-  direct / raise / canonicalize / reject
-loss note:
-  precision, identity, ordering, capability
-```
-
-Unsupported is a legitimate boundary, not a failure, when meaning cannot be
-preserved.
-
-### Notation As Data
-
-Use when a language, expression, query, or formula must be inspected or
-rewritten.
-
-Output artifact:
-
-```text
-expression boundary:
-  predicates / selectors / constructors
-transform rules:
-  algorithms written against the boundary
-render/evaluate boundary:
-  where data becomes displayed or executable again
-```
-
-If transformation rules depend on indexes or string layout, the boundary is not
-real yet.
-
-### History Placement
-
-Use when current behavior cannot be understood from current input alone.
-
-Output artifact:
-
-```text
-placement:
-  pure / local state / stream-log
-state contract:
-  what hidden state summarizes
-stream contract:
-  what each time-indexed value means
-order risk:
-  where histories merge or conflict
-```
-
-Local state hides history for API simplicity. Stream/log exposes history for
-composition, replay, audit, and merge reasoning.
-
-### Event Order Protection
-
-Use when order is part of meaning.
-
-Output artifact:
-
-```text
-order law:
-  required happens-before relation
-protected region:
-  steps that must appear atomic
-mechanism:
-  lock / transaction / queue / serializer / merge policy
-cost:
-  waiting, reduced parallelism, fairness tradeoff
-```
-
-If everything must be serialized, the order law is probably too broad.
-
-## Source Trace
-
-- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
-  Interpretation of Computer Programs*, Second Edition, MIT Press, 1996:
-  procedure/process distinction, data abstraction, closure, generic dispatch,
-  state/history, and metalinguistic boundaries.
-- Matthias Felleisen, Robert Bruce Findler, Matthew Flatt, and Shriram
-  Krishnamurthi, *How to Design Programs, Second Edition*, MIT Press, 2018:
-  templates, abstraction from concrete examples, generative recursion, and
-  accumulator invariants.
-- Sandi Metz, Katrina Owen, and TJ Stankus, *99 Bottles of OOP*, Second
-  Edition, version 2.2.2, 2024: movement patterns, responsibility extraction,
-  messages, substitution, polymorphic roles, type transitions, and factory
-  tradeoffs.
-- Hillel Wayne, *Logic for Programmers*, version 0.14.0, May 4, 2026:
-  contracts, safe replacement, invariants, and meaning-preserving model changes.
-- Zachary Tellman, *Elements of Clojure*, 2019: indirection cost, module
-  assumptions, principled components, adaptable interfaces, and composition.

package/skills/model/references/worked-models-and-specialized-techniques.md

@@ -1,218 +0,0 @@
-# Worked Models And Specialized Techniques
-
-Use this reference to calibrate the artifacts in
-[Problem Modeling](problem-modeling.md). Each technique starts from a different
-uncertainty. Select the smallest model that can expose the consequential mistake.
-
-## Boolean Policy: Access Rule
-
-Prose: “Editors can publish their own drafts, and admins can publish anything,
-unless the document is archived.”
-
-```text
-domain: user in Users, document in Documents
-facts:
-  role(user) in {viewer, editor, admin}
-  owner(document) in Users
-  status(document) in {draft, published, archived}
-
-canPublish(user, document) =
-  status(document) != archived
-  && (role(user) == admin
-      || (role(user) == editor && owner(document) == user))
-
-forbidden counterexample:
-  canPublish(user, document) && status(document) == archived
-```
-
-| archived | admin | editor owns | result |
-| --- | --- | --- | --- |
-| yes | any | any | false |
-| no | yes | any | true |
-| no | no | yes | true |
-| no | no | no | false |
-
-Unknown: whether an editor may republish a published document. Keep it human-
-owned because the prose names drafts only. Verify the four partitions and one
-real authorization integration; do not leave the guarantee in a UI guard alone.
-
-## Relational Data And Constraints
-
-Requirement: each department has at most one active manager at a time, and every
-manager row refers to existing entities.
-
-```text
-Employee(id)
-Department(id)
-Management(employeeId, departmentId, start, end?)
-
-all m in Management:
-  some e in Employee: e.id == m.employeeId
-  some d in Department: d.id == m.departmentId
-  m.end is absent || m.start < m.end
-
-all a, b in Management where a != b
-  && a.departmentId == b.departmentId:
-    intervalsDoNotOverlap(a, b)
-```
-
-The last property may require an exclusion constraint, serialized transaction,
-or application check plus locking depending on the database. A nullable `end`
-needs an explicit open-interval meaning. Exercise historical, current, future,
-overlapping-boundary, and missing-foreign-key instances.
-
-## Replacement Contract
-
-Old API accepts any non-empty timezone string and returns a schedule or a domain
-error. New API accepts only a timezone enum and throws on failure.
-
-```text
-old.Pre: nonEmpty(timezone)
-new.Pre: timezone in KnownTimezone
-
-old.Pre => new.Pre       // false for a legacy but non-empty timezone
-new.Post => old.Post     // false if exceptions are not old domain errors
-```
-
-The replacement is unsafe for old callers even if current tests use only known
-zones. Repair by adapting legacy strings, broadening the new precondition, or
-making the break explicit.
-
-## Temporal Model: Retried Payment
-
-Snapshots do not distinguish a fresh approval from a duplicated response.
-
-```text
-states: Created | Authorizing(attempt, requestId) | Authorized(paymentId)
-        | Failed(reason)
-initial: Created
-
-Authorize(id): Created -> Authorizing(1, id)
-Retry(id2): Authorizing(n, _) -> Authorizing(n + 1, id2)
-Approved(id, payment):
-  Authorizing(_, id) -> Authorized(payment)
-Approved(staleId, _):
-  Authorizing(_, currentId) -> unchanged when staleId != currentId
-
-safety: authorization is recorded at most once
-progress assumption: a live provider eventually responds and retries are finite
-```
-
-Verification needs stale, duplicated, reordered, and retry traces, not one test
-per enum value.
-
-## Proof Boundary: Quotient And Remainder
-
-```text
-qr(x, y) -> (q, r)
-requires: x >= 0 && y > 0
-ensures: q * y + r == x; 0 <= r < y; q >= 0
-
-q = 0
-r = x
-while r >= y:
-  r = r - y
-  q = q + 1
-```
-
-Invariant: `q * y + r == x`.
-
-- initialization: `0 * y + x == x`;
-- preservation: `(q + 1) * y + (r - y) == q * y + r`;
-- exit: the guard and invariant imply the required remainder relation;
-- termination: non-negative integer `r` decreases by positive `y`.
-
-The proof still assumes mathematical integer semantics and complete
-postconditions. Overflow or a missing performance requirement can invalidate the
-product claim without invalidating this proof.
-
-## Constraint Propagation
-
-Before a solver, a relation may itself be the design. Temperature conversion is
-not inherently one-way:
-
-```text
-9 * celsius == 5 * (fahrenheit - 32)
-```
-
-A propagation network can accept either value, derive the other, forget a
-retracted value, and reject inconsistent facts. Its model must identify
-connectors, relations, who asserted each value, and conflict behavior. This is
-useful when information may arrive from several directions; an ordinary
-`toFahrenheit(celsius)` function is clearer when direction is fixed.
-
-The core insight is that a relation states what values must agree, while a
-procedure also chooses direction and evaluation. Do not import propagation
-machinery merely to make a one-way calculation appear declarative.
-
-## Constraint Solver: Shift Assignment
-
-```text
-variables: assigned(task) in Workers
-hard constraints:
-  every task has exactly one worker
-  worker skill covers task requirement
-  overlapping tasks use different workers
-objective: minimize total preference penalty
-equivalence: assignments with equal penalty are acceptable
-```
-
-Test a known satisfiable fixture, a known impossible fixture, and two equal
-optima. `unknown` or timeout is neither a solution nor proof of impossibility. A
-bad weight can yield a mathematically optimal but operationally absurd plan.
-
-## Logic Programming: Dependency Query
-
-```text
-depends(api, domain)
-depends(ui, api)
-
-reachable(a, b) if depends(a, b)
-reachable(a, c) if depends(a, b) and reachable(b, c)
-```
-
-Query `reachable(ui, X)` should yield `api` and `domain`. State whether different
-paths yield duplicate answers and how cycles terminate. If every product query
-must terminate, a restricted deductive language may be better than a general
-backtracking language.
-
-## Planning: Rolling Server Upgrade
-
-```text
-state: set of Server(name, online, version)
-initial: all online at version 1
-goal: all online at version 3
-invariant: at least one server is online
-actions:
-  takeOffline(server) when another server remains online
-  upgrade(server) when server is offline
-  bringOnline(server)
-cost: one per action, plus optional online-version-skew penalty
-```
-
-Show every intermediate state so the invariant can be checked. A shortest plan
-under action count may not minimize risk; changing the cost model can legitimately
-change the preferred plan. Valid and preferred plans are different claims.
-
-## Selection And Stop
-
-| Uncertainty | Artifact | Stop |
-| --- | --- | --- |
-| ambiguous rule | predicate + counterexample + cases | every partition has one result or visible policy gap |
-| data integrity | relations + quantified constraints | known valid and invalid instances differ |
-| compatibility | old/new pre/post implications | callers are covered or breaking scope is explicit |
-| history/order | transition model + safety/progress | stale, retry, duplicate, reorder are defined |
-| exhaustive implementation claim | contract + invariant/proof obligations | assumptions and remaining obligations are explicit |
-| allocation/search | variables, constraints, objective | satisfiable, impossible, alternate-optimum fixtures behave as modeled |
-| inference | facts, rules, query semantics | expected and cyclic cases are explained |
-| action sequence | state, action, invariant, goal, cost | each intermediate state is valid |
-
-## Source Trace
-
-- Hillel Wayne, *Logic for Programmers*, version 0.14.0, May 4, 2026:
-  predicates, contracts and replacement, formal proof boundaries, relational
-  data and constraints, temporal models, solvers, logic programming, planning,
-  and answer-set reasoning. Examples are adapted for product modeling.
-- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
-  Interpretation of Computer Programs*, Second Edition, MIT Press, 1996:
-  state, constraints, and explicit evaluation models.

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

@@ -1,160 +0,0 @@
-# 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.