@harness-engineering/cli 1.3.0 → 1.6.0

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.

package/dist/agents/skills/claude-code/harness-test-advisor/skill.yaml

@@ -0,0 +1,44 @@
+name: harness-test-advisor
+version: "1.0.0"
+description: Graph-based test selection — answers "what tests should I run?"
+cognitive_mode: advisory-guide
+triggers:
+  - manual
+  - on_pr
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-test-advisor
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: files
+      description: Comma-separated list of changed files
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-test-advisor
+    path: string
+type: flexible
+phases:
+  - name: parse
+    description: Identify changed files from diff or input
+    required: true
+  - name: discover
+    description: Find related tests via graph traversal
+    required: true
+  - name: prioritize
+    description: Rank tests by relevance and generate commands
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -72,6 +72,16 @@
 
 3. **Run `harness check-deps`** (intermediate and above) to verify dependency constraints match the actual codebase. If there are violations, decide with the human: update the constraints or fix the code.
 
+### Build the Initial Knowledge Graph
+
+If the project will use graph-based queries, build the initial knowledge graph now:
+
+```
+harness scan [path]
+```
+
+This creates the `.harness/graph/` directory and populates it with the project's dependency and relationship data. Subsequent graph queries (impact analysis, dependency health, test advisor) depend on this initial scan.
+
 4. **Commit the initialization.** All generated and configured files in a single commit.
 
 ## Harness Integration

package/dist/agents/skills/claude-code/validate-context-engineering/SKILL.md

@@ -23,6 +23,15 @@
 
 3. **Review AGENTS.md manually.** Automated tools catch structural issues but miss semantic drift. Read each section and ask: "Is this still true?"
 
+### Graph-Enhanced Context (when available)
+
+When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate auditing:
+
+- `query_graph` — find all undocumented code nodes (file nodes without `documents` edges), replacing manual cross-referencing
+- `search_similar` — detect stale references in AGENTS.md by matching section text against current code entities
+
+When a graph is available, it IS the source of truth for documentation coverage. Drift = stale or missing edges between code and doc nodes. Fall back to file-based commands if no graph is available.
+
 ### Phase 2: Detect Gaps
 
 Categorize findings into four types:

package/dist/agents/skills/gemini-cli/harness-dependency-health/SKILL.md

