@hobin/developer 0.1.7 → 0.1.9

package/skills/sketch/references/runtime-and-compilation.md

@@ -0,0 +1,84 @@
+# Runtime And Compilation
+
+Use this reference after [Language Semantics](language-semantics.md) when the
+accepted language must be interpreted, lowered, compiled, optimized, or mixed
+across execution modes.
+
+## Execution Convention
+
+```text
+inputs and result location
+control/continuation owner
+state modified and state live across nested work
+error/cancellation transfer
+allocation roots, identity, and release
+interpreted/compiled or old/new interoperation
+```
+
+A language contract does not implement this convention; the runtime must preserve
+its declared observers.
+
+## Effect Summaries
+
+Attach conservative summaries to generated fragments:
+
+```text
+needs | modifies | allocates | performs | may-fail
+```
+
+A composition may omit a save, lookup, or check only when the summary proves it
+unneeded. Missing an effect can produce pass-but-wrong execution;
+over-approximating usually loses optimization.
+
+## Optimization Guard
+
+```text
+assumption:
+proof or runtime guard:
+fallback:
+observers preserved:
+```
+
+Lexical addressing, primitive inlining, or direct transfer must preserve scope,
+rebinding, evaluation order, errors, effects, and tail-space promises. Tail calls
+require direct control transfer without a frame retained solely for return.
+
+Mixed execution requires a shared calling convention or an explicit adapter.
+State the complete root set, object identity across movement, external handles,
+capacity, release, and out-of-memory behavior.
+
+## Artifact
+
+```text
+Source language observers:
+Calling and result convention:
+Control, live state, save/restore, error, and cancellation:
+Effect summaries:
+Optimization assumptions, guards, and fallback:
+Tail-space obligation:
+Roots, identity, capacity, handles, and release:
+Interoperation adapter:
+Trace or generated-fragment check:
+```
+
+## Stop And Separation
+
+Stop when a representative nested call and optimized fragment preserve the
+accepted language observers under explicit guards, and roots/release/interoperation
+are complete enough to falsify runtime claims.
+
+Return to `language-semantics` when program meaning remains unsettled. Use
+`process-shape-and-resources` for ordinary non-language process boundaries.
+
+## Source Trace
+
+- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
+  Interpretation of Computer Programs*, Second Edition:
+  Section 5.1,
+  Section 5.3,
+  Section 5.4,
+  and Section 5.5
+  for calling conventions, explicit control, effect/liveness summaries, roots,
+  tail calls, compilation guards, and mixed execution.
+- Validation taxonomies, migrations, production capacity, and rollout protocols
+  are Developer adaptations, not SICP claims.

package/skills/sketch/references/selection-and-creation.md

@@ -0,0 +1,76 @@
+# Selection And Creation
+
+Use this reference when the accepted design must decide which concrete variant to
+construct or supply at a boundary.
+
+## Selection Policy
+
+State:
+
+```text
+available variants and selection input
+owner of dispatch key
+predicate overlap and precedence
+conflict/duplicate policy
+unsupported case
+visibility and load order
+```
+
+Moving predicates into data or registration relocates precedence ownership; it
+does not remove it.
+
+## Creation Continuum
+
+Compare:
+
+```text
+local conditional
+configurable mapping
+registration
+self-registration
+automatic discovery
+```
+
+For each mechanism ask who knows variants, how a new one appears, how duplicates
+and unsupported cases fail, and which reflection, naming, startup, deployment,
+and test assumptions it adds.
+
+Choose the least powerful mechanism satisfying real extension pressure. Moving
+creation to the composition edge keeps concrete names out of domain collaboration
+but does not eliminate selection responsibility or automatically eliminate a
+factory.
+
+## Artifact
+
+```text
+Accepted creation pressure:
+Variants and selection input:
+Selection owner:
+Overlap, precedence, duplicate, unsupported, and load-order policy:
+Creation mechanism and assumptions:
+Local conditional/mapping/registration/discovery comparison:
+Fake variant and startup-failure checks:
+Deferred openness:
+```
+
+## Stop And Separation
+
+Stop when selection has one owner, conflicts and failures are visible, and the
+creation mechanism is no more open or operationally powerful than accepted
+pressure requires.
+
+Use `variation-roles-and-transitions` when the caller role itself is unresolved,
+`generic-dispatch-systems` for a full representation-operation matrix, and
+`abstraction-review` for promotion of a concrete factory/registry boundary.
+
+## Source Trace
+
+- Sandi Metz, Katrina Owen, and TJ Stankus, *99 Bottles of OOP*, Second Edition,
+  v2.2.2, Chapters 6-8, pp. 155-225, for factories, dependency inversion,
+  creation at the edge, forwarding, and the distinction between moving creation
+  and eliminating a factory.
+- Zachary Tellman, *Elements of Clojure*, Leanpub 2019-02-11, Indirection,
+  public-manuscript pp. 64-69 and 90-95, for ordered dispatch conflicts,
+  openness cost, participant pressure, and interface calcification.
+- Automatic discovery, startup visibility, and deployment checks are Developer
+  adaptations of those boundaries.

