@event4u/agent-config 1.9.1

package/.agent-src/templates/agents/agent-project-settings.example.yml

@@ -0,0 +1,138 @@
+# .agent-project-settings.yml — repo-shared agent settings
+#
+# Committed to the repository (the opposite of `.agent-settings.yml`
+# which is git-ignored and per-developer). This file holds decisions
+# that belong to the **project**, not to an individual's workstation.
+#
+# Precedence (lowest → highest):
+#   1. Package defaults (shipped by event4u/agent-config)
+#   2. This file (.agent-project-settings.yml) — team defaults
+#   3. .agent-settings.yml — developer overrides (gitignored)
+#
+# Any key marked `locked: true` in this file CANNOT be overridden by
+# .agent-settings.yml. Use sparingly — locked keys reduce developer
+# autonomy. Reserve for compliance or correctness concerns (e.g.
+# forcing a test framework, pinning a coding style).
+#
+# Copy this file to `.agent-project-settings.yml` (drop the `.example`)
+# and commit it.
+
+schema_version: 1
+
+# --- Project identity ---
+project:
+  # Short slug used in agent output, prompts, and PR metadata. Keep it
+  # identical to the repo name unless there is a reason to differ.
+  slug: ""
+
+  # Human-readable name — used in generated docs and PR bodies.
+  name: ""
+
+  # Primary stack indicator — agent uses this to pick the right skills.
+  # Examples: "laravel", "nextjs", "symfony", "node-express", "react",
+  # "zend-laminas", "multi" (polyglot monorepo).
+  stack: ""
+
+# --- Memory layer (optional) ---
+#
+# Opt-in signal for the @event4u/agent-memory companion package and
+# the repo-shared curated-memory files. If omitted, memory features
+# stay inert — no writes, no reads, no nagging.
+memory:
+  # Enable curated memory files under `agents/memory/` as part of
+  # this repo's dogfooding of its own memory conventions. Only flip
+  # to true after you have agreed on the six content types from
+  # road-to-engineering-memory.md.
+  dogfood: false
+
+  # Path strategy for curated files. `agents` keeps them alongside
+  # roadmaps; `github` puts routing-relevant files under `.github/`.
+  # `auto` picks `github` if that directory exists, else `agents`.
+  path_strategy: auto
+
+  # Hygiene reminders — the agent nudges when entries are stale.
+  # Expiry is evaluated per type (see road-to-engineering-memory.md).
+  hygiene:
+    enabled: true
+    # Warn when `last_validated` is older than this (days). 0 = off.
+    staleness_days: 180
+
+# --- Review routing (optional) ---
+#
+# Points the `review-routing` skill at the two project-local YAML
+# files. See guidelines/agent-infra/review-routing-data-format.md
+# for the schema.
+review_routing:
+  # Location of ownership-map.yml and historical-bug-patterns.yml.
+  # `github` = .github/<file>.yml · `agents` = agents/<file>.yml ·
+  # `auto` = first match wins.
+  location: auto
+
+# --- Role modes (optional) ---
+#
+# Default role loaded for every session in this repo. See
+# guidelines/agent-infra/role-contracts.md for the six modes.
+# Leave empty to fall back to inferred mode switching.
+roles:
+  # One of: developer, reviewer, tester, po, incident, planner.
+  default: ""
+
+  # If set, the agent refuses work outside the default contract
+  # until the user explicitly switches modes with `/mode <name>`.
+  locked: false
+
+# --- Personas (optional) ---
+#
+# Personas are reusable review lenses (see .augment/personas/README.md).
+# Skills cite them in frontmatter (`personas: [id]`). This block lets
+# the project decide the default cast used by multi-lens skills without
+# editing each skill. A developer's .agent-settings.yml can override
+# or narrow the selection unless the key is listed under `locked_keys`.
+personas:
+  # Core cast always loaded by multi-lens skills when `personas:` is
+  # omitted from the skill's frontmatter. Drop an id to remove it from
+  # the default cast repo-wide. Known Core ids: developer,
+  # senior-engineer, product-owner, stakeholder, critical-challenger,
+  # ai-agent.
+  default: [developer, senior-engineer, product-owner, stakeholder, critical-challenger, ai-agent]
+
+  specialists:
+    # Specialist personas auto-included on every multi-lens run. `qa`
+    # is the v1 specialist; more land in v1.1+ (security, performance).
+    # Leave empty to require explicit --personas=+<id> opt-in.
+    auto_include: [qa]
+
+# --- Quality pipeline (optional) ---
+#
+# Per-language gate tools the `quality-fix` command invokes. Empty
+# list = skip the language. Agent will still auto-detect; these
+# values are advisory.
+quality:
+  php:
+    # Tools to run in order. Known: phpstan, rector, ecs, pint.
+    tools: [phpstan, rector, ecs]
+  js:
+    # Known: eslint, prettier, tsc, biome.
+    tools: [eslint, prettier, tsc]
+
+# --- Locked keys (override this file only; never locks .agent-settings.yml) ---
+#
+# List keys from this file whose values cannot be overridden by a
+# developer's .agent-settings.yml. Dot-notation. Example:
+#   locked_keys:
+#     - project.stack
+#     - quality.php.tools
+locked_keys: []
+
+# --- Links to curated data (read-only references) ---
+#
+# Paths the agent consults read-only during work. Curated memory
+# files live here when memory.dogfood is true. These paths are for
+# reference only — no enforcement is done from this file.
+references:
+  architecture_decisions: agents/memory/architecture-decisions/
+  domain_invariants: agents/memory/domain-invariants/
+  incident_learnings: agents/memory/incident-learnings/
+  product_rules: agents/memory/product-rules/
+  ownership_map: ""            # auto-resolved by review-routing
+  historical_bug_patterns: ""  # auto-resolved by review-routing

