@harness-engineering/cli 1.14.0 → 1.16.0

package/dist/agents/skills/cursor/harness-product-spec/skill.yaml

@@ -0,0 +1,72 @@
+name: harness-product-spec
+version: "1.0.0"
+description: User story generation, EARS acceptance criteria, and PRD creation from issues
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+  - on_new_feature
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - emit_interaction
+cli:
+  command: harness skill run harness-product-spec
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: source
+      description: "Input source: issue URL, feature description file, or inline text"
+      required: true
+    - name: format
+      description: "Output format: prd, user-stories, acceptance-criteria, all. Defaults to all."
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-product-spec
+    path: string
+type: rigid
+tier: 3
+internal: false
+keywords:
+  - product spec
+  - user story
+  - acceptance criteria
+  - EARS
+  - PRD
+  - requirements
+  - product requirements
+  - BDD
+  - given-when-then
+  - feature specification
+stack_signals:
+  - "docs/specs/"
+  - "docs/requirements/"
+  - "specs/"
+  - ".github/ISSUE_TEMPLATE/"
+  - "docs/prd/"
+phases:
+  - name: parse
+    description: Extract feature intent, stakeholders, and constraints from input source
+    required: true
+  - name: craft
+    description: Generate user stories with EARS acceptance criteria and edge cases
+    required: true
+  - name: generate
+    description: Produce PRD document with scope, requirements, and success metrics
+    required: true
+  - name: validate
+    description: Verify completeness, testability of acceptance criteria, and traceability to source
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/harness-property-test/SKILL.md

