@harness-engineering/cli 1.15.0 → 1.16.0

package/dist/agents/skills/gemini-cli/harness-deployment/SKILL.md

@@ -247,6 +247,58 @@ Phase 4: VALIDATE
 - **No deploy without rollback.** Every deployment target must have a documented or automated rollback mechanism. Missing rollback is a blocking warning.
 - **No skipping pipeline lint.** Pipeline configuration must pass syntax validation before recommendations are made.
 
+## Evidence Requirements
+
+When this skill makes claims about existing code, architecture, or behavior,
+it MUST cite evidence using one of:
+
+1. **File reference:** `file:line` format (e.g., `src/auth.ts:42`)
+2. **Code pattern reference:** `file` with description (e.g., `src/utils/hash.ts` —
+   "existing bcrypt wrapper")
+3. **Test/command output:** Inline or referenced output from a test run or CLI command
+4. **Session evidence:** Write to the `evidence` session section via `manage_state`
+
+**Uncited claims:** Technical assertions without citations MUST be prefixed with
+`[UNVERIFIED]`. Example: `[UNVERIFIED] The auth middleware supports refresh tokens`.
+
+## Red Flags
+
+### Universal
+
+These apply to ALL skills. If you catch yourself doing any of these, STOP.
+
+- **"I believe the codebase does X"** — Stop. Read the code and cite a file:line
+  reference. Belief is not evidence.
+- **"Let me recommend [pattern] for this"** without checking existing patterns — Stop.
+  Search the codebase first. The project may already have a convention.
+- **"While we're here, we should also [unrelated improvement]"** — Stop. Flag the idea
+  but do not expand scope beyond the stated task.
+
+### Domain-Specific
+
+- **"Deploying without a health check endpoint"** — Stop. Without health checks, the orchestrator cannot detect failed deployments. Add health checks before deploying.
+- **"Skipping canary deployment, it's a small change"** — Stop. Small changes cause outages too. Follow the deployment policy regardless of change size.
+- **"Rolling back manually if something goes wrong"** — Stop. Manual rollback under incident pressure fails. Automate rollback before deploying.
+- **"We can update the runbook after the deploy"** — Stop. If the deployment changes operational behavior, update the runbook first. Stale runbooks during incidents cause escalations.
+
+## Rationalizations to Reject
+
+### Universal
+
+These reasoning patterns sound plausible but lead to bad outcomes. Reject them.
+
+- **"It's probably fine"** — "Probably" is not evidence. Verify before asserting.
+- **"This is best practice"** — Best practice in what context? Cite the source and
+  confirm it applies to this codebase.
+- **"We can fix it later"** — If it is worth flagging, it is worth documenting now
+  with a concrete follow-up plan.
+
+### Domain-Specific
+
+- **"It's just a config change, not a code change"** — Config changes cause outages at the same rate as code changes. Deploy them with the same rigor and rollback strategy.
+- **"We tested this in staging"** — Staging is not production. Traffic patterns, data volume, and edge cases differ. Staging success does not guarantee production safety.
+- **"Downtime will be brief"** — Brief is not zero. Quantify the expected impact and communicate it to stakeholders before deploying.
+
 ## Escalation
 
 - **When the CI/CD platform is unsupported:** Report which platform was detected and that analysis is limited to general best practices. Recommend the user provide platform-specific documentation for deeper analysis.

package/dist/agents/skills/gemini-cli/harness-planning/SKILL.md

@@ -22,6 +22,21 @@ A plan with vague tasks like "add validation" or "implement the service" is not
 
 ---
 
+### Rigor Levels
+
+The `rigorLevel` is passed to the planner by autopilot (or set via `--fast`/`--thorough` flags in standalone invocation). Default is `standard`.
+
+| Phase     | `fast`                                                           | `standard` (default)                                      | `thorough`                                                                      |
+| --------- | ---------------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| SCOPE     | No change — always derive observable truths.                     | No change.                                                | No change.                                                                      |
+| DECOMPOSE | Skip skeleton pass. Produce full tasks directly after file map.  | Skeleton if estimated task count >= 8. Full tasks if < 8. | Always produce skeleton. Require human approval before expanding to full tasks. |
+| SEQUENCE  | No change — always order by dependency.                          | No change.                                                | No change.                                                                      |
+| VALIDATE  | No change — always run harness validate and verify completeness. | No change.                                                | No change.                                                                      |
+
+The skeleton pass is the primary rigor lever for planning. Fast mode trusts the direction and goes straight to full detail. Thorough mode always validates direction before investing tokens in full task expansion.
+
+---
+
 ### Phase 1: SCOPE — Derive Must-Haves from Goals
 
 Work backward from the goal. Do not start with "what should we build?" Start with "what must be true when we are done?"
