@harness-engineering/cli 1.7.0 → 1.8.0

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

@@ -12,8 +12,23 @@
 
 ## 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.
+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
 
@@ -50,6 +65,20 @@ Query the graph for five key structural indicators:
 
 5. **Module cohesion**: For each module (directory), count internal vs external edges. Low internal cohesion (many external edges, few internal) suggests misplaced code.
 
+#### Fallback (without graph)
+
+When no graph is available, use static analysis to approximate structural metrics:
+
+1. **Build adjacency list**: Grep all source files for `import`/`require` statements. Parse each to extract the imported path. Build an adjacency list mapping each file to its imports.
+2. **Hub detection**: From the adjacency list, count inbound edges per file. Files with >10 importers are hubs.
+3. **Orphan detection**: Files with zero inbound edges that are not entry points (not `index.*`, not in `package.json` main/exports). Use glob to find all source files, then subtract those that appear as import targets.
+4. **Cycle detection**: Run DFS on the adjacency list. When a back-edge is found, report the cycle path.
+5. **Deep chain detection**: From entry points, DFS to find the longest import chain. Report chains exceeding 7 hops.
+6. **Module cohesion (approximate)**: For each directory, count imports that stay within the directory (internal) vs imports that leave it (external). Cohesion = internal / (internal + external).
+7. **Run `check_dependencies` CLI** — this works without a graph and can detect layer violations.
+
+> Fallback completeness: ~60% — cannot compute transitive depth beyond what import parsing reveals; coupling metrics are approximate.
+
 ### Phase 2: SCORE — Calculate Health Score
 
 Compute a weighted health score (0-100):
@@ -104,7 +133,7 @@ For each problem found, generate a specific, actionable recommendation:
 
 ## Harness Integration
 
-- **`harness scan`** — Must run before this skill to ensure graph is current.
+- **`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_relationships`, and `check_dependencies` MCP tools.
 
@@ -114,7 +143,7 @@ For each problem found, generate a specific, actionable recommendation:
 - 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
+- All findings are backed by graph query evidence (with graph) or systematic static analysis (without graph)
 
 ## Examples
 
@@ -141,8 +170,8 @@ Output:
 
 ## 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.
+- **Graph preferred, fallback available.** If no graph exists, use fallback strategies (import parsing, DFS cycle detection, hub/orphan identification). Do not stop — produce the best analysis possible.
+- **Systematic analysis required.** All metrics must come from graph queries (with graph) or systematic import parsing (without graph). Do not guess — parse actual import statements.
 
 ## Escalation
 

package/dist/agents/skills/gemini-cli/harness-docs-pipeline/SKILL.md

