@harness-engineering/cli 2.8.0 → 3.0.1

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

@@ -136,7 +136,7 @@ These flow into `handoff.json` `contextKeywords` field. Select keywords that hel
    - **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.
+   - **Architectural Decisions** -- Which decisions from the **Decisions made** section rise to a standalone ADR? Reference each by name with a one-line note on _why_ it warrants an ADR. Do **not** restate the decisions here -- this subsection points back to the canonical **Decisions made** section; duplicating them creates two sources that drift (spec-craft flags this as SPEC-R004). Only for medium/large tier changes -- "None" 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.
@@ -186,21 +186,35 @@ These flow into `handoff.json` `contextKeywords` field. Select keywords that hel
 
    The human must explicitly approve before this skill is complete.
 
-7. **Commit spec artifacts.** After approval, commit the spec and skill recommendations so the paper trail enters git history at sign-off rather than retroactively:
+7. **Promote the roadmap row.** If `docs/roadmap.md` exists, transition the named row to `planned` and link the spec in a single structured call (steps 7 and 8 are intentionally ordered so the commit captures the roadmap mutation). Skip silently only when no roadmap exists.
+   - Derive the lookup key from the slash-command `ARGUMENTS` string (D1). Derive the summary from the spec title (the H1 heading).
+   - Call `manage_roadmap` with action `promote`, `feature: "<ARGUMENTS>"`, `spec: "docs/changes/<feature>/proposal.md"`, and `summary: "<H1>"`.
+   - Branch on the returned `PromoteResult` envelope:
+
+     | Envelope                                    | Skill behavior                                                                                                                                                     |
+     | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+     | `ok: true, transitioned: 'backlog→planned'` | Log "Promoted `<feature>`: backlog → planned". Continue to step 8.                                                                                                 |
+     | `ok: true, transitioned: 'spec-updated'`    | Log "Updated spec link for `<feature>` (status preserved)". Continue to step 8.                                                                                    |
+     | `ok: true, transitioned: 'noop'`            | Log "No change — `<feature>` already promoted with this spec". Continue to step 8.                                                                                 |
+     | `ok: false, reason: 'in-progress'`          | **STOP.** Surface: "Refused to promote `<feature>`: an agent is currently dispatched against this row. Stop the agent or use a different feature name."            |
+     | `ok: false, reason: 'done'`                 | **STOP.** Surface: "Refused to promote `<feature>`: row is already 'done'. To revise a shipped feature, use a new name."                                           |
+     | `ok: false, reason: 'not-found'`            | If no row was expected to exist, fall through to a `created` outcome. Otherwise surface `closestMatches` as a typo hint and **STOP**.                              |
+     | `ok: false, reason: 'ambiguous'`            | **STOP.** Surface: "Refused to promote `<feature>`: matches multiple rows across milestones. Re-invoke with one of: `<matches>`." Matches are milestone-qualified. |
+     | `ok: false, reason: 'write-failed'`         | **STOP.** Surface `detail` verbatim. The brainstorm is not considered complete.                                                                                    |
+
+   - The `not-found` create path: when the row genuinely does not exist yet, call `manage_roadmap` action `add` with `status: "planned"`, `milestone: "Current Work"`, the spec path, and the H1 summary (unchanged from the legacy behavior), then continue to step 8.
+   - "STOP" cases skip step 8 (no commit) and step 9 (no handoff/transition). The spec file written in step 3 stays on disk; the user re-runs the skill after resolving the conflict.
+   - If `manage_roadmap` is unavailable, fall back to `parseRoadmap`/`promoteFeature`/`serializeRoadmap` from core. Warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored."
+   - If no roadmap exists, skip silently (no envelope) and continue to step 8; the commit then contains only the spec files.
+
+8. **Commit spec artifacts and roadmap promotion.** After a successful promote (or a silent skip when no roadmap exists), commit the spec, skill recommendations, and the roadmap mutation together so the promotion ships atomically with the spec:
 
    ```bash
-   git add docs/changes/<feature>/proposal.md docs/changes/<feature>/SKILLS.md
-   git commit -m "docs(<feature>): add spec"
+   git add docs/changes/<feature>/proposal.md docs/changes/<feature>/SKILLS.md docs/roadmap.md
+   git commit -m "docs(<feature>): add spec and promote to planned"
    ```
 
-   Do not skip this step. `harness-execution` commits only implementation files, so a spec uncommitted here stays untracked until someone notices. If a pre-commit hook reformats either file, re-add and re-commit.
-
-8. **Add feature to roadmap.** If `docs/roadmap.md` exists:
-   - Derive feature name from the spec title (the H1 heading).
-   - Call `manage_roadmap` with action `add`, `status: "planned"`, `milestone: "Current Work"`, and the spec path.
-   - If the feature already exists, skip silently.
-   - If `manage_roadmap` is unavailable, fall back to `parseRoadmap`/`serializeRoadmap` from core. Warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored."
-   - If no roadmap exists, skip silently.
+   Include `docs/roadmap.md` in `git add` only when it exists; omit it when the project has no roadmap. Do not skip this step — `harness-execution` commits only implementation files, so a spec uncommitted here stays untracked until someone notices. If a pre-commit hook reformats a file, re-add and re-commit.
 
 9. **Write handoff and suggest transition.** After approval:
 
@@ -336,8 +350,8 @@ Technical claims about existing code, architecture, or tradeoffs MUST cite evide
 - **Spec location** -- `docs/changes/<feature>/proposal.md`.
 - **Handoff** -- Once approved, invoke harness-planning to create the implementation plan.
 - **Session directory** — When session slug is known, handoff goes to `.harness/sessions/<slug>/handoff.json`. The session directory structure is: `handoff.json`, `state.json`, `artifacts.json` (registry of spec/plan paths and file lists). Do not write to `.harness/handoff.json` in session context.
-- **Spec commit** -- After sign-off (Phase 4 Step 7), commit `docs/changes/<feature>/proposal.md` and `docs/changes/<feature>/SKILLS.md` so the spec enters git history at approval, not retroactively. `harness-execution` does not backfill these — see issue #487.
-- **Roadmap sync** -- After approval, call `manage_roadmap` action `add` to register as `planned`. Skip silently if no roadmap. Duplicates ignored.
+- **Spec commit** -- After sign-off, the Phase 4 step 8 commit captures `docs/changes/<feature>/proposal.md`, `docs/changes/<feature>/SKILLS.md`, and the promoted `docs/roadmap.md` together so the spec enters git history at approval, not retroactively. `harness-execution` does not backfill these — see issue #487.
+- **Roadmap promotion** -- After approval (Phase 4 step 7), call `manage_roadmap` action `promote` to transition the named row to `planned` and link the spec atomically with the spec commit. Falls back to `add` (create new row) when the row does not exist; refuses on `in-progress`/`done`/`ambiguous`. Skip silently if no roadmap.
 - **`emit_interaction`** -- End of Phase 4 to suggest transition to harness-planning (confirmed transition).
 
 #### Requirement Phrasing

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

