@hobin/developer 0.1.8 → 0.1.10

package/skills/model/references/solver-result-boundaries.md

@@ -0,0 +1,83 @@
+# Solver Result Boundaries
+
+Use this reference when the model must interpret bounded counterexample search,
+satisfiability, feasibility, or optimization status.
+
+## Encoding Before Status
+
+Separate:
+
+```text
+variables and domains
+hard constraints
+optional objective or ranking
+solution equivalence
+finite scope and search reductions
+encoding assumptions
+```
+
+A mathematically optimal solution can still be operationally wrong when the
+objective encodes the wrong preference.
+
+## Satisfiable Witness And Bound
+
+A bounded result supports only its scope and configuration. Record one
+satisfiable witness for the assumptions so an inconsistent model cannot make
+implications pass vacuously.
+
+```text
+scope and bounds
+property checked
+valid witness
+counterexample result
+unknown or incomplete paths
+```
+
+Absence of a counterexample inside a bound is not an unbounded proof.
+
+## Preserve Result States
+
+Keep exposed statuses distinct:
+
+```text
+satisfiable | unsatisfiable | unknown | timeout | error
+unbounded | feasible | proven-optimal
+```
+
+A feasible result is not an optimality proof. `unknown` is neither satisfaction
+nor impossibility. Specialization trades modeling flexibility for runtime and
+predictability; state that ability-guarantee exchange.
+
+## Artifact
+
+```text
+Variables, domains, and hard constraints:
+Objective and solution equivalence:
+Scope, bounds, and reductions:
+Encoding assumptions:
+Satisfiable witness:
+Exact result status and meaning:
+Counterexample or solution:
+Unmodeled product observers:
+Residual and verification target:
+```
+
+## Stop And Separation
+
+Stop when the reported claim is no broader than the encoded model, bound, witness,
+and exact result status.
+
+Use `proof-obligations` for deductive implementation conformance,
+`logic-query-semantics` for answer enumeration/search semantics, and `verify` for
+tool execution relevance.
+
+## Source Trace
+
+- Hillel Wayne, *Logic for Programmers*, v0.14.0:
+  Chapters 9-11, pp. 100-155, for bounded models, solver encodings,
+  satisfiability, feasibility, optimization, and result states. Recorded beta
+  defects are excluded.
+- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
+  Interpretation of Computer Programs*, Second Edition,
+  Section 3.3.5
+  calibrates relation propagation and contradiction, not modern solver status.

package/skills/model/references/temporal-behavior-models.md

@@ -0,0 +1,106 @@
+# Temporal Behavior Models
+
+Use this reference when correct snapshots are insufficient and the judgment
+depends on histories, retries, stale events, concurrency, or progress.
+
+## Behavior Before State Names
+
+Define a temporal model in this order:
+
+```text
+initial states
+admitted actions and their enabling conditions
+next-state effects and unchanged fields
+safety: forbidden histories
+progress: required eventual behavior
+stuttering or termination semantics
+fairness assumptions by action
+observable refinement boundary
+```
+
+A list of enums is not a temporal model. Every action needs a frame condition so
+omitted state does not change accidentally.
+
+## Representative Retry Model
+
+```text
+Payment = Created
+        | Authorizing(attempt, requestId)
+        | Authorized(paymentId)
+        | Failed(reason)
+
+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
+```
+
+```text
+safety: authorization is recorded at most once
+progress assumption: an enabled live attempt eventually receives a response,
+                     and retries are finite
+```
+
+Exercise stale, duplicate, reordered, retry, cancellation, and concurrent traces.
+One test per state cannot distinguish these histories.
+
+## Stuttering, Termination, And Valid Behavior
+
+State whether a completed system may stop or is modeled by repeated unchanged
+steps. Exhibit at least one valid behavior so inconsistent assumptions cannot
+make every implication vacuously true.
+
+Fairness must name:
+
+- the action it applies to;
+- whether enablement must be continuous or only repeated;
+- the environment assumption that makes the requirement plausible.
+
+Safety does not imply progress. Fairness does not repair an action that is never
+enabled.
+
+## Refinement Observer
+
+An implementation refines an abstract model only when each observable
+implementation behavior is allowed by the abstract specification, possibly after
+an explicit mapping. Declare which intermediate states, failures, timing, or
+effects the observer can see. An abstract atomic action cannot justify visible
+partial states without a refinement argument.
+
+## Artifact
+
+```text
+State variables and initial states:
+Actions, guards, effects, and frame conditions:
+Representative valid trace:
+Stale / duplicate / reordered / retry / concurrent traces:
+Safety properties:
+Progress properties:
+Stuttering or termination semantics:
+Fairness scope and environment assumptions:
+Refinement mapping and observers:
+Guarantee owners and verification targets:
+```
+
+## Stop And Separation
+
+Stop when the model distinguishes all consequential histories and every safety or
+progress claim has assumptions and a counterexample trace.
+
+Hand off to `sketch` when state ownership or event APIs must be designed, to
+`verify` when the model exists but traces are unexercised, and to
+`planning-models` when the main question is finding one goal-directed action
+sequence rather than admitting all valid behaviors.
+
+## Source Trace
+
+- Hillel Wayne, *Logic for Programmers*, v0.14.0:
+  Chapters 9-10, pp. 100-138, for bounded instances, actions, safety, liveness,
+  stuttering, fairness, and refinement. Recorded beta defects are excluded.
+- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
+  Interpretation of Computer Programs*, Second Edition:
+  Section 3.1
+  and Section 3.4
+  for history, identity, assignment, and allowed concurrent histories.

