@hobin/developer 0.1.7 → 0.1.9

package/skills/abstraction-review/references/field-card.md

@@ -1,216 +1,161 @@
-# Abstraction Review Field Card
+# Abstraction Candidate Review
 
-Use this reference when a review should produce more than a paragraph of advice.
-The goal is to turn a wished abstraction into an artifact with a stop check.
+Use this reference when an already-shaped interface, helper, boundary, role,
+workflow rule, or structural unit needs an auditable keep/revise/split/reject/
+defer decision.
 
-## Contents
+This reference reviews a candidate. It does not create the original design,
+extract movement, settle product rules, or choose timing.
 
-- Operating Loop
-- Field Card
-- Source Modes
-- Good Wish Test
-- Recipe-Grade Gate
-- Layer Router
-- Minimal Output
-- Self-Application Check
-
-## Operating Loop
+## Judgment Spine
 
 ```text
-pressure
-  -> wish
-  -> layer
-  -> recipe card
-  -> output artifact
-  -> observable stop
-  -> repair decision
+concrete candidate and caller shape
+-> pressure it claims to remove
+-> promises callers would rely on
+-> evidence and counterexample
+-> observable stop
+-> keep | revise-surface | revise-model | split | reject | defer
 ```
 
-The wish opens freedom; the stop check brings the review back to evidence.
-Failure is not handled by a better name. Failure exposes a broken layer,
-contract, or missing artifact.
-
-Use [the recipe cards](recipe-cards.md) when the derivation rule is missing,
-[the repair table](repair-table.md) when the stop check fails, and
-[the worked examples](worked-examples.md) when a completed calibration case is
-needed. The field card remains the auditable summary; these files supply focused
-construction, repair, and examples.
+A polished name or familiar pattern is not evidence. Missing construction is a
+handoff, not an invitation for this review to absorb another skill.
 
-## Field Card
-
-Fill this card for serious reviews.
+## Candidate Field Card
 
 ```text
-Candidate:
-  What wished interface, helper, boundary, condition model, or abstraction is
-  being judged?
-
-Source and confidence:
-  Where did the candidate come from, and how strong is the evidence?
+Candidate and source:
+  exact current or wished surface; where it came from
 
 Pressure:
-  What complexity, repetition, variation, history, or representation detail is
-  this candidate supposed to remove?
-
-Wish:
-  In the better world, what would callers be able to say or do?
-
-Mismatch:
-  What currently breaks or might break that wish?
+  accepted change, repeated movement, invariant, participant, or representation
+  issue it is meant to remove
 
-Timing:
-  pre-implementation / post-implementation
+Caller contract:
+  operations, inputs, outputs, failures, effects, and observers
 
-Layer:
-  Language / Unit / Law / Boundary / Engine / Time / Run
-
-Recipe:
-  Which narrow card is being executed?
-
-Input artifact:
-  What concrete input must be written before judgment?
+Hidden detail:
+  representation, policy, creation, history, ordering, or process callers may
+  ignore
 
-Derivation:
-  How does that input constrain the output?
+Owner and assumptions:
+  owner of guarantees; environment facts required for usefulness
 
-Contract:
-  What can callers or future users rely on?
+Representative cases:
+  normal, boundary, forbidden, and transfer case
 
-Hidden detail:
-  What representation, policy, timing, history, cost, or process detail should
-  callers not depend on?
+Replacement or variation:
+  another implementation/caller/case the candidate claims to support
 
-Output artifact:
-  What table, graph, contract, invariant, trace, or decision remains?
+Counterexample:
+  smallest plausible case that would pass a superficial review while breaking
+  the promise
 
-Stop:
-  What observable check decides pass/fail?
+Stop check:
+  observable evidence that decides this review
 
 Evidence and gaps:
-  What evidence supports the decision, and what would change it?
+  callers, cases, code, tests, traces, costs, or human-owned policy
 
 Decision:
   keep / revise-surface / revise-model / split / reject / defer
 
-Open consequence:
-  What remains unresolved after this review?
+Open consequence and handoff:
 ```
 
-## Source Modes
-
-Use the candidate source to choose evidence and timing.
+## Review Promises
 
