@harness-engineering/cli 1.4.0 → 1.6.1

package/dist/agents/skills/gemini-cli/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/gemini-cli/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/gemini-cli/harness-perf/SKILL.md

@@ -0,0 +1,231 @@
+# Harness Perf
+
+> Performance enforcement and benchmark management. Tier-based gates block commits and merges based on complexity, coupling, and runtime regression severity.
+
+## When to Use
+
+- After code changes to verify performance hasn't degraded
+- On PRs to enforce performance budgets
+- For periodic performance audits
+- NOT for initial development (use harness-tdd for that)
+- NOT for brainstorming performance improvements (use harness-brainstorming)
+
+## Process
+
+### Iron Law
+
+**No merge with Tier 1 performance violations. No commit with cyclomatic complexity exceeding the error threshold.**
+
+Tier 1 violations are non-negotiable blockers. If a Tier 1 violation is detected, execution halts and the violation must be resolved before any further progress. Do not attempt workarounds.
+
+---
+
+### Phase 1: ANALYZE — Structural and Coupling Checks
+
+1. **Run structural checks.** Execute `harness check-perf --structural` to compute complexity metrics for all changed files:
+   - Cyclomatic complexity per function
+   - Nesting depth per function
+   - File length (lines of code)
+   - Parameter count per function
+
+2. **Run coupling checks.** Execute `harness check-perf --coupling` to compute coupling metrics:
+   - Fan-in and fan-out per module
+   - Afferent and efferent coupling
+   - Transitive dependency depth
+   - Circular dependency detection
+
+3. **Classify violations by tier:**
+   - **Tier 1 (error, block commit):** Cyclomatic complexity > 15, circular dependencies, hotspot in top 5%
+   - **Tier 2 (warning, block merge):** Complexity > 10, nesting > 4, fan-out > 10, size budget exceeded
+   - **Tier 3 (info, no gate):** File length > 300, fan-in > 20, transitive depth > 30
+
+4. **If Tier 1 violations found,** report them immediately and STOP. Do not proceed to benchmarks. The violations must be fixed first.
+
+5. **If no violations found,** proceed to Phase 2.
+
+---
+
+### Phase 2: BENCHMARK — Runtime Performance
+
+This phase runs only when `.bench.ts` files exist in the project. If none are found, skip to Phase 3.
+
+1. **Check for benchmark files.** Scan the project for `*.bench.ts` files. If none exist, skip this phase entirely.
+
+2. **Verify clean working tree.** Run `git status --porcelain`. If there are uncommitted changes, STOP. Benchmarks on dirty trees produce unreliable results.
+
+3. **Run benchmarks.** Execute `harness perf bench` to run all benchmark suites.
+
+4. **Load baselines.** Read `.harness/perf/baselines.json` for previous benchmark results. If no baselines exist, treat this as a baseline-capture run.
+
+5. **Compare results against baselines** using the `RegressionDetector`:
+   - Calculate percentage change for each benchmark
+   - Apply noise margin (default: 3%) before flagging regressions
+   - Distinguish between critical-path and non-critical-path benchmarks
+
+6. **Resolve critical paths** via `CriticalPathResolver`:
+   - Check `@perf-critical` annotations in source files
+   - Check graph fan-in data (functions called by many consumers)
+   - Functions in the critical path set have stricter thresholds
+
+7. **Flag regressions by tier:**
+   - **Tier 1:** >5% regression on a critical path benchmark
+   - **Tier 2:** >10% regression on a non-critical-path benchmark
+   - **Tier 3:** >5% regression on a non-critical-path benchmark (within noise margin consideration)
+
+8. **If this is a baseline-capture run,** report results without regression comparison. Recommend running `harness perf baselines update` to persist.
+
+---
+
+### Phase 3: REPORT — Generate Performance Report
+
+1. **Format violations by tier.** Present Tier 1 violations first (most severe), then Tier 2, then Tier 3. Each violation entry includes:
+   - File path and function name
+   - Metric name and current value
+   - Threshold that was exceeded
+   - Tier classification and gate impact
+
+2. **Show hotspot scores** for top functions if knowledge graph data is available:
+   - Query the graph for functions with high churn + high fan-in
+   - Rank by composite hotspot score
+   - Flag any hotspots that also have performance violations
+
+3. **Show benchmark regression summary** if benchmarks ran:
+   - Table of benchmark name, baseline, current, delta percentage, tier
+   - Highlight critical-path benchmarks with a marker
+   - Show noise margin and whether the regression exceeds it
+
+4. **Recommend specific actions** for each Tier 1 and Tier 2 violation:
+   - For high complexity: suggest extract-method or strategy pattern refactoring
+   - For high coupling: suggest interface extraction or dependency inversion
+   - For benchmark regressions: suggest profiling the specific code path
+   - For size budget violations: suggest module decomposition
+
+5. **Output the report** in structured markdown format suitable for PR comments or CI output.
+
+---
+
+### Phase 4: ENFORCE — Apply Gate Decisions
+
+1. **Tier 1 violations present** — FAIL. Block commit and merge. List all Tier 1 violations with their locations and values. The developer must fix these before proceeding.
+
+2. **Tier 2 violations present, no Tier 1** — WARN. Allow commit but block merge until addressed. List all Tier 2 violations. These must be resolved before the PR can be merged.
+
+3. **Only Tier 3 or no violations** — PASS. Proceed normally. Log Tier 3 violations as informational notes.
+
+4. **Record gate decision** in `.harness/state.json` under a `perfGate` key:
+
+   ```json
+   {
+     "perfGate": {
+       "result": "pass|warn|fail",
+       "tier1Count": 0,
+       "tier2Count": 0,
+       "tier3Count": 0,
+       "timestamp": "ISO-8601"
+     }
+   }
+   ```
+
+5. **Exit with appropriate code:** 0 for pass, 1 for fail, 0 for warn (with warning output).
+
+---
+
+## Harness Integration
+
+- **`harness check-perf`** — Primary command for all performance checks. Runs structural and coupling analysis.
+- **`harness check-perf --structural`** — Run only structural complexity checks.
+- **`harness check-perf --coupling`** — Run only coupling analysis.
+- **`harness perf bench`** — Run benchmarks only. Requires clean working tree.
+- **`harness perf baselines show`** — View current benchmark baselines.
+- **`harness perf baselines update`** — Persist current benchmark results as new baselines.
+- **`harness perf critical-paths`** — View the current critical path set and how it was determined.
+- **`harness validate`** — Run after enforcement to verify overall project health.
+- **`harness graph scan`** — Refresh knowledge graph for accurate hotspot scoring.
+
+## Tier Classification
+
+| Tier | Severity | Gate         | Examples                                                                                            |
+| ---- | -------- | ------------ | --------------------------------------------------------------------------------------------------- |
+| 1    | error    | Block commit | Cyclomatic complexity > 15, >5% regression on critical path, hotspot in top 5%, circular dependency |
+| 2    | warning  | Block merge  | Complexity > 10, nesting > 4, >10% regression elsewhere, fan-out > 10, size budget exceeded         |
+| 3    | info     | None         | File length > 300 lines, fan-in > 20, transitive depth > 30, >5% non-critical regression            |
+
+## Success Criteria
+
+- All Tier 1 violations are resolved before proceeding
+- Performance report follows structured format with tier classification
+- Benchmark regressions are compared against noise margin before flagging
+- Gate decision is recorded in state
+- `harness validate` passes after enforcement
+
+## Examples
+
+### Example: PR with High Complexity Function
+
+```
+Phase 1: ANALYZE
+  harness check-perf --structural
+  Result: processOrderBatch() in src/orders/processor.ts has cyclomatic complexity 18 (Tier 1, threshold: 15)
+
+Phase 2: BENCHMARK — skipped (Tier 1 violation found)
+
+Phase 3: REPORT
+  TIER 1 VIOLATIONS (1):
+    - src/orders/processor.ts:processOrderBatch — complexity 18 > 15
+      Recommendation: Extract validation and transformation into separate functions
+
+Phase 4: ENFORCE
+  Result: FAIL — 1 Tier 1 violation. Commit blocked.
+```
+
+### Example: Benchmark Regression on Critical Path
+
+```
+Phase 1: ANALYZE — no structural violations
+
+Phase 2: BENCHMARK
+  harness perf bench
+  Baseline: parseDocument 4.2ms, current: 4.8ms (+14.3%)
+  parseDocument is @perf-critical — Tier 1 threshold applies (>5%)
+
+Phase 3: REPORT
+  TIER 1 VIOLATIONS (1):
+    - parseDocument: 14.3% regression on critical path (threshold: 5%)
+      Recommendation: Profile parseDocument to identify the regression source
+
+Phase 4: ENFORCE
+  Result: FAIL — 1 Tier 1 violation. Merge blocked.
+```
+
+### Example: Clean PR with Minor Warnings
+
+```
+Phase 1: ANALYZE
+  harness check-perf --structural --coupling
+  Result: src/utils/formatter.ts has 320 lines (Tier 3, threshold: 300)
+
+Phase 2: BENCHMARK
+  harness perf bench — all within noise margin
+
+Phase 3: REPORT
+  TIER 3 INFO (1):
+    - src/utils/formatter.ts: 320 lines > 300 line threshold
+  No Tier 1 or Tier 2 violations.
+
+Phase 4: ENFORCE
+  Result: PASS — no blocking violations.
+```
+
+## Gates
+
+- **No ignoring Tier 1 violations.** They must be fixed or the threshold must be reconfigured (with documented justification).
+- **No running benchmarks with dirty working tree.** Uncommitted changes invalidate benchmark results.
+- **No updating baselines without running benchmarks.** Baselines must come from fresh runs against committed code.
+- **No suppressing violations without documentation.** If a threshold is relaxed, the rationale must be documented in the project configuration.
+
+## Escalation
+
+- **When Tier 1 violations cannot be fixed within the current task:** Propose refactoring the function into smaller units, or raising the threshold with a documented justification. Do not silently skip the violation.
+- **When benchmark results are noisy or inconsistent:** Increase warmup iterations, pin the runtime environment, or run benchmarks in isolation. Report the noise level so the developer can make an informed decision.
+- **When critical path detection seems wrong:** Check `@perf-critical` annotations in source files and verify graph fan-in thresholds. The critical path set can be overridden in `.harness/perf/critical-paths.json`.
+- **When a violation is a false positive:** Document it with a `// perf-ignore: <reason>` comment and add the exception to `.harness/perf/exceptions.json`.

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

@@ -0,0 +1,47 @@
+name: harness-perf
+version: "1.0.0"
+description: Performance enforcement and benchmark management
+cognitive_mode: meticulous-verifier
+triggers:
+  - manual
+  - on_pr
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-perf
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-perf
+    path: string
+type: rigid
+phases:
+  - name: analyze
+    description: Run structural complexity and coupling checks
+    required: true
+  - name: benchmark
+    description: Run benchmarks and detect regressions
+    required: false
+  - name: report
+    description: Generate perf report with violations and recommendations
+    required: true
+  - name: enforce
+    description: Apply tier-based gate decisions
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on:
+  - harness-verify