feat: add bug finder and managed workflow routing

.github/workflows/ci.yml

@@ -35,7 +35,7 @@ jobs:
         run: python .github/render_social_preview.py
 
       - name: Validate skill pack
-        run: python scripts/validate_skill_pack.py . --as-of 2026-08-16
+        run: python scripts/validate_skill_pack.py . --as-of 2026-08-17
 
       - name: Verify anti-slop vendor integrity
         run: python scripts/verify_anti_slop_vendor.py .
@@ -47,37 +47,83 @@ jobs:
         run: python scripts/verify_release_metadata.py .
 
       - name: Run helper smoke tests
-        run: python scripts/run_smoke_tests.py . --as-of 2026-08-16
+        run: python scripts/run_smoke_tests.py . --as-of 2026-08-17
 
-      - name: Validate updater scripts
+      - name: Validate installer and updater scripts
         run: |
           node --check bin/install.mjs
+          node --check bin/toolkit.mjs
           node --check scripts/auto-update-runner.mjs
 
       - name: Inspect package contents
-        run: npm pack --dry-run
+        shell: bash
+        run: |
+          npm pack --dry-run 2>&1 | tee "$RUNNER_TEMP/npm-pack.txt"
+          grep -F 'bin/toolkit.mjs' "$RUNNER_TEMP/npm-pack.txt"
+          grep -F 'orchestration/managed-agents.md' "$RUNNER_TEMP/npm-pack.txt"
+          grep -F 'orchestration/workflows.md' "$RUNNER_TEMP/npm-pack.txt"
 
-      - name: Test full toolkit installer in isolation
+      - name: Test full toolkit installer and managed routing in isolation
         shell: bash
         run: |
+          set -euo pipefail
           temp_home="$(mktemp -d)"
-          node bin/install.mjs setup --no-auto-update --codex-home "$temp_home"
-          test "$(find "$temp_home/skills" -mindepth 2 -maxdepth 2 -name SKILL.md | wc -l)" -eq 19
+          cat > "$temp_home/AGENTS.md" <<'EOF'
+          # User instructions
+
+          Keep this user-authored rule exactly present.
+          EOF
+
+          node bin/toolkit.mjs setup --no-auto-update --codex-home "$temp_home"
+          test "$(find "$temp_home/skills" -mindepth 2 -maxdepth 2 -name SKILL.md | wc -l)" -eq 20
           test "$(find "$temp_home/agents" -maxdepth 1 -name '*.toml' | wc -l)" -eq 6
+          test -f "$temp_home/codex-toolkit/workflows.md"
+          grep -F 'Keep this user-authored rule exactly present.' "$temp_home/AGENTS.md"
+          test "$(grep -c '<!-- codex-toolkit:start -->' "$temp_home/AGENTS.md")" -eq 1
+          test "$(grep -c '<!-- codex-toolkit:end -->' "$temp_home/AGENTS.md")" -eq 1
+          grep -F 'bug-finder' "$temp_home/AGENTS.md"
+          grep -F 'Bug hunt — unknown defects' "$temp_home/codex-toolkit/workflows.md"
+
+          agents_before="$(sha256sum "$temp_home/AGENTS.md" | cut -d' ' -f1)"
+          workflows_before="$(sha256sum "$temp_home/codex-toolkit/workflows.md" | cut -d' ' -f1)"
+          node bin/toolkit.mjs setup --no-auto-update --codex-home "$temp_home"
+          test "$agents_before" = "$(sha256sum "$temp_home/AGENTS.md" | cut -d' ' -f1)"
+          test "$workflows_before" = "$(sha256sum "$temp_home/codex-toolkit/workflows.md" | cut -d' ' -f1)"
+          test "$(grep -c '<!-- codex-toolkit:start -->' "$temp_home/AGENTS.md")" -eq 1
+
+      - name: Verify malformed managed markers fail closed
+        shell: bash
+        run: |
+          set -euo pipefail
+          temp_home="$(mktemp -d)"
+          cat > "$temp_home/AGENTS.md" <<'EOF'
+          # Existing user instructions
+          preserve-me
+          <!-- codex-toolkit:start -->
+          incomplete managed block
+          EOF
+          before="$(sha256sum "$temp_home/AGENTS.md" | cut -d' ' -f1)"
+          if node bin/toolkit.mjs setup --no-auto-update --codex-home "$temp_home"; then
+            echo "setup unexpectedly accepted malformed managed markers" >&2
+            exit 1
+          fi
+          test "$before" = "$(sha256sum "$temp_home/AGENTS.md" | cut -d' ' -f1)"
+          grep -F 'preserve-me' "$temp_home/AGENTS.md"
 
       - name: Test legacy Mission Control installer
         shell: bash
         run: |
           temp_home="$(mktemp -d)"