-| Source | Review pressure | Evidence to require |
-| --- | --- | --- |
-| design draft wished interface | Is the wish implementable and bounded? | caller contract, representative cases, hidden detail, planned stop |
-| structural observation | Is the movement real abstraction or local churn? | before/after diff, repeated movement, condition relation |
-| user-proposed API/helper | Is it domain language or implementation-shaped naming? | wished use, caller obligations, failure modes |
-| existing implementation | Does code still match the abstraction promise? | tests, trace, cost, call sites, hidden coupling |
-| skill/workflow update | Will future agents behave differently? | trigger wording, reference routing, realistic invocation |
+Select only promises the candidate actually makes.
 
-## Good Wish Test
+| Promise | Evidence required | Pass-but-wrong shape | Handoff when the surface is missing |
+| --- | --- | --- | --- |
+| caller language hides representation | two representations or a leak search | new type name with raw fields still required | `sketch` barrier design |
+| one responsibility owns a change | owner/message map and representative change | moved-method bag or generic service | `sketch` responsibility design |
+| several implementations share a role | pre/post/failure compatibility | subtype needs stronger preconditions or different effects | `model` contract/replacement |
+| composition remains in one value world | closed-operation and finalizer table | side effect disguised as chainable result | `sketch` closure design |
+| additive extension is supported | row/column and fake-variant evidence | registry hides precedence or load-order policy | `sketch` generic operations |
+| process remains truthful | trace, waits, cost, resource, failure ownership | same result with unbounded buffer or changed order | `sketch` process design |
+| state/history has one owner | transition and order evidence | enum without stale/duplicate policy | `model` or `sketch` state work |
+| name exposes stable sense | caller/audience/evolution evidence | rich word over unstable responsibility | `naming-judgment` |
 
-A wish is strong enough to review when it exposes a small language, not merely a
-preferred name.
+A candidate can make several promises, but each must be evaluated against the
+same caller contract. If the promises require independent surfaces or owners,
+that is split evidence.
 
-```text
-primitive words:
-  What operations can be trusted without re-opening implementation detail?
-
-means of combination:
-  How do smaller units produce larger valid units?
+## Stability Tests
 
-means of abstraction:
-  How is a repeated composition or method given a reusable handle?
-```
+A candidate is stable enough to keep only when:
 
-Reject or revise a wish when:
+- its pressure is current and observable;
+- callers can use its vocabulary without reopening hidden details;
+- the contract includes relevant effects, failures, order, and resources;
+- a realistic transfer case fits without flags that expose internals;
+- lost abilities are acceptable for current and credible callers;
+- the owner can enforce the promised invariant;
+- the stop check can fail the candidate rather than merely exercise it.
 
-- it only renames current representation shape;
-- it has no caller contract or failure mode;
-- its result cannot be composed or intentionally finalized;
-- no preserved meaning, invariant, or policy owner is visible;
-- it hides cost, history, order, or mutation that callers must understand.
+Bias toward `defer` when pressure is plausible but examples or participant
+independence are too weak. Choose `revise-model` when the candidate cannot be
+judged because admitted meaning is unsettled. Choose `revise-surface` when the
+meaning is accepted but the caller contract leaks or lies.
 
-## Recipe-Grade Gate
+## Separation Router
 
-A review is recipe-grade only when this sentence can be filled:
+Do not construct missing evidence inside this leaf:
 
 ```text
-Given <input artifact>,
-derive <output artifact>
-by <rule>,
-then check <observable stop>.
-If it fails, repair <layer, contract, or artifact>.
+no concrete caller-facing surface -> sketch
+unresolved product cases/rules -> model
+only repeated movement is visible -> signal
+surface is stable but timing is disputed -> schedule
+word/sense is the issue -> naming-judgment
+implementation claim needs evidence -> verify
 ```
 
-If the sentence cannot be filled:
-
-| What it is | Missing | Review consequence |
-| --- | --- | --- |
-| Advice | trigger, artifact, stop check | keep as explanation; do not promote |
-| Heuristic | derivation from input to output | read `repair-table.md` or expose the missing model |
-| Candidate recipe | derivation is still loose | run one worked case |
-| Recipe-grade | trigger, input, rule, output, stop, repair all exist | use in the review |
-
-## Layer Router
-
-| Symptom | Layer | First card |
-| --- | --- | --- |
-| The problem vocabulary is missing or misleading | Language | Notation As Data |
-| Similar functions, workflows, or tests move together | Language/Unit | Movement Pattern Extraction |
-| Data, methods, messages, or change reasons suggest a misplaced owner | Unit/Boundary | Responsibility Boundary |
-| Operation results do not remain composable | Unit | Closure Composition Unit |
-| A loop, state transition, or contract has no preserved meaning | Law | Invariant Iteration |
-| Callers must know raw representation or hidden policy | Boundary | Data Abstraction Boundary |
-| New variants keep changing old conditionals | Engine | Dispatch Registration |
-| Conversion works but meaning loss is hidden | Engine/Law | Meaning-Preserving Path |
-| Same call depends on past interaction | Time | History Placement |
-| Event order changes correctness | Time/Run | Event Order Protection |
-| Result is right but process, cost, sharing, or stack shape is wrong | Run | Procedure -> Process Reality Check |
-
-When the symptom is clearer than the layer, open `repair-table.md`.
+A reference route inside this skill may deepen review, failure localization, or
+calibration. It must not reproduce the construction methods owned by those
+leaves.
 
 ## Minimal Output
 