@@ -0,0 +1,150 @@
+# Harness Dependency Health
+
+> Analyze structural health of the codebase and surface problems before they become incidents.
+
+## When to Use
+
+- Weekly scheduled health check on the codebase
+- Before major refactoring — understand current structural health
+- When onboarding to a new project — assess codebase quality
+- NOT for checking layer violations (use enforce-architecture)
+- NOT for finding dead code (use cleanup-dead-code)
+
+## 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: METRICS — Compute Graph Structural Metrics
+
+Query the graph for five key structural indicators:
+
+1. **Hub detection**: Find nodes with high fan-in (>10 inbound `imports` edges).
+
+   ```
+   query_graph(rootNodeIds=[all file nodes], includeEdges=["imports"])
+   ```
+
+   Hubs are single points of failure — changes to them have outsized blast radius.
+
+2. **Orphan detection**: Find file nodes with zero inbound `imports` edges that are not entry points.
+
+   ```
+   get_relationships(nodeId=<file>, direction="inbound")
+   ```
+
+   Orphans may be dead code or missing from the module system.
+
+3. **Cycle detection**: Use `check_dependencies` to find circular import chains.
+   Cycles create fragile coupling — any change in the cycle affects all members.
+
+4. **Deep chain detection**: Find import chains longer than N hops (default: 7).
+
+   ```
+   query_graph(rootNodeIds=[entry points], maxDepth=10, includeEdges=["imports"])
+   ```
+
+   Deep chains are fragile — a change at the bottom propagates unpredictably.
+
+5. **Module cohesion**: For each module (directory), count internal vs external edges. Low internal cohesion (many external edges, few internal) suggests misplaced code.
+
+### Phase 2: SCORE — Calculate Health Score
+
+Compute a weighted health score (0-100):
+
+| Metric            | Weight | Scoring                                   |
+| ----------------- | ------ | ----------------------------------------- |
+| Hubs (>10 fan-in) | 25%    | 0 hubs = 100, 1-3 = 70, 4-6 = 40, >6 = 10 |
+| Orphans           | 20%    | 0 = 100, 1-5 = 80, 6-15 = 50, >15 = 20    |
+| Cycles            | 25%    | 0 = 100, 1 = 60, 2-3 = 30, >3 = 0         |
+| Deep chains (>7)  | 15%    | 0 = 100, 1-3 = 70, >3 = 30                |
+| Cohesion (avg)    | 15%    | >0.7 = 100, 0.5-0.7 = 70, <0.5 = 30       |
+
+**Grades**: A (90-100), B (75-89), C (60-74), D (40-59), F (<40)
+
+### Phase 3: RECOMMEND — Generate Recommendations
+
+For each problem found, generate a specific, actionable recommendation:
+
+- **Hubs**: "Split `src/utils/helpers.ts` (14 importers) into domain-specific utilities"
+- **Orphans**: "Remove `src/legacy/old-parser.ts` (0 importers, not an entry point)"
+- **Cycles**: "Break cycle A→B→C→A by extracting shared types to `src/types/shared.ts`"
+- **Deep chains**: "Consider flattening chain: entry→A→B→C→D→E→F→G (8 hops)"
+- **Low cohesion**: "Module `src/services/` has 80% external edges — consider splitting"
+
+### Output
+
+```
+## Dependency Health Report
+
+### Score: B (78/100)
+
+### Metrics
+| Metric | Count | Score |
+|--------|-------|-------|
+| Hubs (>10 fan-in) | 2 | 70/100 |
+| Orphans | 3 | 80/100 |
+| Cycles | 0 | 100/100 |
+| Deep chains (>7) | 1 | 70/100 |
+| Module cohesion | 0.62 avg | 70/100 |
+
+### Top Issues
+1. **Hub**: src/utils/helpers.ts — 14 importers (split recommended)
+2. **Hub**: src/types/index.ts — 12 importers (acceptable for type barrel)
+3. **Orphan**: src/legacy/old-parser.ts — 0 importers
+4. **Deep chain**: entry→auth→user→db→pool→config→env→loader (8 hops)
+
+### Recommendations
+1. Split src/utils/helpers.ts into domain-specific modules
+2. Investigate src/legacy/old-parser.ts for removal
+3. Flatten auth chain by having auth import db directly
+```
+
+## 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_relationships`, and `check_dependencies` MCP tools.
+
+## Success Criteria
+
+- Health score computed on 0-100 scale with letter grade (A-F)
+- All five structural metrics gathered (hubs, orphans, cycles, deep chains, cohesion)
+- Recommendations are specific and actionable (name files, suggest concrete fixes)
+- Report follows the structured output format
+- All findings are backed by graph query evidence, not heuristics
+
+## Examples
+
+### Example: Weekly Health Check on Monorepo
+
+```
+Input: Scheduled weekly run on project root
+
+1. METRICS    — query_graph for hubs: 2 found (helpers.ts, index.ts)
+                get_relationships for orphans: 3 found
+                check_dependencies for cycles: 0 found
+                query_graph for deep chains: 1 found (8 hops)
+                Module cohesion average: 0.62
+2. SCORE      — Weighted score: 78/100 (Grade: B)
+3. RECOMMEND  — "Split helpers.ts (14 importers) into domain modules"
+                "Investigate old-parser.ts for removal (0 importers)"
+                "Flatten auth chain — 8 hops exceeds threshold"
+
+Output:
+  Score: B (78/100)
+  Top issues: 2 hubs, 3 orphans, 1 deep chain
+  3 actionable recommendations generated
+```
+
+## Gates
+
+- **No analysis without graph.** If no graph exists, stop and instruct to run `harness scan`.
+- **No guessing.** All metrics must come from graph queries, not heuristics.
+
+## Escalation
+
+- **When score is F (<40)**: Flag as critical and recommend immediate architectural review.
+- **When graph is stale**: Warn and suggest re-scanning before trusting results.

package/dist/agents/skills/gemini-cli/harness-dependency-health/skill.yaml

@@ -0,0 +1,41 @@
+name: harness-dependency-health
+version: "1.0.0"
+description: Analyze structural health of the codebase using graph metrics
+cognitive_mode: analytical-reporter
+triggers:
+  - manual
+  - scheduled
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-dependency-health
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-dependency-health
+    path: string
+type: rigid
+phases:
+  - name: metrics
+    description: Compute graph structural metrics
+    required: true
+  - name: score
+    description: Calculate health score and identify problems
+    required: true
+  - name: recommend
+    description: Generate specific remediation recommendations
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/harness-hotspot-detector/SKILL.md