@@ -129,21 +144,63 @@ When presenting the task breakdown, use progress markers:
    MODIFY src/api/routes/users.ts (add notification trigger)
    ```
 
-2. **Decompose into atomic tasks.** Each task must:
+2. **Skeleton pass (rigor-gated).** Before writing full task details, produce a lightweight skeleton that validates direction. The skeleton is ~200 tokens and catches structural errors before investing in full expansion.
+
+   **Gating logic:**
+   - `rigorLevel == "fast"`: Skip this step entirely. Proceed directly to full task decomposition.
+   - `rigorLevel == "standard"`: Estimate the task count from the file map. If >= 8 tasks, produce the skeleton and present for approval. If < 8 tasks, skip the skeleton and proceed to full decomposition.
+   - `rigorLevel == "thorough"`: Always produce the skeleton and require human approval before expanding.
+
+   **Skeleton format:**
+
+   ```
+   ## Skeleton
+
+   1. Foundation types and interfaces (~3 tasks, ~10 min)
+   2. Core scoring module with TDD (~2 tasks, ~8 min)
+   3. CLI integration and flag parsing (~4 tasks, ~15 min)
+   4. Integration tests and validation (~3 tasks, ~10 min)
+
+   **Estimated total:** 12 tasks, ~43 minutes
+   ```
+
+   Each line is a logical group of tasks with an estimated count and time. The skeleton does NOT contain file paths, code, or detailed instructions — those come in the expansion step.
+
+   **Approval gate:**
+
+   When the skeleton is produced, present it to the human:
+
+   ```json
+   emit_interaction({
+     path: "<project-root>",
+     type: "confirmation",
+     confirmation: {
+       text: "Approve skeleton direction?",
+       context: "<estimated task count> tasks across <group count> groups. <one-sentence summary of approach>",
+       impact: "Approving proceeds to full task expansion. Rejecting allows direction change before detail investment.",
+       risk: "low"
+     }
+   })
+   ```
+
+   - **If approved:** Proceed to full task decomposition (step 3).
+   - **If rejected:** Ask what should change. Revise the skeleton. Re-present for approval. Do not expand until approved.
+
+3. **Decompose into atomic tasks.** Each task must:
    - Be completable in 2-5 minutes
    - Fit in a single context window
    - Have a clear, testable outcome
    - Follow TDD: write test, fail, implement, pass, commit
    - Produce one atomic commit
 
-3. **Write complete instructions for each task.** Not summaries — complete executable instructions:
+4. **Write complete instructions for each task.** Not summaries — complete executable instructions:
    - **Exact file paths** to create or modify
    - **Exact code** to write (not "add validation logic" — write the actual validation code)
    - **Exact test commands** to run (e.g., `npx vitest run src/services/notification-service.test.ts`)
    - **Exact commit message** to use
    - **`harness validate`** as the final step
 
-4. **Include checkpoints.** Mark tasks that require human verification, decisions, or actions:
+5. **Include checkpoints.** Mark tasks that require human verification, decisions, or actions:
    - `[checkpoint:human-verify]` — Pause, show result, wait for confirmation
    - `[checkpoint:decision]` — Pause, present options, wait for choice
    - `[checkpoint:human-action]` — Pause, instruct human on what they need to do
@@ -281,6 +338,15 @@ One sentence.
 - CREATE path/to/file.ts
 - MODIFY path/to/other-file.ts
 
+## Skeleton (if produced)
+
+1. <group name> (~N tasks, ~N min)
+2. <group name> (~N tasks, ~N min)
+
+**Estimated total:** N tasks, ~N minutes
+
+_Skeleton approved: yes/no. If no, note the revision._
+
 ## Tasks
 
 ### Task 1: <descriptive name>
@@ -359,6 +425,8 @@ When this skill makes claims about existing code structure, file locations, or i
 - **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).
+- **Rigor levels** — `--fast` / `--thorough` flags control the skeleton pass in DECOMPOSE. Fast skips skeleton entirely. Standard produces skeleton for plans with >= 8 tasks. Thorough always produces skeleton and requires approval. See the Rigor Levels table for details.
+- **Two-pass planning** — Skeleton pass produces a ~200-token outline before full task expansion. Catches directional errors early. Gated by rigor level and estimated task count.
 
 ## Change Specifications
 
@@ -394,6 +462,11 @@ When `docs/changes/` exists in the project, produce `docs/changes/<feature>/delt
 - `harness validate` passes before the plan is written
 - `harness validate` is included as a step in every task
 - The human has reviewed and approved the plan
