@harness-engineering/cli 1.4.0 → 1.6.1

package/dist/agents/skills/claude-code/harness-release-readiness/skill.yaml

@@ -0,0 +1,57 @@
+name: harness-release-readiness
+version: "1.0.0"
+description: Audit npm release readiness, run maintenance checks, offer auto-fixes, track progress across sessions
+cognitive_mode: meticulous-verifier
+triggers:
+  - manual
+  - on_milestone
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-release-readiness
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: comprehensive
+      description: Run comprehensive checks (API docs, examples, dep health, git hygiene)
+      type: boolean
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-release-readiness
+    path: string
+type: rigid
+phases:
+  - name: audit
+    description: Run release-specific checks (packaging, docs, repo hygiene, CI/CD)
+    required: true
+  - name: maintain
+    description: Dispatch maintenance skills in parallel and collect results
+    required: true
+  - name: fix
+    description: Offer auto-remediation for fixable findings
+    required: true
+  - name: report
+    description: Generate report and persist state for session resumption
+    required: true
+state:
+  persistent: true
+  files:
+    - .harness/release-readiness.json
+depends_on:
+  - detect-doc-drift
+  - cleanup-dead-code
+  - align-documentation
+  - enforce-architecture
+  - harness-diagnostics
+  - harness-parallel-agents

package/dist/agents/skills/claude-code/harness-security-review/SKILL.md