@@ -0,0 +1,135 @@
+# Harness Hotspot Detector
+
+> Identify modules that represent structural risk via co-change and churn analysis.
+
+## When to Use
+
+- Weekly scheduled analysis to track codebase risk
+- Before major refactoring — find the riskiest areas
+- When investigating why changes keep breaking unrelated features
+- NOT for finding dead code (use cleanup-dead-code)
+- NOT for checking architecture rules (use enforce-architecture)
+
+## Prerequisites
+
+A knowledge graph must exist at `.harness/graph/` with git history ingested. 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: CO-CHANGE — Analyze Co-Change Patterns
+
+Query the graph for `co_changes_with` edges (created by GitIngestor):
+
+```
+query_graph(rootNodeIds=[all file nodes], includeEdges=["co_changes_with"])
+```
+
+Identify file pairs that frequently change together:
+
+- **Co-located pairs** (same directory): Normal — they share a concern.
+- **Distant pairs** (different modules): Suspicious — may indicate hidden coupling.
+
+Flag distant co-change pairs as potential hotspots.
+
+### Phase 2: CHURN — Identify High-Churn Files
+
+Query commit nodes to find files with the highest change frequency:
+
+```
+query_graph(rootNodeIds=[commit nodes], includeTypes=["commit", "file"], includeEdges=["co_changes_with"])
+```
+
+Rank files by:
+
+- Total commit count touching the file
+- Recent velocity (commits in last 30 days vs prior 30 days)
+- Change size (total lines added + deleted)
+
+High churn in shared utilities or core modules = high risk.
+
+### Phase 3: COUPLING — Detect Hidden Dependencies
+
+Cross-reference co-change data with structural data:
+
+1. **High logical coupling, low structural coupling**: Files that always change together but have no `imports` edge between them. This indicates a hidden dependency — changing one requires changing the other, but the code doesn't express this relationship.
+
+2. **High structural coupling, low logical coupling**: Files with `imports` edges but that rarely change together. This may indicate over-coupling — the import exists but the relationship is weak.
+
+Use `get_relationships` to check structural edges between co-change pairs.
+
+### Phase 4: REPORT — Generate Ranked Hotspot Report
+
+```
+## Hotspot Analysis Report
+
+### Risk Hotspots (ranked by risk score)
+
+1. **src/services/billing.ts** — Risk: HIGH
+   - Churn: 23 commits (last 30 days: 8)
+   - Co-changes with: src/types/invoice.ts (distant, 15 co-changes)
+   - Hidden dependency: no imports edge to invoice.ts
+   - Recommendation: Extract shared billing types or add explicit dependency
+
+2. **src/utils/helpers.ts** — Risk: HIGH
+   - Churn: 45 commits (highest in codebase)
+   - Co-changes with: 12 different files across 4 modules
+   - Recommendation: Split into domain-specific utilities to reduce blast radius
+
+3. **src/middleware/auth.ts** — Risk: MEDIUM
+   - Churn: 15 commits
+   - Co-changes with: src/routes/login.ts (co-located, expected)
+   - No hidden dependencies detected
+
+### Summary
+- Total hotspots detected: 5
+- High risk: 2
+- Medium risk: 3
+- Hidden dependencies: 1
+```
+
+## 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
+
+- Hotspots ranked by composite risk score (churn + coupling)
+- Hidden dependencies identified (high co-change, no structural edge)
+- Co-change patterns detected and classified (co-located vs distant)
+- Report follows the structured output format
+- All findings are backed by graph query evidence, not heuristics
+
+## Examples
+
+### Example: Detecting Hotspots in a Growing Codebase
+
+```
+Input: Scheduled weekly analysis on project root
+
+1. CO-CHANGE — query_graph for co_changes_with edges
+               Found 4 distant co-change pairs
+2. CHURN     — Ranked files by commit frequency
+               billing.ts: 23 commits, helpers.ts: 45 commits
+3. COUPLING  — Cross-referenced co-change vs imports edges
+               billing.ts <-> invoice.ts: 15 co-changes, no imports edge
+               (hidden dependency detected)
+4. REPORT    — Ranked hotspots by risk score
+
+Output:
+  Hotspots: 5 total (2 high, 3 medium)
+  Hidden dependencies: 1 (billing.ts <-> invoice.ts)
+  Top recommendation: Extract shared billing types
+```
+
+## Gates
+
+- **No analysis without graph + git data.** Both code structure and git history must be ingested.
+- **No guessing at co-change patterns.** Use graph `co_changes_with` edges, not manual git log parsing.
+
+## Escalation
+
+- **When hidden dependencies found**: Recommend making the dependency explicit (add import) or extracting shared code.
+- **When a single file has >30 commits**: Flag as critical hotspot requiring architectural attention.

package/dist/agents/skills/gemini-cli/harness-hotspot-detector/skill.yaml

@@ -0,0 +1,44 @@
+name: harness-hotspot-detector
+version: "1.0.0"
+description: Identify structural risk hotspots via co-change and churn analysis
+cognitive_mode: analytical-reporter
+triggers:
+  - manual
+  - scheduled
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-hotspot-detector
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-hotspot-detector
+    path: string
+type: rigid
+phases:
+  - name: co-change
+    description: Analyze co-change patterns from git history
+    required: true
+  - name: churn
+    description: Identify high-churn files and modules
+    required: true
+  - name: coupling
+    description: Detect hidden dependencies via logical coupling
+    required: true
+  - name: report
+    description: Generate ranked hotspot report
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []