Harness Integrity

# Harness Integrity

> Unified integrity gate — single invocation chains mechanical verification with AI-powered code review and produces a consolidated pass/fail report.

## When to Use

- Before opening or merging a pull request
- At project milestones as a comprehensive quality check
- When you need a single authoritative answer: "is this code ready to ship?"
- NOT after every task (use `harness-verify` for quick post-task checks)
- NOT for deep architectural audits (use `harness-verification` for that)

## Relationship to Other Skills

| Skill                        | What It Does                                   | Scope                  | Time  |
| ---------------------------- | ---------------------------------------------- | ---------------------- | ----- |
| **harness-verify**           | Mechanical only: typecheck, lint, test         | Exit codes             | ~30s  |
| **harness-code-review**      | AI only: change-type-aware review              | LLM analysis           | ~2min |
| **harness-integrity** (this) | Both: verify + code-review unified             | Full pipeline          | ~3min |
| **harness-verification**     | Deep audit: architecture, patterns, edge cases | Thorough investigation | ~5min |

`harness-integrity` is the standard pre-PR gate. It runs the fast mechanical checks first, then layers on AI review, and produces a single consolidated report.

## Process

### Phase 1: VERIFY

Invoke `harness-verify` to run the mechanical quick gate.

1. Delegate entirely to `harness-verify` — typecheck, lint, test.
2. Capture the structured result (PASS/FAIL per check).
3. **If ALL three checks FAIL**, stop here. Do not proceed to Phase 2. The code is not in a reviewable state.
4. If at least one check passes (or some are skipped), proceed to Phase 2.

### Phase 1.5: SECURITY SCAN

Run the built-in security scanner as a mechanical check between verification and AI review.

1. Use `run_security_scan` MCP tool against the project root (or changed files if available).
2. Capture findings by severity: errors, warnings, info.
3. **Error-severity security findings are blocking** — they cause the overall integrity check to FAIL, same as a test failure.
4. Warning/info findings are included in the report but do not block.

### Phase 1.7: DESIGN HEALTH (conditional)

When the project has `design` configured in `harness.config.json`:

1. Run `harness-design` in review mode to check existing components against design intent and anti-patterns.
2. Run `harness-accessibility` in scan+evaluate mode to check WCAG compliance.
3. Combine findings into a design health summary:
   - Error count (blocking, based on strictness)
   - Warning count (non-blocking)
   - Info count (advisory)
4. **Error-severity design findings are blocking** in `strict` mode only. In `standard` and `permissive` modes, design findings do not block.
5. If no `design` block exists, skip this phase entirely.

### Phase 1.8: I18N SCAN (conditional)

When the project has `i18n.enabled: true` in `harness.config.json`:

1. Run `harness-i18n` in scan mode to detect hardcoded strings, missing translations, locale-sensitive formatting issues, and RTL violations.
2. Combine findings into an i18n health summary:
   - Error count (blocking, based on `i18n.strictness`)
   - Warning count (non-blocking)
   - Info count (advisory)
3. **Error-severity i18n findings are blocking** in `strict` mode only. In `standard` and `permissive` modes, i18n findings do not block.
4. If no `i18n` block exists or `i18n.enabled` is false, skip this phase entirely.

### Phase 2: REVIEW

Run change-type-aware AI review using `harness-code-review`.

1. Detect the change type if not provided: `feature`, `bugfix`, `refactor`, or `docs`.
2. Invoke `harness-code-review` with the detected change type.
3. Capture the review findings: suggestions, blocking issues, and notes.
4. A review finding is "blocking" only if it would cause a runtime error, data loss, or security vulnerability.
5. The AI review includes a security-focused pass that complements the mechanical scanner — checking for semantic issues like user input flowing to dangerous sinks across function boundaries.

### Phase 3: REPORT

Produce a unified integrity report in this exact format:

```
Integrity Check: [PASS/FAIL]
- Tests:    [PASS/FAIL/SKIPPED]
- Lint:     [PASS/FAIL/SKIPPED]
- Types:    [PASS/FAIL/SKIPPED]
- Security: [PASS/WARN/FAIL] ([count] errors, [count] warnings)
- Design:   [PASS/WARN/FAIL/SKIPPED] ([count] errors, [count] warnings)
- i18n:     [PASS/WARN/FAIL/SKIPPED] ([count] errors, [count] warnings)
- Review:   [PASS/FAIL] ([count] suggestions, [count] blocking)

Overall: [PASS/FAIL]
```

