@harness-engineering/cli 1.7.0 → 1.8.0

package/dist/agents/personas/documentation-maintainer.yaml

@@ -1,11 +1,13 @@
 version: 1
 name: Documentation Maintainer
 description: Keeps documentation in sync with source code
-role: Detect documentation drift, validate doc coverage, align docs with code changes
+role: Detect documentation drift, validate doc coverage, align docs with code changes, run full documentation health pipeline
 skills:
   - detect-doc-drift
   - align-documentation
   - harness-knowledge-mapper
+  - validate-context-engineering
+  - harness-docs-pipeline
 commands:
   - check-docs
   - validate

package/dist/agents/personas/performance-guardian.yaml

@@ -5,6 +5,7 @@ role: Run structural complexity checks, coupling analysis, benchmark regression
 skills:
   - harness-perf
   - harness-tdd
+  - harness-perf-tdd
 commands:
   - check-perf
   - perf
@@ -20,6 +21,28 @@ config:
   severity: error
   autoFix: false
   timeout: 300000
+steps:
+  - command: validate
+    when: always
+  - command: check-deps
+    when: always
+  - command: check-perf --structural
+    when: always
+  - command: check-perf --coupling
+    when: always
+  - skill: harness-perf
+    phases: [BENCHMARK, REPORT, ENFORCE]
+    when: on_pr
+  - check: missing-benchmarks
+    when: on_pr
+missing_benchmark_detection:
+  description: Detect new/modified source files without co-located benchmarks
+  logic:
+    - step: Identify new/modified source files in the PR diff
+    - step: For each file, check if a co-located .bench.ts file exists
+    - step: "If file is on a @perf-critical path (via get_critical_paths) and has no benchmark: flag Tier 2 warning"
+    - step: "If file is not critical but is new: flag Tier 3 info suggesting harness-perf-tdd"
+    - step: 'Output example: "New file src/core/parser.ts is on a critical path but has no benchmark. Consider using harness-perf-tdd to add one."'
 outputs:
   agents-md: true
   ci-workflow: true

package/dist/agents/skills/claude-code/align-documentation/SKILL.md

@@ -40,6 +40,19 @@ When a knowledge graph exists at `.harness/graph/`, use graph queries for faster
 
 Replaces manual doc-to-code correlation. Fall back to file-based commands if no graph is available.
 
+### 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
+  - Read `pipeline.driftFindings` to know which fixes to apply (pre-classified by safety)
+  - If `pipeline.fixBatch` is set, apply only those specific fixes rather than running full detection
+  - Write applied fixes as `DocFix[]` back to `pipeline.fixesApplied`
+  - This enables the convergence loop to track fix verification status
+- 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.
+
 ### Phase 2: Map — Connect Code Changes to Documentation
 
 For each changed file, identify all documentation that references it:

package/dist/agents/skills/claude-code/cleanup-dead-code/SKILL.md

@@ -43,7 +43,9 @@ Graph reachability reduces false positives compared to static analysis alone, si
 
 - Exports that are not imported anywhere AND not referenced in any config file
 - Files that are not imported anywhere AND have no side effects (no top-level execution)
-- Commented-out code blocks (dead by definition)
+- Dead exports (non-public, zero importers) -- remove `export` keyword or delete entirely if zero internal callers
+- Commented-out code blocks -- delete commented block (dead by definition, code is in git history)
+- Orphaned npm dependencies -- remove from package.json (probably safe; needs install+test verification)
 - Unused local variables and imports within a file (linter can catch these)
 
 **Needs human review before removal:**
@@ -70,6 +72,28 @@ For each item categorized as safe:
 
 5. **Commit the cleanup.** Group related removals into logical commits (e.g., "remove unused shipping utilities" not "delete dead code").
 