-For a compact user-facing review, show:
-
 ```text
 Candidate:
-Source and confidence:
-Layer:
-Recipe:
-Input artifact:
-Derivation rule:
-Contract:
-Hidden detail:
-Output artifact:
-Stop check:
-Evidence and gaps:
+Pressure:
+Caller contract and hidden detail:
+Promises under review:
+Counterexample:
+Stop check and evidence:
 Decision:
-Open consequence:
+Handoff or open consequence:
 ```
 
-When this review is part of a larger task, return the decision and its open
-consequence. The caller or orchestrator decides what happens next. Otherwise,
-stop at the review result. The card must be complete enough that a later person
-or agent can use it without reconstructing the reasoning.
-
-## Self-Application Check
-
-When the candidate is a skill, workflow, recipe, or reference update, review the
-update with the same card.
-
-Map the layers this way:
-
-| Skill update surface | Review layer |
-| --- | --- |
-| trigger wording, user-facing command language | Language |
-| skill responsibility and core question | Boundary |
-| recipe-grade invariant or stop condition | Law |
-| progressive disclosure and reference routing | Engine |
-| whether future agents actually read enough context | Run |
-
-The stop check should be a realistic invocation, self-review card, or
-forward-test prompt. If the review cannot name what future behavior changes, the
-update is probably documentation, not a stable workflow abstraction.
+## Source Trace
+
+This review spine is Developer synthesis over these bounded capabilities:
+
+- Sandi Metz, Katrina Owen, and TJ Stankus, *99 Bottles of OOP*, Second
+  Edition, v2.2.2:
+  Chapters 3-9, pp. 51-268, for pressure, movement, responsibility, roles,
+  factories, and responsibility-level evidence.
+- Harold Abelson and Gerald Jay Sussman with Julie Sussman, *Structure and
+  Interpretation of Computer Programs*, Second Edition:
+  Section 1.1,
+  Section 1.3,
+  Section 2.1,
+  Section 2.2,
+  Section 2.4,
+  Section 3.1, and
+  Section 3.4
+  for black-box promises, barriers, closure, dispatch, history, and order.
+- Matthias Felleisen et al., *How to Design Programs*, living build 9.2.0.3:
+  Chapter 14,
+  Chapter 15,
+  Chapter 16,
+  Chapter 19,
+  and Chapter 20
+  for completed examples, migrated clients, and model stability.
+- Hillel Wayne, *Logic for Programmers*, v0.14.0:
+  Chapter 5, pp. 47-60, for contract and observer-relative replacement.
+- Zachary Tellman, *Elements of Clojure*, Leanpub 2019-02-11:
+  Indirection, public-manuscript pp. 70-95, for participant pressure and
+  interface calcification. Source-specific and universalized claims are excluded.

package/skills/abstraction-review/references/repair-table.md

@@ -1,103 +1,89 @@
-# Abstraction Review Repair Table
+# Abstraction Review Failure Localization
 
-Use this table when a wished abstraction failed, or when the observed symptom is
-clearer than the broken layer.
-
-The named repairs refer to [the recipe cards](recipe-cards.md). Record the result
-on [the field card](field-card.md); use [worked examples](worked-examples.md) only
-when the selected card still lacks a concrete calibration case.
+Use this reference only after the candidate review's observable stop has failed.
+Its job is to locate the broken promise and choose a handoff. It does not repair
+the design inside `abstraction-review`.
 
 ## Diagnostic Loop
 
 ```text
-observed mismatch
-  -> evidence
-  -> broken layer hypothesis
-  -> recipe card
-  -> repair output
-  -> re-run same symptom
+failed stop
+-> exact observation
+-> candidate promise contradicted
+-> broken layer or missing owner
+-> smallest revision class
+-> owning skill handoff
+-> re-run the same stop after later work
 ```
 
