@hobin/developer 0.1.8 → 0.1.9

package/skills/sketch/references/generative-recursion.md

@@ -0,0 +1,122 @@
+# Generative Recursion
+
+Use this reference when the algorithm creates a new instance of the problem
+rather than following an immediate self-reference in the data definition.
+
+## Structural Or Generated
+
+```text
+structural call:
+  consumes a field selected directly from one data clause
+
+generative call:
+  computes a new problem instance from domain or algorithm knowledge
+```
+
+A generated problem may happen to be a suffix or subinterval. What matters is
+why it exists. Misclassifying it as structural hides both the algorithm idea and
+its progress obligation.
+
+## Generative Design Spine
+
+```text
+trivial: which instances have direct answers?
+solve: what are those answers?
+generate: how are next subproblems produced?
+preserve: why do their solutions contribute to this problem?
+combine: how are recursive answers and current facts assembled?
+progress: what well-founded measure decreases on every branch?
+failure: how are no-solution, exhausted search, error, and divergence distinct?
+```
+
+A preserving relation supports result correctness. A decreasing measure supports
+termination. Neither implies the other.
+
+## Process Trace
+
+For binary search, record generated intervals rather than only input/output:
+
+```text
+[0, 6] -> [4, 6] -> [4, 4] -> Found(4)
+[0, 0] -> [1, 0] -> NotFound
+```
+
+The measure `high - low + 1` decreases for every non-trivial call. The accepted
+domain must also establish finite ordered bounds, valid indexing, and discrete
+midpoint progress.
+
+For every generated branch include:
+
+```text
+original problem
+generation result
+preserved relation
+next measure
+branch result and combination
+```
+
+## Machine, Numeric, Random, And Search Progress
+
+Mathematical decrease can fail on a machine. State:
+
+- exact versus inexact representation;
+- rounding, overflow, underflow, and non-finite values;
+- midpoint or update stagnation;
+- tolerance meaning and iteration bounds;
+- universal versus almost-sure termination for randomized progress;
+- branch order, backtracking point, and visited-set scope for search.
+
+Backtracking needs explicit failure and choice policy. Divergence in one branch is
+not failure that permits the next candidate. Path-local, frontier, and global
+visited sets preserve different meanings.
+
+## Composition Boundary
+
+A generative driver may use structurally recursive helpers. Do not label the
+whole program generative or structural when collaborators have different process
+obligations. Keep each helper's data recipe and the driver's generation recipe
+separate.
+
+## Artifact
+
+```text
+Problem domain and trivial instances:
+Generation rule:
+Preservation relation:
+Combination rule:
+Well-founded measure by branch:
+Representative generated traces:
+Machine/numeric/random progress limits:
+Failure, exhaustion, error, and divergence:
+Search order and visited scope, if relevant:
+```
+
+## Stop And Separation
+
+Stop when every recursive branch has a generated-instance explanation, a
+preservation argument, and a progress or explicit divergence boundary.
+
+Use `accumulator-invariant` when the main issue is remembered traversal knowledge,
+the `model` logic-query route when answer/search policy is unresolved, and
+`process-shape-and-resources` when the algorithm is accepted but stack, work, or
+storage behavior needs a design surface.
+
+## Source Trace
+
+- Matthias Felleisen, Robert Bruce Findler, Matthew Flatt, and Shriram
+  Krishnamurthi, *How to Design Programs*, living build 9.2.0.3:
+  Chapter 25,
+  Chapter 26,
+  Chapter 27,
+  Chapter 28,
+  Chapter 29,
+  and Chapter 30
+  for generated problems, preservation, termination, numerics, and backtracking;
+  and Intermezzo 4
+  for exact/inexact arithmetic and machine limits.
+- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
+  Interpretation of Computer Programs*, Second Edition:
+  Section 1.2
+  for generated process shape and resource growth; and
+  Section 4.3
+  for explicit choice, failure, rollback, and search-order pressure.

package/skills/sketch/references/generic-dispatch-systems.md