+**New fix types:**
+
+- **Dead exports (non-public):** Use `apply_fixes` with `fixTypes: ['dead-exports']`. The tool removes the `export` keyword. If the function/class has zero internal callers too, delete the entire declaration.
+- **Commented-out code:** Use `apply_fixes` with `fixTypes: ['commented-code']`. The tool deletes commented-out code blocks. This is cosmetic and only needs lint verification.
+- **Orphaned dependencies:** Use `apply_fixes` with `fixTypes: ['orphaned-deps']`. The tool removes the dep from package.json. **Must run `pnpm install && pnpm test` after** to verify nothing breaks.
+
+### Phase 3.5: Convergence Loop (Standalone)
+
+When running standalone (not through the orchestrator), apply a single-concern convergence loop:
+
+1. **Re-run detection.** After applying all safe fixes, run `harness cleanup --type dead-code` again.
+2. **Check if issue count decreased.** Compare the new count to the previous count.
+3. **If decreased: loop.** New dead code may have been exposed by the fixes (e.g., removing a dead export made a file fully unused). Go back to Phase 2 (Categorize) with the new report.
+4. **If unchanged: stop.** No more cascading fixes are possible. Proceed to Phase 4 (Report).
+5. **Maximum iterations: 5.** To prevent infinite loops, stop after 5 convergence cycles regardless.
+
+**Why convergence matters:** Removing dead code can create more dead code. For example:
+
+- Removing a dead export may make all remaining exports in a file dead, making the file itself dead.
+- Removing a dead file removes its imports, which may make other files' exports dead.
+- Removing an orphaned dep may cause lint warnings that reveal unused imports.
+
 ### Phase 4: Report Remaining Items
 
 ### Graph Refresh

package/dist/agents/skills/claude-code/cleanup-dead-code/skill.yaml

@@ -1,6 +1,6 @@
 name: cleanup-dead-code
-version: "1.0.0"
-description: Detect unused exports and dead code
+version: "1.1.0"
+description: Detect and auto-fix dead code including dead exports, commented-out code, and orphaned dependencies
 cognitive_mode: diagnostic-investigator
 triggers:
   - manual
@@ -18,6 +18,9 @@ cli:
     - name: path
       description: Project root path
       required: false
+    - name: fix
+      description: Enable auto-fix with convergence loop
+      required: false
 mcp:
   tool: run_skill
   input:

package/dist/agents/skills/claude-code/detect-doc-drift/SKILL.md

@@ -30,6 +30,18 @@ When a knowledge graph exists at `.harness/graph/`, use graph queries for faster
 
 When a graph is available, drift is simply stale edges: doc-to-code edges where the code side has been modified more recently than the doc side. This replaces regex pattern matching and catches semantic drift that text search misses. Fall back to file-based commands if no graph is available.
 
+### 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
+  - Use `pipeline.exclusions` to skip findings that were already addressed in a previous phase
+  - Write `DriftFinding[]` results back to `pipeline.driftFindings` in handoff.json
+  - This enables the orchestrator to track findings across phases and avoid double-counting
+- 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.
+
 ### Phase 2: Identify — Classify Drift Types
 
 Categorize each finding into one of these drift types:

package/dist/agents/skills/claude-code/enforce-architecture/SKILL.md

@@ -75,6 +75,53 @@ For each violation, determine:
    - WHAT would happen if the violation were allowed to persist
    - HOW it affects testability, maintainability, and changeability
 
