@hobin/developer 0.1.1 → 0.1.3

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

@@ -0,0 +1,218 @@
+# 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/naming-judgment/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: naming-judgment
-description: "Review or create code names by separating stable domain meaning from the current implementation. Use when variables, functions, types, modules, components, APIs, fields, or abstractions are generic, misleading, filler-like, implementation-shaped, or carrying multiple product senses, including requests to apply Elements of Clojure-style naming judgment."
+description: "Review or create code names by separating stable domain meaning from the current implementation. Use when variables, functions, types, modules, components, APIs, fields, or abstractions are generic, misleading, filler-like, implementation-shaped, effect-hiding, or carrying multiple product senses."
 ---
 
 # Naming Judgment
@@ -73,5 +73,7 @@ Reuse does not prove that a generic name is sound.
 
 ## Reference Routing
 
-Read [the naming reference](references/elements-of-clojure-naming.md) for
-subtle, disputed, or recurring naming pressure.
+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.

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

@@ -0,0 +1,202 @@
+# Domain Naming
+
+Use this reference when an identifier is generic, implementation-shaped,
+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.
+
+## Narrow And Consistent
+
+A useful name is both narrow and consistent:
+
+- **narrow**: it excludes meanings and uses the value cannot support;
+- **consistent**: it agrees with the local code, domain vocabulary, ecosystem
+  conventions, documentation, and intended audience.
+
+Narrow does not mean maximally specific. A name that exposes the current storage
+format, library, widget, transport, or algorithm becomes false when that detail
+changes. A name that says only `data`, `item`, `manager`, or `handler` may admit
+uses the contract cannot support.
+
+## Sign, Referent, And Sense
+
+Separate:
+
+```text
+sign: the identifier text
+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:
+
+```text
+<old> says <current sense>, but callers rely on <actual sense>.
+The current referent is <implementation detail>, which should remain
+hidden/exposed because <reason>.
+```
+
+If the relied-upon sense cannot be stated, the apparent naming problem may be a
+missing product concept, invalid abstraction, or mixed responsibility.
+
+## Names As Useful Indirection
+
+A name creates a place where a reader may stop descending. It succeeds only when
+the reader can use the named thing without reopening details that should be
+hidden.
+
+- a data name hides the current representation while exposing role or invariant;
+- a function name hides a computation or effect while exposing its result or
+  action;
+- a module-qualified name supplies shared context;
+- a public name forms vocabulary that future callers may depend on.
+
+Indirection that only renames syntax adds lookup cost without reducing
+conceptual burden. An inline expression can be more honest than a helper with no
+stable sense.
+
+## Data Names
+
+Name data by domain interpretation, role, or invariant rather than by field
+inventory. A parameter name cannot establish the invariant it implies; validation,
+types, or construction must own that guarantee.
+
+Short local names are appropriate when scope makes the arbitrary role obvious
+and they match project conventions. Long names do not repair a missing boundary.
+
+Absence needs an honest vocabulary. Distinguish missing, `undefined`, `null`,
+empty, defaulted, legacy, and invalid values when callers rely on those
+differences. Do not hide a product default in an adjective such as `effective`
+unless its precedence and source are stable parts of the sense.
+
+## Function Names And Effects
+
+Identify whether the function primarily:
+
+1. pulls data from another scope;
+2. transforms data already in scope;
+3. pushes data or an effect into another scope.
+
+A pure transformation should name the domain result or conversion. A boundary
+action should state its effect or destination. Mutation, I/O, caching, logging,
+network calls, retries, and persistence must not hide behind a name that reads as
+a pure calculation.
+
+When a function truly combines phases, an honest composite name may be better
+than a false pure name. Whether the phases should be split is a `sketch` or
+`abstraction-review` question, not a rename performed here.
+
+## Audience And Context
+
+The same natural word can carry different senses in different contexts. Inspect
+who must understand it:
+
+- public and top-level names must work for newcomers and domain readers;
+- local implementation names may rely on established nearby vocabulary;
+- external conventions usually remain intact at adapters;
+- synthetic terms improve precision only when their definition and learning cost
+  are acceptable.
+
+Module placement can supply context and shorten names, but this leaf may only
+recommend a placement review. It must not invent a module solely to make a word
+shorter or redesign module ownership under the label of naming.
+
+## Responsibility-Derived Names
+
+Choose names from what the unit knows, does, or promises, not from the conditional
+or first special case that revealed it. Intermediate names may remain provisional
+while horizontal movement exposes the real responsibility.
+
+For a type or role, ask:
+
+- which messages callers need to send;
+- which knowledge the receiver owns;
+- which change would belong inside it;
+- which current mechanism callers should not learn.
+
+A rich-sounding name does not make an extracted class or interface valid. Return
+that candidate to `abstraction-review` when its responsibility is still disputed.
+
+## Worked Review
+
+Candidate:
+
+```text
+getEffectiveSchedule(formValues)
+```
+
+Caller inspection shows that the function performs no I/O, chooses no fallback,
+and converts editable form values into a validated domain value. The word `get`
+suggests a pull from another scope; `effective` suggests precedence or default
+policy that does not exist; `Schedule` hides that the result is specifically
+content used by the contract boundary.
+
+```text
+sign: getEffectiveSchedule
+referent: pure mapper from ScheduleFormValues to ScheduleContent
+relied-upon sense: validate and convert editable values into domain content
+audience: feature callers and tests
+reveal: conversion and target domain value
+hide: current object literal and validation library
+candidate: toScheduleContent
+```
+
+Check callers after the rename:
+
+```text
+toScheduleContent(values)       // reads as a pure conversion
+saveScheduleContent(content)    // separately exposes the effect
+```
+
+If inspection instead reveals defaults selected from account settings, the
+rename cannot erase that policy. Use an honest name such as
+`resolveScheduleContent` only after the precedence contract is stated, or return
+the mixed operation to `sketch`.
+
+Second contrast:
+
+```text
+readCache(key)            // honest only if it observes cache state
+cachedPrice(input)        // dishonest if it may call a network and write cache
+loadAndCachePrice(input)  // honest composite while a split remains undecided
+```
+
+The result is a rename map plus preserved behavior checks, not a new module or
+class design.
+
+## Review Procedure
+
+1. Read callers, callees, tests, and surrounding vocabulary.
+2. Identify audience, current referent, and relied-upon sense.
+3. Classify the failure: too broad, too specific, effect-hidden, verb mismatch,
+   sense collision, false indirection, or responsibility leak.
+4. State what the name should reveal and what it should hide.
+5. Propose the smallest rename map and affected scope.
+6. Identify checks and external conventions that must remain unchanged.
+7. Defer boundary redesign instead of smuggling it into the rename.
+
+## Failure Checks
+
+Naming judgment is weak when:
+
+- callers were not inspected;
+- the word describes an algorithm rather than stable sense;
+- a broad term admits unsupported uses;
+- a pure-sounding verb hides effects or scope crossing;
+- every intermediate value receives a name without gaining meaning;
+- a rename disguises a model, responsibility, or abstraction problem;
+- external vocabulary is changed without redesigning the adapter contract;
+- module or process redesign is performed under naming authority.
+
+## 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`.
+- 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.

