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.