+### Phase 3.5: Apply Safe Architecture Fixes
+
+Some architecture violations can be auto-fixed. Apply these before surfacing remaining violations.
+
+**Import ordering violations:**
+
+1. Identify files where imports are not ordered according to the project's layer convention.
+2. Reorder imports: external packages first, then by layer (lowest to highest), then relative imports.
+3. Verify with lint + typecheck. This is a safe, mechanical fix.
+
+**Forbidden import replacement (with configured alternative):**
+
+1. Check `harness.config.json` for `forbiddenImports` entries that include an `alternative` field.
+2. For each violation where an alternative exists, replace the import path with the alternative.
+3. Verify with typecheck + test. This is "probably safe" -- present as a diff for approval in interactive mode, apply silently in CI mode.
+
+**Design token substitution (unambiguous mapping):**
+
+1. When a hardcoded value has exactly one matching design token, replace the literal with the token reference.
+2. Verify with typecheck + test.
+3. If the mapping is ambiguous (multiple candidate tokens), surface to user.
+
+**Never auto-fix these (always surface to user):**
+
+- Upward dependencies
+- Skip-layer dependencies
+- Circular dependencies
+- Forbidden imports without a configured alternative
+
+### Phase 3.6: Convergence Loop (Standalone)
+
+When running standalone (not through the orchestrator), apply a single-concern convergence loop:
+
+1. **Re-run detection.** After applying all safe/probably-safe fixes, run `harness check-deps` again.
+2. **Check if violation count decreased.** Compare the new count to the previous count.
+3. **If decreased: loop.** Fixing one violation can resolve others (e.g., replacing a forbidden import may eliminate a transitive skip-layer violation). Go back to Phase 2 with the new results.
+4. **If unchanged: stop.** Proceed to Phase 4 (Guide Resolution) for remaining violations.
+5. **Maximum iterations: 5.** To prevent infinite loops.
+
+**Verification gate:** After each fix batch, run:
+
+```
+pnpm lint && pnpm tsc --noEmit && pnpm test
+```
+
+If any command fails, revert the batch and reclassify those findings as unsafe.
+
 ### Phase 4: Guide Resolution
 
 For each violation, provide a specific fix:
@@ -82,7 +129,7 @@ For each violation, provide a specific fix:
 - **Upward dependency:** Introduce an interface or abstraction in the lower layer. The higher layer implements it; the lower layer depends only on the abstraction. Alternatively, use dependency injection.
 - **Skip-layer dependency:** Route the call through the intermediate layer. Add a method to the Service layer that delegates to the Repository, then have the UI call the Service.
 - **Circular dependency:** Break the cycle by extracting shared types into a common module that both can depend on, or restructure so the dependency flows in one direction only.
-- **Forbidden import:** Replace the forbidden import with the approved alternative. If no alternative exists, the feature may need to live in a different layer.
+- **Forbidden import:** Check `harness.config.json` for an `alternative` field. If present, this should have been auto-fixed in Phase 3.5. If not present, replace the forbidden import with the approved alternative or restructure the code.
 - **Design constraint violation:** Replace hardcoded values with token references from `design-system/tokens.json`. For anti-pattern violations, consult `design-system/DESIGN.md` for the project's aesthetic intent and approved alternatives. For contrast failures, use `harness-accessibility` to find compliant color pairs.
 
 ## Common Violation Patterns

package/dist/agents/skills/claude-code/enforce-architecture/skill.yaml

@@ -1,6 +1,6 @@
 name: enforce-architecture
-version: "1.0.0"
-description: Validate architectural layer boundaries and detect circular dependencies
+version: "1.1.0"
+description: Validate architectural layer boundaries, detect violations, and auto-fix import ordering and forbidden import replacement
 cognitive_mode: meticulous-verifier
 triggers:
   - manual
@@ -19,6 +19,9 @@ cli:
     - name: path
       description: Project root path
       required: false
+    - name: fix
+      description: Enable auto-fix with convergence loop
+      required: false
 mcp:
   tool: run_skill
   input:

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

@@ -25,6 +25,12 @@
    - `standard` -- warnings are visible, errors block (default behavior)
    - `permissive` -- all findings are informational (nothing blocks, but everything is reported)
 
+2.5. **Check for i18n skill overlap.** Read `harness.config.json` for `i18n.enabled`:
+
+- If `i18n.enabled: true`, **defer** `lang` and `dir` attribute checks to `harness-i18n`. Do not scan for missing `lang` on `<html>` or missing `dir` on user-content containers -- those checks are covered by the i18n skill's scan phase with more context (locale-aware, RTL-aware).
+- If `i18n.enabled` is false or absent, scan for `lang`/`dir` as normal (these remain part of the accessibility audit).
+- This deduplication prevents the same finding from appearing in both the accessibility report and the i18n report.
+
 3. **Scan component files.** Search all files matching `.tsx`, `.jsx`, `.vue`, `.svelte`, `.html` for the following violations:
 
    **Images and media:**