package/skills/sketch/references/state-history-and-order.md

@@ -0,0 +1,126 @@
+# State, History, And Order
+
+Use this reference when identical explicit inputs can produce different outcomes
+because of prior interactions, identity, aliases, event order, or retained
+history.
+
+## State Is A History Summary
+
+```text
+account.withdraw(40) -> Accepted
+account.withdraw(40) -> Rejected
+```
+
+If history explains the difference, fill:
+
+```text
+required history
+sufficient current summary
+owner and writers
+identity and aliases
+transition law
+persistence or replay boundary
+```
+
+Do not store the whole past when a sufficient summary preserves all required
+behavior. Do not claim a summary is sufficient when audit, replay, merge, or
+causal evidence is a product requirement.
+
+## Explicit Transition Surface
+
+```text
+Payment = Created | Authorizing(attempt, requestId)
+        | Authorized(id) | Failed(reason)
+
+transition(Created, Authorize) -> Authorizing(1, requestId)
+transition(Authorizing(_, current), Approved(stale)) -> unchanged
+transition(Authorizing(_, current), Approved(current)) -> Authorized(id)
+```
+
+State events, guards, next states, unchanged fields, invalid events, and
+idempotency. A correct enum without transitions is not a correct history model.
+
+Cover stale, duplicate, reordered, retried, and concurrent events. If those rules
+are still product policy, return to `model` rather than choosing a mechanism.
+
+## Identity, Aliases, And Mutation Graphs
+
+Equal current values may denote different histories. Multiple references may
+observe the same mutation. Record:
+
+- identity rule;
+- alias sources and newly introduced sharing edges;
+- cycle and visited-scope policy;
+- which transitions preserve or break sharing;
+- cache or denormalized-field consistency.
+
+A local mutation is modular only when a coherent history owner and its observer
+boundary remain clear.
+
+## Event Order And Atomicity
+
+State the smallest required order law. For withdrawal:
+
+```text
+read balance -> check funds -> write next balance
+```
+
+must behave as one protected transition for one account. Do not begin with
+“serialize everything.” Choose lock, transaction, queue, compare-and-swap, or
+merge only after naming the forbidden interleaving, cross-resource scope,
+waiting cost, and progress obligation.
+
+Per-object protection cannot preserve an invariant spanning several resources
+unless the coordination scope spans them or the model permits convergence.
+
+## Streams And Logs
+
+```text
+events -> fold(transition, initialState) -> currentState
+```
+
+A log exposes history for replay, audit, merge, or time travel, but adds ordering,
+versioning, retention, identity, and reconstruction costs. A stream of states and
+an event log are different contracts.
+
+For delayed streams record demand, memoization, producer/consumer pace, buffer or
+backpressure, replayability, retained prefixes, effects, failure, and
+cancellation. Laziness moves time obligations; it does not remove them.
+
+## Artifact
+
+```text
+Required history and sufficient summary:
+Owner, writers, identity, and aliases:
+States, events, transitions, and unchanged fields:
+Stale, duplicate, retry, reorder, and invalid policy:
+Order/atomicity law and forbidden interleaving:
+Cross-resource coordination scope:
+Stream/log meaning, demand, retention, and replay:
+Alternative local-state or explicit-history representation:
+Checks and residual policy:
+```
+
+## Stop And Separation
+
+Stop when the state representation explains every admitted history, one owner
+controls each transition, and order/identity/log observers are explicit.
+
+Use `process-shape-and-resources` for wait, capacity, stack, or lifetime without
+product history; return to `model/temporal-behavior-models` when allowed histories
+or fairness remain unresolved; use `verify` when the design exists but traces are
+not exercised.
+
+## Source Trace
+
+- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
+  Interpretation of Computer Programs*, Second Edition:
+  Section 3.1,
+  Section 3.3,
+  Section 3.4, and
+  Section 3.5
+  for history, identity, mutation graphs, concurrency, streams, demand, and
+  memoization.
+- Hillel Wayne, *Logic for Programmers*, v0.14.0, Chapters 9-10, calibrates
+  state/action, stale event, safety/progress, and refinement distinctions; the
+  accepted temporal policy itself remains owned by `model`.