package/skills/naming-judgment/SKILL.md

@@ -12,6 +12,19 @@ Choose names that preserve domain sense across implementation change.
 What domain sense should this name expose, what detail should it hide, and what
 change boundary should it preserve?
 
+## Judgment Spine
+
+```text
+callers and audience
+-> sign / current referent / relied-upon sense
+-> expected evolution and effect boundary
+-> reveal/hide decision
+-> bounded rename map + unchanged checks
+```
+
+If the sense cannot stabilize without redesigning responsibility or policy, hand
+off instead of hiding that work in a rename.
+
 ## Inputs
 
 - Current name and the code or artifact it identifies
@@ -79,7 +92,7 @@ Reuse does not prove that a generic name is sound.
 
 ## Reference Routing
 
-Read [the domain naming reference](references/domain-naming.md) for
-subtle, disputed, or recurring naming pressure. Also read it when the apparent
-naming problem may involve false indirection, a data-scope crossing, an effect
-hidden by a pure-sounding word, or responsibility-derived vocabulary.
+The machine-readable [reference policy](reference-policy.json) is the routing
+authority. Its routed extension refines the sense step, declares the rename
+artifact and stop, and names when model or design work owns the instability. Use
+the exemption only when no trigger applies and cite its evidence.

package/skills/naming-judgment/reference-policy.json

@@ -0,0 +1,29 @@
+{
+  "version": 2,
+  "routes": [
+    {
+      "id": "domain-sense-boundary",
+      "question": "Which stable sense should this sign expose to its audience while hiding the current implementation referent?",
+      "trigger": "Naming pressure is subtle, disputed, recurring, effect-hiding, responsibility-derived, false indirection, or crosses data/module scope so stable sense cannot be read directly from nearby callers.",
+      "method_step": "after inspecting callers and audience, distinguish sign, referent, relied-upon sense, expected evolution, reveal/hide boundary, and effects",
+      "references": [
+        "references/domain-naming.md"
+      ],
+      "artifacts": [
+        "a sign/referent/sense and audience map",
+        "the smallest rename map with reveal/hide rationale",
+        "behavior, effect, convention, and scope checks"
+      ],
+      "stop": "The proposed name is narrow and locally consistent for the relied-upon sense, and no architectural redesign is hidden in the rename.",
+      "separate_when": "The sense cannot be stable until product meaning, ownership, process, or candidate validity is resolved; hand off to model, sketch, or abstraction-review."
+    }
+  ],
+  "exemption": {
+    "when": "Nearby callers, tests, audience, effects, and conventions make the stable sense and smallest rename direct, with no disputed evolution, scope, indirection, or responsibility boundary.",
+    "evidence": [
+      "the inspected callers and audience",
+      "the current referent and relied-upon sense",
+      "the bounded rename scope and unchanged behavior"
+    ]
+  }
+}

