codex-orchestrator 2.0.11 → 2.0.13

package/internal-workflow/skills/code-review/SKILL.md

@@ -1,309 +1,87 @@
 ---
-name: "code-review"
-description: "Evidence-first review of code, PRs, commits, regressions, or review-and-fix work using correctness and standards/cleanup lenses. Auto-fix only qualifying high-confidence severe issues."
+name: code-review
+description: Read-only Review entrypoint for a settled diff. Substantial changes receive independent Spec and Standards review; targeted repair review runs only the affected lens.
 ---
 
-# Code Review
-
-This skill performs evidence-based code review. It is not a style pass and not a summary. Treat the change as potentially wrong until independent review tracks fail to break it.
-
-Passing tests, test names, checklists, and implementation reports are inputs,
-not proof. For each material behavior, trace the production path before reading
-its tests, attempt one concrete violating sequence, then verify that the exact
-setup, actions, and assertions reject it. If a fake bypasses the claimed
-boundary or the test stays green, report a finding or verification gap; do not
-approve nominal coverage.
-
-The review always covers two lenses:
-
-- **Correctness reviewer**: bugs, regressions, runtime behavior, security, contracts, caches, concurrency, framework rules, and failure paths.
-- **Spec & standards reviewer**: requested behavior, documented repo standards, architecture fit, duplication, cleanup, and workaround-shaped implementation.
-
-The main agent is the coordinator. It pins the review target, assigns both
-lenses to one reviewer for `simple` and `medium`, and splits them across two
-independent reviewers only for `high`. It verifies the strongest findings,
-applies only safe fixes, and returns a concise findings-first report.
-
-Full review is bounded to the settled diff, its authority, changed owners, and
-callers or contracts with plausible fan-out. `Full` means complete coverage of
-that assigned scope once; it does not mean a repository-wide audit. Do not load
-unrelated modules or activate optional lenses without a diff signal or mandatory
-Review Focus.
-
-## When To Use
-
-Use this skill when the user asks for:
-
-- code review, PR review, commit audit, regression scan, or bug hunt
-- review since a branch, commit, tag, merge-base, or working tree state
-- review and fix of critical or high-severity high-confidence defects
-- framework-focused review such as `NestJS`, `Next.js`, `Flutter`, or `Dart`
-
-For every implementation profile, the spec/standards lens includes bounded
-cleanup for duplication, obsolete paths, workaround branches, and unjustified
-abstractions. High-risk work assigns that lens to its own reviewer in the same
-parallel final wave. A concrete evidenced simplification risk named by the
-user, approved source, or repo policy amplifies this lens inside the same review
-activation; it never creates a separate cleanup gate.
-
-Exception for approved spec execution: follow
-`../spec-implementer/references/review-loop.md`. Intermediate code-review
-checkpoints activate only their assigned Review Focus; final cleanup coverage
-uses the durable Review Plan and canonical Defect Ledger.
-
-## Implementation Review Adapter
-
-When this skill is called from `$spec-implementer`:
-
-- read `../spec-implementer/references/review-loop.md` and the persisted
-  `## Implementation Review State`
-- recheck the scheduled profile against the settled diff; return an
-  underclassified profile to the executor before launching reviewers
-- accept the scheduled mode, session, revision, and lenses after that check
-- pin the target and give reviewers the owner-defined capsule
-- return the usable result and stable defect updates to the executor
-- keep cleanup findings in the spec/standards lineage and canonical Defect Ledger
-
-Do not infer a fresh review loop, choose another mode, or make the owner's
-terminal decision inside this Adapter.
-
-## Progressive References
-
-Read only the references the current review needs:
-
-- Detailed bug classes: `references/bug-classes.md`
-- Cleanup lens method: `references/cleanup-lens.md`
-- Framework lenses for Next.js, NestJS, Flutter, and Dart: `references/framework-lenses.md`
-- Targeted recipes for recurring diff shapes: `references/targeted-recipes.md`
-- Contract test ledger: `../../docs/agents/contract-test-ledger.md`
-- Shared confidence rubric: `../../docs/agents/confidence-rubric.md`
-
-Load `references/framework-lenses.md` when the user names a framework or files/configs strongly imply one. Load `references/targeted-recipes.md` when the diff shape matches them. Load `../../docs/agents/contract-test-ledger.md` only for a material contract delta with a named failure ordinary targeted proof could miss. Load `references/bug-classes.md` for substantial reviews or broad bug hunts.
-Load `references/cleanup-lens.md` when the spec/standards lens is assigned. Use
-its bounded method by default and its amplified method only for a concrete
-evidenced simplification risk supplied as mandatory Review Focus.
-
-## Coordinator Workflow
-
-### 1. Pin The Review Target
-
-Identify exactly what is being reviewed.
-
-- If the user gave a fixed point, use it directly: branch, commit SHA, tag, `main`, `HEAD~5`, etc.
-- If they did not, infer from context:
-  - current uncommitted work: `git diff` plus staged diff if relevant
-  - branch review: `git diff <base>...HEAD`
-  - commit review: `git show <commit>`
-- If there is no safe inference, ask one short question: "Review against which branch or commit?"
-
-Capture:
-
-- `git status --short`
-- diff stat
-- the exact diff command used
-- commit list when reviewing a branch range
-- changed files and nearest related tests/docs
-
-Use three-dot diff for branch/base reviews: `git diff <fixed-point>...HEAD`.
-
-### 2. Discover Spec And Standards
-
-Do this before reviewer tracks so both tracks receive bounded inputs.
-
-Spec sources, in priority order:
-
-1. Issue or PR references in commit messages, branch names, PR metadata, or user prompt.
-2. A spec/PRD/plan path supplied by the user.
-3. Matching files under `docs/`, `specs/`, `.scratch/`, or local issue folders.
-4. If none exists, continue and mark the spec axis as "no spec found" instead of inventing requirements.
-
-Standards sources:
-
-- `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`
-- `CONTEXT.md`, context maps, domain docs, ADRs
-- `STYLE.md`, `STANDARDS.md`, style guides, review checklists
-- `.editorconfig`, ESLint, Biome, Prettier, TypeScript, analyzer, or framework configs
-- relevant test files and existing examples in the touched area
-
-Machine-enforced config matters as context, but do not spend review findings on issues a required formatter/linter would already catch unless the tool is absent or failing.
-
-### 3. Activate Lenses
-
-Before deep review, decide which lenses apply.
-
-- Always activate the general correctness and spec/standards lenses.
-- Always apply bounded cleanup inside spec/standards; amplify it only for a
-  concrete evidenced Review Focus, never from size or risk labels alone.
-- Add framework lenses when explicit or strongly implied by files/configs.
-- Add targeted recipes when the diff shape matches them.
-- If the user, plan, or implementation spec provides `Review Focus`, treat each listed lens, targeted recipe, invariant, and risk as mandatory. Do not replace it with a generic review; report any focus item that cannot be verified as a verification gap.
-- If inference is uncertain, say so and continue with the best-supported review instead of pretending certainty.
-
-Mandatory delta lenses:
-
-- **Contract Delta Review:** If the diff expands a shared contract, enum/status, schema, DTO, permission, capability, token, or scope, search old consumers and report `changed contract -> searched call sites -> risky fallback/default branches -> tests or fix`.
-- **Backend Trust Boundary Review:** If the diff adds a credential, OAuth scope, permission, role-sensitive write, or external capability, verify the backend-side guard. UI controls, query/state flags, and caller intent are not authorization.
-
-Common framework signals:
-
-- **Next.js**: `next.config.*`, `app/**`, `pages/**`, route handlers, server actions, `use server`, `use client`, revalidation APIs.
-- **NestJS**: `@nestjs/*`, controllers, providers, modules, guards, pipes, interceptors, DTOs, `nest-cli.json`.
-- **Flutter**: `pubspec.yaml`, `lib/**`, widgets, navigation, bloc/provider/riverpod/notifiers.
-- **Dart**: `.dart`, `Future`, `Stream`, isolates, generated serializers, null-safety constructs.
-
-### 4. Run Profile-Selected Reviewers
-
-For `simple`, run one `reviewer_fast`; for `medium`, run one
-`reviewer_standard`. Assign that child both correctness and spec/standards
-lenses in one bounded Full review. For `high`, run two `reviewer_deep` children
-in parallel with one disjoint lens each. Invoking `$code-review` authorizes
-these reviewers. Preserve every fulfilled launch handle if a parallel peer
-fails, then close all launched children. Tell every reviewer not to edit or
-revert unrelated work.
-
-Begin every reviewer launch brief with an exact `Assigned role: <role>` line,
-using `reviewer_fast`, `reviewer_standard`, or `reviewer_deep`. Keep that role
-explicit for Full and Closure launches even when the profile or existing
-lineage already implies it; a generic child prompt is not evidence that the
-profile-selected reviewer topology was executed.
-
-A reviewer is launched only after the child-launch tool returns a non-empty
-handle for that brief. Wait only on returned handles, then close every launched
-child. Never treat an intended role, an empty wait, coordinator analysis, or a
-final-answer claim as reviewer execution. If launch is unavailable or returns
-no handle, report the independent review gate as unavailable and do not
-self-review or claim that the reviewer completed.
-
-A recorded reviewer role or lineage from an earlier Full review identifies
-which role must own Closure; it is never a live child handle. Every Closure
-activation must launch a new child in that same role for the current session,
-capture the new non-empty handle, and wait only on that handle.
-
-For spec-driven checkpoints, obey the track assignment in the persisted Review
-Plan instead of automatically launching both default tracks.
-
-Medium is the normal review profile. API, persistence, multiple files, or a
-shared-looking name do not select `high` unless evidence proves both a material
-failure consequence and an uncertainty amplifier.
-
-When already inside an assigned reviewer child, execute its assigned lens set
-inline and return it to root; do not spawn a grandchild.
-If the user forbids delegation, report the independent review gate as waived or
-unavailable according to the parent workflow; root must not self-review inline.
-
-#### Correctness Reviewer Brief
-
-Include the exact diff command or commit under review, changed file list, commit list, active references, any `Review Focus`, and an instruction to read surrounding execution paths.
-
-> Review runtime correctness adversarially. Hunt concrete bugs in control flow, state, async/concurrency, security, auth, contracts, schemas, caching, persistence, UI/API integration, and framework-specific behavior. If a Review Focus is provided, explicitly test the named risks first, such as duplicate side effects, retry/idempotency, ordering, source-of-truth ownership, partial failure, DTO/schema drift, or false user-facing state. For each finding, provide file/line, trigger path, impact, why guards do not prevent it, severity, and confidence. Do not report style nits or generic "needs tests" comments.
-> For bugfixes, check claim boundaries: what changed tests prove, what they do not prove, and whether sibling execution paths can still violate the claimed invariant.
-> When Contract Delta Review applies, follow new values through old consumers and default/fallback branches before trusting local tests. When Backend Trust Boundary Review applies, verify the server-side authorization predicate at the write/callback boundary.
-
-#### Spec & Standards Reviewer Brief
-
-Include the exact diff command or commit under review, spec source path/content or "no spec found", standards source list, changed file list, commit list, any `Review Focus`, and an instruction to cite the spec or standard behind each finding.
-
-> Review the change against the requested work and repo standards. Check missing requirements, partial behavior, scope creep, undocumented contract changes, architecture drift, duplicate source-of-truth logic, dead/legacy branches, and workaround-shaped implementation. If a Review Focus is provided, explicitly verify each named ownership, scope, validation, and invariant risk against the spec. Cite the spec or standard when available. If there is no spec, skip requirement claims and focus on documented standards and architecture evidence.
-> Apply `references/cleanup-lens.md`: use bounded cleanup by default, or the amplified method when a concrete evidenced simplification risk is mandatory Review Focus. Keep cleanup findings in this review's normal Defect Ledger. Do not create a cleanup-only verdict or separate pass.
-
-### 5. Aggregate And Verify
-
-The coordinator must not blindly relay reviewer output.
-
-1. Deduplicate findings across tracks.
-2. Re-read the relevant code for the strongest findings.
-3. Drop findings that lack a concrete trigger path.
-4. Reclassify severity/confidence using `../../docs/agents/confidence-rubric.md` if evidence does not support the label.
-5. For real contract defects that pass the ledger gate, identify the missing or inadequate invariant when TDD/spec evidence is available.
-6. Confirm every mandatory `Review Focus` item and mandatory delta lens was reviewed; if not, report the unverified item as a verification gap.
-7. Confirm that mandatory behavior evidence rejects the concrete violating
-   sequence attempted by the reviewer. Evidence that bypasses its claimed
-   production boundary invalidates that Full coverage.
-8. Decide whether auto-fix is allowed.
-9. Run the narrowest meaningful verification after any fix.
-
-Keep the two axes visible in your own notes, but present the final report by severity unless the user explicitly asked for side-by-side Standards/Spec output.
-
-After repairs, verify medium or low findings through the coordinator's direct
-failure-path check plus affected validation. Launch Closure only for the
-severity, protected-contract, or invalidated-coverage triggers owned by
-`review-protocol.md`. For a scheduled Closure, send the bounded capsule to the
-selected reviewer lineage and return its defect updates.
-
-## Evidence Standard
-
-A valid finding explains:
-
-- what breaks
-- why it breaks
-- the input, sequence, role, tenant, environment, or timing that triggers it
-- where the defect lives
-- why existing guards do not prevent it
-- severity and confidence
-
-Do not file:
-
-- style nits disguised as correctness issues
-- speculative races without a shared-state path
-- generic "needs tests" comments without a concrete regression risk
-- architecture discomfort without wrong ownership, duplication, leakage, or a regression path
-- performance comments without a hot path or failure mode
-
-## Auto-Fix Policy
-
-Automatically fix only when all are true:
-
-- severity is critical or high
-- confidence is high under `../../docs/agents/confidence-rubric.md`
-- root cause is clear
-- correct fix is narrow and low-risk
-- fix matches local project patterns
-- verification is available, or the edit is obviously safe and syntax-checkable
-
-When auto-fixing:
-
-- patch only the bug
-- add/update behavior tests when regression risk is meaningful and the codebase supports it; update a ledger only when its gate passes
-- rerun relevant verification
-- never revert unrelated user changes
-
-Do not auto-fix ambiguous semantics, product decisions, broad refactors, or low-confidence concerns. Report them with evidence.
-
-## Output Contract
-
-For review-only tasks:
-
-1. Findings first, ordered by severity.
-2. File and line references for each finding.
-3. Trigger path, impact, severity, confidence, and evidence.
-4. Open questions, assumptions, or verification gaps.
-5. Short summary only after findings.
-
-For review-and-fix tasks:
-
-1. State which critical or high-severity high-confidence issues were fixed.
-2. Report remaining findings that were not fixed.
-3. Give one short verification note and any blocked checks.
-4. Keep the closing summary user-facing and outcome-based.
-
-If there are no findings, say so clearly and mention residual test or verification gaps.
-
-For spec-driven review checkpoints or final review gates, include a compact review handoff that can feed the executor's Final Risk Handoff: reviewed target, Review Focus status, high/critical findings fixed or remaining, skipped checks, and residual verification gaps. Keep findings first.
-
-If inline review comments are requested, emit one `::code-comment{...}` directive per actionable finding.
-
-## Tooling Defaults
-
-- Use `rg`/`rg --files` for code search.
-- Prefer parallel reads for status, diff, changed files, related modules, tests, repo docs, and standards.
-- Use official docs or Context7 only when a finding depends on version-sensitive framework/library behavior.
-- Run the narrowest meaningful tests first, then required lint/build/analyzer checks for touched areas.
-- Keep raw command output out of the final response unless the user asks for it.
-
-## Decision Defaults
-
-- If the user says "review", default to findings-first review.
-- If the user says "review and fix", auto-fix only critical or high-severity high-confidence issues that satisfy the auto-fix policy.
-- If the user provides a framework focus, explicitly use it.
-- If no focus is provided, infer active lenses from the diff and say when they materially affected findings.
-- Ask clarification only when the correct review target or fix would otherwise be risky or ambiguous.
+# Review
+
+Review a settled change through two independent lenses:
+
+- **Spec:** requirement fidelity, missing or partial behavior, incorrect
+  implementation, and scope drift.
+- **Standards:** correctness, failure paths, repository policy, maintainability,
+  legacy residue, duplicate ownership, and unnecessary machinery.
+
+Review is inspection-only. Never edit, repair, stage, commit, push, or open a
+PR. Substantial behavior or contract changes require Review; obvious local
+docs, copy, formatting, mechanical config, or corrections may use direct proof.
+
+## Boundaries
+
+- **Authorized outcome:** the request, issue, or Parent PRD plus existing
+  invariants and mandatory repository rules.
+- **Impact cone:** callers, data, runtime, and proof surfaces that may be
+  inspected to establish effects. Inspection creates no authority.
+- **Repair scope:** the smallest change that restores a proven obligation,
+  invariant, or mandatory rule without widening the authorized outcome.
+
+A reviewer verdict is evidence, not authority. Mark a finding `BLOCKER` only
+when evidence links a concrete defect or required-proof gap to an authorized
+obligation, existing invariant, or mandatory rule. Include its source,
+file/line, trigger, impact, and evidence. Treat unsupported preferences,
+hypothetical hardening, and architecture or cleanup beyond the outcome as
+`OBSERVATION`.
+
+For Standards, read [standards-smells.md](references/standards-smells.md).
+Fowler smells remain non-blocking observations unless separate evidence meets the blocker
+threshold. Repository policy wins, and tooling-enforced rules need no duplicate
+finding. If optional machinery causes a defect, prefer deleting it; extend it
+only when the authorized outcome requires it.
+
+## Process
+
+1. Pin an existing baseline and settled target, then verify the comparison is
+   valid and non-empty. Supply the exact diff, changed files, proof, authority
+   source, and repository policy. Missing required authority or proof is a gap;
+   never silently skip a lens.
+2. Select the mode:
+   - initial Review launches one fresh `spec_reviewer` and one fresh `standards_reviewer`
+     in parallel;
+   - targeted Review runs only the affected lens: Spec-only repair for
+     requirement coverage or behavior, Standards-only repair for correctness,
+     invariants, architecture, or mandatory rules, and both lenses when the
+     repair affects both or cannot be isolated.
+   Give targeted reviewers the previous reviewed revision, repair delta,
+   repaired blockers, direct impact cone, and affected proof. Untouched
+   previously approved scope retains approval.
+3. Give both reviewers the same target, diff, proof, authority, policy, and
+   boundaries above. Keep each brief under 400 words and begin it with
+   `Assigned role: <role>`.
+   - `spec_reviewer` checks only missing, partial, incorrect, or extra behavior
+     against cited authority.
+   - `standards_reviewer` checks correctness, failure paths, policy, cleanup,
+     zero legacy, duplicate ownership, unnecessary machinery, and the smell
+     baseline without inventing product obligations.
+4. Use fresh children without history fork (`fork_context=false` on V1;
+   `fork_turns="none"` on V2). Capture every non-empty child identity and wait
+   for those same children. An empty bounded wait means wait again, not failure.
+   Silence is not a hang; request status only without interruption. Never
+   interrupt, terminate, close, or replace an active reviewer. Missing identity,
+   terminal failure, interruption, or incomplete final wait blocks Review;
+   root never substitutes self-review.
+5. Reconcile each finding from its evidence, preserving its lens and defect
+   identity. Reclassify unsupported `BLOCK` labels as observations; an
+   `APPROVE` label cannot erase a verified blocker. Consolidate all verified
+   blockers into one repair batch for the active Implement or Tickets
+   Orchestrator owner. Their original authority covers repairs inside Repair
+   scope without another confirmation. For review-only requests, report and
+   stop without invoking Implement.
+6. Return `Spec` and `Standards` results separately, then consolidated blockers,
+   observations, and proof gaps. Approve only after every selected independent
+   reviewer completed and no verified blocker or required-proof gap remains.
+   Review may approve with observations. A complete Review repeats only when a
+   repair cannot be isolated.
+
+Each reviewer returns findings first, labelled `BLOCKER` or `OBSERVATION`, then
+`APPROVE` or `BLOCK` with a concrete reason. Do not create durable review state,
+maps, ledgers, aliases, adapters, or compatibility routes.

