@shadowclone/cli 0.0.5 → 0.0.6

package/evals.md

@@ -0,0 +1,89 @@
+# Early preference evaluation
+
+This comparison asks whether adding a Shadowclone profile helps a coding agent follow a user's engineering preferences. It measures adherence to stated guidance, not speed, general intelligence, or productivity.
+
+Four small TypeScript tasks were completed across three setups using GPT-5.6 Sol with medium reasoning effort. There was one implementation per task per setup, giving twelve graded implementations. Every preference check has three judge votes.
+
+## What each agent received
+
+| Setup | Repository guidance | Personal skills and context | Shadowclone profile |
+| --- | --- | --- | --- |
+| Bare | Yes | No | No |
+| Skills | The same | Yes | No |
+| Clone | The same | The same as Skills | Yes |
+
+Bare is a repository-native baseline, not an agent with no instructions. The repository's existing guidance can overlap with the preferences being measured.
+
+The personal skills were existing user-written or user-guided instructions. They were not a benchmark-specific library or an independently optimized baseline. Such instructions can become outdated or inconsistent; this comparison did not assess their freshness. They covered coding conventions and task workflows. The Skills setup also admits frozen personal instructions and memory when available, so Skills versus Bare measures the personal context package, not skills alone.
+
+Clone received that same frozen personal context plus the scoped Markdown profile compiled by Shadowclone. The profile provides additional guidance learned or recorded through Shadowclone; it does not change the model's weights. Skills versus Clone is the comparison that isolates the added profile within this setup.
+
+Native Shadowclone injection was removed from the repository snapshots to keep the setups separate. All three agents received the same task, starting repository state, model settings, and execution constraints. They could choose their public APIs, names, and file organization.
+
+## Tasks
+
+All tasks required a self-contained new module and focused tests, with no changes to existing files or project wiring.
+
+| Task | Assignment |
+| --- | --- |
+| 1. Byte quantities | Parse nonnegative decimal quantities with B, KB, MB, GB, KiB, MiB, and GiB units. Use decimal or binary multipliers as appropriate, reject invalid or unsafe byte counts, and format into a requested unit with zero to three decimal places and trailing zero removal. Test conversions, boundaries, fractions, and invalid input. |
+| 2. Integer ranges | Validate half-open safe-integer ranges, normalize unsorted and duplicate ranges, discard empty ranges, merge overlaps and touching ranges, intersect range lists, and check membership. Preserve caller-owned inputs and test boundaries, invalid inputs, and immutability. |
+| 3. Ordered query parameters | Parse and serialize query strings using URLSearchParams semantics while preserving order, duplicates, and empty keys or values. Replace a key's values at its first occurrence, append when absent, and remove it for an empty replacement list. Preserve inputs and test encoding, ordering, and round trips. |
+| 4. Bounded undo/redo | Implement immutable generic history with a positive safe-integer undo capacity, recording, undo, redo, and availability queries. Trim old history, clear redo on branching, and preserve state and redo for Object.is-equal recordings. Test capacity, identity, no-op behavior, and immutability. |
+
+Task 1 was the pilot. Its saved implementations were regraded after clarifying that PascalCase types and human-readable messages are valid. Tasks 2 through 4 then ran with that clarified rubric. The pilot regrade is not counted as another implementation or repetition.
+
+## How preference scoring worked
+
+A versioned code-only rubric was frozen before execution. Each criterion retained a stable identifier, its source quotation, scope, and any explicit task exception. The same rubric was applied to every setup. Workflow instructions that could not be judged from the generated code were excluded.
+
+This rubric contained seventeen checks: type safety, options-object arguments, promise handling, complete names, file length, public module boundaries, lint suppressions, zero comments, identifier casing, abbreviation casing, all-caps names, generic parameter names, module-local names, feature-based organization, colocated tests, composition, and test-local setup.
+
+These are the user's preferences, not universal definitions of good code. A task-required API signature overrides a conflicting preference for that API only. PascalCase type names and readable error messages do not violate the identifier-case check.
+
+Each anonymous implementation was graded separately. Three independent model votes judged each criterion as pass or fail; the majority determined its score. Preference requests contained at most eight criteria per batch. Validated batches were saved immediately so unfinished judging could resume without regenerating code. These are independent votes, not three different judge models or human reviewers.
+
+Each passing criterion contributes one point. A score of 15/17 means fifteen guideline checks passed. The denominator is fixed here: a rule can pass because the code avoids the prohibited construct, even if the task did not actively exercise that rule. Related rules can overlap, such as camelCase identifiers and avoiding all-caps names.
+
+## Recorded preference results
+
+| Task | Bare | Skills | Clone |
+| --- | ---: | ---: | ---: |
+| 1. Byte quantities | 11/17 | 14/17 | 15/17 |
+| 2. Integer ranges | 15/17 | 14/17 | 16/17 |
+| 3. Ordered query parameters | 15/17 | 16/17 | 16/17 |
+| 4. Bounded undo/redo | 14/17 | 15/17 | 15/17 |
+| Total | 55/68 (80.9%) | 59/68 (86.8%) | 62/68 (91.2%) |
+
+Clone scored above Bare on all four tasks. It scored above Skills on two tasks and tied on two. The aggregate difference was 10.3 percentage points over Bare and 4.4 over Skills. These differences describe this small comparison, not an expected gain on other work.
+
+### Judges' reasons
+
+These summaries explain the recorded verdicts; they are not additional grading.
+
+| Task | Bare | Skills | Clone |
+| --- | --- | --- | --- |
+| Byte quantities | Lost checks for a prohibited cast, positional arguments, comments, uppercase constants under two naming rules, and names repeating the module context. | Used options objects and avoided prohibited casts and comments. Lost two naming checks for an uppercase constant and one for redundant module context. | Passed the corrected casing rule. Lost checks for redundant module context and mutable test setup. |
+| Integer ranges | Lost checks for positional arguments and redundant module context. | Had the same two failures plus a forbidden documentation comment. | Used options objects and no comments. Lost only the module-local naming check. |
+| Ordered query parameters | Lost checks for positional replacement arguments and redundant module context. | Used an options object. Lost only the module-local naming check. | Used an options object. Lost only the module-local naming check. |
+| Bounded undo/redo | Lost checks for non-null assertions, positional arguments, and redundant module context. | Avoided the first two violations. Lost checks for redundant module context and setup placed after assertions. | Avoided non-null assertions and positional arguments. Lost checks for redundant module context and reassigned test variables. |
+
+Skills scored below Bare on the integer-range task because it added a comment that violated the zero-comments rule. Extra guidance did not guarantee better adherence. All setups lost the module-local naming check somewhere in each task.
+
+## Correctness is separate
+
+The model-scored correctness checks were identical across setups: 5/5 for Tasks 1, 2, and 4, and 4/5 for Task 3. They are code-review judgments, not proof from executing a complete test suite. The evaluation did not install dependencies or run repository-wide checks, and the selected correctness criteria do not cover every requested behavior.
+
+Task 3's deduction exposes a correctness-rubric defect: it required separate assertions for empty keys and empty values even though the task did not. All three implementations covered both in combined assertions, and the judges acknowledged that the behavior was preserved. That deduction is not evidence of a functional failure.
+
+## Limits and unresolved judging issues
+
+- Four tasks, one implementation per setup, and one model configuration are too small to establish general superiority. This does not meet the harness's repeated-run threshold of three tasks with two repetitions.
+- The test-setup rule was applied inconsistently in Task 4. Skills lost a point for setup after assertions, while similar Bare code passed by a two-to-one vote. The recorded scores have not been silently corrected.
+- Model judges can make correlated mistakes. Three votes improve inspectability but do not replace human review or executable checks.
+- Bare had useful repository guidance, and some checks were easy for every setup to pass. Skills may be stale; the comparison does not show what a carefully revised skill library would achieve.
+- The results show preference adherence under this rubric. They do not establish correctness, safety in unrestricted execution, time saved, or better performance across users, repositories, providers, and task sizes.
+
+## Run your own comparison
+
+Use the evaluation harness with a repository you are authorized to evaluate and your own consented guidance. See [the evaluation architecture](docs/architecture/09-evaluation.md) for setup, isolation, persistence, and recovery, and [the judging design record](docs/design/020-preference-judging.md) for the measurement changes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shadowclone/cli",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "module": "src/cli/index.ts",
   "type": "module",
   "packageManager": "bun@1.3.3",
