@harness-engineering/cli 1.26.0 → 1.26.1

package/dist/agents/commands/cursor/harness/harness-hotspot-detector.mdc

@@ -1,169 +0,0 @@
----
-description: Identify structural risk hotspots via co-change and churn analysis
-alwaysApply: false
----
-
-<!-- Generated by harness generate-slash-commands. Do not edit. -->
-
-# 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 at `.harness/graph/` with git history 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:** Use graph tools as primary strategy. (Staleness sensitivity: **Low** — never auto-refresh.
-Git-based churn data in the graph remains useful even when slightly stale.)
-
-**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: 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.
-
-#### Fallback (without graph)
-
-When no graph is available, git log provides nearly all the data needed (~90% completeness):
-
-1. **Per-file churn**: `git log --format="%H" -- <file>` for each source file (use glob to enumerate). Count commits per file. Sort descending to rank by churn.
-2. **Recent velocity**: `git log --since="30 days ago" --format="%H" -- <file>` vs `git log --since="60 days ago" --until="30 days ago" --format="%H" -- <file>` to compare recent vs prior 30-day windows.
-3. **Co-change detection**: `git log --format="%H %n" --name-only` to build a map of which files changed together in the same commit. File pairs that appear together in >3 commits are co-change candidates.
-4. **Distant co-change identification**: For co-change pairs, check if they share a parent directory (co-located = normal) or are in different modules (distant = suspicious).
-5. **Complexity proxy**: Use line count (`wc -l`) as a rough proxy for complexity when graph complexity metrics are unavailable.
-6. **Hidden dependency detection**: Cross-reference co-change pairs against import parsing (grep for import statements). Co-change pairs with no import relationship indicate hidden dependencies.
-
-> Fallback completeness: ~90% — git log provides nearly all the data the graph stores for this use case.
-
-### 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`** — Recommended before this skill for full graph-enhanced analysis. If graph is missing, skill uses git log 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
-
-- 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 (with graph) or git log analysis (without graph)
-
-## 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
-
-- **Graph preferred, fallback available.** If no graph exists, use git log for churn and co-change analysis. Do not stop — git log provides ~90% of the data needed.
-- **Systematic analysis required.** Use graph `co_changes_with` edges when available; use `git log` commit analysis when not. Do not guess — parse actual git history.
-
-## 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/commands/cursor/harness/harness-impact-analysis.mdc

