@harness-engineering/cli 1.4.0 → 1.6.1

package/dist/agents/skills/claude-code/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/claude-code/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/claude-code/harness-execution/SKILL.md

@@ -41,6 +41,15 @@ Deviating from the plan mid-execution introduces untested assumptions, breaks ta
 
 7. **If prerequisites fail,** do not proceed. Report what is missing and which task is blocked.
 
+### Graph-Enhanced Context (when available)
+
+When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate context:
+
+- `query_graph` — check file overlap between current and next task for conflict detection
+- `get_impact` — understand blast radius before executing a task
+
+Enables smarter execution ordering and blockage detection. Fall back to file-based commands if no graph is available.
+
 ---
 
 ### Phase 2: EXECUTE — Implement Tasks Atomically
@@ -137,6 +146,16 @@ Between tasks (especially between sessions):
    }
    ```
 
+### 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.
+
 2. **Append tagged learnings to `.harness/learnings.md`.** Tag every entry with skill and outcome:
 
    ```markdown

package/dist/agents/skills/claude-code/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/claude-code/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: []

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

@@ -0,0 +1,139 @@
+# Harness Impact Analysis
+
+> Graph-based impact analysis. Answers: "if I change X, what breaks?"
+
+## When to Use
+
+- Before merging a PR — understand the blast radius of changes
+- When planning a refactoring — know what will be affected
+- When a test fails — trace backwards to find what change caused it
+- When `on_pr` triggers fire
+- NOT for understanding code (use harness-onboarding or harness-code-review)
+- 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: IDENTIFY — Determine Changed Files
+
+1. **From diff**: If a git diff is available, parse it to extract changed file paths.
+2. **From input**: If file paths are provided directly, use those.
+3. **From git**: If neither, use `git diff --name-only HEAD~1` to get recent changes.
+
+### Phase 2: ANALYZE — Query Graph for Impact
+
+For each changed file:
+
+1. **Direct dependents**: Use `get_impact` MCP tool to find all files that import or call the changed file.
+
+   ```
+   get_impact(filePath="src/services/auth.ts")
+   → tests: [auth.test.ts, integration.test.ts]
+   → docs: [auth-guide.md]
+   → code: [routes/login.ts, middleware/verify.ts, ...]
+   ```
+
+2. **Transitive dependents**: Use `query_graph` with depth 3 to find indirect consumers.
+
+   ```
+   query_graph(rootNodeIds=["file:src/services/auth.ts"], maxDepth=3, includeEdges=["imports", "calls"])
+   ```
+
+3. **Documentation impact**: Use `get_relationships` to find `documents` edges pointing to changed nodes.
+
+4. **Test coverage**: Identify test files connected via `imports` edges. Flag changed files with no test coverage.
+
+### Phase 3: ASSESS — Risk Assessment and Report
+
+1. **Impact score**: Calculate based on:
+   - Number of direct dependents (weight: 3x)
+   - Number of transitive dependents (weight: 1x)
+   - Whether affected code includes entry points (weight: 5x)
+   - Whether tests exist for the changed code (no tests = higher risk)
+
+2. **Risk tiers**:
+   - **Critical** (score > 50): Changes affect entry points or >20 downstream files
+   - **High** (score 20-50): Changes affect multiple modules or shared utilities
+   - **Medium** (score 5-20): Changes affect a few files within the same module
+   - **Low** (score < 5): Changes are isolated with minimal downstream impact
+
+3. **Output report**:
+
+   ```
+   ## Impact Analysis Report
+
+   ### Changed Files
+   - src/services/auth.ts (modified)
+   - src/types/user.ts (modified)
+
+   ### Impact Summary
+   - Direct dependents: 8 files
+   - Transitive dependents: 23 files
+   - Affected tests: 5 files
+   - Affected docs: 2 files
+   - Risk tier: HIGH
+
+   ### Affected Tests (must run)
+   1. tests/services/auth.test.ts (direct)
+   2. tests/routes/login.test.ts (transitive)
+   3. tests/integration/auth-flow.test.ts (transitive)
+
+   ### Affected Documentation (may need update)
+   1. docs/auth-guide.md → documents src/services/auth.ts
+   2. docs/api-reference.md → documents src/types/user.ts
+
+   ### Downstream Consumers
+   1. src/routes/login.ts — imports auth.ts
+   2. src/middleware/verify.ts — imports auth.ts
+   3. src/routes/signup.ts — imports user.ts (transitive via auth.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
+
+- Impact report generated with a risk tier (Critical / High / Medium / Low)
+- All affected test files listed with direct vs transitive classification
+- All affected documentation files listed with relationship context
+- Report follows the structured output format
+- All findings are backed by graph query evidence, not heuristics
+
+## Examples
+
+### Example: Analyzing a Change to auth.ts
+
+```
+Input: git diff shows src/services/auth.ts modified
+
+1. IDENTIFY — Extract changed file: src/services/auth.ts
+2. ANALYZE  — get_impact(filePath="src/services/auth.ts")
+              query_graph(rootNodeIds=["file:src/services/auth.ts"], maxDepth=3)
+              Results: 8 direct dependents, 23 transitive, 5 tests, 2 docs
+3. ASSESS   — Impact score: 34 (High tier)
+              - Entry points affected: no
+              - Tests exist: yes (5 files)
+
+Output:
+  Risk tier: HIGH
+  Must-run tests: auth.test.ts, login.test.ts, auth-flow.test.ts
+  Docs to update: auth-guide.md, api-reference.md
+  Downstream consumers: 8 files across 3 modules
+```
+
+## Gates
+
+- **No analysis without graph.** If no graph exists at `.harness/graph/`, stop and instruct the user to run `harness scan`.
+- **No risk assessment without data.** Do not guess at impact — use graph queries. If graph data is incomplete, state what is missing.
+
+## Escalation
+
+- **When graph is stale**: If the graph's last scan timestamp is older than the most recent commit, warn that results may be incomplete and suggest re-scanning.
+- **When impact is critical**: If risk tier is Critical, recommend a thorough code review and full test suite run before merging.

package/dist/agents/skills/claude-code/harness-impact-analysis/skill.yaml

@@ -0,0 +1,44 @@
+name: harness-impact-analysis
+version: "1.0.0"
+description: Graph-based impact analysis — answers "if I change X, what breaks?"
+cognitive_mode: analytical-reporter
+triggers:
+  - manual
+  - on_pr
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-impact-analysis
+  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-impact-analysis
+    path: string
+type: rigid
+phases:
+  - name: identify
+    description: Identify changed files from diff or input
+    required: true
+  - name: analyze
+    description: Query graph for impact of each changed file
+    required: true
+  - name: assess
+    description: Rank findings by risk and generate report
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -32,6 +32,15 @@ Invoke `harness-verify` to run the mechanical quick gate.
 3. **If ALL three checks FAIL**, stop here. Do not proceed to Phase 2. The code is not in a reviewable state.
 4. If at least one check passes (or some are skipped), proceed to Phase 2.
 
+### Phase 1.5: SECURITY SCAN
+
+Run the built-in security scanner as a mechanical check between verification and AI review.
+
+1. Use `run_security_scan` MCP tool against the project root (or changed files if available).
+2. Capture findings by severity: errors, warnings, info.
+3. **Error-severity security findings are blocking** — they cause the overall integrity check to FAIL, same as a test failure.
+4. Warning/info findings are included in the report but do not block.
+
 ### Phase 2: REVIEW
 
 Run change-type-aware AI review using `harness-code-review`.
@@ -40,6 +49,7 @@ Run change-type-aware AI review using `harness-code-review`.
 2. Invoke `harness-code-review` with the detected change type.
 3. Capture the review findings: suggestions, blocking issues, and notes.
 4. A review finding is "blocking" only if it would cause a runtime error, data loss, or security vulnerability.
+5. The AI review includes a security-focused pass that complements the mechanical scanner — checking for semantic issues like user input flowing to dangerous sinks across function boundaries.
 
 ### Phase 3: REPORT
 
@@ -47,10 +57,11 @@ Produce a unified integrity report in this exact format:
 
 ```
 Integrity Check: [PASS/FAIL]
