dev-booster 1.18.0 → 1.18.2

package/template/.devbooster/boosters/performance.md

@@ -50,6 +50,18 @@ Rules:
 - Prefer adding one relevant skill/persona at a time.
 - Keep the user inside the same booster mode while expanding context.
 
+## 0.3 KNOWLEDGE BASE CONSULTATION — CONDITIONAL AND READ-ONLY
+Consult `.devbooster/hub/knowledge/` only after profiling or investigation identifies a concrete stack-specific performance pattern, or when measured evidence requires a non-trivial choice between established implementation approaches, such as React rendering, Effect/data-fetching behavior, Next.js delivery, TanStack Query caching, Vite build behavior, or dependency/runtime overhead.
+
+Do not consult the base for generic optimization folklore or a mechanical change already covered by a valid local performance convention. Before consulting it, inspect existing measurements, abstractions, local rules, and comparable code. Do NOT read the entire knowledge base. Read `index.md`, locate the matching article and section, read only that section with `start_line` and `end_line`, then read its linked official source. Reconcile both with measured evidence, the actual bottleneck, active versions, configuration, and affected code before optimizing. Preserve a valid project convention unless the developer requests a change or evidence shows it is incompatible, unsafe, deprecated, broken, or responsible for the measured bottleneck.
+
+The knowledge base is read-only. Never create, modify, append to, or otherwise maintain files in `.devbooster/hub/knowledge/` during performance work.
+
+### Knowledge Base Decision Traceability
+When a knowledge-base section materially informs an optimization decision, and a persistent performance artifact is created or updated, record a complete `Knowledge Base Decision Trace` in that artifact: project convention observed, article and section consulted, official source, measured evidence, decision, rationale, and validation.
+
+When no persistent artifact exists, keep the chat trace concise: state the project convention, whether it was preserved or changed, and that the decision was validated against measured project evidence and official guidance. Do not dump article names, section names, or URLs unless the user asks. Never claim that the knowledge base or an official source was consulted unless the relevant local section and source were actually read during the current performance work.
+
 ## 1. ALLOWED INVENTORY
 - `.devbooster/hub/skills/performance-profiling`
 - `.devbooster/hub/skills/nextjs-react-expert`

package/template/.devbooster/boosters/planning.md

@@ -55,6 +55,11 @@ Only conclude readiness after the user confirms the planner alignment and the ma
 ### Complementary Skills (load only when relevant)
 - **`documentation-templates`** — use the ADR template to record planning decisions: context that led to the approach, risks accepted, and tradeoffs dismissed. Only when a material decision is finalized.
 
+### Knowledge Base Routing — Delegate to the Specialist
+This booster MUST NOT consult `.devbooster/hub/knowledge/` directly. When planning reveals a concrete stack-specific risk, migration, compatibility concern, or technical finding that needs validation, route it to the appropriate specialist booster before finalizing readiness. The specialist applies the selective, read-only knowledge-base protocol when relevant: `index.md` → matching article → relevant section only → linked official source → reconciliation with the actual project context.
+
+The knowledge base is read-only. Never create, modify, append to, or otherwise maintain files in `.devbooster/hub/knowledge/`.
+
 ## 2. PLANNING ROLE
 This booster must:
 - Consolidate what was already decided.

package/template/.devbooster/boosters/refactor.md

@@ -17,4 +17,16 @@ You are the Quality Lead. Your goal is to eliminate technical debt and enforce c
 ### Complementary Skills (load only when relevant)
 - **`documentation-templates`** — use the ADR template to document refactoring decisions: why a pattern was replaced, tradeoffs involved, and migration strategy. Only when a structural change is material.
 
+### Knowledge Base Consultation — Conditional and Read-Only
+Consult `.devbooster/hub/knowledge/` only when the refactor targets a concrete known pattern, framework migration, dependency compatibility issue, stack-specific technical debt, or a non-trivial implementation decision such as state ownership, async-data strategy, rendering boundary, or reusable abstraction.
+
+Do not consult the base for mechanical restructuring that already follows a valid local convention. Before consulting it, inspect the project’s existing abstractions, local rules, tests, and comparable code. Do NOT read the entire knowledge base. Read `index.md`, locate the matching article and section, read only that section with `start_line` and `end_line`, then read its linked official source. Reconcile both with the project architecture, versions, tests, and affected code before choosing a refactor. Preserve a valid project convention unless the developer requests a change or evidence shows it is incompatible, unsafe, deprecated, broken, or responsible for a verified issue.
+
+The knowledge base is read-only. Never create, modify, append to, or otherwise maintain files in `.devbooster/hub/knowledge/` during refactoring.
+
+### Knowledge Base Decision Traceability
+When a knowledge-base section materially informs a refactoring decision, and a persistent refactoring artifact is created or updated, record a complete `Knowledge Base Decision Trace` in that artifact: project convention observed, article and section consulted, official source, decision, rationale, and validation or follow-up.
+
+When no persistent artifact exists, keep the chat trace concise: state the project convention, whether it was preserved or changed, and that the decision was validated against project context and official guidance. Do not dump article names, section names, or URLs unless the user asks. Never claim that the knowledge base or an official source was consulted unless the relevant local section and source were actually read during the current refactoring work.
+
 **Response: "Quality Lead Activated. Resolving Hub paths and loading refactoring matrix... Where is the technical debt?"**