@@ -0,0 +1,75 @@
+# Generic Dispatch Systems
+
+Use this reference when accepted representations must coexist additively through
+operations whose selection should not expose representation fields to callers.
+
+## Two Axes Before Mechanism
+
+| Representation | `charge` | `refund` | `describe` |
+| --- | --- | --- | --- |
+| Card | supported | supported | supported |
+| Bank transfer | supported | unsupported | supported |
+| Store credit | supported | supported | supported |
+
+Distinguish representation growth (row) from operation growth (column). Classes,
+visitors, multimethods, tables, and registries distribute those costs differently.
+Select from observed growth pressure.
+
+## Dispatch Ownership
+
+State:
+
+```text
+dispatch key and operation key
+who registers or enumerates variants
+duplicate and overlap policy
+precedence and load order
+unsupported capability result
+visibility and failure timing
+```
+
+Moving branches into registration data relocates precedence ownership; it does
+not remove it. A local exhaustive conditional is often the smaller owner for a
+few closed variants.
+
+## Extension Check
+
+Add a fake row and one new column. Existing callers and old variant modules should
+remain unchanged only along the axis the design claims to support. A registry adds
+startup, naming, reflection, deployment, duplicate, and failure obligations.
+
+## Artifact
+
+```text
+Variant-operation matrix:
+Observed growth axis:
+Representation barrier:
+Dispatch and registration owner:
+Duplicate, overlap, precedence, load-order, and unsupported policy:
+Fake-row and new-column checks:
+Simpler conditional alternative:
+```
+
+## Stop And Separation
+
+Stop when both axes and all dispatch policies are visible and the chosen mechanism
+is no more powerful than current extension pressure requires.
+
+Use `meaning-preserving-conversions` only when operations cross representation
+worlds, the variation-role or selection-creation route when domain role/creation
+ownership is primary, and `language-semantics` when registered data becomes
+executable notation.
+
+## Source Trace
+
+- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
+  Interpretation of Computer Programs*, Second Edition,
+  Section 2.4
+  and Section 2.5
+  for generic operations, data-directed dispatch, and extension axes.
+- Zachary Tellman, *Elements of Clojure*, Leanpub 2019-02-11, Indirection,
+  public-manuscript pp. 64-69, for ordered conditionals, table conflicts, and
+  qualified openness cost.
+- Sandi Metz et al., *99 Bottles of OOP*, Second Edition, v2.2.2, Chapters 6-7,
+  pp. 155-187, calibrates role and factory pressure without making registration a
+  universal destination.

package/skills/sketch/references/language-semantics.md

@@ -0,0 +1,82 @@
+# Language Semantics
+
+Use this reference when ordinary data and functions have become notation that
+needs its own grammar, validation, evaluation, result, and error semantics.
+
+## Language Gate
+
+A configuration, rule table, query, expression, or workflow is a language only
+when it needs an owned account of:
+
+```text
+primitives
+combination
+abstraction or reusable names
+accepted grammar and validation
+evaluation in an environment
+errors and unsupported programs
+evolution and compatibility
+```
+
+Prefer typed data plus ordinary functions when they keep policy more visible.
+
+## Representation, Parsing, And Meaning
+
+```text
+transport input
+-> accepted grammar or sublanguage
+-> constructed semantic representation
+-> evaluator meaning
+-> rendered or effectful result
+```
+
+Represent inspectable notation as semantic data rather than string positions.
+Constructors may simplify only under explicit semantic laws. Parse success does
+not establish evaluator meaning.
+
+## Evaluator Contract
+
+```text
+evaluate : Program x Environment x ExecutionPolicy -> Evaluation
+Evaluation = One(Result) | Search(Stream<Result>) | LanguageError
+```
+
+State scope, binding, order, demand, zero/one/many results, answer/proof identity,
+duplicates, choice/fairness, branch failure, error, divergence, rollback, effects,
+negation, cancellation, termination, and resource limits as applicable. A
+mathematically equivalent rewrite may change any of these observers.
+
+## Artifact
+
+```text
+Language gate and ordinary-data alternative:
+Primitives, combinations, and abstractions:
+Grammar and semantic representation:
+Validation and invalid programs:
+Evaluator/result/search contract:
+Scope, order, demand, multiplicity, effects, failure, and termination:
+Example program and unsupported case:
+```
+
+## Stop And Separation
+
+Stop when a representative and invalid program have explainable syntax, meaning,
+result shape, effects, and failure, and the ordinary-data alternative was
+considered.
+
+Use `runtime-and-compilation` only when lowering, calling convention, generated
+code, roots, or optimization guards are independently consequential. Return to
+`model/logic-query-semantics` when search meaning is not yet accepted.
+
+## Source Trace
+
+- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
+  Interpretation of Computer Programs*, Second Edition:
+  Section 4.1,
+  Section 4.2,
+  Section 4.3,
+  and Section 4.4
+  for evaluator models, laziness, nondeterminism, and relational semantics.
+- Hillel Wayne, *Logic for Programmers*, v0.14.0, Chapters 11-12, pp. 139-168,
+  calibrates solver/query language result multiplicity and search boundaries;
+  recorded beta defects are excluded.