@@ -56,7 +56,7 @@ When no arguments are provided (standalone invocation), discover plan from `docs
 4. **Load session summary for cold start.** If resuming (session slug known):
    - Call `listActiveSessions()` to read the session index.
    - Call `loadSessionSummary()` for the target session.
-   - If ambiguous, present the index and ask which session to resume.
+   - If ambiguous, present the index and ask which session to resume. Ask in plain text — do not elevate this to `AskUserQuestion` (the session index can exceed its 4-option cap and a natural header like "Pick session" can exceed its 12-char cap, rendering the call as ERR).
 
 5. **Check for known dead ends.** Review `learnings` tagged `[outcome:failure]`. Warn if any match current plan approaches.
 

package/dist/agents/skills/codex/harness-git-workflow/SKILL.md

@@ -13,6 +13,8 @@
 
 ## Process
 
+**Prompt the human in plain text** — every choice and destructive confirmation in this skill (worktree location, discard-experiment, etc.) is plain text only. Do not elevate to `AskUserQuestion`: option labels like the A/B/C worktree-location choices and natural headers like "Discard commits" routinely exceed its 4-option / 12-char caps and render as ERR.
+
 ### Part A: Worktree Creation
 
 #### Step 1: Choose Worktree Location

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

@@ -15,6 +15,8 @@
 
 ## Process
 
+**Prompt the human in plain text** — every confirmation and selection in this skill (`Proceed? (y/n)`, post-critique selection, etc.) is plain text only. Do not elevate to `AskUserQuestion`: natural headers like "Confirm inputs" exceed its 12-char cap and option lists routinely exceed its 4-option cap, rendering the call as ERR.
+
 ### Iron Law
 
 **The skill produces exactly ONE ranked artifact per run, at `docs/ideation/<slug>-YYYY-MM-DD.md`, and NEVER produces a spec, plan, ADR, or code.** If the user wants a spec from a ranked idea, they invoke `harness-brainstorming` next — that is the contract.

package/dist/agents/skills/codex/harness-knowledge-pipeline/SKILL.md

@@ -14,6 +14,8 @@
 
 ## Process
 
+**Prompt the human in plain text** — every confirmation, drift acknowledgement, and contradiction resolution in this skill is plain text only. Do not elevate to `AskUserQuestion`: source labels and finding descriptions routinely exceed its 4-option / 12-char caps, rendering the call as ERR.
+
 1. **EXTRACT:** Run code signal extractors, diagram parsers, BusinessKnowledgeIngestor, and KnowledgeLinker against the project
 2. **RECONCILE:** Build pre-extraction snapshot (current graph state) and post-extraction snapshot, then run StructuralDriftDetector
 3. **DETECT:** Partition findings by classification (new/stale/drifted/contradicting), generate gap report

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

@@ -9,6 +9,7 @@
 - When adding a new feature to an existing roadmap (`--add <feature-name>`)
 - When roadmap statuses may be stale and need updating from plan execution state (`--sync`)
 - When features need reordering, moving between milestones, or blocker updates (`--edit`)
+- When the roadmap needs tidying -- completed work archived, dead `planned` rows demoted (`--groom`)
 - When user asks about project status and no roadmap exists -- suggest `--create`
 - NOT for programmatic CRUD (use `manage_roadmap` MCP tool directly)
 
@@ -20,6 +21,8 @@
 
 If the human has not seen and approved the milestone groupings and feature list, do not write the file. Present. Wait. Confirm. Then write.
 
+**Prompt the human in plain text — every `(y/n)`, "which feature?", and similar prompt in this skill is plain text only.** Do not elevate them to `AskUserQuestion`: feature lists routinely exceed its 4-option cap, and natural header choices ("Pick feature", "Remove feature") exceed its 12-char cap, causing the call to render as ERR.
+
 ---
 
 ### Command: `--create` -- Bootstrap Roadmap
@@ -428,12 +431,67 @@ Choice?
 
 ---
 
+### Command: `--groom` -- Tidy the Roadmap
+
+Keeps the roadmap manageable over time. **Milestones are themes; statuses are lifecycle stages** -- grooming enforces that separation so the backlog never decays back into an undifferentiated dump.
+
+#### Phase 1: SCAN -- Detect Untidiness
+
+1. Check if `docs/roadmap.md` exists. If missing: error and direct the user to `--create`.
+2. Run `manage_roadmap` (`action: "groom"`) in a dry-run frame, or call `checkRoadmapHealth` from `@harness-engineering/core`, to surface the four health signals:
+   - **RMH001** -- completed (`done`) features still sitting in an active milestone.
+   - **RMH002** -- `planned` rows with neither a spec nor a plan (the orchestrator cannot auto-execute these; it escalates them to a human).
+   - **RMH003** -- lifecycle catch-all milestones (`Backlog`, `Current Work`) that should not exist.
+   - **RMH004** -- active milestones that have grown past the size cap (a mini-dump).
+
+#### Phase 2: PROPOSE -- Present the Plan
+
+Show the human exactly what grooming will do, in plain text:
+
+```
+GROOM PLAN
+
+Demote to backlog (planned with no spec/plan):
+  - Feature A (Theme X)
+  - Feature B (Theme Y)
+
+Archive to docs/roadmap-archive.md (completed):
+  - Feature C (Theme X)
+
+Flagged for manual routing (not auto-changed):
+  - Intake lane has 3 items awaiting a theme
+  - "Theme Z" has 28 features (cap 25) -- consider splitting
+
+Apply? (y/n)
+```
+
+Wait for confirmation. The mechanical changes (demote, archive) are safe and automated; **draining the Intake lane into themed milestones and splitting oversized milestones are human decisions** -- propose, do not auto-apply.
+
+#### Phase 3: WRITE -- Apply
+
+1. Run `manage_roadmap` (`action: "groom"`). It demotes unactionable `planned` rows to `backlog` and moves `done` features into `docs/roadmap-archive.md` under a `Shipped` milestone, returning the list of changes.
+2. For Intake-draining or milestone-splitting the human approved, follow up with `--edit` (move features between milestones).
+
+#### Phase 4: VALIDATE -- Verify
+
+1. Run `harness validate` and confirm the `roadmapHealth` check passes (no RMH003 errors; RMH001/002/004 warnings cleared or acknowledged).
+2. Summarize:
+
+   ```
+   Groom complete.
+   Demoted: N | Archived: N -> docs/roadmap-archive.md | Flagged for manual routing: N
+   harness validate (roadmapHealth): passed
+   ```
+
+---
+
 ## Harness Integration
 
-- **`manage_roadmap` MCP tool** -- Primary read/write interface for roadmap operations. Supports `show`, `add`, `update`, `remove`, and `query` actions. Use this when MCP is available for structured CRUD.
-- **`harness validate`** -- Run after any roadmap modification to verify project health. Mandatory in the VALIDATE phase of both `--create` and `--add`.
-- **Core `parseRoadmap`/`serializeRoadmap`** -- Fallback when MCP is unavailable. These functions in `packages/core/src/roadmap/` handle parsing and serializing the roadmap markdown format directly.
-- **Roadmap file** -- Always at `docs/roadmap.md`. This is the single source of truth for the project roadmap.
+- **`manage_roadmap` MCP tool** -- Primary read/write interface for roadmap operations. Supports `show`, `add`, `update`, `remove`, `query`, `sync`, `promote`, and `groom` actions. Use this when MCP is available for structured CRUD.
+- **`harness validate`** -- Run after any roadmap modification to verify project health. Mandatory in the VALIDATE phase of `--create`, `--add`, and `--groom`. The `roadmapHealth` check enforces the maintenance rules (RMH001-RMH004) as a regression guard.
+- **Core `checkRoadmapHealth`/`groomRoadmap`** -- Maintenance engine in `packages/core/src/roadmap/health.ts`. `checkRoadmapHealth` is read-only diagnostics; `groomRoadmap` is the pure transform (demote unactionable planned, archive done). Both are surfaced via `manage_roadmap` and `harness validate`.
+- **Core `parseRoadmap`/`serializeRoadmap`** -- Fallback when MCP is unavailable. These functions in `packages/core/src/roadmap/` handle parsing and serializing the roadmap markdown format directly. Note: the serializer only preserves frontmatter, milestones, features, and the Assignment History table -- never add convention prose or comments to `docs/roadmap.md`, they are dropped on the next write.
+- **Roadmap files** -- Live work in `docs/roadmap.md` (the orchestrator's source of truth); completed work archived to `docs/roadmap-archive.md` by `--groom`. Milestones are themes, not lifecycle stages -- promoted items land in the `Intake` lane and are groomed into themes.
 
 ## Success Criteria
 

package/dist/agents/skills/codex/harness-roadmap-pilot/SKILL.md

@@ -126,6 +126,8 @@ Proceed with Feature A? (y/n/pick another)
 
 ### Phase 3: CONFIRM -- Human Decision
 
+Ask the human in plain text (matching the `y/n/pick another` example above). Do not elevate this confirmation to an `AskUserQuestion` tool call — candidate labels and natural header choices ("Pick candidate", etc.) exceed its 12-char `header` cap and the prompt is rejected as ERR.
+
 1. Wait for human confirmation.
    - If **yes**: proceed to Phase 4.
    - If **pick another**: ask which candidate number, then proceed with that pick.

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

@@ -8,8 +8,9 @@
 - In CI — optimize test suite execution order
 - When a test fails — understand which changes could have caused it
 - When `on_pr` triggers fire
-- NOT for writing tests (use harness-tdd)
-- NOT for test quality analysis (out of scope)
+- **Coverage Audit mode** — when no diff is available and the user asks for "coverage gaps", "deep dive", "coverage plan", or "what's untested", run project-wide gap analysis instead of test selection
+- NOT for writing tests (use harness-tdd, or `canary:canary-write-test` for uncovered files surfaced by Coverage Audit)
+- NOT for test quality analysis at the test-selection level (Coverage Audit mode does include a capped quality review via `canary:canary-review-test`)
 
 ## Prerequisites
 
@@ -112,6 +113,83 @@ npx vitest run tests/services/auth.test.ts tests/types/user.test.ts tests/routes
 npx vitest run tests/services/auth.test.ts tests/types/user.test.ts tests/routes/login.test.ts tests/middleware/verify.test.ts tests/integration/auth-flow.test.ts
 ```
 
