docs(bbba-8154): batch 8 — update CLAUDE.md with planning resilience agents and workflow gates

Document 4 new dedicated agents (feasibility-reviewer, red-team-reviewer,
blue-team-filter, completion-verifier) in architecture section. Add
complexity evaluator new fields (pattern_familiarity, external_boundary_count,
feasibility_review_recommended). Note 6-category adversarial review taxonomy
and artifact persistence.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: JoeOakhartNava

CLAUDE.md

@@ -22,7 +22,7 @@ Task type → Action:
 
 **`/dso:implementation-plan` gap analysis**: COMPLEX stories get opus gap analysis (Step 6); TRIVIAL stories skip. See skill for details.
 
-**`/dso:preplanning` adversarial review**: Epics with 3+ stories get red team + blue team adversarial review (adversarial review phase). See skill for details.
+**`/dso:preplanning` adversarial review**: Epics with 3+ stories get red team + blue team adversarial review (adversarial review phase). Red team uses 6 taxonomy categories (Consumer Impact, Operational Readiness, and 4 others); full exchange persists to `$ARTIFACTS_DIR/adversarial-review-<epic-id>.json`. See skill for details.
 
 ## Quick Reference
 
@@ -60,7 +60,7 @@ Priority: 0-4 (0=critical, 4=backlog). Never use "high"/"medium"/"low".
 **Ticket system v3 (event-sourced)**: The ticket system uses an orphan git branch named `tickets` mounted as a worktree at `.tickets-tracker/`. All mutations append JSON event files to per-ticket directories; the compiled state is produced on-demand by the Python reducer (`ticket-reducer.py`). Writes are serialized with `fcntl.flock` to prevent concurrent corruption. The primary CLI entry point is `ticket <subcommand>` (dispatcher at `plugins/dso/scripts/ticket`); the higher-level `tk-sync-lib.sh` library adds Jira sync, dependency trees, and human-friendly output. Full CLI reference: `plugins/dso/docs/ticket-cli-reference.md`. **Jira bridge**: `.claude/scripts/dso ticket sync` (incremental default, `--full` to force, `--check` for dry-run). Requires `JIRA_URL`, `JIRA_USER`, `JIRA_API_TOKEN`.
 **Hook architecture**: Consolidated dispatchers (2 processes per Bash tool call: `pre-bash.sh` + `post-bash.sh`). All hooks are jq-free — use `parse_json_field`, `json_build`, and `python3` for JSON parsing. Hook optimization: `tool_logging` and `tool_use_guard` removed from per-call dispatchers; `validation_gate` removed from Edit/Write dispatchers (kept in pre-bash.sh); early-exit guards skip narrow hooks when command keywords don't match. Review workflow timing fix: hash capture occurs after auto-fix passes to prevent drift. On review gate mismatch, diagnostic dump writes to `$ARTIFACTS_DIR/mismatch-diagnostics-<timestamp>.log`; breadcrumb trail in `$ARTIFACTS_DIR/commit-breadcrumbs.log`. See `plugins/dso/hooks/dispatchers/` and `plugins/dso/hooks/lib/`. **Review gate (two-layer defense-in-depth)**: Layer 1 — `pre-commit-review-gate.sh` is a git pre-commit hook (registered in `.pre-commit-config.yaml`); uses `git diff --cached --name-only` for reliable staged-file detection (no command-string parsing); default-deny allowlist from `review-gate-allowlist.conf`; checks review-status file + diff hash; writes JSONL telemetry to `$ARTIFACTS_DIR/review-gate-telemetry.jsonl`; formatting-only hash mismatches self-heal by re-running `ruff format`. Layer 2 — `review-gate.sh` is a PreToolUse hook (thin wrapper around `review-gate-bypass-sentinel.sh`); blocks bypass vectors: `--no-verify`, `-n` on git commit, `core.hooksPath=` override, `git commit-tree`, direct `.git/hooks/` writes, direct writes/deletions to `test-gate-status` and `test-exemptions` (only `record-test-status.sh` and `record-test-exemption.sh` are authorized writers). Test suite: `bash tests/hooks/test-two-layer-review-gate.sh` (or via `bash tests/run-all.sh`). **test gate (two-layer defense-in-depth)**: Layer 1 — `pre-commit-test-gate.sh` is a git pre-commit hook (registered in `.pre-commit-config.yaml`); for each staged source file with an associated test (found via fuzzy matching or `.test-index`), verifies that `test-gate-status` in `$ARTIFACTS_DIR` is present, has `passed` on line 1, and has a matching `diff_hash`; files with no associated test are exempt. Test directories are configurable via `test_gate.test_dirs` in `.claude/dso-config.conf` (default: `tests/`). `.test-index` — a repo-root file for mapping source files to unconventionally-named tests; format: `source/path.ext: test/path1.ext, test/path2.ext` (one entry per line; `#` comments and blank lines ignored); associations from `.test-index` are unioned with fuzzy-match results; the hook self-heals by pruning stale entries (test paths that no longer exist on disk) atomically before each commit and auto-staging the result; `.test-index` is excluded from the diff hash (via `review-gate-allowlist.conf`) to prevent mismatch loops when pruning modifies it. **RED marker format**: `source/path.ext: test/path.ext [first_red_test_name]` — the optional `[marker]` after a test path marks the boundary between GREEN tests (already passing) and RED tests (not yet implemented); failures at or after `first_red_test_name` are tolerated (non-blocking), failures before it still block. RED tests must be placed at the end of the test file. **TDD workflow for agents**: When writing a TDD test for a not-yet-implemented feature, add the test at the end of the test file and add a `[test_name]` marker to the `.test-index` entry — e.g., `source/foo.sh: tests/test_foo.sh [test_new_feature]`. After implementation passes, remove the `[marker]` from `.test-index`. **Epic closure enforcement**: `.claude/scripts/dso ticket transition <epic-id> open closed` is blocked while any `[marker]` entries remain in `.test-index` — remove all RED markers before closing an epic. Layer 2 — `review-gate-bypass-sentinel.sh` blocks direct writes/deletions to `test-gate-status` and `test-exemptions`; only `record-test-status.sh` (authorized by COMMIT-WORKFLOW.md Step 3.5) and `record-test-exemption.sh` (for inherently slow tests, exit 124) may write these files.
 **Validation gate**: `validate.sh` writes state; hooks block sprint/epic if validation hasn't passed. `--verbose` for real-time progress.