package/skills/sketch/references/meaning-preserving-conversions.md

@@ -0,0 +1,69 @@
+# Meaning-Preserving Conversions
+
+Use this reference when values from different representation worlds must
+participate in one operation without silently losing domain meaning.
+
+## Draw Paths
+
+```text
+Integer -> Rational -> Decimal
+Money(USD) -X-> Money(EUR) without exchange context
+```
+
+For each edge state:
+
+```text
+source and target meaning
+operation that requires the path
+precision, identity, order, metadata, or capability preserved
+ability lost
+ambiguous alternate paths
+cycle and termination policy
+unsupported result
+```
+
+A path through representations is not evidence that the conversion is meaningful.
+Choose direct operation, coercion, canonical form, explicit context, or rejection.
+
+## Path Selection
+
+Prefer a path only when:
+
+- every edge preserves the observer required by the operation;
+- alternate paths do not produce ambiguous meaning;
+- repeated conversion terminates and does not accumulate hidden loss beyond the
+  contract;
+- unsupported combinations fail visibly;
+- the canonical form, if any, does not erase a needed source distinction.
+
+## Artifact
+
+```text
+Source worlds and target operation:
+Conversion graph:
+Preserved observer by edge:
+Lost ability by edge:
+Ambiguous paths and precedence:
+Cycle/termination policy:
+Direct/canonical/context/reject decision:
+Unsupported and round-trip checks:
+```
+
+## Stop And Separation
+
+Stop when every legal path has an explicit preserved observer and loss note, and
+unsupported or ambiguous paths are rejected or owned by policy.
+
+Return to `model/contract-replacement` when preserved meaning itself is disputed.
+Use `generic-dispatch-systems` when additive operation selection is independently
+required.
+
+## Source Trace
+
+- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
+  Interpretation of Computer Programs*, Second Edition,
+  Section 2.5
+  for coercion, type towers, ambiguity, and representation interactions.
+- Hillel Wayne, *Logic for Programmers*, v0.14.0, Chapter 5, pp. 47-60,
+  calibrates observer-relative replacement; conversion-graph and production
+  compatibility artifacts are Developer synthesis.

package/skills/sketch/references/process-shape-and-resources.md