@@ -0,0 +1,460 @@
+# Harness Docs Pipeline
+
+> Orchestrator composing 4 documentation skills into a sequential pipeline with convergence-based remediation, producing a qualitative documentation health report.
+
+## When to Use
+
+- When you want a single-command documentation health check across drift, coverage, links, and freshness
+- After major refactoring that may have caused widespread documentation drift
+- As a periodic hygiene check (weekly or per-sprint)
+- When onboarding a new project that has no AGENTS.md (bootstrap mode)
+- When `on_doc_check` triggers fire
+- NOT for fixing a single known drift issue (use align-documentation directly)
+- NOT for generating AGENTS.md from scratch when you know you have a graph (use harness-knowledge-mapper directly)
+- NOT for validating a single file's context (use validate-context-engineering directly)
+
+## Relationship to Sub-Skills
+
+| Skill                        | Pipeline Phase | Role                                        |
+| ---------------------------- | -------------- | ------------------------------------------- |
+| detect-doc-drift             | DETECT         | Find drift between code and docs            |
+| align-documentation          | FIX            | Apply fixes for drift findings              |
+| validate-context-engineering | AUDIT          | Find gaps in documentation coverage         |
+| harness-knowledge-mapper     | FILL           | Generate/regenerate AGENTS.md and fill gaps |
+
+This orchestrator delegates to sub-skills — it never reimplements their logic. Each sub-skill retains full standalone functionality.
+
+## Iron Law
+
+**The pipeline delegates, never reimplements.** If you find yourself writing drift detection logic, fix application logic, or gap analysis logic inside the pipeline, STOP. Delegate to the dedicated sub-skill.
+
+**Safe fixes are silent, unsafe fixes surface.** Never apply a fix classified as `unsafe` without explicit user approval. Never prompt the user for a fix classified as `safe`.
+
+## Flags
+
+| Flag           | Effect                                                            |
+| -------------- | ----------------------------------------------------------------- |
+| `--fix`        | Enable convergence-based auto-fix (default: detect + report only) |
+| `--no-freshen` | Skip graph staleness check                                        |
+| `--bootstrap`  | Force AGENTS.md regeneration even if one exists                   |
+| `--ci`         | Non-interactive: apply safe fixes only, report everything else    |
+
+## Shared Context Object
+
+All phases read from and write to a shared `DocPipelineContext`:
+
+```typescript
+interface DocPipelineContext {
+  // Pipeline state
+  graphAvailable: boolean;
+  agentsMdExists: boolean;
+  bootstrapped: boolean; // true if AGENTS.md was created this run
+
+  // Phase outputs
+  driftFindings: DriftFinding[];
+  fixesApplied: DocFix[];
+  gapFindings: GapFinding[];
+  fillsApplied: DocFix[];
+  exclusions: Set<string>; // finding IDs already addressed
+
+  // Health verdict
+  verdict: 'pass' | 'warn' | 'fail';
+  summary: string;
+}
+
+interface DriftFinding {
+  id: string;
+  file: string;
+  line?: number;
+  driftType: 'renamed' | 'new-code' | 'deleted-code' | 'changed-behavior' | 'moved-code';
+  priority: 'critical' | 'high' | 'medium' | 'low';
+  staleText: string;
+  codeChange: string;
+  suggestedFix: string;
+  fixSafety: 'safe' | 'probably-safe' | 'unsafe';
+}
+
+interface GapFinding {
+  id: string;
+  file?: string;
+  gapType: 'undocumented' | 'broken-link' | 'stale-section' | 'missing-context';
+  priority: 'critical' | 'high' | 'medium' | 'low';
+  description: string;
+  suggestedFix: string;
+  fixSafety: 'safe' | 'probably-safe' | 'unsafe';
+}
+
+interface DocFix {
+  findingId: string;
+  file: string;
+  oldText: string;
+  newText: string;
+  safety: 'safe' | 'probably-safe';
+  verified: boolean; // harness check-docs passed after applying
+}
+```
+
+The context is passed to sub-skills via `handoff.json` with a `pipeline` field. Sub-skills check for this field; if absent, they run in standalone mode.
+
+## Process
+
+### Phase 1: FRESHEN — Graph Freshness and AGENTS.md Bootstrap
+
+**Skip this phase if `--no-freshen` flag is set.**
+
+1. **Check graph existence.** Look for `.harness/graph/` directory.
+   - If exists: set `context.graphAvailable = true`
+   - If not: set `context.graphAvailable = false`, log notice: "No knowledge graph available. Pipeline will use static analysis fallbacks. Run `harness scan` for richer results."
+
+2. **Check graph staleness** (only if graph exists).
+   - Count commits since last graph update: `git rev-list --count HEAD ^$(cat .harness/graph/.last-scan-commit 2>/dev/null || echo HEAD)`
+   - If >10 commits behind: run `harness scan` to refresh
+   - If <=10 commits: proceed with current graph
+
+3. **Check AGENTS.md existence.**
+   - If exists and `--bootstrap` not set: set `context.agentsMdExists = true`, proceed to DETECT
+   - If exists and `--bootstrap` set: proceed to step 4 (regenerate)
+   - If not exists: proceed to step 4
+
+4. **Bootstrap AGENTS.md.**
+
+   **If graph available:**
+   - Invoke `harness-knowledge-mapper` to generate AGENTS.md
+   - Set `context.bootstrapped = true`
+   - Set `context.agentsMdExists = true`
+
+   **If no graph (directory structure fallback):**
+   - Glob source directories: `src/*/`, `packages/*/`, `lib/*/`
+   - Read `package.json` for project name and description
+   - Identify entry points: files matching `src/index.*`, `main` field in package.json
+   - List top-level modules: each immediate subdirectory of `src/` (or `packages/`) with its directory name as the module name
+   - Generate minimal AGENTS.md:
+
+     ```markdown
+     # AGENTS.md
+
+     > Generated from directory structure. Run `harness scan` for richer output.
+
+     ## Project
+
+     <name from package.json> — <description from package.json>
+
+     ## Entry Points
+
+     - <each identified entry point>
+
+     ## Modules
+
+     - **<dir-name>/** — <inferred from directory name>
+     ```
+
+   - Set `context.bootstrapped = true`
+   - Set `context.agentsMdExists = true`
+
+5. Proceed to DETECT phase.
+
+### Phase 2: DETECT — Find Documentation Drift
+
+1. **Write pipeline context to handoff.json.** Set the `pipeline` field in `.harness/handoff.json` with the current `DocPipelineContext` so detect-doc-drift can read it.
+
+2. **Invoke detect-doc-drift.** Run the skill's full process:
+   - Phase 1 (Scan): `harness check-docs` and `harness cleanup --type drift`
+   - Phase 2 (Identify): Classify each finding into drift types
+   - Phase 3 (Prioritize): Rank by impact (Critical > High > Medium > Low)
+   - Phase 4 (Report): Structured output
+
+3. **Populate context with DriftFinding objects.** For each finding from detect-doc-drift, create a `DriftFinding` with:
+   - `id`: deterministic hash of `file + line + driftType` (for dedup tracking)
+   - `driftType`: map to one of `renamed`, `new-code`, `deleted-code`, `changed-behavior`, `moved-code`
+   - `priority`: map to `critical`, `high`, `medium`, `low`
+   - `fixSafety`: classify using the safety table below
+
+4. **Store findings.** Set `context.driftFindings = <all DriftFinding objects>`.
+
+5. **If `--fix` flag is not set:** Skip to AUDIT phase (Phase 4).
+
+### Fix Safety Classification
+
+| Category        | Safe (apply silently)                                              | Probably safe (present diff)                                                    | Unsafe (surface to user)                                          |
+| --------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| **Drift fixes** | Update file path where rename is unambiguous; fix import reference | Rewrite description for simple rename/parameter change; update code examples    | Rewrite behavioral explanations; remove sections for deleted code |
+| **Gap fills**   | Add entry for new file with obvious single-purpose name            | Add entry for new file requiring description; update AGENTS.md section ordering | Write documentation for complex modules; create new doc pages     |
+| **Link fixes**  | Redirect broken link where target is unambiguous                   | Redirect when multiple candidates exist (present options)                       | Remove link when target no longer exists                          |
+
+### Phase 3: FIX — Convergence-Based Drift Remediation
+
+**This phase runs only when `--fix` flag is set.**
+
+#### Convergence Loop
+
+```
+previousCount = context.driftFindings.length
+maxIterations = 5
+
+while iteration < maxIterations:
+  1. Partition findings by safety
+  2. Apply safe fixes → verify → record
+  3. Present probably-safe fixes → apply approved → verify → record
+  4. Surface unsafe fixes to user (no auto-apply)
+  5. Re-run detect-doc-drift
+  6. newCount = remaining findings
+  7. if newCount >= previousCount: STOP (converged)
+  8. previousCount = newCount
+  9. iteration++
+```
+
+#### Step-by-step
+
+1. **Partition findings by fixSafety.**
+   - `safeFixes`: findings where `fixSafety === 'safe'`
+   - `probablySafeFixes`: findings where `fixSafety === 'probably-safe'`
+   - `unsafeFixes`: findings where `fixSafety === 'unsafe'`
+
+2. **Apply safe fixes silently.**
+   - Write pipeline context to handoff.json with `pipeline.fixBatch = safeFixes`
+   - Invoke align-documentation to apply the fixes
+   - Run `harness check-docs` after the batch
+   - If check passes: record each fix as a `DocFix` with `verified: true` in `context.fixesApplied`
+   - If check fails: revert the batch (`git checkout -- <files>`), record fixes as `verified: false`
+   - Add fixed finding IDs to `context.exclusions`
+
+3. **Present probably-safe fixes** (skip in `--ci` mode).
+   - For each fix, show the diff (oldText vs newText) to the user
+   - Apply user-approved fixes
+   - Run `harness check-docs` after the batch
+   - Same verify/revert logic as safe fixes
+   - Add fixed finding IDs to `context.exclusions`
+
+4. **Surface unsafe fixes.**
+   - List each unsafe finding with its `suggestedFix` text
+   - Do not apply — user must handle manually
+   - In `--ci` mode: log to report, do not prompt
+
+5. **Re-run detect-doc-drift** to check for cascading issues revealed by fixes.
+   - If new finding count < previous count: loop back to step 1
+   - If new finding count >= previous count: stop (converged or no progress)
+   - If max iterations reached: stop
+
+6. **Record remaining unfixed findings** for the REPORT phase.
+
+### Phase 4: AUDIT — Find Documentation Gaps
+
+1. **Write pipeline context to handoff.json.** Update the `pipeline` field with the current `DocPipelineContext` (including `exclusions` from FIX phase).
+
+2. **Invoke validate-context-engineering.** Run the skill's full process:
+   - Phase 1 (Audit): `harness validate` and `harness check-docs`
+   - Phase 2 (Detect Gaps): Classify into undocumented, broken-link, stale-section, missing-context
+   - Phase 3 (Suggest Updates): Generate specific suggestions
+   - Phase 4 (Apply): Deferred to FILL phase
+
+3. **Populate context with GapFinding objects.** For each finding, create a `GapFinding` with:
+   - `id`: deterministic hash of `file + gapType + description`
+   - `gapType`: map to `undocumented`, `broken-link`, `stale-section`, `missing-context`
+   - `priority`: map to `critical`, `high`, `medium`, `low`
+   - `fixSafety`: classify using the safety table from DETECT phase
+
+4. **Dedup against FIX phase.** Remove any `GapFinding` whose `id` appears in `context.exclusions`. This prevents double-counting items already fixed in the FIX phase.
+
+5. **Store findings.** Set `context.gapFindings = <deduplicated GapFinding objects>`.
+
+6. **If `--fix` flag is not set:** Skip to REPORT phase (Phase 6).
+
+### Phase 5: FILL — Convergence-Based Gap Remediation
+
+**This phase runs only when `--fix` flag is set.**
+
+1. **Check if AGENTS.md needs regeneration.** If `context.bootstrapped === true` and gap findings include AGENTS.md coverage issues, invoke harness-knowledge-mapper (if graph available) or the directory-structure fallback to improve AGENTS.md quality.
+
+2. **Run convergence loop** (same pattern as FIX phase):
+
+   ```
+   previousCount = context.gapFindings.length
+   maxIterations = 5
+
+   while iteration < maxIterations:
+     1. Partition findings by safety
+     2. Apply safe fills → verify → record
+     3. Present probably-safe fills → apply approved → verify → record
+     4. Surface unsafe fills to user
+     5. Re-run validate-context-engineering
+     6. newCount = remaining gaps (after dedup against exclusions)
+     7. if newCount >= previousCount: STOP (converged)
+     8. previousCount = newCount
+     9. iteration++
+   ```
+
+3. **Apply safe fills silently.**
+   - For `broken-link` with unambiguous target: redirect the link
+   - For `undocumented` with obvious single-purpose name: add minimal entry
+   - Run `harness check-docs` after each batch
+   - Record in `context.fillsApplied`
+   - Add filled finding IDs to `context.exclusions`
+
+4. **Present probably-safe fills** (skip in `--ci` mode).
+   - Show diff for: new file entries requiring description, AGENTS.md section reordering
+   - Apply approved fills, verify, record
+
+5. **Surface unsafe fills.**
+   - Documentation for complex modules, new doc pages
+   - Log for report, do not apply
+
+6. **Record remaining unfilled gaps** for the REPORT phase.
+
+### Phase 6: REPORT — Synthesize Health Verdict
+
+1. **Run final `harness check-docs`** to establish the post-pipeline state.
+
+2. **Compute verdict.**
+
+   **FAIL if any of:**
+   - Any critical drift findings remain unfixed
+   - `harness check-docs` fails after all fix attempts
+   - AGENTS.md does not exist and bootstrap failed
+
+   **WARN if any of:**
+   - High-priority drift or gap findings remain (user-deferred)
+   - > 30% of source modules are undocumented
+   - Graph not available (reduced accuracy notice)
+
+   **PASS if:**
+   - No critical or high findings remaining
+   - `harness check-docs` passes
+   - AGENTS.md exists and covers >70% of modules
+
+3. **Generate per-category breakdown:**
+
+   | Category  | Metric                                 |
+   | --------- | -------------------------------------- |
+   | Accuracy  | Drift findings remaining (by priority) |
+   | Coverage  | Undocumented modules remaining         |
+   | Links     | Broken references remaining            |
+   | Freshness | Graph staleness status                 |
+
+4. **List actions taken:**
+   - Auto-fixes applied (safe): count and file list
+   - User-approved fixes (probably-safe): count and file list
+   - Findings deferred to user (unsafe): count and details
+   - AGENTS.md bootstrapped: yes/no and method (graph or directory structure)
+
+5. **Set context verdict and summary.** Write `context.verdict` and `context.summary`.
+
+6. **Output report** to console. Format:
+
+   ```
+   === Documentation Health Report ===
+
+   Verdict: PASS | WARN | FAIL
+
+   Accuracy:  N drift findings remaining (0 critical, 0 high, N medium, N low)
+   Coverage:  N/M modules documented (N%)
+   Links:     N broken references remaining
+   Freshness: Graph current | Graph stale (N commits behind) | No graph
+
+   Actions:
+     - N safe fixes applied silently
+     - N probably-safe fixes applied (user-approved)
+     - N unsafe findings deferred to user
+     - AGENTS.md bootstrapped from <graph|directory structure>
+
+   Remaining findings:
+     [list of unfixed findings with priority and suggested action]
+   ```
+
+## Harness Integration
+
+- **`harness check-docs`** — Run in DETECT, after each fix batch in FIX/FILL, and in REPORT for final state
+- **`harness cleanup --type drift`** — Used by detect-doc-drift during DETECT phase
+- **`harness scan`** — Used in FRESHEN to refresh stale graph
+- **`harness validate`** — Run as final step in each task to verify project health
+
+## Success Criteria
+
+- `harness-docs-pipeline` runs all 4 sub-skills in the right order with shared context
+- FIX and FILL phases iterate until converged; cascading fixes are caught
+- Safe fixes are applied silently; unsafe changes surface to user
+- `harness check-docs` runs after every fix batch; failed fixes are reverted
+- Bootstrap handles cold start (no AGENTS.md) with graph path and directory structure fallback
+- Standalone skills work independently exactly as today when invoked without pipeline context
+- Entire pipeline runs without graph using static analysis fallbacks
+- PASS/WARN/FAIL report includes per-category breakdown and specific remaining findings
+- Drift fixes in FIX phase are excluded from AUDIT findings (no double-counting)
+
+## Examples
+
+### Example: Full pipeline run with fixes
+
+```
+Input: --fix flag set, graph available, AGENTS.md exists
+
+1. FRESHEN  — Graph exists, 3 commits behind (< 10, skip refresh)
+               AGENTS.md exists, no bootstrap needed
+2. DETECT   — detect-doc-drift found 8 findings:
+               2 critical (deleted file still referenced)
+               3 high (renamed functions)
+               2 medium (stale descriptions)
+               1 low (formatting)
+3. FIX      — Iteration 1:
+                 3 safe fixes applied (renamed file paths)
+                 2 probably-safe presented, 2 approved
+                 2 unsafe surfaced to user
+                 harness check-docs: pass
+               Re-detect: 1 new finding (cascading rename)
+               Iteration 2:
+                 1 safe fix applied
+                 Re-detect: 0 new findings — converged
+4. AUDIT    — validate-context-engineering found 5 gaps
+               2 already in exclusions (fixed in FIX) → 3 remaining
+5. FILL     — 1 safe fill (broken link redirect)
+               1 probably-safe (new module entry) → approved
+               1 unsafe (complex module docs) → deferred
+               Re-audit: converged
+6. REPORT   — Verdict: WARN
+               Accuracy: 2 drift findings remaining (0 critical, 0 high, 1 medium, 1 low)
+               Coverage: 12/14 modules documented (86%)
+               Links: 0 broken references
+               Freshness: Graph current
+```
+
+### Example: CI mode (non-interactive)
+
+```
+Input: --fix --ci flags set, no graph
+
+1. FRESHEN  — No graph (notice logged), AGENTS.md exists
+2. DETECT   — 4 findings (1 critical, 2 high, 1 medium)
+3. FIX      — 2 safe fixes applied silently
+               probably-safe and unsafe: logged to report (no prompts)
+4. AUDIT    — 2 gaps (1 deduped) → 1 remaining
+5. FILL     — 0 safe fills, 1 probably-safe logged to report
+6. REPORT   — Verdict: FAIL (1 critical finding remains)
+```
+
+### Example: Bootstrap from directory structure
+
+```
+Input: --bootstrap flag set, no graph, no AGENTS.md
+
+1. FRESHEN  — No graph, no AGENTS.md
+               Fallback bootstrap: glob src/*, read package.json
+               Generated minimal AGENTS.md (32 lines)
+               context.bootstrapped = true
+2. DETECT   — 0 drift findings (fresh AGENTS.md, no stale refs)
+3. AUDIT    — 6 gaps (4 undocumented modules, 2 missing context)
+4. REPORT   — Verdict: WARN (>30% modules undocumented, no graph)
+```
+
+## Gates
+
+- **No fix without verification.** Every fix batch must be followed by `harness check-docs`. If check fails, revert the batch.
+- **No unsafe auto-apply.** Fixes classified as `unsafe` are never applied without explicit user approval. In `--ci` mode, they are logged but never applied.
+- **No reimplementation of sub-skill logic.** The pipeline delegates to sub-skills. If the DETECT phase is writing drift detection code, the plan is wrong.
+- **No convergence without progress.** If a convergence loop iteration does not reduce the finding count, stop immediately. Do not retry.
+- **Max 5 iterations per convergence loop.** Hard cap to prevent runaway loops.
+
+## Escalation
+
+- **When findings exceed 50:** Focus on critical and high priority only. Defer medium and low to a follow-up run.
+- **When bootstrap produces low-quality AGENTS.md:** This is expected without a graph. Log a notice recommending `harness scan` and accept the reduced quality for the current run.
+- **When convergence loop does not converge within 5 iterations:** Stop the loop, log remaining findings, and proceed to the next phase. The report will reflect the unconverged state.
+- **When a sub-skill fails:** Log the failure, skip the phase, and continue the pipeline. The report will note the skipped phase with a WARN or FAIL verdict.
+- **When `harness check-docs` is unavailable:** Fall back to file existence checks and link validation via grep. Log a notice about reduced verification accuracy.

