@harness-engineering/cli 1.14.0 → 1.16.0

package/dist/agents/skills/cursor/harness-state-management/SKILL.md

@@ -0,0 +1,309 @@
+# Harness State Management
+
+> Manage persistent state across agent sessions so that context, decisions, progress, and learnings survive context resets. Load state at session start, track position and decisions throughout, and save state for the next session.
+
+## When to Use
+
+- At the start of every session that continues previous work (load state)
+- When completing a task, phase, or milestone (update progress)
+- When making a decision that future sessions need to know about (record decision)
+- When discovering something non-obvious that would be lost on context reset (capture learning)
+- When hitting a blocker that cannot be resolved in the current session (log blocker)
+- At the end of every session (save state)
+- NOT for storing code — code belongs in git commits, not state files
+- NOT for storing large outputs or logs — state should be concise and navigable
+- NOT as a replacement for a plan document — plans live in `docs/`, state tracks progress through plans
+
+## Process
+
+### Phase 1: LOAD — Restore Context from Previous Sessions
+
+0. **Resolve the stream.** State is organized into streams — isolated directories under `.harness/streams/<name>/`. Before loading any state files:
+   - If you know which work item you're resuming, pass `--stream <name>` or use `manage_state` with `stream: "<name>"`.
+   - Otherwise, the system auto-resolves from the current git branch (e.g., `feature/auth-rework` → `auth-rework` stream) or falls back to the active stream.
+   - If resolution fails, ask the user: "Which stream should I use?" and list known streams via `harness state streams list` or the `list_streams` MCP tool.
+   - When starting new work on a new branch, create a new stream: `harness state streams create <name> --branch <branch>`.
+   - Announce which stream was resolved so the human has visibility.
+
+1. **Read `.harness/state.json`.** This is the primary state file. It contains:
+   - Current position (phase, task, step)
+   - Progress map (which tasks are complete, in progress, or blocked)
+   - Decisions made in previous sessions (date, what, why)
+   - Blockers encountered and their status
+   - Last session summary
+
+2. **Run `harness state show`** to get a formatted view of current state. This is equivalent to reading the JSON but formatted for readability.
+
+3. **Read `.harness/learnings.md`.** This is the append-only knowledge base. Scan for:
+   - Recent learnings (last 2-3 sessions) — these are most likely still relevant
+   - Gotchas and warnings — these prevent repeating mistakes
+   - Decisions with rationale — these explain why things are the way they are
+
+4. **Read `.harness/failures.md` if exists.** Scan for active anti-patterns and dead ends.
+
+5. **Read `.harness/handoff.json` if exists.** Structured context from last skill.
+
+6. **Check `.harness/archive/` for historical failure logs.**
+
+7. **If no state exists,** this is a fresh start. Create `.harness/state.json` with initial structure:
+
+   ```json
+   {
+     "schemaVersion": 1,
+     "position": { "phase": "start", "task": null },
+     "progress": {},
+     "decisions": [],
+     "blockers": [],
+     "lastSession": { "date": null, "summary": null }
+   }
+   ```
+
+8. **Announce the loaded context.** Briefly summarize: "Resuming from [position]. [N] tasks complete. [N] blockers. Key learnings: [summary]." This confirms the state was loaded and gives the human visibility.
+
+### Phase 2: TRACK — Maintain State During the Session
+
+1. **Update position when moving between phases or tasks.** Every time work shifts to a new task or phase, update `position` in state:
+
+   ```json
+   "position": { "phase": "execute", "task": "Task 3", "step": "writing tests" }
+   ```
+
+2. **Record decisions when they are made.** Decisions are choices that affect future work. Record them immediately — do not wait until the end of the session:
+
+   ```json
+   "decisions": [
+     {
+       "date": "2026-03-14",
+       "what": "Use WebSocket instead of SSE for real-time notifications",
+       "why": "SSE does not support bidirectional communication, which Task 5 requires"
+     }
+   ]
+   ```
+
+3. **Log blockers when encountered.** A blocker is anything that prevents the current task from completing:
+
+   ```json
+   "blockers": [
+     {
+       "date": "2026-03-14",
+       "task": "Task 4",
+       "description": "Payment gateway API returns 403 — API key may be expired",
+       "status": "open"
+     }
+   ]
+   ```
+
+4. **Update progress after each completed task:**
+
+   ```json
+   "progress": {
+     "Task 1": "complete",
+     "Task 2": "complete",
+     "Task 3": "in_progress",
+     "Task 4": "blocked"
+   }
+   ```
+
+5. **Keep state concise.** State is not a log. Each field should contain the current status, not a history of all changes. History belongs in `.harness/learnings.md` and git commits.
+
+### Phase 3: LEARN — Capture Knowledge for Future Sessions
+
+1. **Identify learnings as they happen.** A learning is anything that:
+   - Was surprising or non-obvious
+   - Took significant effort to figure out
+   - Would cause repeated wasted time if forgotten
+   - Represents a decision that needs rationale preserved
+
+2. **Capture learnings with `harness state learn`:**
+
+   ```bash
+   harness state learn "Date comparison needs UTC normalization — use Date.now() not new Date()"
+   ```
+
+   This appends to `.harness/learnings.md` with a timestamp.
+
+3. **Or append directly to `.harness/learnings.md`** with structured format:
+
+   ```markdown
+   ## 2026-03-14 — Task 3: Notification Expiry
+
+   - [learning]: PostgreSQL's `now()` returns timestamp with timezone, but our
+     application uses UTC epoch milliseconds. Always convert before comparing.
+   - [gotcha]: The notifications table has a unique constraint on (userId, type).
+     Use upsert (ON CONFLICT DO UPDATE) instead of plain INSERT.
+   - [decision]: Chose to store expiry as epoch milliseconds rather than
+     ISO timestamp for consistency with the rest of the codebase.
+   ```
+
+4. **Learnings are append-only.** Never edit or delete previous learnings. They are a chronological record. Even if a learning turns out to be wrong, append a correction rather than modifying the original.
+
+5. **What belongs in learnings vs. git commits:**
+   - **Learnings:** Context, rationale, gotchas, decisions, warnings — things that explain _why_ and _what to watch out for_
+   - **Git commits:** Code changes, what was done — things that explain _what_ changed
+   - Example: The commit says "feat: add UTC normalization to date comparison." The learning says "Date comparison needs UTC normalization because PostgreSQL returns timezone-aware timestamps but our app uses epoch milliseconds."
+
+### Phase 4: SAVE — Persist State for Next Session
+
+1. **Update `.harness/state.json`** with final position, progress, and session summary:
+
+   ```json
+   {
+     "schemaVersion": 1,
+     "position": { "phase": "execute", "task": "Task 4" },
+     "progress": {
+       "Task 1": "complete",
+       "Task 2": "complete",
+       "Task 3": "complete"
+     },
+     "decisions": [ ... ],
+     "blockers": [ ... ],
+     "lastSession": {
+       "date": "2026-03-14",
+       "summary": "Completed Tasks 2-3. Task 3 required UTC date normalization (see learnings). Starting Task 4 next session."
+     }
+   }
+   ```
+
+2. **Verify learnings were captured.** Review `.harness/learnings.md` — were all non-obvious discoveries recorded? If something was tricky during the session, it should be in learnings.
+
+3. **State is saved to the active stream.** All writes (state, learnings, handoff, failures) go to the resolved stream's directory (e.g., `.harness/streams/auth-rework/state.json`). Switching to a different stream in the next session does not affect the current stream's files.
+
+4. **Decide whether to commit state files.** State files (`.harness/streams/*/state.json`, `.harness/streams/*/learnings.md`) should be committed to git so other team members and agents can access them. Commit state updates separately from code changes so they do not clutter code diffs.
+
+### Building Institutional Knowledge Over Time
+
+The `.harness/learnings.md` file grows over the lifetime of the project. It becomes a valuable resource:
+
+- **Week 1:** A few gotchas about the development environment and initial setup decisions.
+- **Month 1:** Patterns emerge — recurring issues, architectural decisions with rationale, team conventions that were established through experience.
+- **Month 6:** New team members read learnings and avoid months of rediscovery. The file captures knowledge that no single person holds.
+- **Year 1:** Learnings are the project's institutional memory. They explain why the architecture looks the way it does, why certain patterns were adopted, and what was tried and abandoned.
+
+Treat learnings as a first-class project artifact. They are as valuable as tests and documentation.
+
+### Archival Workflow
+
+- **Archive failures:** Move `failures.md` to `.harness/archive/` at milestone boundaries.
+- **Do NOT archive learnings** — permanent. Learnings accumulate for the lifetime of the project.
+- **Do NOT archive state** — git handles history. The current `state.json` is always the source of truth.
+- **Handoff is ephemeral** — overwritten by each skill. No archival needed.
+
+## Harness Integration
+
+- **`harness state show [--stream <name>]`** — Display current state in a formatted, readable view. Use at session start to quickly orient.
+- **`harness state reset [--stream <name>]`** — Reset state to initial values. Use when starting a completely new effort and old state is no longer relevant. Use with caution — this discards progress tracking.
+- **`harness state learn "<message>" [--stream <name>]`** — Append a learning with automatic timestamp formatting.
+- **`harness state streams list`** — List all known streams with branch associations and active status.
+- **`harness state streams create <name> [--branch <branch>]`** — Create a new stream, optionally associated with a git branch.
+- **`harness state streams archive <name>`** — Archive a completed stream.
+- **`harness state streams activate <name>`** — Set the active stream for the project.
+- **`.harness/streams/<name>/state.json`** — Primary state file per stream. Read at session start, updated throughout, saved at session end.
+- **`.harness/streams/<name>/learnings.md`** — Append-only knowledge base per stream.
+- **`.harness/streams/<name>/failures.md`** — Active anti-patterns per stream.
+- **`.harness/streams/<name>/handoff.json`** — Structured context from last skill per stream.
+- **`.harness/streams/index.json`** — Stream index tracking known streams, branch associations, and active stream.
+- **`.harness/trace.md`** — Optional reasoning trace. Useful for debugging agent behavior across sessions.
+- **`.harness/archive/`** — Archived failure logs. Check for historical context when encountering recurring issues.
+
+## Success Criteria
+
+- State is loaded at the start of every session that continues previous work
+- Position is updated whenever the current phase or task changes
+- Decisions are recorded with date, what, and why — immediately when made, not deferred
+- Blockers are logged with task reference, description, and status
+- Progress is updated after each completed task
+- Learnings are captured for every non-obvious discovery during the session
+- `.harness/learnings.md` entries follow the structured format (date, task, tagged items)
+- Learnings are append-only — no edits or deletions of previous entries
+- State is saved before session end with an accurate session summary
+- State files are committed to git separately from code changes
+
+## Examples
+
+### Example: Starting a New Session (Resuming Work)
+
+**LOAD:**
+
+```
+Run: harness state show
+Output:
+  Position: execute / Task 3 (writing tests)
+  Progress: Task 1 complete, Task 2 complete
+  Blockers: none
+  Last session: 2026-03-13 — "Completed Tasks 1-2. Task 2 required
+    adding a new index on notifications.userId for query performance."
+
+Read: .harness/learnings.md
+  Most recent:
+  - [gotcha]: notifications table needs index on userId — queries
+    were timing out without it
+  - [decision]: used partial index (WHERE deleted_at IS NULL) to
+    avoid indexing soft-deleted rows
+
+Summary: "Resuming from Task 3 (writing tests). Tasks 1-2 complete.
+  Note: notifications table has a partial index on userId — see learnings."
+```
+
+### Example: Recording a Decision Mid-Session
+
+```
+Context: Implementing Task 4, need to choose between polling and WebSocket.
+
+Record decision:
+  date: "2026-03-14"
+  what: "Use WebSocket for real-time notification delivery"
+  why: "Polling would require 1-second intervals for acceptable latency,
+    which creates too much load. WebSocket gives instant delivery with
+    one persistent connection per client."
+
+Capture learning:
+  harness state learn "WebSocket chosen over polling for notifications.
+    Polling at 1s intervals = ~86k requests/day per client. WebSocket =
+    1 persistent connection. See Task 4 decision in state."
+```
+
+### Example: Ending a Session
+
+**SAVE:**
+
+```
+Update .harness/state.json:
+{
+  "schemaVersion": 1,
+  "position": { "phase": "execute", "task": "Task 5" },
+  "progress": {
+    "Task 1": "complete",
+    "Task 2": "complete",
+    "Task 3": "complete",
+    "Task 4": "complete"
+  },
+  "decisions": [
+    {
+      "date": "2026-03-14",
+      "what": "Use WebSocket for real-time notification delivery",
+      "why": "Polling creates too much load at acceptable latency intervals"
+    }
+  ],
+  "blockers": [],
+  "lastSession": {
+    "date": "2026-03-14",
+    "summary": "Completed Tasks 3-4. Task 3 added expiry logic with UTC normalization. Task 4 implemented WebSocket delivery (chose over polling — see decisions). Starting Task 5 (UI integration) next session."
+  }
+}
+
+Verify: .harness/learnings.md has entries for UTC normalization and WebSocket decision.
+Commit: git add .harness/ && git commit -m "chore: update harness state after Tasks 3-4"
+```
+
+### Example: What Belongs Where
+
+| Information                                           | Where It Goes                   | Why                                                  |
+| ----------------------------------------------------- | ------------------------------- | ---------------------------------------------------- |
+| "Added WebSocket handler in src/ws/"                  | Git commit message              | Describes what changed in code                       |
+| "Chose WebSocket over polling because..."             | `.harness/state.json` decisions | Records the choice and rationale for future sessions |
+| "WebSocket requires sticky sessions in load balancer" | `.harness/learnings.md`         | Non-obvious operational concern future sessions need |
+| "Task 4 complete"                                     | `.harness/state.json` progress  | Tracks execution position                            |
+| "The WebSocket library auto-reconnects by default"    | `.harness/learnings.md`         | Gotcha that saves future debugging time              |
+| "Tried approach X, failed because Y"                  | `.harness/failures.md`          | Active anti-pattern to avoid repeating               |
+| "Completed Tasks 1-3, Task 4 pending"                 | `.harness/handoff.json`         | Structured context for next skill                    |
+| "[PREPARE 10:30] Loaded 3 failures"                   | `.harness/trace.md`             | Reasoning trace for debugging agent behavior         |