package/internal-workflow/skills/code-review/agents/openai.yaml

@@ -1,4 +1,6 @@
 interface:
-  display_name: "Code Review"
-  short_description: "Profile-routed correctness and standards review"
-  default_prompt: "Use $code-review for one final profile-selected wave; high risk uses two parallel reviewers and the spec/standards lens includes bounded cleanup."
+  display_name: "Review"
+  short_description: "Independent requirements and standards review"
+  default_prompt: "Use $code-review to inspect the settled change with independent Spec and Standards lenses. Report findings without implementing or repairing them."
+policy:
+  allow_implicit_invocation: true

package/internal-workflow/skills/code-review/evals/evals.json

@@ -0,0 +1,83 @@
+{
+  "schema_version": 1,
+  "skill": "code-review",
+  "cases": [
+    {
+      "id": "authorized-regression-blocks",
+      "prompt": "A settled diff breaks an existing caller invariant required by the authorized behavior; the failing public-seam regression proves the trigger and impact.",
+      "expected": [
+        "report a blocker linked to the existing invariant",
+        "include the trigger, impact, and regression evidence",
+        "return BLOCK"
+      ],
+      "forbidden": [
+        "downgrade the proven regression to an observation",
+        "require a broader solution than restoring the invariant"
+      ]
+    },
+    {
+      "id": "optional-architecture-is-observation",
+      "prompt": "The authorized outcome and all existing invariants pass, but the reviewer prefers a more robust architecture for hypothetical future load.",
+      "expected": [
+        "report the architecture or robustness idea only as an observation",
+        "approve when no authorized obligation, invariant, mandatory rule, or proof is missing"
+      ],
+      "forbidden": [
+        "turn hypothetical robustness into a blocker",
+        "treat the reviewer label or impact cone as authority"
+      ]
+    },
+    {
+      "id": "optional-machinery-prefers-removal",
+      "prompt": "The diff adds an optional mediator that is not needed by the authorized outcome, and the mediator contains a defect. Removing it preserves all required behavior and invariants.",
+      "expected": [
+        "prefer removing the optional mediator",
+        "keep repair scope within the authorized outcome"
+      ],
+      "forbidden": [
+        "require hardening or extending the optional mediator",
+        "expand the authorized outcome to preserve unnecessary machinery"
+      ]
+    },
+    {
+      "id": "unsupported-block-reconciles-to-approval",
+      "prompt": "A completed independent reviewer returns BLOCK, but coordinator verification proves every reported item is an optional preference with no authorized obligation, invariant, mandatory rule, or required-proof gap.",
+      "expected": [
+        "reclassify the unsupported findings as observations",
+        "return APPROVE from the completed independent evidence",
+        "perform no repair"
+      ],
+      "forbidden": [
+        "repeat review solely because of the reviewer label",
+        "expand the authorized outcome to satisfy an unsupported verdict"
+      ]
+    },
+    {
+      "id": "two-independent-read-only-lenses",
+      "prompt": "Run Review on one settled substantial target and report its findings.",
+      "expected": [
+        "launch fresh Spec and Standards reviewers in parallel",
+        "keep their findings separated by lens",
+        "keep Review read-only",
+        "return observations and consolidated blockers to the caller"
+      ],
+      "forbidden": [
+        "repair the target",
+        "let either reviewer invent new authority"
+      ]
+    },
+    {
+      "id": "targeted-review-selects-affected-lens",
+      "prompt": "A reviewed repair delta only restores one missing authorized requirement and changes no correctness, invariant, architecture, or repository-rule surface.",
+      "expected": [
+        "run only a fresh Spec reviewer",
+        "limit review to the repair delta and direct impact cone",
+        "preserve untouched approval"
+      ],
+      "forbidden": [
+        "rerun Standards without an affected Standards surface",
+        "repeat the complete review"
+      ]
+    }
+  ]
+}

