@harness-engineering/cli 1.4.0 → 1.6.1

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

@@ -0,0 +1,236 @@
+# Harness Perf TDD
+
+> Red-Green-Refactor with performance assertions. Every feature gets a correctness test AND a benchmark. No optimization without measurement.
+
+## When to Use
+
+- Implementing performance-critical features
+- When the spec includes performance requirements (e.g., "must respond in < 100ms")
+- When modifying `@perf-critical` annotated code
+- When adding hot-path logic (parsers, serializers, query resolvers, middleware)
+- NOT for non-performance-sensitive code (use harness-tdd instead)
+- NOT for refactoring existing code that already has benchmarks (use harness-refactoring + harness-perf)
+
+## Process
+
+### Iron Law
+
+**No production code exists without both a failing test AND a failing benchmark that demanded its creation.**
+
+If you find yourself writing production code before both the test and the benchmark exist, STOP. Write the test. Write the benchmark. Then implement.
+
+---
+
+### Phase 1: RED — Write Failing Test + Benchmark
+
+1. **Write the correctness test** following the same process as harness-tdd Phase 1 (RED):
+   - Identify the smallest behavior to test
+   - Write ONE minimal test with a clear assertion
+   - Follow the project's test conventions
+
+2. **Write a `.bench.ts` benchmark file** alongside the test file:
+   - Co-locate with source: `handler.ts` -> `handler.bench.ts`
+   - Use Vitest bench syntax for benchmark definitions
+   - Set a performance assertion if the spec includes one
+
+   ```typescript
+   import { bench, describe } from 'vitest';
+   import { processData } from './handler';
+
+   describe('processData benchmarks', () => {
+     bench('processData with small input', () => {
+       processData(smallInput);
+     });
+
+     bench('processData with large input', () => {
+       processData(largeInput);
+     });
+   });
+   ```
+
+3. **Run the test** — observe failure. The function is not implemented yet, so the test should fail with "not defined" or "not a function."
+
+4. **Run the benchmark** — observe failure or no baseline. This establishes that the benchmark exists and will track performance once the implementation lands.
+
+---
+
+### Phase 2: GREEN — Pass Test and Benchmark
+
+1. **Write the minimum implementation** to make the correctness test pass. Do not optimize yet. The goal is correctness first.
+
+2. **Run the test** — observe pass. If it fails, fix the implementation until it passes.
+
+3. **Run the benchmark** — capture initial results. This is the first measurement. Note:
+   - If a performance assertion exists in the spec, verify it passes
+   - If no assertion exists, record the result as a baseline reference
+   - Do not optimize at this stage unless the assertion fails
+
+4. **If the performance assertion fails,** you have two options:
+   - The implementation approach is fundamentally wrong (e.g., O(n^2) when O(n) is needed) — revise the algorithm
+   - The assertion is too aggressive for a first pass — note it and defer to REFACTOR phase
+
+---
+
+### Phase 3: REFACTOR — Optimize While Green
+
+This phase is optional. Enter it when:
+
+- The benchmark shows room for improvement against the performance requirement
+- Profiling reveals an obvious bottleneck
+- The code can be simplified while maintaining or improving performance
+
+1. **Profile the implementation** if the benchmark result is far from the requirement. Use the benchmark output to identify the bottleneck.
+
+2. **Refactor for performance** — consider:
+   - Algorithm improvements (sort, search, data structure choice)
+   - Caching or memoization for repeated computations
+   - Reducing allocations (object pooling, buffer reuse)
+   - Eliminating unnecessary work (early returns, lazy evaluation)
+
+3. **After each change,** run both checks:
+   - **Test:** Still passing? If not, the refactor broke correctness. Revert.
+   - **Benchmark:** Improved? If not, the refactor was not effective. Consider reverting.
+
+4. **Stop when** the benchmark meets the performance requirement, or when further optimization yields diminishing returns (< 1% improvement per change).
+
+5. **Do not gold-plate.** If the requirement is "< 100ms" and you are at 40ms, stop. Move on.
+
+---
+
+### Phase 4: VALIDATE — Harness Checks
+
+1. **Run `harness check-perf`** to verify no Tier 1 or Tier 2 violations were introduced by the implementation:
+   - Cyclomatic complexity within thresholds
+   - Coupling metrics acceptable
+   - No benchmark regressions in other modules
+
+2. **Run `harness validate`** to verify overall project health:
+   - All tests pass
+   - Linter clean
+   - Type checks pass
+
+3. **Update baselines** if this is a new benchmark:
+
+   ```bash
+   harness perf baselines update
+   ```
+
+   This persists the current benchmark results so future runs can detect regressions.
+
+4. **Commit with a descriptive message** that mentions both the feature and its performance characteristics:
+   ```
+   feat(parser): add streaming JSON parser (<50ms for 1MB payloads)
+   ```
+
+---
+
+## Benchmark File Convention
+
+Benchmark files are co-located with their source files, using the `.bench.ts` extension:
+
+| Source File                   | Benchmark File                      |
+| ----------------------------- | ----------------------------------- |
+| `src/parser/handler.ts`       | `src/parser/handler.bench.ts`       |
+| `src/api/resolver.ts`         | `src/api/resolver.bench.ts`         |
+| `packages/core/src/engine.ts` | `packages/core/src/engine.bench.ts` |
+
+Each benchmark file should:
+
+- Import only from the module under test
+- Define benchmarks in a `describe` block named after the module
+- Include both small-input and large-input cases when applicable
+- Use realistic data (not empty objects or trivial inputs)
+
+---
+
+## Harness Integration
+
+- **`harness check-perf`** — Run after implementation to check for violations
+- **`harness perf bench`** — Run benchmarks in isolation
+- **`harness perf baselines update`** — Persist benchmark results as new baselines
+- **`harness validate`** — Full project health check
+- **`harness perf critical-paths`** — View critical path set to understand which benchmarks have stricter thresholds
+
+## Success Criteria
+
+- Every new function has both a test file (`.test.ts`) and a bench file (`.bench.ts`)
+- Benchmarks run without errors
+- No Tier 1 performance violations after implementation
+- Baselines are updated for new benchmarks
+- Commit message includes performance context when relevant
+
+## Examples
+
+### Example: Implementing a Performance-Critical Parser
+
+**Phase 1: RED**
+
+```typescript
+// src/parser/json-stream.test.ts
+it('parses 1MB JSON in under 50ms', () => {
+  const result = parseStream(largeMbPayload);
+  expect(result).toEqual(expectedOutput);
+});
+
+// src/parser/json-stream.bench.ts
+bench('parseStream 1MB', () => {
+  parseStream(largeMbPayload);
+});
+```
+
+Run test: FAIL (parseStream not defined). Run benchmark: FAIL (no implementation).
+
+**Phase 2: GREEN**
+
+```typescript
+// src/parser/json-stream.ts
+export function parseStream(input: string): ParsedResult {
+  return JSON.parse(input); // simplest correct implementation
+}
+```
+
+Run test: PASS. Run benchmark: 38ms average (meets <50ms requirement).
+
+**Phase 3: REFACTOR** — skipped (38ms already meets 50ms target).
+
+**Phase 4: VALIDATE**
+
+```
+harness check-perf — no violations
+harness validate — passes
+harness perf baselines update — baseline saved
+git commit -m "feat(parser): add streaming JSON parser (<50ms for 1MB payloads)"
+```
+
+### Example: Optimizing an Existing Hot Path
+
+**Phase 1: RED** — test and benchmark already exist from initial implementation.
+
+**Phase 3: REFACTOR**
+
+```
+Before: resolveImports 12ms (requirement: <5ms)
+Change: switch from recursive descent to iterative with stack
+After:  resolveImports 3.8ms
+Test: still passing
+```
+
+**Phase 4: VALIDATE**
+
+```
+harness check-perf — complexity reduced from 12 to 8 (improvement)
+harness perf baselines update — new baseline saved
+```
+
+## Gates
+
+- **No code before test AND benchmark.** Both must exist before implementation begins.
+- **No optimization without measurement.** Run the benchmark before and after refactoring. Gut feelings are not measurements.
+- **No skipping VALIDATE.** `harness check-perf` and `harness validate` must pass after every cycle.
+- **No committing without updated baselines.** New benchmarks must have baselines persisted.
+
+## Escalation
+
+- **When the performance requirement cannot be met:** Report the best achieved result and propose either relaxing the requirement or redesigning the approach. Include benchmark data.
+- **When benchmarks are flaky:** Increase iteration count, add warmup, or isolate the benchmark from I/O. Report the variance so the team can decide on an acceptable noise margin.
+- **When the test and benchmark have conflicting needs:** Correctness always wins. If a correct implementation cannot meet the performance requirement, escalate to the team for a design decision.