-Do not jump from mismatch to a better name. Names can be repair outputs, but the
-repair must change a layer, contract, or artifact.
+A better name is not a repair unless the failed promise was stable sense.
 
-## Repair Log
+## Failure Log
 
 ```text
-Observed symptom:
-Evidence:
-Broken layer hypothesis:
-Selected recipe:
-Repair output:
-Re-run result:
-Open consequence:
+Candidate:
+Failed stop:
+Observation:
+Promise contradicted:
+Likely broken layer:
+Revision class:
+Owning handoff:
+Evidence needed before re-review:
 ```
 
-If the repair output is empty, the review only explained the problem.
-
-## Repair Matrix
-
-| Symptom | Suspect layer | First repair | Output to create | Stop check |
-| --- | --- | --- | --- | --- |
-| Helpers have nice names but the domain rule is invisible | Language | Restate desired vocabulary | primitive/combination/abstraction vocabulary | new case can be spoken without representation detail |
-| Similar functions differ only by predicate, term, next step, or strategy | Language/Unit | Movement Pattern Extraction | common movement plus variation role table | old cases become simple calls |
-| Similar-looking code has different responsibilities | Unit/Boundary | Reject or split the abstraction | responsibility split note | no shared unit is promoted |
-| Extracted unit still needs unrelated context from its old host | Unit/Boundary | Responsibility Boundary | owner/message map | representative change is local to one coherent owner |
-| Caller reads object fields, list indexes, tags, or provider-specific shape | Boundary | Data Abstraction Boundary | constructor/selector/predicate/operation list | caller no longer touches representation primitive |
-| Operation result cannot be fed into later operations | Unit | Closure Composition Unit | closed operation table | closed operations build larger units |
-| Chainable API forces final side effects into the chain | Unit/Boundary | Split closed operations from finalizers | observer/finalizer boundary | closed operations and boundary effects are distinct |
-| State variables have no meaning | Law | Invariant Iteration | invariant statement | initial/step/final checks pass |
-| Loop is fast but correctness cannot be explained | Law/Run | Invariant + process trace | invariant and process trace | correctness follows from preserved meaning |
-| Recursive version is clear but stack or deferred work grows | Run | Procedure -> Process, then Invariant | shape note and accumulator option | shape change is explicit |
-| Constructor, validator, and normalizer are scattered | Boundary/Engine | Creation policy boundary | creation policy note | value enters the world through one gate |
-| Constructor is too expensive | Engine/Run | Cost placement decision | create/read/update cost note | cost owner is explicit |
-| New representation changes old code | Engine | Dispatch Registration | variant x operation table | new row/package is enough |
-| New operation changes every variant | Engine | Re-evaluate row/column axis | axis decision | frequently growing axis is explicit |
-| Mixed types explode into direct cases | Engine/Law | Meaning-Preserving Path | conversion graph | legal, loss, and unsupported paths are visible |
-| Conversion loses precision, identity, order, or capability | Law | Narrow preserved meaning | loss note | loss appears in contract |
-| Expression rewrite uses strings or indexes | Language/Boundary | Notation As Data | expression selectors/constructors | rules ignore raw layout |
-| AST exists but transforms are representation-specific | Boundary | Data Abstraction Boundary | representation-independent rules | representation can change |
-| Same call returns different results after prior interactions | Time | History Placement | state/history contract | history location is explicit |
-| Caller keeps passing previous state everywhere | Time/Boundary | History Placement | local state decision | burden is intentionally hidden or kept explicit |
-| Local state makes testing/reasoning hard | Time/Run | History Placement + process trace | hidden history note | loss of referential transparency is accepted |
-| Undo, replay, audit, or collaboration needs past events | Time | History as stream/log | stream/log decision | history is manipulable data |
-| Stream merge changes meaning | Time/Run | Event Order Protection | merge/order policy | forbidden interleaving is explainable |
-| Concurrent read-compute-write breaks invariant | Time/Run | Event Order Protection | protected region | invariant-breaking interleaving is blocked |
-| Lock/serializer blocks too much | Time/Engine | Narrow the order law | smaller protected relation | only meaningful order is protected |
-| Generic abstraction is clean but slow | Run/Engine | Procedure -> Process | cost surface | dispatch/lookup/coercion cost is visible |
-| Everything feels abstract and nothing is actionable | Run | Field Card + Recipe Cards | selected recipe card | trigger/input/output/stop are filled |
+## Localization Matrix
+
+| Failure observation | Candidate defect | Review decision | Handoff |
+| --- | --- | --- | --- |
+| caller still reads fields, indexes, tags, or provider shape | barrier is below the caller need or only renames layout | `revise-surface` | `sketch` representation boundary |
+| representative change still touches several unrelated owners | responsibility is incoherent | `split` or `reject` | `sketch` responsibility/collaboration |
+| shared role requires stronger preconditions or different effects for one implementation | substitution promise is false | `split` or `revise-model` | `model` replacement contract |
+| similar cases share syntax but not reason to change | candidate came from incidental similarity | `reject` | `signal` if further comparison is useful |
+| closed operation returns a different value world or hides effects | closure promise is false | `revise-surface` | `sketch` closure/finalizer boundary |
+| new variant still edits old packages | extension axis or ownership is wrong | `revise-surface` | `sketch` generic operation system |
+| registration accepts overlap without visible precedence | openness moved policy into load order | `revise-model` or `split` | `model` policy, then `sketch` dispatch |
+| conversion path loses precision, identity, order, or capability silently | preserved meaning is too broad | `revise-model` | `model` relation/contract |
+| result is right but stack, wait, order, resource, or failure behavior changes | contract omitted a process observer | `revise-surface` | `sketch` process shape |
+| same call changes after history but candidate has no history owner | state promise is incomplete | `revise-model` | `model` temporal, then `sketch` state |
+| public interface has one participant and one purpose with no independent cycle | boundary lacks durable pressure | `defer` or `reject` | none until participant pressure appears |
+| verifier executes but cannot fail the promise | stop is irrelevant | `needs-evidence` | `verify` |
+| only the proposed name changes while contract stays unclear | sense is downstream of missing design | `defer` | `sketch` or `naming-judgment` after ownership |
 
 ## Collision Rules
 