-- Tests:   [PASS/FAIL/SKIPPED]
-- Lint:    [PASS/FAIL/SKIPPED]
-- Types:   [PASS/FAIL/SKIPPED]
-- Review:  [PASS/FAIL] ([count] suggestions, [count] blocking)
+- Tests:    [PASS/FAIL/SKIPPED]
+- Lint:     [PASS/FAIL/SKIPPED]
+- Types:    [PASS/FAIL/SKIPPED]
+- Security: [PASS/WARN/FAIL] ([count] errors, [count] warnings)
+- Review:   [PASS/FAIL] ([count] suggestions, [count] blocking)
 
 Overall: [PASS/FAIL]
 ```
@@ -90,19 +101,22 @@ Integrity Check: PASS
 - Tests: PASS (42/42)
 - Lint: PASS (0 warnings)
 - Types: PASS
+- Security: PASS (0 errors, 0 warnings)
 - Review: 1 suggestion (0 blocking)
 ```
 
-### Example: Blocking Issue
+### Example: Security Blocking Issue
 
 ```
 Integrity Check: FAIL
 - Tests: PASS (42/42)
 - Lint: PASS
 - Types: PASS
+- Security: FAIL (1 error, 0 warnings)
+  - [SEC-INJ-002] src/auth/login.ts:42 — SQL query built with string concatenation
 - Review: 3 findings (1 blocking)
 
-Blocking: [src/auth/login.ts:42] Possible SQL injection — user input passed directly to query without parameterization.
+Blocking: [SEC-INJ-002] SQL injection — user input passed directly to query without parameterization.
 ```
 
 ## Gates