package/dist/agents/skills/claude-code/harness-perf-tdd/skill.yaml

@@ -0,0 +1,47 @@
+name: harness-perf-tdd
+version: "1.0.0"
+description: Performance-aware TDD with benchmark assertions in the red-green-refactor cycle
+cognitive_mode: meticulous-implementer
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-perf-tdd
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-perf-tdd
+    path: string
+type: rigid
+phases:
+  - name: red
+    description: Write failing test and benchmark assertion
+    required: true
+  - name: green
+    description: Implement to pass test and benchmark
+    required: true
+  - name: refactor
+    description: Optimize while keeping both green
+    required: false
+  - name: validate
+    description: Run harness check-perf and harness validate
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on:
+  - harness-tdd
+  - harness-perf

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.
@@ -101,7 +107,29 @@ AI Review: SKIPPED (docs/config only)
 
 If any staged file contains code changes, proceed to Phase 3.
 
-### Phase 3: AI Review (Lightweight)
+### Phase 3: Security Scan
+
+Run the built-in security scanner against staged files. This is a mechanical check — no AI judgment involved.
+
+```bash
+# Get list of staged source files
+git diff --cached --name-only --diff-filter=d | grep -E '\.(ts|tsx|js|jsx|go|py)$'
+```
+
+Use the `run_security_scan` MCP tool or invoke the scanner on the staged files. Report any findings:
+
+- **Error findings (blocking):** Hardcoded secrets, eval/injection, weak crypto — these block the commit just like lint failures.
+- **Warning/info findings (advisory):** CORS wildcards, HTTP URLs, disabled TLS — reported but do not block.
+
+Include security scan results in the report output:
+
+```
+Security Scan: [PASS/WARN/FAIL] (N errors, N warnings)
+```
+
+If no source files are staged, skip the security scan.
+
+### Phase 4: AI Review (Lightweight)
 
 Perform a focused, lightweight review of staged changes. This is NOT a full code review — it catches obvious issues only.
 
