feat(be38-5524): GREEN — add infrastructure init and architect-foundation recommendations

JoeOakhartNava · claude · JoeOakhartNava · commit 502d9d58fe37 · 2026-03-27T15:12:49.000-07:00
Onboarding SKILL.md: Add infrastructure initialization with hook
installation (3 manager types, idempotency, git-common-dir), ticket
system init with orphan branch/push verification/smoke test,
generate-test-index.sh, CLAUDE.md with ticket commands, KNOWN-ISSUES
template, CI trigger strategy.

Architect-foundation SKILL.md: Add Phase 2.5 recommendation synthesis
with project file citations, per-recommendation accept/reject/discuss,
test isolation enforcement. Rewrite Phase 1 for Socratic dialogue.

40/40 + 14/14 tests pass.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/plugins/dso/skills/architect-foundation/SKILL.md b/plugins/dso/skills/architect-foundation/SKILL.md
@@ -31,6 +31,7 @@ Role: **Google Senior Staff Software Architect** specializing in Evolutionary Ar
 ```
 Flow: P0 (Read project-understanding.md) → P1 (Socratic gap-fill)
   → P2 (Blueprint + anti-pattern review)
+  → P2.5 (Recommendation Synthesis — synthesize findings, cite project files, per-recommendation interaction)
   → [user approves?] Yes: P3 (Enforcer Setup) → P4 (Peer Review) → Done
                      Adjust: → P2 (loop)
 ```
@@ -61,32 +62,36 @@ Flow: P0 (Read project-understanding.md) → P1 (Socratic gap-fill)
 
 Ask only the questions NOT already answered by `project-understanding.md`. Use Socratic dialogue — ask **one question at a time**, wait for the answer, then ask the next. Do not batch multiple questions. This single-question cadence ensures the user's answer to each question can inform which follow-up questions are relevant, avoiding wasted effort.
 
+**Dialogue style**: Use open-ended questions that invite the user to describe their situation, not closed menus that force a choice. Avoid rigid question formats: no multiple-choice menus, no lettered lists like (a)/(b)/(c). Instead, ask one open-ended question, listen to the answer, and ask a follow-up question tailored to what was revealed. No rigid menu-style prompts — they prevent the user from expressing nuance. Do not present multiple choice; invite narrative instead.
+
 ### Question Bank (ask only unanswered ones)
 
+For each gap, craft an open-ended question appropriate to the context. The examples below are starting points, not scripts. Ask follow-up questions based on what the user reveals.
+
 #### Group A: Abstraction Surface (enforcement-critical)
 
-**A1. Variants** — Will the system support multiple implementations of the same concept (multiple LLM providers, output formats, storage backends, payment gateways)? If yes, how many on Day 1 vs. planned?
+**A1. Variants** — Ask the user to describe whether the system will support multiple implementations of the same concept (e.g., multiple LLM providers, output formats, storage backends, payment gateways). Ask them to describe what Day 1 looks like vs. planned growth.
 - *Why this matters:* ≥2 variants → AP-3 (incomplete coverage) and AP-4 (parallel inheritance) risks. The blueprint must include a variant registry and abstract error hierarchy.
 
-**A2. Shared Mutable State** — Will components share state through a mutable object (pipeline state dict, request context, shared cache)? Or will state flow through immutable messages/events?
+**A2. Shared Mutable State** — Ask the user to describe how components will share state — whether through a mutable object (pipeline state dict, request context, shared cache) or through immutable messages/events. Ask follow-up questions about the points where state crosses component boundaries.
 - *Why this matters:* Shared mutable state → AP-1 (contract without enforcement) risk. The blueprint must specify the immutability mechanism.
 
-**A3. Configuration Complexity** — How many environment-specific settings do you expect (API keys, feature flags, service URLs, thresholds)? Is there an existing config pattern you want to follow?
+**A3. Configuration Complexity** — Ask the user to describe the configuration landscape: how many environment-specific settings they expect and whether there is an existing config pattern they want to follow.
 - *Why this matters:* >10 config values → AP-5 (config bypass) risk. The blueprint must centralize all configuration into a typed config system.
 
 #### Group B: Enforcement Preferences
 
-**B1. Enforcement style** — Do you prefer enforcement that fails at **edit time** (real-time linting via hooks), **test time** (fitness functions in the test suite), or **CI time** (pre-merge gate)? Which layer do you trust most to catch violations?
+**B1. Enforcement style** — Ask the user where they want enforcement failures to surface: at edit time (real-time linting via hooks), test time (fitness functions in the test suite), or CI time (pre-merge gate). Ask them to describe which layer they trust most.
 