package/dist/agents/skills/cursor/harness-state-management/skill.yaml

@@ -0,0 +1,33 @@
+name: harness-state-management
+version: "1.0.0"
+description: Manage persistent session state across harness agent sessions
+cognitive_mode: meticulous-implementer
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+cli:
+  command: harness skill run harness-state-management
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-state-management
+    path: string
+type: flexible
+internal: true
+state:
+  persistent: true
+  files:
+    - .harness/state.json
+depends_on: []

package/dist/agents/skills/cursor/harness-supply-chain-audit/SKILL.md

@@ -0,0 +1,281 @@
+# Harness Supply Chain Audit
+
+> 6-factor dependency risk evaluation adapted from Trail of Bits security skill patterns. Surfaces dependency risk flags for human review — not automated verdicts.
+
+## When to Use
+
+- Before a major release to assess dependency risk
+- After adding new dependencies
+- During security audits or compliance reviews
+- When `on_milestone` trigger fires (part of release gate)
+- NOT as a replacement for `npm audit` — this complements it with risk signals beyond CVEs
+- NOT for license compliance (separate concern)
+
+## Iron Law
+
+**Present findings as flags for human review, never as verdicts.** A dependency flagged as "high risk" may be entirely appropriate for a project. The skill surfaces signals; humans decide whether to act.
+
+---
+
+## Process
+
+### Phase 1: INVENTORY — Build Dependency List
+
+1. **Resolve project root.** Use the path argument or default to the current directory.
+
+2. **Detect lockfile.** Check for the following in order:
+   - `package-lock.json` (npm)
+   - `pnpm-lock.yaml` (pnpm)
+   - `yarn.lock` (yarn)
+   - If none found: report "No lockfile detected. Run `npm install` first." and stop.
+
+3. **Parse direct dependencies** from `package.json`:
+   - Read `dependencies` and `devDependencies`
+   - Build a list: `{ name, version, isDev }`
+
+4. **Parse transitive depth** from lockfile:
+   - For `package-lock.json`: read `packages` keys to extract the dependency tree. Nesting depth of `node_modules/` segments in keys indicates transitive depth.
+   - For `pnpm-lock.yaml`: read `importers` section for direct dependencies (keyed by workspace path, e.g., `.` for root). Each importer lists `dependencies` and `devDependencies` with version specifiers. Read `packages` section for resolved versions — keys are package identifiers (e.g., `/@scope/pkg@1.2.3`) with `resolution` (tarball URL + integrity hash) and `dependencies` sub-map for transitives.
+   - For `yarn.lock`: parse block-format entries. Each block header is `"pkg@version-range":` followed by indented fields: `version` (resolved), `resolved` (tarball URL), `integrity` (hash), and `dependencies` sub-block listing transitive deps as `"name" "version-range"` pairs.
+   - Assign each package a depth (0 = direct, 1 = first-level transitive, etc.)
+   - Flag packages with depth > 5 for transitive risk evaluation
+
+5. **Build inventory table:**
+
+   ```
+   INVENTORY: <project-name>
+   Direct dependencies: N
+   Dev dependencies: N
+   Total packages (including transitives): N
+   Deep transitive packages (depth > 5): N
+   ```
+
+6. Proceed to EVALUATE.
+
+---
+
+### Phase 2: EVALUATE — Score Dependencies on 6 Factors
+
+For each **direct dependency** (and any transitive with depth > 5), score on 6 factors:
+
+> Network access required: npm registry (`https://registry.npmjs.org/<pkg>`) and GitHub API (`https://api.github.com/repos/<owner>/<repo>`).
+>
+> - If npm registry returns 404: mark as "unresolvable", flag for manual review, skip remaining factors
+> - If GitHub API rate limits hit: score `maintenance-status` as "unknown", continue with other factors
+> - If no GitHub repo link in package metadata: skip `maintenance-status` factor, note in report
+
+#### Factor 1: Maintainer Concentration
+
+- Fetch: `GET https://registry.npmjs.org/<pkg>`
+- Check: `maintainers` array length
+- Score:
+  - **High risk:** 1 maintainer (bus factor = 1)
+  - **Medium risk:** 2-3 maintainers
+  - **Low risk:** 4+ maintainers
+
+#### Factor 2: Maintenance Status
+
+- Source: npm `time` field (last publish date) + GitHub API commit activity
+- npm: `GET https://registry.npmjs.org/<pkg>` → `time.modified`
+- GitHub: `GET https://api.github.com/repos/<owner>/<repo>/commits?per_page=1` → latest commit date
+- Score:
+  - **High risk:** Last publish > 12 months ago AND no GitHub commits in 6 months
+  - **Medium risk:** Last publish > 12 months ago OR no commits in 6 months (not both)
+  - **Low risk:** Active in both dimensions
+
+#### Factor 3: Popularity Signal
+
+- Fetch: `GET https://api.npmjs.org/downloads/point/last-week/<pkg>`
+- Score:
+  - **High risk:** < 1,000 weekly downloads
+  - **Medium risk:** 1,000–10,000 weekly downloads
+  - **Low risk:** > 10,000 weekly downloads
+  - **Note:** Low popularity is a signal, not a verdict — internal/niche packages are expected to be low
+
+#### Factor 4: Install Scripts
+
+- Read: `node_modules/<pkg>/package.json` (or lockfile-resolved path) → `scripts` field
+- Check for: `preinstall`, `postinstall`, `install`, `preuninstall`, `postuninstall`
+- Score:
+  - **High risk:** Any install script present
+  - **Low risk:** No install scripts
+  - **Note:** Some install scripts are legitimate (native addon compilation). Flag for review.
+
+#### Factor 5: Known CVEs
+
+- Run: `npm audit --json` or `pnpm audit --json`
+- Parse: map findings to their package name
+- Score:
+  - **Critical:** Any high/critical severity CVE
+  - **Medium risk:** Moderate severity CVE
+  - **Low risk:** No CVEs or low severity only
+
+#### Factor 6: Transitive Risk
+
+- Source: Lockfile depth analysis from INVENTORY phase
+- Score:
+  - **High risk:** Depth > 5 AND subtree size > 20 transitive packages
+  - **Medium risk:** Depth > 5 OR subtree size > 20
+  - **Low risk:** Depth ≤ 5 and subtree size ≤ 20
+
+#### Risk Scoring
+
+Combine factor scores into an overall risk level:
+
+| Overall Risk | Condition                                                      |
+| ------------ | -------------------------------------------------------------- |
+| **Critical** | Factor 5 is Critical (any high/critical CVE)                   |
+| **High**     | 2+ factors scored High, OR Factor 1 is High + Factor 2 is High |
+| **Medium**   | 1 factor scored High, OR 3+ factors scored Medium              |
+| **Low**      | All factors Low or at most 1 Medium                            |
+
+---
+
+### Phase 3: REPORT — Generate Risk Summary
+
+1. **Produce risk summary table** sorted by overall risk (Critical first):
+
+   ```
+   Supply Chain Audit: <project-name>
+   Date: <ISO date>
+   Packages evaluated: N direct + M deep transitives
+
+   ┌─────────────────────┬──────────┬────────────┬─────────────┬────────────┬──────┬─────────────┐
+   │ Package             │ Version  │ Maintainers│ Last Publish│ Downloads  │ CVEs │ Overall Risk│
+   ├─────────────────────┼──────────┼────────────┼─────────────┼────────────┼──────┼─────────────┤
+   │ example-pkg         │ 1.2.3    │ 1 (HIGH)   │ 18mo (HIGH) │ 500 (MED)  │ none │ HIGH        │
+   │ another-pkg         │ 2.0.0    │ 12         │ 2mo         │ 50k        │ 1 mod│ MEDIUM      │
+   └─────────────────────┴──────────┴────────────┴─────────────┴────────────┴──────┴─────────────┘
+   ```
+
+2. **Detail section for Critical and High risk packages:**
+
+   ```
+   HIGH RISK: example-pkg@1.2.3
+   ├── Maintainer concentration: 1 maintainer (bus factor = 1)
+   ├── Maintenance status: Last publish 18 months ago, no commits in 12 months
+   ├── Popularity: 500 weekly downloads
+   ├── Install scripts: none
+   ├── Known CVEs: none
+   └── Transitive risk: depth 2, subtree 4 packages
+   Recommendation: Consider replacing with a well-maintained alternative,
+   or pin the version and monitor for abandonment.
+   ```
+
+3. **Install script warnings** (any package with install scripts):
+
+   ```
+   INSTALL SCRIPTS DETECTED:
+   - node-gyp@9.4.0: postinstall — native addon compilation (likely legitimate)
+   - suspicious-pkg@1.0.0: postinstall — review script contents before trusting
+   ```
+
+4. **Summary line:**
+
+   ```
+   RESULT: 1 Critical, 2 High, 3 Medium, N Low — Review flagged items before release
+   ```
+
+5. **Output:** Print report to stdout. If `--output <file>` was passed, also write to that file.
+
+---
+
+## Gates
+
+- **Stop if no lockfile.** Do not evaluate without a lockfile — results will be unreliable.
+- **Present as flags, not verdicts.** Never state "this package is unsafe." State "this package has signals that warrant review."
+- **Do not block on API failures.** If npm registry or GitHub API is unavailable, note which factors were skipped and continue with available data.
+
+## Harness Integration
+
+- **`harness validate`** — Run after creating the skill files to verify they are properly placed.
+- **Triggers:** `on_milestone` fires this skill as part of the milestone completion checklist.
+- **Depends on:** `harness-security-scan` — run after mechanical scanning to complete the security picture.
+- **Output:** Stdout report, optionally written to file via `--output`. No state files written.
+
+## Evidence Requirements
+
+When reporting findings, cite the source for each factor:
+
+- Maintainer data: `registry.npmjs.org/<pkg>` → `maintainers` field
+- Publish date: `registry.npmjs.org/<pkg>` → `time.modified`
+- Downloads: `api.npmjs.org/downloads/point/last-week/<pkg>`
+- Install scripts: `node_modules/<pkg>/package.json` → `scripts`
+- CVEs: `npm audit --json` output
+- Depth: lockfile analysis
+
+Do not assert risk scores without citing the specific data point that generated the score.
+
+## Success Criteria
+
+- Running `/harness:supply-chain-audit` on a project with dependencies outputs a risk table with all 6 factors scored
+- A dependency with a sole maintainer and no commits in 12 months scores "high risk"
+- A dependency with a `postinstall` script is flagged in the install scripts section
+- API failures produce "unknown" scores with a note, not errors that stop the audit
+- All findings are framed as flags for human review, not automated verdicts
+
+## Escalation
+
+- **If a critical CVE is found:** Surface immediately — do not bury it in the table. Recommend blocking the dependency update or requiring an immediate patch before merge.
+- **If all maintainers are unresponsive:** Flag the package as abandoned and recommend finding an alternative. Include download counts to help the user assess how widely adopted the package is.
+- **If an install script has unknown behavior:** Do not guess. State that the script requires manual review and link to the script source.
+- **If the npm or GitHub API is unavailable:** Note which factors were skipped with "unknown" scores. Do not fail the audit — partial results are better than none.
+- **If the user asks for a verdict ("is this safe?"):** Decline to give a binary answer. Supply chain risk is probabilistic. Present the risk signals and let the human decide.
+
+## Examples
+
+```
+Supply Chain Audit: my-project
+Date: 2026-03-31
+Packages evaluated: 24 direct + 3 deep transitives (depth > 5)
+
+CRITICAL (1):
+  lodash@4.17.20 — CVE-2021-23337 (high severity, unpatched)
+
+HIGH (2):
+  abandoned-util@0.9.1 — sole maintainer, last publish 22 months ago
+  sketchy-helper@2.1.0 — sole maintainer, postinstall script detected
+
+MEDIUM (3):
+  small-lib@1.0.0 — 800 weekly downloads (low popularity signal)
+  ...
+
+LOW (18): no significant risk signals
+
+INSTALL SCRIPTS:
+  node-gyp@9.4.0 — postinstall (native compilation, likely legitimate)
+  sketchy-helper@2.1.0 — postinstall (REVIEW: contents unknown)
+
+RESULT: 1 Critical, 2 High, 3 Medium, 18 Low
+Next steps: Update lodash to patch CVE. Review sketchy-helper postinstall script.
+Consider alternatives to abandoned-util.
+```
+
+## Example Output
+
+```
+Supply Chain Audit: my-project
+Date: 2026-03-31
+Packages evaluated: 24 direct + 3 deep transitives (depth > 5)
+
+CRITICAL (1):
+  lodash@4.17.20 — CVE-2021-23337 (high severity, unpatched)
+
+HIGH (2):
+  abandoned-util@0.9.1 — sole maintainer, last publish 22 months ago
+  sketchy-helper@2.1.0 — sole maintainer, postinstall script detected
+
+MEDIUM (3):
+  small-lib@1.0.0 — 800 weekly downloads (low popularity signal)
+  ...
+
+LOW (18): no significant risk signals
+
+INSTALL SCRIPTS:
+  node-gyp@9.4.0 — postinstall (native compilation, likely legitimate)
+  sketchy-helper@2.1.0 — postinstall (REVIEW: contents unknown)
+
+RESULT: 1 Critical, 2 High, 3 Medium, 18 Low
+Next steps: Update lodash to patch CVE. Review sketchy-helper postinstall script.
+Consider alternatives to abandoned-util.
+```

package/dist/agents/skills/cursor/harness-supply-chain-audit/skill.yaml

@@ -0,0 +1,51 @@
+name: harness-supply-chain-audit
+version: "1.0.0"
+description: 6-factor dependency risk evaluation for supply chain security
+cognitive_mode: meticulous-implementer
+triggers:
+  - manual
+  - on_milestone
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Grep
+  - Glob
+  - WebFetch
+cli:
+  command: harness skill run harness-supply-chain-audit
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: depth
+      description: Maximum dependency depth to evaluate (default 3)
+      required: false
+    - name: output
+      description: Write report to file instead of stdout
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-supply-chain-audit
+    path: string
+type: rigid
+tier: 2
+phases:
+  - name: inventory
+    description: Build dependency inventory from lockfile
+    required: true
+  - name: evaluate
+    description: Score each dependency on 6 risk factors
+    required: true
+  - name: report
+    description: Generate risk report with actionable findings
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on:
+  - harness-security-scan