@shadowclone/cli 0.0.9 → 0.0.11

package/evals.md

@@ -1,10 +1,10 @@
-# Early preference evaluation
+# Evaluation results
 
-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.
+These small studies measure adherence to stated engineering preferences. They do not establish productivity gains or general superiority. Both used the earlier profile-based system; the current [skills environment protocol](docs/architecture/09-evaluation.md#skills-environment-protocol) evaluates maintained skills separately.
 
-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.
+## Early profile comparison
 
-## What each agent received
+GPT-5.6 Sol, at medium reasoning effort, completed four TypeScript tasks in three setups. One implementation per task and setup produced twelve graded implementations, with three judge votes per preference check.
 
 | Setup | Repository guidance | Personal skills and context | Shadowclone profile |
 | --- | --- | --- | --- |
@@ -12,17 +12,9 @@ Four small TypeScript tasks were completed across three setups using GPT-5.6 Sol
 | 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.
+Bare already had useful repository instructions. Skills added existing user-written or user-guided instructions, including frozen personal memory where available. Their freshness was not assessed. Clone added the scoped Markdown profile; it did not change model weights.
 
-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.
+All setups used the same task, starting state, model settings, and execution constraints. Native Shadowclone injections were removed from snapshots. Each task required a new self-contained module and focused tests, without changing existing files or project wiring.
 
 | Task | Assignment |
 | --- | --- |
@@ -31,59 +23,62 @@ All tasks required a self-contained new module and focused tests, with no change
 | 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.
+The byte-quantity pilot was regraded after clarifying that PascalCase types and readable error messages were valid. The other tasks used that clarified rubric. Regrading did not add another implementation or repetition.
 
-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.
+### Scoring
 
-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.
+A frozen code-only rubric retained each criterion's source quotation, scope, and task exceptions. Its 17 checks covered type safety, options-object arguments, promises, full names, file length, public module boundaries, suppressions, comments, identifier casing, abbreviation casing, all-caps names, generic names, module-local names, feature organization, colocated tests, composition, and test-local setup.
 
-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.
+These are one user's preferences. Workflow instructions that could not be judged from code were excluded. A task-required signature overrode a conflicting preference only for that public API.
 
-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.
+Anonymous candidates received three model votes per criterion, with a majority result. These were separate calls, not three different models or human reviewers. Requests contained at most eight criteria per batch, and validated batches were saved for recovery. Each pass earned one point; the fixed denominator allowed a rule to pass when the task never exercised the prohibited construct. Some naming checks overlapped.
 
-## Recorded preference results
+### Recorded 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 |
+| Byte quantities | 11/17 | 14/17 | 15/17 |
+| Integer ranges | 15/17 | 14/17 | 16/17 |
+| Ordered query parameters | 15/17 | 16/17 | 16/17 |
+| 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.
+Clone exceeded Skills on two tasks and tied on two. The aggregate differences were 10.3 percentage points over Bare and 4.4 over Skills. Those are observations from this sample, not expected gains on other work.
 
-### Judges' reasons
-
-These summaries explain the recorded verdicts; they are not additional grading.
+The recorded deductions show where guidance helped and where it did not:
 
 | 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. |
+| Byte quantities | Cast, positional arguments, comments, uppercase constants under two rules, redundant module context | Two uppercase-constant checks and redundant module context | Redundant module context and mutable test setup |
+| Integer ranges | Positional arguments and redundant module context | The same, plus a forbidden documentation comment | Redundant module context |
+| Ordered query parameters | Positional arguments and redundant module context | Redundant module context | Redundant module context |
+| Bounded undo/redo | Non-null assertions, positional arguments, redundant module context | Redundant module context and setup after assertions | Redundant module context and reassigned test variables |
+
+### Correctness and judging limits
+
+Model-reviewed correctness scores were 5/5 for Tasks 1, 2, and 4, and 4/5 for Task 3 in every setup. Candidate tests were not executed, and the criteria did not cover every requested behavior.
+
+Task 3's deduction came from a rubric defect: it demanded separate assertions for empty keys and values, although combined assertions satisfied the task. Judges acknowledged that the behavior was preserved. The deduction does not demonstrate a functional failure.
+
+The test-setup rule was also inconsistent in Task 4: Skills lost a point for setup after assertions while similar Bare code passed two votes to one. The recorded scores remain unchanged.
 
-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.
+Four tasks with one implementation per setup do not meet the harness's repeated-run threshold. Correlated judge errors, overlapping criteria, and an unoptimized personal-context baseline further limit the result. It does not establish runtime correctness, unrestricted execution safety, or time saved.
 
-## Correctness is separate
+## Repository harness pilot (2026-09-26)
 
-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.
+Two synthetic repositories in `src/harness/fixtures/` each ran once with existing guidance and once after repository setup. Claude Code used `--model sonnet`, `acceptEdits`, a $1.50 cap per run, and no permission bypass. Both arms received the same task; held-out acceptance tests were added after execution.
 
-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.
+Setup was then named `shadowclone harness init`, now `shadowclone init --repo`. The harness arm used a four-rule profile: no TypeScript comments, files under 200 lines, a failing test for new behavior, and no commit.
 
-## Limits and unresolved judging issues
+| Repository | Arm | Held-out acceptance | Gate | Tests added | Agent committed | Cost |
+| --- | --- | --- | --- | --- | --- | --- |
+| Bun task list | baseline | 3 of 3 | pass | yes | no | $0.29 |
+| Bun task list | harness | 3 of 3 | pass | yes | no | $0.22 |
+| Python config | baseline | pass | pass | no | no | $0.29 |
+| Python config | harness | pass | pass | yes | no | $0.22 |
 
-- 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.
+Both arms solved both tasks. The Python baseline skipped a test while the harness arm added one. One run per arm on two small tasks shows that setup carried a working practice in this sample, without establishing a general improvement.
 
-## Run your own comparison
+## Further evaluation
 
-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.
+The [guidance and memory record](docs/design/021-guidance-evaluation.md#recorded-comparisons) preserves later profile comparisons and their measurement problems. See [evaluation architecture](docs/architecture/09-evaluation.md) for current protocols, isolation, budgets, and recovery.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shadowclone/cli",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "module": "src/cli/index.ts",
   "type": "module",
   "packageManager": "bun@1.3.3",
@@ -19,7 +19,7 @@
     "prepack": "bun run build"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.12",
+    "@biomejs/biome": "2.5.14",
     "@types/bun": "latest",
     "typescript": "~5.9"
   },

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

@@ -10,33 +10,23 @@ metadata:
 
 ## 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.
+Callers coordinate too many steps, an abstraction only forwards arguments, or tests must reach through layers to observe behavior. A deep module provides substantial behavior through a small interface.
 
 ## 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.
+1. Read the callers and identify the state, ordering, and policy they currently coordinate.
+2. Put related state and decisions under one owner. Define an operation that expresses the caller's intent.
+3. When the boundary is unclear, compare two placements by caller burden, error handling, and testability.
+4. Move internal sequencing behind the interface. Remove forwarding layers that provide no useful variation or isolation.
+5. Test through the public interface, replacing dependencies only at real external boundaries.
+6. Revisit callers and remove knowledge now owned by 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.
+Keep invariants and error behavior in the interface contract. Use an options object when callers would otherwise correlate primitive arguments. Return outcomes callers need, and contain side effects within their owner.
 
-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.
+Add an abstraction for a concrete variation or isolation need. A short interface still imposes complexity if callers must know a hidden sequence of calls.
 
 ## 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.
+Callers express intent without coordinating internal steps, and tests exercise behavior without depending on that sequence.

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

@@ -10,37 +10,26 @@ metadata:
 
 ## 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.
+A defect or performance regression has no demonstrated cause yet.
 
 ## 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.
+1. State the input, actual result, and expected result. Find the fastest repeatable command that reaches the failing path.
+2. Reproduce the reported failure, then remove inputs or steps while preserving it.
+3. Trace where correct state first becomes incorrect. List plausible causes and an observation that would disprove each.
+4. Probe one cause at a time with a debugger, targeted instrumentation, timings, or controlled inputs.
+5. Stop when a cause predicts the symptom and a controlled change removes it.
+6. Preserve the reproduction as a regression test through a stable public interface where practical. Fix the cause at its origin.
+7. Run the reduced and original reproductions, then remove temporary diagnostics.
 
-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.
+For flaky behavior, measure the reproduction rate and control clocks, randomness, concurrency, or external responses. For performance work, establish a baseline and measure the suspected cost before changing it.
 
 ## 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.
+Redact sensitive traces and paths before reporting them. Change one causal variable per probe. Keep unrelated defects out of the fix and avoid fallbacks that merely hide invalid state.
 
-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.
+If reproduction fails, report what was tried and the missing evidence. Do not turn an unverified theory into a production change.
 
 ## 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.
+The cause explains the original symptom, the fix passes both reproductions and affected checks, and temporary instrumentation is gone.

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

@@ -10,31 +10,22 @@ metadata:
 
 ## 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.
+A confirmed defect has a focused test and a fix. Verify that the test can detect the original failure.
 
 ## 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.
+1. Identify the smallest production change that enforces the fix.
+2. Temporarily invert it to restore the defect while keeping the code compilable.
+3. Print the changed lines with file and line numbers. Run the narrow test and confirm its assertion fails on the original symptom.
+4. If it passes or fails for another reason, improve the test before claiming coverage.
+5. Restore and display the enforcing lines, then rerun the same test and affected suite.
 
 ## 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.
+Keep the mutation local and reversible. Preserve unrelated work and avoid destructive Git operations. Mutate production behavior, not the assertion.
 
-When several tests cover the same fix, run the narrowest test first. Broaden only when the claimed protection spans multiple public behaviors.
+A setup error, compilation failure, timeout, or unrelated assertion does not prove the regression. Restore the code before starting other work. Broaden the proof only when the fix covers distinct 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.
+The visible inverse fails the intended assertion, restoration passes, and the final diff contains no proof mutation.

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

@@ -10,31 +10,22 @@ metadata:
 
 ## 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.
+An implementation decision depends on external facts or behavior that varies by version.
 
 ## 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.
+1. State the decision as an answerable question. Record the project's relevant version, runtime, platform, and constraints.
+2. Find the specification, official documentation, implementation, release note, or first-party issue that defines the behavior.
+3. Open the exact source and check its version and date. Trace consequential claims back from summaries.
+4. Compare the evidence with the installed version and code path. Explain disagreements caused by different environments or versions.
+5. Give the conclusion with direct supporting links and the implementation constraint it creates.
 
 ## 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.
+Search snippets are leads; read the underlying source. Distinguish documented guarantees from inferences and identify the observations supporting an inference.
 
-If no authoritative answer exists, state what remains unknown and choose a reversible implementation that contains the uncertainty behind one interface.
+Quote sparingly and keep credentials, private URLs, and captured user data out of research notes. If authoritative evidence is unavailable, state the unknown and contain it behind a reversible implementation choice.
 
 ## 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.
+The question has a supported answer or an explicit unknown, and the resulting constraint is clear enough to implement.

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

@@ -10,32 +10,23 @@ metadata:
 
 ## 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.
+A merge or rebase is in progress and Git reports conflicts.
 
 ## 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.
+1. Inspect the operation, conflicting paths, and commits being combined.
+2. Read surrounding code and the commits, design records, tests, or review discussions explaining each side.
+3. Identify both intended behaviors. Preserve compatible requirements; ask about incompatible outcomes when the merge goal does not settle them.
+4. Resolve each hunk in the current architecture. Check related names and assumptions outside Git's conflict markers.
+5. Run focused checks and the repository's merge gate. Separate new failures from failures present on either parent.
+6. Stage resolutions and finish the authorized operation. Review the combined diff against both original intents.
 
 ## 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.
+Use whole-file ours or theirs only when that entire side is intentionally obsolete. Keep schema changes, migrations, generated artifacts, and tests coherent. Rename and delete conflicts can change behavior.
 
-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.
+Avoid introducing an unrelated third design. Remove all conflict markers and preserve unrelated user edits. Follow the repository's approval requirements for Git operations.
 
 ## 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.
+No unmerged paths remain, compatible requirements survive, checks cover the combined behavior, and the authorized operation is finished.

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

@@ -10,32 +10,22 @@ metadata:
 
 ## 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.
+Fixing a defect or review finding, or making a change whose scope should stay narrow.
 
 ## 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.
+1. State the reachable input and incorrect behavior, or the requested outcome.
+2. Trace the current path and verify the finding against the working branch.
+3. Keep edits that correct the outcome, plus supporting changes required for correctness or verification.
+4. Leave unrelated cleanup and speculative guards outside the diff.
+5. Verify the behavior through a stable public interface and map each final hunk back to the request.
 
 ## 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.
+Preserve unrelated user edits and existing style. Do not widen a public contract to accommodate an internal shortcut. Refactor only when the requested fix or its verification needs it.
 
-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.
+If an approach causes another regression, remove that approach and reconsider the cause. Avoid layering compensating changes onto a wrong fix. Keep later review rounds in separate commits when authorized; never rewrite pushed history.
 
 ## 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.
+The requested outcome works, focused verification passes, and every hunk has a reason within scope.

package/skills/testing-first/SKILL.md

@@ -11,34 +11,23 @@ metadata:
 
 ## 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.
+Following a test-first workflow for behavior that a caller can observe. Settle the intended interface before choosing 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.
+1. State one behavior as concrete input and observable output.
+2. Write a test through the narrowest stable caller interface, using an expected result obtained independently of the implementation.
+3. Run it and confirm it fails because the behavior is missing or wrong.
+4. Implement the smallest complete slice that makes it pass, including every required layer.
+5. Repeat for the next behavior once the current test is green.
+6. Run affected checks and remove code justified only by an unwritten future test.
 
 ## 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.
+Keep each cycle to one behavioral claim; several assertions can describe that outcome. Prefer real collaborators inside the module and replace dependencies only at established external boundaries.
 
-A test is tautological when it recreates the production calculation to derive the expected value. Replace the derived expectation with a result obtained independently.
+Do not weaken an assertion to make a failing implementation pass. If harmless refactoring breaks a test without changing behavior, move it to a more stable interface. Avoid recreating the production calculation to derive expected values.
 
 ## 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.
+Requested behaviors have tests observed failing first, implementation passes through public interfaces, and affected checks pass.

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

@@ -11,29 +11,22 @@ metadata:
 
 ## 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.
+Choosing coverage in proportion to a change's possible consequences.
 
 ## 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.
+1. Identify affected behavior and callers. Rank risks by consequence, likelihood, and existing coverage.
+2. Read nearby tests for the established public interface and fixture style.
+3. Cover material gaps with the smallest fixture that crosses the real failure boundary.
+4. Run focused tests and the repository checks covering affected consumers.
+5. Define any necessary manual check with its setup, action, and expected result, then report what remains unverified.
 
 ## 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.
+Prioritize state changes, permissions, persistence, parsing, routing, and public contracts. Reuse existing coverage when it already detects the regression.
 
-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.
+Skip tests that mirror private branches or assert reversible text and styling changes unless those details are a supported contract. Keep expected results independent of production calculations and avoid redundant cases for the same risk.
 
 ## 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.
+Each material risk has a meaningful automated or manual check, selected checks have run, and remaining uncertainty is explicit.