-**Agent routing** (dynamic discovery): `discover-agents.sh` resolves routing categories (e.g., `test_fix_unit`, `complex_debug`) to the best available agent using `agent-routing.conf`. Optional plugins (feature-dev, error-debugging, playwright) are preferred when installed; all categories fall back to `general-purpose` with category-specific prompts from `prompts/fallback/<category>.md`. See `plugins/dso/docs/INSTALL.md` for optional plugin documentation. **Named-agent dispatch** (distinct from routing-category dispatch): dedicated plugin agents are dispatched directly via `subagent_type` — `dso:complexity-evaluator` (haiku; dispatched by `/dso:sprint` and `/dso:brainstorm`, read inline by `/dso:fix-bug` due to nesting constraints) and `dso:conflict-analyzer` (sonnet; dispatched by `/dso:resolve-conflicts`). The **tiered code-review agents** are also named-agent dispatched by `/dso:review` (REVIEW-WORKFLOW.md Step 4): `dso:code-reviewer-light` (haiku; light tier), `dso:code-reviewer-standard` (sonnet; standard tier), `dso:code-reviewer-deep-correctness` + `dso:code-reviewer-deep-verification` + `dso:code-reviewer-deep-hygiene` (three parallel sonnet agents; deep tier), and `dso:code-reviewer-deep-arch` (opus; deep tier architectural synthesis). **Tiered review system**: `plugins/dso/scripts/review-complexity-classifier.sh` scores each diff on 7 factors (`blast_radius`, `critical_path`, `anti_shortcut`, `staleness`, `cross_cutting`, `diff_lines`, `change_volume`); score 0–2 → light tier (haiku), 3–6 → standard tier (sonnet), 7+ → deep tier (3 parallel sonnet + opus arch synthesis); floor rules ensure sensitive changes get adequate scrutiny; diff size thresholds: 300+ lines → opus model upgrade, 600+ lines → rejection; merge commits bypass size limits. See `plugins/dso/docs/contracts/classifier-tier-output.md` and `plugins/dso/docs/contracts/classifier-size-output.md` for the classifier output contracts. **Review output schema** (5 dimensions): `correctness`, `verification`, `hygiene`, `design`, `maintainability` — these are the current dimension key names in `reviewer-findings.json`; light/standard tier agents score all five, deep tier sonnet agents each score a subset with N/A for the rest, and the opus arch agent synthesizes the final result. All these agents are defined in `plugins/dso/agents/` and are not resolved through `discover-agents.sh`.
+**Agent routing** (dynamic discovery): `discover-agents.sh` resolves routing categories (e.g., `test_fix_unit`, `complex_debug`) to the best available agent using `agent-routing.conf`. Optional plugins (feature-dev, error-debugging, playwright) are preferred when installed; all categories fall back to `general-purpose` with category-specific prompts from `prompts/fallback/<category>.md`. See `plugins/dso/docs/INSTALL.md` for optional plugin documentation. **Named-agent dispatch** (distinct from routing-category dispatch): dedicated plugin agents are dispatched directly via `subagent_type` — `dso:complexity-evaluator` (haiku; dispatched by `/dso:sprint` and `/dso:brainstorm`, read inline by `/dso:fix-bug` due to nesting constraints) and `dso:conflict-analyzer` (sonnet; dispatched by `/dso:resolve-conflicts`). The complexity evaluator also emits `pattern_familiarity`, `external_boundary_count`, and `feasibility_review_recommended` fields for integration risk assessment. Additional planning agents: `dso:feasibility-reviewer` (sonnet; dispatched by `/dso:brainstorm` as a conditional 4th fidelity reviewer for epics with external integration signals), `dso:red-team-reviewer` (opus; dispatched by `/dso:preplanning` Phase 2.5 adversarial review — dedicated agent replacing generic agent with prompted template; covers 6 taxonomy categories including Consumer Impact and Operational Readiness), `dso:blue-team-filter` (sonnet; dispatched by `/dso:preplanning` Phase 2.5 — replaces generic agent, persists full exchange to `$ARTIFACTS_DIR/adversarial-review-<epic-id>.json`), and `dso:completion-verifier` (sonnet; dispatched by `/dso:sprint` at story closure Step 10a and epic closure Phase 7 Step 0.75 — answers "did we build what the spec says?" by verifying success criteria for epics and done definitions for stories; test pass/fail, code quality, and lint are explicitly out of scope). The **tiered code-review agents** are also named-agent dispatched by `/dso:review` (REVIEW-WORKFLOW.md Step 4): `dso:code-reviewer-light` (haiku; light tier), `dso:code-reviewer-standard` (sonnet; standard tier), `dso:code-reviewer-deep-correctness` + `dso:code-reviewer-deep-verification` + `dso:code-reviewer-deep-hygiene` (three parallel sonnet agents; deep tier), and `dso:code-reviewer-deep-arch` (opus; deep tier architectural synthesis). **Tiered review system**: `plugins/dso/scripts/review-complexity-classifier.sh` scores each diff on 7 factors (`blast_radius`, `critical_path`, `anti_shortcut`, `staleness`, `cross_cutting`, `diff_lines`, `change_volume`); score 0–2 → light tier (haiku), 3–6 → standard tier (sonnet), 7+ → deep tier (3 parallel sonnet + opus arch synthesis); floor rules ensure sensitive changes get adequate scrutiny; diff size thresholds: 300+ lines → opus model upgrade, 600+ lines → rejection; merge commits bypass size limits. See `plugins/dso/docs/contracts/classifier-tier-output.md` and `plugins/dso/docs/contracts/classifier-size-output.md` for the classifier output contracts. **Review output schema** (5 dimensions): `correctness`, `verification`, `hygiene`, `design`, `maintainability` — these are the current dimension key names in `reviewer-findings.json`; light/standard tier agents score all five, deep tier sonnet agents each score a subset with N/A for the rest, and the opus arch agent synthesizes the final result. All these agents are defined in `plugins/dso/agents/` and are not resolved through `discover-agents.sh`.
 **Conflict avoidance** (multi-agent): Static file impact analysis, shared blackboard, agent discovery protocol, semantic conflict check — integrated into `/dso:sprint` and `/dso:debug-everything`.
 **This repo is the `dso` plugin.** Skills: interface-contracts, resolve-conflicts, tickets-health, design-onboarding, design-review, design-wireframe, ui-discover, debug-everything, sprint, brainstorm, preplanning, implementation-plan, fix-bug (canonical bug-fix workflow; replaces tdd-workflow for bug fixes), tdd-workflow (new feature TDD only), etc. Commands (commit, end, review) also come from the plugin. Skills are invoked as `/dso:skill-name` (fully qualified, required) or `/skill-name` (command alias, allowed but not preferred in docs). **Skill namespace qualification policy**: all skill invocations in in-scope files (plugins/dso/skills/, plugins/dso/docs/, plugins/dso/hooks/, plugins/dso/commands/, CLAUDE.md) MUST use the qualified `/dso:<skill-name>` form. `plugins/dso/scripts/check-skill-refs.sh` enforces this as a fatal CI check via `plugins/dso/scripts/validate.sh`; it exits non-zero when any unqualified reference is found. `plugins/dso/scripts/qualify-skill-refs.sh` is the one-shot bulk rewriter (idempotent) that transforms `/skill-name` → `/dso:skill-name` across all in-scope files — run it after adding new in-scope content with unqualified refs. Ticket scripts in `plugins/dso/scripts/` (`ticket` dispatcher, `tk-sync-lib.sh`, and 22+ utility scripts). Project-specific config in `.claude/dso-config.conf` (flat KEY=VALUE format; keys: `format.*`, `ci.*`, `commands.*`, `jira.*`, `design.*`, `tickets.*`, `merge.*`, `version.*`). `version.*` config keys: `version.file_path` (path to the file holding the project's semver string; absent = skip version bumping; supported formats: `.json` → `version` key, `.toml` → `version` field, plaintext/no-extension → single semver line). `test.*` config keys: `test.suite.<name>.command` (shell command to run the suite; config-only suites get `runner=config`), `test.suite.<name>.speed_class` (`fast|slow`; overrides auto-discovered default of `unknown`). Config entries merge with auto-discovered suites by name: config wins on explicitly set fields. Use `project-detect.sh --suites [REPO_ROOT]` to discover test suites — outputs a JSON array with `name`, `command`, `speed_class`, `runner` fields (exit 0 always). Heuristics in precedence order: config > Makefile `/^test[-_]/` > pytest dirs > npm scripts > bash runners. **CI workflow generation** (`/dso:project-setup`): when no `.github/workflows/*.yml` exist, `project-detect.sh --suites` feeds directly into `ci-generator.sh --suites-json <json> --output-dir .github/workflows/` to generate `ci.yml` (fast suites, pull_request trigger) and `ci-slow.yml` (slow suites, push-to-main trigger); YAML is validated via actionlint or `yaml.safe_load` before writing. For existing projects with uncovered suites, `/dso:project-setup` prompts the user for each suite: `fast-gate` (append job to gating workflow), `separate` (new workflow file), or `skip` (writes `test.suite.<name>.ci_placement=skip` to `.claude/dso-config.conf` to suppress future prompts). Non-interactive mode defaults fast suites to fast-gate and slow/unknown suites to separate.
 `ci.*` config keys: `ci.workflow_name` (GitHub Actions workflow name for `gh workflow run`; absent = skip post-push CI trigger recovery — **preferred** over deprecated `merge.ci_workflow_name`). `merge.*` config keys: `merge.visual_baseline_path` (path to snapshot dir; absent = skip baseline intent check), `merge.ci_workflow_name` (**deprecated** — use `ci.workflow_name` instead; `merge-to-main.sh` falls back to this key with a deprecation warning when `ci.workflow_name` is absent), `merge.message_exclusion_pattern` (regex passed to `grep -vE` when composing merge message; default `^chore: post-merge cleanup`). Source of truth: `plugins/dso/scripts/merge-to-main.sh`. Phased workflow: `sync → merge → version_bump → validate → push → archive → ci_trigger`; state file at `/tmp/merge-to-main-state-<branch>.json` (4h TTL) records completed phases for `--resume`; lock file at `/tmp/merge-to-main-lock-<hash>` prevents concurrent runs; SIGURG trap saves current phase to state file on interrupt. The `version_bump` phase runs `bump-version.sh --patch` when `version.file_path` is configured and `--bump` is passed (or bump mode is on); patch bumps happen at merge time, not commit time. **Plugin portability**: All host-project path assumptions (app dir, make targets, Python version) are config-driven via `.claude/dso-config.conf` — the plugin is portable to projects with different directory structures. **Host project script invocation**: Host projects call DSO scripts via `.claude/scripts/dso <script-name>` (shim). Install with `bash plugins/dso/scripts/dso-setup.sh [TARGET_REPO]` from the repo root; the shim resolves DSO_ROOT from `CLAUDE_PLUGIN_ROOT` env var or `dso.plugin_root` in `.claude/dso-config.conf`.