@harness-engineering/cli 1.7.0 → 1.8.1

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

@@ -54,6 +54,18 @@ When the project has `design` configured in `harness.config.json`:
 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`.
@@ -75,6 +87,7 @@ Integrity Check: [PASS/FAIL]
 - 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]
@@ -82,7 +95,7 @@ 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).
+- 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.
@@ -100,6 +113,7 @@ Rules:
 - 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
 
@@ -119,6 +133,7 @@ Integrity Check: PASS
 - 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)
 ```
 
@@ -132,6 +147,7 @@ Integrity Check: FAIL
 - 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.

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

@@ -13,8 +13,35 @@
 
 ## 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.
+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
 
@@ -40,6 +67,20 @@ If the graph exists but code has changed since the last scan, re-run `harness sc
    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:
@@ -109,7 +150,7 @@ This ensures subsequent graph queries (impact analysis, drift detection) include
 
 ## Harness Integration
 
-- **`harness scan`** — Must run before this skill to ensure graph is current.
+- **`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.
 
@@ -119,7 +160,7 @@ This ensures subsequent graph queries (impact analysis, drift detection) include
 - 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
+- All findings are backed by graph query evidence (with graph) or directory/file analysis (without graph)
 
 ## Examples
 
@@ -145,7 +186,7 @@ Output:
 
 ## Gates
 
-- **No generation without graph.** If no graph exists, stop and instruct to run `harness scan`.
+- **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

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

@@ -45,34 +45,62 @@ Tier 1 violations are non-negotiable blockers. If a Tier 1 violation is detected
 
 ---
 
+### Graph Availability
+
+Hotspot scoring and coupling analysis benefit from the knowledge graph but work without it.
+
+**Staleness sensitivity:** Medium -- auto-refresh if >10 commits stale. Hotspot scoring uses churn data which does not change rapidly.
+
+| Feature                              | With Graph                                                   | Without Graph                                                                                                                    |
+| ------------------------------------ | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| Hotspot scoring (churn x complexity) | `GraphComplexityAdapter` computes from graph nodes           | `git log --format="%H" -- <file>` for per-file commit count; complexity from `check-perf --structural` output; multiply manually |
+| Coupling ratio                       | `GraphCouplingAdapter` computes from graph edges             | Parse import statements, count fan-out/fan-in per file                                                                           |
+| Critical path resolution             | Graph inference (high fan-in) + `@perf-critical` annotations | `@perf-critical` annotations only; grep for decorator/comment                                                                    |
+| Transitive dep depth                 | Graph BFS depth                                              | Import chain follow, 2 levels deep                                                                                               |
+
+**Notice when running without graph:** "Running without graph (run `harness scan` to enable hotspot scoring and coupling analysis)"
+
+**Impact on tiers:** Without graph, Tier 1 hotspot detection is degraded. Hotspot scoring falls back to churn-only (no complexity multiplication). This limitation is documented in the performance report output.
+
+---
+
 ### 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.
+1. **Check baseline lock-in.** Before running benchmarks, verify baselines are kept in sync:
+   - List all `.bench.ts` files changed in this PR: `git diff --name-only | grep '.bench.ts'`
+   - If any `.bench.ts` files are new or modified:
+     - Check if `.harness/perf/baselines.json` is also modified in this PR
+     - If NOT modified: flag as Tier 2 warning: "Benchmark files changed but baselines not updated. Run `harness perf baselines update` and commit the result."
+     - If modified: verify the updated baselines include entries for all changed benchmarks
+   - If no `.bench.ts` files changed: skip this check
+   - This check also runs standalone via `--check-baselines` flag
+
+2. **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. **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. **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. **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`:
+6. **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`:
+7. **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:**
+8. **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.
+9. **If this is a baseline-capture run,** report results without regression comparison. Recommend running `harness perf baselines update` to persist.
 
 ---
 
