@event4u/agent-config 14.23.0 → 15.0.0

package/dist/agent-src/guidelines/augment-portability-patterns.md

@@ -0,0 +1,70 @@
+# Augment Portability
+
+> Editing or creating files inside .augment/ directory — skills, rules, commands, templates, contexts must be project-agnostic
+
+_Origin: migrated from `.agent-src.uncondensed/rules/augment-portability.md` per P4.2 of `road-to-kernel-and-router.md`._
+
+# Package Portability
+
+Everything that ships with the `event4u/agent-config` package MUST be
+**project-agnostic**. That includes:
+
+- Everything inside `.augment/` (skills, rules, commands, guidelines,
+  templates, contexts)
+- The package repo's own root `AGENTS.md`
+- The package repo's own `.github/copilot-instructions.md`
+
+All three are either installed into consumer projects (`.augment/` via
+`install.sh`) or read by AI tools when working on the package itself
+(`AGENTS.md`, `copilot-instructions.md`). Leaking consumer-specific
+content into any of them pollutes downstream projects or misleads agents.
+
+## Rules
+
+- NEVER reference a specific consumer project, repo name, domain, or tech
+  stack directly. The package repo itself (`event4u/agent-config`) MAY be
+  named inside its own root `AGENTS.md` and `copilot-instructions.md` —
+  that is meta about the package, not a leak.
+- NEVER hardcode consumer-project paths, class names, or conventions.
+- Write content so it works as a **reusable package** across any project.
+- Project-specific behavior belongs in the **consumer's** `.agent-settings.yml`,
+  `AGENTS.md`, or `agents/` — never in files shipped by this package.
+- If a skill or rule needs project-specific input, read it from
+  `.agent-settings.yml` or accept it as a parameter.
+- When reviewing or editing package files, always ask: "Would this still
+  make sense in a completely different project?"
+
+## Runtime invocations — no `task` commands
+
+Skills, rules, commands, guidelines, personas, and context docs run in
+**consumer projects**, which may not have Task installed. **Never**
+reference a `task <something>` invocation inside any artefact file
+under `.agent-src.uncondensed/{skills,rules,commands,guidelines,personas,contexts}/`
+(and therefore also not in the condensed mirror under `dist/agent-src/`).
+Use direct script invocations instead.
+
+## Consumer CLI — `./agent-config`
+
+A subset of package scripts is exposed through a project-local CLI
+wrapper `./agent-config` (written into the project root by the
+installer, gitignored). Artefacts MUST prefer the CLI over raw
+`./scripts-run src/scripts/…` paths for every command the CLI already covers.
+
+## Translation tables — see mechanics
+
+The full `task`-to-script translation table, the `./agent-config`
+CLI mapping, and the rationale (Task absence on consumers,
+maintainer-vs-artefact split) are **in this file**.
+
+> **Corrected 2026-08-26** (`road-to-contract-review-deadlines` 4.2): this
+> paragraph used to point at a `rules-auto` mechanics file under the contexts
+> tree, which exists nowhere in it. The pointer described a split that was never
+> made; the material it names was already here.
+
+## Enforcement
+
+`scripts/check_portability.ts` scans `.augment/`, `.agent-src.uncondensed/`,
+and the package repo's root `AGENTS.md` + `.github/copilot-instructions.md`
+for forbidden identifiers, for any `task <name>` invocation inside
+artefact files, and for direct script invocations that bypass the
+`./agent-config` CLI. It runs in CI and must pass before any PR.

package/dist/agent-src/guidelines/code-clarity.md

