@harness-engineering/cli 1.26.1 → 1.27.1

package/dist/agents/skills/claude-code/harness-perf/SKILL.md

@@ -22,26 +22,28 @@ Tier 1 violations are non-negotiable blockers. If a Tier 1 violation is detected
 
 ### Phase 1: ANALYZE — Structural and Coupling Checks
 
-1. **Run structural checks.** Execute `harness check-perf --structural` to compute complexity metrics for all changed files:
+1. **Assess current performance posture.** Run `check_performance` to evaluate current performance metrics against defined budgets. Run `get_critical_paths` to identify performance-critical functions and hot paths.
+
+2. **Run structural checks.** Execute `harness check-perf --structural` to compute complexity metrics for all changed files:
    - Cyclomatic complexity per function
    - Nesting depth per function
    - File length (lines of code)
    - Parameter count per function
 
-2. **Run coupling checks.** Execute `harness check-perf --coupling` to compute coupling metrics:
+3. **Run coupling checks.** Execute `harness check-perf --coupling` to compute coupling metrics:
    - Fan-in and fan-out per module
    - Afferent and efferent coupling
    - Transitive dependency depth
    - Circular dependency detection
 
-3. **Classify violations by tier:**
+4. **Classify violations by tier:**
    - **Tier 1 (error, block commit):** Cyclomatic complexity > 15, circular dependencies, hotspot in top 5%
    - **Tier 2 (warning, block merge):** Complexity > 10, nesting > 4, fan-out > 10, size budget exceeded
    - **Tier 3 (info, no gate):** File length > 300, fan-in > 20, transitive depth > 30
 
-4. **If Tier 1 violations found,** report them immediately and STOP. Do not proceed to benchmarks. The violations must be fixed first.
+5. **If Tier 1 violations found,** report them immediately and STOP. Do not proceed to benchmarks. The violations must be fixed first.
 
-5. **If no violations found,** proceed to Phase 2.
+6. **If no violations found,** proceed to Phase 2.
 
 ---
 
@@ -83,7 +85,7 @@ This phase runs only when `.bench.ts` files exist in the project. If none are fo
 
 4. **Run benchmarks.** Execute `harness perf bench` to run all benchmark suites.
 
-5. **Load baselines.** Read `.harness/perf/baselines.json` for previous benchmark results. If no baselines exist, treat this as a baseline-capture run.
+5. **Load baselines.** Load existing baselines via `get_perf_baselines` before running new benchmarks. Read `.harness/perf/baselines.json` for previous benchmark results. If no baselines exist, treat this as a baseline-capture run.
 
 6. **Compare results against baselines** using the `RegressionDetector`:
    - Calculate percentage change for each benchmark
@@ -100,7 +102,7 @@ This phase runs only when `.bench.ts` files exist in the project. If none are fo
    - **Tier 2:** >10% regression on a non-critical-path benchmark
    - **Tier 3:** >5% regression on a non-critical-path benchmark (within noise margin consideration)
 
-9. **If this is a baseline-capture run,** report results without regression comparison. Recommend running `harness perf baselines update` to persist.
+9. **If this is a baseline-capture run,** report results without regression comparison. Recommend running `harness perf baselines update` to persist. After benchmarks pass, update baselines via `update_perf_baselines` to record new performance targets.
 
 ---
 

package/dist/agents/skills/claude-code/harness-planning/SKILL.md

@@ -29,6 +29,7 @@ The `rigorLevel` is passed by autopilot (or set via `--fast`/`--thorough` flags)
 | Phase     | `fast`                                             | `standard` (default)                       | `thorough`                                          |
 | --------- | -------------------------------------------------- | ------------------------------------------ | --------------------------------------------------- |
 | SCOPE     | No change.                                         | No change.                                 | No change.                                          |
+| KNOWLEDGE | Skip entirely.                                     | Run detect; fix if gaps found.             | Run detect; fix if gaps found.                      |
 | DECOMPOSE | Skip skeleton. Full tasks directly after file map. | Skeleton if tasks >= 8; full tasks if < 8. | Always skeleton. Require approval before expanding. |
 | SEQUENCE  | No change.                                         | No change.                                 | No change.                                          |
 | VALIDATE  | No change.                                         | No change.                                 | No change.                                          |
@@ -41,7 +42,7 @@ The skeleton pass is the primary rigor lever. Fast mode goes straight to full de
 
 When invoked by autopilot (or with explicit arguments), resolve paths before starting:
 
-1. **Session slug:** If `session-slug` argument provided, set `{sessionDir} = .harness/sessions/<session-slug>/`. Pass to `gather_context({ session: "<session-slug>" })`. All handoff writes go to `{sessionDir}/handoff.json`.
+1. **Session slug:** If `session-slug` argument provided, set `{sessionDir} = .harness/sessions/<session-slug>/`. Pass to `gather_context({ session: "<session-slug>", include: ["state", "learnings", "handoff", "graph", "businessKnowledge", "sessions", "validation"] })`. All handoff writes go to `{sessionDir}/handoff.json`.
 2. **Spec path:** If `spec-path` argument provided, read spec from that path. Otherwise, discover from `{sessionDir}/handoff.json` (read upstream brainstorming output) or prompt the user.
 3. **Rigor level:** If `fast`/`thorough` argument provided, use it. Otherwise default to `standard`.
 
