@hobin/developer 0.1.8 → 0.1.9

package/skills/abstraction-review/references/worked-examples.md

@@ -1,306 +1,129 @@
-# Abstraction Review Worked Examples
+# Abstraction Review Calibration Cases
 
-Use these examples to calibrate the review output. Keep user-facing answers
-shorter unless the user asks for the full card.
-
-Examples are abbreviated to show the main decision move. For a serious review,
-also include the field-card sections for source and confidence, contract, hidden
-detail, evidence and gaps, and open consequences.
-
-## Contents
-
-- Example Selector
-- Skill Update Self-Review
-- Provider Integration
-- Retry Helper From Repeated Movement
-- Optional Default Semantics
-- Symbolic Expression Rewrite
-- Stateful Account
-- Chainable Builder
+Use one case only when the candidate field card is complete but the decision is
+still ambiguous. These examples calibrate review; they do not supply a missing
+candidate surface.
 
 ## Example Selector
 
-Use the smallest example that matches the candidate shape. Do not read the full
-file unless calibration is still unclear.
-
-| Candidate shape | Example to read |
+| Candidate pressure | Calibration |
 | --- | --- |
-| skill, workflow, recipe, or instruction update | Skill Update Self-Review |
-| generic operation, plugin/provider, type/case expansion | Provider Integration |
-| repeated helper movement with stable roles | Retry Helper From Repeated Movement |
-| optional, nullable, defaulted, or legacy value meaning | Optional Default Semantics |
-| expression, formula, DSL, parser, or rewrite rule | Symbolic Expression Rewrite |
-| local state, hidden history, audit, replay, or concurrency | Stateful Account |
-| fluent API, builder, pipeline, or chainable surface | Chainable Builder |
+| repeated movement exposed a helper | Retry Helper |
+| additive provider or type extension | Provider Registry |
+| representation should be hidden | Schedule Boundary |
+| local state claims to simplify callers | Stateful Account |
+| fluent operations claim closure | Query Builder |
 
-## Skill Update Self-Review
+## Retry Helper
 
 ```text
 Candidate:
-  abstraction-review skill update with field-card, recipe-cards, repair-table,
-  and worked examples
-
+  withRetry(operation, shouldRetry, delayStrategy, maxAttempts)
 Pressure:
-  The first version only classified candidates by layer. It could still collapse
-  into polished advice without a concrete artifact or stop check.
-
-Wish:
-  A future agent can review an abstraction by producing a contract, hidden
-  detail, output artifact, observable stop check, and unresolved consequences.
-
-Layer:
-  Boundary + Engine + Run
-
-Recipe:
-  Data Abstraction Boundary for owned responsibility
-  Dispatch Registration for reference routing
-  Procedure -> Process Reality Check for whether agents will actually use it
-
-Input artifact:
-  SKILL.md procedure, reference list, and current reference files
-
-Derivation:
-  core question -> public contract
-  references -> conditional reference choices
-  realistic invocation -> run evidence
-
-Output artifact:
-  skill boundary:
-    owns abstraction promotion judgment
-    does not create the design surface, choose timing, implement, or perform
-    final completion review
-  reference selector:
-    field-card for substantial review
-    recipe-cards for construction rules
-    repair-table for failed stop checks
-    worked-examples for calibration
-
+  three request workflows already share attempt -> classify -> wait -> retry
+Caller contract:
+  execute one operation under explicit retry classification, delay, and limit
+Hidden detail:
+  loop mechanics, attempt bookkeeping, wait scheduling
+Counterexample:
+  payment retry requires idempotency and stale-response ownership not represented
+  by the generic contract
 Stop:
-  Given a proposed API, workflow, or skill update, the agent produces a review
-  card with output artifact and stop check instead of only saying "looks good."
-
+  old workflows become simple calls; process trace, total wait, cancellation, and
+  failure are explicit; one transfer case fits without a new flag
 Decision:
-  keep with calibration gap if no realistic invocation has been run yet
-  revise-surface if the skill cannot say when to read each reference
-  revise-model if the review invariant or condition space is unclear
+  keep only if variation roles and process observers are genuinely shared;
+  otherwise split by product retry semantics
 ```
 
