@harness-engineering/cli 1.14.0 → 1.16.0

package/dist/agents/skills/codex/harness-integration-test/skill.yaml

@@ -0,0 +1,73 @@
+name: harness-integration-test
+version: "1.0.0"
+description: Service boundary testing, API integration testing, and consumer-driven contract validation
+cognitive_mode: meticulous-verifier
+triggers:
+  - manual
+  - on_new_feature
+  - on_pr
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - emit_interaction
+cli:
+  command: harness skill run harness-integration-test
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: scope
+      description: "Test scope: api, contract, or full. Defaults to full."
+      required: false
+    - name: service
+      description: "Target service name for focused testing. Tests all services when omitted."
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-integration-test
+    path: string
+type: rigid
+tier: 3
+internal: false
+keywords:
+  - integration test
+  - contract test
+  - Pact
+  - service boundary
+  - API test
+  - mock service
+  - test container
+  - supertest
+  - httptest
+  - consumer-driven
+stack_signals:
+  - "tests/integration/"
+  - "src/**/__integration__/"
+  - "pact/"
+  - "contract-tests/"
+  - "tests/api/"
+phases:
+  - name: discover
+    description: Map service boundaries, API endpoints, and inter-service dependencies
+    required: true
+  - name: mock
+    description: Configure mock services, test containers, and contract stubs
+    required: true
+  - name: implement
+    description: Write integration tests covering API contracts, error scenarios, and boundary conditions
+    required: true
+  - name: validate
+    description: Execute tests against real or containerized services and verify contract compliance
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/harness-integrity/SKILL.md

@@ -0,0 +1,167 @@
+# 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
+- 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
+
+## 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`.

package/dist/agents/skills/codex/harness-integrity/skill.yaml

@@ -0,0 +1,48 @@
+name: harness-integrity
+version: "1.0.0"
+description: Unified integrity gate — chains verify (quick gate) with AI review into a single report
+triggers:
+  - manual
+  - on_pr
+  - on_milestone
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-integrity
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: change-type
+      description: "Type of change: feature, bugfix, refactor, docs"
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-integrity
+    path: string
+type: rigid
+tier: 2
+cognitive_mode: meticulous-verifier
+phases:
+  - name: verify
+    description: Run harness-verify quick gate (test, lint, typecheck)
+    required: true
+  - name: review
+    description: Run change-type-aware AI review
+    required: true
+  - name: report
+    description: Produce unified integrity report
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on:
+  - harness-verify
+  - harness-code-review

package/dist/agents/skills/codex/harness-knowledge-mapper/SKILL.md

@@ -0,0 +1,195 @@
+# 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 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 10 commits behind (`git log --oneline <scanTimestamp>..HEAD | wc -l`),
+run `harness scan` to refresh before proceeding. (Staleness sensitivity: **Medium**)
+
+**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.
+
+### Pipeline Context (when orchestrated)
+
+When invoked by `harness-docs-pipeline`, check for a `pipeline` field in `.harness/handoff.json`:
+
+- If `pipeline` field exists: read `DocPipelineContext` from it
+  - If `pipeline.bootstrapped === true`, this is a bootstrap invocation — generate full AGENTS.md without confirmation prompt
+  - Write any generated documentation back as `DocFix[]` to `pipeline.fillsApplied`
+  - This enables the orchestrator to track what was generated and verify it
+- If `pipeline` field does not exist: behave exactly as today (standalone mode)
+
+No changes to the skill's interface or output format — the pipeline field is purely additive.
+
+## 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)
+   ```
+
+#### Fallback (without graph)
+
+When no graph is available, use directory structure and file analysis:
+
+1. **Module hierarchy from directories**: Use the directory structure as the module hierarchy — each directory represents a module. Glob for all source files to build the tree.
+2. **Entry points**: Check `package.json` for `main` and `exports` fields. Glob for `src/index.*` and `index.*` patterns. These are the entry points.
+3. **Source file inventory**: Glob for all source files (`**/*.ts`, `**/*.tsx`, `**/*.js`, `**/*.jsx`, etc.).
+4. **Documentation inventory**: Glob for all doc files (`**/*.md`, `docs/**/*`).
+5. **Undocumented module detection**: Diff the source directory set against the doc directory set. Source directories with no corresponding docs (no README.md, no matching doc file) are undocumented.
+6. **Existing knowledge map**: Read existing AGENTS.md if present for current knowledge map state.
+7. **Dependency flow (approximate)**: Parse import statements in each module's files to determine which modules depend on which others.
+
+> Fallback completeness: ~50% — no semantic grouping; modules grouped by directory only; no cross-cutting concern detection.
+
+### 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`** — Recommended before this skill for full graph-enhanced analysis. If graph is missing, skill uses directory structure fallbacks.
+- **`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 (with graph) or directory/file analysis (without graph)
+
+## 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
+
+- **Graph preferred, fallback available.** If no graph exists, use directory structure and file analysis to build the knowledge map. Do not stop — produce the best map possible.
+- **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/codex/harness-knowledge-mapper/skill.yaml

@@ -0,0 +1,50 @@
+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
+  - on_milestone
+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
+internal: true
+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: []