-**B2. Anti-pattern risk tolerance** — Which anti-patterns concern you most for this project? (e.g., AP-1: contract without enforcement, AP-2: error hierarchy leakage, AP-3: incomplete coverage, AP-4: parallel inheritance, AP-5: config bypass). Are there project-specific anti-patterns we should add?
+**B2. Anti-pattern risk tolerance** — Ask the user which anti-patterns concern them most for this project and whether there are project-specific anti-patterns to add. Common ones: AP-1 (contract without enforcement), AP-2 (error hierarchy leakage), AP-3 (incomplete coverage), AP-4 (parallel inheritance), AP-5 (config bypass).
 
-**B3. Existing enforcement gaps** — Are there architectural rules the team already knows they want to enforce but hasn't yet? (e.g., "no direct DB calls from handlers", "all external I/O must be in adapters", "no `Any` types in domain layer")
+**B3. Existing enforcement gaps** — Ask the user to describe architectural rules the team already knows they want to enforce but hasn't codified yet (e.g., "no direct DB calls from handlers", "all external I/O must be in adapters", "no `Any` types in domain layer"). Ask follow-up questions to understand the history behind each rule.
 
 #### Group C: Blueprint Scope
 
-**C1. Blueprint depth** — Do you want a full system context diagram and directory structure, or just the enforcement layer on top of the existing structure?
+**C1. Blueprint depth** — Ask the user to describe the scope they want: full system context diagram and directory structure, or just the enforcement layer on top of the existing structure.
 
-**C2. ADR preference** — Should we generate Architecture Decision Records for choices already made, or only for new decisions introduced by this scaffolding session?
+**C2. ADR preference** — Ask the user whether they want Architecture Decision Records for choices already made, only for new decisions introduced by this scaffolding session, or both.
 
 ---
 
@@ -117,6 +122,44 @@ If the user requests adjustments, revise the blueprint and re-present. Do not pr
 
 ---
 
+## Phase 2.5: Recommendation Synthesis
+
+Before generating enforcement scaffolding, synthesize everything learned in Phases 0 and 1 into a concrete, project-specific set of enforcement recommendations. This synthesis step ensures the scaffolding reflects actual project patterns — not generic templates.
+
+### Synthesis Process
+
+1. **Gather signals**: Collect all facts from `project-understanding.md` and all answers from the Phase 1 Socratic dialogue.
+
+2. **Synthesize into recommendations**: For each proposed enforcement mechanism, synthesize a recommendation that:
+   - States what will be enforced and at which layer (edit-time, test-time, CI-time)
+   - **Cites the specific project file or pattern that triggered this recommendation** — e.g., "Because `src/adapters/db.py` exists and directly imports `domain/models.py`, recommend enforcing the adapter boundary as a fitness function" or "Because `config.py` reads 14 environment variables directly, recommend a typed config boundary"
+   - Explains why this recommendation fits this specific project (not just why it is generally good)
+   - Includes test isolation enforcement: each recommendation must specify how tests remain isolated from the enforcement mechanism itself (e.g., mock injection points, test-only config overrides, fixture boundaries). Test isolation is a first-class concern in every recommendation.
+
+3. **Present recommendations individually**: Present each recommendation one at a time. For each recommendation, the user may:
+   - **Accept** it (move to the next)
+   - **Reject** it (remove from the enforcement set)
+   - **Discuss** the recommendation further (ask follow-up questions, revise)
+   Allow the user to accept, reject, or discuss each recommendation individually before proceeding to the next.
+
+4. **Revise and confirm**: After the user has reviewed all recommendations, present a final consolidated list of accepted recommendations. Confirm before proceeding to Phase 3.
+
+### Recommendation Template
+
+```
+Recommendation N: [Short title]
+Trigger: [Specific project file or pattern that triggered this — cite file path or code pattern]
+Enforcement: [What will be enforced and at which layer]
+Fit: [Why this fits this project specifically]
+Test isolation: [How tests remain isolated]
+```
+
+### ARCH_ENFORCEMENT.md Compatibility
+
+The accepted recommendations from this phase will be materialized into `ARCH_ENFORCEMENT.md` at the repo root. This file is detected by `check-onboarding.sh` as evidence that architect-foundation scaffolding has been completed. Each accepted recommendation becomes a section in `ARCH_ENFORCEMENT.md`.
+
+---
+
 ## Phase 3: The Enforcer (Deterministic Guardrails)
 
 Treat "Architecture" as something that can be tested. Generate **Fitness Functions** and **enforcement infrastructure** using tools appropriate for the chosen stack. Architecture enforcement operates at multiple layers — each layer catches violations at a different point in the development cycle.