@@ -0,0 +1,206 @@
+# Harness Security Review
+
+> Deep security audit combining mechanical scanning with AI-powered vulnerability analysis. OWASP baseline + stack-adaptive rules + optional threat modeling.
+
+## When to Use
+
+- Before a release or security-sensitive merge
+- After updating dependencies (supply chain risk)
+- When auditing a new or unfamiliar codebase
+- When `on_pr` triggers fire on security-sensitive paths
+- NOT for quick pre-commit checks (use harness-pre-commit-review for that)
+- NOT for general code review (use harness-code-review for that)
+
+## Principle: Layered Security
+
+This skill follows the Deterministic-vs-LLM Responsibility Split principle. The mechanical scanner runs first and catches what patterns can catch. The AI review then looks for semantic issues that patterns miss — user input flowing through multiple functions to a dangerous sink, missing authorization checks, logic flaws in authentication flows.
+
+## Process
+
+### Phase 1: SCAN — Mechanical Security Scanner
+
+Run the built-in security scanner against the project.
+
+1. **Run the scanner.** Use the `run_security_scan` MCP tool or invoke `SecurityScanner` directly:
+
+   ```bash
+   # Via MCP
+   harness scan --security
+
+   # Via CLI
+   npx vitest run packages/core/tests/security/
+   ```
+
+2. **Review findings.** Categorize by severity:
+   - **Error (blocking):** Must fix before merge — secrets, injection, eval, weak crypto
+   - **Warning (review):** Should fix — CORS wildcards, disabled TLS, path traversal patterns
+   - **Info (note):** Consider — HTTP URLs, missing security headers
+
+3. **Report mechanical findings.** Present each finding with:
+   - Rule ID and name
+   - File, line number, matched code
+   - Remediation guidance
+   - CWE/OWASP reference
+
+### Phase 2: REVIEW — AI-Powered Security Analysis
+
+After mechanical scanning, perform deeper AI analysis.
+
+#### OWASP Baseline (always runs)
+
+Review the codebase against OWASP Top 10 and CWE Top 25:
+
+1. **Injection (CWE-89, CWE-78, CWE-79):** Look for user input flowing to SQL queries, shell commands, or HTML output without sanitization. Trace data flow across function boundaries — patterns only catch single-line issues.
+
+2. **Broken Authentication (CWE-287):** Check for weak session management, missing MFA enforcement, hardcoded credentials, predictable tokens.
+
+3. **Sensitive Data Exposure (CWE-200):** Look for PII logged to console/files, sensitive data in error messages, missing encryption for data at rest or in transit.
+
+4. **Broken Access Control (CWE-862):** Check for missing authorization on API endpoints, IDOR vulnerabilities, privilege escalation paths.
+
+5. **Security Misconfiguration (CWE-16):** Check for debug mode in production configs, default credentials, overly permissive CORS, missing security headers.
+
+#### Stack-Adaptive Review (based on detected tech)
+
+After the OWASP baseline, add stack-specific checks:
+
+- **Node.js:** Prototype pollution via `Object.assign` or spread on user input, `__proto__` injection, unhandled promise rejections exposing stack traces
+- **Express:** Missing helmet, rate limiting, CSRF protection, body parser limits
+- **React:** XSS via `dangerouslySetInnerHTML`, sensitive data in client state, insecure `postMessage` listeners
+- **Go:** Race conditions in concurrent handlers, `unsafe.Pointer` usage, format string injection
+
+### Phase 3: THREAT-MODEL (optional, `--deep` flag)
+
+When invoked with `--deep`, build a lightweight threat model:
+
+1. **Identify entry points.** Find all HTTP routes, API endpoints, message handlers, CLI commands, and file upload handlers.
+
+2. **Map trust boundaries.** Where does data cross from untrusted (user input, external APIs) to trusted (database queries, file system, internal services)?
+
+3. **Trace data flows.** For each entry point, trace how user-controlled data flows through the system. Use the knowledge graph if available (`query_graph`, `get_relationships`).
+
+4. **Identify threat scenarios.** For each trust boundary crossing, ask:
+   - What if this input is malicious?
+   - What is the worst-case impact?
+   - What controls are in place?
+
+5. **Report threat model.** Present as a table:
+   | Entry Point | Data Flow | Trust Boundary | Threats | Controls | Risk |
+   |-------------|-----------|----------------|---------|----------|------|
+
+### Phase 4: REPORT — Consolidated Findings
+
+Produce a unified security report:
+
+```
+Security Review: [PASS/WARN/FAIL]
+
+Mechanical Scanner:
+- Scanned: N files, M rules applied
+- Coverage: baseline/enhanced
+- Errors: N | Warnings: N | Info: N
+
+[List each finding with rule ID, file:line, severity, and remediation]
+
+AI Review:
+- OWASP Baseline: [findings or "No issues found"]
+- Stack-Adaptive ([detected stacks]): [findings or "No issues found"]
+
+[If --deep]
+Threat Model:
+- Entry points: N
+- Trust boundaries: N
+- High-risk flows: [list]
+```
+
+## Harness Integration
+
+- **`run_security_scan` MCP tool** — Run the mechanical scanner programmatically
+- **`harness validate`** — Standard project health check
+- **`query_graph` / `get_relationships`** — Used in threat modeling phase for data flow tracing
+- **`get_impact`** — Understand blast radius of security-sensitive changes
+
+## Gates
+
+- **Mechanical scanner must run before AI review.** The scanner catches what patterns can catch; AI reviews what remains.
+- **Error-severity findings are blocking.** The report must be FAIL if any error-severity finding exists.
+- **AI review must reference specific code.** No vague warnings like "consider improving security." Every finding must point to a file, line, and specific issue.
+- **Threat model is optional.** Only runs with `--deep`. Do not run it unless explicitly requested.
+
+## Success Criteria
+
+- Mechanical scanner ran and produced findings (or confirmed clean)
+- AI review covered OWASP Top 10 baseline
+- Stack-adaptive checks matched the detected technology
+- Every finding includes file, line, CWE reference, and remediation
+- Report follows the structured format
+- Error-severity findings result in FAIL status
+
+## Escalation
+
+- **Scanner finds secrets in committed code:** Flag immediately. Recommend rotating the compromised credentials. This is urgent regardless of other findings.
+- **AI review finds a critical vulnerability (RCE, SQLi, auth bypass):** Mark as blocking. Do not approve the PR. Provide exact remediation code.
+- **Conflict between scanner and AI review:** If the scanner flags something the AI thinks is a false positive, include both perspectives in the report. Let the human decide.
+- **Scope too large for meaningful review:** If the project has >1000 source files, recommend scoping the review to changed files or a specific subsystem.
+
+## Examples
+
+### Example: Clean Scan
+
+```
+Security Review: PASS
+
+Mechanical Scanner:
+- Scanned: 42 files, 22 rules applied
+- Coverage: baseline
+- Errors: 0 | Warnings: 0 | Info: 0
+
+AI Review:
+- OWASP Baseline: No issues found
+- Stack-Adaptive (node, express): No issues found
+```
+
+### Example: Findings Detected
+
+```
+Security Review: FAIL
+
+Mechanical Scanner:
+- Scanned: 42 files, 22 rules applied
+- Coverage: baseline
+- Errors: 2 | Warnings: 1 | Info: 0
+
+Findings:
+1. [SEC-SEC-002] ERROR src/config.ts:12 — Hardcoded API key or secret detected
+   Remediation: Use environment variables: process.env.API_KEY
+2. [SEC-INJ-002] ERROR src/db.ts:45 — SQL query built with string concatenation
+   Remediation: Use parameterized queries: query("SELECT * FROM users WHERE id = $1", [id])
+3. [SEC-NET-001] WARNING src/cors.ts:8 — CORS wildcard origin allows any website to make requests
+   Remediation: Restrict CORS to specific trusted origins
+
+AI Review:
+- OWASP Baseline: 1 finding — user input from req.params.id flows through formatQuery() to db.execute() without sanitization (confirms SEC-INJ-002 with data flow trace)
+- Stack-Adaptive (node, express): Missing helmet middleware, missing rate limiting on /api/* routes
+```
+
+### Example: Deep Audit with Threat Model
+
+```
+Security Review: WARN
+
+Mechanical Scanner:
+- Scanned: 120 files, 30 rules applied
+- Coverage: baseline
+- Errors: 0 | Warnings: 2 | Info: 3
+
+AI Review:
+- OWASP Baseline: No critical issues
+- Stack-Adaptive (node, react): localStorage used for session token (SEC-REACT-001)
+
+Threat Model:
+- Entry points: 12 (8 REST endpoints, 2 WebSocket handlers, 2 CLI commands)
+- Trust boundaries: 4 (client→API, API→database, API→external service, CLI→filesystem)
+- High-risk flows:
+  1. POST /api/upload → file stored to disk without size limit or type validation
+  2. WebSocket message handler passes user data to eval-like template engine
+```

