@harness-engineering/cli 1.14.0 → 1.16.0

package/dist/agents/commands/cursor/harness/harness-supply-chain-audit.mdc

@@ -0,0 +1,252 @@
+---
+description: 6-factor dependency risk evaluation for supply chain security
+alwaysApply: false
+---
+
+<!-- Generated by harness generate-slash-commands. Do not edit. -->
+
+# Harness Supply Chain Audit
+
+> 6-factor dependency risk evaluation adapted from Trail of Bits security skill patterns. Surfaces dependency risk flags for human review — not automated verdicts.
+
+## When to Use
+
+- Before a major release to assess dependency risk
+- After adding new dependencies
+- During security audits or compliance reviews
+- When `on_milestone` trigger fires (part of release gate)
+- NOT as a replacement for `npm audit` — this complements it with risk signals beyond CVEs
+- NOT for license compliance (separate concern)
+
+## Iron Law
+
+**Present findings as flags for human review, never as verdicts.** A dependency flagged as "high risk" may be entirely appropriate for a project. The skill surfaces signals; humans decide whether to act.
+
+---
+
+## Process
+
+### Phase 1: INVENTORY — Build Dependency List
+
+1. **Resolve project root.** Use the path argument or default to the current directory.
+
+2. **Detect lockfile.** Check for the following in order:
+   - `package-lock.json` (npm)
+   - `pnpm-lock.yaml` (pnpm)
+   - `yarn.lock` (yarn)
+   - If none found: report "No lockfile detected. Run `npm install` first." and stop.
+
+3. **Parse direct dependencies** from `package.json`:
+   - Read `dependencies` and `devDependencies`
+   - Build a list: `{ name, version, isDev }`
+
+4. **Parse transitive depth** from lockfile:
+   - For `package-lock.json`: read `packages` keys to extract the dependency tree. Nesting depth of `node_modules/` segments in keys indicates transitive depth.
+   - For `pnpm-lock.yaml`: read `importers` section for direct dependencies (keyed by workspace path, e.g., `.` for root). Each importer lists `dependencies` and `devDependencies` with version specifiers. Read `packages` section for resolved versions — keys are package identifiers (e.g., `/@scope/pkg@1.2.3`) with `resolution` (tarball URL + integrity hash) and `dependencies` sub-map for transitives.
+   - For `yarn.lock`: parse block-format entries. Each block header is `"pkg@version-range":` followed by indented fields: `version` (resolved), `resolved` (tarball URL), `integrity` (hash), and `dependencies` sub-block listing transitive deps as `"name" "version-range"` pairs.
+   - Assign each package a depth (0 = direct, 1 = first-level transitive, etc.)
+   - Flag packages with depth > 5 for transitive risk evaluation
+
+5. **Build inventory table:**
+
+   ```
+   INVENTORY: <project-name>
+   Direct dependencies: N
+   Dev dependencies: N
+   Total packages (including transitives): N
+   Deep transitive packages (depth > 5): N
+   ```
+
+6. Proceed to EVALUATE.
+
+---
+
+### Phase 2: EVALUATE — Score Dependencies on 6 Factors
+
+For each **direct dependency** (and any transitive with depth > 5), score on 6 factors:
+
+> Network access required: npm registry (`https://registry.npmjs.org/<pkg>`) and GitHub API (`https://api.github.com/repos/<owner>/<repo>`).
+>
+> - If npm registry returns 404: mark as "unresolvable", flag for manual review, skip remaining factors
+> - If GitHub API rate limits hit: score `maintenance-status` as "unknown", continue with other factors
+> - If no GitHub repo link in package metadata: skip `maintenance-status` factor, note in report
+
+#### Factor 1: Maintainer Concentration
+
+- Fetch: `GET https://registry.npmjs.org/<pkg>`
+- Check: `maintainers` array length
+- Score:
+  - **High risk:** 1 maintainer (bus factor = 1)
+  - **Medium risk:** 2-3 maintainers
+  - **Low risk:** 4+ maintainers
+
+#### Factor 2: Maintenance Status
+
+- Source: npm `time` field (last publish date) + GitHub API commit activity
+- npm: `GET https://registry.npmjs.org/<pkg>` → `time.modified`
+- GitHub: `GET https://api.github.com/repos/<owner>/<repo>/commits?per_page=1` → latest commit date
+- Score:
+  - **High risk:** Last publish > 12 months ago AND no GitHub commits in 6 months
+  - **Medium risk:** Last publish > 12 months ago OR no commits in 6 months (not both)
+  - **Low risk:** Active in both dimensions
+
+#### Factor 3: Popularity Signal
+
+- Fetch: `GET https://api.npmjs.org/downloads/point/last-week/<pkg>`
+- Score:
+  - **High risk:** < 1,000 weekly downloads
+  - **Medium risk:** 1,000–10,000 weekly downloads
+  - **Low risk:** > 10,000 weekly downloads
+  - **Note:** Low popularity is a signal, not a verdict — internal/niche packages are expected to be low
+
+#### Factor 4: Install Scripts
+
+- Read: `node_modules/<pkg>/package.json` (or lockfile-resolved path) → `scripts` field
+- Check for: `preinstall`, `postinstall`, `install`, `preuninstall`, `postuninstall`
+- Score:
+  - **High risk:** Any install script present
+  - **Low risk:** No install scripts
+  - **Note:** Some install scripts are legitimate (native addon compilation). Flag for review.
+
+#### Factor 5: Known CVEs
+
+- Run: `npm audit --json` or `pnpm audit --json`
+- Parse: map findings to their package name
+- Score:
+  - **Critical:** Any high/critical severity CVE
+  - **Medium risk:** Moderate severity CVE
+  - **Low risk:** No CVEs or low severity only
+
+#### Factor 6: Transitive Risk
+
+- Source: Lockfile depth analysis from INVENTORY phase
+- Score:
+  - **High risk:** Depth > 5 AND subtree size > 20 transitive packages
+  - **Medium risk:** Depth > 5 OR subtree size > 20
+  - **Low risk:** Depth ≤ 5 and subtree size ≤ 20
+
+#### Risk Scoring
+
+Combine factor scores into an overall risk level:
+
+| Overall Risk | Condition                                                      |
+| ------------ | -------------------------------------------------------------- |
+| **Critical** | Factor 5 is Critical (any high/critical CVE)                   |
+| **High**     | 2+ factors scored High, OR Factor 1 is High + Factor 2 is High |
+| **Medium**   | 1 factor scored High, OR 3+ factors scored Medium              |
+| **Low**      | All factors Low or at most 1 Medium                            |
+
+---
+
+### Phase 3: REPORT — Generate Risk Summary
+
+1. **Produce risk summary table** sorted by overall risk (Critical first):
+
+   ```
+   Supply Chain Audit: <project-name>
+   Date: <ISO date>
+   Packages evaluated: N direct + M deep transitives
+
+   ┌─────────────────────┬──────────┬────────────┬─────────────┬────────────┬──────┬─────────────┐
+   │ Package             │ Version  │ Maintainers│ Last Publish│ Downloads  │ CVEs │ Overall Risk│
+   ├─────────────────────┼──────────┼────────────┼─────────────┼────────────┼──────┼─────────────┤
+   │ example-pkg         │ 1.2.3    │ 1 (HIGH)   │ 18mo (HIGH) │ 500 (MED)  │ none │ HIGH        │
+   │ another-pkg         │ 2.0.0    │ 12         │ 2mo         │ 50k        │ 1 mod│ MEDIUM      │
+   └─────────────────────┴──────────┴────────────┴─────────────┴────────────┴──────┴─────────────┘
+   ```
+
+2. **Detail section for Critical and High risk packages:**
+
+   ```
+   HIGH RISK: example-pkg@1.2.3
+   ├── Maintainer concentration: 1 maintainer (bus factor = 1)
+   ├── Maintenance status: Last publish 18 months ago, no commits in 12 months
+   ├── Popularity: 500 weekly downloads
+   ├── Install scripts: none
+   ├── Known CVEs: none
+   └── Transitive risk: depth 2, subtree 4 packages
+   Recommendation: Consider replacing with a well-maintained alternative,
+   or pin the version and monitor for abandonment.
+   ```
+
+3. **Install script warnings** (any package with install scripts):
+
+   ```
+   INSTALL SCRIPTS DETECTED:
+   - node-gyp@9.4.0: postinstall — native addon compilation (likely legitimate)
+   - suspicious-pkg@1.0.0: postinstall — review script contents before trusting
+   ```
+
+4. **Summary line:**
+
+   ```
+   RESULT: 1 Critical, 2 High, 3 Medium, N Low — Review flagged items before release
+   ```
+
+5. **Output:** Print report to stdout. If `--output <file>` was passed, also write to that file.
+
+---
+
+## Gates
+
+- **Stop if no lockfile.** Do not evaluate without a lockfile — results will be unreliable.
+- **Present as flags, not verdicts.** Never state "this package is unsafe." State "this package has signals that warrant review."
+- **Do not block on API failures.** If npm registry or GitHub API is unavailable, note which factors were skipped and continue with available data.
+
+## Harness Integration
+
+- **`harness validate`** — Run after creating the skill files to verify they are properly placed.
+- **Triggers:** `on_milestone` fires this skill as part of the milestone completion checklist.
+- **Depends on:** `harness-security-scan` — run after mechanical scanning to complete the security picture.
+- **Output:** Stdout report, optionally written to file via `--output`. No state files written.
+
+## Evidence Requirements
+
+When reporting findings, cite the source for each factor:
+
+- Maintainer data: `registry.npmjs.org/<pkg>` → `maintainers` field
+- Publish date: `registry.npmjs.org/<pkg>` → `time.modified`
+- Downloads: `api.npmjs.org/downloads/point/last-week/<pkg>`
+- Install scripts: `node_modules/<pkg>/package.json` → `scripts`
+- CVEs: `npm audit --json` output
+- Depth: lockfile analysis
+
+Do not assert risk scores without citing the specific data point that generated the score.
+
+## Success Criteria
+
+- Running `/harness:supply-chain-audit` on a project with dependencies outputs a risk table with all 6 factors scored
+- A dependency with a sole maintainer and no commits in 12 months scores "high risk"
+- A dependency with a `postinstall` script is flagged in the install scripts section
+- API failures produce "unknown" scores with a note, not errors that stop the audit
+- All findings are framed as flags for human review, not automated verdicts
+
+## Example Output
+
+```
+Supply Chain Audit: my-project
+Date: 2026-03-31
+Packages evaluated: 24 direct + 3 deep transitives (depth > 5)
+
+CRITICAL (1):
+  lodash@4.17.20 — CVE-2021-23337 (high severity, unpatched)
+
+HIGH (2):
+  abandoned-util@0.9.1 — sole maintainer, last publish 22 months ago
+  sketchy-helper@2.1.0 — sole maintainer, postinstall script detected
+
+MEDIUM (3):
+  small-lib@1.0.0 — 800 weekly downloads (low popularity signal)
+  ...
+
+LOW (18): no significant risk signals
+
+INSTALL SCRIPTS:
+  node-gyp@9.4.0 — postinstall (native compilation, likely legitimate)
+  sketchy-helper@2.1.0 — postinstall (REVIEW: contents unknown)
+
+RESULT: 1 Critical, 2 High, 3 Medium, 18 Low
+Next steps: Update lodash to patch CVE. Review sketchy-helper postinstall script.
+Consider alternatives to abandoned-util.
+```
+