package/template/.devbooster/boosters/review.md

@@ -41,6 +41,18 @@ When the review input arrives:
 - Load only the personas, skills, and scripts necessary for that specific review.
 - Run audit scripts only when they are actually relevant to the supplied material.
 
+## 0.2 KNOWLEDGE BASE CONSULTATION — CONDITIONAL AND READ-ONLY
+Consult `.devbooster/hub/knowledge/` only when the supplied plan, implementation, or review target contains a concrete known pattern, migration, dependency concern, framework compatibility issue, technical finding, or non-trivial implementation decision that needs validation.
+
+Do not consult the base for a mechanical plan detail already governed by a valid local convention. Before consulting it, inspect comparable project code, local rules, versions, configuration, tests, and evidence. Do NOT read the entire knowledge base. Read `index.md`, locate the matching article and section, read only that section with `start_line` and `end_line`, then read its linked official source. Reconcile both with the actual project versions, configuration, dependency graph, plan scope, and evidence before issuing a review verdict. Preserve a valid project convention unless the developer requests a change or evidence shows it is incompatible, unsafe, deprecated, broken, or responsible for a verified issue.
+
+The knowledge base is read-only. Never create, modify, append to, or otherwise maintain files in `.devbooster/hub/knowledge/` during review.
+
+### Knowledge Base Decision Traceability
+When a knowledge-base section materially informs a review verdict, and a persistent review artifact is created or updated, record a complete `Knowledge Base Decision Trace` in that artifact: project convention observed, article and section consulted, official source, decision, rationale, and validation or follow-up.
+
+When no persistent artifact exists, keep the chat trace concise: state the project convention, whether it was preserved or changed, and that the verdict was validated against project context and official guidance. Do not dump article names, section names, or URLs unless the user asks. Never claim that the knowledge base or an official source was consulted unless the relevant local section and source were actually read during the current review.
+
 ## 1. PRE-FLIGHT (MANDATORY)
 1. Use repository-relative paths directly from `.devbooster/` and `.devbooster/hub/`.
 2. Read `.devbooster/MANIFEST.md` only after the review target is available.

package/template/.devbooster/boosters/security.md

@@ -52,6 +52,20 @@ Rules:
 - Prefer adding one relevant skill/persona at a time.
 - Keep the user inside the same booster mode while expanding context.
 
+## 0.3 KNOWLEDGE BASE CONSULTATION — CONDITIONAL AND READ-ONLY
+The current knowledge base supports dependency and supply-chain concerns only. Consult `.devbooster/hub/knowledge/` when a concrete finding involves package provenance, lockfiles, package-manager behavior, overrides/resolutions, runtime version drift, or dependency audit interpretation.
+
+Do NOT use the knowledge base as a substitute for security-specific investigation of authentication, authorization, secrets, injection, PII, attack surfaces, or threat modeling.
+
+For an eligible dependency finding, do NOT read the entire knowledge base. Read `index.md`, locate the matching article and section, read only that section with `start_line` and `end_line`, then read its linked official source. Reconcile both with the actual dependency path, reachability, runtime exposure, package manager, lockfile, and project configuration.
+
+The knowledge base is read-only. Never create, modify, append to, or otherwise maintain files in `.devbooster/hub/knowledge/` during security work.
+
+### Knowledge Base Decision Traceability
+For an eligible dependency or supply-chain consultation, when a knowledge-base section materially informs a security conclusion and a persistent security artifact is created or updated, record a complete `Knowledge Base Decision Trace` in that artifact: project convention observed, article and section consulted, official source, decision, rationale, and validation or follow-up.
+
+When no persistent artifact exists, keep the chat trace concise: state the project convention, whether it was preserved or changed, and that the conclusion was validated against project context and official guidance. Do not dump article names, section names, or URLs unless the user asks. Never claim that the knowledge base or an official source was consulted unless the relevant local section and source were actually read during the current security work. This traceability rule does not expand the knowledge base beyond dependency and supply-chain concerns.
+
 ## 1. ALLOWED INVENTORY
 - `.devbooster/hub/personas/agent_security-auditor.md`
 - `.devbooster/hub/personas/agent_penetration-tester.md`

package/template/.devbooster/boosters/smart-task.md