@@ -0,0 +1,350 @@
+# Code Clarity
+
+> Cross-language coding-clarity conventions. Cited by language-specific
+> guidelines (`php/general.md`, `php/php-coding-patterns.md`, …) so
+> consumers in any stack get the same baseline.
+
+Applies to PHP, JavaScript / TypeScript, Python, Go, Ruby, and any
+other language the package guides. Language-specific files reference
+this one — they don't duplicate it.
+
+## Don't assign single-use values to a variable
+
+If a value is used **exactly once**, pass the expression directly.
+Don't bind it to a temporary variable just to feed it into the next
+call.
+
+The named variable buys nothing — it adds a line, an identifier the
+reader has to track, and a false signal that the value will be reused.
+
+```php
+// ❌ Avoid — $db is referenced exactly once.
+$db = db::getInstance();
+$this->columnExists($db, 'table', 'column');
+
+// ✅ Prefer — value flows directly to the call.
+$this->columnExists(db::getInstance(), 'table', 'column');
+```
+
+```ts
+// ❌ Avoid
+const user = await getCurrentUser();
+return renderProfile(user);
+
+// ✅ Prefer
+return renderProfile(await getCurrentUser());
+```
+
+```python
+# ❌ Avoid
+config = load_config()
+return Worker(config)
+
+# ✅ Prefer
+return Worker(load_config())
+```
+
+## Carve-outs — keep the variable when
+
+The rule is "single use, no extra meaning". Bind to a variable when
+**any** of these hold:
+
+| Carve-out | Why |
+|---|---|
+| **Used 2 or more times** | Inlining duplicates the expression — re-evaluation, repeated side effects, more diff churn. |
+| **Expression has side effects** | A network call, a write, an `INSERT`, a counter bump must run exactly once and be visible to the reader as such. |
+| **The name carries domain meaning** | `$activeMembership = …; allow($activeMembership)` — the identifier documents intent the call site can't. |
+| **Inlining pushes past the line-length budget** | A 130-char single line is harder to read than two named lines. Match the project's formatter. |
+| **Used inside a loop body** | Hoist the invariant out of the loop; keep the binding. |
+| **Debugger / breakpoint affordance** | Stepping through a named value is materially easier than inspecting an expression mid-call. Prefer the variable in code paths under active investigation. |
+| **Type-narrowing assertion** | `const x: Foo = maybeFoo!; …` where the binding pins the type for the type-checker. |
+
+When in doubt — and the expression is short, side-effect-free, and
+used once — inline it.
+
+## Why this matters
+
+- **Smaller diffs — by removing indirection, never by compression.** Two lines
+  (`$x = ...; f($x)`) become one (`f(...)`) because the naming step carried no
+  information, not because one line is a goal in itself. **Simple is not the
+  same as short:** a flat form one line *longer* beats a dense clever one, and a
+  nested ternary or a long optional-call chain that shrinks the diff while
+  raising the cost of every future read is a regression here, not a win. The
+  shape axis in
+  [`agent-interaction-and-decision-quality` § 8b-shape](agent-infra/agent-interaction-and-decision-quality.md)
+  states the same distinction from the scope side.
+- **Less cognitive load.** Readers don't track an identifier whose
+  whole purpose is "the next line".
+- **Honest signals.** A named variable says "this value is reusable
+  or worth labeling". Single-use bindings break that contract and
+  train readers to ignore names.
+- **Faster refactor.** Renaming the call site doesn't drag a now-stale
+  variable name with it.
+
+## Anti-patterns this rule rejects
+
+- **"Variable for the debugger."** If the file is not under active
+  debugging, drop the binding. Don't ship debug scaffolding.
+- **"Variable to align line lengths."** Use the formatter, not a
+  fake intermediate.
+- **"Variable so I have somewhere to put the type."** Modern type
+  inference makes this redundant in PHP 8+, TS, Python 3.10+, Go,
+  Rust, etc. Annotate the parameter or return type instead.
+
+## Comment discipline — state a constraint, not a narration
+
+A code comment earns its place only by stating a constraint the code
+itself can't show — a non-obvious invariant, a workaround for a specific
+bug, a hidden dependency. It never narrates:
+
+- **Provenance** — "added for the X feature", "per ticket #123". That
+  belongs in the commit message or PR description, not the code; it rots
+  the moment the feature or ticket is forgotten.
+- **What the next line does** — well-named identifiers already say it.
+  A comment repeating the code is noise the reader skips past.
+- **Why the change is correct** — that's a message to the reviewer, not
+  to the next person reading the file after it's merged.
+
+Test: would removing the comment leave a future reader confused about a
+non-obvious constraint? If yes, keep it — tightened to the constraint
+alone. If the comment only restates what identifiers already convey, or
+explains the change's history rather than the code's behavior, cut it.
+
+This is the canonical long-form behind the
+[`code-comment-discipline`](../rules/code-comment-discipline.md)
+rule (whose body is merged here per P4 of `road-to-kernel-and-router.md`).
+External consensus in one line each: comments explain **why, never
+what** (competent readers get the what from the code); Google's style
+guides (C++/Go/Python/TS) ban stating the obvious — Go: prefer
+self-describing names over redundant comments; Python: "never describe
+the code"; modern PHP (framework-mainstream since PHP 8 typing) drops
+docblocks that only restate native type hints; TSDoc/JSDoc type
+annotations are redundant in typed TypeScript.
+
+### Banned comment classes
+
+| Banned | Example | Instead |
+|---|---|---|
+| What-narration | `// increment the counter` above `counter++` | Nothing — the code says it |
+| Signature-mirroring docblock | `@param string $name The name` on `string $name` | Nothing — the typehint says it |
+| Redundant `@return` | `@return bool` on `): bool` | Nothing |
+| Banner / section divider | `// ---------- Helpers ----------` | Structure the file; extract a class |
+| Change-log comment | `// added for the export feature`, `// per ticket #123` | Commit message / PR description |
+| Reviewer-directed justification | `// this is safe because my change …` | PR description |
+| Redundant property docblock | `/** @var LoggerInterface */` on a typed property | Nothing — the property type says it |
+| Type-restating JSDoc in typed TS | `/** @param {string} id */` on `id: string` | Nothing — TS carries the type |
+| Obvious docstring | `"""Return the user."""` on `get_user()` | Nothing, or a real contract note |
+| Commented-out code | dead code kept "for reference" | Delete — git history is the tombstone |
+
+### Carve-out — machine-relevant precision docblocks STAY
+
+A docblock that carries type information the native type system cannot express is **not** redundant — static analyzers and IDEs consume it. Keep (and write) these:
+
+- PHP generics / array shapes for PHPStan/Psalm: `@return Collection<int, Post>`, `@param array<string, User> $usersByEmail`, `@template T`, `@phpstan-type`.
+- Union/shape refinements the language can't express natively.
+- Tool-consumed markers: `@deprecated` (with the successor), `@internal`, `@throws` for checked flows the caller must handle.
+- Python typing that only a docstring/stub can carry in the project's toolchain.
+
+The line: the docblock must add information **beyond** the native signature. `@param array<int, Order> $orders` earns its place; `@param array $orders` does not.
+
+### Public-API carve-out — `code_style.docblocks`
+
+Read `code_style.docblocks` from `.agent-settings.yml` (missing → `minimal`):
+
+- `minimal` (default) — the full discipline above; exported/public symbols get no summary docblock unless one of the five legitimate jobs applies.
+- `full` — the **exported public surface of a library package** (published API consumers see in their IDE) MAY carry a one-line summary docblock per symbol. The redundancy ban still holds in `full`: no `@param`/`@return` lines that mirror the signature, ever.
+
+### Per-language keep/drop tables
+
+Docblocks earn their place only with **machine-relevant precision** the
+native type system cannot carry, or genuine why-context. Per language:
+
+#### PHP / PHPDoc
+
+| Keep | Drop |
+|---|---|
+| `@return Collection<int, Post>` — generic the native type can't carry | `@return bool` on `): bool` |
+| `@param array<string, User> $usersByEmail` — array shape for PHPStan/Psalm | `@param string $name The name.` on `string $name` |
+| `@template T`, `@phpstan-type`, `@phpstan-assert` | `/** @var LoggerInterface */` on a natively-typed property |
+| `@throws PaymentDeclined` where callers must handle it | `/** Constructor. */` |
+| `@deprecated use X instead` — tool-consumed | Method summary that re-words the method name |
+
+```php
+// ❌ Drop — five lines, zero information beyond the signature
+/**
+ * Deactivate the user.
+ *
+ * @param User $user The user to deactivate.
+ * @return void
+ */
+public function deactivate(User $user): void
+
+// ✅ Keep — the docblock carries what PHP's type system cannot
+/** @param array<int, OrderLine> $lines */
+public function totalCents(array $lines): int
+```
+
+#### TypeScript / JSDoc-TSDoc
+
+| Keep | Drop |
+|---|---|
+| A why: `// half-up to match the invoice renderer; Intl default is half-even` | `@param {string} id` on `id: string` |
+| `@deprecated` with the successor named | `@returns the formatted price` on `: string` |
+| `@internal` when the build strips internals | Restating a type the compiler already enforces |
+| Non-obvious unit/contract: `/** epoch millis, NOT seconds */` | `// call the API` above `await api.call()` |
+
+```ts
+// ❌ Drop — TS carries every fact stated here
+/**
+ * Formats the price.
+ * @param amount - the amount to format
+ * @returns the formatted string
+ */
+export function formatPrice(amount: number): string
+
+// ✅ Keep — constraint the signature can't show
+// Rounds half-up to match the invoice PDF renderer; Intl default is half-even.
+export function formatPrice(amount: number): string
+```
+
+#### Python / docstrings
+
+| Keep | Drop |
+|---|---|
+| Contract detail: raises, units, side effects a caller must know | `"""Return the user."""` on `get_user()` |
+| Public-API docstring where the toolchain renders it (Sphinx/mkdocs) | Args section restating annotated params |
+| Type info only expressible in a docstring in this project's toolchain | `# loop over items` above a comprehension |
+
+```python
+# ❌ Drop
+def get_user(user_id: int) -> User | None:
+    """Get the user by id and return it or None."""
+
+# ✅ Keep — behavior the signature can't show
+def get_user(user_id: int) -> User | None:
+    """Reads through the request-local cache; never hits the DB twice per request."""
+```
+
+#### Go / doc comments
+
+| Keep | Drop |
+|---|---|
+| Exported-symbol doc comment (`godoc` renders it) — one sentence, adds intent | Doc comment that re-words the function name |
+| A why on non-obvious concurrency/ordering | `// increment i` |
+
+Go is the one ecosystem where exported symbols conventionally carry a
+doc comment — keep the convention, but the comment still must say
+something the name doesn't.
+
+### Redundancy self-check (any language)
+
+Before emitting a comment or docblock, all three must be true:
+
+1. It states something **beyond** the names and native types.
+2. It will still be true after the next refactor of the lines below it.
+3. It addresses the future reader of the file — not the reviewer of the diff.
+
+One "no" → drop it. When in doubt: no comment.
+
+Those three conditions are the code-comment instance of a wider test. The
+generalised form — five questions covering comments, docblocks, labels, hints,
+tooltips, placeholders, badges and empty states alike — is the Information Delta
+Test in [`redundancy-taxonomy`](redundancy-taxonomy.md), together with the
+representation classes that name what a redundant surface *is*. Reach for it
+whenever the surface is not a code comment, and whenever a reduction would touch
+the semantic channel: an accessibility name is required information, so it is a
+hard guard and never a deletion candidate. The rule is not "less text" — it is
+that if removing the text loses no information in any required channel, remove
+it, and if the information is required, express it once, in the strongest native
+form available.
+
+The same document carries the **naming** half, which fires earlier than any of
+this: before introducing a term for a concept, search for the term the tree
+already uses. A second word for an existing concept costs a reader more than a
+redundant sentence does — a redundant sentence is skipped, a second name makes
+them check whether they are looking at one thing or two.
+
+### Additional worked examples
+
+(The TypeScript `formatPrice` pair above is the canonical TS example; these
+cover the remaining shapes.)
+
+```php
+// ❌ Redundant — every line restates the signature
+/**
+ * Get the user by id.
+ *
+ * @param int $id The user id.
+ * @return User|null The user or null.
+ */
+public function getUserById(int $id): ?User
+
+// ✅ Nothing to add — the signature is the documentation
+public function getUserById(int $id): ?User
+```
+
+```php
+// ✅ Docblock KEPT — the generic is machine-relevant (PHPStan), the native type can't carry it
+/** @return Collection<int, Post> */
+public function publishedPosts(): Collection
+```
+
+```python
+# ❌ Narration
+# loop over the items and sum the totals
+total = sum(item.total for item in items)
+
+# ✅ A why that survives
+# Stripe amounts are integer cents; convert once at the boundary, never downstream.
+total_cents = sum(item.total_cents for item in items)
+```
+
+### Scope boundary
+
+The comment discipline governs **new and edited code only**. It is never a
+license to strip comments from untouched code —
+[`minimal-safe-diff`](../rules/minimal-safe-diff.md) wins on diff shape
+("no docstrings/comments on untouched code" cuts both ways: don't add, don't
+remove). Sweeping a file's existing comments is a separate,
+explicitly-requested cleanup task.
+
+### Fixtures
+
+Behavioral baseline: `tests/code-comments/eval-fixtures.md`
+(`ccd-php-class-generation`, `ccd-ts-module-generation`,
+`ccd-untouched-preservation`, `ccd-explicit-teaching-override`); the decidable
+criteria are proven by `tests/scripts/code_comment_fixtures.test.ts`.
+
+### Evidence belongs in the roadmap that asked for it
+
+Measured 2026-09-02 in a consumer repository: **509 German comment lines** and
+**21 report- or provenance-shaped comments** across **41 of 45** changed source
+files, the worst a 101-line colour-analysis report inside a CSS file. The cause
+was a roadmap requiring proof for every checked step: the run read that as
+*evidence should be documented* and wrote the measurements into the source too,
+where the roadmap already carried them.
+
+The provenance of a value is not a WHY, and a roadmap cannot license a comment
+the rule forbids.
+
+Two enforcers carry this because neither rule could fire on a write:
+`code-comment-discipline` matches prompt keywords, and `language-and-tone`'s
+English-comment clause named a `.md`-only validator. `lint_code_comments`
+refuses on the diff; the `comment-discipline` concern reports on the text as
+written. Neither replaces the discipline.
+
+## See also
+
+- Language-specific anchors that link to this guideline:
+  - PHP: `docs/guidelines/php/general.md` § Variables
+  - PHP: `docs/guidelines/php/php-coding-patterns.md` § Variables
+- `code-comment-discipline` rule — the always-loaded enforcement surface
+  for the comment-discipline clause above.
+- `minimal-safe-diff` rule — orthogonal but aligned: smallest change
+  that solves the stated problem; also owns "no comment additions or
+  removals on untouched code".
+- `direct-answers` rule — same spirit at the prose level: shortest
+  version that fully answers the question.
+- [`redundancy-taxonomy`](redundancy-taxonomy.md) — the shared classes,
+  verdicts and Information Delta Test this section instantiates for code
+  comments; also cited by the review and refactoring skills.