@@ -138,6 +166,7 @@ This phase runs only when `.bench.ts` files exist in the project. If none are fo
 - **`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 --check-baselines`** -- Verify baseline file is updated when benchmarks change. Runs the baseline lock-in check standalone.
 - **`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.

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

@@ -21,6 +21,9 @@ cli:
     - name: path
       description: Project root path
       required: false
+    - name: check-baselines
+      description: Verify baseline file is updated when benchmarks change
+      required: false
 mcp:
   tool: run_skill
   input:

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

@@ -60,10 +60,23 @@ If you find yourself writing production code before both the test and the benchm
 
 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
+3. **Run the benchmark** -- capture initial results and apply thresholds:
+
+   **When the spec defines a performance requirement** (e.g., "< 50ms"):
+   - Use the spec requirement as the benchmark assertion threshold
+   - Verify it passes; if not, see step 4
+
+   **When the spec is vague or silent on performance:**
+   - Fall back to harness-perf tier thresholds:
+     - Critical path functions (annotated `@perf-critical` or high fan-in): must not regress >5% from baseline (Tier 1)
+     - Non-critical functions: must not regress >10% from baseline (Tier 2)
+     - Structural complexity: must stay under Tier 2 thresholds (cyclomatic <=15, nesting <=4, function length <=50 lines, params <=5)
+   - These thresholds give developers concrete targets even when the spec does not specify performance requirements
+
+   **When no baseline exists (new code):**
+   - This run captures the initial baseline
+   - No regression comparison on first run
+   - VALIDATE phase (Phase 4) ensures the captured baseline is committed via `harness perf baselines update`
 
 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

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

@@ -38,6 +38,19 @@ Work backward from the goal. Do not start with "what should we build?" Start wit
 
 5. **Apply YAGNI.** For every artifact, ask: "Is this required for an observable truth?" If not, cut it.
 
+   When scope is ambiguous and requires clarification, use `emit_interaction`:
+
+   ```json
+   emit_interaction({
+     path: "<project-root>",
+     type: "question",
+     question: {
+       text: "The spec mentions X but does not define behavior for Y. Should we:",
+       options: ["A) Include Y in this plan", "B) Defer Y to a follow-up plan", "C) Update the spec first"]
+     }
+   })
+   ```
+
 #### EARS Requirement Patterns
 
 When writing observable truths and acceptance criteria, use EARS (Easy Approach to Requirements Syntax) sentence patterns. These patterns eliminate ambiguity by forcing a consistent grammatical structure.
@@ -73,6 +86,12 @@ Enables accurate effort estimation and task sequencing. Fall back to file-based
 
 ### Phase 2: DECOMPOSE — Map File Structure and Create Tasks
 
+When presenting the task breakdown, use progress markers:
+
+```
+**[Phase 2/4]** DECOMPOSE — mapping file structure and creating tasks
+```
+
 1. **Map the file structure first.** Before writing any tasks, list every file that will be created or modified. This is where decomposition decisions are locked. Example:
 
    ```
@@ -128,9 +147,11 @@ Enables accurate effort estimation and task sequencing. Fall back to file-based
 
 5. **Check failures log.** Read `.harness/failures.md` before finalizing. If planned approaches match known failures, flag them with warnings.
 
-6. **Write the plan to `docs/plans/`.** Use naming convention: `YYYY-MM-DD-<feature-name>-plan.md`. If the directory does not exist, create it.
+6. **Run soundness review.** After the plan passes completeness verification, invoke `harness-soundness-review --mode plan` against the draft. Do not proceed to write the plan until the soundness review converges with no remaining issues.
 
-7. **Write handoff.** Save `.harness/handoff.json` with the following structure:
+7. **Write the plan to `docs/plans/`.** Use naming convention: `YYYY-MM-DD-<feature-name>-plan.md`. If the directory does not exist, create it.
+
+8. **Write handoff.** Save `.harness/handoff.json` with the following structure:
 
    ```json
    {
@@ -145,7 +166,39 @@ Enables accurate effort estimation and task sequencing. Fall back to file-based
    }
    ```
 
-8. **Present the plan to the human for review.** Walk through the task list, the estimated timeline, and any checkpoints that require human input.
+9. **Request plan sign-off:**
+
+   ```json
+   emit_interaction({
+     path: "<project-root>",
+     type: "confirmation",
+     confirmation: {
+       text: "Approve plan at <plan-file-path>?",
+       context: "<task count> tasks, <estimated time> minutes. <one-sentence summary>"
+     }
+   })
+   ```
+
+10. **Suggest transition to execution.** After the human approves the plan:
+
+    Call `emit_interaction`:
+
+    ```json
+    {
+      "type": "transition",
+      "transition": {
+        "completedPhase": "planning",
+        "suggestedNext": "execution",
+        "reason": "Plan approved with all tasks defined",
+        "artifacts": ["<plan file path>"],
+        "requiresConfirmation": true,
+        "summary": "<Plan title> -- <N> tasks, <N> checkpoints. Estimated <time>."
+      }
+    }
+    ```
+
+    If the user confirms: invoke harness-execution with the plan path.
+    If the user declines: stop. The handoff is already written for future invocation.
 
 ---
 
@@ -155,7 +208,7 @@ Enables accurate effort estimation and task sequencing. Fall back to file-based
 # Plan: <Feature Name>
 
 **Date:** YYYY-MM-DD