package/dist/agents/skills/claude-code/harness-security-review/skill.yaml

@@ -0,0 +1,50 @@
+name: harness-security-review
+version: "1.0.0"
+description: Deep security audit with OWASP baseline and stack-adaptive analysis
+cognitive_mode: meticulous-implementer
+triggers:
+  - manual
+  - on_pr
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-security-review
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: deep
+      description: Enable threat modeling phase
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-security-review
+    path: string
+type: rigid
+phases:
+  - name: scan
+    description: Run mechanical security scanner
+    required: true
+  - name: review
+    description: AI-powered security review (OWASP + stack-adaptive)
+    required: true
+  - name: threat-model
+    description: Lightweight threat model from codebase graph
+    required: false
+  - name: report
+    description: Generate findings report with remediation guidance
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on:
+  - harness-code-review

package/dist/agents/skills/claude-code/harness-security-scan/SKILL.md

@@ -0,0 +1,102 @@
+# Harness Security Scan
+
+> Lightweight mechanical security scan. Fast triage, not deep review.
+
+## When to Use
+
+- As part of the codebase-health-analyst sweep
+- For quick security triage on a project or changed files
+- On scheduled cron runs for continuous security coverage
+- NOT for deep security review (use harness-security-review)
+- NOT for threat modeling (use harness-security-review --deep)
+
+## Process
+
+### Phase 1: SCAN — Run Mechanical Scanner
+
+1. **Resolve project root.** Use provided path or cwd.
+
+2. **Load security config.** Read `harness.config.json` and extract `security`
+   section. Fall back to defaults if absent.
+
+3. **Determine file scope.**
+   - If `--changed-only` or triggered by PR: run `git diff --name-only HEAD~1`
+     to get changed files. Filter to source files only (exclude node_modules,
+     dist, test files per config).
+   - Otherwise: scan all source files in the project.
+
+4. **Run SecurityScanner.** Call `SecurityScanner.scanFiles()` from
+   `@harness-engineering/core`.
+
+5. **Filter by severity threshold.** Remove findings below the configured
+   threshold:
+   - `error`: only errors
+   - `warning`: errors and warnings (default)
+   - `info`: all findings
+
+6. **Output report.** Present findings grouped by severity:
+
+   ```
+   Security Scan: [PASS/FAIL]
+   Scanned: N files, M rules applied
+   Errors: N | Warnings: N | Info: N
+
+   [List findings with rule ID, file:line, severity, message, remediation]
+   ```
+
+## Gates
+
+- **Error-severity findings are blocking.** Report is FAIL if any error-severity
+  finding exists after filtering.
+- **No AI review.** This skill is mechanical only. Do not perform OWASP analysis
+  or threat modeling.
+
+## Harness Integration
+
+- **`harness check-security`** — CLI command that invokes this skill's scanner.
+- **`SecurityScanner`** — Core class from `@harness-engineering/core` that executes the rule engine.
+- **`harness.config.json`** — Security section configures severity threshold and file exclusions.
+- **codebase-health-analyst persona** — Invokes this skill as part of its sweep.
+
+## Escalation
+
+- **When error-severity findings are disputed:** The scanner is mechanical — it may flag false positives. If a finding is a false positive, add a `// harness-ignore SEC-XXX` comment on the line and document the rationale. Do not suppress without explanation.
+- **When the scanner misses a known vulnerability:** This skill runs pattern-based rules only. For semantic analysis (taint tracking, control flow), use `/harness:security-review` instead.
+- **When scan is too slow on large codebases:** Use `--changed-only` to scope to recently changed files. Full scans can run on a scheduled cron instead.
+
+## Success Criteria
+
+- Scanner ran and produced findings (or confirmed clean)
+- Findings are filtered by the configured severity threshold
+- Report follows the structured format
+- Exit code reflects pass/fail status
+
+## Examples
+
+### Example: Clean Scan
+
+```
+Security Scan: PASS
+Scanned: 42 files, 12 rules applied
+Errors: 0 | Warnings: 0 | Info: 0
+```
+
+### Example: Findings Detected
+
+```
+Security Scan: FAIL
+Scanned: 42 files, 12 rules applied
+Errors: 1 | Warnings: 2 | Info: 0
+
+[SEC-SECRET-001] src/config.ts:15 (error)
+  Hardcoded API key detected: `const API_KEY = "sk-..."`
+  Remediation: Move to environment variable, use dotenv or secrets manager.
+
+[SEC-NET-001] src/cors.ts:5 (warning)
+  CORS wildcard origin: `origin: "*"`
+  Remediation: Restrict to specific allowed origins.
+
+[SEC-CRYPTO-001] src/auth.ts:22 (warning)
+  Weak hash algorithm: `crypto.createHash("md5")`
+  Remediation: Use SHA-256 or stronger.
+```