package/dist/agents/commands/cursor/harness/harness-tdd.mdc

@@ -0,0 +1,185 @@
+---
+description: Test-driven development integrated with harness validation
+alwaysApply: false
+---
+
+<!-- Generated by harness generate-slash-commands. Do not edit. -->
+
+# Harness TDD
+
+> Red-green-refactor cycle integrated with harness validation. No production code exists without a failing test first.
+
+## When to Use
+
+- Implementing any new feature, function, module, or component
+- Fixing any bug (write a test that reproduces the bug first)
+- Adding behavior to existing code
+- When `on_new_feature` or `on_bug_fix` triggers fire
+- NOT when doing pure refactoring with existing test coverage (use harness-refactoring instead)
+- NOT when writing documentation, configuration, or non-behavioral files
+- NOT when spiking/prototyping (but convert spikes to TDD before merging)
+
+## Process
+
+### Iron Law
+
+**No production code may exist without a failing test that demanded its creation.**
+
+If you find yourself writing production code first, STOP. Delete it. Write the test first. This is not a guideline — it is a hard constraint.
+
+### Phase 1: RED — Write a Failing Test
+
+1. **Identify the smallest behavior to test.** One assertion per test. One behavior per cycle. If you are testing two things, split into two cycles.
+
+2. **Write the test file or add to the appropriate test file.** Follow the project's existing test conventions (file naming, framework, location).
+
+3. **Write ONE minimal test** that asserts the expected behavior. The test should:
+   - Have a clear, descriptive name that states what behavior is expected
+   - Set up only the minimal fixtures needed
+   - Make a single assertion about the expected outcome
+   - NOT test implementation details — test observable behavior
+
+4. **Run the test suite.** Use the project's test runner (e.g., `npx vitest run path/to/test`, `npm test`, `pytest`).
+
+5. **MANDATORY: Watch the test FAIL.** Read the failure message. Confirm it fails for the RIGHT reason — the behavior is not yet implemented, not because the test is broken. If the test passes, either the behavior already exists (skip this cycle) or the test is wrong (fix the test).
+
+6. **Record the failure.** Note the test name and failure reason. This is your contract for the GREEN phase.
+
+### Phase 2: GREEN — Write the Simplest Code to Pass
+
+1. **Write the MINIMUM production code** that makes the failing test pass. Do not write code for future tests. Do not add error handling you have not tested. Do not generalize.
+
+2. **Resist the urge to write "good" code.** The GREEN phase is about correctness, not elegance. Hardcoded values are acceptable if they pass the test. Duplication is acceptable. You will clean up in REFACTOR.
+
+3. **Run the FULL test suite** (not just the new test). All tests must pass.
+
+4. **MANDATORY: Watch the test PASS.** Read the output. Confirm all tests are green. If any test fails, fix the production code (not the tests) until all pass.
+
+5. **Do not proceed to REFACTOR if any test is red.** Fix first.
+
+### Phase 3: REFACTOR — Clean Up While Green
+
+1. **With all tests passing,** look for opportunities to improve:
+   - Remove duplication (DRY)
+   - Extract methods or functions for clarity
+   - Rename for better readability
+   - Simplify conditionals
+   - Improve structure without changing behavior
+
+2. **Run the full test suite after EVERY change.** If a test breaks during refactoring, undo the last change immediately. Refactoring must not change behavior.
+
+3. **Keep refactoring steps small.** One rename, one extraction, one simplification at a time. Run tests between each.
+
+4. **If no refactoring is needed, skip this phase.** Not every cycle requires cleanup.
+
+### Phase 4: VALIDATE — Run Harness Checks
+
+1. **Run `harness check-deps`** to verify dependency boundaries are respected. New code must not introduce forbidden imports or layer violations.
+
+2. **Run `harness validate`** to verify the full project health. This catches architectural drift, documentation gaps, and constraint violations.
+
+3. **If either check fails,** fix the issue before committing. The fix may require another RED-GREEN-REFACTOR cycle if it involves behavioral changes.
+
+4. **Commit the cycle.** Each RED-GREEN-REFACTOR-VALIDATE cycle produces one atomic commit. The commit message references what behavior was added (not "add test" — describe the behavior).
+
+### 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.
+
+### Cycle Rhythm
+
+Repeat the 4 phases for each new behavior. A typical feature requires 3-10 cycles. Each cycle should take 2-15 minutes. If a cycle takes longer than 15 minutes, the step is too large — break it down.
+
+**Ordering within a feature:**
+
+1. Start with the happy path (simplest success case)
+2. Add edge cases one at a time
+3. Add error handling cases
+4. Add integration points last
+
+## Harness Integration
+
+- **`harness check-deps`** — Run in VALIDATE phase after each cycle. Catches forbidden imports and layer boundary violations introduced by new code.
+- **`harness validate`** — Run in VALIDATE phase after each cycle. Full project health check including architecture, documentation, and constraints.
+- **`harness cleanup`** — Run periodically (every 3-5 cycles) to detect entropy accumulation. Address any issues before they compound.
+- **Test runner** — Use the project's configured test runner. Harness does not prescribe a test framework but the test must actually execute and report results.
+
+## Success Criteria
+
+- Every production function/method has at least one corresponding test
+- Every test was observed to fail before the production code was written
+- Every test was observed to pass after the production code was written
+- `harness check-deps` passes after each cycle
+- `harness validate` passes after each cycle
+- Each cycle is an atomic commit with a descriptive message
+- No test tests implementation details (only observable behavior)
+- No production code exists that was not demanded by a failing test
+
+## Examples
+
+### Example: Adding a `calculateTotal` function
+
+**RED:**
+
+```typescript
+// cart.test.ts
+it('calculates total for items with quantity and price', () => {
+  const items = [
+    { name: 'Widget', price: 10, quantity: 2 },
+    { name: 'Gadget', price: 25, quantity: 1 },
+  ];
+  expect(calculateTotal(items)).toBe(45);
+});
+```
+
+Run tests. Observe: `ReferenceError: calculateTotal is not defined`. Correct failure — function does not exist yet.
+
+**GREEN:**
+
+```typescript
+// cart.ts
+export function calculateTotal(items: Array<{ price: number; quantity: number }>): number {
+  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
+}
+```
+
+Run tests. Observe: all tests pass.
+
+**REFACTOR:** No refactoring needed for this simple function. Skip.
+
+**VALIDATE:**
+
+```bash
+harness check-deps   # Pass
+harness validate     # Pass
+git add cart.ts cart.test.ts
+git commit -m "feat(cart): calculate total from item price and quantity"
+```
+
+**Next cycle (RED):** Write a test for empty array input. Watch it fail (or pass — if it passes, the behavior is already handled). Continue.
+
+## Gates
+
+These are hard stops. Violating any gate means the process has broken down.
+
+- **Code before test = delete it.** If production code is written before a failing test exists, delete the production code and start the cycle correctly.
+- **Must watch fail.** If you did not observe the test fail with the correct failure reason, the RED phase is incomplete. Do not proceed to GREEN.
+- **Must watch pass.** If you did not observe all tests pass after writing production code, the GREEN phase is incomplete. Do not proceed to REFACTOR.
+- **No skipping VALIDATE.** Every cycle must end with `harness check-deps` and `harness validate`. Skipping creates architectural debt that compounds.
+- **No multi-behavior tests.** One test, one assertion, one behavior. Tests that assert multiple unrelated things must be split.
+- **No "I'll write tests later."** There is no later. The test comes first or the code does not get written.
+
+## Escalation
+
+- **After 3 failed attempts to make a test pass:** Stop coding. The design may be wrong. Re-examine the interface, the test assumptions, or the architecture. Consider whether the feature needs a different approach. Consult the plan or spec.
+- **When a test cannot be written without complex mocking:** This is a design smell. The code under test has too many dependencies. Refactor the existing code to be more testable before proceeding, or reconsider the abstraction boundary.
+- **When harness checks repeatedly fail:** The new code may be violating architectural constraints intentionally. Escalate to the human to decide whether to update the constraints or change the approach.
+- **When the cycle is taking more than 15 minutes:** The step is too large. Break the current behavior into smaller sub-behaviors and test each one separately.
+- **When you are unsure what to test next:** Review the spec or plan. If no spec exists, use the harness-brainstorming skill to clarify requirements before writing more tests.
+