package/skills/schedule/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: schedule
-description: "Decide whether a concrete structural change or reviewed abstraction candidate belongs now, after, or never using invariant pressure, evidence, reversibility, nested-work pressure, and cost of delay. Use when the candidate is concrete and timing is consequential, including requests to apply Tidy First-style behavior-versus-structure sequencing."
+description: "Decide whether a concrete structural change or reviewed abstraction candidate belongs now, after, or never using invariant pressure, evidence, reversibility, nested-work pressure, behavior-versus-structure separation, and cost of delay. Use when the candidate is concrete and timing is consequential."
 ---
 
 # Schedule

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

@@ -7,14 +7,16 @@ invariant pressure, or the cost of delay.
 ## Contents
 
 - Behavior And Structure
+- Small And Separate Structural Moves
 - Timing Vocabulary
 - Decision Procedure
 - Guarantee And Ability Tradeoff
 - Reversibility And Cost Of Delay
 - Nested Work Pressure
+- Worked Timing Decision
 - Reopen Conditions
 - Failure Checks
-- Conceptual Lineage
+- Source Trace
 
 ## Behavior And Structure
 
@@ -29,6 +31,19 @@ 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.
 
+## 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.
+
+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
+behavior change or has become an independent aspiration. When structural and
+behavior changes become tangled, return to the last green state and separate the
+two purposes before continuing.
+
 ## Timing Vocabulary
 
 This skill uses three outcomes:
