@hobin/developer 0.1.0

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

@@ -0,0 +1,306 @@
+# Abstraction Review Worked Examples
+
+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
+
+## 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 |
+| --- | --- |
+| 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 |
+
+## Skill Update Self-Review
+
+```text
+Candidate:
+  abstraction-review skill update with field-card, recipe-cards, repair-table,
+  and worked examples
+
+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
+
+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."
+
+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
+```
+
+## 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
+
+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
+
+```text
+Candidate:
+  withRetry(operation, shouldRetry, delayStrategy, maxAttempts)
+
+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
+
+Stop:
+  old cases are simple calls and a new retrying operation needs no new branch in
+  withRetry
+
+Decision:
+  keep if variation roles are stable; reject if each case has different
+  responsibility or product semantics
+```
+
+## Optional Default Semantics
+
+```text
+Candidate:
+  readConfig("timeout") returns configured timeout or fallback
+
+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
+
+Stop:
+  each state has one meaning, one enforcement layer, and one test target
+
+Decision:
+  revise-model if missing/null/legacy meanings are not decided yet
+```
+
+## Symbolic Expression Rewrite
+
+```text
+Candidate:
+  simplify(expression)
+
+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
+
+Stop:
+  rewrite rules use selectors/constructors, not raw layout
+
+Decision:
+  keep after constructors own simplification policy; otherwise split policy
+```
+
+## Stateful Account
+
+```text
+Candidate:
+  makeAccount(initialBalance).withdraw(amount)
+
+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
+
+Stop:
+  caller contract states whether history is hidden or explicit
+
+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
+```
+
+## 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
+
+Input artifact:
+  query unit, closed operations, finalizers
+
+Derivation:
+  mark where/orderBy/limit as Query -> Query
+  mark execute as Query -> Result
+
+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
+```

package/skills/adversarial-eval/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: adversarial-eval
+description: "Design and run finite adversarial evaluations for Pi skills, packages, agent workflows, or implementation claims using exact source provenance, escalating counterexamples, hidden checks, failure classification, and a marginal-value stop rule. Use when ordinary checks may miss real workflow, compatibility, or pass-but-wrong failures."
+---
+
+# Adversarial Eval
+
+Design and run the smallest evaluation that can falsify the target claim.
+
+## Core Question
+
+What adversarial evidence would expose the target's real failure modes?
+
+## Inputs
+
+- Target, exact source or version, and falsifiable claims
+- Existing tests, transcripts, reports, diffs, or recent failures
+- Likely pass-but-wrong shapes and compatibility hazards
+- Cost, time, mutation, and safety limits
+
+## Output
+
+Lead with the target claim and observed failure mode; keep eval labels secondary.
+Produce target provenance, claims and risk model, an escalating fixture ladder,
+execution matrix, observed feedback, failure taxonomy, stop rule, and residual
+risks. When used inside a larger task, return:
+
+```text
+Status: resolved | needs-evidence | not-applicable | blocked
+Result: evidence for or against the exact evaluated claim
+Basis: fixtures, commands, transcripts, provenance, and observations
+Open questions: untested failure modes or source gaps, or none
+Artifacts: fixtures, execution matrix, feedback, and stop decision
+```
+
+When reporting multiple claims or rounds, keep the local evidence auditable:
+
+| Claim | Fixture or verifier | Observation | Classification | Residual |
+| --- | --- | --- | --- | --- |
+
+Use only the failure classes defined below. This table records evaluation
+evidence; it does not choose another capability.
+
+Return only this skill's judgment for the question at hand; leave subsequent
+routing to the caller.
+
+## Completion
+
+Finish when the highest-risk failure modes have been exercised, the last useful
+round no longer changes a patch or decision, or the next round's expected
+information is lower than its cost. Revisit after a new source version, failure
+class, user regression, or compatibility path appears.
+
+## Method
+
+1. Bind the target to its requested and actual source or version.
+2. State a falsifiable behavioral claim.
+3. Build a risk model from likely hidden conditions, stale source, human-owned
+   decisions, mutation scope, and pass-but-wrong behavior.
+4. Choose the smallest useful ladder:
+   - `smoke`: metadata, syntax, manifest, or command health;
+   - `visible`: straight-line baseline behavior;
+   - `hidden-parent`: stronger local invariants and artifact checks;
+   - `adversarial`: ambiguous, conflicting, stale, stateful, or nested cases;
+   - `compatibility`: requested source versus actually loaded source;
+   - `gate-residual`: evidence or acceptance that must remain unresolved.
+5. For each round, state the claim, fixture, verifier, expected evidence,
+   failure meaning, mutation scope, and stop condition.
+6. Run each round within the declared mutation and safety limits, preserving
+   exact command, fixture, source, and observation provenance.
+7. Classify results as `pass`, `implementation-fail`, `model-or-spec-fail`,
+   `verifier-gap`, `blocked-environment`, `pass-but-wrong-risk`, or
+   `structural-degradation`.
+8. Add or rerun a round only when it can change the target claim or decision.
+
+## Missing Evidence
+
+Return `needs-evidence` when a concrete fixture or exact-source run is still
+available. Return `not-applicable` when the claim is not falsifiable. Return
+`blocked` when the requested source or environment was not actually exercised.
+Never count evidence from a mismatched source as a target failure.
+
+## Boundary
+
+Do not import the target workflow's responsibilities, repair the evaluated
+target, exceed the declared fixture mutation scope, or present evaluation
+evidence as release approval.

package/skills/model/SKILL.md

@@ -0,0 +1,76 @@
+---
+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, state, time, or policy interaction."
+---
+
+# Model
+
+Expose the condition space a valid implementation must satisfy.
+
+## Core Question
+
+Which cases, rules, states, or transitions make the claim precise?
+
+## Inputs
+
+- Requirement, invariant, policy, workflow, or code behavior
+- Existing cases, tests, examples, and counterexamples
+- Data shapes, states, transitions, and external constraints when relevant
+
+## Output
+
+Lead with the user's product language; keep modeling labels secondary.
+Produce the lightest useful model: domain, predicates or cases, facts, rules,
+forbidden cases, transitions or objectives when relevant, guarantee placement,
+and verification targets. When used inside a larger task, return:
+
+```text
+Status: resolved | needs-evidence | not-applicable | blocked
+Result: the condition model and its main consequences
+Basis: requirement, invariant, code, tests, and explicit assumptions
+Open questions: unresolved policy or evidence gaps, or none
+Artifacts: case table, rules, transitions, or verification targets
+```
+
+Return only this skill's judgment for the question at hand; leave subsequent
+routing to the caller.
+
+## Completion
+
+Finish when plausible counterexamples can be classified by the model and each
+important rule has an observable verification target. Revisit when new cases,
+states, transitions, or policy decisions invalidate the model.
+
+## Method
+
+1. Use an accepted invariant when available; otherwise label a provisional one.
+2. Choose the lightest sufficient depth:
+   - `light`: cases, constraints, and verification targets;
+   - `structured`: explicit rules, forbidden states, or transitions;
+   - `formal`: exhaustive combinations, temporal behavior, or solver-like
+     constraints when the cost of omission justifies it.
+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,
+   property, proof, model check, or human decision.
+7. Derive verification targets and the counterexample each target should catch.
+
+## Missing Evidence
+
+Return `needs-evidence` when code, data, or examples can settle a case. Return
+`blocked` when resolving the model would require inventing product policy.
+Return `not-applicable` when no consequential condition space remains to model.
+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.
+
+## References
+
+Read [the problem-modeling reference](references/problem-modeling.md) for
+policy-heavy, stateful, optimization, safety-critical, or otherwise complex
+condition spaces.