package/dist/agents/commands/cursor/harness/harness-test-advisor.mdc

@@ -0,0 +1,168 @@
+---
+description: Graph-based test selection — answers "what tests should I run?"
+alwaysApply: false
+---
+
+<!-- Generated by harness generate-slash-commands. Do not edit. -->
+
+# Harness Test Advisor
+
+> Graph-based test selection. Answers: "I changed these files — what tests should I run?"
+
+## When to Use
+
+- Before pushing code — run only the tests that matter
+- In CI — optimize test suite execution order
+- When a test fails — understand which changes could have caused it
+- When `on_pr` triggers fire
+- NOT for writing tests (use harness-tdd)
+- NOT for test quality analysis (out of scope)
+
+## Prerequisites
+
+A knowledge graph at `.harness/graph/` enables full analysis. If no graph exists,
+the skill uses static analysis fallbacks (see Graph Availability section).
+Run `harness scan` to enable graph-enhanced analysis.
+
+### Graph Availability
+
+Before starting, check if `.harness/graph/graph.json` exists.
+
+**If graph exists:** Check staleness — compare `.harness/graph/metadata.json`
+scanTimestamp against `git log -1 --format=%ct` (latest commit timestamp).
+If graph is more than 10 commits behind (`git log --oneline <scanTimestamp>..HEAD | wc -l`),
+run `harness scan` to refresh before proceeding. (Staleness sensitivity: **Medium**)
+
+**If graph exists and is fresh (or refreshed):** Use graph tools as primary strategy.
+
+**If no graph exists:** Output "Running without graph (run `harness scan` to
+enable full analysis)" and use fallback strategies for all subsequent steps.
+
+## Process
+
+### Phase 1: PARSE — Identify Changed Files
+
+1. **From diff**: Parse `git diff --name-only` to get changed file paths.
+2. **From input**: Accept comma-separated file paths.
+3. **Filter**: Only consider `.ts`, `.tsx`, `.js`, `.jsx` files (skip docs, config).
+
+### Phase 2: DISCOVER — Find Related Tests via Graph
+
+For each changed file, use graph traversal to find test files:
+
+1. **Direct test coverage**: Use `get_impact` to find test files that import the changed file.
+
+   ```
+   get_impact(filePath="src/services/auth.ts")
+   → tests: ["tests/services/auth.test.ts", "tests/integration/auth-flow.test.ts"]
+   ```
+
+2. **Transitive test coverage**: Use `query_graph` with depth 2 to find tests that import files that import the changed file.
+
+   ```
+   query_graph(rootNodeIds=["file:src/services/auth.ts"], maxDepth=2, includeEdges=["imports"], bidirectional=true)
+   ```
+
+3. **Co-change tests**: Check `co_changes_with` edges for test files that historically change alongside the modified files.
+
+#### Fallback (without graph)
+
+When no graph is available, use naming conventions, import parsing, and git history:
+
+1. **Tier 1 — Filename convention matching**: For each changed file `foo.ts`, search for:
+   - `foo.test.ts`, `foo.spec.ts` (same directory)
+   - `__tests__/foo.ts`, `__tests__/foo.test.ts`
+   - Test files in a parallel `tests/` directory mirroring the source path
+2. **Tier 2 — Import-linked tests**: Parse test files' import statements (grep for `import.*from` in `*.test.*` and `*.spec.*` files). If a test file imports the changed file, it belongs in Tier 2 (if not already in Tier 1).
+3. **Tier 3 — Co-change correlated tests**: Use `git log --format="%H" --name-only` to find test files that frequently change in the same commit as the target file. Files that co-change in >2 commits are co-change correlated.
+4. **Rank**: Tier 1 = direct filename match, Tier 2 = import-linked tests, Tier 3 = co-change correlated tests. Output the same tiered format as the graph version.
+
+> Fallback completeness: ~80% — naming conventions and imports catch most mappings; misses dynamic imports and indirect coverage.
+
+### Phase 3: PRIORITIZE — Rank and Generate Commands
+
+Organize tests into three tiers:
+
+**Tier 1 — Must Run** (direct coverage):
+Tests that directly import or test the changed files. These are most likely to catch regressions.
+
+**Tier 2 — Should Run** (transitive coverage):
+Tests that cover code one hop away from the changed files. These catch indirect breakage.
+
+**Tier 3 — Could Run** (related):
+Tests in the same module or that co-change with the modified files. Lower probability of failure but worth running if time permits.
+
+### Output
+
+```
+## Test Advisor Report
+
+### Changed Files
+- src/services/auth.ts (modified)
+- src/types/user.ts (modified)
+
+### Tier 1 — Must Run (direct coverage)
+1. tests/services/auth.test.ts — imports auth.ts
+2. tests/types/user.test.ts — imports user.ts
+
+### Tier 2 — Should Run (transitive)
+3. tests/routes/login.test.ts — imports routes/login.ts → imports auth.ts
+4. tests/middleware/verify.test.ts — imports middleware/verify.ts → imports auth.ts
+
+### Tier 3 — Could Run (related)
+5. tests/integration/auth-flow.test.ts — same module, co-changes with auth.ts
+
+### Quick Run Command
+npx vitest run tests/services/auth.test.ts tests/types/user.test.ts tests/routes/login.test.ts tests/middleware/verify.test.ts
+
+### Full Run Command (all tiers)
+npx vitest run tests/services/auth.test.ts tests/types/user.test.ts tests/routes/login.test.ts tests/middleware/verify.test.ts tests/integration/auth-flow.test.ts
+```
+
+## Harness Integration
+
+- **`harness scan`** — Recommended before this skill for full graph-enhanced analysis. If graph is missing, skill uses naming convention and import parsing fallbacks.
+- **`harness validate`** — Run after acting on findings to verify project health.
+- **Graph tools** — This skill uses `query_graph`, `get_impact`, and `get_relationships` MCP tools.
+
+## Success Criteria
+
+- Tests prioritized into 3 tiers (Must Run, Should Run, Could Run)
+- Executable run commands generated for quick and full test runs
+- Coverage gaps flagged for changed files with no test coverage
+- Report follows the structured output format
+- All findings are backed by graph query evidence (with graph) or systematic static analysis (without graph)
+
+## Examples
+
+### Example: Selecting Tests for a Services Change
+
+```
+Input: git diff shows src/services/auth.ts and src/types/user.ts modified
+
+1. PARSE    — 2 changed files identified (both .ts)
+2. DISCOVER — get_impact(filePath="src/services/auth.ts")
+              query_graph with depth 2 for transitive tests
+              Tier 1: auth.test.ts, user.test.ts (direct imports)
+              Tier 2: login.test.ts, verify.test.ts (one hop away)
+              Tier 3: auth-flow.test.ts (co-change history)
+3. PRIORITIZE — 5 tests across 3 tiers
+
+Output:
+  Tier 1 (must run): 2 tests
+  Tier 2 (should run): 2 tests
+  Tier 3 (could run): 1 test
+  Quick command: npx vitest run auth.test.ts user.test.ts login.test.ts verify.test.ts
+  Coverage gaps: none
+```
+
+## Gates
+
+- **Graph preferred, fallback available.** If no graph exists, use naming conventions, import parsing, and git co-change analysis to identify relevant tests. Do not stop — produce the best test selection possible.
+- **Always include Tier 1.** Direct test coverage is non-negotiable — always recommend running these (whether found via graph or naming conventions).
+
+## Escalation
+
+- **When changed file has no test coverage**: Flag as a gap: "No tests found for src/services/auth.ts — consider adding tests before merging."
+- **When Tier 1 has >20 tests**: The changed file may be a hub. Suggest running Tier 1 in parallel or splitting the file.
+