@@ -0,0 +1,281 @@
+# Harness Property Test
+
+> Property-based and generative testing with fast-check, hypothesis, and automatic shrinking. Discovers edge cases that example-based tests miss by generating thousands of random inputs and verifying invariants hold for all of them.
+
+## When to Use
+
+- Testing functions with large input spaces (parsers, serializers, encoders, validators)
+- Verifying mathematical or algebraic properties (commutativity, associativity, round-trip encoding)
+- Finding edge cases in data transformation, sorting, or filtering logic
+- NOT when testing UI rendering or visual output (use harness-visual-regression instead)
+- NOT when testing simple CRUD operations with well-defined inputs (use harness-tdd instead)
+- NOT when testing external service integrations (use harness-integration-test instead)
+
+## Process
+
+### Phase 1: IDENTIFY -- Discover Testable Properties and Invariants
+
+1. **Catalog candidate functions.** Search for functions that exhibit testable properties:
+   - **Pure functions** with deterministic output for given input
+   - **Serializers/deserializers** where `decode(encode(x)) === x` (round-trip property)
+   - **Sorting/filtering** where output maintains invariants (sorted order, subset relationship)
+   - **Validators** where valid input always passes and specific invalid inputs always fail
+   - **Mathematical functions** with known algebraic properties
+
+2. **Identify properties for each candidate.** Common property categories:
+   - **Round-trip:** `deserialize(serialize(x)) === x` for any valid `x`
+   - **Idempotence:** `f(f(x)) === f(x)` (applying the function twice gives the same result)
+   - **Invariant preservation:** output always satisfies a postcondition regardless of input
+   - **Commutativity:** `f(a, b) === f(b, a)` for operations where order should not matter
+   - **No-crash (robustness):** function does not throw for any input in the domain
+   - **Monotonicity:** if `a <= b`, then `f(a) <= f(b)` for order-preserving functions
+   - **Equivalence:** `fastImpl(x) === referenceImpl(x)` for optimized implementations
+
+3. **Define input domains.** For each property, specify:
+   - The type and range of valid inputs
+   - Constraints that inputs must satisfy (e.g., non-empty arrays, positive integers)
+   - Edge cases that the generator should emphasize (empty strings, zero, max int, Unicode)
+
+4. **Prioritize by risk.** Focus property tests on:
+   - Functions where bugs have high business impact
+   - Functions with complex branching logic
+   - Functions that have had historical bugs or regression issues
+
+5. **Report findings.** List candidate functions, their properties, and the expected generator configuration.
+
+### Phase 2: DEFINE -- Write Property Specifications and Custom Generators
+
+1. **Select the property testing framework.** Based on the project's language:
+   - **TypeScript/JavaScript:** fast-check
+   - **Python:** hypothesis
+   - **Rust:** proptest or quickcheck
+   - **Scala:** ScalaCheck
+   - **Haskell:** QuickCheck
+   - **Java/Kotlin:** jqwik
+
+2. **Define custom generators (arbitraries) for domain types.** For each domain model:
+   - Build a generator that produces valid instances with realistic field values
+   - Add constraints matching the model's validation rules
+   - Compose generators for nested structures using `map`, `flatMap`, and `filter`
+
+3. **Write property test specifications.** For each property identified in Phase 1:
+   - State the property as a universally quantified assertion: "For all inputs X satisfying constraint C, property P holds"
+   - Use the framework's property definition syntax
+   - Configure iteration count (default: 100 iterations for fast properties, 1000 for critical properties)
+
+4. **Configure shrinking.** Ensure the framework's automatic shrinking is enabled:
+   - Shrinking reduces failing inputs to the minimal counterexample
+   - Custom generators should support shrinking (use `map` over `filter` where possible, since `filter` breaks shrinking)
+   - Set a shrink limit to prevent infinite shrinking on complex inputs
+
+5. **Write seed values for reproducibility.** Configure:
+   - A fixed seed for CI to ensure deterministic reruns
+   - Seed logging so that any failure can be reproduced exactly
+   - Replay capability: failed seeds are stored and replayed on subsequent runs
+
+### Phase 3: EXECUTE -- Run Property Tests and Collect Counterexamples
+
+1. **Run property tests with verbose output.** Execute the test suite and observe:
+   - Number of test cases generated per property
+   - Any counterexamples found (failing inputs)
+   - Shrinking progress (how the framework reduces counterexamples)
+
+2. **Analyze counterexamples.** For each failing property:
+   - Read the shrunk counterexample -- this is the minimal input that violates the property
+   - Understand why this input causes a failure
+   - Classify: is this a real bug, or is the property specification too strict?
+
+3. **Reproduce counterexamples deterministically.** For each counterexample:
+   - Record the failing seed value
+   - Write an explicit example-based test using the shrunk counterexample as a regression test
+   - This regression test serves as documentation and prevents the same bug from recurring
+
+4. **Handle flaky property tests.** If a property test fails intermittently:
+   - Increase the iteration count to reproduce more reliably
+   - Check if the property is sensitive to floating-point precision
+   - Verify that the generator does not produce inputs outside the valid domain
+
+5. **Iterate on generator quality.** If the generator frequently produces uninteresting inputs:
+   - Add bias toward edge cases (empty collections, boundary values)
+   - Use `filter` sparingly (it discards inputs, wasting iterations)
+   - Prefer `map` and `flatMap` to construct valid inputs directly
+
+### Phase 4: ANALYZE -- Diagnose Root Causes and Harden Implementations
+
+1. **Fix bugs exposed by counterexamples.** For each real bug found:
+   - Understand the root cause using the minimal counterexample
+   - Fix the implementation
+   - Verify the property now holds (rerun with the same seed)
+   - Keep the regression test with the explicit counterexample
+
+2. **Strengthen property specifications.** After fixing bugs:
+   - Consider whether additional properties are now testable
+   - Tighten existing properties if the fix enables stricter invariants
+   - Add properties for edge cases revealed by the counterexamples
+
+3. **Measure property test effectiveness.** Evaluate:
+   - Number of unique bugs found by property tests vs. example-based tests
+   - Types of bugs found (off-by-one, overflow, Unicode handling, null handling)
+   - Generator coverage: what percentage of the input domain is being explored
+
+4. **Integrate property tests into CI.** Configure:
+   - Property tests run on every PR with a moderate iteration count (100)
+   - Nightly runs use a higher iteration count (10,000) for deeper exploration
+   - Failed seeds are stored as artifacts for reproduction
+
+5. **Run `harness validate`.** Confirm the project passes all harness checks with property tests in place.
+
+### Graph Refresh
+
+If a knowledge graph exists at `.harness/graph/`, refresh it after code changes to keep graph queries accurate:
+
+```
+harness scan [path]
+```
+
+## Harness Integration
+
+- **`harness validate`** -- Run in ANALYZE phase after property tests are written and bugs are fixed. Confirms project health.
+- **`harness check-deps`** -- Run after DEFINE phase to verify property testing framework is in devDependencies.
+- **`emit_interaction`** -- Used to present counterexample analysis and property specification decisions to the human.
+- **Grep** -- Used in IDENTIFY phase to find pure functions, serializers, validators, and mathematical operations.
+- **Glob** -- Used to catalog existing property test files and domain type definitions.
+
+## Success Criteria
+
+- Every function with large input space has at least one property test
+- Custom generators produce valid domain objects without relying heavily on `filter`
+- All counterexamples are investigated: real bugs are fixed, property specs are adjusted for false positives
+- Shrunk counterexamples are preserved as explicit regression tests
+- Property tests are deterministic in CI (fixed seed) while still exploring randomly in local development
+- `harness validate` passes with property tests in place
+
+## Examples
+
+### Example: fast-check for a TypeScript URL Parser
+
+**IDENTIFY -- Properties of a URL parser:**
+
+```
+Function: parseUrl(input: string): ParsedUrl
+Properties:
+  1. Round-trip: formatUrl(parseUrl(url)) === url for any valid URL
+  2. No-crash: parseUrl(arbitrary_string) never throws (returns Result type)
+  3. Invariant: parsed.protocol is always lowercase
+  4. Invariant: parsed.host never contains a trailing slash
+```
+
+**DEFINE -- Custom generator and property tests:**
+
+```typescript
+// tests/property/url-parser.prop.test.ts
+import fc from 'fast-check';
+import { parseUrl, formatUrl } from '../../src/url-parser';
+
+// Custom generator for valid URLs
+const urlArb = fc
+  .record({
+    protocol: fc.constantFrom('http', 'https', 'ftp'),
+    host: fc.domain(),
+    port: fc.option(fc.integer({ min: 1, max: 65535 }), { nil: undefined }),
+    path: fc
+      .array(
+        fc.stringOf(fc.constantFrom(...'abcdefghijklmnopqrstuvwxyz0123456789-_'.split('')), {
+          minLength: 1,
+        })
+      )
+      .map((segments) => '/' + segments.join('/')),
+  })
+  .map(({ protocol, host, port, path }) => `${protocol}://${host}${port ? ':' + port : ''}${path}`);
+
+describe('URL parser properties', () => {
+  it('round-trips valid URLs', () => {
+    fc.assert(
+      fc.property(urlArb, (url) => {
+        const parsed = parseUrl(url);
+        if (!parsed.ok) return false; // skip invalid (generator should not produce these)
+        return formatUrl(parsed.value) === url;
+      }),
+      { numRuns: 1000, seed: 42 }
+    );
+  });
+
+  it('never throws on arbitrary string input', () => {
+    fc.assert(
+      fc.property(fc.string(), (input) => {
+        const result = parseUrl(input);
+        // Must return a Result, never throw
+        return result.ok === true || result.ok === false;
+      }),
+      { numRuns: 5000 }
+    );
+  });
+
+  it('always produces lowercase protocol', () => {
+    fc.assert(
+      fc.property(urlArb, (url) => {
+        const parsed = parseUrl(url.toUpperCase());
+        if (!parsed.ok) return true; // skip failures
+        return parsed.value.protocol === parsed.value.protocol.toLowerCase();
+      })
+    );
+  });
+});
+```
+
+### Example: hypothesis for a Python Sorting Algorithm
+
+**DEFINE -- Property tests with hypothesis:**
+
+```python
+# tests/property/test_sort_properties.py
+from hypothesis import given, settings, assume
+from hypothesis import strategies as st
+from myapp.sorting import merge_sort
+
+@given(st.lists(st.integers()))
+def test_sort_preserves_length(xs):
+    """Sorted output has the same length as input."""
+    assert len(merge_sort(xs)) == len(xs)
+
+@given(st.lists(st.integers()))
+def test_sort_preserves_elements(xs):
+    """Sorted output contains exactly the same elements as input."""
+    assert sorted(merge_sort(xs)) == sorted(xs)
+
+@given(st.lists(st.integers(), min_size=1))
+def test_sort_produces_ordered_output(xs):
+    """Every element is less than or equal to the next."""
+    result = merge_sort(xs)
+    for i in range(len(result) - 1):
+        assert result[i] <= result[i + 1]
+
+@given(st.lists(st.integers()))
+def test_sort_is_idempotent(xs):
+    """Sorting an already-sorted list produces the same result."""
+    once = merge_sort(xs)
+    twice = merge_sort(once)
+    assert once == twice
+
+@settings(max_examples=5000)
+@given(st.lists(st.floats(allow_nan=False, allow_infinity=False)))
+def test_sort_handles_floats(xs):
+    """Sort works correctly with floating-point numbers."""
+    result = merge_sort(xs)
+    for i in range(len(result) - 1):
+        assert result[i] <= result[i + 1]
+```
+
+## Gates
+
+- **No property tests without shrinking.** If the framework's automatic shrinking is disabled or the generator uses patterns that break shrinking (excessive `filter`), counterexamples will be unhelpfully large. Fix the generator to support shrinking.
+- **No ignoring counterexamples.** Every counterexample produced by a property test must be investigated. If it reveals a real bug, fix it. If it is a false positive, adjust the property specification or generator. Never just increase the iteration count to make it "less likely to fail."
+- **No property tests that always pass trivially.** A property that returns `true` for every input is useless. Review that properties make substantive assertions. If a property has a `return true` fallback for most inputs, the generator is producing too many invalid inputs.
+- **Regression tests are mandatory for counterexamples.** Every shrunk counterexample that revealed a bug must be preserved as an explicit example-based test, even after the property test passes. The explicit test serves as documentation and prevents regression.
+
+## Escalation
+
+- **When the generator cannot produce valid inputs efficiently (> 50% rejection rate):** Rewrite the generator to construct valid inputs directly rather than filtering. Use `flatMap` to build constrained structures incrementally. If the domain constraints are too complex for a generator, consider whether the function's API needs simplification.
+- **When a counterexample is too complex to understand even after shrinking:** The shrinking strategy may be insufficient for the data type. Write a custom shrinker that targets the specific structure. Alternatively, add intermediate logging to the property to trace which sub-property fails.
+- **When property tests are too slow for CI (> 5 minutes):** Reduce the iteration count for PR runs (100 iterations). Run high-iteration tests (10,000+) as a nightly job. Consider whether some properties can be tested with smaller input ranges without losing coverage.
+- **When the team debates whether a property is correct:** The property may be encoding an assumption that does not hold. Review the specification or domain requirements. If the correct behavior is ambiguous, escalate to product/domain experts before encoding the property in a test.

package/dist/agents/skills/cursor/harness-property-test/skill.yaml

@@ -0,0 +1,71 @@
+name: harness-property-test
+version: "1.0.0"
+description: Property-based and generative testing with fast-check, hypothesis, and automatic shrinking
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+  - on_new_feature
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - emit_interaction
+cli:
+  command: harness skill run harness-property-test
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: framework
+      description: "Property testing framework: fast-check, hypothesis, proptest, or quickcheck. Auto-detected when omitted."
+      required: false
+    - name: target
+      description: "Target function or module for property test generation."
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-property-test
+    path: string
+type: rigid
+tier: 3
+internal: false
+keywords:
+  - property-based testing
+  - generative testing
+  - fast-check
+  - hypothesis
+  - proptest
+  - QuickCheck
+  - fuzzing
+  - shrinking
+  - arbitrary
+  - invariant
+stack_signals:
+  - "src/**/*property*"
+  - "tests/property/"
+  - "src/**/*.prop.*"
+  - "tests/**/properties/"
+phases:
+  - name: identify
+    description: Analyze functions and data types to discover testable properties and invariants
+    required: true
+  - name: define
+    description: Define property specifications, custom generators, and shrinking strategies
+    required: true
+  - name: execute
+    description: Run property tests with sufficient iterations and collect counterexamples
+    required: true
+  - name: analyze
+    description: Interpret shrunk counterexamples, diagnose root causes, and harden implementations
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/harness-refactoring/SKILL.md

@@ -0,0 +1,169 @@
+# Harness Refactoring
+
+> Safe refactoring with constraint verification at every step. Change structure without changing behavior, with harness checks as your safety net.
+
+## When to Use
+
+- When improving code structure, readability, or maintainability without changing behavior
+- When reducing duplication (DRY refactoring)
+- When moving code to the correct architectural layer
+- When splitting large files or functions into smaller, focused ones
+- When renaming for clarity across the codebase
+- After completing a feature (post-TDD cleanup beyond single-cycle refactoring)
+- NOT when adding new behavior (use harness-tdd instead)
+- NOT when fixing bugs (use harness-tdd — write a failing test first)
+- NOT when the test suite is already failing — fix the tests before refactoring
+
+## Process
+
+### Iron Rule
+
+**All tests must pass BEFORE you start refactoring and AFTER every single change.**
+
+If tests are not green before you start, you are not refactoring — you are debugging. Fix the tests first. If tests break during refactoring, undo the last change immediately. Do not try to fix forward.
+
+### Phase 1: Prepare — Verify Starting State
+
+1. **Run the full test suite.** Every test must pass. Record the count of passing tests — this number must not decrease at any point.
+
+2. **Run `harness validate`** and **`harness check-deps`**. Both must pass. You are establishing a clean baseline. If either reports issues, fix those first (that is a separate task, not part of this refactoring).
+
+3. **Identify the refactoring target.** Be specific: which file, function, class, or module? What is wrong with the current structure? What will be better after refactoring?
+
+4. **Plan the steps.** Break the refactoring into the smallest possible individual changes. Each step should be independently committable and verifiable. If you cannot describe a step in one sentence, it is too large.
+
+### Graph-Enhanced Context (when available)
+
+When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate context:
+
+- `get_impact` — precise impact analysis: "if I move this function, what breaks?"
+- `query_graph` — find all transitive consumers, not just direct importers
+
+Catches indirect consumers that grep misses. Fall back to file-based commands if no graph is available.
+
+### Phase 2: Execute — One Small Change at a Time
+
+For EACH step in the plan:
+
+1. **Make ONE small change.** Examples of "one small change":
+   - Rename one variable or function
+   - Extract one function from a larger function
+   - Move one function to a different file
+   - Inline one unnecessary abstraction
+   - Replace one conditional with polymorphism
+   - Remove one instance of duplication
+
+2. **Run the full test suite.** All tests must pass. If any test fails:
+   - **STOP immediately.**
+   - **Undo the change** (git checkout the file or revert manually).
+   - **Analyze why it broke.** Either the change was not purely structural (it changed behavior) or the tests are coupled to implementation details.
+   - **Try a smaller step** or a different approach.
+
+3. **Run `harness validate` and `harness check-deps`.** Both must pass. A refactoring that fixes code structure but violates architectural constraints is not safe.
+
+4. **Commit the step.** Each step gets its own commit. The commit message describes the structural change: "extract validateInput from processOrder" or "move UserRepository to data-access layer."
+
+5. **Repeat** for the next step in the plan.
+
+### Phase 3: Verify — Confirm the Refactoring is Complete
+
+1. **Run the full test suite one final time.** Same number of passing tests as Phase 1.
+
+2. **Run `harness validate` and `harness check-deps` one final time.** Clean output.
+
+### Graph Refresh
+
+If a knowledge graph exists at `.harness/graph/`, refresh it after code changes to keep graph queries accurate:
+
+```
+harness scan [path]
+```
+
+Skipping this step means subsequent graph queries (impact analysis, dependency health, test advisor) may return stale results.
+
+3. **Review the cumulative diff.** Does the final state match the intended improvement? Is the code genuinely better, or just different?
+
+4. **If the refactoring introduced no improvement,** revert the entire sequence. Refactoring for its own sake is churn.
+
+## Common Refactoring Patterns
+
+### Extract Function
+
+**When:** A function is doing too many things, or a block of code is reused in multiple places.
+**How:** Identify the block. Ensure all variables it uses are either parameters or local. Cut the block into a new function with a descriptive name. Replace the original block with a call to the new function.
+**Harness guidance:** If the extracted function belongs in a different layer, move it there AND update the import. Run `harness check-deps` to verify the new import respects layer boundaries.
+
+### Move to Layer
+
+**When:** Code is in the wrong architectural layer (e.g., business logic in a UI component, database queries in a service).
+**How:** Create the function in the correct layer. Update all callers to import from the new location. Delete the old function. Run `harness check-deps` after each step.
+**Harness guidance:** This is where `harness check-deps` is most valuable. Moving code between layers changes the dependency graph. The tool will tell you immediately if the move created a violation.
+
+### Split File
+
+**When:** A file has grown too large or contains unrelated responsibilities.
+**How:** Identify the cohesive groups within the file. Create new files, one per group. Move functions/classes to their new files. Update the original file to re-export from the new files (for backward compatibility) or update all callers.
+**Harness guidance:** Run `harness validate` after splitting to ensure the new files follow naming conventions and are properly structured. Run `harness check-deps` to verify no new boundary violations.
+
+### Inline Abstraction
+
+**When:** An abstraction (class, interface, wrapper function) adds complexity without value. It has only one implementation, is never extended, and obscures what the code actually does.
+**How:** Replace uses of the abstraction with the concrete implementation. Delete the abstraction. Run tests.
+**Harness guidance:** Removing an abstraction may expose a layer violation that the abstraction was hiding. Run `harness check-deps` to check.
+
+### Rename for Clarity
+
+**When:** A name is misleading, ambiguous, or no longer reflects what the code does.
+**How:** Use your editor's rename/refactor tool to change the name everywhere it appears. If the name is part of a public API, check for external consumers first.
+**Harness guidance:** Run `harness check-docs` after renaming to detect documentation that still uses the old name. AGENTS.md, inline comments, and doc pages may all need updating.
+
+## Harness Integration
+
+- **`harness validate`** — Run before starting, after each step, and at the end. Catches structural issues, naming violations, and configuration drift.
+- **`harness check-deps`** — Run after each step, especially when moving code between files or layers. Catches dependency violations introduced by structural changes.
+- **`harness check-docs`** — Run after renaming or moving public APIs. Catches documentation that references old names or locations.
+- **`harness cleanup`** — Run after completing a refactoring sequence. Detects dead code that the refactoring may have created (unused exports, orphaned files).
+
+## Success Criteria
+
+- All tests pass before, during, and after refactoring (same count, same results)
+- `harness validate` passes at every step
+- `harness check-deps` passes at every step
+- Each step is an atomic commit with a clear structural description
+- The code is measurably better after refactoring (clearer names, less duplication, correct layering, smaller functions)
+- No behavioral changes were introduced (the test suite is the proof)
+- No dead code was left behind (run `harness cleanup` to verify)
+
+## Examples
+
+### Example: Moving business logic out of a UI component
+
+**Target:** `src/components/OrderSummary.tsx` contains a `calculateDiscount()` function with complex business rules. This logic belongs in the service layer.
+
+**Step 1:** Create `src/services/discount-service.ts` with the `calculateDiscount` function copied from the component.
+
+- Run tests: pass
+- Run `harness check-deps`: pass (new file, no violations)
+- Commit: "extract calculateDiscount to discount-service"
+
+**Step 2:** Update `OrderSummary.tsx` to import `calculateDiscount` from `discount-service` instead of using the local function.
+
+- Run tests: pass
+- Run `harness check-deps`: pass (UI importing from service is allowed)
+- Commit: "update OrderSummary to use discount-service"
+
+**Step 3:** Delete the original `calculateDiscount` function from `OrderSummary.tsx`.
+
+- Run tests: pass
+- Run `harness check-deps`: pass
+- Run `harness cleanup`: no dead code detected
+- Commit: "remove duplicate calculateDiscount from OrderSummary"
+
+**Final verification:** 3 steps, 3 commits, all tests green throughout, all harness checks passing. The business logic is now in the correct layer.
+
+## Escalation
+
+- **When tests fail during refactoring and you cannot figure out why:** Revert to the last green commit. The test failure means the change was not purely structural. Analyze the test to understand what behavioral assumption it depends on, then plan a different approach.
+- **When `harness check-deps` fails after a move:** The code you moved may have dependencies that are not allowed in its new layer. You may need to refactor the moved code itself (remove forbidden imports) before it can live in the new layer.
+- **When a refactoring requires changing tests:** This is a warning sign. If the tests need to change, the refactoring may be changing behavior. The only valid reason to change tests during refactoring is if the tests were testing implementation details (not behavior) — and in that case, fix the tests first as a separate step before refactoring.
+- **When the refactoring scope keeps growing:** Stop. Commit what you have (if it is clean). Re-plan with a smaller scope. Large refactorings should be broken into multiple sessions, each leaving the code in a better state.

package/dist/agents/skills/cursor/harness-refactoring/skill.yaml

@@ -0,0 +1,34 @@
+name: harness-refactoring
+version: "1.0.0"
+description: Safe refactoring with validation before and after changes
+cognitive_mode: meticulous-implementer
+triggers:
+  - manual
+  - on_refactor
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-refactoring
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-refactoring
+    path: string
+type: flexible
+tier: 1
+state:
+  persistent: false
+  files: []
+depends_on: []