-## Provider Integration
-
-```text
-Candidate:
-  charge(provider, amount) as a generic operation
-
-Pressure:
-  Each new provider edits old switch statements and leaks provider fields.
-
-Layer:
-  Engine + Boundary
-
-Recipe:
-  Dispatch Registration, then Data Abstraction Boundary
+The helper is reviewable because its caller shape and three concrete sources
+already exist. If only duplication exists and the interface must still be
+invented, return to `signal` and `sketch`.
 
-Input artifact:
-  providers x operations table
-
-Derivation:
-  each current branch -> one (provider, operation) method cell
-
-Output artifact:
-  registerProvider(provider, { charge, refund })
-  charge(provider, amount)
-  unsupported refund policy
-
-Stop:
-  add fake provider without changing caller code
-
-Decision:
-  keep if unsupported cases are explicit; otherwise revise-surface
-```
-
-## Retry Helper From Repeated Movement
+## Provider Registry
 
 ```text
 Candidate:
-  withRetry(operation, shouldRetry, delayStrategy, maxAttempts)
-
+  registerProvider(kind, { charge, refund })
 Pressure:
-  Several request functions repeat the same movement: run operation, inspect
-  failure, wait, retry, eventually fail.
-
-Layer:
-  Language + Unit
-
-Recipe:
-  Movement Pattern Extraction, then Procedure -> Process Reality Check
-
-Input artifact:
-  cases:
-    fetchProfile, submitPayment, syncInventory
-  common movement:
-    attempt -> classify failure -> delay -> retry or give up
-  variation roles:
-    operation, shouldRetry, delayStrategy, maxAttempts
-
-Derivation:
-  common movement becomes the helper body
-  variation roles become parameters or strategy callbacks
-
-Output artifact:
-  withRetry signature
-  role table for existing cases
-  process note for total attempts and delay behavior
-
+  accepted providers repeatedly edit central dispatch
+Promise:
+  a provider can be added without changing old callers or provider modules
+Counterexample:
+  duplicate registration silently overwrites a provider based on load order
 Stop:
-  old cases are simple calls and a new retrying operation needs no new branch in
-  withRetry
-
+  fake provider addition plus explicit duplicate, unsupported, visibility, and
+  startup-failure behavior
 Decision:
-  keep if variation roles are stable; reject if each case has different
-  responsibility or product semantics
+  revise-surface until precedence and failure ownership are public; reject when a
+  local exhaustive conditional remains the cheaper truthful owner
 ```
 
-## Optional Default Semantics
+## Schedule Boundary
 
 ```text
 Candidate:
-  readConfig("timeout") returns configured timeout or fallback
-
+  Schedule.create(input), schedule.isActiveAt(epoch), schedule.summary()
 Pressure:
-  Missing values are handled differently by producers and consumers.
-
-Layer:
-  Law + Boundary
-
-Recipe:
-  Data Abstraction Boundary, then Meaning-Preserving Path
-
-Input artifact:
-  states: missing / null / empty / configured / legacy
-  owner: producer / constructor / consumer fallback
-
-Derivation:
-  decide which states preserve the same meaning and which are unsupported
-
-Output artifact:
-  absence/default policy:
-    missing means <x>
-    null means <y>
-    fallback owner is <layer>
-    consumer fallback is defensive unless explicitly owned
-
+  callers currently depend on tuple positions
+Promise:
+  callers rely on interval behavior, not representation fields
+Counterexample:
+  summary or membership is reimplemented outside the owner using raw fields
 Stop:
-  each state has one meaning, one enforcement layer, and one test target
-
+  object-slot and private-tuple implementations satisfy the same caller contract;
+  leak search finds no indexes, destructuring, or raw construction
 Decision:
-  revise-model if missing/null/legacy meanings are not decided yet
+  keep if only supported operations are public; reject field-alias getters that
+  hide no consequential choice
 ```
 