@@ -69,14 +70,16 @@ Work backward from the goal. Start with "what must be true when we are done?"
 
 Store the parsed skill list for use in Phase 2 task annotation.
 
-2. **Derive observable truths.** What can be observed (running a command, opening a browser, reading a file) that proves the goal is met? Be specific:
+2. **Review prior decisions.** Check `decisions` from the prior brainstorming session (loaded via `sessions` in gather_context). Do not re-decide what was already decided — build on those choices.
+
+3. **Derive observable truths.** What can be observed (running a command, opening a browser, reading a file) that proves the goal is met? Be specific:
    - BAD: "The API handles errors"
    - GOOD: "GET /api/users/nonexistent returns 404 with `{ error: 'User not found' }` body"
-3. **Derive required artifacts.** For each truth, what files must exist? What functions? What tests pass? List exact file paths.
-4. **Identify key links.** How do artifacts connect? What imports what? What calls what?
-5. **Apply YAGNI.** For every artifact: "Is this required for an observable truth?" If not, cut it.
+4. **Derive required artifacts.** For each truth, what files must exist? What functions? What tests pass? List exact file paths.
+5. **Identify key links.** How do artifacts connect? What imports what? What calls what?
+6. **Apply YAGNI.** For every artifact: "Is this required for an observable truth?" If not, cut it.
 
-6. **Surface uncertainties.** Before proceeding to Phase 2, explicitly list what you do NOT know. For each uncertainty, classify it:
+7. **Surface uncertainties.** Before proceeding to Phase 2, explicitly list what you do NOT know. For each uncertainty, classify it:
    - **Blocking:** Cannot decompose tasks without resolving this. Escalate to user.
    - **Assumption:** Can proceed with a stated assumption. Document it. If wrong, specific tasks will need revision.
    - **Deferrable:** Does not affect task decomposition. Note for execution phase.