package/dist/agent-src/guidelines/component-oriented-and-oop-development.md

@@ -0,0 +1,189 @@
+# Component-Oriented & Object-Oriented Development
+
+> Cross-cutting development standard: **think in reusable units, and — in an
+> object-oriented / class-based codebase — treat object-oriented design as a
+> high-priority default where it reduces complexity.** Split by surface below
+> (frontend / backend), each pointing to the stack-specific carve-outs rather
+> than restating them. Framework-neutral by construction — React / Storybook /
+> Laravel / Symfony specifics live in their own skills, never here.
+
+## Paradigm-appropriate first — detect, then apply
+
+**Reuse is universal; OOP is paradigm-scoped.** Detect the codebase's paradigm
+before applying the object-oriented half: class-based / OO code (PHP, Java, C#,
+typical TS/React service layers) → this standard's OOP guidance is the
+high-priority default. A **functional / pipeline / actor-model** codebase
+(Elixir/Phoenix, Clojure, Haskell, Go-idiomatic, heavy FP-in-TS) → apply *that*
+paradigm's principles (immutability, pure functions, pattern-matching,
+composition of functions), and read the OOP bullets as "the same rigor, its
+paradigm's shape." **Never impose classes on functional code to satisfy this
+standard** — consistency with the codebase's chosen paradigm wins over OOP
+advocacy, always.
+
+## The standard, in one breath
+
+- **Reuse before you build** (every paradigm). Compose from units that already
+  exist — audit first, reuse the design system / shared abstractions, extract a
+  new unit only when the same shape repeats.
+- **Object-oriented where it fits** (in an OO codebase). Encapsulation, single
+  responsibility, composition over inheritance, and behavior-rich objects are
+  the high-priority default *when they reduce complexity* — not a quota to hit,
+  and not imposed on a codebase that has chosen a different paradigm.
+
+## The load-bearing caveat — reuse/OOP is a tool, never a mandate to abstract
+
+This standard **never** authorizes speculative abstraction. It is bounded by the
+package's restraint posture and defers to it on every conflict:
+
+- [`minimal-safe-diff`](../rules/minimal-safe-diff.md) (+ its
+  anti-over-engineering mechanics) — smallest change; no premature abstraction,
+  no speculative feature, no rewrite for taste.
+- [`senior-engineering-discipline`](../rules/senior-engineering-discipline.md)
+  — reuse the *existing* abstraction; generalize, don't overfit; never invent an
+  API to look object-oriented.
+- [`improve-before-implement`](../rules/improve-before-implement.md) —
+  "does it fit the existing architecture?" before adding structure.
+- **When NOT to use a pattern** ([`php/patterns.md`](php/patterns.md) §) — KISS &
+  YAGNI trump pattern purity: no interface for a single implementation, no
+  pattern for a five-line function, no class where a function is clearer.
+
+Rule of thumb: **two real repetitions (or a genuine second axis of change)
+before you extract a code-level abstraction.** One occurrence is not a
+component; one branch is not a Strategy. A reviewer should be able to name the
+concrete duplication or the concrete change-axis the abstraction removes.
+UI extractions carry deliberately higher, scoped bars (shell 3+ · stateful
+component ~4 + real state) — the per-class canon is
+[`abstraction-thresholds`](abstraction-thresholds.md); this file does not
+restate it.
+
+**Precedence (explicit): `minimal-safe-diff` / YAGNI always trump OOP
+advocacy.** When "prefer OO shape" and "smallest change" conflict, the smallest
+change wins — this standard adds a *consideration*, never a competing objective
+that pressures preemptive abstraction. The review lens (below) may flag OO shape
+only where the duplication or the growing branch is **already present in the
+diff**, never as "this could grow later."
+
+## Frontend — think in reusable components
+
+Component-first is the default mindset, not an afterthought: decompose a screen
+into composable units, reuse the project's primitives, and extract shared shells
+when they repeat. Depth and mechanics already live in dedicated skills — consult
+them, don't duplicate:
+
+- [`fe-design`](../skills/fe-design/SKILL.md) § Component Architecture —
+  the stack-agnostic "kind, not framework" taxonomy, granularity, and the
+  UI-shell bar (per [`abstraction-thresholds`](abstraction-thresholds.md)).
+- [`ui-component-architect`](../skills/ui-component-architect/SKILL.md) —
+  how to *shape* a reusable component: composition over inheritance, slot
+  contracts, prop-API caps, controlled/uncontrolled, the stateful-component
+  bar (repeat **and** real state, per the same canon).
+- [`existing-ui-audit`](../skills/existing-ui-audit/SKILL.md) — the
+  reuse-before-invent gate: inventory existing components/tokens/primitives
+  first (enforced by [`ui-audit-gate`](../rules/ui-audit-gate.md)).
+- [`design-tokens`](../skills/design-tokens/SKILL.md) /
+  [`design-system-capture`](../skills/design-system-capture/SKILL.md) —
+  the shared token/design-system layer components draw from.
+
+**Component workshop (Storybook et al.) — when the project is large enough.**
+For a project with a real, growing shared-component library, isolating and
+documenting each reusable component in a component workshop (Storybook or the
+ecosystem equivalent) pays for itself — it makes components discoverable,
+reviewable in isolation, and reused instead of re-invented. It is **not** worth
+the setup for a small surface with a handful of one-off components. The
+framework-specific setup is a carve-out, not a generic mandate — React /
+Storybook specifics: [`react-shadcn-ui`](../skills/react-shadcn-ui/SKILL.md)
+§ Component workshop.
+
+Framework carve-outs (never restated here): React →
+[`react-shadcn-ui`](../skills/react-shadcn-ui/SKILL.md); Next.js
+server/client component boundary →
+[`nextjs-patterns`](../skills/nextjs-patterns/SKILL.md); Laravel FE →
+[`blade-ui`](../skills/blade-ui/SKILL.md) /
+[`livewire`](../skills/livewire/SKILL.md) /
+[`flux`](../skills/flux/SKILL.md); styling →
+[`tailwind-engineer`](../skills/tailwind-engineer/SKILL.md).
+
+## Backend — object-oriented where it reduces complexity
+
+The structural half — thin handlers, business logic in services / use-cases,
+behavior-rich domain models, validation at the boundary — is owned by
+[`architecture`](../rules/architecture.md) and holds across paradigms. In
+an **object-oriented / class-based** service layer, layer the OO principles below
+on top of it, each applied only where it earns its place. In a **functional /
+pipeline** codebase, apply that paradigm's equivalent (pure functions +
+composition instead of behavior-rich objects; a dispatch map / pattern-match
+instead of a Strategy class) — the goal (encapsulate change, one responsibility,
+compose don't duplicate) is paradigm-independent; only its *shape* is OO here:
+
+- **Encapsulation** — objects own their data + the behavior over it; no anemic
+  bags mutated from the outside.
+- **Single responsibility** — one class, one reason to change; no god services.
+- **Composition over inheritance** — inject collaborators; reach for a base
+  class only for genuine is-a substitutability, not code sharing.
+- **Behavior-rich domain objects** — push rules into the model, keep services
+  orchestration-thin.
+- **Patterns where they earn their place** — a Strategy when a branch on a
+  discriminator will grow (`if-else` chain → polymorphism); a Factory when
+  construction is non-trivial; DI on an abstraction when there is a *real*
+  second implementation. Not before.
+
+Language / framework carve-outs (never restated here): PHP →
+[`php-coding-patterns`](php/php-coding-patterns.md) +
+[`patterns.md`](php/patterns.md) (+ `php/patterns/strategy.md`,
+`php/patterns/dependency-injection.md`, `php/patterns/factory.md`,
+`php/patterns/service-layer.md`)
++ skills [`php-coder`](../skills/php-coder/SKILL.md) /
+[`php-service`](../skills/php-service/SKILL.md); Laravel →
+[`laravel`](../skills/laravel/SKILL.md); Symfony →
+[`symfony-workflow`](../skills/symfony-workflow/SKILL.md); Next.js / TS →
+[`nextjs-patterns`](../skills/nextjs-patterns/SKILL.md); cross-language
+clean-code baseline → [`code-clarity`](code-clarity.md).
+
+## Enums over scattered literals
+
+A field with two or more non-boolean states is an enum, not a bare string /
+magic number — the small OO move that keeps a codebase greppable and safe to
+change. Full rule + the defer-and-ask flow for pre-existing literals:
+[`prefer-enums-over-literals`](../rules/prefer-enums-over-literals.md).
+
+## How this is reviewed
+
+"Reuse existing components + object-oriented shape (where it reduces
+complexity)" is a check on the code-quality review lens
+([`judge-code-quality`](../skills/judge-code-quality/SKILL.md)), so it
+reaches `/review-changes`, `/judge`, the subagent judge modes, and team-mode's
+fallback review frame. It fires **only where the duplication or the growing
+branch is already present in the diff** — never "this could grow later" — and
+in the **codebase's own paradigm** (it will not tell a functional service to
+grow a class). It stays a human-judgment call that defers to the codebase's own
+conventions — never a generic SOLID dogma imposed over a project that has chosen
+differently.
+
+## Council review (2026-07-15)
+
+Deep debate, 3 rounds, cross-vendor (`anthropic/claude-sonnet-4-5` +
+`openai/gpt-4o`), $0.16. Split verdict; the load-bearing (anthropic) critique —
+that an "OOP-supreme default" over-indexes on OOP for a multi-paradigm consumer
+base and can conflict with `minimal-safe-diff` — was applied, bounded by this
+standard's stated purpose (OOP *is* a deliberate high priority for the operator):
+
+- **Paradigm-appropriate framing** — OOP is the high-priority default *within an
+  OO / class-based codebase*; detect and defer to a functional / pipeline /
+  actor paradigm; never impose classes on functional code (§ Paradigm-appropriate).
+- **Explicit precedence** — `minimal-safe-diff` / YAGNI win on conflict; the
+  review lens flags only *already-present* duplication / complexity, never
+  preemptive (§ caveat, § How this is reviewed).
+
+Divergence held: the frontend section stays (an intentional FE / backend
+entry-point + carve-out index, per the operator's explicit "split by FE /
+backend" ask) — against the anthropic "delete as redundant"; it is a cohesive
+index of the existing FE surfaces, not a claim of novel guidance. The trace is
+the 2026-07-15 session above, not a path: council output is gitignored and
+auto-pruned, and this guideline is a stable artifact that must not carry a link
+which rots (`no-roadmap-references`).
+
+## See also
+
+- [`architecture`](../rules/architecture.md) — the structural home this layers onto.
+- [`code-clarity`](code-clarity.md) — the cross-language clean-code baseline.
+- [`minimal-safe-diff`](../rules/minimal-safe-diff.md) · [`senior-engineering-discipline`](../rules/senior-engineering-discipline.md) — the restraint anchors this standard is bounded by.