@@ -1,192 +0,0 @@
----
-description: Graph-based impact analysis — answers "if I change X, what breaks?"
-alwaysApply: false
----
-
-<!-- Generated by harness generate-slash-commands. Do not edit. -->
-
-# 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 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 2 commits behind (`git log --oneline <scanTimestamp>..HEAD | wc -l`),
-run `harness scan` to refresh before proceeding. (Staleness sensitivity: **High**)
-
-**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: 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.
-
-5. **Design token impact**: When the graph contains `DesignToken` nodes, use `query_graph` with `USES_TOKEN` edges to find components that consume changed tokens.
-
-   ```
-   query_graph(rootNodeIds=["designtoken:color.primary"], maxDepth=2, includeEdges=["uses_token"])
-   → components: [Button.tsx, Card.tsx, Header.tsx, ...]
-   ```
-
-   If a changed file is `design-system/tokens.json`, identify ALL tokens that changed and trace each to its consuming components. This reveals the full design blast radius of a token change.
-
-6. **Design constraint impact**: When the graph contains `DesignConstraint` nodes, check if changed code introduces new `VIOLATES_DESIGN` edges.
-
-#### Fallback (without graph)
-
-When no graph is available, use static analysis to approximate impact:
-
-1. **Parse imports**: For each changed file, grep all source files for `import.*from.*<changed-file>` and `require.*<changed-file>` patterns to find direct dependents.
-2. **Follow imports 2 levels deep**: For each direct dependent found, repeat the import grep to find second-level dependents. Stop at 2 levels (fallback cannot reliably trace deeper).
-3. **Find test files by naming convention**: For each changed file `foo.ts`, search for:
-   - `foo.test.ts`, `foo.spec.ts` (same directory and `__tests__/` directory)
-   - `*.test.*` and `*.spec.*` files that import the changed file (from step 1)
-4. **Find docs by path matching**: Grep `docs/` directory for references to the changed module name (filename without extension).
-5. **Group results** the same as the graph version: tests, docs, code, other. Note the count of files found.
-
-> Fallback completeness: ~70% — misses transitive deps beyond 2 levels.
-
-### 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)
-   - Whether design tokens are affected (weight: 2x — token changes cascade to all consumers)
-
-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)
-
-   ### Affected Design Tokens (when tokens change)
-   1. color.primary → used by 12 components
-   2. typography.body → used by 8 components
-   ```
-
-## Harness Integration
-
-- **`harness scan`** — Recommended before this skill for full graph-enhanced analysis. If graph is missing, skill uses static analysis 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
-
-- 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 (with graph) or systematic static analysis (without graph)
-
-## 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
-
-- **Graph preferred, fallback available.** If no graph exists, use fallback strategies (import parsing, naming conventions, path matching). Do not stop — produce the best analysis possible with available tools.
-- **No risk assessment without data.** Use graph queries when available; use import parsing and naming conventions when not. If neither approach yields data, 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/commands/cursor/harness/harness-integrity.mdc

@@ -1,175 +0,0 @@
----
-description: Unified integrity gate — chains verify (quick gate) with AI review into a single report
-alwaysApply: false
----
-
-<!-- Generated by harness generate-slash-commands. Do not edit. -->
-
-# Harness Integrity
-
-> Unified integrity gate — single invocation chains mechanical verification with AI-powered code review and produces a consolidated pass/fail report.
-
-## When to Use
-
-- Before opening or merging a pull request
-- At project milestones as a comprehensive quality check
-- When you need a single authoritative answer: "is this code ready to ship?"
-- NOT after every task (use `harness-verify` for quick post-task checks)
-- NOT for deep architectural audits (use `harness-verification` for that)
-
-## Relationship to Other Skills
-
-| Skill                        | What It Does                                   | Scope                  | Time  |
-| ---------------------------- | ---------------------------------------------- | ---------------------- | ----- |
-| **harness-verify**           | Mechanical only: typecheck, lint, test         | Exit codes             | ~30s  |
-| **harness-code-review**      | AI only: change-type-aware review              | LLM analysis           | ~2min |
-| **harness-integrity** (this) | Both: verify + code-review unified             | Full pipeline          | ~3min |
-| **harness-verification**     | Deep audit: architecture, patterns, edge cases | Thorough investigation | ~5min |
-
-`harness-integrity` is the standard pre-PR gate. It runs the fast mechanical checks first, then layers on AI review, and produces a single consolidated report.
-
-## Process
-
-### Phase 1: VERIFY
-
-Invoke `harness-verify` to run the mechanical quick gate.
-
-1. Delegate entirely to `harness-verify` — typecheck, lint, test.
-2. Capture the structured result (PASS/FAIL per check).
-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 1.7: DESIGN HEALTH (conditional)
-
-When the project has `design` configured in `harness.config.json`:
-
-1. Run `harness-design` in review mode to check existing components against design intent and anti-patterns.
-2. Run `harness-accessibility` in scan+evaluate mode to check WCAG compliance.
-3. Combine findings into a design health summary:
-   - Error count (blocking, based on strictness)
-   - Warning count (non-blocking)
-   - Info count (advisory)
-4. **Error-severity design findings are blocking** in `strict` mode only. In `standard` and `permissive` modes, design findings do not block.
-5. If no `design` block exists, skip this phase entirely.
-
-### Phase 1.8: I18N SCAN (conditional)
-
-When the project has `i18n.enabled: true` in `harness.config.json`:
-
-1. Run `harness-i18n` in scan mode to detect hardcoded strings, missing translations, locale-sensitive formatting issues, and RTL violations.
-2. Combine findings into an i18n health summary:
-   - Error count (blocking, based on `i18n.strictness`)
-   - Warning count (non-blocking)
-   - Info count (advisory)
-3. **Error-severity i18n findings are blocking** in `strict` mode only. In `standard` and `permissive` modes, i18n findings do not block.
-4. If no `i18n` block exists or `i18n.enabled` is false, skip this phase entirely.
-
-### Phase 2: REVIEW
-
-Run change-type-aware AI review using `harness-code-review`.
-
-1. Detect the change type if not provided: `feature`, `bugfix`, `refactor`, or `docs`.
-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
-
-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]
-- Security: [PASS/WARN/FAIL] ([count] errors, [count] warnings)
-- Design:   [PASS/WARN/FAIL/SKIPPED] ([count] errors, [count] warnings)
-- i18n:     [PASS/WARN/FAIL/SKIPPED] ([count] errors, [count] warnings)
-- Review:   [PASS/FAIL] ([count] suggestions, [count] blocking)
-
-Overall: [PASS/FAIL]
-```
-
-Rules:
-
-- Overall `PASS` requires: all non-skipped mechanical checks pass AND zero blocking review findings AND zero blocking design findings (strict mode only) AND zero blocking i18n findings (strict mode only).
-- Any mechanical failure OR any blocking review finding means `FAIL`.
-- On FAIL, include a summary section listing each failure reason.
-- Non-blocking review suggestions are noted but do not cause FAIL.
-
-## Deterministic Checks
-
-- **Phase 1 is fully deterministic.** Exit codes determine pass/fail with no interpretation.
-- **Phase 2 involves LLM judgment.** The AI review may produce different results on repeated runs. Only "blocking" findings (runtime errors, data loss, security) affect the overall result.
-
-## Harness Integration
-
-- Chains harness-verify (mechanical) and harness-code-review (AI) into a unified pipeline
-- Follows Principle 7 — deterministic checks always run first
-- Consumes change-type detection from harness-code-review for per-type checklists
-- Output can be written to `.harness/integrity-report.md` for CI integration
-- Invokes `harness-design` and `harness-accessibility` for design health when `design` config exists
-- Design strictness from config controls whether design findings block the overall result
-- Invokes `harness-i18n` for i18n compliance when `i18n.enabled` is true in config. i18n strictness controls whether findings block the overall result.
-
-## Success Criteria
-
-- [ ] Mechanical verification ran and produced structured results
-- [ ] AI review ran with change-type awareness
-- [ ] Unified report follows the exact format
-- [ ] Overall verdict correctly reflects both mechanical and review results
-
-## Examples
-
-### Example: All Clear
-
-```
-Integrity Check: PASS
-- Tests: PASS (42/42)
-- Lint: PASS (0 warnings)
-- Types: PASS
-- Security: PASS (0 errors, 0 warnings)
-- Design: PASS (0 errors, 0 warnings)
-- i18n: PASS (0 errors, 0 warnings)
-- Review: 1 suggestion (0 blocking)
-```
-
-### 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
-- Design: WARN (0 errors, 2 warnings)
-- i18n: SKIPPED
-- Review: 3 findings (1 blocking)
-
-Blocking: [SEC-INJ-002] SQL injection — user input passed directly to query without parameterization.
-```
-
-## Gates
-
-- **Mechanical first.** Always run Phase 1 before Phase 2. If the code does not compile or pass basic checks, AI review is wasted effort (unless partial results exist).
-- **No partial reports.** The report must include results from all phases that were executed. Do not output Phase 1 results without attempting Phase 2 (unless the all-fail early stop triggers).
-- **Fresh execution only.** Do not reuse cached results. Run everything from scratch each time.
-
-## Escalation
-
-- **All checks fail:** If typecheck, lint, and test all fail in Phase 1, stop immediately. Report the failures and skip Phase 2. The code needs basic fixes before review is worthwhile.
-- **Architectural concerns:** If the AI review identifies architectural concerns, note them in the report but do not mark them as blocking. Architectural decisions require human judgment.
-- **Timeout:** Phase 1 inherits the 120-second per-command timeout from `harness-verify`. Phase 2 has a 180-second timeout for the AI review.
-- **Missing dependencies:** If `harness-verify` or `harness-code-review` skills are unavailable, report the missing dependency and mark the corresponding phase as `ERROR`.
-