npm - @harness-engineering/cli - Versions diffs - 1.25.7 → 1.26.1 - Mend

@harness-engineering/cli 1.25.7 → 1.26.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (189) hide show

package/dist/agents/commands/cursor/harness/harness-onboarding.mdc DELETED Viewed

@@ -1,296 +0,0 @@
----
-description: Onboard a new developer to a harness-managed project
-alwaysApply: false
----
-<!-- Generated by harness generate-slash-commands. Do not edit. -->
-# Harness Onboarding
-> Navigate an existing harness-managed project and generate a structured orientation for new team members. Map the codebase, understand constraints, identify the adoption level, and produce a summary that gets someone productive fast.
-## When to Use
-- A new developer (human or agent) is joining a harness-managed project for the first time
-- Resuming work on a project after extended time away and needing to re-orient
-- When `on_project_init` triggers fire in an existing project (agent starting a new session)
-- When someone asks "how does this project work?" or "where do I start?"
-- NOT when initializing a new project (use initialize-harness-project)
-- NOT when the project has no harness configuration (onboard to harness first with initialize-harness-project)
-- NOT when deep-diving into a specific module (use standard code exploration — onboarding gives the big picture)
-## Process
-### Phase 1: READ — Load Project Configuration
-1. **Read `AGENTS.md`.** This is the primary source of truth for agent behavior in the project. Note:
-   - Project description and purpose
-   - Architecture overview
-   - Conventions and coding standards
-   - Constraints and forbidden patterns
-   - Any special instructions or warnings
-2. **Read `harness.config.json`.** Extract:
-   - Project name and stack
-   - Adoption level (basic, intermediate, advanced)
-   - Layer definitions and their directory mappings
-   - Dependency constraints between layers
-   - Registered skills and their triggers
-   - Persona configuration (if present)
-3. **Read `.harness/learnings.md`** if it exists. This contains hard-won insights from previous sessions — decisions made, gotchas discovered, patterns that worked or failed. Summarize the most recent and most important entries.
-4. **Read `.harness/state.json`** if it exists. This reveals what was happening in the last session — current phase, active task, any blockers that were recorded.
-### Phase 2: MAP — Understand the Codebase Structure
-1. **Map the technology stack.** Identify from package files, configuration, and code:
-   - Language(s) and version(s)
-   - Framework(s) and major libraries
-   - Test framework and test runner command
-   - Build tool and build command
-   - Package manager
-   - Database or data stores (if applicable)
-2. **Map the architecture.** Walk the directory structure and identify:
-   - Top-level organization pattern (monorepo, single package, workspace)
-   - Source code location and entry points
-   - Layer boundaries (from `harness.config.json` and actual directory structure)
-   - Shared utilities or common modules
-   - Configuration files and their purposes
-3. **Map the conventions.** Look for patterns in existing code:
-   - File naming conventions (kebab-case, camelCase, PascalCase)
-   - Test file location and naming (co-located, separate directory, `.test.ts` vs `.spec.ts`)
-   - Import style (relative, aliases, barrel files)
-   - Error handling patterns
-   - Logging patterns
-   - Code formatting (detect from config files: `.prettierrc`, `.eslintrc`, `biome.json`)
-4. **Map the constraints.** Identify what is restricted:
-   - Forbidden imports (from `harness.config.json` dependency constraints)
-   - Layer boundary rules (which layers can import from which)
-   - Linting rules that encode architectural decisions
-   - Any constraints documented in `AGENTS.md` that are not yet automated
-5. **Map the design system** (when present). Look for:
-   - `design-system/tokens.json` — W3C DTCG design tokens (colors, typography, spacing)
-   - `design-system/DESIGN.md` — Aesthetic intent, anti-patterns, platform notes
-   - `harness.config.json` `design` block — strictness level, enabled platforms, token path
-   - Active design skills — check if `harness-design-system`, `harness-accessibility`, `harness-design`, `harness-design-web`, `harness-design-mobile` are available
-   - Design constraint violations — run a quick `harness-accessibility` scan to surface any existing issues
-   - Token coverage — how many components reference tokens vs. hardcoded values
-   If no design system exists, note this as a potential improvement area.
-6. **Map the concerns.** Identify areas that need attention:
-   - Are there TODOs or FIXMEs in the code?
-   - Does `harness validate` pass cleanly, or are there warnings?
-   - Are there known blockers in `.harness/state.json`?
-   - Is documentation up to date with the code?
-   - Are there tests? What is the approximate coverage?
-### Graph-Enhanced Context (when available)
-When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate codebase mapping:
-- `query_graph` — map architecture automatically from module and layer nodes, replacing manual directory walking
-- `search_similar` — find entry points and key files by querying for high-connectivity nodes
-- `get_relationships` — show layer dependencies and module structure as a traversable graph
-Graph queries produce a complete architecture map in seconds, including transitive relationships that directory inspection misses. Fall back to file-based commands if no graph is available.
-### Phase 3: ORIENT — Identify Adoption Level and Maturity
-1. **Confirm the adoption level** matches what `harness.config.json` declares:
-   - Basic: `AGENTS.md` and `harness.config.json` exist but no layers or constraints
-   - Intermediate: Layers defined, dependency constraints enforced, at least one custom skill
-   - Advanced: Personas, state management, learnings, CI integration
-2. **Assess harness health.** Run `harness validate` and note any issues. A project that declares intermediate but fails validation is not truly intermediate.
-3. **Identify available skills.** List the skills configured for the project. Note which are custom (project-specific) vs. standard (harness-provided). Each skill represents a workflow the team has formalized.
-### Phase 4: SUMMARIZE — Generate Orientation Output
-1. **Produce a structured orientation summary.** This is the deliverable. Format:
-```markdown
-# Project Orientation: <project-name>
-## Overview
-<1-2 sentence project description from AGENTS.md>
-## Stack
-- Language: <language> <version>
-- Framework: <framework>
-- Tests: <test framework> (`<test command>`)
-- Build: <build tool> (`<build command>`)
-- Package manager: <pm>
-## Architecture
-<Brief description of top-level organization>
-### Layers
-| Layer   | Directories | Can Import From   |
-| ------- | ----------- | ----------------- |
-| <layer> | <dirs>      | <allowed imports> |
-### Key Components
-- <component>: <purpose> (<location>)
-## Constraints
-- <constraint 1>
-- <constraint 2>
-## Conventions
-- <convention 1>
-- <convention 2>
-## Design System
-- **Tokens:** [present/absent] ([token count] tokens in [group count] groups)
-- **Aesthetic Intent:** [present/absent] (style: [style], strictness: [level])
-- **Platforms:** [web, mobile, or none configured]
-- **Accessibility:** [baseline scan result — e.g., "3 warnings, 0 errors"]
-- **Design Skills:** [list of available design skills]
-## Harness Status
-- Adoption level: <level>
-- Validation: <pass/fail with summary>
-- Available skills: <list>
-- State: <current phase/task if applicable>
-## Recent Learnings
-- <most relevant learnings from .harness/learnings.md>
-## Getting Started
-1. <first thing to do>
-2. <second thing to do>
-3. <third thing to do>
-```
-2. **Tailor "Getting Started" to the audience.** For a new developer: how to set up the dev environment and run tests. For an agent resuming work: what the current task is and what to do next. For a reviewer: where to look and what constraints to check.
-3. **Present the summary to the human.** Do not write it to a file unless asked. The orientation is a conversation artifact, not a project artifact.
-## Harness Integration
-- **`harness validate`** — Run during onboarding to assess project health and identify any configuration issues.
-- **`harness skill list`** — List available skills to understand what workflows the team has formalized.
-- **`harness check-deps`** — Run to verify dependency constraints are passing, which confirms layer boundaries are respected.
-- **`harness state show`** — View current state to understand where the last session left off.
-- **`AGENTS.md`** — Primary source of project context and agent instructions.
-- **`harness.config.json`** — Source of structural configuration (layers, constraints, skills).
-- **`.harness/learnings.md`** — Historical context and institutional knowledge.
-## Success Criteria
-- All four configuration sources were read (`AGENTS.md`, `harness.config.json`, `.harness/learnings.md`, `.harness/state.json`)
-- Technology stack is accurately identified (language, framework, test runner, build tool)
-- Architecture is mapped with correct layer boundaries and dependency directions
-- Conventions are identified from actual code patterns, not assumed
-- Constraints are enumerated from both `harness.config.json` and `AGENTS.md`
-- Adoption level is confirmed (not just declared — validated)
-- A structured orientation summary is produced with all sections filled
-- The "Getting Started" section is actionable and tailored to the audience
-- `harness validate` was run and results are reported
-## Examples
-### Example: Onboarding to an Intermediate TypeScript Project
-**READ:**
-```
-Read AGENTS.md:
-  - Project: Widget API — REST service for widget lifecycle management
-  - Stack: TypeScript, Express, Vitest, PostgreSQL
-  - Conventions: zod validation, repository pattern, kebab-case files
-Read harness.config.json:
-  - Level: intermediate
-  - Layers: presentation (src/routes/), business (src/services/), data (src/repositories/)
-  - Constraints: presentation → business OK, business → data OK, data → presentation FORBIDDEN
-Read .harness/learnings.md:
-  - "Date comparison needs UTC normalization — use Date.now()"
-  - "The notifications table has a unique constraint on (userId, type) — upsert, don't insert"
-Read .harness/state.json:
-  - Position: Phase execute, Task 4 of 6
-  - Blocker: none
-```
-**MAP:**
-```
-Stack: TypeScript 5.3, Express 4, Vitest 1.2, pg (node-postgres)
-Architecture: Single package, 3 layers, entry point src/index.ts
-Conventions: kebab-case files, co-located tests (.test.ts), barrel exports
-Constraints: 3 layers with strict downward-only imports
-Concerns: harness validate passes, 47 tests all passing
-```
-**ORIENT:**
-```
-Adoption level: intermediate (confirmed — layers defined, constraints enforced)
-Skills: harness-tdd, harness-execution, harness-code-review
-State: Mid-execution on a 6-task notification feature plan
-```
-**SUMMARIZE:**
-```
-Produce orientation with all sections. Getting Started for this context:
-1. Read the plan at docs/plans/2026-03-14-notifications-plan.md
-2. Resume execution at Task 4 (state shows Tasks 1-3 complete)
-3. Note the UTC normalization gotcha from learnings before working with dates
-```
-### Example: Onboarding to a Basic Project
-**READ:**
-```
-Read AGENTS.md — exists, minimal content
-Read harness.config.json — level: basic, no layers defined
-No .harness/learnings.md
-No .harness/state.json
-```
-**MAP and SUMMARIZE:**
-```
-Adoption level: basic (confirmed — no layers or constraints)
-Getting Started:
-1. Run npm install && npm test to verify the project builds and tests pass
-2. Read AGENTS.md for project context and conventions
-3. Consider migrating to intermediate level to add layer boundaries
-   (use initialize-harness-project to upgrade)
-```
-## Adoption Maturity
-A mental model for where a team sits on the harness adoption curve. Not prescriptive — just orientation.
-| Level | Name               | Description                                                                                                                                                          |
-| ----- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 1     | **Manual**         | Write `CLAUDE.md` by hand, run commands manually. Harness is a reference, not a tool.                                                                                |
-| 2     | **Repeatable**     | Skills installed, agent follows conventions consistently. Workflows are codified but enforcement is human-driven.                                                    |
-| 3     | **Automated**      | Mechanical gates in CI. `harness validate` runs on PRs. Failures auto-log to `.harness/failures.md`. The system catches mistakes before humans do.                   |
-| 4     | **Self-improving** | Learnings accumulate in `.harness/learnings.md`. Agents reference past failures before planning. Institutional knowledge compounds across sessions and team members. |
-Most teams start at Level 1 and move up as they see the value. There is no pressure to reach Level 4 — each level delivers real benefits on its own.