Rules:

- Overall `PASS` requires: all non-skipped mechanical checks pass AND zero blocking review findings AND zero blocking design findings (strict mode only) AND zero blocking i18n findings (strict mode only).
- Any mechanical failure OR any blocking review finding means `FAIL`.
- On FAIL, include a summary section listing each failure reason.
- Non-blocking review suggestions are noted but do not cause FAIL.

## Deterministic Checks

- **Phase 1 is fully deterministic.** Exit codes determine pass/fail with no interpretation.
- **Phase 2 involves LLM judgment.** The AI review may produce different results on repeated runs. Only "blocking" findings (runtime errors, data loss, security) affect the overall result.

## Harness Integration

- Chains harness-verify (mechanical) and harness-code-review (AI) into a unified pipeline
- Follows Principle 7 — deterministic checks always run first
- **`check_traceability`** — Include as part of the integrity gate to verify requirement coverage (every spec requirement maps to an implemented artifact and test).
- **`validate_cross_check`** — Run against the plan to verify plan-to-implementation alignment before producing the final report.
- Consumes change-type detection from harness-code-review for per-type checklists
- Output can be written to `.harness/integrity-report.md` for CI integration
- Invokes `harness-design` and `harness-accessibility` for design health when `design` config exists
- Design strictness from config controls whether design findings block the overall result
- Invokes `harness-i18n` for i18n compliance when `i18n.enabled` is true in config. i18n strictness controls whether findings block the overall result.

## Success Criteria

- [ ] Mechanical verification ran and produced structured results
- [ ] AI review ran with change-type awareness
- [ ] Unified report follows the exact format
- [ ] Overall verdict correctly reflects both mechanical and review results

## Rationalizations to Reject

These are common rationalizations that sound reasonable but lead to incorrect results. When you catch yourself thinking any of these, stop and follow the documented process instead.

| Rationalization                                                                                                | Why It Is Wrong                                                                                                                                    |
| -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| "All three mechanical checks failed, but I should still run the AI review to get useful feedback"              | When ALL three checks fail, stop immediately. Do not proceed to Phase 2. AI review on code that does not compile is wasted effort.                 |
| "The security scanner found a warning but it is not high severity, so it should not affect the overall result" | Error-severity security findings are blocking. The distinction is severity, not the agent's opinion of importance.                                 |
| "The AI review flagged an architectural concern as blocking, so the integrity check should fail"               | Only runtime errors, data loss, and security vulnerabilities count as blocking review findings. Architectural concerns are noted but do not block. |

## Examples

### Example: All Clear

```
Integrity Check: PASS
- Tests: PASS (42/42)
- Lint: PASS (0 warnings)
- Types: PASS
- Security: PASS (0 errors, 0 warnings)
- Design: PASS (0 errors, 0 warnings)
- i18n: PASS (0 errors, 0 warnings)
- Review: 1 suggestion (0 blocking)
```

### Example: Security Blocking Issue

```
Integrity Check: FAIL
- Tests: PASS (42/42)
- Lint: PASS
- Types: PASS
- Security: FAIL (1 error, 0 warnings)
  - [SEC-INJ-002] src/auth/login.ts:42 — SQL query built with string concatenation
- Design: WARN (0 errors, 2 warnings)
- i18n: SKIPPED
- Review: 3 findings (1 blocking)

Blocking: [SEC-INJ-002] SQL injection — user input passed directly to query without parameterization.
```

## Gates

- **Mechanical first.** Always run Phase 1 before Phase 2. If the code does not compile or pass basic checks, AI review is wasted effort (unless partial results exist).
- **No partial reports.** The report must include results from all phases that were executed. Do not output Phase 1 results without attempting Phase 2 (unless the all-fail early stop triggers).
- **Fresh execution only.** Do not reuse cached results. Run everything from scratch each time.

## Escalation

- **All checks fail:** If typecheck, lint, and test all fail in Phase 1, stop immediately. Report the failures and skip Phase 2. The code needs basic fixes before review is worthwhile.
- **Architectural concerns:** If the AI review identifies architectural concerns, note them in the report but do not mark them as blocking. Architectural decisions require human judgment.
- **Timeout:** Phase 1 inherits the 120-second per-command timeout from `harness-verify`. Phase 2 has a 180-second timeout for the AI review.
- **Missing dependencies:** If `harness-verify` or `harness-code-review` skills are unavailable, report the missing dependency and mark the corresponding phase as `ERROR`.