@tplog/hasapi 0.1.0

package/hasapi-skills/_shared/custom-risks-guide.md

@@ -0,0 +1,48 @@
+# Custom Risk Loading Guide
+
+When `.brooks-lint.yaml` contains a `custom_risks` map, this guide governs how those
+risks are loaded and scanned. Custom risks use `Cx` codes (C1, C2, …) — no conflict with
+the standard R1–R6 and T1–T6 namespaces.
+
+---
+
+## Loading
+
+1. For each entry in `custom_risks`, validate that it has:
+   - `name` — non-empty string
+   - `question` — the diagnostic question to ask
+   - `symptoms` — non-empty list of symptom patterns
+   - `severity` — map with at least one of: `critical`, `warning`, `suggestion`
+
+2. Register each valid entry as a `Cx` code alongside R1–R6 / T1–T6. Once loaded,
+   `Cx` codes become valid targets for `disable`, `focus`, and `severity` fields in
+   the same config file.
+
+3. Report any validation errors as config warnings (do not abort the review):
+   - Missing required field: `"Config warning: C1 missing 'symptoms'"`
+   - Invalid code format (must be `C` followed by digits): skip, note error
+   - Code conflicts with R/T namespace: skip, note error
+
+---
+
+## Scanning
+
+During the analysis, treat each custom risk as an additional step after the standard
+process:
+
+- Use `question` as the diagnostic question
+- Use `symptoms` as the symptom lookup list
+- Use the `severity` map for tier classification
+- Apply the Iron Law: `Source` field should be `"[Project-defined risk] — <risk name>"`
+- Include custom risk findings in the Health Score (same deduction rules as R/T codes)
+- In the report, custom findings appear after standard findings under a
+  **### Project-Specific Risks** sub-heading
+
+---
+
+## Config Validation additions
+
+The following codes are valid in `disable`, `focus`, and `severity`:
+- Standard: `R1`–`R6`, `T1`–`T6`
+- Custom: any `Cx` code defined in `custom_risks`
+- Any other code: skip it and emit `"Config warning: X is not a valid risk code"`

package/hasapi-skills/_shared/decay-risks.md