package/skills/sketch/references/type-transitions.md

@@ -0,0 +1,54 @@
+# Type Transitions
+
+Use this reference when an accepted event or operation transforms one domain type
+into another and the design must preserve meaning across the boundary.
+
+## Transition Contract
+
+```text
+source type
+triggering operation or event
+target type
+preconditions
+meaning preserved
+source facts consumed or retained
+boundary or terminal behavior
+failure result
+who selects or constructs the target
+```
+
+A transition that does not preserve a common role may require an explicit result
+type rather than inheritance. The target should not select itself when the needed
+selection knowledge belongs to a caller or creation boundary.
+
+## Artifact
+
+```text
+Source and target types:
+Event/operation and preconditions:
+Preserved meaning:
+Consumed, retained, and newly created facts:
+Terminal/boundary behavior:
+Failure and unsupported transitions:
+Selection/construction owner:
+Transition examples and checks:
+```
+
+## Stop And Separation
+
+Stop when every accepted source state has one explicit target/failure meaning and
+preserved facts can be checked without relying on representation coincidence.
+
+Use `variation-roles` when several implementations share one protocol,
+`selection-and-creation` when target selection is independently unresolved, and
+`model/temporal-behavior` when order among transitions remains product policy.
+
+## Source Trace
+
+- Sandi Metz, Katrina Owen, and TJ Stankus, *99 Bottles of OOP*, Second Edition,
+  v2.2.2, Chapters 6-7, pp. 155-187, for type transitions, target selection, and
+  the boundary between polymorphic role and a changed type.
+- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
+  Interpretation of Computer Programs*, Second Edition,
+  Section 2.5
+  calibrates operations whose results move between representation systems.

package/skills/sketch/references/variation-roles.md