package/.agent-src/templates/agents/memory/architecture-decisions.example.yml

@@ -0,0 +1,95 @@
+# architecture-decisions.yml — indexed ADRs with path constraints
+#
+# Writer:   decision author at ADR time
+# Reader:   `feature-plan`, `api-design`, `blast-radius-analyzer`
+#           (consulted BEFORE proposing structural changes)
+# Expiry:   marked `deprecated` on reversal; NEVER deleted — history
+#           is the value. Supersession via `superseded_by`.
+# Location: agents/memory/architecture-decisions/<hash>.yml
+#           OR agents/memory/architecture-decisions.yml (single-file)
+#
+# The YAML is an **index**, not the decision doc. Each entry points
+# to a long-form ADR (Markdown, Notion, Confluence — wherever your
+# team writes them) and captures the machine-readable metadata an
+# agent needs: paths constrained, alternatives rejected, trade-offs.
+
+version: 1
+
+entries:
+  - id: 0007-tenant-boundaries
+    status: active                       # active | deprecated | archived
+    confidence: high
+    source:
+      - docs/adr/0007-tenant-boundaries.md
+      - https://github.com/example/repo/pull/842
+    owner: platform-team
+    last_validated: 2026-04-10
+    review_after_days: 365
+
+    # --- decision body ---
+    title: Tenant boundaries enforced by global scopes + dedicated DB
+    date: 2025-11-18
+    context: >
+      Multi-tenant SaaS; legal requirement to isolate tenant data at
+      rest. Prior approach (column-based scoping) leaked in three
+      incidents over six months.
+    decision: >
+      Adopt per-tenant database connections with a `TenantScope`
+      global scope on every tenant-owned Eloquent model. Raw DB
+      access is forbidden outside migrations.
+    alternatives_rejected:
+      - id: column-scoping-only
+        reason: Column scoping proven unsafe under complex joins.
+      - id: schema-per-tenant
+        reason: Operational cost of N schemas exceeded team capacity.
+    trade_offs:
+      - Higher connection pool usage — mitigated by connection reuse.
+      - Slower local dev onboarding — mitigated by seeder changes.
+    paths:                               # globs this ADR constrains
+      - app/Models/Tenant*/**
+      - config/database.php
+      - database/migrations/*_tenant_*.php
+    superseded_by: ""                    # id of replacement ADR
+
+  - id: 0012-money-representation
+    status: active
+    confidence: high
+    source:
+      - docs/adr/0012-money-representation.md
+    owner: finance-team
+    last_validated: 2026-03-20
+    review_after_days: 730
+
+    title: Money represented as integer cents end-to-end
+    date: 2026-01-05
+    context: >
+      Float precision errors in payment reconciliation caused
+      two customer-facing discrepancies.
+    decision: >
+      All monetary values are integer cents (smallest currency unit).
+      Floats appear only inside the formatter boundary, never in
+      storage, transport, or business logic.
+    alternatives_rejected:
+      - id: decimal-type
+        reason: DB decimal support uneven across MariaDB / SQLite
+          test environments; integer is unambiguous.
+    trade_offs:
+      - Every new developer must learn the convention — mitigated by
+        a dedicated `Money` value object with a strict type.
+    paths:
+      - app/Models/Invoice*.php
+      - app/Models/Payment*.php
+      - app/Services/Billing/**
+    superseded_by: ""
+
+# --- How to add an entry ---
+#
+# 1. Write the ADR as a Markdown doc FIRST. This index is a pointer,
+#    not a replacement.
+# 2. Link the ADR doc under `source`. At least one link is mandatory.
+# 3. List `paths` as globs the agent can match. Be generous — it is
+#    better to trigger the ADR on too many paths than too few.
+# 4. Fill `alternatives_rejected` even when it feels obvious. The
+#    agent's main job here is to stop re-litigating decisions.
+# 5. On reversal: keep the old entry, set `status: deprecated`, add
+#    the new entry with `superseded_by` pointing back. History stays.

package/.agent-src/templates/agents/memory/domain-invariants.example.yml

@@ -0,0 +1,80 @@
+# domain-invariants.yml — non-negotiable rules the system must uphold
+#
+# Writer:   senior engineer / architect
+# Reader:   `developer-like-execution`, `php-coder`, `laravel` skills
+#           (consulted BEFORE writing code in matching paths)
+# Expiry:   reviewed at every major version bump
+# Location: agents/memory/domain-invariants/<hash>.yml (content-addressed)
+#           OR agents/memory/domain-invariants.yml (single-file mode)
+#
+# See guidelines/agent-infra/role-contracts.md and
+# road-to-engineering-memory.md for the full contract.
+
+version: 1
+
+# Each entry is an invariant the code MUST uphold. Agents read them
+# before editing matched paths and call them out in their output.
+entries:
+  - id: tenant-isolation
+    status: active                       # active | deprecated | archived
+    confidence: high                     # low | medium | high
+    source:                              # at least one reference
+      - https://github.com/example/repo/pull/1234
+      - adr://0007-tenant-boundaries
+    owner: platform-team
+    last_validated: 2026-04-01
+    review_after_days: 365
+
+    # --- invariant body ---
+    rule: >
+      Tenant IDs must never cross-reference. A query in tenant A
+      must never return a row belonging to tenant B, regardless of
+      join path.
+    paths:                               # glob patterns the rule applies to
+      - app/Models/**
+      - app/Http/Controllers/Tenant*/**
+      - app/Services/Tenant*/**
+    enforcement:                         # how violation is detected
+      - test: tests/Feature/TenantIsolationTest.php
+      - policy: app/Policies/TenantPolicy.php
+    guardrail: >
+      Every Eloquent query on tenant-scoped models must go through
+      the `TenantScope` global scope. Raw DB::query() calls touching
+      tenant tables are forbidden outside migrations.
+
+  - id: money-as-integer-cents
+    status: active
+    confidence: high
+    source:
+      - adr://0012-money-representation
+    owner: finance-team
+    last_validated: 2026-03-20
+    review_after_days: 730
+
+    rule: >
+      All monetary amounts are stored and passed around as integer
+      cents (or the smallest unit of the currency). Float / decimal
+      representations are forbidden at every layer below the
+      formatter.
+    paths:
+      - app/Models/Invoice*.php
+      - app/Models/Payment*.php
+      - app/Services/Billing/**
+    enforcement:
+      - static_analysis: phpstan level 9 on Billing namespace
+      - test: tests/Unit/MoneyTest.php
+    guardrail: >
+      Use the `Money` value object for all monetary values. Never
+      cast a float to a model attribute. Formatter is the ONLY
+      boundary where floats appear, and only for display.
+
+# --- How to add an entry ---
+#
+# 1. Pick a stable `id` (kebab-case, unique within this file).
+# 2. Reference at least one source (PR, ADR, spec link).
+# 3. Pick a confidence honestly — if you are writing this from a
+#    hunch rather than evidence, start with `medium`.
+# 4. List concrete `paths` — globs the agent can match against.
+# 5. Describe the `guardrail` as a **mechanism**, not a wish. "Use
+#    X", "validate with Y" — not "be careful with Z".
+# 6. Run `task check-memory` before committing.

package/.agent-src/templates/agents/memory/historical-patterns.example.yml

@@ -0,0 +1,82 @@
+# historical-patterns.yml — recurring bug shapes and near-misses tied
+# to specific files or modules
+#
+# Writer:   engineers after incidents, code reviewers, bug-fix command
+# Reader:   `judge-bug-hunter`, `review-routing`, `blast-radius-analyzer`
+#           (consulted BEFORE editing matched paths)
+# Expiry:   reviewed after each incident against the matched module
+# Location: agents/memory/historical-patterns/<hash>.yml (content-addressed)
+#           OR agents/memory/historical-patterns.yml (single-file mode)
+#
+# See guidelines/agent-infra/engineering-memory-data-format.md for the
+# full schema.
+
+version: 1
+
+entries:
+  - id: checkout-null-currency
+    status: active
+    confidence: high
+    source:
+      - https://github.com/example/repo/issues/8421
+      - https://sentry.example.com/events/abc123
+    owner: billing-team
+    last_validated: 2026-03-15
+    review_after_days: 180
+
+    # --- historical pattern body ---
+    symptom: >
+      `TypeError: Cannot read property 'code' of null` when a guest
+      checkout hits the price formatter without a resolved currency.
+    paths:
+      - app/Services/Billing/PriceFormatter.php
+      - app/Http/Controllers/Billing/Checkout.php
+    trigger_conditions:
+      - "Anonymous user (no session currency)"
+      - "Product priced only in a non-default currency"
+    guardrail: >
+      Any code reading `$order->currency` must resolve via
+      `CurrencyResolver::forOrder($order)`, which falls back to the
+      tenant default. Never dereference `$order->currency->code`
+      directly.
+    regression_test: tests/Feature/Billing/GuestCheckoutTest.php
+    first_seen: 2025-11-03
+    last_seen: 2026-02-18
+    recurrence_count: 4
+
+  - id: queue-retry-log-noise
+    status: active
+    confidence: medium
+    source:
+      - https://github.com/example/repo/pull/9010
+    owner: platform-team
+    last_validated: 2026-04-10
+    review_after_days: 90
+
+    symptom: >
+      Retryable jobs double-log the same exception on every attempt,
+      inflating the Sentry error budget and masking real regressions.
+    paths:
+      - app/Jobs/**
+    trigger_conditions:
+      - "Job implements ShouldQueue and throws a typed exception"
+      - "retries() > 1 and no unique_for key set"
+    guardrail: >
+      Use `SilentRetry` trait or explicitly set `$this->dontReport = true`
+      on the first N-1 retries. Final-attempt failure is the only one
+      that calls `report()`.
+    regression_test: tests/Feature/Queue/RetryReportingTest.php
+    first_seen: 2026-01-20
+    last_seen: 2026-04-05
+    recurrence_count: 7
+
+# --- How to add an entry ---
+#
+# 1. Pick a stable `id` that names the pattern, not the fix.
+# 2. Cite the first bug report and the most recent recurrence.
+# 3. `trigger_conditions` are the minimal inputs that reproduce.
+# 4. `guardrail` is a mechanism, not a wish. "Go through X" — not
+#    "be careful with Y".
+# 5. Always link a `regression_test` — the pattern earns its entry
+#    only once a test exists that would have caught it.
+# 6. Run `task check-memory` before committing.

package/.agent-src/templates/agents/memory/incident-learnings.example.yml

@@ -0,0 +1,113 @@
+# incident-learnings.yml — pattern + consequence + guardrail
+#
+# Writer:   incident commander after resolution
+# Reader:   `Incident` role mode, `bug-investigate`, `bug-analyzer`
+# Expiry:   archived when the underlying class is structurally
+#           eliminated (guardrail landed AND verified in prod)
+# Location: agents/memory/incident-learnings/<hash>.yml
+#           OR agents/memory/incident-learnings.yml (single-file)
+#
+# REDACTION IS MANDATORY — see road-to-engineering-memory.md.
+# Every entry is a PATTERN + CONSEQUENCE + GUARDRAIL.
+# Every entry that contains a customer name, internal URL, PII, or
+# secret is rejected by `scripts/check_memory.py`. No opt-out.
+#
+# BAD entry (auto-rejected):
+#   "On 2026-03-14 customer ACME hit a rate limit and Redis died."
+# GOOD entry:
+#   "When rate limit X is crossed on path Y, queue worker Z starves
+#   the primary DB pool. Guardrail: circuit-break at 80% of X."
+
+version: 1
+
+entries:
+  - id: queue-worker-db-pool-starvation
+    status: active                       # active | deprecated | archived
+    confidence: high
+    source:
+      - https://github.com/example/repo/pull/2104    # guardrail PR
+      - https://github.com/example/repo/issues/2098  # incident ticket
+    owner: platform-team
+    last_validated: 2026-04-15
+    review_after_days: 180
+    severity: high                       # low | medium | high | critical
+
+    # --- pattern ---
+    pattern: >
+      When sustained throughput on queue `invoices` exceeds the
+      configured rate limit on path `/api/invoices/*`, the queue
+      worker retries saturate the primary DB connection pool and
+      starve synchronous requests.
+    trigger_conditions:
+      - sustained_rps_gt: 150
+      - path_prefix: /api/invoices/
+      - worker_queue: invoices
+
+    # --- consequence (no customer specifics) ---
+    consequence: >
+      Synchronous requests on unrelated endpoints fail with 500 and
+      connection-timeout errors. User-facing latency spikes to ≥ 3s
+      p99 within 60 seconds.
+
+    # --- guardrail (mechanism, not wish) ---
+    guardrail: >
+      Circuit-break the queue worker at 80% of the rate limit.
+      Emit a sustained-latency alert on the `invoices` queue.
+      Connection pool sized to (worker_count × 2 + sync_workers).
+    enforcement:
+      - test: tests/Feature/QueueBackpressureTest.php
+      - alert: grafana/alerts/invoices-queue-latency.yml
+      - config: config/horizon.php — balance=simple, max_processes=...
+
+    paths:
+      - app/Jobs/ProcessInvoice.php
+      - app/Http/Controllers/Api/InvoiceController.php
+      - config/horizon.php
+
+  - id: webhook-signature-verify-timing
+    status: active
+    confidence: medium
+    source:
+      - https://github.com/example/repo/pull/1876
+    owner: integrations-team
+    last_validated: 2026-02-28
+    review_after_days: 90
+    severity: medium
+
+    pattern: >
+      Webhook signature verification that concatenates body parts
+      before hashing is vulnerable to timing-based side channels
+      on high-volume endpoints when response latency leaks.
+    trigger_conditions:
+      - endpoint_type: webhook
+      - verify_pattern: string-concat-then-hash
+
+    consequence: >
+      Attackers with sustained probe access can infer signature
+      prefix bytes from response-time deltas at the millisecond
+      granularity over minutes to hours.
+
+    guardrail: >
+      Always use `hash_equals()` for signature comparison. Compute
+      the full HMAC on the raw request body, never on a
+      concatenated view. Pad response time to the worst-case branch.
+    enforcement:
+      - test: tests/Security/WebhookVerifyTest.php
+      - static_analysis: phpstan rule forbids `===` on webhook sigs
+    paths:
+      - app/Http/Middleware/VerifyWebhookSignature.php
+      - app/Services/Webhook/**
+
+# --- How to add an entry ---
+#
+# 1. Wait until the incident is RESOLVED. Draft entries from open
+#    incidents leak half-baked hypotheses.
+# 2. Distil to pattern + consequence + guardrail. If the entry reads
+#    like a post-mortem summary, it is too specific.
+# 3. Scrub — no customer names, no ticket IDs from the incident, no
+#    internal URLs, no timestamps with identifying precision. The
+#    check rejects these; do not fight it.
+# 4. Link the guardrail PR as a source — an entry without a
+#    guardrail is not a learning, it is a confession.
+# 5. Set `review_after_days` aggressively (90–180). Entries that
+#    outlive their guardrail are more dangerous than missing.

package/.agent-src/templates/agents/memory/ownership.example.yml

@@ -0,0 +1,75 @@
+# ownership.yml — who owns what in the codebase
+#
+# Writer:   tech lead / team maintainer
+# Reader:   `review-routing`, `requesting-code-review`, blast-radius
+#           analysis (consulted to pick reviewers and CODEOWNERS hints)
+# Expiry:   reviewed quarterly or after team reorganizations
+# Location: agents/memory/ownership/<hash>.yml (content-addressed)
+#           OR agents/memory/ownership.yml (single-file mode)
+#
+# See guidelines/agent-infra/review-routing-data-format.md for the
+# sibling review-router schema; this file is the authoritative source
+# for WHO, not HOW.
+
+version: 1
+
+entries:
+  - id: billing-module
+    status: active
+    confidence: high
+    source:
+      - https://github.com/example/repo/blob/main/CODEOWNERS
+      - adr://0003-team-boundaries
+    owner: billing-team
+    last_validated: 2026-04-01
+    review_after_days: 180
+
+    # --- ownership body ---
+    paths:
+      - app/Services/Billing/**
+      - app/Http/Controllers/Billing/**
+      - app/Models/{Invoice,Payment,Subscription}*.php
+    primary_reviewer: "@alice-lead"
+    secondary_reviewers:
+      - "@bob-senior"
+      - "@carol-eng"
+    escalation: "@head-of-platform"
+    slack_channel: "#team-billing"
+    rotation_policy: >
+      Any PR touching `app/Services/Billing/**` must have at least one
+      review from `@alice-lead` or `@bob-senior`. Vacation coverage
+      documented in the team runbook.
+
+  - id: infra-terraform
+    status: active
+    confidence: high
+    source:
+      - https://github.com/example/repo/blob/main/CODEOWNERS
+    owner: platform-team
+    last_validated: 2026-03-10
+    review_after_days: 365
+
+    paths:
+      - terraform/**
+      - .github/workflows/deploy*.yml
+      - docker-compose*.yml
+    primary_reviewer: "@dan-infra"
+    secondary_reviewers:
+      - "@erin-sre"
+    escalation: "@head-of-platform"
+    slack_channel: "#team-platform"
+    rotation_policy: >
+      Infra changes require two platform-team reviews in business
+      hours. After-hours hotfixes follow the break-glass policy in
+      `agents/contexts/deployment-order.md`.
+
+# --- How to add an entry ---
+#
+# 1. `id` is the module/domain name, not a person's handle.
+# 2. `paths` are globs the agent uses to pick reviewers for an
+#    incoming diff. Keep them tight — avoid `app/**` catch-alls.
+# 3. `primary_reviewer` is singular; `secondary_reviewers` is the
+#    fallback pool.
+# 4. `escalation` routes urgent cross-cutting issues; the agent
+#    surfaces it when a PR sits idle past the team's SLA.
+# 5. Run `task check-memory` before committing.

package/.agent-src/templates/agents/memory/product-rules.example.yml

@@ -0,0 +1,87 @@
+# product-rules.yml — product-side invariants code must honour
+#
+# Writer:   PO or tech lead after product decision
+# Reader:   `PO` role mode, `validate-feature-fit`, `laravel-validation`
+#           (consulted BEFORE proposing feature changes)
+# Expiry:   version-stamped; old versions archived on rule change
+# Location: agents/memory/product-rules/<hash>.yml
+#           OR agents/memory/product-rules.yml (single-file)
+#
+# Bridges PO intent and developer execution. An entry here exists
+# because the agent MUST enforce this rule in validation, gating,
+# or feature-fit checks — it is not a feature wishlist.
+#
+# REDACTION IS MANDATORY — see road-to-engineering-memory.md.
+# No customer names, no pricing-with-customer-discount, no PII.
+
+version: 1
+
+entries:
+  - id: free-plan-no-export
+    status: active                       # active | deprecated | archived
+    confidence: high
+    source:
+      - https://example.com/product/pricing-tiers   # public doc
+      - https://github.com/example/repo/pull/1503   # enforcement PR
+    owner: product-team
+    last_validated: 2026-04-05
+    review_after_days: 180
+    version: "2.0"
+
+    # --- rule body ---
+    rule: >
+      Users on the `free` plan cannot trigger data exports (CSV,
+      JSON, XLSX) exceeding 100 rows. Exports above the threshold
+      are reserved for `pro` and `enterprise` plans.
+    applies_to:
+      endpoints:
+        - POST /api/exports
+        - GET  /api/exports/{id}/download
+      plan_tiers: [free]
+    enforcement:
+      - policy: app/Policies/ExportPolicy.php
+      - feature_gate: "plan_tiers in FeatureGate service"
+      - test: tests/Feature/FreePlanExportLimitTest.php
+    error_contract:
+      http_status: 403
+      error_code: EXPORT_PLAN_LIMIT
+      user_message: Upgrade to export more than 100 rows.
+
+  - id: weekend-sla-tier-b
+    status: active
+    confidence: medium
+    source:
+      - https://example.com/legal/sla.pdf           # public SLA doc
+      - adr://0019-sla-tier-mapping
+    owner: customer-success-team
+    last_validated: 2026-03-12
+    review_after_days: 90
+    version: "1.3"
+
+    rule: >
+      Support tickets opened between 18:00 Friday and 08:00 Monday
+      in the customer's timezone fall under SLA tier B response
+      time (4h first response) instead of tier A (1h).
+    applies_to:
+      systems: [support-queue, sla-calculator]
+      timezone_scope: customer-local
+    enforcement:
+      - service: app/Services/SLA/ResponseTimeCalculator.php
+      - test: tests/Unit/SlaWeekendTest.php
+      - config: config/sla.yml
+    error_contract: {}                   # no user-facing error; SLA
+                                         # is applied silently
+
+# --- How to add an entry ---
+#
+# 1. A product decision was made AND signed off. Pending proposals
+#    do not belong here.
+# 2. The rule is enforceable — every entry must name at least one
+#    enforcement point (policy, feature gate, test, service).
+# 3. Bump `version` whenever the rule semantics change. Old
+#    versions get `status: archived` and stay for audit.
+# 4. Link both the PRODUCT-side doc (pricing page, SLA PDF, landing
+#    page) AND the code-side enforcement PR.
+# 5. Keep `error_contract` precise — agents generate error messages
+#    from it. An empty contract (`{}`) means "no user error", not
+#    "to be decided later".