package/dist/agents/skills/gemini-cli/harness-docs-pipeline/skill.yaml

@@ -0,0 +1,69 @@
+name: harness-docs-pipeline
+version: "1.0.0"
+description: Orchestrator composing 4 documentation skills into a sequential pipeline with convergence-based remediation and qualitative health reporting
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+  - on_doc_check
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-docs-pipeline
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: fix
+      description: Enable convergence-based auto-fix (default detect + report only)
+      required: false
+    - name: no-freshen
+      description: Skip graph staleness check
+      required: false
+    - name: bootstrap
+      description: Force AGENTS.md regeneration even if one exists
+      required: false
+    - name: ci
+      description: Non-interactive mode — apply safe fixes only, report everything else
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-docs-pipeline
+    path: string
+type: rigid
+phases:
+  - name: freshen
+    description: Check graph freshness, detect AGENTS.md, trigger bootstrap if needed
+    required: true
+  - name: detect
+    description: Invoke detect-doc-drift, classify and prioritize findings
+    required: true
+  - name: fix
+    description: Convergence loop — classify, apply safe fixes, verify, re-detect
+    required: false
+  - name: audit
+    description: Invoke validate-context-engineering, find gaps, dedup against fixes
+    required: true
+  - name: fill
+    description: Convergence loop — fill gaps, regenerate AGENTS.md if needed, verify
+    required: false
+  - name: report
+    description: Synthesize verdict (PASS/WARN/FAIL) with per-category breakdown
+    required: true
+state:
+  persistent: false
+  files:
+    - .harness/handoff.json
+depends_on:
+  - detect-doc-drift
+  - align-documentation
+  - validate-context-engineering
+  - harness-knowledge-mapper

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

@@ -12,8 +12,21 @@
 
 ## 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.
+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
 
@@ -48,6 +61,19 @@ Rank files by:
 
 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:
@@ -90,7 +116,7 @@ Use `get_relationships` to check structural edges between co-change pairs.
 
 ## Harness Integration
 
-- **`harness scan`** — Must run before this skill to ensure graph is current.
+- **`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.
 
@@ -100,7 +126,7 @@ Use `get_relationships` to check structural edges between co-change pairs.
 - 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
+- All findings are backed by graph query evidence (with graph) or git log analysis (without graph)
 
 ## Examples
 
@@ -126,8 +152,8 @@ Output:
 
 ## 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.
+- **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