-## Symbolic Expression Rewrite
+## Stateful Account
 
 ```text
 Candidate:
-  simplify(expression)
-
+  account.withdraw(amount)
 Pressure:
-  Rewrite rules are tied to list indexes or string positions.
-
-Layer:
-  Language + Boundary
-
-Recipe:
-  Notation As Data, then Data Abstraction Boundary
-
-Input artifact:
-  expression cases: number, variable, sum, product
-
-Derivation:
-  cases -> predicates; parts -> selectors; new expressions -> constructors
-
-Output artifact:
-  isSum, addend, augend, makeSum
-  isProduct, multiplier, multiplicand, makeProduct
-
+  caller should not thread balance manually
+Promise:
+  local state is a sufficient summary of accepted transaction history
+Counterexample:
+  audit/replay or concurrent withdrawal is required but no event/order contract
+  exists
 Stop:
-  rewrite rules use selectors/constructors, not raw layout
-
+  owner, writers, identity, aliases, transition law, and concurrency scope match
+  admitted cases
 Decision:
-  keep after constructors own simplification policy; otherwise split policy
+  keep for bounded local history; revise-model when audit, replay, or concurrent
+  histories are product meaning
 ```
 
-## Stateful Account
+## Query Builder
 
 ```text
 Candidate:
-  makeAccount(initialBalance).withdraw(amount)
-
+  query.where(...).orderBy(...).limit(...).execute()
 Pressure:
-  Same method call can produce different results after previous calls.
-
-Layer:
-  Time
-
-Recipe:
-  History Placement
-
-Input artifact:
-  required history: transaction sequence
-  sufficient summary: current balance
-  interaction model: single actor or concurrent actors
-
-Derivation:
-  decide whether balance can be hidden local state or must be explicit stream/log
-
-Output artifact:
-  balance is hidden summary of accepted transactions
-  transaction log is required if audit/replay/collaboration matters
-
+  query transformations should compose
+Promise:
+  builder operations remain in the Query world
+Counterexample:
+  execute is treated as another Query while performing I/O and returning rows
 Stop:
-  caller contract states whether history is hidden or explicit
-
+  where/order/limit are Query -> Query; execute is an explicit finalizer with
+  failure and resource semantics
 Decision:
-  keep for single-actor local state; revise-model if concurrency/audit matters
-```
-
-If concurrent withdrawals appear, run Event Order Protection:
-
-```text
-order law:
-  read balance, decide sufficient funds, write new balance is one protected unit
-
-stop:
-  forbidden interleaving cannot violate balance invariant
+  keep after the finalizer boundary is visible
 ```
 
-## Chainable Builder
-
-```text
-Candidate:
-  query.where(...).orderBy(...).limit(...).execute()
-
-Pressure:
-  Most operations compose, but execute leaves the query world.
-
-Layer:
-  Unit + Boundary
-
-Recipe:
-  Closure Composition Unit
+## Calibration Boundary
 
-Input artifact:
-  query unit, closed operations, finalizers
+Do not select the example whose surface looks most similar. Select the one whose
+**promise and falsifier** match. If no case matches, use the field card directly
+or hand off; do not expand this file into another design catalog.
 
-Derivation:
-  mark where/orderBy/limit as Query -> Query
-  mark execute as Query -> Result
+## Source Trace
 
-Output artifact:
-  closed query builder vocabulary
-  explicit finalizer boundary
-
-Stop:
-  all builder operations return Query; execute is intentionally outside
-
-Decision:
-  keep if finalizer is not hidden as another closed operation
-```
+These are source-independent Developer calibration cases. Their review promises
+and counterexamples are derived from the sources traced in
+Abstraction Candidate Review. No example is a copied source API.