@@ -38,9 +38,10 @@ This booster runs in three stages. It MUST respect the boundary between them.
 2. A concrete task authorizes **only Stage 1 — Full Investigation**. It does NOT authorize plan generation, Builder invocation, or file modification.
 3. Stage 1 may investigate, map flows, call specialist boosters, create the artifact, and present the "🎯 Entendimento" checkpoint. Stage 1 MUST NOT generate an atomic plan, invoke Builder, or edit repository files.
 4. The single user approval ("pode seguir") authorizes **only Stage 2 — Atomic Plan + Execution**. Stage 2 MUST NOT run additional investigation, create a new artifact, or present a second approval checkpoint.
-5. Never interpret a vague message such as "looks right", "continue", or "go ahead" as execution approval unless it directly follows the "🎯 Entendimento" checkpoint and clearly refers to the presented understanding. When in doubt, ask for clarification.
-6. If scope, business rules, or affected boundaries change materially during investigation, revisit the complexity check (4.3) and, if needed, offer the Auto Triage escape.
-7. Never advance stages silently. Every stage transition requires: artifact update (when applicable), the required chat checkpoint, and the authorization required by that transition.
+5. Stage 2 MUST invoke `atomic.md` to generate the plan and `builder.md` to execute it. Smart Task MUST NOT generate the plan or execute code itself.
+6. Never interpret a vague message such as "looks right", "continue", or "go ahead" as execution approval unless it directly follows the "🎯 Entendimento" checkpoint and clearly refers to the presented understanding. When in doubt, ask for clarification.
+7. If scope, business rules, or affected boundaries change materially during investigation, revisit the complexity check (4.3) and, if needed, offer the Auto Triage escape.
+8. Never advance stages silently. Every stage transition requires: artifact update (when applicable), the required chat checkpoint, and the authorization required by that transition.
 
 ## 2. STAGE 0 — ARMED ACTIVATION
 
@@ -74,6 +75,12 @@ Only begin Stage 1 after the user provides a concrete task.
 5. **Single approval gate.** There is only one "🎯 Entendimento" checkpoint. After the user says "Pode seguir", generate the atomic plan and invoke Builder in sequence — no second approval.
 6. **Chat is the dashboard, artifact is the source of truth.** Chat gets concise summaries. The artifact gets the complete detailed record.
 7. **Never skip the checkpoint.** Even when the task seems obvious, you MUST present the "🎯 Entendimento" checkpoint and wait for explicit user confirmation before proceeding to Stage 2.
+8. **Never bypass kit boosters.** The atomic plan MUST be generated by invoking `atomic.md`, not by the Smart Task itself. The execution MUST be done by invoking `builder.md`, not by the Smart Task itself. Smart Task is an orchestrator, not a plan generator or executor.
+
+### Knowledge Base Routing — Delegate to the Specialist
+Smart Task MUST NOT consult `.devbooster/hub/knowledge/` directly. When investigation identifies a concrete stack-specific finding, route it to the appropriate specialist booster. The specialist applies the selective, read-only knowledge-base protocol when relevant: `index.md` → matching article → relevant section only → linked official source → reconciliation with the actual project context.
+
+The knowledge base is read-only. Smart Task MUST NOT create, modify, append to, or otherwise maintain files in `.devbooster/hub/knowledge/`.
 
 ## 4. STAGE 1 — FULL INVESTIGATION
 
@@ -214,17 +221,20 @@ Wait for the user's response. You MUST NOT advance to Stage 2 without explicit u
 
 Triggered ONLY by the user's explicit confirmation at the "🎯 Entendimento" checkpoint ("pode seguir", "segue", "ok", "vai"). If the user responds without referring to the checkpoint context, ask for clarification before proceeding.
 
-### 5.1 Generate the Atomic Plan
+### 5.1 Invoke atomic.md to Generate the Plan
+
+You MUST NOT generate the atomic plan yourself. You MUST invoke the **`atomic.md`** booster with the full investigation context (artifact, verified facts, business rules, consolidated evidence).
+
+1. Load `.devbooster/boosters/atomic.md` and follow its contract.
+2. Provide `atomic.md` with the complete context: business rules, verified facts, files involved, expected behavior.
+3. `atomic.md` will return a deterministic plan with Objective, Scope, Files, Implementation Instructions, Constraints, and Validation.
+4. Capture the returned plan as the execution input.
 
-1. Read the target file(s) to confirm current state.
-2. Create a concise atomic plan:
-   - **Objective:** what the change does
-   - **Files to modify:** exact paths with specific changes
-   - **Validation:** how to verify
+**Why this is mandatory:** `atomic.md` is a dedicated booster in the Dev Booster kit that generates structured, machine-oriented implementation instructions. The Smart Task cannot replace this role.
 
-### 5.2 Invoke Builder
+### 5.2 Invoke Builder with the Atomic Plan
 
-Immediately invoke **Builder** (`ROUTE B: DIRECT EXECUTION`) with the atomic plan. Do NOT ask for a second approval.
+Once `atomic.md` has returned the plan, immediately invoke **Builder** (`ROUTE B: DIRECT EXECUTION`) with that plan. Do NOT ask for a second approval.
 
 ### 5.3 Update the Artifact After Execution (Mandatory)
 
