Refactor skills documentation and patterns

- Updated README.md to reflect new pattern files and their purposes.
- Enhanced index.md with binding legends for applicable agents and updated skill file references.
- Revised completeness-traceability.md to correct the number of skill files in the index.
- Added decision rules and clarified usage in idea-to-prompt.md and spec-driven-development.md.
- Improved llm-behavior-guidelines.md by condensing anti-pattern examples and enhancing clarity.
- Updated memory-promotion-candidates.md to clarify provenance of the checklist.
- Streamlined repo-memory-hygiene.md for clarity and conciseness in the pre-write checklist.
- Adjusted security-review-discipline.md to specify provenance of the discipline.

Author: Smith

.github/copilot-instructions.md

@@ -26,6 +26,7 @@ When status is `FAILED`, `NEEDS_INPUT`, `NEEDS_REVISION`, or `REJECTED`, include
 - `fixable` — Small correctable issue (typo, missing import, config value); retry with fix hint.
 - `needs_replan` — Architecture mismatch or missing dependency; delegate to Planner for targeted replan.
 - `escalate` — Security vulnerability, data integrity risk, or unresolvable blocker; stop and await human approval.
+- `model_unavailable` — the routed/primary model is unavailable or unreachable; substitute per model-routing fallback and retry up to `model_unavailable_max` (see runtime-policy.json), then escalate. Distinct from `transient`; the PlanAuditor/AssumptionVerifier `transient`-exclusion does NOT exclude `model_unavailable`.
 
 ## NOTES.md
 Maintain/update `NOTES.md` for persistent state across context resets:
@@ -59,7 +60,7 @@ Agent engineering policies are in `docs/agent-engineering/`:
 - Failure taxonomy applies to all agents; PlanAuditor and AssumptionVerifier exclude `transient`.
 - P.A.R.T. section order in every agent file: **Prompt → Archive → Resources → Tools** (see `PART-SPEC.md`).
 - Orchestrator and Planner must delegate only to project-internal agents documented in `plans/project-context.md`; external/third-party agents are strictly prohibited.
-- Adding/editing agents or skills: follow the 4-step process in `CONTRIBUTING.md` (create agent file, schema, eval scenarios, register in `plans/project-context.md`).
+- Adding/editing agents or skills: follow the agent-contribution process in `CONTRIBUTING.md` (create agent file, schema, eval scenarios, register in `plans/project-context.md`).
 - Tool and agent permission grants are in `governance/` (`agent-grants.json`, `tool-grants.json`, `runtime-policy.json`, `rename-allowlist.json`). Update these when changing an agent's tool profile.
 
 ## Agent System

.gitignore

