docs(be38-5524): update CLAUDE.md for refined onboarding and architect-foundation

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

Author: JoeOakhartNava

CLAUDE.md

@@ -78,6 +78,8 @@ RED test escalation: `dso:red-test-writer` → `dso:red-test-evaluator` triage 
 **Tiered review**: `review-complexity-classifier.sh` scores diffs on 7 factors; 0–2 → light (haiku), 3–6 → standard (sonnet), 7+ → deep (3 parallel sonnet + opus synthesis). Diff: 300+ lines → opus upgrade, 600+ → rejection; merge commits bypass size limits. See `plugins/dso/docs/contracts/classifier-tier-output.md`. **Review dimensions**: `correctness`, `verification`, `hygiene`, `design`, `maintainability` in `reviewer-findings.json`.
 **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, onboarding, architect-foundation, design-review, design-wireframe, ui-discover, debug-everything, sprint, brainstorm, preplanning, implementation-plan, fix-bug (replaces tdd-workflow for bug fixes), tdd-workflow (new feature TDD only), etc. Commands: commit, end, review. Invocation: `/dso:skill-name` (qualified, required) or `/skill-name` (alias). **Namespace policy**: in-scope files MUST use `/dso:<skill-name>`. Enforced by `check-skill-refs.sh` (fatal in `validate.sh`); `qualify-skill-refs.sh` for bulk migration. Config: `.claude/dso-config.conf` (flat KEY=VALUE; keys: `format.*`, `ci.*`, `commands.*`, `jira.*`, `design.*`, `tickets.*`, `merge.*`, `version.*`, `test.*`). Test suites: `project-detect.sh --suites [REPO_ROOT]` for discovery. CI workflow generation: see `/dso:onboarding` skill.
+**Onboarding** (`/dso:onboarding`): Phase 1 auto-detects project configuration from files (`project-detect.sh`, `package.json`, `pyproject.toml`, `.husky/`, `.github/workflows/`, test directories) before asking any questions; detected values are presented for confirmation rather than re-discovered from scratch. Phase 3 initializes enforcement infrastructure for the host project: installs git pre-commit hooks (Husky / pre-commit framework / bare `.git/hooks/` — detected automatically), initializes the ticket system (orphan `tickets` branch + `.tickets-tracker/` + smoke test), generates `.test-index` via `generate-test-index.sh`, generates a host-project `CLAUDE.md` with ticket command references, and copies the `KNOWN-ISSUES` template. Both the `project-understanding.md` artifact and `dso-config.conf` are presented for user review before writing; existing files show a diff so no prior configuration is silently overwritten.
+**Architect-foundation** (`/dso:architect-foundation`): Reads `.claude/project-understanding.md` written by `/dso:onboarding` and skips questions already answered there. Phase 2.5 (Recommendation Synthesis) synthesizes findings into concrete, project-specific enforcement recommendations — each recommendation cites the specific project file or pattern that triggered it (e.g., "Because `src/adapters/db.py` directly imports `domain/models.py`, recommend enforcing the adapter boundary as a fitness function"). Recommendations are presented one at a time for the user to accept, reject, or discuss. Phase 2.75 presents every artifact for user review before writing; existing files (such as `CLAUDE.md` or `ARCH_ENFORCEMENT.md`) show a diff rather than a full replacement.
 Config keys: `ci.workflow_name` (GitHub Actions workflow; preferred over deprecated `merge.ci_workflow_name`), `merge.visual_baseline_path` (snapshot dir), `merge.message_exclusion_pattern` (default `^chore: post-merge cleanup`), `version.file_path` (semver file; `.json`/`.toml`/plaintext; absent = skip bumping). Source of truth: `plugins/dso/scripts/merge-to-main.sh`. Phases: `sync → merge → version_bump → validate → push → archive → ci_trigger`; state file at `/tmp/merge-to-main-state-<branch>.json` (4h TTL) for `--resume`; SIGURG saves current phase. **Plugin portability**: path assumptions config-driven via `.claude/dso-config.conf`. **Host project invocation**: `.claude/scripts/dso <script-name>` shim; install via `bash plugins/dso/scripts/dso-setup.sh [TARGET_REPO]`.
 
 The pre-commit review gate (`pre-commit-review-gate.sh`) handles merge commits (`MERGE_HEAD`) natively — when MERGE_HEAD exists, it computes the merge base and filters out incoming-only files (files changed on main but not on the worktree branch) from review consideration, since those were already reviewed on main. Fail-safe: if MERGE_HEAD equals HEAD or merge-base computation fails, normal review enforcement applies.