@hobin/developer 0.1.8 → 0.1.10

package/skills/model/references/contract-and-replacement-models.md

@@ -0,0 +1,112 @@
+# Contract And Replacement Models
+
+Use this reference after the general problem model when the unresolved question
+is what callers may require, what implementations must guarantee, or whether a
+new implementation can replace an old one for a declared observer.
+
+## Contract Relation
+
+Model a callable or boundary as:
+
+```text
+requires: facts the caller establishes
+ensures: facts successful execution guarantees
+invariant: facts preserved through relevant internal steps
+failure: admitted error outcomes and when they become observable
+observers: value, effects, order, errors, resource behavior, persisted/public form
+```
+
+Composition is an implication check. If `A` calls `B`, facts established by `A`
+must imply `B.requires`, and `B.ensures` must establish what the rest of `A`
+needs. Locally correct contracts can still fail at their seam.
+
+## Replacement Relation
+
+For existing callers, require at least:
+
+```text
+old.requires => new.requires
+new.ensures  => old.ensures
+```
+
+The new implementation must not demand more from old callers or promise less.
+Apply the same relation to error behavior and every declared observer. Passing
+old examples is sufficient only when those examples completely express the
+chosen contract, which is uncommon.
+
+For representation changes, write an abstraction or refinement mapping:
+
+```text
+new representation/state/behavior
+-> old abstract meaning observed by callers
+```
+
+Every relevant new behavior must map to an admitted old behavior. Intermediate
+states matter when callers can observe them.
+
+## Ability And Guarantee Check
+
+A narrower enum, schema, or result type may strengthen guarantees while rejecting
+previously valid input. Record:
+
+```text
+old admitted ability:
+new restriction:
+guarantee gained:
+old caller or stored value excluded:
+explicit migration or breaking scope:
+```
+
+Do not hide a breaking change behind the word `validation`.
+
+## Compatibility Beyond The Logical Contract
+
+Actual systems may depend on behavior never written into the contract. Inspect:
+
+- real callers and built consumers;
+- persisted and serialized legacy forms;
+- failure types and timing;
+- ordering, effects, and resource observers;
+- telemetry only as bounded evidence, never proof of absence;
+- public documentation and known bugs that became de facto behavior.
+
+Migration, rollout, coexistence, telemetry, and rollback protocols are Developer
+adaptations. This model names their obligations but does not claim a source book
+supplies a production procedure.
+
+## Artifact
+
+```text
+Old requires / ensures / failures:
+New requires / ensures / failures:
+Declared observers:
+Precondition implication:
+Postcondition implication:
+Refinement mapping:
+Excluded old inputs or behaviors:
+Actual caller and persistence evidence:
+Compatibility decision or open policy:
+Verification targets:
+```
+
+## Stop And Separation
+
+Stop when every implication is supported, contradicted, or left as an explicit
+compatibility question, and the observer set is named.
+
+Hand off to `sketch` when adapters or a new boundary must be designed, to
+`schedule` when migration timing is the question, and to `verify` when the model
+exists but evidence for compatibility is missing.
+
+## Source Trace
+
+- Hillel Wayne, *Logic for Programmers*, v0.14.0:
+  Chapter 5, pp. 47-60, for contracts, composition, replacement, and accidental
+  observable behavior.
+- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
+  Interpretation of Computer Programs*, Second Edition:
+  Section 2.1
+  for abstraction mappings, representation laws, and observer-relative data
+  meaning.
+- The explicit production compatibility inventory is a Developer adaptation of
+  those semantic obligations.

package/skills/model/references/logic-query-semantics.md