@@ -0,0 +1,157 @@
+# Process Shape And Resources
+
+Use this reference when returned values do not describe the generated work,
+control, waits, capacity, lifetime, or effect boundary of a design.
+
+## Procedure Is Not Process
+
+Trace 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
+work generated at each step
+control owner and continuation
+deferred work or stack growth
+shared and retained data
+active and paused execution
+input shortage/overload behavior
+time/space bounds
+failure and cancellation surface
+```
+
+Short source text is not evidence of a simple process. A fluent pipeline may
+materialize several collections; recursive syntax may generate constant-space or
+growing-stack execution depending on continuation placement.
+
+## Active, Paused, And Capacity Boundaries
+
+```text
+data scope:
+  initial values, shared references, acquired input, new sharing edges
+active execution:
+  locally ordered operations while progress is possible
+paused execution:
+  external signal, resource, or capacity required
+input excess:
+  ignore, reject, bound, queue, shed, or backpressure
+input shortage:
+  wait, timeout, retry/back off, fail, or report
+```
+
+A thread-safe queue coordinates access; it does not prove bounded waiting,
+starvation freedom, capacity, or independent understandability. Name the owner
+and finite bound before claiming isolation.
+
+## Control, Tail Position, And Retention
+
+At every nested step state:
+
+```text
+what must happen after return
+values live across the call
+what may be clobbered
+what is saved and where
+maximum nesting and overflow policy
+error/cancellation transfer
+```
+
+A call is in tail position only when the current computation has no deferred work
+that requires a return frame. Verify stack and control claims with stack depth,
+operation count, allocation, retained graph, or an adversarial bounded trace—not
+with result equality alone.
+
+For memory-sensitive work identify roots, reachable objects, release events,
+external handles, identity rules, capacity, and out-of-memory behavior. Garbage
+collection cannot repair an unintended root, cache, callback, stream prefix, or
+unclosed handle.
+
+## Pull, Transform, Push
+
+Use this phase split only when it matches failure and ownership:
+
+```text
+pull:
+  acquire and bound external information; own invalid/unavailable behavior
+transform:
+  compute a context-light domain result
+push:
+  interpret effect data; own idempotency and partial failure
+apex:
+  coordinate the whole outcome at the last responsible moment
+```
+
+If pull returns a lazy effectful producer, the pull owner must enclose
+consumption, resource closure, retry, truncation, and decoding. Prefer inspectable
+effect data until push. Reject this split when one atomic transaction or shared
+invariant is the real boundary.
+
+## Task Completion And Acknowledgment
+
+For work crossing processes, distinguish message delivery from completed task:
+
+```text
+task identity and entry command
+effect boundary where outcome becomes uncertain
+completion acknowledgment and failure meaning
+outstanding-work owner and durable state
+retry owner, duplicate policy, cancellation, and stop
+intermediate release point
+```
+
+An edge-held outstanding-task record is an ownership candidate, not an
+exactly-once guarantee. Distributed durability and recovery require separate
+protocol evidence.
+
+## Artifact
+
+```text
+Procedure promise and representative process trace:
+Generated work and continuation owner:
+Shared data and new sharing edges:
+Active/paused dependencies:
+Too-much/too-little policy:
+Stack, queue, time, space, and retention bounds:
+Roots, identity, handles, and release:
+Pull/transform/push ownership, if applicable:
+Task acknowledgment and outstanding-work owner:
+Failure, retry, duplicate, cancellation, and residual risk:
+```
+
+## Stop And Separation
+
+Stop when work, control, wait, capacity, lifetime, failure, and completion are
+owned and bounded enough to make the first implementation step honest.
+
+Use `state-history-and-order` when previous interactions or event ordering define
+meaning, and `runtime-and-compilation` when these obligations belong to an
+interpreter/compiler convention rather than an ordinary process.
+
+## Source Trace
+
+- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
+  Interpretation of Computer Programs*, Second Edition:
+  Section 1.2
+  for process shape and resource growth;
+  Section 5.1
+  for control, continuations, registers, and stacks;
+  Section 5.2.4
+  for process instrumentation;
+  Section 5.3
+  for reachability, roots, identity, and storage reclamation; and
+  Section 5.4.2
+  for tail calls and retained frames.
+- Zachary Tellman, *Elements of Clojure*, Leanpub 2019-02-11:
+  Composition, public-manuscript pp. 98-119, for partial data/execution isolation,
+  waiting, overload, pull-transform-push, effectful lazy input, topology, and task
+  acknowledgment.
+- Complete production cancellation, recovery, capacity, and delivery protocols
+  remain Developer adaptations.

package/skills/sketch/references/representation-barriers.md

@@ -0,0 +1,73 @@
+# Representation Barriers
+
+Use this reference after [Design Levels And Boundaries](design-levels-and-boundaries.md)
+when one accepted domain value needs public operations and laws that hide a
+consequential representation choice.
+
+## Build The Barrier
+
+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 public vocabulary.
+7. Search for representation primitives outside the owner.
+
+Do not expose a field alias merely because the representation contains the field.
+Public operations come from caller purposes and stable laws.
+
+## Worked Shape
+
+```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 normalizes at creation. Representation B stores raw terms and
+normalizes at observation. `multiplyRate` and callers must not change. The
+barrier preserves freedom about representation and normalization time.
+
+## Artifact
+
+```text
+Domain meaning and caller purposes:
+Public operations and laws:
+Invariant/normalization owner:
+Representations A and B:
+Real caller rewritten:
+Replacement check:
+Leak search:
+Unsupported raw access:
+```
+
+## Stop And Separation
+
+Stop when a materially different representation changes only the owner and
+adapters, one real caller uses only domain vocabulary, and leak search finds no
+raw primitives.
+
+Reject when no choice is hidden, callers still require layout, or operations are
+only field aliases with no stable law. Use `closure-and-conventional-interfaces`
+when composition of values is the independent question.
+
+## Source Trace
+
+- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
+  Interpretation of Computer Programs*, Second Edition,
+  Section 2.1
+  for data abstraction, selectors/constructors, laws, and representation
+  independence.
+- Matthias Felleisen et al., *How to Design Programs*, living build 9.2.0.3,
+  Chapter 22
+  for accessors over alternate positional encodings.
+- Replacement and repository leak-search artifacts are Developer adaptations of
+  those barriers.

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