@@ -176,6 +182,7 @@ This phase is optional. It applies fixes only for **mechanical issues** -- viola
 - **`DesignIngestor`** (`packages/graph/src/ingest/DesignIngestor.ts`) -- Provides token data used for contrast checking. The ingestor parses `tokens.json` so the accessibility scanner can compare code colors against declared tokens.
 - **`harness-impact-analysis`** -- When tokens change (palette update, new colors), impact analysis traces affected components. The accessibility skill uses this to determine which components need re-scanning.
 - **`harness-design-system`** -- Dependency. When contrast failures originate from token definitions (not component code), escalate to harness-design-system to fix at the source.
+- **`harness-i18n` deduplication** -- When `i18n.enabled: true` in config, `lang` and `dir` attribute checks are deferred to the i18n skill. This prevents duplicate findings across the accessibility and i18n reports. When i18n is not enabled, these checks remain part of the accessibility scan.
 
 ## Success Criteria
 

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

@@ -97,7 +97,14 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 5. **Load context.** Read `.harness/learnings.md` and `.harness/failures.md` (global, at `.harness/` root) if they exist. Note any relevant learnings or known dead ends for the current phase.
 
-6. **Transition to ASSESS.**
+6. **Load roadmap context.** If `docs/roadmap.md` exists, read it to understand:
+   - Current project priorities (which features are `in-progress`)
+   - Blockers that may affect the upcoming phases
+   - Overall project status and milestone progress
+
+   This provides the autopilot with project-level context beyond the individual spec being executed. If the roadmap does not exist, skip this step — the autopilot operates normally without it.
+
+7. **Transition to ASSESS.**
 
 ---
 
@@ -374,6 +381,7 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 - **State file** — `.harness/sessions/<slug>/autopilot-state.json` tracks the orchestration state machine. `.harness/sessions/<slug>/state.json` tracks task-level execution state (managed by harness-execution). The slug is derived from the spec path during INIT.
 - **Handoff** — `.harness/sessions/<slug>/handoff.json` is written by each delegated skill and read by the next. Autopilot writes a final handoff on DONE.
 - **Learnings** — `.harness/learnings.md` (global) is appended by both delegated skills and autopilot itself.
+- **Roadmap context** — During INIT, reads `docs/roadmap.md` (if present) for project-level priorities, blockers, and milestone status. Provides broader context for phase execution decisions.
 
 ## Success Criteria
 

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

@@ -38,6 +38,21 @@ If you find yourself writing production code, tests, or scaffolding before the h
 
 1. **Ask ONE question at a time.** Do not dump a list of 10 questions on the human. Ask the most important question first. Wait for the answer. Let the answer inform the next question.
 
+   When asking a clarifying question, use `emit_interaction` with `type: 'question'`:
+
+   ```json
+   emit_interaction({
+     path: "<project-root>",
+     type: "question",
+     question: {
+       text: "For auth, should we use:",
+       options: ["A) existing JWT middleware", "B) OAuth2 via provider X", "C) external service"]
+     }
+   })
+   ```
+
+   This records the question in state and returns a formatted prompt to present.
+
 2. **Prefer multiple choice.** Instead of "How should we handle auth?", ask "For auth, should we: (A) use existing JWT middleware, (B) add OAuth2 via provider X, or (C) delegate to an external service?" Give 2-4 concrete options with brief tradeoff notes.
 
 3. **When the human answers, acknowledge and build on it.** Do not re-ask clarified points. Track decisions as they accumulate.
@@ -67,6 +82,13 @@ These keywords flow into the `handoff.json` `contextKeywords` field when the spe
    - **Estimated complexity:** Low / Medium / High, with a brief justification
    - **Risk:** What could go wrong, what assumptions might be wrong
 