@@ -0,0 +1,89 @@
+# Logic Query Semantics
+
+Use this reference when facts and relations can yield zero, one, or many answers
+and search behavior affects the meaning of an observed result.
+
+## Query Contract
+
+State:
+
+```text
+facts and derived rules
+query variables
+answer identity
+derivation or proof identity
+duplicate and aggregation policy
+negation meaning
+binding requirements
+search order, fairness, and cycle policy
+termination and resource bound
+outcome vocabulary
+```
+
+Different proofs may produce one domain answer. Decide whether aggregation uses a
+set, bag, or proof count.
+
+## Negation And Failure
+
+Negation-as-failure means the current knowledge base and search cannot derive the
+goal. It is not classical falsehood about the world. Require variables used by
+negation or host predicates to be bound when runtime meaning depends on binding
+order.
+
+Keep distinct:
+
+```text
+answer
+exhausted complete search
+bounded unknown
+timeout
+language/runtime error
+divergence before a later branch
+```
+
+Failure to observe an answer proves absence only after a complete search
+terminates conclusively.
+
+## Worked Shape
+
+```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)` must explain duplicate paths, cycles, answer identity,
+and completion.
+
+## Artifact
+
+```text
+Facts, rules, and query:
+Answer versus proof identity:
+Duplicate and aggregation policy:
+Negation and binding semantics:
+Search order, fairness, cycles, and termination:
+Outcome states:
+Known answer, duplicate, cycle, divergence, and no-answer cases:
+```
+
+## Stop And Separation
+
+Stop when every observed empty/non-empty result has one defined interpretation
+relative to search completion, duplicates, negation, and termination.
+
+Use `planning-models` for legal action sequences toward a goal,
+`solver-result-boundaries` for conclusive bounded status, and the `sketch`
+language-semantics route when the query runtime must be designed.
+
+## Source Trace
+
+- Hillel Wayne, *Logic for Programmers*, v0.14.0:
+  Chapter 12, pp. 156-168, for zero/one/many answers, duplicates, negation,
+  search, and answer sets. Recorded Prolog and exercise defects are excluded.
+- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
+  Interpretation of Computer Programs*, Second Edition,
+  Section 4.4
+  for proof multiplicity, search order, closed-world negation, fairness, and
+  termination.

package/skills/model/references/planning-models.md

@@ -0,0 +1,75 @@
+# Planning Models
+
+Use this reference when the unresolved model is a legal sequence of actions from
+an initial state to a goal, optionally ranked by cost.
+
+## Planning Contract
+
+```text
+initial state
+goal predicate
+legal actions and preconditions
+transition result
+state invariant
+optional action cost
+plan equivalence
+```
+
+Show every intermediate state. A plan is valid only when every action is enabled
+and every intermediate state preserves the invariant.
+
+## Valid Is Not Preferred
+
+A shortest plan under action count may not minimize risk, downtime, or version
+skew. State the encoded objective and acceptable equal optima. Changing the cost
+model can legitimately change the preferred plan without changing validity.
+
+Failure to find a plan proves impossibility only when a complete search terminates
+conclusively. Timeout, pruning, divergence, finite depth, or an omitted action
+produce unknown or model gaps.
+
+## Worked Shape
+
+```text
+state: servers with online/version
+initial: all online at version 1
+goal: all online at version 3
+invariant: at least one server online
+actions: takeOffline, upgrade, bringOnline
+cost: action count plus optional version-skew penalty
+```
+
+The artifact lists each intermediate state and checks the invariant before
+comparing costs.
+
+## Artifact
+
+```text
+Initial state and goal:
+Actions, guards, and transitions:
+State invariant:
+Representative plan with intermediate states:
+Invalid action or invariant-breaking plan:
+Cost/objective and equivalent optima:
+Search completeness and no-plan meaning:
+Omitted actions or environmental assumptions:
+```
+
+## Stop And Separation
+
+Stop when one valid and one invalid sequence are distinguishable, every
+intermediate state is checked, and preferred/no-plan claims are relative to the
+encoded objective and search completeness.
+
+Use `temporal-behavior-models` when the question is all allowed histories rather
+than one goal-directed sequence, `logic-query-semantics` for relational answer
+semantics, and `solver-result-boundaries` for proven optimal or unsatisfiable
+status.
+
+## Source Trace
+
+- Hillel Wayne, *Logic for Programmers*, v0.14.0:
+  Chapters 11-12, pp. 139-168, for constraint planning, action sequences,
+  objective functions, and result boundaries. Recorded beta defects are excluded.
+- The production rolling-upgrade example and operational risk objectives are
+  Developer adaptations; the source supplies the planning and search distinctions.