+## Coverage Audit Mode
+
+Activates when `--audit` is passed, OR when no diff is available AND the user's
+language matches audit intent ("coverage gaps", "deep dive", "coverage plan",
+"what's untested"). When this mode is selected, skip Phases 1–3 above and run
+the audit phases below instead.
+
+### Audit Phase 0: PROBE — Detect canary CLI availability
+
+Call the `canary_probe` MCP tool once at the start of the audit. It returns
+`{ status: "available" | "degraded", version?, reason? }` and never errors.
+
+- **`available`** — the deterministic canary CLI is usable; use `canary_recommend_framework`
+  for framework selection in Phase 3 (GAP REPORT).
+- **`degraded`** — the CLI is not usable (reason: `not-installed`, `binary-missing`,
+  `exec-failed`, or `bad-output`). Print one line:
+
+  > canary CLI unavailable (`<reason>`) — install `canary-test-cli` for deterministic
+  > framework recommendations. Proceeding; framework picks fall back to the plugin.
+
+  Then skip `canary_recommend_framework` calls for the rest of the run. This does **not**
+  affect the plugin-based Quality Review in Phase 2 (`canary:canary-review-test` is a
+  separate Claude Code plugin, installed independently of the CLI).
+
+### Audit Phase 1: INVENTORY — Build the Source-to-Test Map
+
+1. **Enumerate source files**: glob for `.ts`, `.tsx`, `.js`, `.jsx` under the
+   project's source roots (e.g., `src/`, `packages/*/src/`). Skip `node_modules`,
+   `dist`, build outputs, and fixtures.
+2. **Enumerate test files**: glob for `*.test.*`, `*.spec.*`, and files under
+   `__tests__/` and parallel `tests/` directories.
+3. **Map source → test**: for each source file, find its test file using the
+   Tier 1 / Tier 2 / Tier 3 strategies described in `Phase 2: DISCOVER`. With a
+   graph, prefer `get_impact`; without one, use naming conventions and import
+   parsing.
+4. **Split**: produce two lists — `covered` (source files with at least one
+   matching test) and `uncovered` (source files with no matching test).
+
+### Audit Phase 2: QUALITY REVIEW — Critique Covered Test Files
+
+1. **Cap at 10 files per run**: a deep quality review is expensive. Pick the
+   top 10 covered files prioritized by size (lines of code) and criticality
+   (depth in the graph / co-change frequency). The remaining covered files are
+   accepted as-is for this run.
+2. **For each of the 10**: dispatch `canary:canary-review-test` against the
+   test file. Collect its findings (missing edge cases, anti-patterns,
+   brittleness, oracle gaps).
+3. **Aggregate**: bin findings by severity (high / medium / low) and by file.
+
+### Audit Phase 3: GAP REPORT — Synthesize a Unified Coverage Plan
+
+Emit a single report with three sections:
+
+```
+## Coverage Audit Report
+
+### Uncovered Files (no test found)
+| File | Lines | Priority | Suggested Action |
+|------|-------|----------|------------------|
+| src/services/billing.ts | 412 | high | canary:canary-write-test |
+| src/utils/format.ts     | 38  | low  | canary:canary-write-test |
+
+### Quality Gaps (from Quality Review, capped at 10 reviewed)
+| Test File | Severity | Top Gap |
+|-----------|----------|---------|
+| tests/services/auth.test.ts | high | no failure-path assertions |
+| tests/utils/date.test.ts    | med  | mock leaks across cases |
+
+### Recommended Next Steps
+- Generate tests for high-priority uncovered files via `canary:canary-write-test`.
+- Resolve high-severity quality gaps via `canary:canary-review-test` follow-ups.
+- For uncovered files, pick a framework first: when Phase 0 reported `available`, call
+  the `canary_recommend_framework` MCP tool with a prompt describing the file's purpose
+  (deterministic, no LLM round-trip) and put its `framework` in the Suggested Action.
+  When `degraded`, fall back to the `canary:canary-pick-framework` plugin.
+```
+
 ## Harness Integration
 
 - **`harness scan`** — Recommended before this skill for full graph-enhanced analysis. If graph is missing, skill uses naming convention and import parsing fallbacks.