@@ -40,9 +55,9 @@ This skill uses three outcomes:
 - `never`: reject the candidate for the current scope because it is speculative,
   harmful, or has no evidence-backed pressure.
 
-Kent Beck's broader vocabulary sometimes separates `later` from `after`. Here,
-`after` covers both immediate follow-up and evidence-triggered deferral. The
-reopen condition makes the distinction explicit.
+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.
 
 ## Decision Procedure
 
@@ -112,6 +127,54 @@ Bias toward `after` when the candidate opens a chain of nested work without
 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.
+
+## Worked Timing Decision
+
+Accepted behavior change: add a locker fulfillment method. Current code has a
+small conditional for pickup and delivery copy. Candidate structure: introduce
+a public `FulfillmentStrategy` registry before adding the branch.
+
+```text
+Candidate:
+  public strategy registry
+Current dependency:
+  none; one local conditional can express the accepted third case
+Evidence of stability:
+  variants share a result but have different fields; no independent provider or
+  registration lifecycle exists
+Guarantee gained:
+  future variants could register without editing central dispatch
+Ability lost:
+  exhaustiveness and one visible owner; load order and duplicate registration
+  become new failure modes
+Reversibility:
+  registry is easy to add later but a public API is hard to retract
+Cost of delay:
+  one additional local branch
+Nested work:
+  registry errors, startup wiring, documentation, and plugin tests
+Decision:
+  after
+Reopen:
+  a separately deployed provider must add a variant without changing the core
+```
+
+The accepted behavior proceeds with the direct branch. This is not a claim that
+registries are bad; the present guarantee does not justify their present cost.
+
+Contrast: if the new method must be supplied by an independently deployed
+package and core releases cannot change with it, that pressure makes the
+extension boundary a current invariant. The decision can become `now`, but only
+the smallest boundary required by that invariant should precede behavior.
+
+`never` example: renaming every local `result` solely for stylistic uniformity
+has no relation to the accepted change and no evidence-triggered future value.
+Reject it for this scope rather than disguising it as `after`.
+
 ## Reopen Conditions
 
 An `after` decision must state observable evidence that reopens it, such as:
@@ -139,12 +202,16 @@ The timing judgment is weak when:
 - large nested work is hidden inside a small-sounding abstraction;
 - timing substitutes for product prioritization that only a human can decide.
 
-## Conceptual Lineage
-
-This reference adapts Kent Beck's distinction between behavior and structure,
-and his timing vocabulary of first, after, later, and never. The package reduces
-the vocabulary to `now`, `after`, and `never` while preserving reversibility,
-optionality, and cost-of-delay reasoning.
-
-- Structure and behavior: https://newsletter.kentbeck.com/p/structure-and-behavior
-- First, after, later, never: https://newsletter.kentbeck.com/p/first-after-later-never
+## 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.
+- 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.
+- 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.

package/skills/signal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: signal
-description: "Inspect requirements, code, diffs, tests, UI states, names, or recent changes for observable structural movement and classify it as absent, horizontal, vertical, or ambiguous. Use when evidence suggests duplication, model-code mismatch, boundary pressure, or an emerging refactoring candidate, including requests for flocking-style small behavior-preserving refactoring."
+description: "Inspect requirements, code, diffs, tests, UI states, names, or recent changes for observable structural movement and classify it as absent, horizontal, vertical, or ambiguous. Use when duplication, model-code mismatch, boundary pressure, parallel cases, or an emerging refactoring candidate needs a smallest evidence-backed observation."
 ---
 
 # Signal
@@ -20,7 +20,7 @@ What structural movement is actually visible in the evidence?
 
 ## Reference Routing
 
-Read [the flocking and structural movement reference](references/flocking-and-structural-movement.md)
+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