-          node bin/install.mjs --codex-home "$temp_home"
+          node bin/toolkit.mjs --codex-home "$temp_home"
           test -f "$temp_home/skills/delegate-with-mission-cards/SKILL.md"
           test "$(find "$temp_home/agents" -maxdepth 1 -name '*.toml' | wc -l)" -eq 6
+          test ! -e "$temp_home/AGENTS.md"
 
       - name: Validate automatic-update scheduler plan
         shell: bash
         run: |
           temp_home="$(mktemp -d)"
-          node bin/install.mjs auto-update install --dry-run --codex-home "$temp_home"
+          node bin/toolkit.mjs auto-update install --dry-run --codex-home "$temp_home"
 
       - name: Validate release-pinned update runner
         shell: bash
@@ -95,9 +141,9 @@ jobs:
           cat > "$runner_dir/state.json" <<'JSON'
           {
             "schema_version": 1,
-            "release": "v0.6.0"
+            "release": "v0.7.0"
           }
           JSON
-          node "$runner_dir/update-runner.mjs" --dry-run --tag v0.7.0 | tee "$runner_dir/plan.txt"
-          grep -F 'github:cmdr-chara/codex-toolkit#v0.7.0' "$runner_dir/plan.txt"
+          node "$runner_dir/update-runner.mjs" --dry-run --tag v0.8.0 | tee "$runner_dir/plan.txt"
+          grep -F 'github:cmdr-chara/codex-toolkit#v0.8.0' "$runner_dir/plan.txt"
           grep -F '"setup"' "$runner_dir/plan.txt"

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.8.0 - 2026-08-17
+
+- Add `bug-finder` for proactive discovery of previously unknown correctness defects using explicit invariants, high-risk surface prioritization, and proof/falsification before confirmation.
+- Separate unknown-defect discovery from causal debugging: confirmed bug candidates hand off to `debugging-investigator` only when their root-cause chain or minimal explanatory fix is still uncertain.
+- Add managed global workflow routing to full `setup`: preserve user-authored `AGENTS.md` content outside a Codex Toolkit managed block and install the conditional workflow catalog under the active `CODEX_HOME`.
+- Make routing updates follow the existing release-pinned auto-updater, so new skills and workflow changes arrive together without following unreleased `main` commits.
+- Add fail-closed marker validation, conflict backups, idempotent routing synchronization, package checks, and CI coverage for twenty installable skills and nineteen production routes.
+
 ## 0.7.0 - 2026-08-17
 
 - Add a zero-maintenance `setup` command that installs all toolkit skills and Mission Control into Codex and registers automatic updates.

README.md

@@ -1,17 +1,17 @@
 # Codex Toolkit
 