package/dist/agents/skills/claude-code/harness-security-scan/skill.yaml

@@ -0,0 +1,41 @@
+name: harness-security-scan
+version: "1.0.0"
+description: Lightweight mechanical security scan for health checks
+cognitive_mode: meticulous-implementer
+triggers:
+  - manual
+  - scheduled
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-security-scan
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: severity
+      description: Minimum severity threshold (error, warning, info)
+      required: false
+    - name: changed-only
+      description: Only scan git-changed files
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-security-scan
+    path: string
+type: rigid
+phases:
+  - name: scan
+    description: Run SecurityScanner and filter by severity threshold
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/harness-state-management/SKILL.md

@@ -18,6 +18,13 @@
 
 ### Phase 1: LOAD — Restore Context from Previous Sessions
 
+0. **Resolve the stream.** State is organized into streams — isolated directories under `.harness/streams/<name>/`. Before loading any state files:
+   - If you know which work item you're resuming, pass `--stream <name>` or use `manage_state` with `stream: "<name>"`.
+   - Otherwise, the system auto-resolves from the current git branch (e.g., `feature/auth-rework` → `auth-rework` stream) or falls back to the active stream.
+   - If resolution fails, ask the user: "Which stream should I use?" and list known streams via `harness state streams list` or the `list_streams` MCP tool.
+   - When starting new work on a new branch, create a new stream: `harness state streams create <name> --branch <branch>`.
+   - Announce which stream was resolved so the human has visibility.
+
 1. **Read `.harness/state.json`.** This is the primary state file. It contains:
    - Current position (phase, task, step)
    - Progress map (which tasks are complete, in progress, or blocked)
