@eltonssouza/development-utility-kit 0.10.0

package/dashboard/public/content/manual/existing-project.en.md

@@ -0,0 +1,848 @@
+# Manual — Adopting an existing project
+
+> Picked up a legacy repo? Got an old Java/Spring/Angular codebase and want the
+> development-utility-kit harness without rewriting anything? This manual is for
+> you. Covers initial adoption, debt audit, safe first feature, stack migration,
+> and recurring template updates — without breaking production.
+
+## 1. Introduction
+
+**For whom**: dev who inherited a legacy project (Java 8/11/17 + Spring Boot
+2/3, Angular 14/15/16, RN 0.70+) and wants to adopt the `development-utility-kit`
+harness to get agents/skills, senior+ gate, brain-keeper
+running.
+
+**What this manual covers**:
+
+- Installing the harness on a project WITHOUT `.claude/`
+- Updating a project that ALREADY has `.claude/` (idempotent)
+- Batch adoption (multiple projects via `/active-project`)
+- Initial audit: structure, coverage, debt
+- First feature on a legacy codebase with a GREEN baseline
+- Stack migration (Java/Spring/Angular major versions)
+- Recurring template update when the plugin evolves
+- Antipatterns, troubleshooting, glossary
+
+**Prerequisites**:
+
+- Git installed, clean repository (commit or stash pending changes first)
+- Node.js >= 18 (for `npx @eltonssouza/development-utility-kit install`)
+- Cowork connected OR Claude Code CLI installed
+- Dedicated branch (`git checkout -b chore/adopt-harness` before touching anything)
+- Read/write access on the project directory
+
+**What's NOT here**: scaffolding a new project (use `backend.en.md`,
+`frontend.en.md`, `fullstack.en.md`, `mobile.en.md`). This manual is legacy only.
+
+## 2. 5-min onboarding — project WITHOUT `.claude/`
+
+Scenario: you cloned a legacy repo and want to plug in the harness for the first
+time.
+
+### 2.1 Preparation
+
+```bash
+cd C:\my-legacy-project
+
+# Confirm clean branch — installer does NOT touch dirty files
+git status
+
+# Dedicated branch for adoption (NEVER run on main/develop directly)
+git checkout -b chore/adopt-harness
+```
+
+### 2.2 Install via npx (recommended)
+
+```bash
+npx @eltonssouza/development-utility-kit install
+```
+
+Expected output:
+
+```text
+> development-utility-kit install
+> Detecting project type...
+✓ Detected type: fullstack (backend/pom.xml + frontend/angular.json)
+✓ Backup created at .claude.backup-2026-05-27T14-32-18/ (if .claude already existed)
+✓ .claude/agents/ — 25 agents installed
+✓ .claude/skills/ — 18 skills installed
+✓ .claude/settings.json — hooks configured
+✓ CLAUDE.md — generated/merged preserving Project Identity
+✓ docs/brain/ — provisioned if absent
+✓ Install completed in 3.2s
+
+Next step: edit CLAUDE.md → ## Project Identity with the REAL current state of the project.
+```
+
+### 2.3 Install via global binary
+
+If you've already run `npx @eltonssouza/development-utility-kit install` on the
+host and have `duk` on PATH:
+
+```bash
+cd C:\my-legacy-project
+duk install
+```
+
+`duk install` and `duk update` are aliases — same behavior. Use whichever you
+prefer; `update` makes it explicit you're re-injecting on a project that
+already has the harness.
+
+### 2.4 Preview without writing
+
+```bash
+duk install --dry-run
+```
+
+Prints what WOULD be written without touching any file. Use this on sensitive
+projects before adopting.
+
+### 2.5 Subfolder (monorepo)
+
+If the fullstack project lives in a subdirectory:
+
+```bash
+cd C:\my-monorepo
+duk install --sub backend
+duk install --sub frontend
+```
+
+Each subfolder gets its own `.claude/` + `CLAUDE.md`, with isolated
+`Project Identity`.
+
+### 2.6 Edit `CLAUDE.md → Project Identity`
+
+The template injects a `## Project Identity` section with placeholders. Replace
+them with the REAL state of the project (not the desired state):
+
+```markdown
+## Project Identity
+
+- **Project name**: `legacy-erp`
+- **Project type**: `fullstack`
+- **Primary stack**: `Java 11 + Spring Boot 2.7 + Angular 14`
+- **Database**: `Oracle 19c + Redis 6`
+- **Domain**: `Financial ERP`
+- **Team size**: `5 backend, 2 frontend`
+- **Additional rules**: |
+   - JUnit 4 in use (JUnit 5 migration tracked in ADR-031)
+   - H2 in legacy tests
+   - Modernization to Java 25 + SB 4 in backlog (ADR-040)
+```
+
+### 2.7 Bring up the dashboard (optional)
+
+```bash
+duk dashboard
+```
+
+Opens `http://localhost:4242` with manuals, agents, skills, and ADRs of the
+harness for offline reference.
+
+### 2.8 Open Cowork or Claude Code
+
+From here the chat has access to all agents/skills. Recommended first prompt:
+
+```text
+auditor compares .claude structure with official template
+```
+
+Confirms the install came out clean.
+
+## 3. Onboarding — project ALREADY HAS `.claude/`
+
+Scenario: the repo was adopted before (by you or another dev) and you want to
+update.
+
+### 3.1 Update via CLI (idempotent)
+
+```bash
+cd C:\my-legacy-project
+git checkout -b chore/update-harness
+duk install
+```
+
+The installer:
+
+- Detects existing `.claude/`
+- Creates backup at `.claude.backup-<timestamp>/`
+- Overwrites `agents/`, `skills/`, `settings.json` with current version
+- MERGES `CLAUDE.md`: preserves `## Project Identity`, overwrites other
+  sections with the new plugin version
+- Prints summary diff
+
+### 3.2 Update via chat
+
+```text
+> "update the template"
+```
+
+Triggers the `update-template` agent (model: haiku, it's mechanical). Same
+effect as `duk install`, but you watch it via chat.
+
+### 3.3 Sync with development-utility-kit
+
+```text
+> "sync with development-utility-kit"
+> "bring in the new skills"
+```
+
+Same triggers as `update-template`. Use whichever vocabulary feels natural.
+
+## 4. Batch adoption — multiple projects
+
+If you have 5+ legacy repos and want to adopt them all without entering each:
+
+```text
+/active-project C:/projects/legacy-1
+/active-project C:/projects/legacy-2 --force-type=backend
+/active-project C:/projects/legacy-3 --template=C:/development/tools/development-utility-kit
+/active-project C:/projects/legacy-4 --dry-run
+```
+
+### 4.1 `/active-project` flags
+
+- `--dry-run` — preview, writes nothing
+- `--force-type=<backend|frontend|fullstack|mobile>` — force type when
+  auto-detect gets it wrong (e.g. backend with `package.json` for build tools
+  but actually Java)
+- `--template=<path>` — use an alternate template path (local forks, pending
+  upstream fix)
+- `--skip-brain` — don't provision `docs/brain/`
+
+### 4.2 Fast-lane vs interactive
+
+| Skill | Mode | When to use |
+|---|---|---|
+| `active-project` | Non-interactive, path-driven | Batch, multiple projects, CI |
+| `update-template` | Interactive, prompt-driven | Single project, manual validation |
+| `duk install` (CLI) | Non-interactive, CWD-driven | Local, first contact |
+
+All three converge on the same result: `.claude/` + `CLAUDE.md` at the current
+version.
+
+## 5. Workflow 1 — Initial audit (day 1)
+
+You just installed the harness. Before touching code, audit the state.
+
+### Turn 1 — compare with official template
+
+```text
+You:
+auditor compares .claude structure with official template
+
+Claude (auditor):
+> Diff vs template development-utility-kit v5.18.0:
+>   .claude/agents/: 25 agents, all up to date ✓
+>   .claude/skills/: 18 skills, 1 outdated:
+>     - auto-test-guard V5.13 (current V5.18) — pyramid ratio gate missing
+>   CLAUDE.md: Project Identity OK ✓
+>   docs/brain/: structure missing
+>   .claude/settings.json: custom PostToolUse hook preserved
+> Recommend: "update the template" for skill sync, then "register in the brain"
+> to provision docs/brain/.
+```
+
+### Turn 2 — audit tests
+
+```text
+You:
+audit the tests
+
+Claude (test-coverage-auditor):
+> Backend src/main/java/: 187 classes, 142 with tests (76%)
+> Frontend src/app/: 87 .ts, 51 with .spec.ts (59%)
+> JaCoCo: 71% lines (below 85% threshold)
+> JaCoCo branches: 64% (below 80%)
+> PIT mutation: not configured (gate requires 70% in domain/application)
+>
+> P0 (business rule without test): 3 use cases
+>   - PaymentUseCase.calculateTax — 4 branches, 0 tests
+>   - OrderUseCase.applyDiscount — 6 branches, 0 tests
+>   - InventoryUseCase.reserve — 8 branches, 0 tests
+> P1 (partial, edges missing): 8 classes
+> P2 (utility, low criticality): 23 classes
+> P3 (DTO/config): 12 classes
+>
+> Verdict PRD-ready: NO-GO.
+> Full report in docs/brain/architecture/tech-debt.md
+```
+
+### Turn 3 — prioritize
+
+```text
+You:
+tech-lead prioritizes P0/P1 and creates ADR for debt payment
+
+Claude (tech-lead):
+> Plan:
+>   1. P0 PaymentUseCase — 2 days (estimated by @qa-engineer)
+>   2. P0 OrderUseCase — 1 day
+>   3. P0 InventoryUseCase — 1 day
+>   4. P1 (8 classes) — 1 week, parallelizable by sub-team
+>   5. P2 — backlog, pay along with features that touch the code
+>
+> ADR-040 created in docs/adr/ADR-040-coverage-debt-payment.md:
+>   - Context: RED gate blocks new features
+>   - Decision: pay P0+P1 in a dedicated sprint before release
+>   - Consequences: 2 weeks without new features, GREEN gate in 14 days
+>
+> Sprint 0 (debt-payment) created in docs/sprints/SPRINT-0.md.
+> Recommend: "run sprint 0" to start.
+```
+
+### Turn 4 — provision vault
+
+```text
+You:
+register in the brain
+
+Claude (brain-keeper):
+> docs/brain/ provisioned:
+>   ├── MOC.md (map of content)
+>   ├── architecture/
+>   │   ├── tech-debt.md (auditor report)
+>   │   └── decisions.md (ADR index)
+>   ├── features/
+>   ├── daily/2026-05-27.md
+>   └── .obsidian/ (color snippet, initial config)
+> Vault ready for Obsidian. Open with File > Open Folder.
+```
+
+### Turn 5 — memorize context
+
+```text
+You:
+remember that the project is on Java 11 + Spring Boot 2.7, modernization to
+Java 25 + SB 4 planned for Q3. JUnit 4 still in 23 tests.
+
+```
+
+## 6. Workflow 2 — First feature on legacy
+
+Rule: never start a feature on a project with a RED gate. The harness protects you.
+
+### Turn 1 — request
+
+```text
+You:
+grill me about adding CSV export of sales
+
+Claude (grill-me):
+> Before starting the discovery interview: is gate-keeper GREEN on the current
+> project state? Without a green baseline, adding a feature on top of debt is
+> stacking liability.
+> Run "run the tests" first to validate.
+```
+
+### Turn 2 — validate baseline
+
+```text
+You:
+run the tests
+
+Claude (gate-keeper):
+> Full suite:
+>   mvn verify ......................... FAIL (3 tests RED after develop merge)
+>   Backend coverage ................... 71% (below 85%)
+>   PIT mutation ....................... not configured
+>   SpotBugs ........................... 2 HIGH
+>   Frontend coverage .................. 59%
+>   ESLint ............................. 14 warnings
+>   Playwright ......................... PASS
+>
+> Verdict: RED. Don't start a new feature. Recommend:
+>   1. "tech-lead diagnoses the 3 red tests"
+>   2. "gate-keeper generates tests for P0 of tech-debt.md"
+>   3. Then: feature.
+```
+
+### Turn 3 — pay debt first
+
+```text
+You:
+gate-keeper generate tests for the 3 P0 from tech-debt.md
+
+Claude:
+> Dispatch in parallel:
+>   - qa-engineer → PaymentUseCase (18 tests, branches + edge cases)
+>   - qa-engineer → OrderUseCase (24 tests)
+>   - qa-engineer → InventoryUseCase (32 tests)
+> Total: 74 new tests in domain/application.
+>
+> Re-run of the gate:
+>   JaCoCo lines ................... 86% ✓
+>   JaCoCo branches ................ 81% ✓
+>   PIT mutation (configured) ...... 71% ✓
+>   SpotBugs ....................... 0 HIGH ✓
+>   Frontend ....................... 59% (still below, P1 backlog)
+>
+> Verdict: GREEN on backend. Frontend still P1 but does not block backend
+> feature. You can proceed.
+```
+
+### Turn 4 — normal discovery
+
+```text
+You:
+now grill me about adding CSV export of sales
+
+Claude (grill-me):
+> Discovery interview, 10-15 turns. Question 1/N:
+> What's the definition of "sale" in the export context? Order completed?
+> Order shipped? Order with confirmed payment? Each changes the SQL filter.
+> ...
+> [full interview]
+> Output: docs/discovery/DISCOVERY-csv-export-sales.md
+```
+
+From here the flow is standard (analyst → architect → sprint-runner →
+gate-keeper → code-reviewer → tech-lead). See `pipeline.en.md` for details.
+
+## 7. Workflow 3 — Stack migration (migrator)
+
+Full example: Java 11 + Spring Boot 2.7 → Java 25 + Spring Boot 4.0.
+
+### Turn 1 — request
+
+```text
+You:
+migrate this project from Java 11 + Spring Boot 2.7 to Java 25 + Spring Boot 4
+
+Claude (migrator):
+> Mandatory prerequisite: gate-keeper GREEN baseline. A major migration on a
+> project with RED tests or coverage below threshold = Russian roulette.
+> Confirm gate-keeper returned GREEN in the last 24h? (yes/no)
+```
+
+### Turn 2 — confirmation
+
+```text
+You:
+yes, ran it yesterday and came back GREEN
+
+Claude (migrator):
+> Plan in 4 phases. Each phase ends with gate-keeper validation.
+>
+> Phase 1 — Assessment (read-only, 1 day)
+>   Generates docs/migrations/MIGRATION-java11-springboot2.7-to-java25-springboot4.md
+>   - 47 removed APIs in use (List.of, var inference, switch expressions)
+>   - 12 deprecated APIs (RestTemplate → RestClient, WebSecurityConfigurerAdapter)
+>   - 8 application.yml changes (jakarta.* namespace, renamed properties)
+>   - 5 dependencies without Spring Boot 4 compatible version
+>     - hibernate-core 5.6 → 6.5
+>     - lombok 1.18.20 → 1.18.32
+>     - mapstruct 1.4 → 1.6
+>     - testcontainers 1.16 → 1.20
+>     - mockito 3.12 → 5.14
+>   - 23 JUnit 4 tests (migrate to JUnit 5 in parallel)
+>
+> Phase 2 — Quick wins non-breaking (1 day)
+>   ✓ List.of() / Map.of() where applicable
+>   ✓ Optional.orElseThrow()
+>   ✓ Records where DTOs became immutable
+>   ✓ Pattern matching for instanceof
+>   gate-keeper validation: GREEN ✓
+>
+> Phase 3 — Breaking changes (4-6 days, ADR per major cross)
+>   ADR-041: Java 11 → 17 LTS (text blocks, sealed classes)
+>   ADR-042: Java 17 → 21 LTS (virtual threads, sequenced collections)
+>   ADR-043: Java 21 → 25 (stream gatherers, scoped values stable)
+>   ADR-044: Spring Boot 2.7 → 3.0 (jakarta.* migration — highest risk)
+>   ADR-045: 3.0 → 3.2 (optional Native Image)
+>   ADR-046: 3.2 → 4.0 (SecurityFilterChain, RestClient, ProblemDetail RFC 9457)
+>   gate-keeper validation: GREEN on EACH cross ✓
+>
+> Phase 4 — Final validation (1 day)
+>   mvn verify ...................... ✓
+>   PIT mutation .................... 74% ✓
+>   SpotBugs ........................ 0 HIGH ✓
+>   OWASP DC ........................ 0 CVE CVSS ≥ 7.0 ✓
+>   Smoke test in staging ........... 48h mandatory
+>
+> Total estimate: 7-9 working days. PR per phase (6 PRs total). Rollback plan:
+> revert phase PR + controlled downgrade via maven profile.
+>
+> Confirm kickoff? (yes for Phase 1 / no to abort)
+```
+
+### Turn 3 — execution
+
+```text
+You:
+yes
+
+Claude (migrator):
+> Phase 1 started. Output in docs/migrations/MIGRATION-*.md in ~10 minutes.
+> Next expected prompt: "phase 2" after you review the assessment.
+```
+
+### Why one ADR per major cross?
+
+Each major jump (Java 11→17→21→25, SB 2.7→3.0→3.2→4.0) has its own trade-offs:
+deps, breaking changes, lib velocity. A single ADR "migrate from X to Y" loses
+traceability. One ADR per cross keeps the decision history clear and enables
+granular rollback.
+
+## 8. Workflow 4 — Recurring debt audit
+
+Audit isn't a one-time event. Run quarterly or after long sprints.
+
+```text
+You:
+audit coverage and update tech-debt.md
+
+Claude (test-coverage-auditor):
+> Comparison with previous audit (2026-04-01):
+>   JaCoCo lines coverage ............ 71% → 86% ✓
+>   JaCoCo branches coverage ......... 64% → 81% ✓
+>   PIT mutation ..................... not configured → 74% ✓
+>   Frontend coverage ................ 59% → 68% (P1 still open)
+>
+>   P0 closed ........................ 3 → 0 ✓
+>   P1 closed ........................ 8 → 2 (6 paid)
+>   P2 closed ........................ 23 → 19 (4 paid via feature work)
+>   P3 ............................... 12 → 12 (unchanged)
+>
+>   New P0 ........................... 0 ✓
+>   New P1 ........................... 1
+>     - ExportCsvUseCase.streamLargeBatch: >100k rows edge case untested
+>
+>   Verdict PRD-ready: GO.
+>
+> docs/brain/architecture/tech-debt.md updated.
+> docs/brain/daily/2026-05-27.md got the audit entry.
+```
+
+## 9. Workflow 5 — Recurring template update
+
+When the `development-utility-kit` plugin evolves (new agent, skill, base ADR),
+you'll want to pull it into your project.
+
+### Via CLI
+
+```bash
+cd C:\my-project
+git checkout -b chore/update-harness-2026-05
+duk install
+```
+
+Output:
+
+```text
+✓ Backup: .claude.backup-2026-05-27T15-12-04/
+✓ 2 skills updated (auto-test-guard, brain-keeper)
+✓ 1 new agent (release-engineer-v2)
+✓ settings.json overwritten (3 new hooks)
+✓ CLAUDE.md merged — Project Identity preserved
+✓ docs/brain/ untouched (history is never overwritten)
+```
+
+### Via chat
+
+```text
+> "update the template"
+> "sync with development-utility-kit"
+> "bring in the new skills"
+```
+
+All trigger the `update-template` agent (haiku). Result identical to CLI.
+
+### Update policy
+
+- Update on demand, not by habit
+- ALWAYS on a dedicated branch (`chore/update-harness-<date>`)
+- Review diff in `.claude/settings.json` (hooks can change behavior)
+- Confirm `## Project Identity` in `CLAUDE.md` is intact
+- Run `auditor` afterwards to validate
+- Test 1-2 critical skills before merge (`audit the tests`, `run the tests`)
+- Keep `.claude.backup-*` backup for 7 days before removing
+
+## 10. Cheat sheet — triggers for existing projects
+
+| I want to... | Type |
+|---|---|
+| Adopt project without .claude/ | `duk install` (terminal) OR `/active-project <path>` (chat) |
+| Update template | `duk install` (terminal) OR `update the template` (chat) |
+| Compare with official template | `auditor compares .claude structure with official template` |
+| Audit coverage | `audit the tests` |
+| Prioritize debt | `tech-lead prioritizes P0/P1` |
+| Generate missing tests | `gate-keeper generates tests for P0` |
+| Migrate Spring 2/3 → 4 | `migrate from Spring Boot <X> to 4` |
+| Migrate legacy Java | `migrate Java <X> to 25` |
+| Migrate Angular 14-20 → 21 | `migrate Angular <X> to 21` |
+| First feature on legacy | `run the tests` → `grill me about <X>` |
+| Bug on legacy | `let's debug <X>` |
+| PRD-ready check | `is this ready for production?` |
+| Batch adoption | `/active-project <path>` repeated |
+| Remember state | `remember that the project is on <stack>` |
+| Register feature/ADR/debt | `register in the brain` |
+| Debt-payment sprint | `run sprint 0` (after tech-lead plan) |
+
+## 11. Decision tree
+
+```text
+.claude/ absent in the project?
+  → duk install (CLI) or /active-project <path> (chat batch)
+
+.claude/ present but outdated?
+  → duk install (idempotent) OR "update the template"
+
+Don't know the test state?
+  → "audit the tests" (test-coverage-auditor)
+
+Coverage bad, going to prod tomorrow?
+  → "is this ready for production?" (prd-ready-check)
+  → "tech-lead prioritizes P0/P1"
+
+Legacy stack (Java 8/11/17, Spring 2/3, Angular 14-20)?
+  → "migrate from <X> to <Y>" (migrator)
+  → ALWAYS with GREEN baseline first
+
+About to start a new feature?
+  → "run the tests" → gate GREEN? → "grill me about <X>"
+  → Gate RED? → pay debt first
+
+Several projects to adopt at once?
+  → "/active-project <path>" in batch (non-interactive)
+
+Obscure/intermittent bug on legacy?
+  → "let's debug <X>" (pair-debug, hypothesis-driven)
+
+Want project history/MOC?
+  → "register in the brain" (brain-keeper)
+  → Open docs/brain/ in Obsidian
+```
+
+## 12. CLAUDE.md Project Identity — declare REALITY
+
+Common mistake: declare the DESIRED stack ("Java 25 + Spring Boot 4") in a
+project still running Java 11 + SB 2.7. Agents will then suggest APIs that
+don't exist yet, generate incompatible tests, and the gate becomes noise.
+
+**Rule**: `Project Identity` reflects the CURRENT state. Use `Additional rules`
+to annotate deviations and modernization plan.
+
+### Correct example
+
+```markdown
+## Project Identity
+
+- **Project name**: `legacy-erp`
+- **Project type**: `fullstack`
+- **Primary stack**: `Java 11 + Spring Boot 2.7 + Angular 14`
+- **Database**: `Oracle 19c + Redis 6`
+- **Domain**: `Financial ERP`
+- **Team size**: `5 backend, 2 frontend`
+- **Additional rules**: |
+   - JUnit 4 still in use (JUnit 5 migration in ADR-031)
+   - H2 in legacy tests (Testcontainers replacement in ADR-028)
+   - Hibernate 5.6, DO NOT use Hibernate 6 APIs
+   - javax.* namespace (DO NOT migrate to jakarta.* yet)
+   - RestTemplate in use (RestClient only after SB 3.x — ADR-044)
+   - Target modernization Java 25 + SB 4 in backlog (ADR-040)
+```
+
+### What goes in `Additional rules`
+
+- Lib/framework versions that diverge from the harness target
+- Temporary migration decisions ("don't auto-convert X")
+- Local conventions ("NEVER use Lombok @SneakyThrows")
+- Referenced ADRs (link to `docs/adr/ADR-NNN-*.md`)
+
+### What NOT to touch
+
+Other sections (`## Claude Model`, `## Mandatory Stack and Versions`,
+`## Skills`, etc.) are plugin baseline. Don't edit manually — use `duk install`
+/ `update-template` to receive updates. Local edits in those sections become
+conflict on the next merge.
+
+## 13. Antipatterns
+
+### Adoption
+
+- `duk install` directly on `main`/`master`/`develop` — always dedicated branch
+- Deleting `.claude.backup-<timestamp>/` before testing — wait 7 days
+- Overwriting `Project Identity` with desired stack, not current
+- Manually editing `.claude/agents/*.md` (lost on next update)
+- Modifying base sections of `CLAUDE.md` (only `Project Identity` is yours)
+- Running `duk install` in a directory that's not a git repo (installer aborts)
+
+### Execution
+
+- Starting a new feature with RED gate
+- Major migration without green baseline
+- Skipping ADRs on migration (each major cross needs an ADR)
+- Forcing automatic migration of everything instead of in phases
+- Ignoring P0 from `test-coverage-auditor`
+- Mixing debt payment with new feature in the same PR
+
+### Commits
+
+- `Co-Authored-By: Claude` (CLAUDE.md forbids)
+- Mentioning Claude/Anthropic/AI/LLM in commits (NON-NEGOTIABLE)
+- Committing directly to `main`/`master` — always via PR
+
+### CLI
+
+- `duk <skill>` — DOES NOT EXIST. Skills trigger via keyword in chat
+- `duk migrate` — DOES NOT EXIST. Migration is via chat (`migrate from X to Y`)
+- `duk audit` — DOES NOT EXIST. Audit is via chat (`audit the tests`)
+- Asking the user for credentials — read from
+  `C:\development\tools\credentials\vps.txt`
+
+## 14. Troubleshooting
+
+| Symptom | Cause | Solution |
+|---|---|---|
+| `duk install` fails with "not a git repo" | Target directory isn't a git repo | `git init` or abort — installer requires git |
+| `duk install` fails with `git pull` error | Target directory has pending changes | `git commit` or `git stash` first |
+| Directory exists but isn't a git repo | Detected but invalid | Installer aborts with exit 1 — init git or remove directory |
+| `auditor` reports outdated agents | Template evolved | `duk install` re-injects |
+| `auditor` reports custom skills deleted | Overwritten by update | Restore from `.claude.backup-<date>/skills/` |
+| `migrator` refuses to start | Gate baseline isn't GREEN | `run the tests`, pay debt, try again |
+| `test-coverage-auditor` returns P0 | Business rules without tests | DO NOT skip; generate tests (`gate-keeper generates...`) OR create a documented acceptance ADR |
+| `update-template` botched `CLAUDE.md` merge | Conflict in automatic merge | `cp CLAUDE.md.bak.<date> CLAUDE.md` + manual section merge |
+| `.obsidian/` absent after adoption | brain-keeper didn't run | `register in the brain` provisions the vault |
+| Obsidian vault without `MOC.md` | New vault, brain-keeper hasn't run yet | `register in the brain` creates MOC and indices |
+| `settings.json` customizations lost | Merge overwrote on update | Restore from `.claude.backup-<date>/settings.json` |
+| Agents with old path after update | Incomplete backup | `duk install --force` or remove `.claude/` and reinstall |
+| `npx @eltonssouza/development-utility-kit install` fails with EACCES | Permission on target directory | Run as admin OR `--path <dir-with-permission>` |
+| `duk install --sub <folder>` doesn't detect type | Subfolder without `pom.xml`/`package.json` at root | `--force-type=<backend\|frontend>` |
+| Dashboard 4242 won't start | Port in use or Node < 18 | `node -v` and free the port |
+| `/active-project` doesn't recognize path | Path with spaces or backslash | Use forward slash: `C:/projects/legacy-1` |
+
+## 16. Active hooks after `duk install`
+
+The `.claude/settings.json` injected by the harness activates these hooks
+(summary):
+
+- **PreToolUse Bash** — blocks dangerous commands: `rm -rf` in tests,
+  `git push --force` to `main`, `DROP DATABASE`, etc.
+- **PostToolUse Edit/Write** — runs `prettier`/`spotless` inline on edited
+  files and fires a reminder if the file is production code without a matching
+  test
+- **Stop** — records session history at session end (deltas,
+  decisions, ADRs created)
+
+Full details: `[Hooks reference](../docs/hooks-reference)`.
+
+Local customizations in `.claude/settings.json` are preserved until the next
+`duk install`. To preserve across updates, edit via the `update-template`
+agent rather than manually, or annotate the customization in `Additional rules`
+of `CLAUDE.md` (alerts the template on the next merge).
+
+## 17. Flow guarantee (S2 — ADR-036/ADR-041)
+
+Every prompt now passes through the **flow-guard** hook before the model sees it.
+
+### What it does
+
+1. Injects `[FLOW STATE: <stage> | status: OK/BLOCK/BYPASS]` into every prompt.
+2. Classifies the prompt into one of 4 lanes:
+   - **greenfield** — new project, no artifacts yet → requires `grill-me` first
+   - **brownfield** — existing project, implementation intent → requires DISCOVERY_*.md
+   - **sprint** — explicit sprint run → requires PLAN_*.md
+   - **small-task** — trivial / conversational → routes directly
+3. Hard-blocks brownfield/sprint work missing its prerequisite artifact.
+4. Honors `flow: skip-guard` anywhere in the prompt (audited in `.flow-state.json`).
+
+### project-manager as front-controller
+
+`project-manager` is the universal front door for every development task:
+
+| Domain count | Mode | Dispatch |
+|---|---|---|
+| 1 | ROUTE | 1 specialist agent |
+| 2–5 (independent) | ORCHESTRATE | ≤5 agents in parallel, shared `run_group_id` |
+| >5 or dependent | ESCALATE | → `grill-me` → `analyst` → `sprint-runner` |
+
+ORCHESTRATE enforces three invariants before marking any subtask `[PAR]`:
+paths must be disjoint, no output dependency, STACK CONTEXT injected per Task.
+
+### Bypass
+
+Add `flow: skip-guard` to the prompt. The bypass is logged with timestamp and session ID to `.flow-state.json` (gitignored). `duk lint` verifies the hook is registered.
+
+---
+
+## 18. Processes panel (S4 — ADR-045)
+
+The dashboard now shows **recent orchestration runs** for each project.
+
+### How to use
+
+1. Open `duk dashboard` → Dashboard tab.
+2. Click any project in the **Projects** list.
+3. A **Processes** panel appears below the three cards.
+4. Each row is a `run_group_id` (one per ORCHESTRATE dispatch).
+5. Click a row to expand it — shows each parallel agent with type, model, and status.
+6. The panel auto-refreshes every 5 s.
+
+### What gets recorded
+
+Phase A (current): `run_group_id`, `parent`, `agent_type`, `model`,
+`project_path`, `session_id`, `ended_at`, `status` — written after each agent
+finishes (`SubagentStop`). Phase B (live in-flight) is deferred — no
+`SubagentStart` hook exists in Claude Code today.
+
+### Typical display
+
+```
+rg-20260530-prod  [completed]  3 agents   ▶
+  ├── backend-developer   sonnet  completed
+  ├── frontend-developer  sonnet  completed
+  └── database-engineer   sonnet  completed
+```
+
+---
+
+## 19. Operational guard-rails
+
+**Mass edits in the native environment**: prefer Cowork or a sandbox for bulk
+read/validate operations. Direct mass file edits via the Claude Code CLI in the
+native environment can trigger OS-level locks or antivirus scans on Windows.
+`duk doctor` reminds you of this when run.
+
+**Never commit credentials**: `C:\development\tools\credentials\vps.txt` is
+read by skills at runtime — it must never be staged or pushed.
+
+**Install on dirty tree**: `duk install` will detect local modifications via
+`.MANIFEST` (sha256) and refuse to overwrite without `--force`. Always start
+from a clean branch.
+
+---
+
+## 20. Quick glossary
+
+- **skill** — keyword-based entry point (`.claude/skills/<name>/SKILL.md`)
+- **agent** — specialized executor (`.claude/agents/<name>.md`)
+- **Task tool** — mechanism that lets a skill call an agent
+- **PLAN** — `docs/plans/PLAN_*.md`, analyst output with goal-ready DoD
+- **PRD** — `docs/prd/PRD_*.md`, product requirements (`to-prd`)
+- **ADR** — Architecture Decision Record in `docs/adr/`
+- **goal-ready DoD** — Definition of Done the sprint-runner can execute
+- **senior+ gate** — threshold set in CLAUDE.md (`Senior+ Quality Gate`)
+- **Obsidian vault** — `docs/brain/` opened in Obsidian for history/MOC
+- **Autonomy Matrix** — who decides what without asking the human (CLAUDE.md)
+- **P0/P1/P2/P3** — debt severity from `test-coverage-auditor`:
+  - P0: business rule without test — BLOCKS release
+  - P1: partial, edges missing — pay in dedicated sprint
+  - P2: utility, low criticality — pay along with features
+  - P3: DTO/config — perpetual backlog
+- **Project Identity** — `CLAUDE.md` section YOU edit; rest is baseline
+- **GREEN baseline** — gate-keeper returned OK on current state
+- **`.claude.backup-<timestamp>/` backup** — automatic copy before
+  `duk install` overwrites
+- **MOC** — Map of Content, vault's main index at `docs/brain/MOC.md`
+
+## 18. Cross references
+
+- [Architecture overview](../docs/architecture-overview)
+- [Agents reference](../docs/agents-reference)
+- [Skills reference](../docs/skills-reference)
+- [Pipeline](../docs/pipeline)
+- [Quality gate](../docs/quality-gate)
+- [Stack rules](../docs/stack-rules)
+- [Autonomy matrix](../docs/autonomy-matrix)
+- [Hooks reference](../docs/hooks-referenc