@hobin/developer 0.1.7 → 0.1.9

package/skills/signal/references/structural-movement.md

@@ -4,6 +4,10 @@ Use this reference when duplication, parallel branches, repeated tests, code
 smells, or a model-code mismatch suggests movement but does not yet justify an
 abstraction or implementation plan.
 
+It extends `signal` at comparison and falsification: choose one pair, expose one
+difference with one behavior-preserving observation move, then classify. It does
+not promote the resulting candidate or continue a refactoring sequence.
+
 ## Central Question
 
 What is actually moving in the evidence, and what smallest observation could
@@ -31,10 +35,12 @@ was appropriate for a previous requirement may become awkward only after new
 evidence arrives.
 
 A simple concrete implementation with temporary duplication can be a strong
-baseline when it is understandable and protected by relevant examples. Visible
-duplication without current pressure is not an instruction to refactor. Return
-`no-signal` when the behavior is cheap to change and no accepted claim is being
-inhibited.
+baseline when it is understandable and protected by relevant examples. Before
+simplifying parallel cases, ask whether the data definition and problem model are
+stable enough that the repeated responsibilities are known; model discrepancy is
+not abstraction evidence. Visible duplication without current pressure is not an
+instruction to refactor. Return `no-signal` when the behavior is cheap to change
+and no accepted claim is being inhibited.
 
 ## Select The Comparison
 
