@harness-engineering/cli 1.4.0 → 1.6.0

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-knowledge-mapper/SKILL.md

@@ -0,0 +1,154 @@
+# Harness Knowledge Mapper
+
+> Auto-generate always-current knowledge maps from graph topology. Never stale because it's computed, not authored.
+
+## When to Use
+
+- When AGENTS.md is outdated or doesn't exist — generate it from the graph
+- After major refactoring — regenerate the knowledge map to reflect new structure
+- On scheduled basis — keep documentation aligned with code
+- When `on_commit` to main triggers fire
+- NOT for validating existing AGENTS.md (use validate-context-engineering)
+- NOT for fixing documentation drift (use align-documentation)
+
+## 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: SURVEY — Query Graph for Structure
+
+1. **Module hierarchy**: Query for module nodes and their `contains` edges to file nodes.
+
+   ```
+   query_graph(rootNodeIds=[all module nodes], includeTypes=["module", "file"], includeEdges=["contains"])
+   ```
+
+2. **Entry points**: Find file nodes with high out-degree but low in-degree (they initiate dependency chains).
+
+   ```
+   search_similar(query="main entry point index")
+   ```
+
+3. **Layer structure**: Query for layer nodes if defined.
+
+4. **Dependency flow**: For each module, trace outbound `imports` edges to other modules.
+
+   ```
+   get_relationships(nodeId=<module>, direction="outbound", depth=1)
+   ```
+
+### Phase 2: GENERATE — Build Knowledge Map
+
+Generate markdown sections following AGENTS.md conventions:
+
+1. **Repository Structure**: Module hierarchy with brief descriptions derived from file contents and function names.
+
+2. **Key Entry Points**: Files identified as entry points with their purpose (inferred from exports and naming).
+
+3. **Module Dependencies**: For each module, list what it depends on and what depends on it. Format as a dependency table.
+
+4. **API Surface**: Public exports from each module, grouped by type (functions, classes, types).
+
+5. **Patterns and Conventions**: Detected patterns from graph structure (e.g., "all services follow Repository pattern", "tests co-located with source").
+
+### Phase 3: AUDIT — Identify Coverage Gaps
+
+1. **Undocumented modules**: Use `check_docs` to find code nodes without `documents` edges.
+
+2. **Missing descriptions**: Modules with no README or doc file.
+
+3. **Stale references**: If an existing AGENTS.md exists, compare its file references against the graph to find mentions of files that no longer exist.
+
+### Phase 4: OUTPUT — Write Knowledge Map
+
+1. **Default**: Write to AGENTS.md in project root.
+2. **Custom path**: Write to specified output path.
+3. **Diff mode**: If AGENTS.md exists, show what changed rather than overwriting.
+
+### Output
+
+```
+## Generated Knowledge Map
+
+### Repository Structure
+- **packages/core/** — Core library: context assembly, entropy detection, constraints, feedback
+  - src/context/ — Token budget, filtering, doc coverage, knowledge map validation
+  - src/entropy/ — Drift detection, dead code analysis, pattern violations
+  - src/constraints/ — Layer validation, circular dependency detection, boundaries
+  - src/feedback/ — Self-review, peer review, diff analysis
+
+- **packages/graph/** — Knowledge graph: store, query, ingest, search
+  - src/store/ — LokiJS-backed graph store, vector store, serialization
+  - src/query/ — ContextQL traversal, projection
+  - src/ingest/ — Code, git, knowledge, connector ingestion
+  - src/search/ — FusionLayer hybrid search
+
+### Entry Points
+1. packages/core/src/index.ts — Core library barrel export
+2. packages/graph/src/index.ts — Graph library barrel export
+3. packages/cli/src/index.ts — CLI entry point (Commander.js)
+4. packages/mcp-server/src/server.ts — MCP server registration
+
+### Coverage Gaps
+- 3 modules have no documentation
+- 5 files have no test coverage
+```
+
+### Graph Refresh
+
+After generating documentation, refresh the graph so new `documents` edges reflect the updated docs:
+
+```
+harness scan [path]
+```
+
+This ensures subsequent graph queries (impact analysis, drift detection) include the newly generated documentation.
+
+## 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_docs` MCP tools.
+
+## Success Criteria
+
+- Knowledge map generated with all sections (structure, entry points, dependencies, API surface, patterns)
+- Coverage gaps identified (undocumented modules, missing descriptions, stale references)
+- Output written to AGENTS.md (or specified path) in proper markdown format
+- Report follows the structured output format
+- All findings are backed by graph query evidence, not heuristics
+
+## Examples
+
+### Example: Generating AGENTS.md from Graph
+
+```
+Input: No AGENTS.md exists, graph is current after harness scan
+
+1. SURVEY   — query_graph for module hierarchy: 4 packages found
+              search_similar for entry points: 4 identified
+              get_relationships for dependency flow per module
+2. GENERATE — Built 5 sections: structure, entry points,
+              dependencies, API surface, patterns
+3. AUDIT    — check_docs found 3 undocumented modules,
+              5 files with no test coverage
+4. OUTPUT   — Wrote AGENTS.md to project root (new file)
+
+Output:
+  AGENTS.md generated (142 lines)
+  Coverage gaps: 3 undocumented modules, 5 untested files
+  No stale references (fresh generation)
+```
+
+## Gates
+
+- **No generation without graph.** If no graph exists, stop and instruct to run `harness scan`.
+- **Never overwrite without confirmation.** If AGENTS.md exists, show the diff and ask before replacing.
+
+## Escalation
+
+- **When >50% of modules are undocumented**: Flag as critical documentation debt.
+- **When graph structure doesn't match directory structure**: The graph may be stale — recommend re-scanning.

