@harness-engineering/cli 1.14.0 → 1.16.0

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

@@ -23,6 +23,15 @@ cli:
     - name: path
       description: Project root path
       required: false
+    - name: review-plans
+      description: Force human review of all plans (overrides auto-approve)
+      required: false
+    - name: fast
+      description: Run with reduced rigor — skip skeleton approval, skip scratchpad, minimal verification
+      required: false
+    - name: thorough
+      description: Run with maximum rigor — require skeleton approval, verbose scratchpad, full verification
+      required: false
 mcp:
   tool: run_skill
   input:
@@ -37,6 +46,9 @@ phases:
   - name: loop
     description: Execute state machine — assess, plan, execute, verify, review per phase
     required: true
+  - name: final_review
+    description: Project-wide code review of cumulative changes before PR offer
+    required: true
   - name: complete
     description: Final summary and PR offering
     required: true

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

@@ -58,6 +58,20 @@ interface ReviewFinding {
 | `--deep`          | Pass `--deep` to `harness-security-review` for threat modeling in the security fan-out slot |
 | `--no-mechanical` | Skip mechanical checks (useful if already run in CI)                                        |
 | `--ci`            | Enable eligibility gate, non-interactive output                                             |
+| `--fast`          | Reduced rigor: skip learnings integration, fast-tier agents for all fan-out slots           |
+| `--thorough`      | Maximum rigor: always load learnings, full agent roster + meta-judge, learnings in output   |
+
+### Rigor Levels
+
+The `rigorLevel` is set via `--fast` or `--thorough` flags (or passed by autopilot). Default is `standard`. Rigor controls learnings integration, agent tier selection, and output verbosity.
+
+| Phase      | `fast`                                                            | `standard` (default)                                                                               | `thorough`                                                                                                      |
+| ---------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| 3. CONTEXT | Skip learnings integration entirely. No `filterByRelevance` call. | Load learnings if `.harness/review-learnings.md` exists. Score and filter via `filterByRelevance`. | Always load learnings. Score and filter via `filterByRelevance`. Fail loudly if learnings file is missing.      |
+| 4. FAN-OUT | All agents run at fast tier. Reduced focus areas.                 | Default tier assignments (see Model Tiers table).                                                  | Full agent roster at default tiers + meta-judge pass that cross-validates findings across domains.              |
+| 7. OUTPUT  | Standard output format.                                           | Standard output format.                                                                            | Include a "Learnings Applied" section listing which learnings influenced the review and their relevance scores. |
+
+When `rigorLevel` is `fast`, the pipeline optimizes for speed: learnings are skipped entirely and all fan-out agents run at fast tier. When `rigorLevel` is `thorough`, the pipeline optimizes for depth: learnings are always scored and included, the full agent roster runs, a meta-judge validates cross-domain findings, and the output includes which learnings were applied.
 
 ### Model Tiers
 
@@ -71,19 +85,39 @@ Tiers are abstract labels resolved at runtime from project config. If no config
 
 ### Review Learnings Calibration
 
-Before starting the pipeline, check for a project-specific calibration file:
+Before starting the pipeline, check for a project-specific calibration file. Learnings integration is gated by rigor level:
+
+- **`fast`:** Skip this section entirely. Do not read or score learnings.
+- **`standard`:** Read learnings if the file exists. Score and filter. If the file does not exist, proceed with default focus areas.
+- **`thorough`:** Always read learnings. If `.harness/review-learnings.md` does not exist, log a warning: "No review-learnings.md found -- thorough mode expects calibration data."
 
 ```bash
 cat .harness/review-learnings.md 2>/dev/null
 ```
 
-If `.harness/review-learnings.md` exists:
+If `.harness/review-learnings.md` exists (and rigor is not `fast`):
 
 1. **Read the Useful Findings section.** Prioritize these categories during review — they have historically caught real issues in this project.
 2. **Read the Noise / False Positives section.** De-prioritize or skip these categories — flagging them wastes the author's time and erodes trust in the review process.
 3. **Read the Calibration Notes section.** Apply these project-specific overrides to your review judgment. These represent deliberate team decisions, not oversights.
 
-If the file does not exist, proceed with default review focus areas. After completing the review, consider suggesting that the team create `.harness/review-learnings.md` if you notice patterns that would benefit from calibration.
+#### Learnings Relevance Scoring
+
+When learnings are loaded (standard or thorough mode), score them against the diff context before applying:
+
+1. **Build the diff context string.** Concatenate: changed file paths (one per line) + diff summary (commit message or PR description).
+2. **Score each learning** using `filterByRelevance(learnings, diffContext, 0.7, 1000)` from `packages/core/src/state/learnings-relevance.ts`.
+   - Each learning is scored against the diff context via Jaccard similarity.
+   - Only learnings scoring >= 0.7 are retained.
+   - Results are sorted by score descending.
+   - Results are truncated to fit within the 1000-token budget.
+3. **Apply filtered learnings** to the review focus areas:
+   - Useful Findings entries that pass the filter: boost priority for those categories.
+   - Noise/False Positive entries that pass the filter: actively suppress those patterns.
+   - Calibration Notes entries that pass the filter: apply as overrides.
+4. **If no learnings pass the 0.7 threshold,** proceed with default focus areas. Do not fall back to unscored inclusion.
+
+If the file does not exist and rigor is `standard`, proceed with default review focus areas. After completing the review, consider suggesting that the team create `.harness/review-learnings.md` if you notice patterns that would benefit from calibration.
 
 ## Pipeline Phases
 
@@ -285,6 +319,12 @@ Use commit history to answer:
 **Tier:** mixed (see per-agent tiers below)
 **Purpose:** Run four parallel review subagents, each with domain-scoped context from Phase 3. Each agent produces findings in the `ReviewFinding` schema.
 
+**Rigor overrides:**
+
+- **`fast`:** All four agents run at **fast tier** (haiku-class). Focus areas are unchanged but agents operate with reduced reasoning depth.
+- **`standard`:** Default tier assignments as listed per agent below.
+- **`thorough`:** Default tier assignments + a **meta-judge pass** after all agents return. The meta-judge (strong tier) cross-validates findings across domains: confirms findings cited by multiple agents, flags contradictions, and surfaces cross-cutting concerns that individual agents missed.
+
 #### Compliance Agent (standard tier)
 
 Reviews adherence to project conventions, standards, and documentation requirements.
@@ -493,6 +533,16 @@ For each issue, provide:
 - **Request Changes** — Critical or important issues must be addressed.
 - **Comment** — Observations only, no blocking issues.
 
+**Learnings Applied (thorough mode only):** When `rigorLevel` is `thorough`, append a "Learnings Applied" section after the Assessment:
+
+```
+**Learnings Applied:**
+- [0.85] "Useful Finding: Missing error handling in service layer" — boosted priority for error handling checks
+- [0.72] "Noise: Style-only import ordering" — suppressed import order findings
+```
+
+Each entry shows the Jaccard relevance score and how the learning influenced the review. This section is omitted in `fast` and `standard` modes.
+
 **Exit code:** 0 for Approve/Comment, 1 for Request Changes.
 
 #### Inline GitHub Comments (`--comment` flag)
@@ -679,6 +729,8 @@ Every review finding MUST cite evidence using one of:
 - **`harness cleanup`** — Optional check during Phase 2 for entropy accumulation in changed files.
 - **Graph queries** — Used in Phase 3 (CONTEXT) for dependency-scoped context and in Phase 5 (VALIDATE) for reachability verification. Graceful fallback when no graph exists.
 - **`emit_interaction`** -- Call after review approval to suggest transitioning to merge/PR creation. Only emitted on APPROVE assessment. Uses confirmed transition (waits for user approval).
+- **Rigor levels** — `--fast` / `--thorough` flags control learnings integration and agent tiers. Fast skips learnings and runs all agents at fast tier. Standard includes learnings if available. Thorough always loads learnings, runs a meta-judge pass, and includes a "Learnings Applied" section in output. See the Rigor Levels table for details.
+- **`filterByRelevance`** — Used in the Review Learnings Calibration section (Phase 3) to score learnings against diff context. Threshold 0.7, token budget 1000. From `packages/core/src/state/learnings-relevance.ts`.
 
 ## Success Criteria
 
@@ -696,6 +748,10 @@ Every review finding MUST cite evidence using one of:
 - No code merges with failing harness checks
 - Response to feedback (Role C) is verified before implementation
 - Pushback on incorrect feedback is evidence-based
+- When `rigorLevel` is `fast`, learnings integration is skipped and all fan-out agents run at fast tier
+- When `rigorLevel` is `thorough`, learnings are always loaded and scored, a meta-judge validates cross-domain findings, and a "Learnings Applied" section appears in the output
+- When `rigorLevel` is `standard`, learnings are included if `.harness/review-learnings.md` exists, scored via `filterByRelevance` at 0.7 threshold
+- When all learnings score below 0.7 threshold, zero learnings are included (no fallback to unscored inclusion)
 
 ## Examples
 
@@ -753,6 +809,44 @@ Every review finding MUST cite evidence using one of:
 - **Never agree performatively.** "Sure, I'll change that" without understanding why is forbidden. Every change must be understood.
 - **Never skip the YAGNI check.** Every suggestion must answer: "Does this serve a current, concrete need?" Speculative improvements are rejected.
 
+## 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
+
+- **"The change looks reasonable, approving"** — Stop. Have you read every changed file? Approval without full review is rubber-stamping.
+- **"Let me fix this issue I found"** — Stop. Review identifies issues; it does not fix them. Suggest the fix, do not apply it.
+- **"This is a minor style issue"** — Stop. Is it a style issue or a readability/maintainability concern? Classify accurately before dismissing.
+- **"The author probably meant to..."** — Stop. Do not infer intent. If the code is ambiguous, flag it as a question for the author.
+
+## 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
+
+- **"The tests pass, so the logic must be correct"** — Tests can be incomplete. Review the logic independently of test results.
+- **"This is how it was done elsewhere in the codebase"** — Existing patterns can be wrong. Evaluate the pattern on its merits, not just its precedent.
+- **"It's just a refactor, low risk"** — Refactors change behavior surfaces. Review them with the same rigor as feature changes.
+
 ## Escalation
 
 - **When reviewers disagree:** If two reviewers give contradictory feedback, escalate to the human or tech lead.

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

@@ -33,6 +33,12 @@ cli:
     - name: --ci
       description: Enable eligibility gate, non-interactive output
       required: false
+    - name: --fast
+      description: Reduced rigor — skip learnings integration, fast-tier agents only
+      required: false
+    - name: --thorough
+      description: Maximum rigor — always load learnings, full agent roster + meta-judge
+      required: false
 mcp:
   tool: run_skill
   input:

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

@@ -26,7 +26,7 @@
 
 ### Phase 1: CONTEXT -- Build Hotspot Map
 
-1. **Run hotspot detection** via `harness skill run harness-hotspot-detector` or equivalent git log analysis:
+1. **Run hotspot detection** via git log analysis:
    ```bash
    git log --format=format: --name-only --since="6 months ago" | sort | uniq -c | sort -rn | head -50
    ```
@@ -38,7 +38,6 @@
 
 1. **Dead code detection** (skip if `--architecture-only`):
    - Run `harness cleanup --type dead-code --json`
-   - Or use the `detect_entropy` MCP tool with `type: 'dead-code'`
    - Captures: dead files, dead exports, unused imports, dead internals, commented-out code blocks, orphaned dependencies
 
 2. **Architecture detection** (skip if `--dead-code-only`):
@@ -204,8 +203,7 @@ After removing the `legacy-auth` module:
 
 - **`harness cleanup --type dead-code --json`** -- Dead code detection input
 - **`harness check-deps --json`** -- Architecture violation detection input
-- **`harness skill run harness-hotspot-detector`** -- Hotspot context for safety classification
-- **`detect_entropy` MCP tool with `autoFix: true`** -- Detects entropy and applies safe fixes via the MCP server
+- **`git log` analysis** -- Hotspot context for safety classification (inline command, no skill invocation needed)
 - **`harness validate`** -- Final validation after all fixes
 - **`harness check-deps`** -- Final architecture check after all fixes
 

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

@@ -250,6 +250,58 @@ CREATE POLICY tenant_isolation ON users
 - **Migration files must include rollback logic.** Every `up` function must have a corresponding `down` function. WHERE a migration is irreversible (data loss on rollback), THEN it must be explicitly marked as such with a comment explaining why.
 - **No migrations that lock large tables without warning.** WHERE a migration performs an ALTER TABLE that acquires an ACCESS EXCLUSIVE lock on a table estimated to have more than 10,000 rows, THEN the skill must flag the lock risk and suggest a non-locking alternative.
 
+## 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
+
+- **"Running this migration in production"** without a rollback plan — Stop. Every migration must have a tested reverse migration before it touches production data.
+- **"Adding an index to speed up this query"** without checking write patterns — Stop. Indexes speed reads but slow writes. Check both access patterns before recommending.
+- **"Dropping this column, it's unused"** — Stop. Verify no application code references it — including ORMs, background jobs, analytics queries, and reporting systems.
+- **"Let's denormalize this for performance"** — Stop. Denormalization decisions are hard to reverse. Cite the specific query performance problem with evidence before recommending.
+
+## 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
+
+- **"The table is small, we don't need an index"** — Tables grow. Plan for the steady state, not the current row count.
+- **"The ORM handles this for us"** — ORMs generate SQL that may not match your performance expectations. Review the generated queries for correctness and efficiency.
+- **"We can always add a migration later"** — Schema changes in production have operational cost. Design the schema thoughtfully now rather than migrating repeatedly.
+
 ## Escalation
 
 - **Production data at risk:** When a migration would delete or overwrite existing data (DROP COLUMN, column type change that truncates), report: "This migration will permanently delete data in column `X`. Provide a data backup confirmation or approve a non-destructive alternative (add new column, backfill, drop old) before proceeding."

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-product-spec/SKILL.md

@@ -43,7 +43,7 @@
    ```
 
 5. **Load project context.** Scan the project for existing specs, user stories, or PRDs to maintain consistency in format and terminology:
-   - Check `docs/specs/`, `docs/requirements/`, `docs/prd/` for existing documents
+   - Check `docs/changes/`, `docs/requirements/`, `docs/prd/` for existing documents
    - Check `.github/ISSUE_TEMPLATE/` for the project's preferred issue format
    - Identify domain terminology used in existing specs
 
@@ -133,7 +133,7 @@
    REQ-003 -> US-004, US-005 (could-have)
    ```
 
-5. **Write the PRD to file.** Save to the project's spec directory (detected in Phase 1 or defaulting to `docs/specs/`). Use a filename pattern: `YYYY-MM-DD-feature-name-prd.md`.
+5. **Write the PRD to file.** Save to the project's spec directory (detected in Phase 1 or defaulting to `docs/changes/`). Use a filename pattern: `YYYY-MM-DD-feature-name-prd.md`.
 
 ---
 
@@ -171,7 +171,7 @@
    Coverage: all actors covered, all constraints addressed
    Open questions: N remaining
 
-   Generated: docs/specs/2026-03-27-notifications-prd.md
+   Generated: docs/changes/2026-03-27-notifications-prd.md
    ```
 
 ---
@@ -227,7 +227,7 @@ Phase 2: CRAFT
               And their other preferences remain unchanged.
 
 Phase 3: GENERATE
-  Written: docs/specs/2026-03-27-team-notifications-prd.md
+  Written: docs/changes/2026-03-27-team-notifications-prd.md
   Sections: problem statement, 4 user stories, 12 acceptance criteria, 8 BDD scenarios
   Traceability: REQ-001 -> US-001, US-002 | REQ-002 -> US-003, US-004
 
@@ -260,7 +260,7 @@ Phase 2: CRAFT
             return 400 and log a security warning.
 
 Phase 3: GENERATE
-  Written: docs/specs/2026-03-27-stripe-webhooks-prd.md
+  Written: docs/changes/2026-03-27-stripe-webhooks-prd.md
   Technical constraints section includes: idempotency keys, signature verification,
     5-second response SLA, Stripe retry behavior documentation
 

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