@@ -10,7 +10,6 @@ yarn-error.log*
 # Ignore all plan files by default, but allow required project artifacts
 plans/*
 !plans/project-context.md
-!plans/pipeline-comparison.md
 !plans/session-outcomes.md
 !plans/templates/
 plans/templates/*
@@ -56,6 +55,8 @@ temp/
 *.swo
 # ── Eval warm cache ────────────────────────────────────────────
 evals/.cache/
+# ── Eval stdout dumps (debug scratch, not tracked) ────────────
+evals/out*.txt
 # ── Tool output spill directory ───────────────────────────────
 .cache/tool-output/
 # ── Windows OS artifacts ──────────────────────────────────

AssumptionVerifier-subagent.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Adversarial mirage detector that hunts assumption-fact confusion in plans using 17 systematic patterns'
 tools: [read/readFile, search/codebase, search/fileSearch, search/listDirectory, search/textSearch, search/usages]
-model: Claude Opus 4.7 (copilot)
+model: Claude Opus 4.8 (copilot)
 model_role: capable-reviewer
 ---
 You are AssumptionVerifier, an adversarial mirage detector for plan verification.

CHANGELOG.md

@@ -11,76 +11,38 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Added
 
 - **Cursor IDE Support**: Added `.cursor/rules` to provide high-level guidance to the Cursor agent, along with documentation in `docs/agent-engineering/CURSOR-SUPPORT.md`.
-
----
-
-## [Unreleased] — Claude Code Plugin (Phase 6)
-
-### Added - Claude Code Plugin
-
 - **Claude Code Plugin**: Shipped a first-class plugin adaptation for Anthropic's Claude Code at `plugins/controlflow-claude-code/`.
   - Includes 10 ControlFlow workflow skills adapted for Claude native slash-invocation.
   - Adds 6 native plugin agents for isolated review, research, mapping, and verification tasks.
   - Ships local validation scripts and local development lifecycle documentation.
   - Adds project-level references inside `README.md`, `CONTRIBUTING.md`, and quickstart docs.
-
----
-
-## [Unreleased] — Codex Plugin & Lifecycle Documentation Parity (Phases 4-8)
-
-### Added - Codex Parity
-
 - **BrowserTester Evidence Discipline**: Added snapshot, wait, console/network, visual regression, and untrusted content protocols (`BrowserTester-subagent.agent.md`).
 - **Living-Document Guidance**: Added "Living-Document and Restartability Guidance" section to `plans/templates/plan-document-template.md`.
-
-### Changed - Codex Parity
-
-- **Codex Plugin Lifecycle**: Introduced fixed lifecycle sections (`## Progress`, `## Discoveries`, `## Decision Log`, `## Outcomes`, `## Idempotence & Recovery`) in strict-plan dialect, enforced by `validate-strict-artifacts.ps1`.
-- **Plugin First-Class Status**: Upgraded `controlflow-codex` to a first-class plugin deliverable in `AGENTS.md` and `README.md`.
-
----
-
-## [Unreleased] — Model Routing Stage C Matrix
-
-### Added - Model Routing
-
-- `feat: add optional final review gate via final_review_gate policy flag` — Adds opt-in Completion Gate sub-step that dispatches CodeReviewer with review_scope=final for holistic scope-drift detection. Auto-triggers for LARGE tier plans. Configured via governance/runtime-policy.json.
-- **Stage C Final (Consolidated)**: Model Routing Stage C has fully landed. Stage D is a forward pointer only.
+- **Optional final review gate** via the `final_review_gate` policy flag — adds an opt-in Completion Gate sub-step that dispatches CodeReviewer with `review_scope=final` for holistic scope-drift detection. Auto-triggers for LARGE tier plans. Configured via `governance/runtime-policy.json`.
+- **Model Routing Stage C Matrix (Consolidated)**: Model Routing Stage C has fully landed. Stage D is a forward pointer only.
   - All 13 agents now declare `model_role:` frontmatter.
   - `governance/model-routing.json` extended with optional `by_tier` matrix (10 roles × 4 complexity tiers with `inherit_from: "default"` for non-divergent cases).
   - `evals/drift-checks.mjs` gained `validateModelRole` + `validateByTierShape`.
   - Drift-check suite grew from 23 → 34 (+11): 4 Check #1 model_role tests (A/B/C/D), 4 matrix-completeness tests (N1/N2/N3/positive), 3 reference-integrity tests (RI-1/RI-2/RI-3).
-  - Structural gained +1 (Check #1 real implementation).
-  - Total eval suite: 358 → 370.
   - VS Code runtime tolerance PASS recorded in `plans/artifacts/model-routing-stage-c/phase-1-spike-result.md`.
+- **ControlFlow Comprehensive Revision** — ten-phase revision and modernization program delivered per `plans/controlflow-comprehensive-revision-plan.md`:
+  - **Phase 1 — Researcher validation + `plans_classification`.** Evidence-first confirmation of all 10 audit findings and per-plan classification artifact gating downstream archival decisions.
+  - **Phase 2 — CodeMapper drift inventory.** Mechanical cross-reference of agent model pins, tool grants, schema references, skill registrations, executor-enum alignment, and PreFlect baseline line counts.
+  - **Phase 3 — Consistency fixes (relabel-only; archival gated).** Phase Executor Agents table reduced to 8 rows matching the `executor_agent` enum; three-way check-count reconciliation; in-place status relabels without destructive moves.
+  - **Phase 4 — Model Routing (logical-index-only; spike deferred).** Published `governance/model-routing.json` with 10 logical roles covering all 13 agents and `docs/agent-engineering/MODEL-ROUTING.md`. Runtime opt-in via agent frontmatter `model_role:` is held pending VS Code frontmatter-tolerance verification; drift Check #1 remains gated off.
+  - **Phase 5 — Observability & `trace_id` schema hardening.** UUIDv4 `trace_id` added as additive-optional field across 13 report / verdict / audit / discovery / research / clarification / plan schemas; `docs/agent-engineering/OBSERVABILITY.md` documents generation, propagation, and the NDJSON sink convention at `plans/artifacts/observability/<task-id>.ndjson`.
+  - **Phase 6 — Agentic Memory layering.** Three-layer memory model (session / task-episodic / repo-persistent) codified in `docs/agent-engineering/MEMORY-ARCHITECTURE.md`; `NOTES.md` scoped to repo-persistent state with reversible migration manifest.
+  - **Phase 7 — PreFlect canonicalization.** Single `skills/patterns/preflect-core.md` replaces per-agent PreFlect restatements with pointer + ≤5 domain lines; Orchestrator-enforced cross-plan entry gate against `plans/performance-optimization-plan.md`.
+  - **Phase 8 — SOTA pattern integration (additive, no budget compounding).** `skills/patterns/reflection-loop.md` (pre-retry hook; default disabled; draws from existing `retry_budgets`), `skills/patterns/budget-tracking.md` (`budget_defaults` orthogonal to `retry_budgets`), and `docs/agent-engineering/AGENT-AS-TOOL.md` (MCP forward-compatible input contract).
+  - **Phase 9 — Additive drift-detection evals.** Four new drift checks (roster ↔ enum bidirectional alignment, agent `Resources` ↔ schemas existence, cross-plan file-overlap with anchor-map gate, multi-doc check-count consistency) in `evals/tests/drift-detection.test.mjs`; `model_role` resolution check staged but gated off until Phase 4 spike re-enables it.
+  - **Phase 10 — README & engineering-docs refresh.** Measured-value badges, new Feature rows for the six shipped capabilities, and `docs/agent-engineering/README.md` index for the 14 engineering documents.
+
+### Changed
 
-### Changed - Model Routing
-
-- **Eval suite (410 checks)** — 227 structural + 78 behavior + 63 orchestration-handoff + 42 drift-detection. Advertised counts in `README.md`, `.github/copilot-instructions.md`, `CONTRIBUTING.md`, `evals/README.md`, `SECURITY.md`, and `.github/PULL_REQUEST_TEMPLATE.md` reconciled to the measured value and enforced by drift Check #5.
-
----
-
-## [Unreleased] — ControlFlow Comprehensive Revision
-
-Ten-phase revision and modernization program delivered per `plans/controlflow-comprehensive-revision-plan.md`.
-
-### Added - Comprehensive Revision
-
-- **Phase 1 — Researcher validation + `plans_classification`.** Evidence-first confirmation of all 10 audit findings and per-plan classification artifact gating downstream archival decisions.
-- **Phase 2 — CodeMapper drift inventory.** Mechanical cross-reference of agent model pins, tool grants, schema references, skill registrations, executor-enum alignment, and PreFlect baseline line counts.
-- **Phase 3 — Consistency fixes (relabel-only; archival gated).** Phase Executor Agents table reduced to 8 rows matching the `executor_agent` enum; three-way check-count reconciliation; in-place status relabels without destructive moves.
-- **Phase 4 — Model Routing (logical-index-only; spike deferred).** Published `governance/model-routing.json` with 10 logical roles covering all 13 agents and `docs/agent-engineering/MODEL-ROUTING.md`. Runtime opt-in via agent frontmatter `model_role:` is held pending VS Code frontmatter-tolerance verification; drift Check #1 remains gated off.
-- **Phase 5 — Observability & `trace_id` schema hardening.** UUIDv4 `trace_id` added as additive-optional field across 13 report / verdict / audit / discovery / research / clarification / plan schemas; `docs/agent-engineering/OBSERVABILITY.md` documents generation, propagation, and the NDJSON sink convention at `plans/artifacts/observability/<task-id>.ndjson`.
-- **Phase 6 — Agentic Memory layering.** Three-layer memory model (session / task-episodic / repo-persistent) codified in `docs/agent-engineering/MEMORY-ARCHITECTURE.md`; `NOTES.md` scoped to repo-persistent state with reversible migration manifest.
-- **Phase 7 — PreFlect canonicalization.** Single `skills/patterns/preflect-core.md` replaces per-agent PreFlect restatements with pointer + ≤5 domain lines; Orchestrator-enforced cross-plan entry gate against `plans/performance-optimization-plan.md`.
-- **Phase 8 — SOTA pattern integration (additive, no budget compounding).** `skills/patterns/reflection-loop.md` (pre-retry hook; default disabled; draws from existing `retry_budgets`), `skills/patterns/budget-tracking.md` (`budget_defaults` orthogonal to `retry_budgets`), and `docs/agent-engineering/AGENT-AS-TOOL.md` (MCP forward-compatible input contract).
-- **Phase 9 — Additive drift-detection evals.** Four new drift checks (roster ↔ enum bidirectional alignment, agent `Resources` ↔ schemas existence, cross-plan file-overlap with anchor-map gate, multi-doc check-count consistency) in `evals/tests/drift-detection.test.mjs`; `model_role` resolution check staged but gated off until Phase 4 spike re-enables it.
-- **Phase 10 — README & engineering-docs refresh.** Measured-value badges, new Feature rows for the six shipped capabilities, and `docs/agent-engineering/README.md` index for the 11 engineering documents.
-
-### Changed - Comprehensive Revision
-
-- **Eval suite (358 checks)** — 212 structural + 74 behavior + 49 orchestration-handoff + 23 drift-detection. Advertised counts in `README.md`, `.github/copilot-instructions.md`, `CONTRIBUTING.md`, `evals/README.md`, `SECURITY.md`, and `.github/PULL_REQUEST_TEMPLATE.md` reconciled to the measured value and enforced by drift Check #5.
-- Phase Executor Agents table reduced to 8 rows aligned with the `executor_agent` enum; AssumptionVerifier and ExecutabilityVerifier reclassified as review-only roles outside the executor enum.
+- **Codex Plugin Lifecycle**: Introduced fixed lifecycle sections (`## Progress`, `## Discoveries`, `## Decision Log`, `## Outcomes`, `## Idempotence & Recovery`) in strict-plan dialect, enforced by `validate-strict-artifacts.ps1`.
+- **Plugin First-Class Status**: Upgraded `controlflow-codex` to a first-class plugin deliverable in `AGENTS.md` and `README.md`.
+- **Eval suite count reconciliation** — Advertised eval counts in `README.md`, `.github/copilot-instructions.md`, `CONTRIBUTING.md`, `evals/README.md`, `SECURITY.md`, and `.github/PULL_REQUEST_TEMPLATE.md` were reconciled to the measured value. There is no live count-enforcement pass; the current total is reported by `cd evals && npm test`.
+- **Phase Executor Agents table** reduced to 8 rows aligned with the `executor_agent` enum; AssumptionVerifier and ExecutabilityVerifier reclassified as review-only roles outside the executor enum.
 
 ### Notes
 

CONTRIBUTING.md

@@ -10,6 +10,8 @@ Thank you for your interest in contributing! This guide covers the key contribut
   - [Adding a new agent](#adding-a-new-agent)
   - [Editing an existing agent](#editing-an-existing-agent)
   - [Adding skills](#adding-skills)
+  - [Adding or modifying eval scenarios and validator passes](#adding-or-modifying-eval-scenarios-and-validator-passes)
+  - [Editing governance configuration (`governance/*.json`)](#editing-governance-configuration-governancejson)
   - [Proposing changes](#proposing-changes)
   - [Code of conduct](#code-of-conduct)
 
@@ -60,8 +62,10 @@ npm run test:behavior
    - `ABSTAIN` / `NEEDS_INPUT` / failure classification behavior
    - Tool routing compliance if the agent uses external tools
 
-5. **Register the agent in governance files**:
-   - Add it to `governance/agent-grants.json` with its canonical tool grants.
+5. **Register the agent in governance files** (see AGENTS.md §4 editing checklist):
+   - Add it to `governance/agent-grants.json` with its canonical agent/tool grants.
+   - Add it to `governance/tool-grants.json` when the agent's tool surface changes — the eval suite enforces consistency.
+   - Update `governance/runtime-policy.json` and `governance/rename-allowlist.json` where relevant (e.g. review routing/retry knobs or rename permissions).
    - Add it to `plans/project-context.md` (agent roster table).
 
 6. **Update `README.md`**:
@@ -93,6 +97,24 @@ For project-wide orchestration audits, prefer `skills/patterns/orchestration-aud
 
 ---
 
+## Adding or modifying eval scenarios and validator passes
+
+The eval suite is the only verification gate (`cd evals && npm test`).
+
+1. Scenario fixtures live in `evals/scenarios/`; add or edit the fixture that exercises the behavior, validated against the matching schema in `schemas/`.
+2. Validator passes live in `evals/validate.mjs` (structural/schema/P.A.R.T) and drift checks in `evals/drift-checks.mjs`. Add a pass only when an existing one cannot express the contract; keep new passes offline and network-free.
+3. Run `cd evals && npm test` (or the faster `test:structural` / `test:behavior`) and confirm green before opening a PR. See `evals/README.md` for pass descriptions.
+
+---
+
+## Editing governance configuration (`governance/*.json`)
+
+1. Most knobs in `governance/` are referenced by Orchestrator/Planner prompt text — re-read the consumers and update the prompt wording when knob semantics change (per AGENTS.md §4).
+2. Keep grants consistent: `governance/agent-grants.json` and `governance/tool-grants.json` are enforced against agent frontmatter by the eval suite.
+3. Run `cd evals && npm test` after any governance edit to catch drift — changes here affect all agents.
+
+---
+
 ## Contributing to Plugins (Codex and Claude Code)
 
 Changes to files under `plugins/controlflow-codex/` and `plugins/controlflow-claude-code/` require their own validation in addition to the repository eval suite:

CodeReviewer-subagent.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Review code changes from a completed implementation phase.'
 tools: ['search', 'usages', 'problems', 'changes', 'runCommands', 'runTasks', 'read/readFile']
-model: Claude Opus 4.7 (copilot)
+model: Claude Opus 4.8 (copilot)
 model_role: capable-reviewer
 ---
 You are CodeReviewer-subagent, the deterministic verification gate.
@@ -132,6 +132,7 @@ Agent-specific additions: _none_
 - `schemas/code-reviewer.verdict.schema.json`
 - `schemas/orchestrator.gate-event.schema.json`
 - `plans/project-context.md` (if present)
+- `skills/patterns/llm-behavior-guidelines.md` (load on non-trivial tasks — anti-pattern guardrails: scope drift, over-abstraction, silent assumptions, weak success criteria)
 
 ## Tools
 

CoreImplementer-subagent.agent.md

@@ -76,6 +76,7 @@ Agent-specific fields:
 - `schemas/core-implementer.execution-report.schema.json`
 - `plans/project-context.md` (if present)
 - `docs/agent-engineering/TOOL-ROUTING.md`
+- `skills/patterns/llm-behavior-guidelines.md` (load on non-trivial tasks — anti-pattern guardrails: scope drift, over-abstraction, silent assumptions, weak success criteria)
 
 ## Tools
 

NOTES.md

@@ -2,6 +2,6 @@
 
 Repo-persistent active-objective state only. See `docs/agent-engineering/MEMORY-ARCHITECTURE.md` for the three-layer memory model; task-episodic history lives under `plans/artifacts/<task-slug>/`.
 
-- Active objective: capability-matrix registry follow-up cleanup is complete; runtime uses registry metadata and strict file-level anchor-map coverage.
+- Active objective: comprehensive cleanup effort is complete; full eval gate (`cd evals && npm test`) is green.
 - Blockers: none.
 - Pending: optional follow-up to investigate pre-existing capability-matrix live-tree drift flags surfaced by the smoke test.

PlanAuditor-subagent.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Adversarial plan reviewer that audits architecture, security, and risk coverage before implementation begins.'
 tools: ['read/readFile', 'read/problems', 'search/codebase', 'search/fileSearch', 'search/textSearch', 'search/listDirectory', 'search/usages']
-model: Claude Opus 4.7 (copilot)
+model: Claude Opus 4.8 (copilot)
 model_role: capable-reviewer
 ---
 You are PlanAuditor-subagent, the adversarial plan auditor.

Planner.agent.md

@@ -114,6 +114,7 @@ Agent-specific additions:
 - `docs/agent-engineering/PROMPT-BEHAVIOR-CONTRACT.md`
 - `plans/project-context.md` (if present)
 - `skills/index.md` (domain skill mapping — read during Step 5)
+- `skills/patterns/llm-behavior-guidelines.md` (load on non-trivial tasks — anti-pattern guardrails: scope drift, over-abstraction, silent assumptions, weak success criteria)
 - Plan artifacts directory: `plans/` (default location for all plan and completion files)
 
 ## Tools