+- When `rigorLevel` is `fast`, the skeleton pass is skipped and full tasks are produced directly
+- When `rigorLevel` is `thorough`, a skeleton is always produced and requires human approval before expansion
+- When `rigorLevel` is `standard` and task count >= 8, a skeleton is produced for approval
+- When `rigorLevel` is `standard` and task count < 8, the skeleton is skipped
+- The skeleton format is lightweight (~200 tokens): numbered groups with task count and time estimates
 
 ## Examples
 
@@ -420,6 +493,10 @@ MODIFY src/api/routes/users.ts
 MODIFY src/api/routes/users.test.ts
 ```
 
+**Skeleton (standard mode, 6 tasks — skeleton skipped because < 8 tasks)**
+
+_Skeleton not produced — task count (6) below threshold (8)._
+
 **Task 1: Define notification types**
 
 ```
@@ -463,6 +540,25 @@ Files: src/services/notification-service.ts, src/services/notification-service.t
 6. Commit: "feat(notifications): add list and expiry to NotificationService"
 ```
 
+### Example: Planning with Skeleton (thorough mode)
+
+**Goal:** Add rate limiting to all API endpoints.
+
+**Skeleton (thorough mode — always produced):**
+
+```
+## Skeleton
+
+1. Rate limit types and configuration (~2 tasks, ~7 min)
+2. Rate limit middleware with Redis backend (~3 tasks, ~12 min)
+3. Route integration and per-endpoint config (~4 tasks, ~15 min)
+4. Integration tests and load verification (~3 tasks, ~10 min)
+
+**Estimated total:** 12 tasks, ~44 minutes
+```
+
+_Presented for approval. User approved. Expanded to full tasks._
+
 ## Gates
 
 These are hard stops. Violating any gate means the process has broken down.

package/dist/agents/skills/gemini-cli/harness-planning/skill.yaml

@@ -22,6 +22,12 @@ cli:
     - name: path
       description: Project root path
       required: false
+    - name: fast
+      description: Skip skeleton pass — produce full plan directly
+      required: false
+    - name: thorough
+      description: Always produce skeleton for approval before full expansion
+      required: false
 mcp:
   tool: run_skill
   input:

package/dist/agents/skills/gemini-cli/harness-pre-commit-review/SKILL.md

@@ -150,7 +150,7 @@ Run the built-in security scanner against staged files. This is a mechanical che
 git diff --cached --name-only --diff-filter=d | grep -E '\.(ts|tsx|js|jsx|go|py)$'
 ```
 
-Use the `run_security_scan` MCP tool or invoke the scanner on the staged files. Report any findings:
+Run `harness check-security --changed-only` on the staged files. Report any findings:
 
 - **Error findings (blocking):** Hardcoded secrets, eval/injection, weak crypto — these block the commit just like lint failures.
 - **Warning/info findings (advisory):** CORS wildcards, HTTP URLs, disabled TLS — reported but do not block.

package/dist/agents/skills/gemini-cli/harness-security-review/SKILL.md

@@ -55,16 +55,14 @@ This skill follows the Deterministic-vs-LLM Responsibility Split principle. The
 
 Run the built-in security scanner against the project.
 
-1. **Run the scanner.** Use the `run_security_scan` MCP tool or invoke `SecurityScanner` directly:
+1. **Run the scanner.** Use the `harness check-security` CLI command:
 
    ```bash
-   # Via MCP
-   harness scan --security
-
-   # Via CLI
-   npx vitest run packages/core/tests/security/
+   harness check-security
    ```
 
+   For machine-readable output, add `--json`. For scanning only changed files, add `--changed-only`.
+
 2. **Review findings.** Categorize by severity:
    - **Error (blocking):** Must fix before merge — secrets, injection, eval, weak crypto
    - **Warning (review):** Should fix — CORS wildcards, disabled TLS, path traversal patterns
@@ -103,6 +101,28 @@ After the OWASP baseline, add stack-specific checks:
 - **React:** XSS via `dangerouslySetInnerHTML`, sensitive data in client state, insecure `postMessage` listeners
 - **Go:** Race conditions in concurrent handlers, `unsafe.Pointer` usage, format string injection
 