@@ -90,7 +93,7 @@ Store the parsed skill list for use in Phase 2 task annotation.
    - [DEFERRABLE] Exact error message wording. (Can be finalized during implementation.)
    ```
 
-   **Read-only constraint:** Steps 1-5 above are research and analysis. Do not propose task structure, file organization, or implementation approaches during SCOPE. Record what must be true (observable truths) and what you do not know (uncertainties). Solutions belong in DECOMPOSE.
+   **Read-only constraint:** Steps 1-6 above are research and analysis. Do not propose task structure, file organization, or implementation approaches during SCOPE. Record what must be true (observable truths) and what you do not know (uncertainties). Solutions belong in DECOMPOSE.
 
    When scope is ambiguous, use `emit_interaction`:
 
@@ -160,9 +163,39 @@ When a knowledge graph exists at `.harness/graph/`, use graph queries for faster
 
 - `query_graph` — discover module dependencies for realistic task decomposition
 - `get_impact` — estimate which modules a feature touches
+- `compute_blast_radius` — simulate failure propagation from target files to understand scope
+- `predict_failures` — forecast which architectural constraints are at risk from planned changes, informing where extra test coverage or smaller tasks are needed
+- `detect_anomalies` — identify structural irregularities in the affected area before planning tasks around them
 
 Fall back to file-based commands if no graph is available.
 
+### Intelligence Signals (when orchestrator is available)
+
+If the orchestrator is running, request intelligence analysis via `POST /api/analyze` with the feature title/description before decomposing. The pipeline returns:
+
+- **SEL** (Spec Enrichment) — affected systems and blast radius derived from the graph
+- **CML** (Complexity Modeling) — structural, semantic, and historical complexity scores. Use `structuralComplexity > 0.7` to flag areas needing smaller, more cautious tasks.
+- **PESL** (Pre-Execution Simulation) — simulated risk score. Use `riskScore > 0.6` to add extra checkpoints or split risky tasks further.
+
+If no orchestrator, `predict_failures` and `compute_blast_radius` MCP tools provide equivalent directional signals.
+
+---
+
+### Phase 1.5: KNOWLEDGE BASELINE — Materialize Domain Knowledge
+
+Before decomposing into tasks, ensure domain knowledge from PRDs and specs is documented. **Skip this phase** when no PRDs, specs, or business domain documents exist in the project, or when rigor level is `fast`.
+
+1. **Run knowledge pipeline in detect mode.** Execute `harness knowledge-pipeline --domain <feature-domain>` to produce a differential gap report comparing extracted business rules against documented knowledge in `docs/knowledge/`.
+
+2. **If gaps exist and `--fix` is appropriate,** run `harness knowledge-pipeline --fix --domain <feature-domain>` to materialize `docs/knowledge/{domain}/*.md` files from extracted findings. This creates the knowledge baseline from PRDs before any tasks are written.
+
+3. **Cross-check uncertainties against materialized knowledge** (from `businessKnowledge` loaded in gather_context and freshly materialized docs):
+   - Remove "assumptions" from the uncertainty list that are now documented facts in `docs/knowledge/`
+   - Escalate if contradictions exist between PRDs and existing knowledge docs
+   - Use `business_fact` nodes from the graph context to validate domain assumptions
+
+4. **Reference materialized knowledge in Phase 2 task decomposition.** Tasks should reference specific knowledge docs they implement. Observable truths should map back to documented business rules. Use the `businessKnowledge` context (domains, tags, documented facts) loaded in Phase 1 to ground task instructions in verified domain knowledge rather than assumptions.
+
 ---
 
 ### Phase 2: DECOMPOSE — Map File Structure and Create Tasks
@@ -219,11 +252,33 @@ Report progress: `**[Phase 2/4]** DECOMPOSE — mapping file structure and creat
    - `[checkpoint:decision]` — Pause, present options, wait for choice
    - `[checkpoint:human-action]` — Pause, instruct human on required action
 
+7. **Derive integration tasks from the spec's Integration Points section.** If the spec contains an Integration Points section, create tasks for each non-empty integration point. Skip subsections marked "None" — do not derive tasks from them. Integration tasks are normal plan tasks but tagged with `category: "integration"` in their description. They appear at the end of the task list, after all implementation tasks.
+
+   For each subsection of Integration Points, derive tasks:
+
+   | Integration Point                               | Example Derived Task                                                       |
+   | ----------------------------------------------- | -------------------------------------------------------------------------- |
+   | Entry Points: "New CLI command"                 | "Regenerate barrel exports. Verify new command appears in `_registry.ts`." |
+   | Registrations Required: "Skill at tier 2"       | "Add skill to tier list in `AGENTS.md`. Generate slash commands."          |
+   | Documentation Updates: "AGENTS.md capabilities" | "Update AGENTS.md to describe the feature."                                |
+   | Architectural Decisions: "ADR for approach X"   | "Write ADR `docs/knowledge/decisions/NNNN-<slug>.md`."                     |
+   | Knowledge Impact: "Domain concept Y"            | "Enrich knowledge graph with concept node."                                |
+
+   Integration tasks follow the same atomic task rules (2-5 minutes, exact file paths, exact code). Use the `**Category:** integration` tag in the task header, e.g.:
+
+   ```
+   ### Task N: Update AGENTS.md with new feature description
+
+   **Depends on:** Task N-1 | **Files:** `AGENTS.md` | **Category:** integration
+   ```
+
+   If the spec has no Integration Points section, skip this step.
+
 ---
 
 ### Phase 3: SEQUENCE — Order Tasks and Identify Dependencies
 
-1. **Order by dependency.** Types before implementations. Implementations before integrations. Tests alongside implementations (same task, TDD style).
+1. **Order by dependency.** Types before implementations. Implementations before integrations. Integration tasks (tagged `category: "integration"`) after all implementation tasks. Tests alongside implementations (same task, TDD style).
 2. **Identify parallel opportunities.** Tasks touching different subsystems with no shared state can be marked parallelizable.
 3. **Number tasks sequentially.** Use `Task 1`, `Task 2`, etc. Dependencies reference task numbers.
 4. **Estimate total time.** Sum 2-5 minutes per task. If total exceeds available time, identify a milestone boundary for pausing.
@@ -260,7 +315,7 @@ Report progress: `**[Phase 2/4]** DECOMPOSE — mapping file structure and creat
 ```markdown
 # Plan: <Feature Name>
 
-**Date:** YYYY-MM-DD | **Spec:** (if applicable) | **Tasks:** N | **Time:** N min
+**Date:** YYYY-MM-DD | **Spec:** (if applicable) | **Tasks:** N | **Time:** N min | **Integration Tier:** small | medium | large
 
 ## Goal
 
@@ -298,6 +353,18 @@ One sentence.
 [checkpoint:human-verify] ...
 ```
 
+### Integration Tier Heuristics
+
+When a spec contains an **Integration Points** section, set the plan's `integrationTier` field based on scope:
+
+| Tier       | Signal                                                               | Integration Requirements                                                 |
+| ---------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| **small**  | Bug fix, config change, < 3 files, no new exports                    | Wiring checks only (defaults always run)                                 |
+| **medium** | New feature within existing package, new exports, 3-15 files         | Wiring + project updates (roadmap, changelog, graph enrichment)          |
+| **large**  | New package, new skill, new public API surface, architectural change | Wiring + project updates + knowledge materialization (ADRs, doc updates) |
+
+If the spec has no Integration Points section, omit the `integrationTier` field from the plan header.
+
 ## Session State
 
 | Section       | Read | Write | Purpose                                                           |
@@ -311,7 +378,7 @@ One sentence.
 
 **When to write:** Phase 1 — constraints and risks. Phase 2 — decisions about task structure. Phase 4 — resolve questions.
 
-**When to read:** Start of Phase 1 via `gather_context` with `include: ["sessions"]` to inherit brainstorming context.
+**When to read:** Start of Phase 1 via `gather_context` with `include: ["state", "learnings", "handoff", "graph", "businessKnowledge", "sessions", "validation"]` to inherit brainstorming context and load documented business knowledge.
 
 ## Evidence Requirements
 

package/dist/agents/skills/claude-code/harness-refactoring/SKILL.md

@@ -28,9 +28,11 @@ If tests are not green before you start, you are not refactoring — you are deb
 
 2. **Run `harness validate`** and **`harness check-deps`**. Both must pass. You are establishing a clean baseline. If either reports issues, fix those first (that is a separate task, not part of this refactoring).
 
-3. **Identify the refactoring target.** Be specific: which file, function, class, or module? What is wrong with the current structure? What will be better after refactoring?
+3. **Run `compute_blast_radius` on target files** to understand downstream impact before refactoring. This reveals which modules, tests, and consumers will be affected by structural changes.
 
-4. **Plan the steps.** Break the refactoring into the smallest possible individual changes. Each step should be independently committable and verifiable. If you cannot describe a step in one sentence, it is too large.
+4. **Identify the refactoring target.** Be specific: which file, function, class, or module? What is wrong with the current structure? What will be better after refactoring?
+
+5. **Plan the steps.** Break the refactoring into the smallest possible individual changes. Each step should be independently committable and verifiable. If you cannot describe a step in one sentence, it is too large.
 
 ### Graph-Enhanced Context (when available)
 
@@ -81,6 +83,10 @@ For EACH step in the plan:
 
 2. **Run `harness validate` and `harness check-deps` one final time.** Clean output.
 
+3. **Run `detect_stale_constraints`** to verify architectural constraints are still valid after structural changes. Refactoring can render existing constraints obsolete or misaligned.
+
+4. **Run `check_traceability`** to confirm refactoring didn't break requirement-to-implementation mappings. Moved or renamed code may orphan traceability links.
+
 ### Graph Refresh
 
 If a knowledge graph exists at `.harness/graph/`, refresh it after code changes to keep graph queries accurate:
@@ -91,9 +97,9 @@ harness scan [path]
 
 Skipping this step means subsequent graph queries (impact analysis, dependency health, test advisor) may return stale results.
 
-3. **Review the cumulative diff.** Does the final state match the intended improvement? Is the code genuinely better, or just different?
+5. **Review the cumulative diff.** Does the final state match the intended improvement? Is the code genuinely better, or just different?
 
-4. **If the refactoring introduced no improvement,** revert the entire sequence. Refactoring for its own sake is churn.
+6. **If the refactoring introduced no improvement,** revert the entire sequence. Refactoring for its own sake is churn.
 
 ## Common Refactoring Patterns
 
@@ -133,6 +139,9 @@ Skipping this step means subsequent graph queries (impact analysis, dependency h
 - **`harness check-deps`** — Run after each step, especially when moving code between files or layers. Catches dependency violations introduced by structural changes.
 - **`harness check-docs`** — Run after renaming or moving public APIs. Catches documentation that references old names or locations.
 - **`harness cleanup`** — Run after completing a refactoring sequence. Detects dead code that the refactoring may have created (unused exports, orphaned files).
+- **`compute_blast_radius`** — Run in Phase 1 PREPARE before making changes. Reveals downstream impact of target files so you understand what the refactoring will affect.
+- **`detect_stale_constraints`** — Run in Phase 3 VERIFY after refactoring. Checks whether architectural constraints are still valid after structural changes.
+- **`check_traceability`** — Run in Phase 3 VERIFY after refactoring. Confirms requirement-to-implementation mappings were not broken by moved or renamed code.
 
 ## Success Criteria
 

package/dist/agents/skills/claude-code/harness-security-scan/SKILL.md

@@ -34,7 +34,9 @@
    - `warning`: errors and warnings (default)
    - `info`: all findings
 
-6. **Output report.** Present findings grouped by severity:
+6. **Check security trends.** Check `get_security_trends` to compare current scan results against the project's security posture history and identify trajectory changes.
+
+7. **Output report.** Present findings grouped by severity:
 
    ```
    Security Scan: [PASS/FAIL]

package/dist/agents/skills/claude-code/harness-soundness-review/SKILL.md

@@ -47,6 +47,10 @@ Every finding conforms to this structure:
 
 Execute all checks for the active mode. Classify each finding as `autoFixable: true` or `false`. Record total issue count.
 
+#### Traceability and Cross-Check Tools
+
+Run `check_traceability` to verify that all requirements in the spec/plan have corresponding implementation artifacts. Run `validate_cross_check` to verify plan-to-implementation alignment as part of the soundness assessment.
+
 #### Graph Detection and Fallback
 
 Before running checks, determine graph availability:

package/dist/agents/skills/claude-code/harness-tdd/SKILL.md

@@ -71,9 +71,11 @@ If you find yourself writing production code first, STOP. Delete it. Write the t
 
 2. **Run `harness validate`** to verify the full project health. This catches architectural drift, documentation gaps, and constraint violations.
 
-3. **If either check fails,** fix the issue before committing. The fix may require another RED-GREEN-REFACTOR cycle if it involves behavioral changes.
+3. **Run `check_traceability`** to verify new tests map to specific requirements, ensuring test coverage aligns with spec expectations. This catches tests that exist in isolation without a traced requirement.
 
-4. **Commit the cycle.** Each RED-GREEN-REFACTOR-VALIDATE cycle produces one atomic commit. The commit message references what behavior was added (not "add test" — describe the behavior).
+4. **If any check fails,** fix the issue before committing. The fix may require another RED-GREEN-REFACTOR cycle if it involves behavioral changes.
+
+5. **Commit the cycle.** Each RED-GREEN-REFACTOR-VALIDATE cycle produces one atomic commit. The commit message references what behavior was added (not "add test" — describe the behavior).
 
 ### Graph Refresh
 
@@ -111,6 +113,7 @@ Repeat the 4 phases for each new behavior. A typical feature requires 3-10 cycle
 - **`harness check-deps`** — Run in VALIDATE phase after each cycle. Catches forbidden imports and layer boundary violations introduced by new code.
 - **`harness validate`** — Run in VALIDATE phase after each cycle. Full project health check including architecture, documentation, and constraints.
 - **`harness cleanup`** — Run periodically (every 3-5 cycles) to detect entropy accumulation. Address any issues before they compound.
+- **`check_traceability`** — Run in VALIDATE phase after tests are written. Verifies new tests map to specific requirements so test coverage aligns with spec expectations.
 - **Test runner** — Use the project's configured test runner. Harness does not prescribe a test framework but the test must actually execute and report results.
 
 ## Success Criteria

package/dist/agents/skills/claude-code/harness-verification/SKILL.md

@@ -386,6 +386,10 @@ Task: "Create UserService with CRUD operations."
 - **`harness check-deps`** -- Run during Level 3 (WIRED) to verify dependency boundaries.
 - **`harness check-docs`** -- Verify documentation updated for new artifacts. Missing docs for public APIs is a gap.
 - **Test runner** -- Must be run fresh (not cached) during Level 3. Read actual output, check exit codes.
+- **`check_traceability`** -- Run during Level 3 (WIRED) to verify every requirement in the spec maps to at least one implemented artifact and test.
+- **`validate_cross_check`** -- Run after Level 3 against the plan to verify implementation matches planned file map and task descriptions.
+- **`check_phase_gate`** -- Run before producing the verification report to validate the current phase meets all gate criteria before marking complete.
+- **`detect_anomalies`** -- Run during the Anti-Pattern Scan to identify structural inconsistencies (orphaned files, missing tests, unusual coupling) introduced during execution.
 - **`emit_interaction`** -- Auto-transition to harness-code-review on PASS verdict only.
 - **Session directory** -- `.harness/sessions/<slug>/` contains `handoff.json`, `state.json`, `artifacts.json` (spec path, plan path, file lists from execution). Do not write to global `.harness/handoff.json` when session slug is known.
 

package/dist/agents/skills/codex/cleanup-dead-code/SKILL.md

@@ -26,7 +26,9 @@
 
 2. **Run `harness cleanup --type dead-code --json`** for machine-readable output focused specifically on unused code.
 
-3. **Review the report summary.** Note the total count and distribution. A few dead exports are normal; dozens suggest accumulated entropy from incomplete refactorings.
+3. **Check for stale constraints.** Run `detect_stale_constraints` to identify architectural constraints referencing removed code that should also be cleaned up.
+
+4. **Review the report summary.** Note the total count and distribution. A few dead exports are normal; dozens suggest accumulated entropy from incomplete refactorings.
 
 ### Graph-Enhanced Context (when available)
 

package/dist/agents/skills/codex/detect-doc-drift/SKILL.md

@@ -20,7 +20,9 @@
 
 2. **Run `harness cleanup --type drift`** for a deeper analysis that cross-references code changes against documentation references.
 
-3. **Optionally, run `git diff` against a baseline** (last release, last sprint, etc.) to identify which code files changed. This helps prioritize — docs for recently changed files are most likely to be drifted.
+3. **Check for stale constraints.** Run `detect_stale_constraints` alongside drift detection to find architectural constraints that no longer match the codebase.
+
+4. **Optionally, run `git diff` against a baseline** (last release, last sprint, etc.) to identify which code files changed. This helps prioritize — docs for recently changed files are most likely to be drifted.
 
 ### Graph-Enhanced Context (when available)
 

package/dist/agents/skills/codex/harness-architecture-advisor/SKILL.md

@@ -53,6 +53,10 @@ Store answers in: .harness/architecture/<topic>/discovery.md
 
 Read the codebase to understand the current state. Do not propose solutions yet — gather facts.
 
+#### Step 0: Discover Constraints and Trends
+
+Run `detect_constraint_emergence` to discover implicit architectural patterns that should be formalized as constraints. Run `detect_stale_constraints` to identify constraints that no longer apply or need updating. Check `get_decay_trends` to understand how architectural health has evolved and which areas are degrading fastest. Run `predict_failures` to forecast which constraints are most likely to be violated based on current trends.
+
 #### Step 1: Map Existing Patterns
 
 Search for how the codebase currently handles similar concerns:

package/dist/agents/skills/codex/harness-autopilot/SKILL.md

@@ -12,12 +12,13 @@
 
 ## Persona Agents
 
-| Skill                | `subagent_type`         | State(s)             |
-| -------------------- | ----------------------- | -------------------- |
-| harness-planning     | `harness-planner`       | PLAN                 |
-| harness-execution    | `harness-task-executor` | EXECUTE              |
-| harness-verification | `harness-verifier`      | VERIFY               |
-| harness-code-review  | `harness-code-reviewer` | REVIEW, FINAL_REVIEW |
+| Skill                   | `subagent_type`         | State(s)             |
+| ----------------------- | ----------------------- | -------------------- |
+| harness-planning        | `harness-planner`       | PLAN                 |
+| harness-execution       | `harness-task-executor` | EXECUTE              |
+| harness-verification    | `harness-verifier`      | VERIFY               |
+| **harness-integration** | **`harness-verifier`**  | **INTEGRATE**        |
+| harness-code-review     | `harness-code-reviewer` | REVIEW, FINAL_REVIEW |
 
 **Iron Law:** Autopilot delegates, never reimplements. If writing plan/execute/verify/review logic, STOP — delegate via `subagent_type`. Always use dedicated persona agents, never general-purpose agents.
 
@@ -31,15 +32,16 @@ Set at INIT (`--fast` / `--thorough`); persists for session. Default: `standard`
 | APPROVE_PLAN | Auto-approve, skip signals | Signal-based          | Force human review            |
 | EXECUTE      | Skip scratchpad            | Scratchpad >500 words | Verbose scratchpad            |
 | VERIFY       | `harness validate` only    | Full pipeline         | Expanded checks               |
+| INTEGRATE    | WIRE only, auto-approve    | Full tier-appropriate | Full + human ADR review       |
 
 ## State Machine
 
 ```
-INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW → PHASE_COMPLETE
-                                                                    │
-                                                             [next phase?]
-                                                              │           │
-                                                           ASSESS   FINAL_REVIEW → DONE
+INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → INTEGRATE → REVIEW → PHASE_COMPLETE
+                                                                                  │
+                                                                           [next phase?]
+                                                                            │           │
+                                                                         ASSESS   FINAL_REVIEW → DONE
 ```
 
 ---
@@ -51,7 +53,7 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 3. Check for existing state: read `{sessionDir}/autopilot-state.json`. If present and not DONE: report "Resuming from `{currentState}`, phase {N}: {name}." Apply schema migration if `schemaVersion < 5` (backfill missing fields). Jump to recorded state.
 4. Fresh start: read spec, parse `## Implementation Order` for phases (`### Phase N: Name` + `<!-- complexity: low|medium|high -->`, default: `medium`). Capture `startingCommit` via `git rev-parse HEAD`. Write `autopilot-state.json` (schemaVersion: 5, currentState: "ASSESS", currentPhase: 0).
 5. Flags: `--fast` → `rigorLevel: "fast"`. `--thorough` → `rigorLevel: "thorough"`. `--review-plans` → `reviewPlans: true`. Both flags together → reject with error.
-6. Call `gather_context({ path, skill: "harness-autopilot", session: slug, include: ["state", "learnings", "handoff", "validation"] })`.
+6. Call `gather_context({ path, skill: "harness-autopilot", session: slug, include: ["state", "learnings", "handoff", "graph", "businessKnowledge", "sessions", "validation"] })`.
 7. → ASSESS.
 
 ---
@@ -60,10 +62,15 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 1. Read current phase at `currentPhase`.
 2. If `planPath` set and file exists: → APPROVE_PLAN.
-3. Complexity routing:
+3. **Intelligence-enhanced complexity assessment.** Before routing by complexity, refine the annotation with signals from available tools:
+   - Run `predict_failures` on the phase domain to check if constraints are trending toward violation — high failure probability suggests upgrading complexity.
+   - Run `compute_blast_radius` on files the phase is likely to touch — large blast radius (>15 affected modules) suggests upgrading to `high`.
+   - If the orchestrator is running, request intelligence analysis via `POST /api/analyze` with the phase title/description to get CML complexity scores and PESL simulation results. Use CML `structuralComplexity > 0.7` or PESL `riskScore > 0.6` as triggers to upgrade complexity routing.
+   - If no orchestrator, the MCP tool signals above are sufficient.
+4. Complexity routing:
    - `low`/`medium`: auto-plan via harness-planner → PLAN.
    - `high`: pause. Instruct: "Run `/harness:planning` interactively, then re-invoke `/harness:autopilot`." Wait for re-invocation.
-4. Update `currentState: "PLAN"`.
+5. Update `currentState: "PLAN"`.
 
 ---
 
@@ -93,6 +100,7 @@ On return: read `planPath` from `{sessionDir}/handoff.json`. Complexity override
    - `phase.complexityOverride !== null`
    - Handoff `concerns` non-empty
    - Task count > 15
+   - Knowledge gaps: `harness knowledge-pipeline --domain <phase-domain>` reports `totalGaps > 0` and `--fix` was not run during planning
 5. **Auto-approve:** emit report (mode, complexity, concerns, task count). Record decision with signal snapshot in `decisions[]`. → EXECUTE.
 6. **Pause:** show triggered signals. Ask "Approve? (yes / revise / skip phase / stop)." Record decision. Route accordingly.
 
@@ -120,13 +128,34 @@ prompt: "Phase {N}: {name}. Plan: {planPath}. Session: {sessionSlug}. Rigor: {ri
 
 ### VERIFY
 
-- `"fast"`: run `harness validate`. Pass → REVIEW. Fail → surface to user.
+- `"fast"`: run `harness validate`. Pass → INTEGRATE. Fail → surface to user.
 - `"standard"`/`"thorough"`: dispatch harness-verifier:
   ```
   subagent_type: "harness-verifier"
   prompt: "Phase {N}: {name}. Session: {sessionSlug}. Rigor: {rigorLevel}. Verify and report pass/fail with findings."
   ```
-  Pass → REVIEW. Fail → ask "fix / skip verification / stop." `fix`: re-enter EXECUTE (retry budget resets).
+  Pass → INTEGRATE. Fail → ask "fix / skip verification / stop." `fix`: re-enter EXECUTE (retry budget resets).
+
+---
+
+### INTEGRATE
+
+1. Resolve tier: `max(plan.integrationTier, derived-from-execution)`. If tier escalated: notify human with "Tier escalated from `{planned}` to `{derived}`: {reason}."
+2. Dispatch harness-integration skill:
+   ```
+   subagent_type: "harness-verifier"
+   prompt: "Phase {N}: {name}. Session: {sessionSlug}. Tier: {tier}.
+            Plan: {planPath}. Verify integration per harness-integration skill."
+   ```
+3. **Rigor interaction:**
+   - `"fast"`: WIRE sub-phase only, auto-approve, no ADR drafting.
+   - `"standard"`: Full tier-appropriate checks (WIRE + MATERIALIZE + UPDATE per tier).
+   - `"thorough"`: Full checks + human reviews every ADR draft + force knowledge graph verification.
+4. Pass → REVIEW.
+5. Fail → report incomplete items. Ask "fix / skip integration / stop":
+   - **fix:** re-enter EXECUTE with integration-specific fix tasks, then re-VERIFY, re-INTEGRATE. Retry budget resets.
+   - **skip:** record decision in `decisions[]`, proceed to REVIEW (human override).
+   - **stop:** save state and exit.
 
 ---
 
@@ -145,8 +174,8 @@ Persist findings to `{sessionDir}/phase-{N}-review.json`. No blocking → PHASE_
 
 ### PHASE_COMPLETE
 
-1. Present summary: name, tasks completed, retries used, verification result, review findings count, elapsed time.
-2. Record in `history[]`: phase index, name, startedAt, completedAt, tasksCompleted, retriesUsed, verificationPassed, reviewFindings.
+1. Present summary: name, tasks completed, retries used, verification result, integration report (`{sessionDir}/phase-{N}-integration.json`), review findings count, elapsed time.
+2. Record in `history[]`: phase index, name, startedAt, completedAt, tasksCompleted, retriesUsed, verificationPassed, integrationPassed, reviewFindings.
 3. Mark phase `complete` in state. Clear scratchpad: `clearScratchpad({ session, phase, projectPath })`.
 4. Sync roadmap: `manage_roadmap sync apply:true` (skip if no roadmap; never `force_sync: true`).
 5. Write session summary: `writeSessionSummary(projectPath, sessionSlug, { session, lastActive, skill: "harness-autopilot", phase, status, spec, plan, keyContext, nextStep })`.
@@ -188,9 +217,11 @@ Persist findings to `{sessionDir}/phase-{N}-review.json`. No blocking → PHASE_
 2. **ASSESS** — Route by complexity: low/medium auto-plans, high pauses for interactive planning.
 3. **PLAN → APPROVE** — Dispatch harness-planner, check approval signals, auto-approve or pause.
 4. **EXECUTE** — Dispatch harness-task-executor with plan path, handle checkpoints and retries (max 3).
-5. **VERIFY → REVIEW** — Dispatch harness-verifier and harness-code-reviewer, fix blocking findings.
-6. **PHASE_COMPLETE** — Summarize, sync roadmap, loop to ASSESS for next phase or proceed to FINAL_REVIEW.
-7. **FINAL_REVIEW → DONE** — Cross-phase review, offer PR creation, write final handoff.
+5. **VERIFY** — Dispatch harness-verifier, confirm code correctness and wiring.
+6. **INTEGRATE** — Resolve integration tier, dispatch harness-integration, verify system wiring, knowledge materialization, and documentation per tier.
+7. **REVIEW** — Dispatch harness-code-reviewer, fix blocking findings.
+8. **PHASE_COMPLETE** — Summarize (including integration report), sync roadmap, loop to ASSESS for next phase or proceed to FINAL_REVIEW.
+9. **FINAL_REVIEW → DONE** — Cross-phase review, offer PR creation, write final handoff.
 
 ---
 
@@ -205,9 +236,9 @@ Persist findings to `{sessionDir}/phase-{N}-review.json`. No blocking → PHASE_
 
 ## Gates
 
-- **No reimplementing delegated skills.** Writing planning/execution/verification/review logic → STOP. Delegate via `subagent_type`.
+- **No reimplementing delegated skills.** Writing planning/execution/verification/review/integration logic → STOP. Delegate via `subagent_type`.
 - **No executing without plan approval.** Every plan passes APPROVE_PLAN. No exceptions.
-- **No skipping VERIFY or REVIEW.** Human can override findings; steps cannot be skipped.
+- **No skipping VERIFY, INTEGRATE, or REVIEW.** Human can override findings; steps cannot be skipped. INTEGRATE may be skipped only via explicit "skip" choice with decision recorded in `decisions[]`.
 - **No infinite retries.** EXECUTE budget: 3 attempts. FINAL_REVIEW: 3 cycles. If exhausted, stop and surface.
 - **No modifying state files manually.** If corrupted, start fresh.
 
@@ -231,7 +262,7 @@ Persist findings to `{sessionDir}/phase-{N}-review.json`. No blocking → PHASE_
 
 ## Success Criteria
 
-- All phases in the spec are executed in order with plan → execute → verify → review per phase
+- All phases in the spec are executed in order with plan → execute → verify → integrate → review per phase
 - Every plan approval is recorded in `decisions[]` (auto or manual)
 - Retry budget (3 attempts) is enforced — exhausted retries surface to user, never silently continue
 - FINAL_REVIEW runs on `startingCommit..HEAD` diff and catches cross-phase coherence issues

package/dist/agents/skills/codex/harness-brainstorming/SKILL.md

@@ -35,10 +35,11 @@ When no arguments are provided (standalone invocation), the skill operates exact
 
 ### Phase 1: EXPLORE -- Gather Context
 
-1. **Read the existing codebase.** Understand architecture, constraints, and conventions. Check AGENTS.md, existing specs in `docs/`, and relevant source files.
-2. **Identify the problem boundary.** What exactly needs solving? What is out of scope? Write both down.
-3. **Check for prior art.** Has this been partially solved elsewhere? Are there patterns to follow or deliberately break?
-4. **Assess scope.** If the problem spans >3 major subsystems or >2 weeks to implement, decompose into sub-projects first.
+1. **Load project context.** Call `gather_context({ path: "<project-root>", intent: "<feature description>", skill: "harness-brainstorming", session: "<session-slug-if-known>", include: ["graph", "businessKnowledge", "sessions", "validation"] })`. The `graph` context surfaces `business_fact` nodes relevant to the feature domain. The `businessKnowledge` context loads documented domain knowledge from `docs/knowledge/`. Use both to ground exploration in verified facts rather than assumptions.
+2. **Read the existing codebase.** Understand architecture, constraints, and conventions. Check AGENTS.md, existing specs in `docs/`, and relevant source files.
+3. **Identify the problem boundary.** What exactly needs solving? What is out of scope? Write both down. Cross-reference `businessKnowledge` domains — if documented business rules constrain the problem, note them.
+4. **Check for prior art.** Has this been partially solved elsewhere? Are there patterns to follow or deliberately break?
+5. **Assess scope.** If the problem spans >3 major subsystems or >2 weeks to implement, decompose into sub-projects first.
 
 ---
 
@@ -107,9 +108,19 @@ These flow into `handoff.json` `contextKeywords` field. Select keywords that hel
    - Overview and goals
    - Decisions made (with rationale from brainstorming)
    - Technical design (data structures, APIs, file layout)
+   - Integration points (entry points, registrations, docs, decisions, knowledge impact)
    - Success criteria (observable, testable outcomes)
    - Implementation order (high-level phases, not detailed tasks)
 
+   The **Integration Points** section is required in every spec. It defines how the feature connects to the existing system. Populate it with five subsections:
+   - **Entry Points** -- Which system entry points does this feature touch or create? (e.g., new CLI command, new MCP tool, new skill, new API route, new barrel export)
+   - **Registrations Required** -- What registrations are needed for the feature to be discoverable? (e.g., barrel export regeneration, skill tier assignment, route registration)
+   - **Documentation Updates** -- What docs need updating to reflect the new capability? (e.g., AGENTS.md section, API docs, README, guides)
+   - **Architectural Decisions** -- What decisions warrant ADRs? List the decision and a one-line rationale. Only for medium/large tier changes -- omit for small changes.
+   - **Knowledge Impact** -- What domain concepts, patterns, or relationships should enter the knowledge graph?
+
+   If the feature is a small change (bug fix, config tweak, < 3 files), the section may contain only Entry Points and Registrations Required with "None" for the others. The section must still be present.
+
 2. **Run soundness review.** Invoke `harness-soundness-review --mode spec` against the draft. Do not write to `docs/` until the review converges with no remaining issues.
 
 3. **Write the spec** to `docs/changes/<feature>/proposal.md`.
@@ -308,7 +319,7 @@ Apply when output includes specific behavioral expectations.
 
 ## Success Criteria
 
-- Spec exists in `docs/` with all required sections (overview, decisions, technical design, success criteria, implementation order)
+- Spec exists in `docs/` with all required sections (overview, decisions, technical design, integration points, success criteria, implementation order)
 - Human explicitly approved before any implementation
 - YAGNI applied: no speculative features in the spec
 - 2-3 approaches presented with honest tradeoffs before decision