package/dist/agents/skills/claude-code/harness-knowledge-mapper/skill.yaml

@@ -0,0 +1,49 @@
+name: harness-knowledge-mapper
+version: "1.0.0"
+description: Auto-generate always-current knowledge maps from graph topology
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+  - on_commit
+  - scheduled
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-knowledge-mapper
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: output
+      description: Output file path (default AGENTS.md)
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-knowledge-mapper
+    path: string
+type: rigid
+phases:
+  - name: survey
+    description: Query graph for module structure and topology
+    required: true
+  - name: generate
+    description: Generate structured knowledge map from graph data
+    required: true
+  - name: audit
+    description: Identify undocumented modules and coverage gaps
+    required: true
+  - name: output
+    description: Write knowledge map to file
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -73,6 +73,16 @@
    - Is documentation up to date with the code?
    - Are there tests? What is the approximate coverage?
 
+### Graph-Enhanced Context (when available)
+
+When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate codebase mapping:
+
+- `query_graph` — map architecture automatically from module and layer nodes, replacing manual directory walking
+- `search_similar` — find entry points and key files by querying for high-connectivity nodes
+- `get_relationships` — show layer dependencies and module structure as a traversable graph
+
+Graph queries produce a complete architecture map in seconds, including transitive relationships that directory inspection misses. Fall back to file-based commands if no graph is available.
+
 ### Phase 3: ORIENT — Identify Adoption Level and Maturity
 
 1. **Confirm the adoption level** matches what `harness.yaml` declares:

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

@@ -30,6 +30,15 @@ Before dispatching anything in parallel, rigorously verify independence:
 
 5. **When in doubt, run serially.** The cost of a false parallel dispatch (merge conflicts, subtle bugs, wasted work) far exceeds the cost of running serially.
 
+### Graph-Enhanced Context (when available)
+
+When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate independence verification:
+
+- `query_graph` — get the dependency subgraph per candidate task and check for node overlap between tasks
+- `get_impact` — verify tasks do not write to overlapping files or share transitive dependencies
+
+Automated graph-based independence verification replaces manual import grep and catches transitive overlaps that file-level checks miss. Fall back to file-based commands if no graph is available.
+
 ### Step 2: Create Focused Agent Tasks
 
 For each independent task, write a focused agent brief:

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

@@ -60,6 +60,15 @@ When writing observable truths and acceptance criteria, use EARS (Easy Approach
 
 **When to use EARS:** Apply these patterns when writing observable truths in Phase 1. Not every criterion needs an EARS pattern — use them when the requirement is behavioral (not structural). File existence checks ("src/types/user.ts exists with User interface") do not need EARS framing.
 
+### Graph-Enhanced Context (when available)
+
+When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate context:
+
+- `query_graph` — discover module dependencies for realistic task decomposition
+- `get_impact` — estimate which modules a feature touches and their dependencies
+
+Enables accurate effort estimation and task sequencing. Fall back to file-based commands if no graph is available.
+
 ---
 
 ### Phase 2: DECOMPOSE — Map File Structure and Create Tasks

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

@@ -61,6 +61,12 @@ Mechanical Checks:
 Action: Fix lint errors before committing.
 ```
 
+### Graph Freshness Check
+
+If a knowledge graph exists at `.harness/graph/` and code files have changed since the last scan, run `harness scan` before proceeding. The AI review phase uses graph-enhanced MCP tools (impact analysis, harness checks) that return stale results with an outdated graph.
+
+If no graph exists, skip this step — the tools fall back to non-graph behavior.
+
 ### Phase 2: Classify Changes
 
 Determine whether AI review is needed based on what changed.

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

@@ -32,6 +32,15 @@ If tests are not green before you start, you are not refactoring — you are deb
 
 4. **Plan the steps.** Break the refactoring into the smallest possible individual changes. Each step should be independently committable and verifiable. If you cannot describe a step in one sentence, it is too large.
 
+### Graph-Enhanced Context (when available)
+
+When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate context:
+
+- `get_impact` — precise impact analysis: "if I move this function, what breaks?"
+- `query_graph` — find all transitive consumers, not just direct importers
+
+Catches indirect consumers that grep misses. Fall back to file-based commands if no graph is available.
+
 ### Phase 2: Execute — One Small Change at a Time
 
 For EACH step in the plan:
@@ -62,6 +71,16 @@ For EACH step in the plan:
 
 2. **Run `harness validate` and `harness check-deps` one final time.** Clean output.
 
+### 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.
+
 3. **Review the cumulative diff.** Does the final state match the intended improvement? Is the code genuinely better, or just different?
 
 4. **If the refactoring introduced no improvement,** revert the entire sequence. Refactoring for its own sake is churn.

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.