package/dist/agents/commands/cursor/harness/harness-perf.mdc DELETED Viewed

@@ -1,268 +0,0 @@
----
-description: Performance enforcement and benchmark management
-alwaysApply: false
----
-<!-- Generated by harness generate-slash-commands. Do not edit. -->
-# Harness Perf
-> Performance enforcement and benchmark management. Tier-based gates block commits and merges based on complexity, coupling, and runtime regression severity.
-## When to Use
-- After code changes to verify performance hasn't degraded
-- On PRs to enforce performance budgets
-- For periodic performance audits
-- NOT for initial development (use harness-tdd for that)
-- NOT for brainstorming performance improvements (use harness-brainstorming)
-## Process
-### Iron Law
-**No merge with Tier 1 performance violations. No commit with cyclomatic complexity exceeding the error threshold.**
-Tier 1 violations are non-negotiable blockers. If a Tier 1 violation is detected, execution halts and the violation must be resolved before any further progress. Do not attempt workarounds.
----
-### Phase 1: ANALYZE — Structural and Coupling Checks
-1. **Run structural checks.** Execute `harness check-perf --structural` to compute complexity metrics for all changed files:
-   - Cyclomatic complexity per function
-   - Nesting depth per function
-   - File length (lines of code)
-   - Parameter count per function
-2. **Run coupling checks.** Execute `harness check-perf --coupling` to compute coupling metrics:
-   - Fan-in and fan-out per module
-   - Afferent and efferent coupling
-   - Transitive dependency depth
-   - Circular dependency detection
-3. **Classify violations by tier:**
-   - **Tier 1 (error, block commit):** Cyclomatic complexity > 15, circular dependencies, hotspot in top 5%
-   - **Tier 2 (warning, block merge):** Complexity > 10, nesting > 4, fan-out > 10, size budget exceeded
-   - **Tier 3 (info, no gate):** File length > 300, fan-in > 20, transitive depth > 30
-4. **If Tier 1 violations found,** report them immediately and STOP. Do not proceed to benchmarks. The violations must be fixed first.
-5. **If no violations found,** proceed to Phase 2.
----
-### 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 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.
-3. **Verify clean working tree.** Run `git status --porcelain`. If there are uncommitted changes, STOP. Benchmarks on dirty trees produce unreliable results.
-4. **Run benchmarks.** Execute `harness perf bench` to run all benchmark suites.
-5. **Load baselines.** Read `.harness/perf/baselines.json` for previous benchmark results. If no baselines exist, treat this as a baseline-capture run.
-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
-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
-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)
-9. **If this is a baseline-capture run,** report results without regression comparison. Recommend running `harness perf baselines update` to persist.
----
-### Phase 3: REPORT — Generate Performance Report
-1. **Format violations by tier.** Present Tier 1 violations first (most severe), then Tier 2, then Tier 3. Each violation entry includes:
-   - File path and function name
-   - Metric name and current value
-   - Threshold that was exceeded
-   - Tier classification and gate impact
-2. **Show hotspot scores** for top functions if knowledge graph data is available:
-   - Query the graph for functions with high churn + high fan-in
-   - Rank by composite hotspot score
-   - Flag any hotspots that also have performance violations
-3. **Show benchmark regression summary** if benchmarks ran:
-   - Table of benchmark name, baseline, current, delta percentage, tier
-   - Highlight critical-path benchmarks with a marker
-   - Show noise margin and whether the regression exceeds it
-4. **Recommend specific actions** for each Tier 1 and Tier 2 violation:
-   - For high complexity: suggest extract-method or strategy pattern refactoring
-   - For high coupling: suggest interface extraction or dependency inversion
-   - For benchmark regressions: suggest profiling the specific code path
-   - For size budget violations: suggest module decomposition
-5. **Output the report** in structured markdown format suitable for PR comments or CI output.
----
-### Phase 4: ENFORCE — Apply Gate Decisions
-1. **Tier 1 violations present** — FAIL. Block commit and merge. List all Tier 1 violations with their locations and values. The developer must fix these before proceeding.
-2. **Tier 2 violations present, no Tier 1** — WARN. Allow commit but block merge until addressed. List all Tier 2 violations. These must be resolved before the PR can be merged.
-3. **Only Tier 3 or no violations** — PASS. Proceed normally. Log Tier 3 violations as informational notes.
-4. **Record gate decision** in `.harness/state.json` under a `perfGate` key:
-   ```json
-   {
-     "perfGate": {
-       "result": "pass|warn|fail",
-       "tier1Count": 0,
-       "tier2Count": 0,
-       "tier3Count": 0,
-       "timestamp": "ISO-8601"
-     }
-   }
-   ```
-5. **Exit with appropriate code:** 0 for pass, 1 for fail, 0 for warn (with warning output).
----
-## Harness Integration
-- **`harness check-perf`** — Primary command for all performance checks. Runs structural and coupling analysis.
-- **`harness check-perf --structural`** — Run only structural complexity checks.
-- **`harness check-perf --coupling`** — Run only coupling analysis.
-- **`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.
-## Tier Classification
-| Tier | Severity | Gate         | Examples                                                                                            |
-| ---- | -------- | ------------ | --------------------------------------------------------------------------------------------------- |
-| 1    | error    | Block commit | Cyclomatic complexity > 15, >5% regression on critical path, hotspot in top 5%, circular dependency |
-| 2    | warning  | Block merge  | Complexity > 10, nesting > 4, >10% regression elsewhere, fan-out > 10, size budget exceeded         |
-| 3    | info     | None         | File length > 300 lines, fan-in > 20, transitive depth > 30, >5% non-critical regression            |
-## Success Criteria
-- All Tier 1 violations are resolved before proceeding
-- Performance report follows structured format with tier classification
-- Benchmark regressions are compared against noise margin before flagging
-- Gate decision is recorded in state
-- `harness validate` passes after enforcement
-## Examples
-### Example: PR with High Complexity Function
-```
-Phase 1: ANALYZE
-  harness check-perf --structural
-  Result: processOrderBatch() in src/orders/processor.ts has cyclomatic complexity 18 (Tier 1, threshold: 15)
-Phase 2: BENCHMARK — skipped (Tier 1 violation found)
-Phase 3: REPORT
-  TIER 1 VIOLATIONS (1):
-    - src/orders/processor.ts:processOrderBatch — complexity 18 > 15
-      Recommendation: Extract validation and transformation into separate functions
-Phase 4: ENFORCE
-  Result: FAIL — 1 Tier 1 violation. Commit blocked.
-```
-### Example: Benchmark Regression on Critical Path
-```
-Phase 1: ANALYZE — no structural violations
-Phase 2: BENCHMARK
-  harness perf bench
-  Baseline: parseDocument 4.2ms, current: 4.8ms (+14.3%)
-  parseDocument is @perf-critical — Tier 1 threshold applies (>5%)
-Phase 3: REPORT
-  TIER 1 VIOLATIONS (1):
-    - parseDocument: 14.3% regression on critical path (threshold: 5%)
-      Recommendation: Profile parseDocument to identify the regression source
-Phase 4: ENFORCE
-  Result: FAIL — 1 Tier 1 violation. Merge blocked.
-```
-### Example: Clean PR with Minor Warnings
-```
-Phase 1: ANALYZE
-  harness check-perf --structural --coupling
-  Result: src/utils/formatter.ts has 320 lines (Tier 3, threshold: 300)
-Phase 2: BENCHMARK
-  harness perf bench — all within noise margin
-Phase 3: REPORT
-  TIER 3 INFO (1):
-    - src/utils/formatter.ts: 320 lines > 300 line threshold
-  No Tier 1 or Tier 2 violations.
-Phase 4: ENFORCE
-  Result: PASS — no blocking violations.
-```
-## Gates
-- **No ignoring Tier 1 violations.** They must be fixed or the threshold must be reconfigured (with documented justification).
-- **No running benchmarks with dirty working tree.** Uncommitted changes invalidate benchmark results.
-- **No updating baselines without running benchmarks.** Baselines must come from fresh runs against committed code.
-- **No suppressing violations without documentation.** If a threshold is relaxed, the rationale must be documented in the project configuration.
-## Escalation
-- **When Tier 1 violations cannot be fixed within the current task:** Propose refactoring the function into smaller units, or raising the threshold with a documented justification. Do not silently skip the violation.
-- **When benchmark results are noisy or inconsistent:** Increase warmup iterations, pin the runtime environment, or run benchmarks in isolation. Report the noise level so the developer can make an informed decision.
-- **When critical path detection seems wrong:** Check `@perf-critical` annotations in source files and verify graph fan-in thresholds. The critical path set can be overridden in `.harness/perf/critical-paths.json`.
-- **When a violation is a false positive:** Document it with a `// perf-ignore: <reason>` comment and add the exception to `.harness/perf/exceptions.json`.