package/skills/naming-judgment/references/domain-naming.md

@@ -5,6 +5,10 @@ misleading, effect-hiding, or disputed across callers. This capability judges
 the word and the sense readers may rely on; it does not redesign the surrounding
 module or process.
 
+It extends `naming-judgment` at the sense step: distinguish sign, current
+referent, relied-upon sense, audience, and expected evolution, then produce one
+bounded rename map. An unstable responsibility is a handoff, not a naming task.
+
 ## Narrow And Consistent
 
 A useful name is both narrow and consistent:
@@ -28,8 +32,13 @@ referent: the current value, function, type, or implementation
 sense: the stable properties readers understand and rely on
 ```
 
-Judge the name around its sense. Complete this statement before proposing a
-rename:
+Judge the name around its sense. Equal current referents do not establish equal
+sense: two values or implementations may need distinct names because readers
+expect them to evolve independently. Conversely, two distinct signs should not
+invent a future divergence nobody intends. Record that evolution observer before
+merging or splitting vocabulary.
+
+Complete this statement before proposing a rename:
 
 ```text
 <old> says <current sense>, but callers rely on <actual sense>.
@@ -191,12 +200,22 @@ Naming judgment is weak when:
 
 ## Source Trace
 
-- Zachary Tellman, *Elements of Clojure*, 2019: the Names chapter on narrow and
-  consistent names, sign/referent/sense, naming data, functions, and macros; the
-  Indirection and Composition chapters inform effect and context boundaries but
-  their architectural decisions are owned by `sketch` and
-  `abstraction-review`.
+- Zachary Tellman, *Elements of Clojure*, Leanpub edition published 2019-02-11,
+  cross-checked against the public
+  first-printing manuscript:
+  Names, public-manuscript pp. 7-26, for narrow and consistent names,
+  sign/referent/sense, expected evolution, audience, and naming data, functions,
+  and macros; Idioms pp. 40-45 and 58-61 for dynamic-scope/effect and absence
+  boundaries; Indirection pp. 64-95 for context and interface sense; and
+  Composition pp. 98-119 for process effects. Architectural decisions remain
+  owned by `sketch` and `abstraction-review`;
+  recorded source defects and Clojure-specific naming syntax are not universal
+  rules.
 - Sandi Metz, Katrina Owen, and TJ Stankus, *99 Bottles of OOP*, Second
-  Edition, version 2.2.2, 2024: chapters 2, 4, 5, and 9 on exposing
-  responsibilities, provisional names, deriving names from responsibilities,
-  naming classes, and communicating with future readers.
+  Edition, version 2.2.2, 2024: Chapter 1, pp. 12-13; Chapter 2, pp. 37-43;
+  Chapter 3, pp. 63-64; Chapter 4, pp. 75-99; Chapter 5, pp. 112-113;
+  Chapter 6, pp. 159-160; Chapter 8, pp. 196-216; and Chapter 9, pp. 237-243
+  and 257-259, on implementation-shaped names, sender knowledge, provisional
+  names, deriving names from responsibilities, receiver-supplied context,
+  sender-oriented requests, naming classes, and communicating with future
+  readers.

package/skills/schedule/SKILL.md

@@ -11,6 +11,18 @@ Decide when a concrete structural move belongs.
 
 When should this candidate be done: now, after, or never?
 
+## Judgment Spine
+
+```text
+stable concrete candidate
+-> current dependency and invariant pressure
+-> guarantee gained / ability lost
+-> reversibility, delay cost, and nested work
+-> now | after(immediate/later + reopen) | never
+```
+
+Timing cannot stabilize a candidate whose meaning or surface is still unresolved.
+
 ## Inputs
 
 - Concrete candidate and scope
@@ -20,12 +32,10 @@ When should this candidate be done: now, after, or never?
 
 ## Reference Routing
 
-Read [the structural change timing reference](references/structural-change-timing.md)
-when a behavior change and structural change compete, when `now` would remove
-meaningful implementation freedom, or when reversibility, nested work, and cost
-of delay point in different directions. Also read it when an `after` decision
-needs an observable reopen condition. A small, reversible candidate whose
-timing follows directly from the current invariant does not need the reference.
+The machine-readable [reference policy](reference-policy.json) is the routing
+authority. Its routed extension refines the tradeoff step, declares the timing
+artifact and stop, and names when an unstable candidate must be handed back. Use
+the exemption only when no trigger applies and cite its evidence.
 
 ## Output
 