@@ -68,7 +74,34 @@ Revealing result: what would support or reject the suspected structure
 ```
 
 If the relevant evidence is missing, return `needs-evidence`. Do not rewrite
-tests merely so a proposed refactor can remain green.
+tests merely so a proposed refactor can remain green. “Behavior-preserving” must
+name the relevant semantics: reassociation, traversal order, effects, failure
+versus divergence, or a new complexity class can make an apparently structural
+alignment observable.
+
+## Catalog Moves Are Experiments
+
+Use familiar tidyings as candidate observation moves, not automatic cleanup:
+
+- flatten a nested condition to a guard only when the condition governs all of
+  the remaining body and return/failure behavior is equivalent;
+- delete suspected dead code only after static and scoped runtime evidence;
+  silence in telemetry is bounded negative evidence, not proof of absence;
+- normalize one symmetry only when representational difference does not encode a
+  product, ordering, or failure difference;
+- introduce a wished interface over the old implementation as a reversible
+  compatibility seam, not as proof of a durable public abstraction;
+- change reading or cohesion order only while preserving declaration, data, and
+  evaluation dependencies;
+- introduce explaining names or explicit parameters only after the represented
+  meaning and effect boundary are understood;
+- chunk or extract when purpose and interaction are bounded, but inline toward
+  one pile when fragmentation itself hides the process;
+- preserve a nonredundant comment when code cannot carry the reason, external
+  constraint, or known coupling honestly.
+
+Each move must end in a locally explainable comparison. The catalog does not
+supply the accepted pressure, verifier, or next destination.
 
 ## Horizontal Movement
 
@@ -81,7 +114,9 @@ Classify movement as horizontal when alignment stays at the current level:
 
 A stable landing is useful evidence: the code is green, understandable, safe to
 pause, and newly comparable. It is not permission to continue toward a
-predetermined design. Re-select the closest pair from the new state.
+predetermined design. A structural template may expose more selectors or
+recursive candidates than the completed purpose needs; an explicit purpose-based
+omission is not missing movement. Re-select the closest pair from the new state.
 
 ## Vertical Movement
 
@@ -126,6 +161,31 @@ accepted model with the implementation for:
 Use a behavior-preserving movement only to expose the mismatch. When satisfying
 the model requires changed behavior, keep that behavior change explicit.
 
+## Change-Relative Coupling And Cohesion
+
+Do not report two elements as simply “coupled.” Name the accepted or historically
+observed delta and direction:
+
+```text
+change delta:
+source element and required change:
+dependent element and why it must also change:
+fanout or cascade:
+evidence: contract, repeated accepted diff, compatibility rule, or trace
+counterevidence: tooling, generated code, shared owner, or accidental batching
+```
+
+Files appearing together in commits are a clue, not proof: formatting, broad
+pull requests, ownership, and generated output can create false co-change.
+Conversely, runtime capacity or deployment assumptions can couple elements with
+no source dependency.
+
+Moving change-related elements adjacent is horizontal cohesion movement. It can
+make a change set easier to see without eliminating the coupling. Report a
+vertical candidate only when repeated deltas reveal a stable containing unit,
+policy, or invariant owner. Do not infer cohesion from proximity alone or create
+one giant container for every transitive relationship.
+
 ## Worked Observation
 
 Baseline: tests protect verses 1, 2, and 0 in a simple formatter. A new accepted
@@ -190,13 +250,26 @@ The capability is being misused when:
 ## Source Trace
 
 - Sandi Metz, Katrina Owen, and TJ Stankus, *99 Bottles of OOP*, Second
-  Edition, version 2.2.2, 2024: chapters 1-4 on Shameless Green, listening to
-  change, points of attack, flocking, concentrating on difference, horizontal
-  movement, and stable landings.
+  Edition, version 2.2.2, 2024: Chapter 1, pp. 2-22; Chapter 2, pp. 23-50;
+  Chapter 3, pp. 51-72; and Chapter 4, pp. 73-101, on Shameless Green,
+  listening to change, points of attack, flocking, concentrating on difference,
+  horizontal movement, and stable landings.
 - Matthias Felleisen, Robert Bruce Findler, Matthew Flatt, and Shriram
-  Krishnamurthi, *How to Design Programs, Second Edition*, MIT Press, 2018:
-  deriving abstractions by comparing completed concrete designs and lifting
-  corresponding differences.
+  Krishnamurthi, *How to Design Programs*, official living build 9.2.0.3,
+  released 2026-05-28 and audited 2026-05-28:
+  Chapter 14
+  and Chapter 15
+  for comparing completed concrete designs and lifting corresponding roles;
+  Chapter 19
+  and Chapter 20
+  for stabilizing a data model before simplification; and
+  Intermezzo 5
+  for duplicated-work and hidden-traversal cost signals.
 - Kent Beck, *Tidy First?: A Personal Exercise in Empirical Software Design*,
-  O'Reilly Media, 2023: small behavior-preserving structural moves and the need
-  to keep them separate from behavior changes.
+  First Edition, Second Release, O'Reilly Media, 2025-12-12:
+  Part I, Chapters 1-15, pp. 3-32, for small catalog-shaped observation moves;
+  Part II, Chapters 16-18, pp. 35-46, for behavior/structure separation,
+  chaining, and batch interactions; and Part III, Chapters 29-32, pp. 77-90,
+  for change-relative coupling, fanout/cascades, and cohesion movement. Commit
+  co-change, power-law cost, tool-constant fanout, and universal collocation are
+  qualified rather than imported as laws.

package/skills/sketch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sketch
-description: "Shape an implementable design surface from a requirement, invariant, problem model, existing code, or representative cases using data definitions, templates, wished interfaces, collaborations, checks, and a small implementation queue. Use when ownership, boundaries, data flow, recursion, state, composition, responsibility, variation, or implementation shape remains unresolved."
+description: "Shape an implementable design surface from a requirement, invariant, problem model, existing code, or representative cases using data definitions, templates, wished interfaces, collaborations, checks, and a small implementation queue. Use when ownership, boundaries, data flow, recursion, state, composition, responsibility, variation, or implementation shape remains unresolved. Prefer sketch when caller-facing operations or collaborations still need to be invented; review a candidate only after that concrete surface exists."
 ---
 
 # Sketch
@@ -11,6 +11,21 @@ Turn accepted intent into an implementable design surface.
 
 What design surface makes this intent implementable?
 
+## Judgment Spine
+
+```text
+accepted intent and cases
+-> data/state/ownership facts
+-> one unresolved design question
+-> wishful caller-visible surface
+-> contract, owner, hidden detail, and falsifier
+-> first executable item + explicit handoffs
+```
+
+A reference extends one arrow in this spine. It must not contribute unrelated
+insights merely because they share a book or broad topic. If a question has its
+own artifact and stop, select or create a separate route.
+
 ## Inputs
 
 - Requirement, invariant, or problem model when available
@@ -20,40 +35,13 @@ What design surface makes this intent implementable?
 
 ## Reference Routing
 
-Read [the data-driven design reference](references/data-driven-design.md) when
-the information model, data variants, traversal, recursion, examples, or tests
-should determine the function skeleton. Read it when a proposed sketch jumps
-from prose to helpers without deriving cases and a template from the data.
-
-Within that capability, read [the data-shape template catalog](references/data-shape-template-catalog.md)
-when atomic, itemized, structured, recursive, intertwined, multi-input, output,
-or interactive data must derive a template. Read
-[composition, generative recursion, and accumulators](references/composition-generative-recursion-and-accumulators.md)
-for wished auxiliaries, abstraction from completed functions, generated
-subproblems and termination, or an invariant-bearing accumulator.
-
-Read [the abstraction, composition, and state reference](references/abstraction-composition-and-state.md)
-when wishful top-level design, representation independence, abstraction
-barriers, compositional interfaces, module assumptions, environmental process
-boundaries, state/history ownership, or levels of language carry consequential
-judgment.
-
-Within that capability, read [abstraction barriers and closure](references/abstraction-barriers-and-closure.md)
-for a representation or combination boundary,
-[processes, state, and time](references/processes-state-and-time.md) for runtime
-shape, history, identity, streams, concurrency, or order, and
-[generic operations and languages](references/generic-operations-and-languages.md)
-for additive representations, coercion, symbolic data, a DSL, or an evaluator.
-
-Read [the responsibility and variation reference](references/responsibility-and-variation.md)
-when real change pressure exposes repeated arguments, data clumps, conditional
-dispatch, misplaced knowledge, role substitution, object creation, factory
-tradeoffs, or test-unit boundaries.
-
-Read multiple references only when their questions genuinely combine: for
-example, data shape may derive the operational skeleton while abstraction and
-responsibility evidence determine its boundaries. A small local design whose
-purpose, cases, data flow, and first item are already clear needs none.
+The machine-readable [reference policy](reference-policy.json) is the routing
+authority. Each route answers one narrower design question and declares the
+judgment step, artifact, stop, and separation boundary it owns. Select a narrow
+route instead of its fallback; select several only when each produces an
+independent artifact needed by the same sketch. A co-required set means every
+member is necessary for that route's one result, not that the documents share a
+subject. Use the exemption only when no trigger applies and cite its evidence.
 
 ## Output
 
@@ -101,16 +89,19 @@ data-flow assumptions.
 2. State the design unit's purpose in the user's language.
 3. Derive relevant data or state definitions and their ownership pressure.
 4. List representative cases before choosing code shape.
-5. Derive the template from data, state, traversal, or ownership flow.
-6. Write wishful top-level code, pseudocode, or interaction flow in a fenced
+5. Name each independently unresolved design question and select only its routed
+   extension; keep disputed meaning in `model`.
+6. Derive the needed template, composition, generation, invariant, level,
+   process, state, dispatch, language, or responsibility artifact.
+7. Write wishful top-level code, pseudocode, or interaction flow in a fenced
    code block. Show every wished interface in context rather than merely naming
    helpers in prose.
-7. For each wished interface, state its purpose, contract, owner, hidden detail,
+8. For each wished interface, state its purpose, contract, owner, hidden detail,
    and representative stop check in a table.
-8. Draw the smallest inline map that exposes non-trivial data flow,
+9. Draw the smallest inline map that exposes non-trivial data flow,
    collaboration, state movement, or ownership boundaries.
-9. Separate design artifacts, implementation items, and deferred candidates.
-10. Keep the queue small; do not turn the sketch into a project plan.
+10. Separate design artifacts, implementation items, candidate reviews, and
+    deferred questions. Keep the implementation queue small.
 
 ## Missing Evidence
 
@@ -123,4 +114,9 @@ assumptions.
 ## Boundary
 
 Do not own product scope, decide model correctness, promote an abstraction,
-schedule structural timing, implement the change, or verify completion.
+schedule structural timing, implement the change, or verify completion. Creating
+an original public operation set, representation boundary, ownership map, or
+caller shape belongs here even when replacement pressure motivates it. Route
+`abstraction-review` only after a concrete caller-facing candidate exists; route
+`model` first only when unresolved cases or rules can materially change the
+surface.

package/skills/sketch/reference-policy.json

@@ -0,0 +1,212 @@
+{
+  "version": 2,
+  "routes": [
+    {
+      "id": "data-driven-design",
+      "question": "How do accepted data meanings and examples determine the first executable function surface?",
+      "trigger": "Product information, variants, examples, or tests should determine the function skeleton, and no narrower template, composition, generation, or accumulator question is primary.",
+      "method_step": "derive data definition, interpretation, examples, purpose, template, completed shape, and first executable item",
+      "references": ["references/data-driven-design.md"],
+      "artifacts": ["the six ordered design artifacts", "repository contradictions mapped to those artifacts", "a bounded first item and propagation check"],
+      "stop": "Accepted data and behavior examples constrain an executable skeleton with contradictions and compatibility visible.",
+      "separate_when": "Template shape, composition, earned abstraction, generated problems, or accumulated knowledge has an independent artifact."
+    },
+    {
+      "id": "data-shape-template",
+      "question": "Which branches, selectors, recursive calls, and delegations follow from this accepted data shape?",
+      "trigger": "Atomic, interval, itemized, structured, recursive, intertwined, multi-input, complex-output, or interactive data must determine the structural template.",
+      "method_step": "after data meaning/examples, derive one position for every accepted clause, field, self-reference, or delegated reference",
+      "read_order": "listed",
+      "references": ["references/data-driven-design.md", "references/data-shape-template-catalog.md"],
+      "artifacts": ["the six design artifacts", "a data-corresponding template", "purpose-based omissions and first mismatch diagnosis"],
+      "stop": "Every template position corresponds to accepted data and every omission follows from purpose.",
+      "separate_when": "Calls are generated rather than structurally selected, traversal needs carried knowledge, or input relations remain policy."
+    },
+    {
+      "id": "composition-by-wishes",
+      "question": "Which independently meaningful operations compose this accepted result?",
+      "trigger": "One accepted purpose contains several separately nameable subproblems with composable intermediate results.",
+      "method_step": "after the base recipe, write top-level wished composition and design each subproblem purpose, contract, examples, and template",
+      "read_order": "listed",
+      "references": ["references/data-driven-design.md", "references/composition-by-wishes.md"],
+      "artifacts": ["a top-level wished composition", "independent subproblem contracts/templates", "intermediate compatibility and first composable slice"],
+      "stop": "Each operation is independently designable/checkable and the composition hides no incompatible order, effect, or failure boundary.",
+      "separate_when": "The question is shared roles across completed designs, generated problems, carried knowledge, process, or state."
+    },
+    {
+      "id": "earned-abstraction",
+      "question": "Which stable variation roles emerge from several completed correct designs?",
+      "trigger": "At least two completed designs with stable purposes/data models expose aligned common movement and possible variation roles.",
+      "method_step": "align completed designs and roles, test migration, transfer, and semantic/process observers, then return a candidate",
+      "read_order": "listed",
+      "references": ["references/data-driven-design.md", "references/earned-abstraction.md"],
+      "artifacts": ["completed-design alignment", "a variation-role table and candidate interface", "migration, transfer, observer, and deferred-promotion checks"],
+      "stop": "Migrated old designs are simple clients, one transfer fits, and the result is handed to abstraction review rather than approved here.",
+      "separate_when": "Only horizontal similarity exists, model meaning is unstable, or a single purpose merely needs decomposition."
+    },
+    {
+      "id": "generative-recursion",
+      "question": "How are new problem instances generated, related to the original, combined, and proven to progress?",
+      "trigger": "Recursive calls are computed by an algorithm idea rather than immediate data fields, including numeric, randomized, divide-and-conquer, or backtracking processes.",
+      "method_step": "derive trivial cases, generation, preservation, combination, progress, traces, and failure/divergence semantics",
+      "read_order": "listed",
+      "references": ["references/data-driven-design.md", "references/generative-recursion.md"],
+      "artifacts": ["generation and preservation relations", "a branchwise progress measure or divergence boundary", "machine/random/search limits"],
+      "stop": "Every generated branch has correctness and progress evidence; failure, exhaustion, error, and divergence are distinct.",
+      "separate_when": "Calls follow data fields, the issue is accumulated knowledge, or search policy remains a model question."
+    },
+    {
+      "id": "accumulator-invariant",
+      "question": "What lost knowledge or repeated work should traversal carry, and what invariant determines its updates?",
+      "trigger": "Traversal recomputes work, loses original/path context, requires provenance/visited/cache knowledge, or needs a sufficient summary.",
+      "method_step": "state the original/current/accumulated relation before selecting argument, closure, field, branch, frontier, global, or result ownership",
+      "read_order": "listed",
+      "references": ["references/data-driven-design.md", "references/accumulator-invariants.md"],
+      "artifacts": ["an invariant determining initial/update/result", "a trace and ownership choice", "semantic and resource delta checks"],
+      "stop": "The invariant explains initial, step, and final states and every semantic/resource delta is explicit.",
+      "separate_when": "Problems are generated, carried data is persistent product history, or a concrete cache surface needs review."
+    },
+    {
+      "id": "design-levels",
+      "question": "Which vocabulary, owner, and dependency direction make this caller contract truthful?",
+      "trigger": "The sketch must choose a level, owner, environment/interface boundary, hidden choice, or dependency direction, and no narrower route is primary.",
+      "method_step": "place wished operations, observers, owner, hidden mechanism, assumptions, drift, and replacement falsifier on explicit levels",
+      "references": ["references/design-levels-and-boundaries.md"],
+      "artifacts": ["a caller-purpose and level map", "contract/owner/hidden choice/assumptions", "an alternate implementation or falsifier"],
+      "stop": "Dependencies use truthful vocabulary, guarantees have owners, and lower-level change does not force unrelated callers.",
+      "separate_when": "Representation, closure, process, state, dispatch, conversion, language, runtime, responsibility, or variation has its own output."
+    },
+    {
+      "id": "representation-barrier",
+      "question": "Which public operations and laws hide this consequential representation choice?",
+      "trigger": "A domain value needs representation-independent constructors, selectors, predicates, operations, laws, replacement, or leak checks.",
+      "method_step": "after levels, derive supported public operations/laws, owner, two representations, caller rewrite, replacement, and leak search",
+      "read_order": "listed",
+      "references": ["references/design-levels-and-boundaries.md", "references/representation-barriers.md"],
+      "artifacts": ["a public domain vocabulary/law set", "two representations and one caller rewrite", "replacement and leak checks"],
+      "stop": "A materially different representation changes only the owner/adapters and callers use no raw primitive.",
+      "separate_when": "The issue is closure/finalizers, process, state, dispatch, language, or candidate promotion."
+    },
+    {
+      "id": "closure-interface",
+      "question": "Which operations keep results inside one composable unit, and which intentionally finalize outside it?",
+      "trigger": "A closure property, higher-order role, conventional interface, observer/finalizer split, or operational composition assumption is consequential.",
+      "method_step": "derive unit predicate, primitives, closed operations, finalizers, invalid combinations, role contracts, and interface assumptions",
+      "read_order": "listed",
+      "references": ["references/design-levels-and-boundaries.md", "references/closure-and-conventional-interfaces.md"],
+      "artifacts": ["a composition-unit and closed-operation table", "explicit observers/finalizers", "higher-order/conventional-interface operational checks"],
+      "stop": "Closed operations build required larger units, finalizers are explicit, and stages agree on operational semantics.",
+      "separate_when": "The issue is raw representation, process-resource behavior, or a language evaluator."
+    },
+    {
+      "id": "process-resources",
+      "question": "What work, control, waits, capacity, lifetime, and completion process does this surface generate?",
+      "trigger": "Correctness depends on work, continuation/tail position, stack/queue/buffer cost, paused dependencies, overload, lazy acquisition, retention, acknowledgment, cancellation, or bounds without product history being primary.",
+      "method_step": "trace work, control, waits, capacity, roots, release, phases, acknowledgment, and failure ownership",
+      "read_order": "listed",
+      "references": ["references/design-levels-and-boundaries.md", "references/process-shape-and-resources.md"],
+      "artifacts": ["a process/continuation trace", "wait/capacity/root/release ownership", "phase/acknowledgment/retry/cancellation boundaries"],
+      "stop": "Work, control, wait, capacity, lifetime, failure, and completion are owned and bounded for one honest step.",
+      "separate_when": "History/order defines product meaning, or the process is specifically a language runtime convention."
+    },
+    {
+      "id": "state-history-order",
+      "question": "Which history, identity, transition, and order laws must the design own?",
+      "trigger": "Correctness depends on prior interactions, identity, aliases, mutation, transitions, stale/duplicate/reordered/concurrent events, atomicity, streams, logs, replay, or demand history.",
+      "method_step": "derive required history, sufficient summary, owner/writers, transitions, order law, aliases, and stream/log observers",
+      "read_order": "listed",
+      "references": ["references/design-levels-and-boundaries.md", "references/state-history-and-order.md"],
+      "artifacts": ["a history/summary relation", "states/events/transitions/identity/order law", "stale/duplicate/retry/stream/log policy"],
+      "stop": "Every admitted history has an owner/transition explanation and identity, order, and log observers are explicit.",
+      "separate_when": "Allowed histories/fairness remain a model question, or only resource behavior without product history is unresolved."
+    },
+    {
+      "id": "generic-dispatch",
+      "question": "Which extension axis and dispatch owner support additive variants without hidden policy?",
+      "trigger": "Accepted representations must coexist through generic operations, data-directed dispatch, registration, or explicit unsupported capabilities.",
+      "method_step": "derive the variant-operation matrix, observed growth axis, dispatch owner, conflicts, precedence, load order, and extension checks",
+      "read_order": "listed",
+      "references": ["references/design-levels-and-boundaries.md", "references/generic-dispatch-systems.md"],
+      "artifacts": ["a variant-operation matrix and growth-axis decision", "dispatch/conflict/unsupported policy", "fake-row, new-column, and simpler-conditional checks"],
+      "stop": "Both axes and dispatch policies are explicit and the mechanism is no more powerful than current pressure requires.",
+      "separate_when": "The task is semantic conversion, role/creation ownership, or executable language notation."
+    },
+    {
+      "id": "meaning-preserving-conversion",
+      "question": "Which conversion path preserves the observer required by this cross-representation operation?",
+      "trigger": "Mixed representation worlds need direct operation, coercion, canonicalization, explicit context, or rejection with visible precision/identity/order/capability loss.",
+      "method_step": "draw conversion paths and derive preserved observer, lost ability, ambiguity, cycle/termination, and unsupported policy per edge",
+      "read_order": "listed",
+      "references": ["references/design-levels-and-boundaries.md", "references/meaning-preserving-conversions.md"],
+      "artifacts": ["a conversion graph", "preserved/lost observer notes", "ambiguity, cycle, unsupported, and round-trip checks"],
+      "stop": "Every legal edge preserves the required observer and every loss, ambiguity, or unsupported path is explicit.",
+      "separate_when": "Preserved meaning is disputed or additive operation dispatch is independently required."
+    },
+    {
+      "id": "language-semantics",
+      "question": "What programs does this notation admit, and what do they mean?",
+      "trigger": "The design needs symbolic data, a DSL, query/workflow language, grammar, parser, evaluator, result/search shape, scope, order, effects, errors, or termination semantics.",
+      "method_step": "pass the language gate, then derive grammar, semantic representation, validation, evaluator/result/effect/error contract, and ordinary-data alternative",
+      "read_order": "listed",
+      "references": ["references/design-levels-and-boundaries.md", "references/language-semantics.md"],
+      "artifacts": ["a language gate and ordinary-data alternative", "grammar/representation/validation", "an evaluator/result/effect/error contract"],
+      "stop": "Representative and invalid programs have explainable syntax, meaning, result shape, effects, and failure.",
+      "separate_when": "Lowering, compilation, calling convention, roots, or optimization is independently consequential, or search policy is unresolved."
+    },
+    {
+      "id": "runtime-compilation",
+      "question": "How does this runtime or compiler preserve the accepted language observers?",
+      "trigger": "An accepted language needs interpreter/VM/compiler lowering, calling convention, effect summaries, optimization guards, tail-space, roots, release, or mixed execution.",
+      "method_step": "after language semantics, derive execution convention, live state, effects, guards/fallback, roots/release, and interoperation",
+      "read_order": "listed",
+      "references": ["references/design-levels-and-boundaries.md", "references/language-semantics.md", "references/runtime-and-compilation.md"],
+      "artifacts": ["an execution/calling convention", "effect summaries and optimization guards", "tail-space, roots, release, and interoperation checks"],
+      "stop": "Nested calls and optimized fragments preserve accepted observers under guards with complete enough roots/release/interoperation.",
+      "separate_when": "Program meaning is unsettled or the process is an ordinary non-language execution boundary."
+    },
+    {
+      "id": "responsibility-collaboration",
+      "question": "Which owner and messages make this accepted change local without participant or navigation leaks?",
+      "trigger": "A real change exposes repeated arguments, data clumps, misplaced knowledge, feature envy, navigation leaks, participant assumptions, or responsibility-focused test pressure.",
+      "method_step": "inventory current knowledge/decisions/coordination, then derive wished messages, one coherent owner, participant assumptions, and collaboration boundary",
+      "references": ["references/responsibility-and-collaboration.md"],
+      "artifacts": ["a responsibility inventory and point of attack", "wished messages and candidate owner", "participant/assumption/navigation/evidence checks"],
+      "stop": "The representative change is local to a coherent owner and callers need no unrelated context or participant internals.",
+      "separate_when": "Role substitution/creation is independently unresolved, meaning is disputed, only movement is visible, or the candidate needs review."
+    },
+    {
+      "id": "variation-role",
+      "question": "Which shared caller role supports these accepted implementations?",
+      "trigger": "Accepted variants may share caller messages, substitution obligations, effects, failures, or unsupported cases.",
+      "method_step": "derive the caller role, implementation preconditions/results/failures/effects, unsupported policy, transfer case, and direct-conditional alternative",
+      "references": ["references/variation-roles.md"],
+      "artifacts": ["a role/implementation contract", "substitution and unsupported-case checks", "a transfer implementation and direct-conditional alternative"],
+      "stop": "Every admitted implementation substitutes for declared observers and one transfer fits without caller type tests or flags.",
+      "separate_when": "Type transition, selection/creation, responsibility ownership, generic dispatch, compatibility meaning, or candidate promotion is independently unresolved."
+    },
+    {
+      "id": "type-transition",
+      "question": "How does this accepted event transform one domain type into another while preserving meaning?",
+      "trigger": "An operation or event changes a source domain type into a target type with consequential preserved, consumed, retained, terminal, or failure semantics.",
+      "method_step": "derive source/event/target, preconditions, preserved meaning, consumed/retained facts, boundary behavior, failure, and construction owner",
+      "references": ["references/type-transitions.md"],
+      "artifacts": ["a source-event-target contract", "preserved/consumed/retained fact map", "terminal, failure, and construction-owner checks"],
+      "stop": "Every accepted source state has one explicit target or failure meaning and preserved facts do not depend on representation coincidence.",
+      "separate_when": "Shared role, target selection/creation, or temporal ordering among transitions is independently unresolved."
+    },
+    {
+      "id": "selection-creation",
+      "question": "Which owner and least-powerful mechanism should select and construct this variant?",
+      "trigger": "Accepted work needs conditional/ordered selection, object creation, factory/mapping/registration/discovery choice, or creation at the composition edge.",
+      "method_step": "derive variants/selection input, owner, overlap/precedence/conflicts, unsupported/load-order policy, and mechanism continuum",
+      "references": ["references/selection-and-creation.md"],
+      "artifacts": ["a selection-owner and conflict policy", "a creation-mechanism comparison", "fake-variant, startup-failure, and deferred-openness checks"],
+      "stop": "Selection has one owner and the creation mechanism is no more open or operationally powerful than accepted pressure requires.",
+      "separate_when": "The caller role, responsibility boundary, full generic-operation matrix, or candidate promotion is independently unresolved."
+    }
+  ],
+  "exemption": {
+    "when": "The local purpose, cases, data flow, ownership, caller skeleton, checks, and first item are explicit, and no routed judgment has an independent artifact.",
+    "evidence": ["accepted intent and cases", "existing caller surface and owner map", "bounded first item and checks", "why every judgment extension is non-consequential"]
+  }
+}

package/skills/sketch/references/accumulator-invariants.md

@@ -0,0 +1,125 @@
+# Accumulator Invariants
+
+Use this reference when traversal loses knowledge needed later, repeats work, or
+requires an explicit summary of the processed and remaining problem.
+
+## Pressure Before Parameter
+
+Do not start by adding an argument. Name the pressure:
+
+- prior work is recomputed;
+- an answer must be built in an order the natural return path cannot provide;
+- branch-local provenance or visited knowledge is required;
+- a tail-position process needs a sufficient summary;
+- a cached fact must remain consistent with the represented value.
+
+An extra parameter without a stated meaning is hidden state.
+
+## Invariant First
+
+Write a relation among original input, current remainder, and accumulated
+knowledge:
+
+```text
+original meaning
+= combine(processed meaning, remaining meaning)
+```
+
+For reverse:
+
+```text
+original == reverse(seenReversed) ++ remaining
+```
+
+Trace it:
+
+```text
+original [a,b,c], remaining [a,b,c], seenReversed []
+original [a,b,c], remaining [b,c],   seenReversed [a]
+original [a,b,c], remaining [c],     seenReversed [b,a]
+original [a,b,c], remaining [],      seenReversed [c,b,a]
+```
+
+The invariant determines initialization, transition, and result.
+
+## Three Obligations
+
+1. **Initial:** identity values make the relation true before work.
+2. **Preserve:** every structural or generated branch updates all related values
+   so the relation remains true.
+3. **Conclude:** the base condition plus the invariant implies the public result.
+
+If one branch cannot preserve the relation, revise the invariant or the ownership
+of accumulated knowledge rather than patching the update.
+
+## Ownership Forms
+
+Choose the smallest truthful owner:
+
+- helper argument for traversal-local context;
+- closure for stable original context;
+- data field for cached facts behind a closed update boundary;
+- branch-local value for path provenance;
+- frontier or global structure for graph search;
+- threaded result when one branch consumes another branch's output.
+
+Path-local, frontier, and global visited sets are not interchangeable. A public
+wrapper should hide private accumulator states when only one initialization
+satisfies the public contract.
+
+## Semantic And Resource Delta
+
+An accumulator transformation may change:
+
+- arithmetic association and floating-point result;
+- item or branch order;
+- failure versus divergence;
+- totality on previously failing inputs;
+- tail position and stack usage;
+- lookup complexity and retained memory;
+- cache consistency and alias behavior.
+
+Treat optimization, totality repair, and behavior preservation as different
+claims. Verify the observer each claim names.
+
+## Artifact
+
+```text
+Observed lost knowledge or repeated work:
+Original / current / accumulated relation:
+Identity initialization:
+Transition and preservation explanation:
+Base condition and conclusion:
+Accumulator owner and visibility:
+Representative trace:
+Arithmetic/order/failure/space delta:
+Public wrapper and checks:
+```
+
+## Stop And Separation
+
+Stop when the invariant mechanically determines initialization, update, and
+result, and the semantic/resource delta is explicit.
+
+Use `generative-recursion` when next problems are algorithmically produced,
+`state-history-and-order` when accumulated knowledge is persistent product
+history, and `abstraction-review` only after a concrete accumulator interface or
+cached representation exists to judge.
+
+## Source Trace
+
+- Matthias Felleisen, Robert Bruce Findler, Matthew Flatt, and Shriram
+  Krishnamurthi, *How to Design Programs*, living build 9.2.0.3:
+  Chapter 31,
+  Chapter 32,
+  Chapter 33,
+  and Chapter 34
+  for accumulator pressure, invariants, wrappers, ownership variants, cached
+  fields, provenance, and accumulator-as-result designs.
+- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
+  Interpretation of Computer Programs*, Second Edition:
+  Section 1.2
+  and Section 5.4.2
+  for process shape, continuation placement, and tail-space behavior.
+- Machine-resource gates, visited-scope taxonomy, and production cache checks are
+  Developer adaptations of those invariant and process boundaries.