@@ -159,7 +166,9 @@
 
 2. **Verify learnings were captured.** Review `.harness/learnings.md` — were all non-obvious discoveries recorded? If something was tricky during the session, it should be in learnings.
 
-3. **Decide whether to commit state files.** State files (`.harness/state.json`, `.harness/learnings.md`) should be committed to git so other team members and agents can access them. Commit state updates separately from code changes so they do not clutter code diffs.
+3. **State is saved to the active stream.** All writes (state, learnings, handoff, failures) go to the resolved stream's directory (e.g., `.harness/streams/auth-rework/state.json`). Switching to a different stream in the next session does not affect the current stream's files.
+
+4. **Decide whether to commit state files.** State files (`.harness/streams/*/state.json`, `.harness/streams/*/learnings.md`) should be committed to git so other team members and agents can access them. Commit state updates separately from code changes so they do not clutter code diffs.
 
 ### Building Institutional Knowledge Over Time
 
@@ -181,13 +190,18 @@ Treat learnings as a first-class project artifact. They are as valuable as tests
 
 ## Harness Integration
 
-- **`harness state show`** — Display current state in a formatted, readable view. Use at session start to quickly orient.
-- **`harness state reset`** — Reset state to initial values. Use when starting a completely new effort and old state is no longer relevant. Use with caution — this discards progress tracking.
-- **`harness state learn "<message>"`** — Append a learning to `.harness/learnings.md` with automatic timestamp formatting.
-- **`.harness/state.json`** — Primary state file. Read at session start, updated throughout, saved at session end.
-- **`.harness/learnings.md`** — Append-only knowledge base. Read at session start for context, appended to when discoveries are made.
-- **`.harness/failures.md`** — Active anti-patterns. Read at session start to avoid known dead ends.
-- **`.harness/handoff.json`** — Structured context from last skill. Read at session start for immediate context.
+- **`harness state show [--stream <name>]`** — Display current state in a formatted, readable view. Use at session start to quickly orient.
+- **`harness state reset [--stream <name>]`** — Reset state to initial values. Use when starting a completely new effort and old state is no longer relevant. Use with caution — this discards progress tracking.
+- **`harness state learn "<message>" [--stream <name>]`** — Append a learning with automatic timestamp formatting.
+- **`harness state streams list`** — List all known streams with branch associations and active status.
+- **`harness state streams create <name> [--branch <branch>]`** — Create a new stream, optionally associated with a git branch.
+- **`harness state streams archive <name>`** — Archive a completed stream.
+- **`harness state streams activate <name>`** — Set the active stream for the project.
+- **`.harness/streams/<name>/state.json`** — Primary state file per stream. Read at session start, updated throughout, saved at session end.
+- **`.harness/streams/<name>/learnings.md`** — Append-only knowledge base per stream.
+- **`.harness/streams/<name>/failures.md`** — Active anti-patterns per stream.
+- **`.harness/streams/<name>/handoff.json`** — Structured context from last skill per stream.
+- **`.harness/streams/index.json`** — Stream index tracking known streams, branch associations, and active stream.
 - **`.harness/trace.md`** — Optional reasoning trace. Useful for debugging agent behavior across sessions.
 - **`.harness/archive/`** — Archived failure logs. Check for historical context when encountering recurring issues.
 

package/dist/agents/skills/claude-code/harness-tdd/SKILL.md

@@ -75,6 +75,16 @@ If you find yourself writing production code first, STOP. Delete it. Write the t
 
 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.

package/dist/agents/skills/claude-code/harness-test-advisor/SKILL.md

@@ -0,0 +1,131 @@
+# 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 must exist at `.harness/graph/`. Run `harness scan` if no graph is available.
+If the graph exists but code has changed since the last scan, re-run `harness scan` first — stale graph data leads to inaccurate results.
+
+## 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.
+
+### 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`** — Must run before this skill to ensure graph is current.
+- **`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, not heuristics
+
+## 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
+
+- **No advice without graph.** If no graph exists, fall back to: "Run all tests in the same directory as changed files."
+- **Always include Tier 1.** Direct test coverage is non-negotiable — always recommend running these.
+
+## 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.