@@ -23,7 +23,7 @@
     "@types/bun": "latest",
     "typescript": "~5.9"
   },
-  "description": "Learns how you work from the AI coding sessions already on your disk, then runs copies of you inside the agent you already use.",
+  "description": "Turns how you work into a portable, tested environment for the coding agents you already use.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -44,8 +44,11 @@
   "files": [
     "bin",
     "dist",
+    "preferences",
+    "skills",
     ".claude-plugin",
     "README.md",
+    "evals.md",
     "LICENSE"
   ],
   "dependencies": {

package/preferences/dependencies-existing.md

@@ -0,0 +1,12 @@
+---
+id: dependencies-existing
+title: Prefer the existing stack
+axis: dependency-posture
+category: dependencies
+section: engineering
+applies-when:
+  - choosing an implementation dependency
+---
+## Prefer the existing stack
+
+Prefer the language runtime and dependencies already present in the project. Add a dependency only when the existing stack cannot express the behavior without substantial custom machinery.

package/preferences/dependencies-mature.md

@@ -0,0 +1,12 @@
+---
+id: dependencies-mature
+title: Adopt mature focused dependencies
+axis: dependency-posture
+category: dependencies
+section: engineering
+applies-when:
+  - choosing an implementation dependency
+---
+## Adopt mature focused dependencies
+
+Use a mature, focused dependency when it removes custom code around a well-understood problem. Check its maintenance, license, runtime cost, and fit before adding it.

package/preferences/planning-first.md

@@ -0,0 +1,12 @@
+---
+id: planning-first
+title: Plan before changing code
+axis: planning-threshold
+category: planning
+section: workflow
+applies-when:
+  - starting an implementation task
+---
+## Plan before changing code
+
+Write a concrete implementation plan before editing. Tie each step to a file, behavior, validation method, and dependency on earlier work.

package/preferences/planning-when-costly.md

@@ -0,0 +1,12 @@
+---
+id: planning-when-costly
+title: Plan only costly changes
+axis: planning-threshold
+category: planning
+section: workflow
+applies-when:
+  - starting an implementation task
+---
+## Plan only costly changes
+
+Begin reversible local changes directly. Write a plan before choices that are expensive to reverse, cross subsystem boundaries, or need agreement from another person.

package/preferences/questions-autonomous.md

@@ -0,0 +1,12 @@
+---
+id: questions-autonomous
+title: Use judgment and keep moving
+axis: question-frequency
+category: communication
+section: workflow
+applies-when:
+  - choosing between reasonable implementation paths
+---
+## Use judgment and keep moving
+
+Use repository context and prior decisions to choose between reasonable paths. Ask only when a missing fact blocks progress or the choice is expensive to reverse.

package/preferences/questions-early.md

@@ -0,0 +1,12 @@
+---
+id: questions-early
+title: Ask when intent is unclear
+axis: question-frequency
+category: communication
+section: workflow
+applies-when:
+  - finding multiple plausible interpretations of a request
+---
+## Ask when intent is unclear
+
+Ask before choosing when plausible interpretations would produce meaningfully different results. Make the decision and its consequences easy to compare.

package/preferences/refactor-boundaries.md

@@ -0,0 +1,12 @@
+---
+id: refactor-boundaries
+title: Refactor when boundaries improve
+axis: refactor-tolerance
+category: architecture
+section: engineering
+applies-when:
+  - changing code near a weak module boundary
+---
+## Refactor when boundaries improve
+
+Reshape nearby code when the change creates a smaller interface, removes duplicated policy, or puts ownership in one module. Keep the refactor tied to the behavior being changed.

package/preferences/refactor-preserve.md

@@ -0,0 +1,12 @@
+---
+id: refactor-preserve
+title: Preserve the local structure
+axis: refactor-tolerance
+category: architecture
+section: engineering
+applies-when:
+  - changing behavior in existing code
+---
+## Preserve the local structure
+
+Fit the change into the existing design and avoid rearranging nearby code. Refactor only when the requested behavior cannot be expressed safely in the current structure.

package/skills/design-deep-modules/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: design-deep-modules
+description: Design or improve a module so callers get substantial behavior through a small stable interface. Use when choosing seams, reducing orchestration in callers, or making a subsystem easier to test and change.
+metadata:
+  shadowclone-category: architecture
+  shadowclone-section: engineering
+  shadowclone-applies-when: designing or reshaping a module or subsystem
+---
+# Design Deep Modules
+
+## Use when
+
+Use this skill when complexity is spread across callers, a proposed abstraction mostly forwards arguments, or tests must reach through several layers to observe behavior.
+
+A module is any implementation presented through an interface. Depth means the caller learns a small interface and receives substantial coherent behavior. A seam is the place where one implementation can be replaced without editing its callers.
+
+## Process
+
+1. List the callers and the facts each caller currently needs to coordinate the behavior.
+2. Separate policy decisions from mechanical steps and identify the implementation that owns the required state.
+3. Write the smallest interface that lets callers express their intent without coordinating internal order.
+4. Sketch at least two materially different placements for the seam when its location is uncertain.
+5. Compare the alternatives by caller burden, hidden complexity, error behavior, and the tests each interface enables.
+6. Choose the interface that keeps related policy and state local while preserving useful variation.
+7. Move orchestration behind the interface and remove pass-through layers that add no decision or isolation.
+8. Test behavior through the chosen interface with dependencies replaced only at real external seams.
+9. Read every caller again and remove knowledge that now belongs inside the module.
+
+## Guardrails
+
+- Add a seam when behavior or dependencies genuinely vary, or when isolation is required at an external boundary.
+- Keep invariants, ordering, error modes, and configuration inside the interface contract.
+- Prefer one options object over sequences of primitive arguments that callers must correlate.
+- Return results when callers need outcomes; contain side effects behind the owning interface.
+- Avoid wrappers whose public surface repeats the implementation beneath them.
+- Keep repository and domain terms in names so the interface matches the system users recognize.
+
+An interface is still large when callers must know which methods to call, in what order, and which intermediate state to carry. Move that sequence behind one intent-level operation.
+
+## Completion
+
+The design is complete when callers express intent through a smaller interface, related complexity has one owner, each remaining seam has a concrete reason to vary or isolate, and tests can exercise the module without depending on its internal sequence.

package/skills/diagnose-before-editing/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: diagnose-before-editing
+description: Diagnose a reproducible defect or performance regression before changing production code. Use when behavior is broken, failing, throwing, flaky, or unexpectedly slow.
+metadata:
+  shadowclone-category: debugging
+  shadowclone-section: workflow
+  shadowclone-applies-when: diagnosing a reported defect or performance regression
+---
+# Diagnose Before Editing
+
+## Use when
+
+Use this skill for a reported defect whose cause is not already demonstrated by a failing test or a direct invariant violation. The goal is a tight feedback loop and a causal explanation before the production fix begins.
+
+## Process
+
+1. Restate the symptom as concrete input, actual output, and expected output.
+2. Build the fastest repeatable command that reaches the same path and produces a binary result for that symptom.
+3. Run the command and verify it fails in the way the user described.
+4. Reduce the scenario one input, dependency, or step at a time while preserving the failure.
+5. Trace data and control flow across the remaining boundaries. Record where correct state first becomes incorrect.
+6. Form several falsifiable causes and rank them by evidence. For each cause, state what observation would disprove it.
+7. Probe one cause at a time with a debugger, targeted instrumentation, a query plan, or a controlled input change.
+8. Remove disproved causes. Stop when one cause predicts the observed failure and a controlled change removes it.
+9. Turn the reduced reproduction into a regression test at the public seam when that seam can express the defect.
+10. Apply the smallest fix at the point where the invalid state originates.
+11. Re-run the reduced test and the original reproduction, then remove diagnostic artifacts.
+
+For a flaky defect, measure its reproduction rate and tighten the trigger until the signal is useful. Pin clocks, random seeds, concurrency, and external responses where they influence the outcome.
+
+For a performance regression, establish a baseline measurement before forming a theory. Use profiling, timings, or query plans that separate the suspected cost from unrelated work.
+
+## Guardrails
+
+- Keep captured logs, traces, and payloads out of reports until secrets and personal paths are redacted.
+- Instrument only boundaries that distinguish current hypotheses.
+- Change one causal variable per probe.
+- Treat a nearby error as a separate defect unless it explains the reported symptom.
+- Fix the origin of invalid state rather than adding a downstream fallback that hides it.
+- Preserve a reduced reproduction as a test only when it exercises the real failure through a stable seam.
+
+If the defect cannot be reproduced, report the exact loops attempted and the missing access or artifact required. Do not convert an unverified theory into a production edit.
+
+## Completion
+
+Diagnosis is complete when one repeatable command demonstrates the original symptom, the causal boundary is identified with evidence, the fix makes both the reduced and original reproductions pass, relevant checks stay green, and temporary instrumentation is gone.

package/skills/prove-regression-tests/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: prove-regression-tests
+description: Prove that a regression test detects the defect it claims to guard by temporarily removing or inverting the enforcing change. Use when adding a test for a confirmed bug or review finding.
+metadata:
+  shadowclone-category: testing
+  shadowclone-section: workflow
+  shadowclone-applies-when: adding a regression test for a confirmed defect
+---
+# Prove Regression Tests
+
+## Use when
+
+Use this skill after a defect has a focused test and a fix. A passing test after the fix does not show that the test reaches the broken behavior, so the enforcing change must be removed or inverted briefly.
+
+## Process
+
+1. Identify the smallest production condition, expression, or value that makes the fixed behavior differ from the defect.
+2. Choose a minimal inverse that restores the defect while keeping the code compilable and the test runnable.
+3. Apply only that inverse. Avoid reverting the full patch or deleting the implementation under test.
+4. Print the mutated lines with file and line numbers so the changed condition is visible.
+5. Run the narrow regression test and confirm its assertion fails on the user's original symptom.
+6. Reject the test if it passes, fails during setup, or fails for an unrelated reason. Improve the seam or assertion before continuing.
+7. Restore the enforcing line exactly.
+8. Print the restored lines and run the same test again.
+9. Run the affected suite to ensure the proof mutation left no residue.
+
+## Guardrails
+
+- Keep the mutation local, reversible, and valid under the type checker.
+- Mutate production behavior rather than weakening the test.
+- Preserve a clean working tree outside the lines involved in the proof.
+- Avoid destructive history commands to simulate the regression.
+- Treat a setup error, compiler error, timeout, or different assertion as a failed proof.
+- Restore before changing anything else so later failures cannot inherit the mutation.
+
+When several tests cover the same fix, run the narrowest test first. Broaden only when the claimed protection spans multiple public behaviors.
+
+## Completion
+
+The proof is complete when the visible inverse causes the intended assertion to fail, the visible restoration makes the same test pass, the affected suite passes, and the working diff contains only the intended implementation and test.

package/skills/research-primary-sources/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: research-primary-sources
+description: Resolve a technical implementation question against authoritative first-party evidence. Use when behavior depends on a library, platform, protocol, standard, or tool that may have changed.
+metadata:
+  shadowclone-category: research
+  shadowclone-section: workflow
+  shadowclone-applies-when: resolving an implementation question that depends on external facts
+---
+# Research Primary Sources
+
+## Use when
+
+Use this skill when an implementation choice depends on facts outside the repository or on behavior that may differ by version. Primary sources include official documentation, specifications, source code, release notes, and first-party issue trackers.
+
+## Process
+
+1. Write the decision as one answerable question and list the facts needed to settle it.
+2. Record the repository's relevant version, runtime, platform, and existing dependency constraints.
+3. Search for the owner of each fact. Prefer the specification or implementation that defines the behavior.
+4. Open the exact supporting page or source location. Check its version and publication or commit date.
+5. Trace important claims back from summaries to their primary source.
+6. Compare the evidence with the repository's installed version and current code path.
+7. Resolve disagreements by authority and applicability. State when the sources describe different versions or environments.
+8. Write the conclusion beside links that directly support each consequential claim.
+9. Translate the conclusion into the smallest implementation constraint the code needs.
+
+## Guardrails
+
+- Treat search snippets as leads rather than evidence.
+- Prefer current first-party sources for changing APIs and compatibility claims.
+- Distinguish a documented guarantee from behavior inferred from source code.
+- Mark an inference as an inference and name the observations it connects.
+- Quote only the minimum words needed to preserve exact terminology.
+- Keep credentials, private URLs, and captured user data out of research notes.
+
+If no authoritative answer exists, state what remains unknown and choose a reversible implementation that contains the uncertainty behind one interface.
+
+## Completion
+
+Research is complete when the decision question has a direct answer or an explicit unknown, every consequential claim has an applicable primary source, version differences are reconciled, and the resulting code constraint is clear enough to implement without repeating the search.

package/skills/resolve-conflicts-by-intent/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: resolve-conflicts-by-intent
+description: Resolve an in-progress merge or rebase by tracing each conflicting change to its original intent and validating the combined behavior. Use when Git reports conflicted files.
+metadata:
+  shadowclone-category: version-control
+  shadowclone-section: workflow
+  shadowclone-applies-when: resolving an in-progress merge or rebase conflict
+---
+# Resolve Conflicts by Intent
+
+## Use when
+
+Use this skill only while a merge or rebase is in progress. A conflict is a disagreement between changes, so the correct result comes from understanding both changes rather than choosing the side with newer text.
+
+## Process
+
+1. Inspect the Git operation, conflicting paths, current branch, and commits being combined.
+2. Read each conflicted file with enough surrounding code to understand the affected behavior.
+3. Find the primary source for both sides: commits, pull requests, issues, design records, tests, and nearby callers.
+4. State the intent of each side before editing the hunk.
+5. Decide whether both intents can coexist. When they cannot, choose the intent that matches the merge goal and record the lost behavior for review.
+6. Resolve one hunk at a time in the current architecture. Avoid introducing a third design that neither side requested.
+7. Search the full file for related names and assumptions that Git did not mark as conflicts.
+8. Run focused checks after each coherent file group, then the repository's merge gate.
+9. Stage resolved files and continue the Git operation until no conflicts remain.
+10. Inspect the combined diff against both original intents before reporting completion.
+
+## Guardrails
+
+- Use whole-file ours or theirs only when one side's entire file is intentionally obsolete.
+- Preserve schema changes, migrations, generated artifacts, and tests as one coherent set.
+- Treat rename and delete conflicts as behavior decisions rather than path cleanup.
+- Keep conflict markers out of the staged tree.
+- Separate failures introduced by the merge from failures already present on either parent.
+- Finish the requested merge or rebase after resolution unless a destructive or irreversible choice needs user input.
+
+When intent remains ambiguous after reading primary sources, present the exact incompatible outcomes and the evidence for each. Ask about that decision instead of guessing from line order.
+
+## Completion
+
+Resolution is complete when Git reports no unmerged paths, each hunk has a stated intent-based result, the combined behavior passes relevant checks, the operation has finished, and the final diff preserves every compatible requirement from both sides.

package/skills/scope-confirmed-changes/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: scope-confirmed-changes
+description: Keep a bug fix or review correction tied to reachable behavior and the requested outcome. Use when addressing defects, reviewer findings, or a request for a minimal focused change.
+metadata:
+  shadowclone-category: change-control
+  shadowclone-section: workflow
+  shadowclone-applies-when: fixing a defect or addressing review feedback
+---
+# Scope Confirmed Changes
+
+## Use when
+
+Use this skill when nearby cleanup, defensive cases, or architectural improvements could easily expand a concrete correction. The scope boundary is the observable failure or requested outcome.
+
+## Process
+
+1. State the defect as reachable input followed by incorrect observable behavior, or state the requested outcome in equally concrete terms.
+2. Trace the path that produces it and confirm the current code can reach that path.
+3. Sort candidate edits into required, supporting, and unrelated changes.
+4. Keep required edits that directly change the outcome.
+5. Keep a supporting edit only when the required change cannot remain correct or testable without it.
+6. Leave unrelated cleanup, speculative guards, and style changes outside the diff.
+7. Add or update the narrow test that expresses the confirmed behavior through its public seam.
+8. Read every final hunk and map it back to the stated defect, outcome, or necessary verification.
+9. Commit each later review round separately so reviewers retain a stable history.
+
+## Guardrails
+
+- Verify a review finding against the current branch before changing code.
+- Reject cases that cannot occur under the validated input and type boundaries.
+- Avoid widening public contracts to accommodate an internal implementation shortcut.
+- Keep refactors only when they create the seam required to fix or test the behavior.
+- Preserve unrelated user edits and existing style.
+- Use a separate proposal for improvements that do not affect the confirmed outcome.
+- Never rewrite pushed history to make a correction look like the first attempt.
+
+When a proposed fix causes a different observable regression, remove that approach and return to the confirmed failure. Do not accumulate compensating changes around a wrong fix.
+
+## Completion
+
+The change is complete when the original behavior is corrected, its focused verification passes, every diff hunk maps to the requested outcome, unrelated observations are left out, and the commit history preserves each pushed correction round.

package/skills/testing-first/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: testing-first
+description: Build observable behavior through a red-green cycle at a stable public seam. Use when the user asks for test-first work, TDD, or a regression test before implementation.
+metadata:
+  shadowclone-category: testing
+  shadowclone-section: engineering
+  shadowclone-applies-when: changing observable behavior with a test-first workflow
+  shadowclone-axis: testing-approach
+---
+# Test First Through a Public Seam
+
+## Use when
+
+Use this skill when a behavior can be exercised through an interface that callers already use, or through the interface the change is intended to create.
+
+Before writing a test, identify the observable result and the seam where a real caller sees it. If the seam is unclear, settle the interface before committing to test structure.
+
+## Process
+
+1. State one behavior as concrete input and observable output. Name the user-visible failure the test must detect.
+2. Find the narrowest stable seam that reaches the behavior without exposing private implementation details.
+3. Write one test through that seam with an expected value independent of the implementation.
+4. Run only that test and confirm it fails because the behavior is absent or wrong.
+5. Implement the smallest vertical slice that makes the test pass. Include every layer required for that one behavior.
+6. Run the focused test again. Inspect the failure if it stays red rather than weakening the assertion.
+7. Repeat with the next behavior only after the previous slice is green.
+8. Run the broader checks affected by the completed slices and review the final diff for speculative code.
+
+## Guardrails
+
+- Test behavior through the same interface a caller uses.
+- Keep each cycle to one new claim. Multiple assertions may support that claim when they observe one outcome.
+- Use literals, specifications, recorded fixtures, or another independent source for expected results.
+- Prefer real collaborators inside the tested module. Replace a dependency only at an established external seam.
+- Keep the failing output long enough to prove the test can detect the missing behavior.
+- Remove implementation added for a future test that has not been written.
+
+A test is coupled to implementation when a harmless refactor breaks it while public behavior stays the same. Move that test outward to the stable seam.
+
+A test is tautological when it recreates the production calculation to derive the expected value. Replace the derived expectation with a result obtained independently.
+
+## Completion
+
+The work is complete when every requested behavior has a focused test that was observed failing first, the implementation passes those tests through public seams, affected repository checks pass, and the diff contains no code justified only by an unwritten future test.

package/skills/testing-risk-based/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: testing-risk-based
+description: Select tests from concrete regression risk instead of applying test-first work to every edit. Use for changes where the user wants proportional coverage or where existing behavior may regress.
+metadata:
+  shadowclone-category: testing
+  shadowclone-section: engineering
+  shadowclone-applies-when: changing observable behavior with proportional test coverage
+  shadowclone-axis: testing-approach
+---
+# Test Where Behavior Is at Risk
+
+## Use when
+
+Use this skill when the change should be tested in proportion to what can break. It fits maintenance work, extensions to tested modules, and changes where a presentation-only edit has a different risk than a state transition or data boundary.
+
+## Process
+
+1. List the observable behaviors touched by the change and the callers that depend on each one.
+2. Rank the risks by consequence, likelihood, and whether an existing check would detect the regression.
+3. Read nearby tests to find the established public seam and fixture style.
+4. Add or change a test for every material risk that existing coverage misses.
+5. Use the smallest fixture that still crosses the real boundary where the regression could occur.
+6. Run the focused tests, then the repository checks that cover affected consumers.
+7. Inspect the final diff and explain any material risk left to manual verification.
+
+## Guardrails
+
+- Add coverage for changes to state, permissions, persistence, parsing, routing, and public contracts.
+- Prefer an existing integration seam when a unit test would only mirror private branches.
+- Skip a new test when an existing test already fails under the proposed regression and clearly names the behavior.
+- Skip tests that assert static text, styling, or reversible wiring unless those details are a supported contract.
+- Keep expected results independent from the code that computes them.
+- Do not inflate test count with cases that exercise the same branch and consequence.
+
+When the risk cannot be automated, define a manual check with exact setup, action, and expected result. A vague instruction to test manually is not coverage.
+
+## Completion
+
+The work is complete when every material regression risk is caught by an existing test, a new test, or a concrete manual check; all selected checks have run; and the handoff states any remaining unverified behavior.

package/skills/typescript-type-safety/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: typescript-type-safety
+description: Represent valid state and relationships in TypeScript so invalid combinations fail at compile time. Use when designing types, parsing unknown input, or removing unsafe assertions.
+metadata:
+  shadowclone-category: typescript
+  shadowclone-section: engineering
+  shadowclone-applies-when: language=typescript and changing typed state or boundaries
+---
+# Represent State in TypeScript Types
+
+## Use when
+
+Use this skill when values change together, optional fields encode hidden states, external input enters typed code, or a type assertion is needed to make the compiler accept an operation.
+
+## Process
+
+1. Name the domain states and the transitions the code permits.
+2. Replace groups of independent optional fields with a discriminated union when only certain combinations are valid.
+3. Preserve relationships between keys and values with generics, mapped types, or a typed setter rather than erasing both to broad primitives.
+4. Accept external data as `unknown` and validate it once at the boundary.
+5. Narrow values through predicates, control flow, schema results, or destructuring before use.
+6. Make absence explicit when it is a valid state and impossible when the caller must supply a value.
+7. Return a result type that forces callers to handle meaningful failure modes.
+8. Run the type checker and tests that exercise runtime validation at the boundary.
+
+## Guardrails
+
+- Keep one source of truth for each state discriminator.
+- Prefer exhaustive switches where every union member requires behavior.
+- Preserve literal relationships instead of widening values to `string` or `number` too early.
+- Use runtime validation for files, network responses, environment values, and parsed JSON or YAML.
+- Treat `any`, non-null assertions, and broad type assertions as evidence that a boundary or relationship is missing.
+- Use a narrow assertion only when the runtime invariant is established outside TypeScript and cannot be expressed through validation or control flow.
+- Avoid generic abstractions that make a local relationship harder to read than explicit types would.
+
+When a library returns an imprecise type, contain the adaptation in one boundary function. Return a precise project type so unsafety does not spread through callers.
+
+## Completion
+
+The work is complete when valid states are directly constructible, invalid combinations are rejected by validation or the compiler, key-value relationships survive through the call path, the type checker passes, and no new unsafe escape is left unexplained at a boundary.