+#### Insecure Defaults Analysis
+
+For each configuration variable that controls a security feature (auth, encryption, TLS, CORS, rate limiting), verify:
+
+- Does the feature **fail-closed** (error/deny) when configuration is missing?
+- Or does it **fail-open** (degrade to permissive/disabled)?
+- Trace fallback chains: `config.x ?? env.Y ?? default` — is the final default secure?
+
+Patterns the mechanical `SEC-DEF-*` rules cannot catch (focus here):
+
+- Multi-line fallback chains where the insecure default is not adjacent to the security variable name
+- Conditional logic that enables security features only in specific environments (e.g., `if (isProd) enableTLS()`)
+- Error handlers that swallow failures in auth, session, or token validation code (multi-line `catch` blocks)
+- Silent type coercions that convert truthy env vars to falsy values
+
+**Rationalizations to reject** (adapted from Trail of Bits):
+
+- "The default is only used in development" — production deployments inherit defaults when config is missing
+- "The env var will always be set" — missing env vars are the #1 cause of fail-open in production
+- "The catch block will be filled in later" — empty auth catch blocks ship to production
+- "It's behind a feature flag" — feature flags can be inadvertently enabled or disabled
+
 ### Phase 3: THREAT-MODEL (optional, `--deep` flag; full mode or explicit `--deep` in pipeline)
 
 When invoked with `--deep`, build a lightweight threat model:
@@ -149,7 +169,7 @@ Threat Model:
 
 ## Harness Integration
 
-- **`run_security_scan` MCP tool** — Run the mechanical scanner programmatically
+- **`harness check-security`** — Run the mechanical scanner via CLI. Use `--json` for machine-readable output.
 - **`harness validate`** — Standard project health check
 - **`query_graph` / `get_relationships`** — Used in threat modeling phase for data flow tracing
 - **`get_impact`** — Understand blast radius of security-sensitive changes

package/dist/agents/skills/gemini-cli/harness-security-scan/SKILL.md

@@ -58,6 +58,58 @@
 - **`harness.config.json`** — Security section configures severity threshold and file exclusions.
 - **codebase-health-analyst persona** — Invokes this skill as part of its sweep.
 
+## Evidence Requirements
+
+When this skill makes claims about existing code, architecture, or behavior,
+it MUST cite evidence using one of:
+
+1. **File reference:** `file:line` format (e.g., `src/auth.ts:42`)
+2. **Code pattern reference:** `file` with description (e.g., `src/utils/hash.ts` —
+   "existing bcrypt wrapper")
+3. **Test/command output:** Inline or referenced output from a test run or CLI command
+4. **Session evidence:** Write to the `evidence` session section via `manage_state`
+
+**Uncited claims:** Technical assertions without citations MUST be prefixed with
+`[UNVERIFIED]`. Example: `[UNVERIFIED] The auth middleware supports refresh tokens`.
+
+## Red Flags
+
+### Universal
+
+These apply to ALL skills. If you catch yourself doing any of these, STOP.
+
+- **"I believe the codebase does X"** — Stop. Read the code and cite a file:line
+  reference. Belief is not evidence.
+- **"Let me recommend [pattern] for this"** without checking existing patterns — Stop.
+  Search the codebase first. The project may already have a convention.
+- **"While we're here, we should also [unrelated improvement]"** — Stop. Flag the idea
+  but do not expand scope beyond the stated task.
+
+### Domain-Specific
+
+- **"This finding is in test code, so it's not a real issue"** — Stop. Test code can leak secrets, establish bad patterns, and be copy-pasted to production.
+- **"This dependency is widely used, so it's safe"** — Stop. Popularity is not a security guarantee. Check CVE databases and advisory feeds.
+- **"This is a low-severity finding, skipping"** — Stop. Low-severity findings compound. Document why you are deprioritizing, do not silently skip.
+- **"The scanner didn't flag it, so it's clean"** — Stop. Scanners have false negatives. A clean scan is not proof of security — it is absence of evidence.
+
+## Rationalizations to Reject
+
+### Universal
+
+These reasoning patterns sound plausible but lead to bad outcomes. Reject them.
+
+- **"It's probably fine"** — "Probably" is not evidence. Verify before asserting.
+- **"This is best practice"** — Best practice in what context? Cite the source and
+  confirm it applies to this codebase.
+- **"We can fix it later"** — If it is worth flagging, it is worth documenting now
+  with a concrete follow-up plan.
+
+### Domain-Specific
+
+- **"No attacker would find this"** — Security by obscurity. If the code is wrong, flag it regardless of discoverability.
+- **"We're behind a firewall"** — Network boundaries change. Code should be secure at every layer regardless of deployment topology.
+- **"The framework handles this for us"** — Verify the framework's actual behavior. Misuse of a secure framework is still insecure.
+
 ## Escalation
 
 - **When error-severity findings are disputed:** The scanner is mechanical — it may flag false positives. If a finding is a false positive, add a `// harness-ignore SEC-XXX` comment on the line and document the rationale. Do not suppress without explanation.

package/dist/agents/skills/gemini-cli/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.
+```