package/skills/model/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: model
-description: "Model the condition space behind a requirement, invariant, bug, policy, workflow, or code behavior using cases, predicates, rules, forbidden states, transitions, objectives, guarantee placement, and verification targets. Use when correctness depends on combinations, absence or default semantics, contracts, replacement, state, time, or policy interaction."
+description: "Model unresolved condition space behind a requirement, invariant, bug, policy, workflow, or code behavior using cases, predicates, rules, forbidden states, transitions, objectives, guarantee placement, and verification targets. Use when correctness depends on combinations, absence or default semantics, contracts, replacement, state, time, or policy interaction that must be settled before design. Supplied laws or invariants that only need an interface shape belong directly to sketch."
 ---
 
 # Model
@@ -11,6 +11,20 @@ Expose the condition space a valid implementation must satisfy.
 
 Which cases, rules, states, or transitions make the claim precise?
 
+## Judgment Spine
+
+```text
+unresolved uncertainty
+-> admitted domain and consequential distinctions
+-> rules, forbidden cases, and assumptions
+-> counterexamples and guarantee owners
+-> model artifact that constrains later design
+```
+
+Choose representation from the uncertainty, not from a favorite formal tool.
+Specialized references extend one modeling obligation; they do not turn the leaf
+into a catalog of solvers or languages.
+
 ## Inputs
 
 - Requirement, invariant, policy, workflow, or code behavior
@@ -61,10 +75,12 @@ states, transitions, or policy decisions invalidate the model.
 3. Separate facts, decisions, assumptions, properties, and helper predicates.
 4. Make missing, undefined, null, empty, legacy, and configured states explicit
    when absence matters. Name the policy owner and misplaced-default cases.
-5. Model transitions separately from current-state validity when order matters.
-6. Place each guarantee at the appropriate type, boundary, validation, test,
+5. Select one specialized model only when contract, relation, time, exhaustive
+   evidence, or search has an independent artifact and stop condition.
+6. State the ability lost and guarantee gained by the chosen representation.
+7. Place each guarantee at the appropriate type, boundary, validation, test,
    property, proof, model check, or human decision.
-7. Derive verification targets and the counterexample each target should catch.
+8. Derive counterexamples and verification targets without designing the API.
 
 ## Missing Evidence
 
@@ -76,15 +92,17 @@ Keep provisional rules visibly provisional.
 ## Boundary
 
 Do not decide product scope, design the implementation surface, schedule
-structural work, mutate artifacts, or make the final evidence judgment.
+structural work, mutate artifacts, or make the final evidence judgment. Words
+such as “law,” “invariant,” or “replacement” do not require a model route when
+the requirement already fixes their meaning and asks only for public operations,
+ownership, collaborators, or caller shape; route that original surface to
+`sketch`.
 
 ## Reference Routing
 
-Read [the problem-modeling reference](references/problem-modeling.md) for
-policy-heavy, stateful, optimization, safety-critical, or otherwise complex
-condition spaces.
-
-Read [the worked models and specialized techniques](references/worked-models-and-specialized-techniques.md)
-when a boolean policy, relational constraint, replacement, temporal rule, proof
-obligation, solver encoding, logic program, or plan needs a complete calibration
-example rather than the compact procedure alone.
+The machine-readable [reference policy](reference-policy.json) is the routing
+authority. Each route answers one modeling question, refines one judgment step,
+and declares its artifact, stop, and separation boundary. Prefer a specialized
+route over the broad condition-space fallback when it owns the unresolved
+obligation; combine routes only for independent model questions. Use the
+exemption only when no route trigger applies and cite its evidence.

package/skills/model/reference-policy.json