package/skills/schedule/reference-policy.json

@@ -0,0 +1,29 @@
+{
+  "version": 2,
+  "routes": [
+    {
+      "id": "structural-timing-tradeoff",
+      "question": "Should this concrete structural candidate happen now, after, or never for the current accepted work?",
+      "trigger": "Behavior and structural change compete, doing structure now may remove meaningful ability, reversibility and delay cost conflict, nested work is consequential, or an after decision needs an observable reopen condition.",
+      "method_step": "after confirming a concrete candidate, compare current invariant pressure, gained guarantee, lost ability, observer-relative reversibility, delay cost, nested work, optionality, and batch boundary",
+      "references": [
+        "references/structural-change-timing.md"
+      ],
+      "artifacts": [
+        "a now/after/never timing matrix",
+        "guarantee-versus-ability and reversibility evidence",
+        "an after mode and observable reopen condition when applicable"
+      ],
+      "stop": "One timing outcome follows from current evidence without inventing product priority or treating future flexibility as free value.",
+      "separate_when": "The candidate surface, meaning, or stability is unresolved; hand back to sketch, model, signal, or abstraction-review before scheduling."
+    }
+  ],
+  "exemption": {
+    "when": "A small reversible candidate has a direct timing consequence from the current invariant, with no behavior/structure conflict, lost ability, nested work, or meaningful delay tradeoff.",
+    "evidence": [
+      "the exact candidate and current dependency",
+      "the direct invariant and reversibility evidence",
+      "the outcome and any immediate follow-up boundary"
+    ]
+  }
+}

package/skills/schedule/references/structural-change-timing.md

@@ -4,6 +4,10 @@ Use this reference when a concrete refactor or abstraction candidate competes
 with a behavior change, and timing depends on reversibility, optionality,
 invariant pressure, or the cost of delay.
 
+It extends `schedule` only at the tradeoff step: derive one `now | after | never`
+decision, its observer-relative reversibility, and its reopen condition. If the
+candidate surface is still unstable, hand it back rather than timing a wish.
+
 ## Contents
 
 - Behavior And Structure
@@ -27,16 +31,20 @@ Separate two kinds of change before deciding timing:
   behavior.
 
 The same diff may contain both. Split them conceptually even when they are
-committed together. A structural candidate belongs now only when its timing can
-be justified by the current behavior or invariant—not merely by aesthetic
-preference.
+committed together. Define the behavior observer before calling a change
+structural: returned values may stay equal while effects, exception timing,
+ordering, resource use, persisted forms, or public compatibility change. A
+structural candidate belongs now only when its timing can be justified by the
+current behavior or invariant—not merely by aesthetic preference.
 
 ## Small And Separate Structural Moves
 
 A tidying is a small, behavior-preserving structural move. Keep it small enough
 that the intended rearrangement, affected behavior evidence, and rollback are
 obvious. Separate it from behavior change in reasoning and, when practical, in
-the change history.
+the change history. Separate pull requests are one workflow option, not the
+definition: review latency, integration policy, deployment independence, and
+team trust determine useful batch boundaries.
 
 Small does not mean arbitrary. A chain of tidyings can quietly become a redesign.
 After each move, ask whether the next one still lowers the cost of the accepted
@@ -56,8 +64,16 @@ This skill uses three outcomes:
   harmful, or has no evidence-backed pressure.
 
 The book distinguishes `first`, `after`, `later`, and `never`. This skill maps
-`first` to `now` and folds immediate follow-up and evidence-triggered `later`
-into `after`; the reopen condition preserves the important distinction.
+`first` to `now` and folds both immediate follow-up and evidence-triggered
+`later` into `after`. Preserve the distinction inside the decision:
+
+```text
+after mode: immediate follow-up | evidence-triggered later
+reopen: observation that starts a later move; `none` for immediate follow-up
+```
+
+Do not use `never` to mean merely “not in this task.” It requires no credible
+future behavior pressure or learning value within the admitted environment.
 
 ## Decision Procedure
 