@@ -0,0 +1,294 @@
+# Decay Risk Reference
+
+Six patterns that cause software to degrade. Apply the Iron Law to each finding.
+
+---
+
+## Risk 1: Cognitive Overload
+
+**Diagnostic question:** How much mental effort does a human need to understand this?
+
+Cognitive load beyond working memory causes mistakes, avoidance, and blocks the refactoring that would fix it.
+
+### Symptoms
+
+- Function longer than 20 lines where multiple levels of abstraction are mixed together
+- Nesting depth greater than 3 levels
+- Parameter list with more than 4 parameters
+- Magic numbers or unexplained constants
+- Variable names that require reading the implementation to understand (e.g., `d`, `tmp2`, `flag`)
+- Boolean expressions with 3 or more conditions combined
+- Train-wreck chains: `a.getB().getC().doD()`
+- Code names that do not match what the business calls the same concept
+- Flag Arguments: a boolean parameter that makes the function do two fundamentally different
+  things depending on its value — a sign the function has two responsibilities
+- Primitive Obsession: domain concepts represented as primitive types (`String email`,
+  `int orderId`, `double money`) rather than purpose-built value types — forces callers to know
+  which string is an email and which is a name
+- Shallow module: the interface or documentation of a component is more complex relative to
+  the functionality it provides
+
+### Sources
+
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Long Method | Fowler — Refactoring | Long Method |
+| Long Parameter List | Fowler — Refactoring | Long Parameter List |
+| Message Chains | Fowler — Refactoring | Message Chains |
+| Flag Arguments | Fowler — Refactoring | Flag Arguments |
+| Primitive Obsession | Fowler — Refactoring | Primitive Obsession |
+| Function length and nesting | McConnell — Code Complete | Ch. 7: High-Quality Routines |
+| Variable naming | McConnell — Code Complete | Ch. 11: The Power of Variable Names |
+| Magic numbers | McConnell — Code Complete | Ch. 12: Fundamental Data Types |
+| Domain name mismatch | Evans — Domain-Driven Design | Ubiquitous Language |
+| Shallow Module | Ousterhout — A Philosophy of Software Design | Ch. 4: Modules Should Be Deep |
+
+### Severity Guide
+
+- 🔴 Critical: function > 50 lines, nesting > 5, or virtually no meaningful names
+- 🟡 Warning: function 20–50 lines, nesting 4–5, some unclear names
+- 🟢 Suggestion: minor naming issues, 1–2 magic numbers, isolated train-wreck chains
+
+### What Not to Flag
+
+- Linear code with clear names and guard clauses is not automatically high cognitive load
+- Internal implementation detail hidden behind a deep, simple module boundary is not a shallow-module problem
+- Domain-specific terminology should not be flagged if it matches how experts actually speak
+
+---
+
+## Risk 2: Change Propagation
+
+**Diagnostic question:** How many unrelated things break when you change one thing?
+
+Each change ripples to unrelated modules, slowing velocity and multiplying regression risk.
+
+### Symptoms
+
+- Modifying one feature requires touching more than 3 files in unrelated modules
+- One class changes for multiple different business reasons (e.g., `UserService` changes for
+  billing logic AND notification logic AND profile logic)
+- A method uses more data from another class than from its own class
+- Two classes know each other's internal state directly
+- Changing one module requires recompiling or retesting many unrelated modules
+- **Hyrum's Law**: with sufficient callers, every observable behavior — including
+  implementation details, error message text, coincidental call ordering, and undocumented
+  side effects — becomes an implicit contract that callers depend on, even though it was
+  never guaranteed by the declared API
+- **Orthogonality violation**: changing one dimension of a feature forces edits in
+  unrelated dimensions — adding a new payment type should not require touching logging,
+  caching, or notification code, but in a non-orthogonal design it does
+- Information Leakage: a design decision (e.g., a file format, protocol detail, or data
+  shape) is encoded in more than one module, so changing it requires coordinated edits
+  in multiple places even though only one module "owns" the concept
+
+### Sources
+
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Shotgun Surgery | Fowler — Refactoring | Shotgun Surgery |
+| Divergent Change | Fowler — Refactoring | Divergent Change |
+| Feature Envy | Fowler — Refactoring | Feature Envy |
+| Inappropriate Intimacy | Fowler — Refactoring | Inappropriate Intimacy |
+| Orthogonality violation | Hunt & Thomas — The Pragmatic Programmer | Ch. 2: Orthogonality |
+| DIP violation | Martin — Clean Architecture | Dependency Inversion Principle |
+| High change propagation radius | Brooks — The Mythical Man-Month | Ch. 2: Brooks's Law (communication overhead) |
+| Hyrum's Law | Winters et al. — Software Engineering at Google | Ch. 1: Hyrum's Law |
+| Information Leakage | Ousterhout — A Philosophy of Software Design | Ch. 5: Information Hiding and Leakage |
+
+### Severity Guide
+
+- 🔴 Critical: one change touches > 5 files, or there is a structural dependency inversion (domain depends on infrastructure)
+- 🟡 Warning: one change touches 3–5 files, mild coupling between modules
+- 🟢 Suggestion: minor coupling, easily isolatable
+
+### What Not to Flag
+
+- A composition root wiring concrete dependencies is not a DIP violation by itself
+- A stable public API with intentionally supported behavior is not automatically Hyrum's Law debt
+- Similar edits inside one bounded context may be normal coordinated change, not shotgun surgery
+
+---
+
+## Risk 3: Knowledge Duplication
+
+**Diagnostic question:** Is the same decision expressed in more than one place?
+
+Multiple copies drift apart silently. DRY is about decisions, not code lines.
+
+### Symptoms
+
+- Same logic copy-pasted across multiple files or functions
+- Same concept named differently in different parts of the codebase
+  (e.g., `user`, `account`, `member`, `customer` all referring to the same domain entity)
+- Parallel class hierarchies that must change in sync
+  (e.g., adding a new payment type requires adding a class in 3 different hierarchies)
+- Configuration values repeated as literals in multiple places
+- Two modules that implement the same algorithm independently
+
+### Sources
+
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Code duplication | Fowler — Refactoring | Duplicate Code |
+| Parallel Inheritance | Fowler — Refactoring | Parallel Inheritance Hierarchies |
+| DRY violation | Hunt & Thomas — The Pragmatic Programmer | DRY: Don't Repeat Yourself |
+| Inconsistent naming | Evans — Domain-Driven Design | Ubiquitous Language |
+| Alternative Classes | Fowler — Refactoring | Alternative Classes with Different Interfaces |
+
+### Severity Guide
+
+- 🔴 Critical: core business logic duplicated across modules, or same domain concept named 3+ different ways
+- 🟡 Warning: utility code duplicated, naming inconsistent within a subsystem
+- 🟢 Suggestion: minor literal duplication, single naming inconsistency
+
+### What Not to Flag
+
+- Repetition across separate bounded contexts is not automatically duplicate knowledge
+- Temporary duplication during an active extraction or migration is not necessarily debt
+- Shared protocol constants repeated at explicit boundaries may be acceptable when local ownership is clearer
+
+---
+
+## Risk 4: Accidental Complexity
+
+**Diagnostic question:** Is the code more complex than the problem it solves?
+
+Accidental complexity accumulates addition by addition until developers fight scaffolding more than solving the problem.
+
+### Symptoms
+
+- Abstractions built "for future use" with no current consumer
+  (e.g., a plugin system for a use case that has only one known implementation)
+- Classes that barely justify their existence (wrap a single method call)
+- Classes that only delegate to another class without adding behavior (pure middle-men)
+- Second attempt at a system that is significantly more elaborate than the first,
+  adding generality for requirements that do not yet exist
+- Switch statements that signal missing polymorphism
+- Configuration options that have never been changed from their defaults
+- Framework code larger than the application it powers
+- Code grown under sustained tactical shortcuts: each workaround seemed small, but
+  accumulated shortcuts mean every new feature requires fighting the existing structure
+
+### Sources
+
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Speculative Generality | Fowler — Refactoring | Speculative Generality |
+| Lazy Class | Fowler — Refactoring | Lazy Class |
+| Middle Man | Fowler — Refactoring | Middle Man |
+| Switch Statements | Fowler — Refactoring | Switch Statements |
+| Second System Effect | Brooks — The Mythical Man-Month | Ch. 5: The Second-System Effect |
+| YAGNI violations | McConnell — Code Complete | Ch. 5: Design in Construction |
+| Over-engineering | Hunt & Thomas — The Pragmatic Programmer | Topic 4: Good-Enough Software |
+| Tactical programming debt | Ousterhout — A Philosophy of Software Design | Ch. 3: Strategic vs. Tactical Programming |
+
+### Severity Guide
+
+- 🔴 Critical: an entire subsystem built around a speculative requirement, or framework overhead dominates domain logic
+- 🟡 Warning: several unnecessary abstractions or wrapper classes, unused configuration systems
+- 🟢 Suggestion: one or two lazy classes or middle-man patterns in non-critical paths
+
+### What Not to Flag
+
+- A switch over an external protocol, wire format, or closed enum is not automatically missing polymorphism
+- Thin wrappers that absorb vendor churn or hide instability may be justified
+- A larger second version is not second-system effect unless the added generality exceeds present needs
+
+---
+
+## Risk 5: Dependency Disorder
+
+**Diagnostic question:** Do dependencies flow in a consistent, predictable direction?
+
+When business logic depends on infrastructure, infrastructure changes cascade into domain changes. Cycles prevent isolation.
+
+### Symptoms
+
+- Circular dependencies between modules or packages
+- High-level business logic directly imports from low-level infrastructure
+  (e.g., a domain service imports from a specific database driver)
+- Stable, widely-used components depend on unstable, frequently-changing ones
+- Abstract components depending on concrete implementations
+- Law of Demeter violations: `order.getCustomer().getAddress().getCity()`
+- Module fan-out greater than 5 (imports from more than 5 other modules)
+- A module implements an interface but only uses a subset of its methods, or must
+  provide stub implementations for methods it does not need (ISP violation: fat interface
+  forces unwanted dependencies on callers)
+- The system feels like "one mind did not design this" — different modules use
+  incompatible architectural patterns with no clear rule for which to use where
+- Direct version-pinned dependencies on transitive packages (diamond dependency risk);
+  upgrading one library requires coordinating multiple unrelated teams or repositories
+
+### Sources
+
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Dependency cycles | Martin — Clean Architecture | Acyclic Dependencies Principle (ADP) |
+| DIP violation | Martin — Clean Architecture | Dependency Inversion Principle (DIP) |
+| Instability direction | Martin — Clean Architecture | Stable Dependencies Principle (SDP) |
+| Abstraction mismatch | Martin — Clean Architecture | Stable Abstractions Principle (SAP) |
+| ISP violation | Martin — Clean Architecture | Interface Segregation Principle (ISP) |
+| Conceptual integrity | Brooks — The Mythical Man-Month | Ch. 4: Conceptual Integrity |
+| Law of Demeter | Hunt & Thomas — The Pragmatic Programmer | Ch. 5: Decoupling and the Law of Demeter |
+| SOLID violations | Martin — Clean Architecture | Single Responsibility, Open/Closed Principles |
+| Diamond dependency / upgrade blockage | Winters et al. — Software Engineering at Google | Ch. 21: Dependency Management |
+
+### Severity Guide
+
+- 🔴 Critical: dependency cycles present, or domain layer directly depends on infrastructure layer
+- 🟡 Warning: several SDP or DIP violations but no cycles; conceptual inconsistency across modules
+- 🟢 Suggestion: minor Demeter violations, slightly elevated fan-out in isolated modules
+
+### What Not to Flag
+
+- High fan-out in an orchestration layer or composition root is not automatically disorder
+- Adapter modules may depend on both domain and infrastructure when they explicitly translate across the boundary
+- A stable facade over many leaf dependencies can be healthy if dependency policy is clear
+
+---
+
+## Risk 6: Domain Model Distortion
+
+**Diagnostic question:** Does the code faithfully represent the problem it is solving?
+
+Code that mismatches business language forces mental translation. Over time it models schemas instead of the domain, with logic bleeding into service layers.
+
+### Symptoms
+
+- Business logic scattered across service layers while domain objects have only getters and setters
+  (anemic domain model)
+- Code variable, class, or method names that do not match what business stakeholders call the concept
+- A class whose only purpose is to hold data with no behavior (pure data bag)
+- A subclass that ignores or overrides most of its parent's behavior (refuses the inheritance)
+- Bounded context boundaries crossed without any translation or anti-corruption layer
+- Methods that are more interested in the data of another class than their own
+  (domain logic in the wrong place)
+- A subclass overrides most parent methods with incompatible behavior or throws exceptions
+  where the parent contract guarantees success (LSP violation: substitution breaks callers)
+- Value Objects treated as Entities: a concept defined entirely by its attributes (e.g., Money,
+  Email, Address) is given a mutable ID and lifecycle instead of being replaced when changed
+
+### Sources
+
+| Symptom | Book | Principle / Smell |
+|---------|------|-------------------|
+| Anemic Domain Model | Evans — Domain-Driven Design | Domain Model pattern |
+| Ubiquitous Language drift | Evans — Domain-Driven Design | Ubiquitous Language |
+| Bounded context violation | Evans — Domain-Driven Design | Bounded Context |
+| Data Class | Fowler — Refactoring | Data Class |
+| Refused Bequest | Fowler — Refactoring | Refused Bequest |
+| Feature Envy | Fowler — Refactoring | Feature Envy |
+| LSP violation | Martin — Clean Architecture | Liskov Substitution Principle (LSP) |
+
+### Severity Guide
+
+- 🔴 Critical: domain logic entirely in service layer, domain objects are pure data bags with no behavior
+- 🟡 Warning: partial anemia, some naming inconsistency between code and domain language
+- 🟢 Suggestion: minor naming drift in non-core areas, isolated cases of Feature Envy
+
+### What Not to Flag
+
+- CRUD-heavy workflows may legitimately use transaction scripts instead of rich domain objects
+- DTOs, persistence records, and API payload models are allowed to be data-only
+- Shared infrastructure language should not be mistaken for domain drift if the business model itself is simple