@@ -0,0 +1,96 @@
+{
+  "version": 2,
+  "routes": [
+    {
+      "id": "condition-space",
+      "question": "Which distinctions, rules, forbidden cases, assumptions, and guarantee owners define this condition space?",
+      "trigger": "Prose or isolated examples hide consequential combinations, quantifiers, absence/default meaning, ability-guarantee tradeoffs, or model/environment assumptions, and no specialized route below is primary.",
+      "method_step": "lower accepted language into the smallest sufficient domain, distinctions, predicates, forbidden cases, assumptions, owners, and counterexamples",
+      "references": ["references/problem-modeling.md"],
+      "artifacts": ["a bounded domain and distinction map", "explicit rules, forbidden cases, assumptions, and human-owned policy", "a guarantee-owner and counterexample map"],
+      "stop": "Every consequential distinction changes a rule, forbidden case, owner, or check, and no unsupported implementation surface has been invented.",
+      "separate_when": "A contract/replacement, relational, temporal, proof, solver, logic-query, or planning question has an independent artifact and stop; select that route."
+    },
+    {
+      "id": "contract-replacement",
+      "question": "Can the new contract replace the old one for the declared callers and observers?",
+      "trigger": "Caller/callee obligations, API or schema compatibility, old/new preconditions and postconditions, or observer-relative refinement are consequential.",
+      "method_step": "after defining the admitted domain, compare requires, ensures, failures, observers, and refinement mapping",
+      "read_order": "listed",
+      "references": ["references/problem-modeling.md", "references/contract-and-replacement-models.md"],
+      "artifacts": ["old and new contract relations", "precondition and postcondition implication results", "an observer set, refinement mapping, and excluded compatibility cases"],
+      "stop": "Every replacement obligation is supported, contradicted, or left as an explicit compatibility question for a named observer.",
+      "separate_when": "Adapters or migration surfaces must be designed, timing chosen, or compatibility evidence executed; hand off to sketch, schedule, or verify."
+    },
+    {
+      "id": "relational-constraints",
+      "question": "Which entity relationships and quantified constraints distinguish valid from invalid instances?",
+      "trigger": "Correctness depends on entities, intervals, cross-record integrity, quantified relations, bidirectional constraints, SQL translation, or set-versus-bag semantics.",
+      "method_step": "after defining domains, state decisions, properties, assumptions, quantified constraints, identity, multiplicity, and runtime translation obligations",
+      "read_order": "listed",
+      "references": ["references/problem-modeling.md", "references/relational-constraint-models.md"],
+      "artifacts": ["a relational domain and quantified constraint set", "known valid and invalid instances", "endpoint, null, multiplicity, mutation, and contradiction policy"],
+      "stop": "Known valid and invalid instances differ for the modeled reason and runtime translation obligations are explicit.",
+      "separate_when": "Histories rather than instances carry meaning, solver status is the claim, or an enforcement API must be designed."
+    },
+    {
+      "id": "temporal-behavior",
+      "question": "Which histories are allowed, forbidden, or required to make progress?",
+      "trigger": "Snapshots are insufficient because retry, stale or duplicate events, lifecycle, concurrency, safety, progress, stuttering, fairness, or temporal refinement matters.",
+      "method_step": "derive states, actions, guards, effects, frame conditions, representative traces, safety, progress, fairness, and observer mapping",
+      "read_order": "listed",
+      "references": ["references/problem-modeling.md", "references/temporal-behavior-models.md"],
+      "artifacts": ["a state/action relation with frame conditions", "valid, stale, duplicate, retry, reorder, and concurrent traces", "safety, progress, stuttering, fairness, and refinement obligations"],
+      "stop": "Every consequential history is classified and each safety or progress claim has assumptions and a counterexample trace.",
+      "separate_when": "State ownership or event APIs must be designed, traces executed, or the task is finding one goal-directed plan."
+    },
+    {
+      "id": "proof-obligation",
+      "question": "What exact implementation claim follows from this specification, invariant, and proof argument?",
+      "trigger": "A deductive implementation-conformance claim needs preconditions, postconditions, invariant initialization/preservation/conclusion, termination, or arithmetic/tool assumptions.",
+      "method_step": "bind the claim to its specification, invariant, proof steps, termination argument, runtime model, trusted boundary, and omitted observers",
+      "read_order": "listed",
+      "references": ["references/problem-modeling.md", "references/proof-obligations.md"],
+      "artifacts": ["a specification and proof-obligation set", "initialization, preservation, conclusion, and termination evidence", "a narrowed claim and omitted-observer list"],
+      "stop": "The proof supports exactly the stated specification under explicit assumptions and every omitted observer is visible.",
+      "separate_when": "The evidence is bounded search or optimization status, or proof execution/relevance must be verified."
+    },
+    {
+      "id": "solver-result-boundary",
+      "question": "What exact claim follows from this bounded model or solver status?",
+      "trigger": "Bounded counterexample search, satisfiability, feasibility, optimization, scope/configuration, or solver result-state interpretation is consequential.",
+      "method_step": "bind status to variables, domains, constraints, objective, equivalence, bound, encoding assumptions, satisfiable witness, and unmodeled observers",
+      "read_order": "listed",
+      "references": ["references/problem-modeling.md", "references/solver-result-boundaries.md"],
+      "artifacts": ["a solver encoding and scope", "a satisfiable witness and exact result status", "a narrowed bounded/feasible/optimal claim and residual"],
+      "stop": "The reported claim is no broader than the encoding, bound, witness, and exact result state.",
+      "separate_when": "The task is deductive proof, query-answer semantics, action planning, or tool execution relevance."
+    },
+    {
+      "id": "logic-query-semantics",
+      "question": "What do answers, empty results, duplicates, negation, and search completion mean for this query?",
+      "trigger": "Facts/rules, zero-one-many answers, proof multiplicity, duplicates, negation-as-failure, binding order, search fairness, cycles, or divergence are consequential.",
+      "method_step": "define answer/proof identity, duplicate and aggregation policy, negation, bindings, search order, outcomes, fairness, cycles, and termination",
+      "read_order": "listed",
+      "references": ["references/problem-modeling.md", "references/logic-query-semantics.md"],
+      "artifacts": ["a facts/rules/query model", "answer, proof, duplicate, negation, binding, and search semantics", "answer, no-answer, cycle, divergence, and completion cases"],
+      "stop": "Every observed empty/non-empty result has one interpretation relative to search completion, duplicates, negation, and termination.",
+      "separate_when": "The task is action planning, conclusive solver status, or design of the query language runtime."
+    },
+    {
+      "id": "planning-model",
+      "question": "Which legal action sequence reaches the goal while preserving the invariant, and what makes one plan preferred?",
+      "trigger": "Initial state, goal, legal actions, intermediate-state invariants, action costs, equivalent plans, or no-plan meaning is consequential.",
+      "method_step": "derive action guards/transitions, intermediate-state invariant, representative valid/invalid plan, objective, equivalence, and search-completeness boundary",
+      "read_order": "listed",
+      "references": ["references/problem-modeling.md", "references/planning-models.md"],
+      "artifacts": ["an initial/goal/action model", "a plan with every intermediate invariant check", "objective/equivalence and complete-versus-unknown no-plan semantics"],
+      "stop": "One valid and one invalid sequence are distinguishable and preferred/no-plan claims are relative to objective and search completeness.",
+      "separate_when": "The question is all allowed histories, relational query answers, solver optimality status, or planner runtime design."
+    }
+  ],
+  "exemption": {
+    "when": "The condition space is finite and direct enough for the SKILL.md judgment spine to expose every consequential distinction, rule, forbidden case, assumption, owner, and counterexample without a specialized model extension.",
+    "evidence": ["the bounded dimensions and admitted values", "the complete rule and forbidden-case surface", "the guarantee owners and counterexamples", "why no specialized model question has an independent artifact"]
+  }
+}