-> Nineteen focused Codex skills for understanding, changing, and verifying real software projects.
+> Twenty focused Codex skills for understanding, changing, and verifying real software projects.
 
 [![CI](https://github.com/cmdr-chara/codex-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/cmdr-chara/codex-toolkit/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-0ea5e9.svg)](LICENSE)
-[![Skills](https://img.shields.io/badge/Codex_skills-19-7c3aed.svg)](skills)
+[![Skills](https://img.shields.io/badge/Codex_skills-20-7c3aed.svg)](skills)
 [![Custom agents](https://img.shields.io/badge/custom_agents-6-f97316.svg)](agents/mission-control)
 
 <p align="center">
-  <img src=".github/assets/codex-toolkit-social-preview.png" width="900" alt="Codex Toolkit: Inspect. Change. Prove. Nineteen Codex skills and six optional agents." />
+  <img src=".github/assets/codex-toolkit-social-preview.png" width="900" alt="Codex Toolkit: Inspect. Change. Prove. Twenty Codex skills and six optional agents." />
 </p>
 
-Codex can write code without this toolkit. These skills help with the harder parts around the code: understanding an unfamiliar system, choosing the right change, finding failures, controlling scope, finishing work completely, and proving that a release is ready.
+Codex can write code without this toolkit. These skills help with the harder parts around the code: understanding an unfamiliar system, choosing the right change, finding unknown defects, explaining failures, controlling scope, finishing work completely, and proving that a release is ready.
 
 ## Install
 
@@ -21,9 +21,19 @@ Codex can write code without this toolkit. These skills help with the harder par
 npx --yes github:cmdr-chara/codex-toolkit setup
 ```
 
-That one command installs all nineteen skills, the six Mission Control agents, and a user-level auto-updater. After that, the operating system checks for the **latest published GitHub Release** automatically. New toolkit skills are picked up too; unreleased commits on `main` are never installed by the updater.
+That one command installs all twenty skills, the six Mission Control agents, a small managed routing block in your global Codex `AGENTS.md`, the detailed workflow catalog under `~/.codex/codex-toolkit/workflows.md`, and a user-level auto-updater.
 
-Changed local toolkit files are backed up before replacement. There is no always-running daemon.
+After that, the operating system checks for the **latest published GitHub Release** automatically. New toolkit skills and routing/workflow updates are picked up too; unreleased commits on `main` are never installed by the updater.
+
+The installer never replaces your whole `AGENTS.md`. It owns only the section between:
+
+```text
+<!-- codex-toolkit:start -->
+...
+<!-- codex-toolkit:end -->
+```
+
+Everything outside that block is preserved. If the markers are malformed or duplicated, setup stops instead of guessing. Changed local toolkit files are backed up before replacement. There is no always-running daemon.
 
 Check or disable the updater at any time:
 
@@ -32,7 +42,7 @@ npx --yes github:cmdr-chara/codex-toolkit auto-update status
 npx --yes github:cmdr-chara/codex-toolkit auto-update remove
 ```
 
-See [Automatic updates](docs/auto-update.md) for Windows, macOS, Linux, custom `CODEX_HOME`, and scheduler details.
+Disabling automatic updates leaves installed skills, Mission Control, and routing instructions in place. See [Automatic updates](docs/auto-update.md) for Windows, macOS, Linux, custom `CODEX_HOME`, and scheduler details.
 
 ### Install just one skill
 
@@ -48,7 +58,29 @@ Install one skill globally for Codex:
 npx skills add https://github.com/cmdr-chara/codex-toolkit --skill repository-intelligence -g -a codex
 ```
 
-`npx skills add` is still useful for selective installs, but it does not run this repository's auto-update setup. Use the recommended `setup` command when you want the whole toolkit to maintain itself.
+`npx skills add` is still useful for selective installs, but it does not install the toolkit's global workflow routing or auto-update setup. Use the recommended `setup` command when you want the whole toolkit to compose and maintain itself.
+
+## Automatic workflow routing
+
+With the full setup installed, you normally do **not** need to memorize skill names. The global managed instructions teach Codex to choose one primary specialist and add supporting skills only when their trigger becomes true.
+
+For example:
+
+```text
+Find and fix important bugs in this repository.
+```
+
+can route as:
+
+```text
+repository-intelligence? → bug-finder
+                         → debugging-investigator? (confirmed bug still needs causal proof)
+                         → owning implementation specialist?
+                         → unlazy? (substantial remediation)
+                         → verification-and-release? (integrated release candidate)
+```
+
+The question mark means conditional, not mandatory. Repository-local `AGENTS.md` rules remain authoritative for project-specific constraints. The full catalog is installed from [orchestration/workflows.md](orchestration/workflows.md).
 
 ## Pick a skill
 
@@ -57,12 +89,13 @@ npx skills add https://github.com/cmdr-chara/codex-toolkit --skill repository-in
 | What you need | Skill |
 | --- | --- |
 | Map an unfamiliar codebase or see what a change could affect | [repository-intelligence](skills/repository-intelligence) |
+| Find important bugs you do not know about yet | [bug-finder](skills/bug-finder) |
+| Find the root cause of a known bug or regression | [debugging-investigator](skills/debugging-investigator) |
 | Decide what the codebase should improve next | [codebase-improvement-planner](skills/codebase-improvement-planner) |
 | Tighten TypeScript types and lint rules without hiding errors | [typescript-quality-enforcer](skills/typescript-quality-enforcer) |
 | Inspect or remove hidden metadata from files you own | [content-provenance-hygiene](skills/content-provenance-hygiene) |
 | Finish a large, already-scoped task without stopping half-done | [unlazy](skills/unlazy) |
 | Review code or refactor it safely | [review-and-refactor-code](skills/review-and-refactor-code) |
-| Find the root cause of a bug or regression | [debugging-investigator](skills/debugging-investigator) |
 | Make a slow path faster using measurements | [optimize-codebase-performance](skills/optimize-codebase-performance) |
 | Upgrade a dependency, framework, API, schema, or runtime safely | [codebase-evolution-controller](skills/codebase-evolution-controller) |
 | Keep documentation in sync with code changes | [documentation-synchronizer](skills/documentation-synchronizer) |
@@ -86,14 +119,15 @@ npx skills add https://github.com/cmdr-chara/codex-toolkit --skill repository-in
 | Split a large task across agents without write conflicts | [multi-agent-work-coordinator](skills/multi-agent-work-coordinator) |
 | Send approved tasks to the toolkit's custom reader/writer agents | [delegate-with-mission-cards](skills/delegate-with-mission-cards) |
 
-Use the smallest skill that owns the decision in front of you. `unlazy` is cross-cutting: it can make a substantial task's finish line explicit, but it cannot override another skill's safety or approval boundary.
+Use the smallest skill that owns the decision in front of you. `bug-finder` owns unknown-defect discovery; `debugging-investigator` owns the causal explanation of a concrete failure. `unlazy` is cross-cutting: it can make a substantial task's finish line explicit, but it cannot override another skill's safety or approval boundary.
 
 ## Common workflows
 
-- Unfamiliar repository → `repository-intelligence` → the specialist that owns the change.
-- “What should we improve?” → `codebase-improvement-planner` → the chosen specialist.
-- Bug → `debugging-investigator` → focused fix → `verification-and-release`.
-- Refactor → `review-and-refactor-code` → approval → incremental refactor.
+- Unknown bugs → `repository-intelligence?` → `bug-finder` → `debugging-investigator?` → bounded fix → `unlazy?` → `verification-and-release?`.
+- Known bug → `repository-intelligence?` → `debugging-investigator` → focused fix → `verification-and-release?`.
+- Unfamiliar repository change → `repository-intelligence` → the specialist that owns the change.
+- “What should we improve?” → `repository-intelligence` → `codebase-improvement-planner` → the chosen specialist.
+- Refactor → `review-and-refactor-code` → approval → incremental refactor → `unlazy?`.
 - Slow path → `optimize-codebase-performance` → approval → measured optimization.
 - Framework/API/schema upgrade → `codebase-evolution-controller` → `documentation-synchronizer` → `verification-and-release`.
 - New product direction → `product-design-director` → web/mobile implementation skill.
@@ -142,15 +176,20 @@ Each skill is an installable folder with:
 - optional references for deeper guidance;
 - optional read-only scripts for deterministic inspection.
 
+The full installer also carries:
+
+- `orchestration/managed-agents.md` — the short global routing policy inserted into the managed `AGENTS.md` block;
+- `orchestration/workflows.md` — conditional multi-skill workflows installed under the active `CODEX_HOME`.
+
 Skills remain independently installable. External integrations are explicit and operator-controlled rather than hidden shared runtime dependencies.
 
 ## Check the toolkit
 
 The checks run without network access and do not modify their fixture projects.
 
 ```sh
-python scripts/validate_skill_pack.py . --as-of 2026-08-16
-python scripts/run_smoke_tests.py . --as-of 2026-08-16
+python scripts/validate_skill_pack.py . --as-of 2026-08-17
+python scripts/run_smoke_tests.py . --as-of 2026-08-17
 ```
 
 CI also:
@@ -159,6 +198,8 @@ CI also:
 - renders and verifies release metadata/social preview;
 - inspects the npm package contents;
 - installs the full toolkit into an isolated temporary Codex home;
+- verifies that setup preserves user-authored `AGENTS.md` content and is idempotent;
+- verifies malformed managed markers fail closed;
 - verifies the auto-update installation plan without registering a real scheduler on the runner.
 
 See [the evaluation guide](evaluations/README.md) for routing and workflow tests.
@@ -170,8 +211,9 @@ See [the evaluation guide](evaluations/README.md) for routing and workflow tests
 | agents | Six optional Mission Control agents |
 | docs | Design decisions, boundaries, updater docs, and research sources |
 | evaluations | Routing, overlap, workflow, and smoke-test cases |
+| orchestration | Managed global routing instructions and multi-skill workflow catalog |
 | scripts | Installers, update runner, and validation tools |
-| skills | Nineteen installable skills |
+| skills | Twenty installable skills |
 
 ## Research and credit
 
@@ -185,7 +227,7 @@ The TypeScript quality enforcer vendors the deterministic Oxlint runtime from Di
 
 Content provenance hygiene was designed after inspecting Guillaume Meyer's MIT-licensed `watermarks-remover` service and skill. Codex Toolkit does not vendor that runtime; the optional protocol reference is pinned in [skills/content-provenance-hygiene/references/service-protocol.md](skills/content-provenance-hygiene/references/service-protocol.md).
 
-The code-review, refactoring, performance, and codebase-improvement skills were independently authored after inspecting an unlicensed public skill collection. No source prose or code was copied. The research record is in [docs/research-ledger.md](docs/research-ledger.md).
+The code-review, refactoring, performance, codebase-improvement, and bug-finder skills are toolkit-authored workflows. No third-party runtime is vendored for `bug-finder`.
 
 ## Contributing