@@ -70,9 +86,16 @@ Ask in order:
 5. What implementation freedom or alternate representation would it remove?
 6. Can a smaller type, contract, test, validation, adapter, or local movement
    provide the same guarantee?
-7. How reversible is the move if the model changes?
+7. How reversible is the move if the model changes, and for which observer?
 8. What cost grows if the move is delayed?
 9. What nested work does doing it now create?
+10. Does the move pay off immediately through comprehension or a cheaper accepted
+    behavior change?
+11. If payoff is later, which credible behavior changes become cheaper and how
+    will that option be exercised?
+12. How confident are we that this specific movement removes the present obstacle?
+13. What batch, review, integration, and deployment boundaries keep the move
+    locally explainable?
 
 Choose `now` when the accepted work is otherwise blocked, unsafe, or difficult
 to verify for a concrete reason. Choose `after` when the move is plausible and
@@ -111,6 +134,24 @@ valid implementation paths.
 
 Do not confuse large effort with irreversibility. A large but isolated movement
 may remain reversible; a one-line public contract can be difficult to undo.
+Assess reversibility against code rollback, persisted data, public consumers,
+external effects, generated artifacts, deployment order, and the time during
+which old and new forms coexist. “Can revert the commit” is not enough when an
+observer has already acted on the new behavior or shape.
+
+Treat optionality as a decision aid, not an options-pricing calculation. Name the
+credible future behavior portfolio, the structural choice preserved, the cost of
+exercising it, the period in which it remains useful, and the present premium.
+Unspecified future flexibility is not an option, and uncertainty alone does not
+make a structural investment valuable.
+
+Judge structural excess against the environment the code serves now and is
+credibly expected to serve. A broader model removes assumptions but grows the
+conceptual surface. A public or multi-party interface can outlive every current
+implementation, so let a boundary mature under local control before making it
+foundational when possible. Conversely, replacing an accreted component from
+scratch is costly; cut away only what current work can no longer use rather than
+rebuilding merely to obtain a cleaner model.
 
 ## Nested Work Pressure
 
@@ -128,9 +169,14 @@ protecting the current invariant. If a small prerequisite is genuinely needed,
 schedule that prerequisite rather than the full idealized architecture.
 
 Also watch batch size and rhythm. Several individually safe moves can create a
-large review and debugging surface when chained without checkpoints. Prefer a
-rhythm of small structural movement, evidence, then behavior progress over a long
-cleanup prelude whose payoff cannot yet be observed.
+large review and debugging surface when chained without checkpoints. Compare
+fixed review/integration/deployment cost against collision delay, interactions
+between moves, and speculative cleanup. Those curves are local measurements,
+not universal laws. Integration and deployment may be separate events, and
+unreviewed tidyings require earned evidence about tooling, checks, ownership,
+and failure recovery—not a claim of absolute safety. Prefer a rhythm of small
+structural movement, evidence, then behavior progress over a long cleanup prelude
+whose payoff cannot yet be observed.
 
 ## Worked Timing Decision
 
@@ -205,13 +251,30 @@ The timing judgment is weak when:
 ## Source Trace
 
 - Kent Beck, *Tidy First?: A Personal Exercise in Empirical Software Design*,
-  O'Reilly Media, 2023: behavior/structure separation, small tidyings,
-  first/after/later/never decisions, batching, optionality, reversibility, and
-  the economics of structural change.
+  First Edition, Second Release, O'Reilly Media, 2025-12-12:
+  Part II, Chapters 16-21, pp. 35-54, for separating behavior and structure,
+  chaining, batch costs, rhythm, untangling, and first/after/later/never timing;
+  and Part III, Chapters 23-31, pp. 61-87, for immediate behavior value,
+  optionality, cash-flow timing, reversibility, and change-relative coupling.
+  The package treats option pricing, Pareto/power-law claims, absolute safety,
+  integration-equals-deployment, and Constantine's Equivalence as heuristics or
+  excluded overclaims, not universal laws. Production migration, telemetry,
+  rollout, and rollback protocols remain Developer adaptations.
 - Sandi Metz, Katrina Owen, and TJ Stankus, *99 Bottles of OOP*, Second