@@ -116,7 +144,7 @@ git diff --cached
 Review the staged diff for these high-signal issues only:
 
 - **Obvious bugs:** null dereference, infinite loops, off-by-one errors, resource leaks
-- **Security issues:** hardcoded secrets, SQL injection, path traversal, unvalidated input
+- **Security issues:** hardcoded secrets, SQL injection, path traversal, unvalidated input (complements the mechanical scan with semantic analysis — e.g., tracing user input across function boundaries)
 - **Broken imports:** references to files/modules that do not exist
 - **Debug artifacts:** console.log, debugger statements, TODO/FIXME without issue reference
 - **Type mismatches:** function called with wrong argument types (if visible in diff)
@@ -139,6 +167,7 @@ Mechanical Checks:
 - Lint: PASS
 - Types: PASS
 - Tests: PASS (12/12)
+- Security Scan: PASS (0 errors, 0 warnings)
 
 AI Review: PASS (no issues found)
 ```
@@ -152,6 +181,8 @@ Mechanical Checks:
 - Lint: PASS
 - Types: PASS
 - Tests: PASS (12/12)
+- Security Scan: WARN (0 errors, 1 warning)
+  - [SEC-NET-001] src/cors.ts:5 — CORS wildcard origin
 
 AI Review: 2 observations
 1. [file:line] Possible null dereference — `user.email` accessed without null check after `findUser()` which can return null.

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.