package/dist/agents/skills/codex/harness-test-advisor/skill.yaml

@@ -1,6 +1,6 @@
 name: harness-test-advisor
 version: "1.0.0"
-description: Graph-based test selection — answers "what tests should I run?"
+description: Graph-based test selection and project-wide coverage audit — answers "what tests should I run?" or "what's untested?"
 stability: static
 cognitive_mode: advisory-guide
 triggers:
@@ -25,6 +25,9 @@ cli:
     - name: files
       description: Comma-separated list of changed files
       required: false
+    - name: audit
+      description: Run Coverage Audit mode (project-wide gap analysis) instead of test selection
+      required: false
 mcp:
   tool: run_skill
   input:

package/dist/agents/skills/codex/initialize-harness-project/SKILL.md

@@ -29,6 +29,8 @@ Detect plugin-only state by checking whether `harness` resolves on PATH (`comman
 
 ## Process
 
+**Prompt the human in plain text** — every framework confirmation, migration check, and telemetry-identity question in this skill is plain text only. Do not elevate to `AskUserQuestion`: the framework list (~10 options) exceeds its 4-option cap and natural headers like "Confirm framework" exceed its 12-char cap, rendering the call as ERR.
+
 ### Phase 1: ASSESS — Determine Current State
 
 1. **Check for existing harness configuration.** Look for `.harness/` directory, `AGENTS.md`, `harness.config.json`, and any skill definitions. Their presence determines whether this is a new project or a migration.
@@ -96,7 +98,7 @@ Detect plugin-only state by checking whether `harness` resolves on PATH (`comman
 5. **Configure i18n (all levels).** Ask: "Will this project support multiple languages?" Based on the answer:
    - **Yes:** Invoke `harness-i18n-workflow` configure phase to set up i18n config in `harness.config.json` (source locale, target locales, framework, strictness). Then invoke `harness-i18n-workflow` scaffold phase to create translation file structure and extraction config. Set `i18n.enabled: true`.
    - **No:** Set `i18n.enabled: false` in `harness.config.json`. The `harness-i18n-process` skill will still fire gentle prompts for unconfigured projects when features touch user-facing strings.
-   - **Not sure yet:** Skip i18n configuration entirely. Do not set `i18n.enabled`. The project can enable i18n later by running `harness-i18n-workflow` directly.
+   - **Not sure:** Skip i18n configuration entirely. Do not set `i18n.enabled`. The project can enable i18n later by running `harness-i18n-workflow` directly.
 
 5b. **Configure design system (non-test-suite projects).** Ask: "Will this project have a UI requiring a design system?" Mirror the i18n step's three-way response shape. Use `emit_interaction`:
 
@@ -136,7 +138,7 @@ Detect plugin-only state by checking whether `harness` resolves on PATH (`comman
     Based on the answer:
     - **Yes:** Ask a follow-up: "Which platforms? `web`, `mobile`, or both?" Write `design.enabled: true` and `design.platforms: [...]` (a non-empty array of `web` and/or `mobile`) to `harness.config.json`. Inform the user: "Design tokens will be generated when you start your first design-touching feature — `harness-design-system` fires automatically via `on_new_feature`."
     - **No:** Write `design.enabled: false` to `harness.config.json`. Do not write `design.platforms`. The `on_new_feature` trigger respects this flag and will not fire `harness-design-system`.
-    - **Not sure yet:** Do not write `design.enabled` or `design.platforms`. The project can enable design later by running `harness-design-system` directly; `on_new_feature` will prompt gently when a feature touches user-facing UI.
+    - **Not sure:** Do not write `design.enabled` or `design.platforms`. The project can enable design later by running `harness-design-system` directly; `on_new_feature` will prompt gently when a feature touches user-facing UI.
 
     **Skip this step entirely if Phase 1 step 5 classified the project as a test suite.** Test-suite projects will be dispatched at step 6 below to `initialize-test-suite-project` and have no UI to govern.
 
@@ -183,7 +185,7 @@ Detect plugin-only state by checking whether `harness` resolves on PATH (`comman
     - **Absent (most common on init).** Present the prompt above. Apply the answer:
       - **Yes:** delegate to `harness-strategy` (which routes via its own Phase 0 to the first-run interview). When `harness-strategy` completes, continue with step 6.
       - **No:** write `init.strategy.declined: true` to `.harness/state.json` (merge into existing JSON; do not clobber). This is the explicit decline location; re-running init detects the flag and skips the prompt.
-      - **Not sure yet:** no state write. `/harness:strategy` remains available standalone, and a future re-run of init will re-offer.
+      - **Not sure:** no state write. `/harness:strategy` remains available standalone, and a future re-run of init will re-offer.
 
     - **Present and valid.** Skip the prompt silently. Surface a one-line note: `STRATEGY.md detected — downstream skills will pick it up as grounding`. No `init.strategy.declined` write.
 
@@ -303,7 +305,7 @@ This phase closes the parity gap that the marketplace plugin install does not co
 
    Based on the answer:
    - **Yes:** Invoke `harness-roadmap` (skill) or run `/harness:roadmap --create` to create `docs/roadmap.md`. Verify the file exists. The `manage_roadmap` MCP tool is for managing entries in an existing roadmap, not for creating one.
-     - **If `design.enabled === true` in `harness.config.json`** (set by Phase 3 step 5b), call `manage_roadmap` with `action: add`, `feature: "Set up design system"`, `status: "planned"`, `milestone: "Current Work"`, `summary: "Run harness-design-system to define palette, typography, and generate W3C DTCG tokens. Deferred from project init — fires on first design-touching feature via on_new_feature."`. Skip silently if `manage_roadmap show` reports a duplicate `(feature, milestone)` pair. This closes the loop between deferred design intent and visible planning work.
+     - **If `design.enabled === true` in `harness.config.json`** (set by Phase 3 step 5b), call `manage_roadmap` with `action: add`, `feature: "Set up design system"`, `status: "planned"`, `milestone: "Intake"`, `summary: "Run harness-design-system to define palette, typography, and generate W3C DTCG tokens. Deferred from project init — fires on first design-touching feature via on_new_feature."`. Skip silently if `manage_roadmap show` reports a duplicate `(feature, milestone)` pair. This closes the loop between deferred design intent and visible planning work.
    - **No:** Skip silently. The user can still run `/harness:roadmap --create` later — that informational fallback remains valid.
 
 2. **Commit the initialization.** All generated, configured, and instrumentation files in a single commit. Include `harness.config.json`, `AGENTS.md`, `.harness/arch/baselines.json`, `.harness/telemetry.json` (if created), updates to project `.mcp.json` (if Tier-0 integrations were wired), and any roadmap files.
@@ -323,11 +325,11 @@ This phase closes the parity gap that the marketplace plugin install does not co
 - **`harness integrations list` / `harness integrations add <name>`** — Phase 5 step 6. Lists Tier-0 (zero-config) and Tier-1 (API-key) MCP integrations and adds them to project `.mcp.json`.
 - **`harness-i18n-workflow configure` + `harness-i18n-workflow scaffold`** — Invoked during Phase 3 if the project will support multiple languages. Sets up i18n configuration and translation file structure.
 - **`harness-design-system` (deferred via `on_new_feature`)** — Phase 3 step 5b records `design.enabled` + `design.platforms` in `harness.config.json` but does NOT run the full design-system skill. Token generation defers to the first design-touching feature, where `harness-design-system` fires via `on_new_feature` and reads `design.enabled` to decide whether to proceed.
-- **`harness-strategy`** — Phase 3 step 5c delegates to this skill on "Yes". The skill conducts a first-run interview (pushback rules with a 2-round cap per section) and writes a valid `STRATEGY.md` at repo root via `writeStrategyDoc`. On "No" init writes `init.strategy.declined: true` to `.harness/state.json`. On "Not sure yet" no state is written; the user can run `/harness:strategy` standalone. When `STRATEGY.md` already exists and is valid the prompt is skipped; when present-but-invalid the user gets the three-path repair offer.
+- **`harness-strategy`** — Phase 3 step 5c delegates to this skill on "Yes". The skill conducts a first-run interview (pushback rules with a 2-round cap per section) and writes a valid `STRATEGY.md` at repo root via `writeStrategyDoc`. On "No" init writes `init.strategy.declined: true` to `.harness/state.json`. On "not sure" no state is written; the user can run `/harness:strategy` standalone. When `STRATEGY.md` already exists and is valid the prompt is skipped; when present-but-invalid the user gets the three-path repair offer.
 - **`validateStrategy`** — `@harness-engineering/core` helper used by Phase 3 step 5c to detect present-but-invalid `STRATEGY.md`. Invoked through a Node one-liner so init does not require importing core directly.
 - **`initialize-test-suite-project`** — Sub-skill. Invoked during Phase 3 step 6 when Phase 1 step 5 classified the project as a test suite. Owns archetype selection, shared-library vs in-repo decision, layer variants, tag taxonomy, reporter stack, custom report, and "prove the guards fire" verification.
 - **`harness-roadmap` skill** — Phase 6 step 1 invokes this skill (or `/harness:roadmap --create`) when the user opts in to creating `docs/roadmap.md`. The `manage_roadmap` MCP tool does not create roadmaps; it manages entries in an existing one.
-- **`manage_roadmap` MCP tool** — Phase 6 step 1, when `design.enabled === true`, calls `manage_roadmap` with `action: add` to insert a `planned` "Set up design system" item under milestone `Current Work` with a summary describing the deferred work.
+- **`manage_roadmap` MCP tool** — Phase 6 step 1, when `design.enabled === true`, calls `manage_roadmap` with `action: add` to insert a `planned` "Set up design system" item under milestone `Intake` with a summary describing the deferred work.
 
 ## Success Criteria
 
@@ -340,29 +342,29 @@ This phase closes the parity gap that the marketplace plugin install does not co
 - The adoption level matches what was agreed upon with the human
 - All generated files are committed in a single atomic commit
 - i18n configuration is set if the human chose to enable it during init
-- For non-test-suite projects, the design-system question was asked and `harness.config.json` reflects the answer: `design.enabled: true` (with `design.platforms` populated) for yes, `design.enabled: false` for no, or absent for not-sure.
-- The strategy question (Phase 3 step 5c) was asked unless `STRATEGY.md` already existed and was valid (in which case the prompt was skipped silently with a one-line detection note). The answer was recorded according to the documented semantics: Yes → `STRATEGY.md` exists and `harness validate` passes against `StrategyDocSchema`; No → `.harness/state.json` contains `init.strategy.declined: true`; Not sure yet → no `STRATEGY.md` and no `init.strategy.declined` flag.
+- For non-test-suite projects, the design-system question was asked and `harness.config.json` reflects the answer: `design.enabled: true` (with `design.platforms` populated) for yes, `design.enabled: false` for no, or absent for not sure.
+- The strategy question (Phase 3 step 5c) was asked unless `STRATEGY.md` already existed and was valid (in which case the prompt was skipped silently with a one-line detection note). The answer was recorded according to the documented semantics: Yes → `STRATEGY.md` exists and `harness validate` passes against `StrategyDocSchema`; No → `.harness/state.json` contains `init.strategy.declined: true`; Not sure → no `STRATEGY.md` and no `init.strategy.declined` flag.
 - **Phase 5 (INSTRUMENT) outputs:** `.harness/graph/` is populated; `.harness/arch/baselines.json` exists; `harness check-perf` ran without errors (intermediate and above); `.harness/telemetry.json` exists if the human opted into identity tagging; legacy layout warnings were surfaced via `harness migrate --dry-run` and either resolved or explicitly deferred; Tier-0 MCP integrations (context7, sequential-thinking, playwright) are present in the project's `.mcp.json` (or the human declined and that decision is recorded).
 - The roadmap question was asked. If the user answered yes, `docs/roadmap.md` exists and was created via `harness-roadmap` (or the documented `/harness:roadmap --create` fallback).
-- When `design.enabled === true` AND the user answered yes to the roadmap question, `docs/roadmap.md` contains a `planned` entry titled "Set up design system" under milestone `Current Work` with a summary describing the deferred work. The entry is absent in all other answer combinations.
+- When `design.enabled === true` AND the user answered yes to the roadmap question, `docs/roadmap.md` contains a `planned` entry titled "Set up design system" under milestone `Intake` with a summary describing the deferred work. The entry is absent in all other answer combinations.
 - For test suites: `initialize-test-suite-project` ran to completion and its Success Criteria are also met
 - For plugin-only invocations: every CLI invocation in this skill ran successfully via `npx @harness-engineering/cli <cmd>` without requiring a global install. If any invocation failed because the npx download failed, the human was prompted to retry or `npm install -g @harness-engineering/cli` instead.
 
 ## Rationalizations to Reject
 
-| Rationalization                                                              | Why It Is Wrong                                                                                                                                                                                                                                                                                                                                                       |
-| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| "The generated AGENTS.md template looks fine -- no need to customize it"     | Phase 3 says do not blindly accept generated content. Without project-specific descriptions, agents receive generic instructions.                                                                                                                                                                                                                                     |
-| "We should start at the advanced level since we want full coverage"          | The skill recommends basic for new projects. Each level builds on the previous. Jumping to advanced creates misconfigured rules.                                                                                                                                                                                                                                      |
-| "I will skip the i18n question to keep setup fast"                           | Phase 3 requires asking about i18n and recording the decision. Skipping creates ambiguity about whether the omission was intentional.                                                                                                                                                                                                                                 |
-| "I will skip the design-system question to keep setup fast"                  | Phase 3 step 5b requires asking about design and recording the answer in `design.enabled`. Skipping creates ambiguity about whether the omission was intentional and bypasses the linkage between init and the deferred `harness-design-system` invocation on `on_new_feature`.                                                                                       |
-| "I will skip the strategy question — it's just paperwork"                    | Phase 3 step 5c is the only point in the workflow where init asks the user to capture the strategic anchor. Skipping bypasses the grounding signal that brainstorming, ideate, and roadmap-pilot read; downstream skill output degrades silently. Even a "No" or "Not sure yet" answer is better than no answer because it locks in the decision (or absence of one). |
-| "STRATEGY.md exists already, so I should re-run the interview to refresh it" | When `STRATEGY.md` is present and valid, Phase 3 step 5c skips the prompt silently. Refreshing strategy mid-init is out of scope — that is what the standalone `/harness:strategy` update flow is for. Surface a one-line detection note and continue.                                                                                                                |
-| "STRATEGY.md is present but invalid, so I should block init"                 | Phase 3 step 5c explicitly does NOT block. It surfaces the validation error, offers three repair paths (fix now / move-to-bak / ignore), and continues based on the user's choice. Init is the wrong place to gate on strategy correctness.                                                                                                                           |
-| "Validation passed, so the project is ready"                                 | Phase 5 captures baselines, configures telemetry identity, surfaces legacy warnings, and wires Tier-0 integrations. Validation alone is not sufficient.                                                                                                                                                                                                               |
-| "Plugin install means setup is done"                                         | The marketplace plugin ships skills, slash commands, subagents, hooks, and MCP — but it cannot mutate the user's project state. `harness.config.json`, baselines, telemetry identity, and Tier-0 integrations require running this skill once per project.                                                                                                            |
-| "Skip Phase 5 if we already ran `harness setup`"                             | Phase 5 is idempotent. It safely no-ops where setup already wired things and fills gaps where it didn't (common case: setup ran once, then a new Tier-0 integration was added or a layout was migrated). Re-running is the right behavior.                                                                                                                            |
-| "This is a test suite, we'll configure layers in this skill"                 | Phase 3 step 6 dispatches to `initialize-test-suite-project` for archetype selection, layer variants, and the rest. Do not inline test-suite-specific configuration here — the sub-skill owns it and carries the gotchas.                                                                                                                                             |
+| Rationalization                                                              | Why It Is Wrong                                                                                                                                                                                                                                                                                                                                                   |
+| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "The generated AGENTS.md template looks fine -- no need to customize it"     | Phase 3 says do not blindly accept generated content. Without project-specific descriptions, agents receive generic instructions.                                                                                                                                                                                                                                 |
+| "We should start at the advanced level since we want full coverage"          | The skill recommends basic for new projects. Each level builds on the previous. Jumping to advanced creates misconfigured rules.                                                                                                                                                                                                                                  |
+| "I will skip the i18n question to keep setup fast"                           | Phase 3 requires asking about i18n and recording the decision. Skipping creates ambiguity about whether the omission was intentional.                                                                                                                                                                                                                             |
+| "I will skip the design-system question to keep setup fast"                  | Phase 3 step 5b requires asking about design and recording the answer in `design.enabled`. Skipping creates ambiguity about whether the omission was intentional and bypasses the linkage between init and the deferred `harness-design-system` invocation on `on_new_feature`.                                                                                   |
+| "I will skip the strategy question — it's just paperwork"                    | Phase 3 step 5c is the only point in the workflow where init asks the user to capture the strategic anchor. Skipping bypasses the grounding signal that brainstorming, ideate, and roadmap-pilot read; downstream skill output degrades silently. Even a "no" or "not sure" answer is better than no answer because it locks in the decision (or absence of one). |
+| "STRATEGY.md exists already, so I should re-run the interview to refresh it" | When `STRATEGY.md` is present and valid, Phase 3 step 5c skips the prompt silently. Refreshing strategy mid-init is out of scope — that is what the standalone `/harness:strategy` update flow is for. Surface a one-line detection note and continue.                                                                                                            |
+| "STRATEGY.md is present but invalid, so I should block init"                 | Phase 3 step 5c explicitly does NOT block. It surfaces the validation error, offers three repair paths (fix now / move-to-bak / ignore), and continues based on the user's choice. Init is the wrong place to gate on strategy correctness.                                                                                                                       |
+| "Validation passed, so the project is ready"                                 | Phase 5 captures baselines, configures telemetry identity, surfaces legacy warnings, and wires Tier-0 integrations. Validation alone is not sufficient.                                                                                                                                                                                                           |
+| "Plugin install means setup is done"                                         | The marketplace plugin ships skills, slash commands, subagents, hooks, and MCP — but it cannot mutate the user's project state. `harness.config.json`, baselines, telemetry identity, and Tier-0 integrations require running this skill once per project.                                                                                                        |
+| "Skip Phase 5 if we already ran `harness setup`"                             | Phase 5 is idempotent. It safely no-ops where setup already wired things and fills gaps where it didn't (common case: setup ran once, then a new Tier-0 integration was added or a layout was migrated). Re-running is the right behavior.                                                                                                                        |
+| "This is a test suite, we'll configure layers in this skill"                 | Phase 3 step 6 dispatches to `initialize-test-suite-project` for archetype selection, layer variants, and the rest. Do not inline test-suite-specific configuration here — the sub-skill owns it and carries the gotchas.                                                                                                                                         |
 
 ## Examples
 
@@ -458,7 +460,7 @@ Step 4 (roadmap): "Set up a project roadmap now?"
   design.enabled === true detected → manage_roadmap action: add
     feature: "Set up design system"
     status: planned
-    milestone: Current Work
+    milestone: Intake
     summary: "Run harness-design-system to define palette, typography, and generate W3C DTCG tokens..."
   Result: docs/roadmap.md contains the planned design item.
 
@@ -470,7 +472,7 @@ git add harness.config.json .harness/ AGENTS.md docs/roadmap.md
 git commit -m "feat: initialize harness project with design and roadmap"
 ```
 
-**Final state:** `harness.config.json` has `design.enabled: true` + `design.platforms: ["web"]`; `docs/roadmap.md` lists "Set up design system" as a `planned` item under `Current Work`; on the first feature touching UI, `on_new_feature` fires `harness-design-system` which reads `design.enabled` and runs the full discover/define/generate/validate flow.
+**Final state:** `harness.config.json` has `design.enabled: true` + `design.platforms: ["web"]`; `docs/roadmap.md` lists "Set up design system" as a `planned` item under `Intake`; on the first feature touching UI, `on_new_feature` fires `harness-design-system` which reads `design.enabled` and runs the full discover/define/generate/validate flow.
 
 ### Example: Migrating Existing Project from Basic to Intermediate
 
@@ -547,7 +549,7 @@ npx @harness-engineering/cli init  # auto-detects framework
 Customize AGENTS.md with project-specific content.
 Phase 3 step 5 (i18n): "No, English only." → i18n.enabled = false.
 Phase 3 step 5b (design): "No, this is a backend service." → design.enabled = false.
-Phase 3 step 5c (strategy): "Not sure yet." → no STRATEGY.md, no init.strategy.declined flag; user can run /harness:strategy later.
+Phase 3 step 5c (strategy): "not sure." → no STRATEGY.md, no init.strategy.declined flag; user can run /harness:strategy later.
 Phase 3 step 6 (test-suite dispatch): not a test suite, skipped.
 ```
 

package/dist/agents/skills/codex/initialize-harness-project/skill.yaml

@@ -35,3 +35,4 @@ state:
 depends_on:
   - initialize-test-suite-project
   - harness-design-system
+  - harness-roadmap

package/dist/agents/skills/codex/outcome-eval/SKILL.md

@@ -0,0 +1,97 @@
+# Outcome Eval
+
+> Post-execution LLM-judgment: did the implementation actually satisfy its spec? Reads the spec's acceptance section, the change diff, and test output, and emits a confidence-rated `OutcomeVerdict` (`SATISFIED | NOT_SATISFIED | INCONCLUSIVE`) with a rationale and unmet criteria. Ship authority is derived in TypeScript, never trusted from the LLM: a high-confidence `NOT_SATISFIED` blocks ship; every other verdict is advisory. The harness's first blocking post-execution spec-satisfaction gate (the roadmap's named #1 gap). Each verdict persists as an `execution_outcome` node, compounding into skill-effectiveness baselines.
+
+## When to Use
+
+- At orchestrator step 6.5 — after Code Review, before Ship — on every change with a spec.
+- When you need a durable, structured answer to "did this code do what the spec said?"
+- NOT for pre-execution risk simulation (use PESL).
+- NOT for rule-based floors (lint/architecture/entropy) or craft ceilings (naming/spec/security) — those run elsewhere.
+- NOT for auto-remediation. outcome-eval judges; it does not fix.
+- NOT when no judgable spec section exists — the verdict degrades to INCONCLUSIVE/advisory and never blocks.
+
+## Process
+
+### Phase 1: GATHER — Collect inputs
+
+1. Capture the change under judgment as a unified diff: `git diff` (or `git diff <base>...HEAD` for a branch). Record it as `diff`.
+2. Capture test-runner output. If a test command is known, run it and capture stdout+stderr as `testOutput`; otherwise pass the most recent captured output. Empty/unparseable test output is tolerated (degrades to advisory).
+3. Resolve the spec path. Prefer the spec under `docs/changes/<feature>/proposal.md` for the current change. Record as `specPath`.
+
+### Phase 2: RESOLVE — Find the judgment section
+
+The evaluator resolves the section internally via the fallback chain `## Success Criteria` -> `## User-Visible Behavior` -> `## Overview`, recording the match in `judgedAgainst`. No manual action — pass `specPath` and let `OutcomeEvaluator` resolve. If no section is judgable, the verdict is INCONCLUSIVE/advisory.
+
+### Phase 3: JUDGE — Invoke the evaluator
+
+1. Invoke the MCP tool `mcp__harness__outcome_eval` with `{ specPath, diff, testOutput }` (optional `model`). The tool constructs `OutcomeEvaluator` cli-side and calls `evaluate({ specPath, diff, testOutput })`; the supported v1 provider is the anthropic analysis provider (`ANTHROPIC_API_KEY`).
+2. **`diff` and `testOutput` are required inputs and the agent MUST supply them** from the session (`git diff` + captured test-runner output). They are the evidence the judge reasons over — passing an empty `diff` or empty `testOutput` is the degradation path, not the normal path: the verdict degrades to INCONCLUSIVE/advisory (never blocking), which defeats the gate. Do not invoke the tool without real diff/test content.
+3. The LLM returns ONLY `verdict / confidence / rationale / unmetCriteria`. `authority` is computed in TypeScript from `(verdict, confidence)` and is never read from the LLM — do not attempt to override it. The tool returns the verdict exactly as the evaluator derives it.
+4. The call is degrade-safe: provider failure (incl. no `ANTHROPIC_API_KEY`), empty diff, empty test output, or missing judgable section yields INCONCLUSIVE/low/advisory. It never throws and never blocks.
+
+### Phase 4: GATE — Render and (conditionally) halt
+
+1. Render the verdict: `verdict`, `confidence`, `judgedAgainst`, `rationale`, and `unmetCriteria`.
+2. Authority rule (must match `deriveAuthority`): authority is `blocking` **iff** `verdict === 'NOT_SATISFIED' && confidence === 'high'`; every other combination — including all `INCONCLUSIVE` and `SATISFIED` cases, and all `medium`/`low` `NOT_SATISFIED` — is `advisory`.
+3. **On a blocking verdict: HALT before the Ship step.** Report the unmet criteria and stop; do not proceed to step 7. Resolution requires fixing the implementation (or the spec) and re-running outcome-eval.
+4. On an advisory verdict: report it and proceed. Advisory `NOT_SATISFIED` is surfaced for human attention but does not stop the workflow.
+
+## Harness Integration
+
+- **`mcp__harness__outcome_eval`** — MCP tool (the invocation surface). Inputs: `specPath` (required), `diff` (required), `testOutput` (required), `model` (optional), `path` (optional project root for graph persistence). The agent supplies `diff` and `testOutput` from the session; omitting them degrades the verdict to INCONCLUSIVE/advisory (never blocking). The handler builds the cli `AnalysisProvider` + a `GraphStore`, constructs `OutcomeEvaluator`, and returns the `OutcomeVerdict` with authority exactly as derived in TypeScript.
+- **Evaluator surface:** `OutcomeEvaluator`, `deriveAuthority`, `verdictSchema`, `OutcomeVerdict` are exported from `@harness-engineering/intelligence`.
+- **Provider path (v1 supported):** the anthropic analysis provider (`ANTHROPIC_API_KEY`). When no provider is configured the call degrades to INCONCLUSIVE/advisory. The openai-compatible _strict_ structured-output path is a known follow-up (see Known Limitations).
+- **Orchestrator:** runs as step 6.5 between Code Review and Ship in `harness.orchestrator.md`.
+- **Persistence:** each `evaluate()` writes one `execution_outcome` node via `ExecutionOutcomeConnector`, consumable by `effectiveness/scorer.ts`.
+
+## Known Limitations
+
+- **INCONCLUSIVE persistence:** the persisted node maps `INCONCLUSIVE -> result: 'failure'` for type-validity, but it OMITS `agentPersona` and writes `affectedSystemNodeIds: []`. The effectiveness scorer (`gatherOutcomes`) ignores any node missing `agentPersona` or `outcome_of` edges, so outcome-eval nodes are **scorer-non-counting** in v1 — the INCONCLUSIVE-as-failure mapping is therefore harmless and does not punish any persona. If a future change attaches persona/affected-system attribution, it MUST first change INCONCLUSIVE modeling (do not persist INCONCLUSIVE, or use a distinct result value the scorer excludes) before the node becomes scorer-counted.
+- **openai-compatible strict mode:** `zodToJsonSchema` does not emit `additionalProperties: false`, which OpenAI strict structured output requires. The v1 supported path is claude-cli / anthropic. Follow-up tracked.
+- **CI required-check wiring:** deferred to roadmap #540 (unbuilt CI workflow template).
+
+## Success Criteria
+
+See `docs/changes/outcome-eval/proposal.md` for the full 9 criteria. This skill satisfies SC8 (orchestrator step 6.5 + blocking halt) and SC9 (introduces no new `harness validate` findings; layer rules respected).
+
+## Examples
+
+### Example: NOT_SATISFIED with high confidence (blocks)
+
+**Input:** spec Success Criteria require `GET /api/users/:id` to return 404 with `{ error: 'User not found' }`; the diff implements the happy path only, no 404 branch; test output shows the 404 test failing.
+
+**Verdict:**
+
+```
+verdict:        NOT_SATISFIED
+confidence:     high
+judgedAgainst:  success-criteria
+authority:      blocking
+unmetCriteria:
+  - "404 path for nonexistent user is unimplemented; the failing test asserts { error: 'User not found' }."
+rationale:      "The diff adds the lookup but returns 200 with an empty body when the user is missing."
+```
+
+**Action:** HALT before Ship. Report unmet criteria; do not open the PR.
+
+### Example: partial implementation (advisory)
+
+**Input:** the diff meets most criteria; one acceptance item is ambiguous in the diff.
+
+**Verdict:** `NOT_SATISFIED confidence: medium authority: advisory` — surfaced for review, workflow proceeds.
+
+## Gates
+
+- **Authority is never read from the LLM.** The verdict's `authority` is always `deriveAuthority(verdict, confidence)` computed in TypeScript. If you find yourself letting the model assert blocking/advisory, STOP — that defeats the entire purpose of this gate.
+- **Block only on high-confidence NOT_SATISFIED.** `authority === 'blocking'` iff `verdict === 'NOT_SATISFIED' && confidence === 'high'`. Every other combination — all `SATISFIED`, all `INCONCLUSIVE`, and every `medium`/`low` `NOT_SATISFIED` — is advisory. Do not halt the workflow on an advisory verdict.
+- **Always supply `diff` and `testOutput`.** Omitting them degrades the verdict to INCONCLUSIVE/advisory (a silent false-negative at the ship gate). Gather them from the session before invoking the tool.
+- **Never block on infrastructure noise.** A provider failure, an unparseable response, or a missing spec must resolve to INCONCLUSIVE/advisory, never a thrown error or a block. The evaluator enforces this; do not reintroduce a hard failure in the wrapper.
+- **Do not skip step 6.5.** The gate runs after Code Review and before Ship. A blocking verdict halts before step 7; it is not optional.
+
+## Escalation
+
+- **Blocking verdict the author disputes:** the resolution is to fix the implementation (or amend the spec's Success Criteria if they were wrong) and re-run outcome-eval — not to override the gate. If the spec itself is wrong, that is a spec change, reviewed on its own merits.
+- **Repeated INCONCLUSIVE on a real change:** usually means `diff`/`testOutput` were not supplied, or no judgable section exists in the spec. Confirm inputs and that the spec has a Success Criteria / User-Visible Behavior / Overview section.
+- **No `ANTHROPIC_API_KEY` configured:** every verdict degrades to INCONCLUSIVE/advisory and nothing blocks. Surface this to the human — the gate is effectively disabled until a provider is configured.
+- **Verdict seems wrong (false positive/negative):** capture the spec section, diff, and verdict, and route to the maintainers; do not loosen the conservative-confidence prompt ad hoc.