+   When presenting approach tradeoffs, use conventional markdown patterns:
+
+   ```
+   **[IMPORTANT]** Approach 1 trades simplicity for extensibility
+   **[SUGGESTION]** Consider Approach 2 if real-time requirements emerge later
+   ```
+
 2. **Be honest about tradeoffs.** Do not soft-sell a preferred approach. If approach A is simpler but less extensible, say so plainly.
 
 3. **State your recommendation** and why, but defer to the human's decision.
@@ -84,13 +106,62 @@ These keywords flow into the `handoff.json` `contextKeywords` field when the spe
    - Success criteria (observable, testable outcomes)
    - Implementation order (high-level phases, not detailed tasks — that is harness-planning's job)
 
-2. **After all sections are reviewed, write the spec to `docs/`.** Use the project's existing spec naming convention. If none exists, use `docs/specs/YYYY-MM-DD-<feature-name>.md`.
+2. **Run soundness review.** After all sections are reviewed and the spec is drafted, invoke `harness-soundness-review --mode spec` against the draft. Do not proceed to write the spec to `docs/` until the soundness review converges with no remaining issues.
 
-   When the project has `docs/specs/`, write proposals to `docs/changes/<feature>/proposal.md` instead. This keeps change proposals separate from established specs. Fall back to the existing behavior (`docs/specs/`) when no `docs/specs/` directory exists yet.
+3. **Write the spec to `docs/`.** Use the project's existing spec naming convention. If none exists, use `docs/specs/YYYY-MM-DD-<feature-name>.md`.
 
-3. **Run `harness validate`** to verify the spec file is properly placed and the project remains healthy.
+   When the project has `docs/specs/`, write proposals to `docs/changes/<feature>/proposal.md` instead. This keeps change proposals separate from established specs. Fall back to the existing behavior (`docs/specs/`) when no `docs/specs/` directory exists yet.
 
-4. **Ask for final sign-off.** Present the complete spec file path and a one-paragraph summary. The human must explicitly approve before this skill is complete.
+4. **Run `harness validate`** to verify the spec file is properly placed and the project remains healthy.
+
+5. **Request sign-off via `emit_interaction`:**
+
+   ```json
+   emit_interaction({
+     path: "<project-root>",
+     type: "confirmation",
+     confirmation: {
+       text: "Approve spec at <file-path>?",
+       context: "<one-paragraph summary of the design>"
+     }
+   })
+   ```
+
+   The human must explicitly approve before this skill is complete.
+
+6. **Write handoff and suggest transition.** After the human approves the spec:
+
+   Write `.harness/handoff.json`:
+
+   ```json
+   {
+     "fromSkill": "harness-brainstorming",
+     "phase": "VALIDATE",
+     "summary": "<1-sentence spec summary>",
+     "artifacts": ["<spec file path>"],
+     "decisions": [{ "what": "<decision>", "why": "<rationale>" }],
+     "contextKeywords": ["<domain keywords from Phase 2>"]
+   }
+   ```
+
+   Call `emit_interaction`:
+
+   ```json
+   {
+     "type": "transition",
+     "transition": {
+       "completedPhase": "brainstorming",
+       "suggestedNext": "planning",
+       "reason": "Spec approved and written to docs/",
+       "artifacts": ["<spec file path>"],
+       "requiresConfirmation": true,
+       "summary": "<Spec title> -- <key design choices>. <N> success criteria, <N> implementation phases."
+     }
+   }
+   ```
+
+   If the user confirms: invoke harness-planning with the spec path.
+   If the user declines: stop. The handoff is written for future invocation.
 
 ---
 
@@ -147,6 +218,7 @@ Converge on a recommendation that addresses all concerns before presenting the d
 - **`harness check-docs`** — Run to verify the spec does not conflict with existing documentation.
 - **Spec location** — Specs go to `docs/` (or `docs/specs/` if the project uses that convention). Follow existing naming patterns.
 - **Handoff to harness-planning** — Once the spec is approved, invoke harness-planning to create the implementation plan from the spec.
+- **`emit_interaction`** -- Call at the end of Phase 4 to suggest transitioning to harness-planning. Uses confirmed transition (waits for user approval).
 
 #### Requirement Phrasing
 

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

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