diff --git a/plugins/dso/skills/onboarding/SKILL.md b/plugins/dso/skills/onboarding/SKILL.md
@@ -558,6 +558,143 @@ Accept these values? [Y/n]
 
 Write `commands.acli_version` and `commands.acli_sha256` to `.claude/dso-config.conf` on acceptance.
 
+### Step 2c: Infrastructure Initialization
+
+After writing `.claude/dso-config.conf`, set up the supporting infrastructure for the host project. These steps ensure the enforcement gates, ticket system, and documentation templates are in place before the first commit.
+
+#### Hook Installation
+
+Install the DSO git pre-commit hooks (`pre-commit-test-gate.sh` and `pre-commit-review-gate.sh`) into the project's hooks directory. Hook installation must account for the detected hook manager:
+
+**Detect hook manager and install accordingly:**
+
+1. **Husky** — if `.husky/` exists, add DSO hook calls to `.husky/pre-commit` (create if absent). **Idempotency**: check whether the hook call already exists before appending to avoid duplicates on re-run:
+   ```bash
+   HOOKS_DIR="$REPO_ROOT/.husky"
+   grep -qF 'pre-commit-test-gate' "$HOOKS_DIR/pre-commit" 2>/dev/null || \
+     echo 'bash "$REPO_ROOT/plugins/dso/hooks/dispatchers/pre-commit-test-gate.sh"' >> "$HOOKS_DIR/pre-commit"
+   grep -qF 'pre-commit-review-gate' "$HOOKS_DIR/pre-commit" 2>/dev/null || \
+     echo 'bash "$REPO_ROOT/plugins/dso/hooks/dispatchers/pre-commit-review-gate.sh"' >> "$HOOKS_DIR/pre-commit"
+   ```
+
+2. **pre-commit framework** — if `.pre-commit-config.yaml` exists, add DSO hooks as local hooks in the config.
+
+3. **Bare `.git/hooks/`** — if neither Husky nor the pre-commit framework is detected, install directly into the git hooks directory. Use `git rev-parse --git-common-dir` to find the correct hooks path (supports worktrees and submodules where `.git` may be a file rather than a directory):
+   ```bash
+   GIT_COMMON_DIR=$(git rev-parse --git-common-dir)
+   HOOKS_DIR="$GIT_COMMON_DIR/hooks"
+   cp "$REPO_ROOT/plugins/dso/hooks/dispatchers/pre-commit-test-gate.sh" "$HOOKS_DIR/pre-commit-test-gate"
+   cp "$REPO_ROOT/plugins/dso/hooks/dispatchers/pre-commit-review-gate.sh" "$HOOKS_DIR/pre-commit-review-gate"
+   # Ensure the pre-commit hook calls both
+   PRECOMMIT_HOOK="$HOOKS_DIR/pre-commit"
+   if [[ ! -f "$PRECOMMIT_HOOK" ]]; then
+       echo '#!/usr/bin/env bash' > "$PRECOMMIT_HOOK"
+       chmod +x "$PRECOMMIT_HOOK"
+   fi
+   echo 'bash "$(git rev-parse --git-common-dir)/hooks/pre-commit-test-gate"' >> "$PRECOMMIT_HOOK"
+   echo 'bash "$(git rev-parse --git-common-dir)/hooks/pre-commit-review-gate"' >> "$PRECOMMIT_HOOK"
+   ```
+
+After hook installation, confirm with the user which hook manager was used and where the hooks were installed.
+
+#### Ticket System Initialization
+
+Initialize the DSO ticket system by creating an orphan branch and setting up the `.tickets-tracker/` directory:
+
+```bash
+# Create orphan branch for ticket event storage
+cd "$REPO_ROOT"
+git checkout --orphan tickets
+git rm -rf . --quiet 2>/dev/null || true
+mkdir -p .tickets-tracker
+echo "# DSO Ticket System" > .tickets-tracker/README.md
+git add .tickets-tracker/README.md
+git commit -m "chore: initialize ticket system"
+git checkout -  # return to previous branch
+```
+
+**Push verification:** After creating the orphan branch, push it to the remote and verify push success. If the push fails, warn the user:
+
+```bash
+if git push origin tickets 2>&1; then
+    echo "Ticket system initialized and pushed successfully."
+else
+    echo "WARNING: push to origin tickets failed. The ticket system is initialized locally but not synced to remote. Run 'git push origin tickets' when remote access is available."
+fi
+```
+
+#### Ticket Smoke Test
+
+After initialization, perform a ticket smoke test to verify the system works end-to-end. Create a test ticket and read it back:
+
+```bash
+# Smoke test: create and read a ticket
+TEST_ID=$(.claude/scripts/dso ticket create task "DSO smoke test — delete me" 2>/dev/null | grep -oE '[0-9a-f]{4}-[0-9a-f]{4}')
+if [[ -n "$TEST_ID" ]]; then
+    .claude/scripts/dso ticket show "$TEST_ID" > /dev/null 2>&1 && echo "Ticket smoke test PASSED (id: $TEST_ID)" || echo "WARNING: ticket smoke test failed — show returned non-zero"
+    .claude/scripts/dso ticket transition "$TEST_ID" open closed --reason="Fixed: smoke test cleanup" 2>/dev/null
+else
+    echo "WARNING: ticket smoke test failed — could not create test ticket"
+fi
+```
+
+#### Generate Test Index
+
+If test directories were detected during Phase 1 auto-detection, run `generate-test-index.sh` to build the initial `.test-index` file mapping source files to test files:
+
+```bash
+if [[ -n "$TEST_DIRS" ]]; then
+    bash "$REPO_ROOT/plugins/dso/scripts/generate-test-index.sh" "$REPO_ROOT" 2>/dev/null && \
+        echo "Test index generated." || \
+        echo "NOTE: generate-test-index.sh unavailable — create .test-index manually if needed."
+fi
+```
+
+#### Generate CLAUDE.md
+
+Generate a `CLAUDE.md` at the HOST PROJECT root (not the plugin's `CLAUDE.md`) using the `/dso:generate-claude-md` skill. This file should include:
+- Project-specific defaults drawn from `project-understanding.md` and `dso-config.conf`
+- Ticket command references (the ticket commands table: create, show, list, transition, etc.)
+- CI trigger strategy notes from the onboarding conversation (do NOT assume PR-based workflow)
+
+```
+Invoke: /dso:generate-claude-md
+```
+
+The generated `CLAUDE.md` must include a Quick Reference table of ticket commands so that future Claude sessions can manage work items without re-reading the full DSO documentation.
+
+#### Copy KNOWN-ISSUES Template
+
+Copy the DSO `KNOWN-ISSUES` template to `.claude/docs/` in the host project:
+
+```bash
+KNOWN_ISSUES_SRC="$REPO_ROOT/plugins/dso/docs/templates/KNOWN-ISSUES.md"
+KNOWN_ISSUES_DEST="$REPO_ROOT/.claude/docs/KNOWN-ISSUES.md"
+if [[ -f "$KNOWN_ISSUES_SRC" ]] && [[ ! -f "$KNOWN_ISSUES_DEST" ]]; then
+    mkdir -p "$REPO_ROOT/.claude/docs"
+    cp "$KNOWN_ISSUES_SRC" "$KNOWN_ISSUES_DEST"
+    echo "KNOWN-ISSUES template copied to .claude/docs/KNOWN-ISSUES.md"
+fi
+```
+
+#### CI Trigger Strategy
+
+Ask the user about the CI trigger strategy — do NOT assume a PR-based workflow:
+
+```
+What events should trigger CI? Common options:
+- Pull request (on open, sync, reopen)
+- Push to specific branches (e.g., main, develop)
+- Manual dispatch only
+- Scheduled (cron)
+
+This affects the ci.workflow_name setting and any generated workflow templates.
+```
+
+Record the CI trigger strategy in `dso-config.conf` under `ci.workflow_name` and in `.claude/project-understanding.md` under the CI section.
+
+---
+
 ### Step 3: Offer /dso:architect-foundation
 
 After writing `.claude/project-understanding.md`, offer the next step:
@@ -602,4 +739,4 @@ If the user says no or wants to continue manually, summarize what was learned an
 |-------|------|---------------|
 | 1: Auto-Detection | Pre-fill answers | Run project-detect.sh, initialize scratchpad temp file, summarize findings |
 | 2: Socratic Dialogue | Fill gaps in 7 areas | One question at a time, confirmation-based (not rigid menus), skip confirmed areas |
-| 3: Completion | Finalize and hand off | Present summary, write .claude/project-understanding.md (detected/user-stated tags), write .claude/design-notes.md (UI projects only: vision, archetypes, golden paths, visual language, accessibility), generate dso-config.conf (ticket prefix, CI workflow examples, ACLI_VERSION), offer /dso:architect-foundation |
+| 3: Completion | Finalize and hand off | Present summary, write .claude/project-understanding.md (detected/user-stated tags), write .claude/design-notes.md (UI projects only: vision, archetypes, golden paths, visual language, accessibility), generate dso-config.conf (ticket prefix, CI workflow examples, ACLI_VERSION), infrastructure init (hook install with Husky/pre-commit framework/.git/hooks manager detection, git-common-dir for worktree support, ticket system orphan branch + .tickets-tracker/ + push verification + smoke test, generate-test-index.sh, CLAUDE.md with ticket commands, KNOWN-ISSUES template, CI trigger strategy), offer /dso:architect-foundation |
