@harness-engineering/cli 1.15.0 → 1.17.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-roadmap-pilot/SKILL.md

@@ -0,0 +1,204 @@
+# Harness Roadmap Pilot
+
+> AI-assisted selection of the next highest-impact unblocked roadmap item. Scores candidates, recommends one, assigns it, and transitions to the appropriate next skill.
+
+## When to Use
+
+- When the team or individual needs to pick the next item to work on from the roadmap
+- When there are multiple unblocked items and prioritization guidance is needed
+- After completing a feature and looking for the next highest-impact work
+- NOT when the roadmap does not exist (direct user to harness-roadmap --create)
+- NOT when the user already knows what to work on (use harness-brainstorming or harness-autopilot directly)
+
+## Process
+
+### Iron Law
+
+**Never assign or transition without the human confirming the recommendation first.**
+
+Present the ranked candidates, the AI reasoning, and the recommended pick. Wait for explicit confirmation before making any changes.
+
+---
+
+### Phase 1: SCAN -- Score Candidates
+
+1. Check if `docs/roadmap.md` exists.
+   - If missing: error. "No roadmap found at docs/roadmap.md. Run harness-roadmap --create first."
+2. Parse the roadmap using `parseRoadmap` from `@harness-engineering/core`.
+3. Determine the current user:
+   - Use the `--user` argument if provided
+   - Otherwise, attempt to detect from git config: `git config user.name` or `git config user.email`
+   - If neither available, proceed without affinity scoring
+4. Call `scoreRoadmapCandidates(roadmap, { currentUser })` from `@harness-engineering/core`.
+5. If no candidates: inform the human. "No unblocked planned or backlog items found. All items are either in-progress, done, blocked, or the roadmap is empty."
+
+Present the top 5 candidates:
+
+```
+ROADMAP PILOT -- Candidate Scoring
+
+Top candidates (scored by position 50%, dependents 30%, affinity 20%):
+
+  #  Feature               Milestone    Priority  Score   Breakdown
+  1. Feature A             MVP Release  P0        0.85    pos:0.9 dep:0.8 aff:1.0
+  2. Feature B             MVP Release  P1        0.72    pos:0.8 dep:0.6 aff:0.5
+  3. Feature C             Q2 Release   --        0.65    pos:0.7 dep:0.5 aff:0.0
+  4. Feature D             Backlog      --        0.40    pos:0.3 dep:0.4 aff:0.0
+  5. Feature E             Backlog      --        0.35    pos:0.2 dep:0.3 aff:0.0
+```
+
+### Phase 2: RECOMMEND -- AI-Assisted Analysis
+
+1. For the top 3 candidates, read their spec files (if they exist):
+   - Read the spec's Overview and Goals section
+   - Read the spec's Success Criteria section
+   - Assess effort and impact from the spec content
+
+2. Provide a recommendation with reasoning:
+
+```
+RECOMMENDATION
+
+I recommend Feature A (MVP Release, P0, score: 0.85).
+
+Reasoning:
+- Highest priority (P0) with strong positional signal (first in MVP milestone)
+- Unblocks 2 downstream features (Feature X, Feature Y)
+- You completed its blocker "Foundation" -- high context affinity
+- Spec exists with clear success criteria (12 acceptance tests)
+- Estimated effort: medium (8 tasks in the plan)
+
+Alternative: Feature B (P1, score: 0.72) -- consider if Feature A's scope is too large for the current time window.
+
+Proceed with Feature A? (y/n/pick another)
+```
+
+### Phase 3: CONFIRM -- Human Decision
+
+1. Wait for human confirmation.
+   - If **yes**: proceed to Phase 4.
+   - If **pick another**: ask which candidate number, then proceed with that pick.
+   - If **no**: stop. No changes made.
+
+### Phase 4: ASSIGN -- Execute Assignment and Transition
+
+1. Call `assignFeature(roadmap, feature, currentUser, todayDate)` from `@harness-engineering/core`.
+   - This updates the feature's `Assignee` field
+   - Appends `assigned` record to assignment history (and `unassigned` for previous assignee if reassignment)
+
+2. Serialize and write the updated roadmap to `docs/roadmap.md`.
+
+3. If tracker config exists in `harness.config.json`, sync the assignment:
+   - Call the external tracker's `assignTicket` to push the assignment
+   - Log result but do not block on failure
+
+4. Determine the transition target:
+   - If the feature has a `spec` field (non-null): transition to `harness:autopilot`
+   - If the feature has no `spec`: transition to `harness:brainstorming`
+
+5. Present the transition to the human via `emit_interaction`:
+
+   ```json
+   emit_interaction({
+     path: "<project-root>",
+     type: "transition",
+     transition: {
+       completedPhase: "roadmap-pilot",
+       suggestedNext: "<brainstorming|autopilot>",
+       reason: "Feature '<name>' assigned and ready for <brainstorming|execution>",
+       artifacts: ["docs/roadmap.md"],
+       requiresConfirmation: true,
+       summary: "Assigned '<name>' to <user>. <Spec exists -- ready for autopilot|No spec -- needs brainstorming first>.",
+       qualityGate: {
+         checks: [
+           { "name": "roadmap-parsed", "passed": true },
+           { "name": "candidate-scored", "passed": true },
+           { "name": "human-confirmed", "passed": true },
+           { "name": "assignment-written", "passed": true }
+         ],
+         allPassed: true
+       }
+     }
+   })
+   ```
+
+6. Run `harness validate`.
+
+---
+
+## Harness Integration
+
+- **`parseRoadmap` / `serializeRoadmap`** -- Parse and write `docs/roadmap.md`. Import from `@harness-engineering/core`.
+- **`scoreRoadmapCandidates`** -- Core scoring algorithm. Import from `@harness-engineering/core`. Takes a `Roadmap` and optional `PilotScoringOptions` (currentUser for affinity).
+- **`assignFeature`** -- Assignment with history tracking. Import from `@harness-engineering/core`. Handles new assignment and reassignment (unassigned + assigned records).
+- **`emit_interaction`** -- Used for the skill transition at the end. Transitions to `harness:brainstorming` (no spec) or `harness:autopilot` (spec exists).
+- **`harness validate`** -- Run after assignment is written.
+- **External sync** -- If `harness.config.json` has tracker config, use `fullSync` or direct `assignTicket` to push assignment to external service.
+
+## Success Criteria
+
+1. Roadmap is parsed and unblocked planned/backlog items are scored
+2. Scoring uses two-tier sort: explicit priority first, then weighted score
+3. AI reads top candidates' specs and provides recommendation with reasoning
+4. Human confirms before any changes are made
+5. Assignment updates feature field, appends history records, and syncs externally
+6. Reassignment produces two history records (unassigned + assigned)
+7. Transition routes to brainstorming (no spec) or autopilot (spec exists)
+8. `harness validate` passes after all changes
+
+## Examples
+
+### Example: Pick Next Item from a Multi-Milestone Roadmap
+
+**Context:** A roadmap with 3 milestones, 8 features. 2 are in-progress, 1 is done, 2 are blocked, 3 are planned/backlog and unblocked. User is @cwarner who completed "Core Library Design".
+
+**Phase 1: SCAN**
+
+```
+ROADMAP PILOT -- Candidate Scoring
+
+Top candidates:
+  #  Feature               Milestone    Priority  Score   Breakdown
+  1. Graph Connector       MVP Release  P2        0.78    pos:0.8 dep:0.6 aff:1.0
+  2. Performance Baselines Q3 Hardening --        0.45    pos:0.5 dep:0.3 aff:0.0
+  3. Push Notifications    Backlog      --        0.30    pos:0.2 dep:0.2 aff:0.5
+```
+
+**Phase 2: RECOMMEND**
+
+```
+I recommend Graph Connector (MVP Release, P2, score: 0.78).
+
+Reasoning:
+- Only prioritized item among candidates (P2)
+- You completed its blocker "Core Library Design" -- maximum affinity bonus
+- Unblocks "API Integration" downstream
+- Spec exists at docs/changes/graph-connector/proposal.md
+
+Proceed? (y/n/pick another)
+```
+
+Human confirms **y**.
+
+**Phase 4: ASSIGN**
+
+```
+Assigned: Graph Connector -> @cwarner
+History: +1 record (assigned, 2026-04-02)
+Roadmap updated: docs/roadmap.md
+External sync: github:harness-eng/harness#43 assigned
+
+Transitioning to harness:autopilot (spec exists)...
+```
+
+## Gates
+
+- **No assignment without human confirmation.** The CONFIRM phase must complete with explicit approval. Never auto-assign.
+- **No transition without assignment.** The skill must write the assignment before transitioning to the next skill.
+- **No scoring without a parsed roadmap.** If `docs/roadmap.md` does not exist or fails to parse, stop with an error.
+
+## Escalation
+
+- **When no unblocked candidates exist:** Inform the human. Suggest reviewing blocked items to see if blockers can be resolved, or adding new features via `harness-roadmap --add`.
+- **When affinity data is unavailable:** Proceed without affinity scoring (weight falls to 0 for all candidates). Note this in the output.
+- **When external sync fails:** Log the error, complete the local assignment, and note that external sync can be retried with `harness-roadmap --sync`.

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

@@ -0,0 +1,52 @@
+name: harness-roadmap-pilot
+version: "1.0.0"
+description: AI-assisted selection of the next highest-impact roadmap item with scoring, assignment, and skill transition
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - emit_interaction
+cli:
+  command: harness skill run harness-roadmap-pilot
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: user
+      description: "Current user identifier (e.g., @cwarner) for affinity matching"
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-roadmap-pilot
+    path: string
+type: rigid
+tier: 2
+phases:
+  - name: scan
+    description: Parse roadmap, filter unblocked candidates, compute scores
+    required: true
+  - name: recommend
+    description: AI reads top candidates specs and provides recommendation
+    required: true
+  - name: confirm
+    description: Present recommendation to human for approval
+    required: true
+  - name: assign
+    description: Update assignee, history, sync external, transition to next skill
+    required: true
+state:
+  persistent: false
+depends_on:
+  - harness-brainstorming
+  - harness-autopilot
+  - harness-roadmap

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.