@@ -0,0 +1,108 @@
+# Responsibility And Collaboration
+
+Use this reference when a real accepted change exposes misplaced knowledge,
+repeated arguments, data clumps, feature envy, navigation leaks, or uncertainty
+about which participant should own a decision.
+
+## Begin With Change Pressure
+
+State the accepted change and where the current arrangement resists it. A smell
+locates a point of attack; it does not select a class, service, or pattern.
+
+Inventory what each current unit:
+
+- knows;
+- calculates or decides;
+- coordinates;
+- creates;
+- sends to collaborators;
+- changes for independent reasons.
+
+Write wished messages in domain language. Repeatedly pulling data from one unit
+so another can interpret it is evidence of misplaced responsibility.
+
+## Candidate Owner
+
+```text
+responsibility and reason to change
+knowledge or history required
+minimal caller messages
+hidden context callers stop knowing
+creation/selection owner
+representative accepted change
+rejected old placement
+```
+
+A credible unit groups behavior with the knowledge needed to answer its messages.
+Reject moved-method bags, generic services, and pass-through interfaces with no
+independent participant or change pressure.
+
+## Participant And Environment Boundary
+
+```text
+environment and participants
+represented and ignored facts
+interface sense
+assumptions and drift signal
+independent purposes/deployments/replacement cycles
+```
+
+A cohesive component may share assumptions internally. Strong interfaces belong
+between independently evolving participants. Public boundaries calcify, so mature
+them locally when both sides co-evolve.
+
+## Navigation And Dependency
+
+A message chain is problematic when intermediate results cross collaborator API
+boundaries and expose structure. Chain length alone is not the criterion.
+Forwarding can reduce direct coupling as an intermediate move, but a
+structure-shaped forwarding name is not completed responsibility movement.
+
+Depend on the stable role a caller actually uses. Do not inject unrelated objects
+merely to make every unit configurable.
+
+## Tests As Responsibility Evidence
+
+Prefer focused evidence for stable public responsibility and integration evidence
+for collaboration/creation. A tiny collaborator may be covered through its
+owner only when it is simple, invisible elsewhere, and has no independent
+context. Fakes preserve the role while removing irrelevant context; tests that
+echo private calls inhibit redesign.
+
+## Artifact
+
+```text
+Accepted change pressure:
+Current responsibility inventory:
+Point of attack:
+Wished messages:
+Candidate owner, knowledge, contract, and hidden context:
+Participant environment, assumptions, and replacement cycles:
+Navigation/dependency boundary:
+Representative change and rejected placement:
+Responsibility and collaboration checks:
+```
+
+## Stop And Separation
+
+Stop when the representative change becomes local to one coherent owner and
+callers use meaningful messages without unrelated context or participant leaks.
+
+Use `variation-roles-and-transitions` when several implementations must share a
+caller contract, and `selection-and-creation` when choosing or constructing a
+variant is independently unresolved. Route a concrete candidate to
+`abstraction-review`; do not approve it here.
+
+## Source Trace
+
+- Sandi Metz, Katrina Owen, and TJ Stankus, *99 Bottles of OOP*, Second Edition,
+  v2.2.2, Chapters 3-5 and 8-9, pp. 51-154 and 188-268, for change pressure,
+  responsibility extraction, messages, argument movement, dependency direction,
+  API-aware Demeter judgment, forwarding, and responsibility-focused tests.
+- Zachary Tellman, *Elements of Clojure*, Leanpub 2019-02-11:
+  Indirection, public-manuscript pp. 70-95, for environment/model/interface/
+  assumptions, principled components, participant pressure, and calcification.
+- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
+  Interpretation of Computer Programs*, Second Edition,
+  Section 2.1
+  calibrates hidden representation and operation ownership.