package/hasapi-skills/_shared/remedy-guide.md

@@ -0,0 +1,37 @@
+# Remedy Guide — Actionable Fix Mode
+
+When `--fix` is active, enhance every finding's Remedy field to be directly actionable:
+
+## Remedy Enhancement Rules
+
+For each finding, the Remedy must include:
+1. **Target**: exact file path and function/class name
+2. **Action**: specific refactoring operation (e.g., "Extract lines 45-67 into a new
+   function `calculateShippingCost(items, config)`")
+3. **Rationale**: one sentence explaining why this specific fix (not just "refactor")
+
+## Fixability Classification
+
+Classify each finding after writing the enhanced Remedy:
+
+| Tier | Criteria | Report label |
+|------|---------|-------------|
+| Quick fix | Single-file, mechanical: rename, extract constant, reorder imports | `[quick-fix]` |
+| Guided fix | Requires a design choice: where to split, what interface shape | `[guided]` |
+| Manual | Cross-module, needs domain knowledge or team discussion | `[manual]` |
+
+Append the label to the finding title: `**R1 — Long function in OrderService [quick-fix]**`
+
+## Output Addition
+
+After the standard report, add a **Fix Summary** section:
+
+| Finding | Tier | Target File | Action |
+|---------|------|------------|--------|
+| R1 — Long function | quick-fix | src/order.ts:45 | Extract `calculateTotal()` |
+| R5 — Circular dep | manual | src/models/ ↔ src/services/ | Introduce interface boundary |
+
+## What NOT to do
+- Do NOT modify any files. Phase 1 is diagnosis + actionable plan only.
+- Do NOT generate diffs or code blocks. The Remedy text IS the deliverable.
+- Do NOT re-score. The Health Score reflects current state, not projected state.

package/hasapi-skills/_shared/source-coverage.md

@@ -0,0 +1,248 @@
+---
+books:
+  - The Mythical Man-Month
+  - Code Complete
+  - Refactoring
+  - Clean Architecture
+  - The Pragmatic Programmer
+  - Domain-Driven Design
+  - A Philosophy of Software Design
+  - Software Engineering at Google
+  - xUnit Test Patterns
+  - The Art of Unit Testing
+  - Working Effectively with Legacy Code
+  - How Google Tests Software
+---
+
+# Source Coverage Matrix
+
+Use this file after selecting a mode and before writing findings.
+It exists to prevent shallow "book-name citation" reviews.
+
+## Review Discipline
+
+- Cite a book only when the observed symptom actually matches that book's principle.
+- A threshold crossing is a hint, not a verdict. Check context, intent, and blast radius.
+- Look for justified tradeoffs before flagging a smell as debt.
+- Prefer concrete architectural or domain consequences over abstract style complaints.
+- If two books pull in different directions, state the tradeoff instead of pretending there is no tension.
+
+---
+
+## Frederick Brooks — *The Mythical Man-Month*
+
+**Encoded today**
+- Change propagation as communication overhead
+- Second-System Effect
+- Conceptual Integrity
+
+**Do not ignore**
+- Whether the design shows a single coherent idea or competing local optimizations
+- Whether cross-team coordination cost is becoming part of feature cost
+
+**Do not over-flag**
+- Large systems are not automatically second systems
+- Multi-module designs are acceptable when they preserve conceptual integrity
+
+---
+
+## Steve McConnell — *Code Complete*
+
+**Encoded today**
+- Routine length, nesting, naming, and magic numbers
+- Construction-phase YAGNI checks
+- Defensive programming and error-handling discipline (guard clauses, input validation,
+  explicit error paths, assertions for invariants)
+
+**Do not ignore**
+- Whether low-level readability choices compound into operational risk
+- Whether missing error handling makes failure modes invisible to maintainers
+
+**Do not over-flag**
+- Small, explicit guard clauses are not cognitive overload
+- A long routine may be acceptable when it is linear, well-named, and single-purpose
+
+---
+
+## Martin Fowler — *Refactoring*
+
+**Encoded today**
+- Long Method, Long Parameter List, Message Chains
+- Shotgun Surgery, Divergent Change, Feature Envy, Inappropriate Intimacy
+- Duplicate Code, Speculative Generality, Lazy Class, Middle Man, Data Class
+- Flag Arguments: boolean parameters that split a function into two behaviors
+- Primitive Obsession: domain concepts expressed as raw primitive types instead of value types
+
+**Do not ignore**
+- Whether the code smell is local or systemic
+- Whether a refactoring target has a natural home in the model
+
+**Do not over-flag**
+- Temporary duplication during an active extraction is not always debt
+- A data-focused structure is acceptable when it is intentionally a DTO or boundary record
+
+---
+
+## Robert C. Martin — *Clean Architecture*
+
+**Encoded today**
+- DIP, ADP, SDP, SAP, and layering direction
+- ISP: fat interfaces that force callers to depend on methods they do not use
+- LSP: subclasses that break the behavioral contract of their parent type
+- SRP and OCP: classes with multiple reasons to change; modules closed to modification
+  but open to extension via abstraction
+
+**Do not ignore**
+- Policy vs detail boundaries
+- Whether dependency arrows preserve replaceability and testability
+
+**Do not over-flag**
+- Composition roots may depend on concrete infrastructure by design
+- Thin adapter layers can import both directions when they are explicitly boundary glue
+
+---
+
+## Andrew Hunt & David Thomas — *The Pragmatic Programmer*
+
+**Encoded today**
+- Orthogonality
+- DRY
+- Law of Demeter
+
+**Do not ignore**
+- Whether knowledge duplication is really duplicated decision-making
+- Whether coupling is accidental or a deliberate local simplification
+
+**Do not over-flag**
+- Similar code in different bounded contexts is not automatically a DRY violation
+- Direct object access inside a cohesive aggregate is not always a Demeter problem
+
+---
+
+## Eric Evans — *Domain-Driven Design*
+
+**Encoded today**
+- Ubiquitous Language
+- Bounded Context
+- Anemic Domain Model
+- Entity vs Value Object: objects with identity and lifecycle vs. objects defined solely by
+  their attributes (Money, Email, Address should be immutable value types, not mutable entities)
+- Aggregate Roots: who owns the invariant boundary; cross-aggregate access only through the root
+
+**Do not ignore**
+- Aggregate boundaries, invariant ownership, and anti-corruption layers
+- Whether names match the business language used by experts
+
+**Do not over-flag**
+- CRUD-heavy workflows may legitimately use transaction scripts
+- Thin entities are acceptable when the domain itself is simple
+
+---
+
+## John Ousterhout — *A Philosophy of Software Design*
+
+**Encoded today**
+- Deep vs shallow modules
+- Strategic vs tactical programming
+- Information Leakage: a design decision encoded in more than one module, creating
+  change coupling even when no explicit import exists between the modules
+
+**Do not ignore**
+- Interface complexity relative to hidden complexity
+- Whether repeated tactical patches are raising long-term cognitive load
+- Whether a "helper" exposes internal design decisions that callers should not know
+
+**Do not over-flag**
+- Internal implementation complexity is fine when the interface stays simple
+- A small wrapper is acceptable when it meaningfully absorbs volatility
+
+---
+
+## Titus Winters, Tom Manshreck, Hyrum Wright — *Software Engineering at Google*
+
+**Encoded today**
+- Hyrum's Law
+- Dependency management and upgrade blockage
+- Code sustainability: whether code as written can be maintained, migrated, and upgraded
+  over a multi-year horizon without heroic effort
+- Backward compatibility: whether API changes preserve existing callers or force
+  coordinated upgrades across the organization
+
+**Do not ignore**
+- De facto APIs created by observable behavior
+- The maintenance cost of exposing too much surface area
+- Whether the dependency graph will allow independent upgrades over time
+
+**Do not over-flag**
+- A stable public API is not a liability if it is intentionally supported
+- Fan-out alone is not disorder when dependency policy is explicit and governed
+
+---
+
+## Gerard Meszaros — *xUnit Test Patterns*
+
+**Encoded today**
+- Assertion Roulette, Mystery Guest, General Fixture
+- Eager Test, Lazy Test, Test Code Duplication, Behavior Verification
+- Erratic Test: tests that produce non-deterministic results due to shared state,
+  time dependence, or ordering assumptions between tests
+
+**Do not ignore**
+- Whether test failures are diagnosable
+- Whether the suite shape amplifies maintenance cost
+
+**Do not over-flag**
+- Multiple assertions are acceptable when they express one behavior with one failure story
+- Shared fixtures are acceptable when every field is relevant to the scenario
+
+---
+
+## Roy Osherove — *The Art of Unit Testing*
+
+**Encoded today**
+- Test naming discipline
+- Test isolation
+- Mock usage guidelines
+- Completeness of edge-path tests
+
+**Do not ignore**
+- Whether tests verify behavior rather than wiring
+- Whether seams are used to simplify tests, or production code is being contorted for testability
+
+**Do not over-flag**
+- A mock is acceptable when the dependency is nondeterministic and the assertion still verifies behavior
+- Naming conventions are guidance; clarity is the goal
+
+---
+
+## Michael Feathers — *Working Effectively with Legacy Code*
+
+**Encoded today**
+- Legacy code as code without tests
+- Sensing and Separation
+- Seams
+- Characterization Tests
+
+**Do not ignore**
+- Whether the team can change a risky area safely today
+- Whether the code offers any seam for isolating behavior under change
+
+**Do not over-flag**
+- Untested code is not automatically legacy if it is stable and not under active change
+- Characterization tests are most important before modifying unclear existing behavior
+
+---
+
+## Google Engineering — *How Google Tests Software*
+
+**Encoded today**
+- Change coverage vs line coverage
+- Pyramid shape and suite portfolio economics
+
+**Do not ignore**
+- Whether the suite reflects business risk, not just percentages
+- Whether expensive tests dominate feedback loops
+
+**Do not over-flag**
+- A non-70:20:10 ratio can be healthy when justified by platform constraints or product risk
+- High coverage is useful when paired with meaningful branch and change protection