-| Collision | Prefer first when evidence says... | Then check... |
-| --- | --- | --- |
-| Language vs Boundary | caller has no useful words except representation details | whether a boundary is still needed after vocabulary exists |
-| Movement vs Duplication | cases share behavior roles, not just text | whether old cases become simpler and responsibility stays coherent |
-| Unit vs Boundary | results leave the composable world | observer/finalizer separation |
-| Law vs Run | result is right but why is unclear | invariant first, then process shape |
-| Boundary vs Engine | caller knows internal details | boundary first, then registry/table placement |
-| Engine vs Law | dispatch/conversion works but meaning loss hides | preserved meaning, then path graph |
-| Time vs Boundary | same call changes with history | whether history is public contract or hidden state |
-| Time vs Run | delayed execution or event order changes correctness | order law or process trace |
-| Run vs Engine | abstraction is semantically right but costs too much | cost trace, then dispatch/coercion placement |
+When several failures appear, localize the earliest broken promise:
 
-## Exit Checks
+1. disputed meaning before surface;
+2. missing caller surface before candidate review;
+3. responsibility or boundary before naming;
+4. semantic contract before process optimization;
+5. process/history observer before timing;
+6. relevant evidence before approval.
 
-Before leaving the table, check:
+Do not combine all repairs into one redesign. The same failed stop should be
+re-run after the owning leaf produces a new candidate.
 
-```text
-Symptom:
-  Did the review name the actual mismatch?
+## Exit Check
+
+Leave with exactly one of:
 
-Evidence:
-  Was the mismatch observed in caller code, trace, test, cost, history, or order?
+```text
+re-review now:
+  existing evidence already supports a revised decision
 
-Layer:
-  Is the layer a likely cause, not merely a consequence?
+handoff:
+  another leaf owns a missing artifact
 
-Recipe:
-  Does the selected card require an output artifact?
+defer:
+  accessible evidence is insufficient but no current blocker exists
 
-Re-run:
-  Did the same symptom disappear, remain, or become a new symptom?
+reject:
+  the candidate promise is contradicted and no smaller truthful surface remains
 ```
+
+## Source Trace
+
+This diagnostic table is Developer synthesis. Its promise boundaries are
+calibrated by the exact sources listed in
+Abstraction Candidate Review; it introduces no additional
+source claim or construction method.