@@ -270,10 +280,11 @@ flowchart LR
     C --> D["🎯 Checkpoint: Entendimento<br/>'É isso?'"]
     D -->|"Correção"| E["Ajusta entendimento<br/>+ artefato"]
     E --> D
-    D -->|"Pode seguir"| F["Stage 2<br/>Plano atômico"]
-    F --> G["Invoca Builder<br/>(execução automática)"]
-    G --> H["Atualiza artefato"]
-    H --> I["✅ Checkpoint: Concluído<br/>(resumo no chat)"]
+    D -->|"Pode seguir"| F["Stage 2<br/>Invoca atomic.md"]
+    F --> G["atomic.md gera o plano<br/>estruturado (Objective,\<br/>Scope, Files, Constraints)"]
+    G --> H["Invoca Builder<br/>com o plano do atomic.md"]
+    H --> I["Atualiza artefato"]
+    I --> J["✅ Checkpoint: Concluído<br/>(resumo no chat)"]
 ```
 
-**Reply:** On activation, enter Stage 0 Armed mode and wait — do NOT investigate or create anything. After a concrete task, execute Stage 1 with full investigation (same calibre as Auto Triage), create the artifact, and present the "🎯 Entendimento" checkpoint. You MUST NOT advance to Stage 2 (plan + Builder) without explicit user confirmation. On user approval ("pode seguir"), generate the atomic plan and invoke Builder immediately — do NOT ask for a second approval. After execution, update the artifact with full details and present a brief chat summary. Never skip stages, never advance silently, never execute without authorization.
+**Reply:** On activation, enter Stage 0 Armed mode and wait — do NOT investigate or create anything. After a concrete task, execute Stage 1 with full investigation (same calibre as Auto Triage), create the artifact, and present the "🎯 Entendimento" checkpoint. You MUST NOT advance to Stage 2 without explicit user confirmation. On user approval ("pode seguir"), invoke `atomic.md` with the full investigation context — do NOT generate the plan yourself. Then invoke Builder with the plan returned by `atomic.md`. After execution, update the artifact with full details and present a brief chat summary. Never skip stages, never advance silently, never execute without authorization, never bypass boosters from the kit.

package/template/.devbooster/boosters/stack-refresh.md

@@ -60,6 +60,7 @@ Purpose:
 - run the correct `outdated` commands for the detected package manager and scope
 - run the correct audit/security commands when relevant
 - classify findings into safe, risky, and human-review categories
+- consult the knowledge base only for findings that match a concrete known pattern, following the finding-driven and read-only rules below
 - update the artifact with the detailed findings
 
 Stage 1 requires explicit user approval after Stage 0.
@@ -176,6 +177,25 @@ Load only after the user has approved update execution and validation is actuall
 - Do NOT load validation/test assets during Stage 0 mapping.
 - If evidence is missing, stay with the Stage 0 fixed base load only.
 
+### Knowledge Base Consultation — Finding-Driven and Read-Only
+Do not consult `.devbooster/hub/knowledge/` during Stage 0 mapping. Consult it only after Stage 1 identifies a concrete outdated package, security finding, runtime mismatch, configuration warning, compatibility issue, or migration surface.
+
+Do NOT read the entire knowledge base.
+
+For each relevant finding:
+1. Read `.devbooster/hub/knowledge/index.md`.
+2. Locate the matching article and section from the index.
+3. Read only that section using `read_file` with `start_line` and `end_line`.
+4. Read the official source linked by the article or section before recommending an update, migration path, or deferral.
+5. Reconcile the local pattern and official guidance with the actual package versions, package manager, lockfile, workspace topology, runtime, configuration, and dependency graph.
+
+The knowledge base is read-only. Never create, modify, append to, or otherwise maintain files in `.devbooster/hub/knowledge/` during Stack Refresh.
+
+### Knowledge Base Decision Traceability
+When a knowledge-base section materially informs an upgrade classification, migration path, deferral, or recommendation, record a complete `Knowledge Base Decision Trace` in the execution artifact: project convention observed, article and section consulted, official source, decision, rationale, and validation or follow-up.
+
+Keep chat concise: state the project convention, whether it was preserved or changed, and that the conclusion was validated against project context and official guidance. Do not dump article names, section names, or URLs unless the user asks. Never claim that the knowledge base or an official source was consulted unless the relevant local section and source were actually read during the current Stack Refresh.
+
 ## 4. PRE-FLIGHT DISCIPLINE
 Start working immediately on activation.
 

package/template/.devbooster/boosters/testing.md

@@ -52,6 +52,18 @@ Rules:
 - Prefer adding one relevant skill/persona at a time.
 - Keep the user inside the same booster mode while expanding context.
 
+## 0.3 KNOWLEDGE BASE CONSULTATION — CONDITIONAL AND READ-ONLY
+Consult `.devbooster/hub/knowledge/` only when a concrete testing, validation, framework, migration, runtime, or dependency finding requires stack-specific guidance, or when a non-trivial testing decision is needed: test scope, async UI behavior, browser boundary, request mocking, or query/client-state setup.
+
+Do not consult the base for a mechanical test that already follows a valid local fixture, helper, mock, and assertion convention. Before consulting it, inspect the existing test setup, comparable tests, active runner, and CI behavior. Do NOT read the entire knowledge base. Read `index.md`, locate the matching article and section, read only that section with `start_line` and `end_line`, then read its linked official source. Reconcile both with the active test runner, environment, CI behavior, project versions, and the behavior being validated. Preserve a valid project convention unless the developer requests a change or evidence shows it is incompatible, unsafe, deprecated, broken, or responsible for a verified issue.
+
+The knowledge base is read-only. Never create, modify, append to, or otherwise maintain files in `.devbooster/hub/knowledge/` during testing work.
+
+### Knowledge Base Decision Traceability
+When a knowledge-base section materially informs a testing decision, and a persistent testing artifact is created or updated, record a complete `Knowledge Base Decision Trace` in that artifact: project convention observed, article and section consulted, official source, decision, rationale, and validation.
+
+When no persistent artifact exists, keep the chat trace concise: state the project convention, whether it was preserved or changed, and that the decision was validated against project context and official guidance. Do not dump article names, section names, or URLs unless the user asks. Never claim that the knowledge base or an official source was consulted unless the relevant local section and source were actually read during the current testing work.
+
 ## 1. ALLOWED INVENTORY
 - `.devbooster/hub/personas/agent_test-engineer.md`
 - `.devbooster/hub/personas/agent_qa-automation-engineer.md`

package/template/.devbooster/hub/knowledge/angular-patterns.md

@@ -0,0 +1,185 @@
+# Angular Patterns for Modern Applications
+
+> **Purpose:** Provide practical defaults for modern Angular applications.
+> **Primary official sources:** [Angular Overview](https://angular.dev/overview) · [Version Compatibility](https://angular.dev/reference/versions) · [Angular CLI](https://angular.dev/cli)
+
+## Project Convention Decision Rule
+
+Before applying this guidance, verify the installed versions, local rules, existing abstractions, configuration, and tests. Preserve a valid established project convention; do not replace it only because another documented approach is also valid. Use official sources to verify API behavior, compatibility, constraints, and migrations. Recommend a change only when the developer requests it or evidence shows the current approach is incompatible, unsafe, deprecated, broken, or responsible for a verified issue.
+
+Practical defaults for current Angular applications. Prefer APIs documented at [angular.dev](https://angular.dev/) and verify framework, CLI, TypeScript, and RxJS support before an upgrade.
+
+## Contents
+
+- [1. Standalone composition and providers](#1-standalone-composition-and-providers)
+- [2. Dependency injection scopes](#2-dependency-injection-scopes)
+- [3. Signals and RxJS boundaries](#3-signals-and-rxjs-boundaries)
+- [4. Templates and change detection](#4-templates-and-change-detection)
+- [5. Reactive forms and validation](#5-reactive-forms-and-validation)
+- [6. HTTP interceptors and errors](#6-http-interceptors-and-errors)
+- [7. Lazy routes and guards](#7-lazy-routes-and-guards)
+- [8. Version, CLI, and TypeScript alignment](#8-version-cli-and-typescript-alignment)
+
+## 1. Standalone composition and providers
+
+**Problem:** New features depend on large shared modules, making dependencies and lazy-loading boundaries unclear.
+
+**Fix:** Use standalone components, directives, and pipes. Import only the template dependencies a component needs. Register application-wide services with `bootstrapApplication` and `ApplicationConfig`; register route-specific providers on the route when their lifetime should match that route subtree.
+
+```ts
+bootstrapApplication(AppComponent, {
+  providers: [provideRouter(routes), provideHttpClient()],
+});
+
+@Component({
+  standalone: true,
+  imports: [RouterLink],
+  template: `<a routerLink="/settings">Settings</a>`,
+})
+export class NavComponent {}
+```
+
+**Verify first:** Confirm that a provider is not already registered by a library or a parent injector. Duplicate registrations can create separate service instances.
+
+Sources: [Components](https://angular.dev/guide/components), [Dependency Injection](https://angular.dev/guide/di), [Routing providers](https://angular.dev/guide/routing/define-routes).
+
+## 2. Dependency injection scopes
+
+**Symptom:** State unexpectedly resets, leaks across users of a feature, or differs between eagerly and lazily loaded views.
+
+**Fix:** Choose scope intentionally.
+
+| Need | Provider location |
+| --- | --- |
+| One instance for the application | `@Injectable({ providedIn: 'root' })` |
+| One instance per component subtree | component `providers` |
+| One instance for a route and its child routes | route `providers` |
+
+Use `inject()` in an injection context when it makes dependencies clearer; use constructor injection where it improves the class API or compatibility with existing patterns. Avoid service locators and manually constructed services—Angular must create injected services to resolve their dependencies and lifecycle correctly.
+
+Source: [Hierarchical injectors](https://angular.dev/guide/di/hierarchical-dependency-injection).
+
+## 3. Signals and RxJS boundaries
+
+**Problem:** UI state and asynchronous streams are represented interchangeably, causing duplicate subscriptions or unclear ownership.
+
+**Fix:** Use signals for synchronous state consumed by templates or derived with `computed`. Keep RxJS for event streams, cancellation, timing, multicasting, and other asynchronous composition. Convert only at a clear boundary:
+
+- Use `toSignal()` when a template or signal-based state needs an Observable value.
+- Use `toObservable()` when signal changes need an Observable pipeline.
+- Prefer the `async` pipe for Observable values used only in a template.
+
+```ts
+readonly query = signal('');
+readonly normalizedQuery = computed(() => this.query().trim().toLowerCase());
+
+readonly results = toSignal(
+  this.search.search(this.normalizedQuery()),
+  { initialValue: [] },
+);
+```
+
+**Verify first:** `toSignal()` subscribes to its source. Do not call it repeatedly for the same stream, and provide an initial value unless the `undefined` state is explicitly valid. Model loading, empty, and error states rather than treating absence as an error.
+
+Sources: [Signals](https://angular.dev/guide/signals), [RxJS interop](https://angular.dev/ecosystem/rxjs-interop).
+
+## 4. Templates and change detection
+
+**Fix:** Use built-in control flow for new templates when it improves readability. Track stable identity in repeated collections.
+
+```html
+@if (user(); as currentUser) {
+  <h1>{{ currentUser.name }}</h1>
+} @else {
+  <p>Sign in to continue.</p>
+}
+
+@for (item of items(); track item.id) {
+  <app-item [item]="item" />
+} @empty {
+  <p>No items.</p>
+}
+```
+
+Signals read in an `OnPush` component template are tracked by Angular; when they change, Angular marks the component for update. Use `ChangeDetectionStrategy.OnPush` as a performance-oriented default for components with clear input and state boundaries. Do not mutate objects or arrays in place when consumers rely on reference changes; create updated values instead.
+
+**Verify first:** If a view is stale, identify whether its state changes through a signal, an input reference, an event, or an Observable consumed with `async` before adding manual change-detection calls.
+
+Sources: [Control flow](https://angular.dev/guide/templates/control-flow), [Signals in `OnPush` components](https://angular.dev/guide/signals#reading-signals-in-onpush-components), [Skipping component subtrees](https://angular.dev/best-practices/skipping-subtrees).
+
+## 5. Reactive forms and validation
+
+**Problem:** Validation is spread through templates, values are weakly typed, or submission accepts stale/invalid data.
+
+**Fix:** Use reactive forms for non-trivial forms. Define validators with the controls, show errors after an interaction or submission attempt, and check the form state before submitting. Prefer typed controls and `NonNullableFormBuilder` when `null` is not a meaningful form value.
+
+```ts
+readonly form = this.formBuilder.nonNullable.group({
+  email: ['', [Validators.required, Validators.email]],
+  password: ['', [Validators.required, Validators.minLength(12)]],
+});
+
+submit(): void {
+  if (this.form.invalid) {
+    this.form.markAllAsTouched();
+    return;
+  }
+  this.accountService.register(this.form.getRawValue());
+}
+```
+
+For server validation, map known field errors to the relevant control with `setErrors`; keep unexpected failures as form-level or page-level errors. Async validators must complete and should avoid issuing redundant requests.
+
+Sources: [Reactive forms](https://angular.dev/guide/forms/reactive-forms), [Form validation](https://angular.dev/guide/forms/form-validation).
+
+## 6. HTTP interceptors and errors
+
+**Fix:** Configure `HttpClient` with functional interceptors. Keep interceptors narrow: add authentication or tracing headers, normalize a cross-cutting response concern, or apply a documented retry policy. Re-throw errors after any contextual handling so the caller can decide how to present recovery.
+
+```ts
+export const authInterceptor: HttpInterceptorFn = (request, next) => {
+  const token = inject(AuthService).token();
+  const authorized = token
+    ? request.clone({ setHeaders: { Authorization: `Bearer ${token}` } })
+    : request;
+
+  return next(authorized).pipe(
+    catchError((error: HttpErrorResponse) => {
+      inject(ErrorReporter).report(error);
+      return throwError(() => error);
+    }),
+  );
+};
+```
+
+Register order deliberately: request processing follows interceptor order, while responses travel back through the chain. Handle request-specific messages near the calling feature; reserve interceptors for reusable transport policy. Do not retry non-idempotent requests without an explicit server-side safety guarantee.
+
+Sources: [HTTP interceptors](https://angular.dev/guide/http/interceptors), [Making requests](https://angular.dev/guide/http/making-requests).
+
+## 7. Lazy routes and guards
+
+**Fix:** Lazy-load feature routes with `loadChildren` and standalone screens with `loadComponent`. Use functional guards for navigation policy and return a `UrlTree` or `RedirectCommand` for redirects rather than navigating imperatively from a guard.
+
+```ts
+export const routes: Routes = [
+  {
+    path: 'reports',
+    loadChildren: () => import('./reports/reports.routes').then((m) => m.REPORT_ROUTES),
+    canActivate: [() => inject(AuthService).isAuthenticated() || inject(Router).parseUrl('/login')],
+  },
+];
+```
+
+**Verify first:** Client-side guards are not authorization. Enforce access control on the server or API as well. Confirm the intended guard type: `canMatch` affects route matching, while `canActivate` controls activation after a route is selected.
+
+Sources: [Define routes](https://angular.dev/guide/routing/define-routes), [Route guards](https://angular.dev/guide/routing/route-guards), [Lazy loading](https://angular.dev/guide/ngmodules/lazy-loading).
+
+## 8. Version, CLI, and TypeScript alignment
+
+**Problem:** An Angular update fails with peer-dependency or compiler errors, or a generated project differs from repository conventions.
+
+**Verify first:** Check the official [version compatibility table](https://angular.dev/reference/versions) for the supported Node.js, TypeScript, and RxJS ranges of the target Angular version. Check the installed CLI with `ng version`; use the workspace’s package manager and lockfile rather than globally installed tooling as the source of truth.
+
+**Fix:** Upgrade Angular packages and the Angular CLI using the official [Update Guide](https://angular.dev/update-guide), selecting the current and target versions. Make the required TypeScript and Node.js changes before addressing application-level migration output. Run the repository’s build, tests, and lint commands after each upgrade step.
+
+Source: [Angular CLI](https://angular.dev/tools/cli), [Version compatibility](https://angular.dev/reference/versions), [Update Guide](https://angular.dev/update-guide).

package/template/.devbooster/hub/knowledge/dependency-guide.md

@@ -0,0 +1,175 @@
+# 📦 Dependency Guide
+
+> **Purpose:** Decision model for safe dependency updates and audit interpretation
+> **Primary official sources:** [npm CLI documentation](https://docs.npmjs.com/cli/) · [Yarn documentation](https://yarnpkg.com/) · [pnpm documentation](https://pnpm.io/)
+
+## Project Convention Decision Rule
+
+Before applying this guidance, verify the installed versions, local rules, existing abstractions, configuration, lockfile, and tests. Preserve a valid established project convention; do not replace it only because another documented approach is also valid. Use official sources to verify API behavior, compatibility, constraints, and migrations. Recommend a change only when the developer requests it or evidence shows the current approach is incompatible, unsafe, deprecated, broken, or responsible for a verified issue.
+
+---
+
+## Table of Contents
+
+1. [Safe-Update Decision Model](#safe-update-decision-model)
+2. [Eligible vs Non-Eligible — Examples](#eligible-vs-non-eligible)
+3. [Method for Analyzing Dependency Usage](#method-for-analyzing-dependency-usage)
+4. [Audit Interpretation Rules](#audit-interpretation-rules)
+5. [Package Manager Behavior](#package-manager-behavior)
+6. [Validation Hierarchy](#validation-hierarchy)
+
+---
+
+## Safe-Update Decision Model
+
+### Conditions for considering an update "safe"
+
+A dependency is eligible for a safe update **only when ALL of the following conditions are true**:
+
+1. **Same major version** — the update stays within the same major version (including a patch or minor update) and the upstream release notes do not identify an incompatible change
+2. **No coupled migration** — it is not part of a known migration family that requires source code adaptation
+3. **Role understood** — the dependency's role is known: runtime, build, types, or security
+4. **Validation path exists** — the project exposes a validation path capable of detecting obvious fallout (lint, build, typecheck)
+5. **No forced operations** — the update does not require lockfile override, `resolutions`, codemod, global rewrite, or behavior not supported by the package manager
+
+### Golden rule
+If any condition fails, the update goes to deeper analysis.
+
+---
+
+## Eligible vs Non-Eligible
+
+### Eligible (safe update)
+| Category | Example | Reason |
+|---|---|---|
+| Same-major minor | `next 16.1.x → 16.2.x` | Eligible for release-note review and validation; not inherently free of breaking behavior |
+| Coupled packages | `react + react-dom` | Update together within compatible major versions |
+| Security priority | `axios 1.x → 1.y` | Same-major security update; confirm the advisory path and release notes |
+| Bounded same-major | `@tanstack/react-query 5.x → 5.y` | Same-major update with targeted validation |
+
+### Non-Eligible (requires deep analysis)
+| Dependency | Reason |
+|---|---|
+| `tailwindcss 3 → 4` | Breaking change, config migration |
+| `Chakra UI 2 → 3` | Breaking change, component rewrite |
+| `TypeScript 5 → 7` | Two majors, high risk |
+| `ESLint 9 → 10` | Config breaking change |
+| `Zustand 4 → 5` | API breaking change |
+| `date-fns 2 → 4` | Two majors, breaking changes |
+
+---
+
+## Method for Analyzing Dependency Usage
+
+### Four layers of evidence
+
+Before recommending an update or removal, use these 4 layers:
+
+1. **Runtime import evidence**
+   - Search the code for imports/requires and API calls
+   ```bash
+   rg -n --glob '*.{js,jsx,ts,tsx,mjs,cjs}' \
+     "from ['\"]package-name['\"]|import ['\"]package-name['\"]|require\(['\"]package-name['\"]|import\(['\"]package-name['\"]" src/
+   ```
+   - Also check aliases, generated code, and configuration files; source searches alone are not conclusive.
+
+2. **Framework/config evidence**
+   - Inspect: framework config, PostCSS/Tailwind, ESLint, scripts, Docker, CI
+   - The dependency may be in use even without a direct import in source
+
+3. **Type-system evidence**
+   - Inspect `tsconfig.json`, exported types
+   - Packages that only provide types (e.g., `@types/*`) have no runtime import
+
+4. **Dependency provenance**
+   - Use `yarn why <package>` / `npm ls <package>` / `pnpm why <package>`
+   - Check whether it's a direct or transitive dependency
+
+### Result classification
+
+| Classification | Meaning | Action |
+|---|---|---|
+| **Runtime confirmed** | Direct import/call in source | Do not remove |
+| **Tooling confirmed** | Used by scripts/config/build | Do not remove without checking scripts |
+| **Indirect only** | Required by framework/chain | Check if framework still needs it |
+| **Removal candidate** | No direct or indirect evidence | Remove with validation |
+
+### Generic example
+A package like `sharp` may be listed in `package.json` but have no direct import in source — it may be used internally by the framework (e.g., Next.js uses `sharp` for image optimization). **In this case, even without a direct import, do not remove it without confirming whether the framework still uses it.**
+
+---
+
+## Audit Interpretation Rules
+
+### Rules for interpreting `npm audit` / `yarn audit`
+
+1. **Audit count ≠ business risk**
+   - A package may emit multiple advisories and paths
+   - The number of findings is not the number of independent risks
+
+2. **Root upgrade does not patch nested framework copy**
+   - Root `sharp@0.35` can coexist with `next#sharp@0.34`
+   - Root `postcss@8.5` can coexist with `next#postcss@8.4`
+   - Updating the root does not necessarily resolve the nested copy
+
+3. **Always cross-reference audit output with provenance**
+   ```bash
+   yarn why <package>
+   npm ls <package>
+   ```
+   Inspect the upstream package's `package.json` when necessary.
+
+4. **Classify risk separately**
+   - Findings in toolchain (eslint, webpack, etc.) may be **build-time risk**, not runtime
+   - Do not ignore — classify exposure and remediation separately
+
+5. **Do not add resolutions/overrides just to lower audit count**
+   - Overriding an internal framework range is a policy decision
+   - Requires compatibility validation and explicit approval
+
+---
+
+## Package Manager Behavior
+
+### Yarn Classic (1.x)
+
+| Command | Important behavior |
+|---|---|
+| `yarn outdated` | Exit code `1` when there are updates — **not an error**, it's a sign of findings |
+| `yarn audit --level moderate` | Returns a severity bitmask: info `1`, low `2`, moderate `4`, high `8`, critical `16`; `--level` filters displayed findings but does not change the exit code |
+| `yarn outdated` | Lists current, wanted, and latest versions; it does not diagnose lockfile synchronization |
+| Peer warnings | May exist even with lint/build passing (e.g., React 18 peer range in libs) |
+
+If `package.json` changes, run `yarn install` serially to update `yarn.lock`. In CI, use the project's frozen/immutable lockfile policy to detect unexpected lockfile changes.
+
+### Mandatory serialization
+**Never** run two commands that write to the lockfile in parallel:
+```bash
+# ❌ WRONG: parallel
+yarn add package-a & yarn add package-b
+
+# ✅ CORRECT: serialized
+yarn add package-a
+yarn add package-b
+```
+
+Serialize `install`, `add`, `remove`, and equivalents to avoid:
+- Lockfile races
+- Non-deterministic state
+- Loss of updates
+
+---
+
+## Validation Hierarchy
+
+### Available validation matrix
+
+| Validation | What it proves | Limitation |
+|---|---|---|
+| `lint` | Lint config works, no errors | Does not exercise runtime |
+| `build` | The configured production build pipeline (for example, bundling and framework configuration) | Type checking, route coverage, and generated output depend on the project's toolchain and settings; does not verify external APIs or UX |
+| Dedicated typecheck | Type errors (faster than build) | May not exist as a separate script |
+| Automated tests | Regression of behavior | May not exist |
+| Manual smoke test | UX and integration | Requires human execution |
+
+---