@@ -0,0 +1,59 @@
+# Variation Roles
+
+Use this reference when accepted variants may share one caller protocol without
+exposing concrete type.
+
+## Role And Substitution
+
+State:
+
+```text
+caller messages
+preconditions
+result meaning
+failure outcomes
+effects and ordering
+unsupported cases
+implementations
+```
+
+Every implementation must preserve caller expectations. A variant requiring
+stronger inputs or producing different result/effect meaning may need a narrower
+role.
+
+Conditionals remain appropriate when variants are local, finite, readable, and
+owned together. Polymorphism is justified when accepted variants repeatedly
+force old behavior owners to change and callers can remain ignorant of concrete
+types.
+
+## Artifact
+
+```text
+Accepted variation pressure:
+Caller role contract:
+Implementations:
+Precondition/result/failure/effect substitution checks:
+Unsupported cases:
+Direct-conditional alternative:
+Transfer implementation:
+Deferred variants:
+```
+
+## Stop And Separation
+
+Stop when every admitted implementation substitutes for all declared observers
+and one transfer implementation fits without adding a type test or flag to the
+caller contract.
+
+Use `type-transitions` when one domain type becomes another,
+`selection-and-creation` when choosing/constructing a variant is independent,
+and `model/contract-replacement` when role compatibility itself is disputed.
+Route a shaped role candidate to `abstraction-review` for promotion.
+
+## Source Trace
+
+- Sandi Metz, Katrina Owen, and TJ Stankus, *99 Bottles of OOP*, Second Edition,
+  v2.2.2, Chapters 5-6, pp. 102-170, for responsibility separation, role
+  substitution, and polymorphic movement.
+- Hillel Wayne, *Logic for Programmers*, v0.14.0, Chapter 5, pp. 47-60,
+  calibrates caller-contract replacement and observer-relative preservation.

package/skills/verify/SKILL.md

@@ -11,6 +11,19 @@ Map evidence to claims without turning green checks into broader proof.
 
 What claims does the available evidence support?
 
+## Judgment Spine
+
+```text
+claim and observer
+-> cheapest relevant falsifier
+-> executed evidence and provenance
+-> plausible pass-but-wrong implementation
+-> strongest supported claim + explicit residual
+```
+
+Green execution is only an observation until relevance and counterexample
+coverage connect it to the claim.
+
 ## Inputs
 
 - Claims under review
@@ -20,12 +33,10 @@ What claims does the available evidence support?
 
 ## Reference Routing
 
-Read [the verifier selection and pass-but-wrong reference](references/verifier-selection-and-pass-but-wrong.md)
-when several claims need different evidence, a passing command may not exercise
-the accepted meaning, source compatibility matters, or behavior can pass while
-structure degrades. Also read it before a consequential completion claim whose
-verifier relevance or residual risk is unclear. A narrow claim with direct,
-relevant evidence does not need the reference.
+The machine-readable [reference policy](reference-policy.json) is the routing
+authority. Its routed extension refines claim splitting, verifier relevance, and
+pass-but-wrong search, then declares the evidence artifact, stop, and handoff.
+Use the exemption only when no trigger applies and cite its evidence.
 
 ## Output
 

package/skills/verify/reference-policy.json

@@ -0,0 +1,30 @@
+{
+  "version": 2,
+  "routes": [
+    {
+      "id": "claim-evidence-gap",
+      "question": "What strongest claim does the executed evidence support after relevance and pass-but-wrong risk are considered?",
+      "trigger": "Several claims need different evidence, a green check may not exercise accepted meaning, source/version compatibility matters, behavior can pass while structure degrades, or a consequential completion claim has unclear verifier relevance or residual risk.",
+      "method_step": "split claims and observers, choose the cheapest falsifier, inspect execution/provenance, attempt a plausible wrong implementation, then narrow the supported claim",
+      "references": [
+        "references/verifier-selection-and-pass-but-wrong.md"
+      ],
+      "artifacts": [
+        "a claim/evidence/relevance matrix",
+        "requested-versus-exercised provenance",
+        "a plausible wrong shape, distinguishing check, strongest supported claim, and residual"
+      ],
+      "stop": "Every claim is supported, narrowed, contradicted, or explicitly unverified, and another verifier costs more than its expected information.",
+      "separate_when": "The claim itself or admitted model is unresolved, implementation repair is requested, or remaining acceptance is human-owned; hand off rather than broadening evidence."
+    }
+  ],
+  "exemption": {
+    "when": "One narrow claim has direct, relevant, source-matched evidence, no consequential structural observer, and no plausible cheap pass-but-wrong shape.",
+    "evidence": [
+      "the exact claim and observer",
+      "the directly relevant executed check",
+      "the source/version exercised",
+      "the attempted counterexample and bounded residual"
+    ]
+  }
+}