-**Spec:** docs/specs/<spec-file>.md (if applicable)
+**Spec:** docs/changes/<feature>/proposal.md (if applicable)
 **Estimated tasks:** N
 **Estimated time:** N minutes
 
@@ -211,6 +264,7 @@ One sentence.
 - **Plan location** — Plans go to `docs/plans/`. Follow the naming convention: `YYYY-MM-DD-<feature-name>-plan.md`.
 - **Handoff to harness-execution** — Once the plan is approved, invoke harness-execution to begin task-by-task implementation.
 - **Task commands** — Every task includes exact harness CLI commands to run (e.g., `harness validate`, `harness check-deps`).
+- **`emit_interaction`** -- Call at the end of Phase 4 to suggest transitioning to harness-execution. Uses confirmed transition (waits for user approval).
 
 ## Change Specifications
 
@@ -232,7 +286,7 @@ When planning changes to existing functionality (not greenfield), express requir
 
 This is not mandatory for greenfield features. Only apply when modifying existing documented behavior.
 
-When `docs/specs/` exists in the project, produce `docs/changes/<feature>/delta.md` alongside the task plan. This keeps the change intent separate from the full spec and makes review easier.
+When `docs/changes/` exists in the project, produce `docs/changes/<feature>/delta.md` alongside the task plan. This keeps the change intent separate from the full spec and makes review easier.
 
 ## Success Criteria
 

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

@@ -15,6 +15,7 @@ tools:
   - Write
   - Edit
   - Glob
+  - emit_interaction
 cli:
   command: harness skill run harness-planning
   args:
@@ -45,3 +46,4 @@ state:
   files: []
 depends_on:
   - harness-verification
+  - harness-soundness-review

package/dist/agents/skills/claude-code/harness-release-readiness/SKILL.md

@@ -113,6 +113,20 @@ Run every check below. Record each as **pass**, **warn**, or **fail**:
 | `typecheck` or `tsc` script exists in root `package.json`       | fail                |
 | `harness validate` passes (project-level health check)          | fail                |
 
+##### i18n Coverage (conditional)
+
+When `i18n.enabled: true` in `harness.config.json`, run these checks:
+
+| Check                                                                                          | Severity if failing             |
+| ---------------------------------------------------------------------------------------------- | ------------------------------- |
+| Translation coverage meets `i18n.coverage.minimumPercent` for all target locales               | fail (strict) / warn (standard) |
+| No untranslated values (source text in target locale files) when `coverage.detectUntranslated` | warn                            |
+| All CLDR plural forms present for target locales when `coverage.requirePlurals`                | warn                            |
+| No stale translations (source changed since last translation timestamp)                        | warn                            |
+| `harness-i18n` scan passes with zero errors                                                    | fail (strict) / warn (standard) |
+
+If `i18n.enabled` is false or the `i18n` config block is absent, skip this section entirely and report it as "N/A" in the audit output.
+
 #### Comprehensive Checks (only with `--comprehensive`)
 
 These checks run only when `--comprehensive` is passed. They are slower and may require network access.
@@ -160,6 +174,7 @@ Packaging:  8/12 passed, 2 warnings, 2 failures
 Docs:       5/6 passed, 1 warning, 0 failures
 Hygiene:    3/5 passed, 2 warnings, 0 failures
 CI/CD:      4/5 passed, 1 warning, 0 failures
+i18n:       N/N passed, N warnings, N failures (or: skipped — i18n not enabled)
 [comprehensive] API Docs:  skipped (use --comprehensive)
 [comprehensive] Examples:  skipped (use --comprehensive)
 [comprehensive] Dep Health: skipped (use --comprehensive)
@@ -496,6 +511,7 @@ This framing is informational — it does not block anything. It gives the team
 - **Sub-skill invocations** — Phase 2 dispatches `detect-doc-drift`, `cleanup-dead-code`, `enforce-architecture`, and `diagnostics` as parallel agents. Phase 3 delegates fixes to `align-documentation` and `cleanup-dead-code`.
 - **State file** — `.harness/release-readiness.json` enables session resumption and progress tracking. This file is read at the start of each invocation and written at the end.
 - **Report file** — `release-readiness-report.md` is written to the project root. It is a snapshot, not a tracked artifact — regenerate it on each run.
+- **i18n coverage** — When `i18n.enabled: true`, Phase 1 checks translation coverage against configured thresholds. Uses `harness-i18n` scan results and `harness-i18n-workflow` coverage tracking. Blocks release in strict mode if coverage is below `i18n.coverage.minimumPercent`.
 
 ## Success Criteria