-  Edition, version 2.2.2, 2024: waiting for real change pressure, tolerating
-  duplication, selecting a point of attack, gradual movement, and stable
-  landings.
+  Edition, version 2.2.2, 2024: Chapter 1, pp. 2-22; Chapters 3-4,
+  pp. 51-101; and Chapter 8, pp. 188-192 and 223-225, on waiting for real
+  change pressure, tolerating informative duplication, selecting a point of
+  attack, gradual movement, stable landings, and deferring added indirection
+  whose current payoff is not justified.
+- Zachary Tellman, *Elements of Clojure*, Leanpub edition published 2019-02-11,
+  cross-checked against the public
+  first-printing manuscript:
+  Indirection, public-manuscript pp. 81-95, for environment-relative
+  over-engineering, model growth, replacement cost, interface calcification,
+  and maturing externally visible boundaries. Production migration, telemetry,
+  rollout, and rollback protocols remain Developer adaptations.
 - Hillel Wayne, *Logic for Programmers*, version 0.14.0, May 4, 2026:
-  ability-guarantee tradeoffs and replacement obligations that affect the cost
-  and reversibility of a structural choice.
+  Chapter 2, pp. 16-17, for the bidirectional ability-guarantee tradeoff and
+  Chapter 5, pp. 55-60, for replacement obligations and observable accidental
+  contracts. Production migration, telemetry, and rollback economics remain
+  Developer adaptations.

package/skills/signal/SKILL.md

@@ -11,6 +11,18 @@ Observe structural movement without promoting or scheduling it.
 
 What structural movement is actually visible in the evidence?
 
+## Judgment Spine
+
+```text
+current pressure
+-> closest comparable pair
+-> one smallest meaningful difference
+-> one behavior-preserving falsifying move
+-> no-signal | horizontal | vertical | ambiguous
+```
+
+The output is an observation and optional candidate, never a refactoring plan.
+
 ## Inputs
 
 - Requirement, code slice, diff, tests, command output, or UI state
@@ -20,12 +32,11 @@ What structural movement is actually visible in the evidence?
 
 ## Reference Routing
 
-Read [the structural movement reference](references/structural-movement.md)
-when duplication, parallel branches, similar tests, repeated UI states,
-conditionals, or a recent refactor need a behavior-preserving next move. Also
-read it when the horizontal/vertical distinction is consequential or the
-available checks may not keep a small movement green. A direct, evidence-backed
-observation with no proposed movement does not need the reference.
+The machine-readable [reference policy](reference-policy.json) is the routing
+authority. Its routed extension refines comparison and falsification, declares
+the classification artifact and stop, and names when promotion or implementation
+belongs elsewhere. Use the exemption only when no trigger applies and cite its
+evidence.
 
 ## Output
 

package/skills/signal/reference-policy.json

@@ -0,0 +1,29 @@
+{
+  "version": 2,
+  "routes": [
+    {
+      "id": "behavior-preserving-movement",
+      "question": "What smallest behavior-preserving observation move distinguishes incidental similarity from a durable structural candidate?",
+      "trigger": "Duplication, parallel branches, repeated tests/UI states, conditionals, a recent refactor, change-relative coupling, or model-code mismatch needs consequential horizontal-versus-vertical classification.",
+      "method_step": "select one comparable pair and one smallest difference, state the observer, propose one falsifying local move, then classify no-signal, horizontal, vertical, or ambiguous",
+      "references": [
+        "references/structural-movement.md"
+      ],
+      "artifacts": [
+        "a comparison table with one smallest difference",
+        "a behavior-preserving observation move and relevant check",
+        "a bounded structural classification and candidate only when vertical or ambiguous"
+      ],
+      "stop": "The selected difference is exposed and classified without performing the movement or promoting a destination abstraction.",
+      "separate_when": "The move would change accepted behavior, the candidate already needs review/timing, or the next implementation step is already justified."
+    }
+  ],
+  "exemption": {
+    "when": "The evidence supports a direct no-signal or local structural observation with no consequential proposed movement, horizontal/vertical ambiguity, coupling analysis, or model-code mismatch.",
+    "evidence": [
+      "the exact observed artifact",
+      "the current pressure or absence of pressure",
+      "the bounded classification and why no experiment is needed"
+    ]
+  }
+}