package/internal-workflow/skills/code-review/references/standards-smells.md

@@ -0,0 +1,41 @@
+# Standards Smell Baseline
+
+Two rules bind this baseline:
+
+- **The repo overrides.** A documented repo standard always wins; where it
+  endorses something the baseline would flag, suppress the smell.
+- **Always a judgement call.** Each smell is a labelled heuristic, never a hard
+  violation — and, like any standard here, skip anything tooling already
+  enforces.
+
+Each smell reads *what it is* -> *how to fix*:
+
+- **Mysterious Name** — a function, variable, or type whose name doesn't reveal
+  what it does or holds. -> rename it; if no honest name comes, the design's
+  murky.
+- **Duplicated Code** — the same logic shape appears in more than one hunk or
+  file in the change. -> extract the shared shape, call it from both.
+- **Feature Envy** — a method that reaches into another object's data more than
+  its own. -> move the method onto the data it envies.
+- **Data Clumps** — the same few fields or params keep travelling together (a
+  type wanting to be born). -> bundle them into one type, pass that.
+- **Primitive Obsession** — a primitive or string standing in for a domain
+  concept that deserves its own type. -> give the concept its own small type.
+- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs
+  across the change. -> replace with polymorphism, or one map both sites share.
+- **Shotgun Surgery** — one logical change forces scattered edits across many
+  files in the diff. -> gather what changes together into one module.
+- **Divergent Change** — one file or module is edited for several unrelated
+  reasons. -> split so each module changes for one reason.
+- **Speculative Generality** — abstraction, parameters, or hooks added for needs
+  the spec doesn't have. -> delete it; inline back until a real need shows.
+- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't
+  depend on. -> hide the walk behind one method on the first object.
+- **Middle Man** — a class or function that mostly just delegates onward. -> cut
+  it, call the real target direct.
+- **Refused Bequest** — a subclass or implementer that ignores or overrides most
+  of what it inherits. -> drop the inheritance, use composition.
+
+A smell alone is a non-blocking observation. Escalate only when evidence
+demonstrates a concrete defect or proof gap causally linked to an explicit
+obligation, existing invariant, or mandatory repository rule.