@ryuenn3123/agentic-senior-core 3.0.49 → 4.0.0

package/.agent-context/rules/git-workflow.md

@@ -1,200 +1,84 @@
-# Git Workflow — Clean History, Atomic Commits
-
-> Your git log is a changelog. If it reads like gibberish, your team is lost.
-
-## Commit Message Format: Conventional Commits (Enforced)
-
-```
-<type>(<scope>): <description>
-
-[optional body — explain WHY, not WHAT]
-[optional footer — Breaking changes, issue references]
-```
-
-### Types (Strict Set)
-| Type | When | Example |
-|------|------|---------|
-| `feat` | New feature | `feat(auth): add JWT refresh token rotation` |
-| `fix` | Bug fix | `fix(payment): handle race condition in checkout` |
-| `refactor` | Code restructuring (no behavior change) | `refactor(user): extract validation to separate service` |
-| `docs` | Documentation only | `docs(api): add OpenAPI schema for /orders endpoint` |
-| `test` | Adding/fixing tests | `test(cart): add edge case for empty cart discount` |
-| `chore` | Build, CI, config, dependencies | `chore(deps): upgrade prisma to 5.x` |
-| `perf` | Performance improvement | `perf(search): add index on users.email column` |
-| `style` | Formatting, semicolons (no logic change) | `style: apply prettier formatting` |
-| `ci` | CI/CD changes | `ci: add Node 20 to test matrix` |
-
-### Rules
-1. **Type is mandatory.** No commits without a type prefix.
-2. **Scope is required for module or feature changes.** Use the module/feature name.
-3. **Description is imperative mood.** "add", not "added" or "adds".
-4. **Max 72 characters** for the subject line.
-5. **Body explains WHY,** not what. The diff shows what.
-
-### ❌ BANNED Commit Messages
-```
-fix bug
-updates
-WIP
-asdf
-misc changes
-working now
-final fix
-fix fix fix
-```
-
 ---
-
-## Branching Model
-
-### Main Branches
-| Branch | Purpose | Merge Strategy |
-|--------|---------|---------------|
-| `main` | Production-ready code | Merge commit or squash |
-| `develop` | Integration branch (if using GitFlow) | Merge commit |
-
-### Feature Branches
-```
-Pattern: <type>/<ticket-id>-<short-description>
-
-Examples:
-  feat/AUTH-123-jwt-refresh
-  fix/PAY-456-checkout-race-condition
-  refactor/USER-789-extract-validation
-  chore/INFRA-101-upgrade-node-20
-```
-
-### Rules
-1. Branch from `main` (or `develop` if using GitFlow)
-2. Keep branches short-lived (max 2-3 days)
-3. Rebase on `main` before creating PR — don't merge main into your branch
-4. Delete branch after merge
-
+id_prefix: GIT
+domain: git-workflow
+priority: medium
+scope: governance
+applies_to:
+  - backend
+  - frontend
+  - fullstack
+keywords:
+  - git-workflow
+  - git
+  - commit
+  - branch
+  - pull-request
+  - gitignore
 ---
 
-## Pull Request Standards
-
-### PR Size
-| Size | Lines Changed | Verdict |
-|------|--------------|---------|
-| Small | 1-100 | ✅ Ideal — easy to review |
-| Medium | 100-300 | ⚠️ Acceptable — split if possible |
-| Large | 300-500 | 🔶 Needs justification |
-| Massive | 500+ | ❌ MUST be split into smaller PRs |
-
-**Rule:** If a PR touches more than 5 files across different modules, it's doing too much. Split it.
-
-### PR Description Template
-```markdown
-## What
-Brief description of what this PR does.
-
-## Why
-Why this change is needed. Link to issue/ticket.
-
-## How
-High-level approach. Mention any non-obvious design decisions.
-
-## Testing
-- [ ] Unit tests added/updated
-- [ ] Integration tests (if applicable)
-- [ ] Manual testing steps
-
-## Screenshots (if UI change)
-Before | After
-```
-
-### PR Review Rules
-1. Every PR needs at least 1 approval
-2. Author resolves all comments before merge
-3. CI must pass (lint, test, build)
-4. No `// TODO` without a linked issue
-5. No `console.log` debugging statements in production code
-
----
-
-## Commit Atomicity
-
-### Rule: Each Commit Must Be a Complete, Working Unit
-
-```
-❌ BANNED sequence:
-1. feat(user): add user model          ← compiles? maybe
-2. fix: fix import                     ← fixing previous commit
-3. feat(user): add user service        ← compiles? probably
-4. fix: fix typo                       ← fixing previous commit
-5. feat(user): add user controller     ← finally works together
-
-✅ REQUIRED:
-1. feat(user): add user registration module
-   → Model, Service, Controller, Tests — all in one complete, working commit
-   → Or split into logical chunks that each compile and pass tests independently
-```
-
-**Rule:** Every commit on `main` should compile, pass lint, and pass tests. Use interactive rebase (`git rebase -i`) to squash fix-up commits before merging.
-
----
-
-## .gitignore Standards
-
-### MUST Ignore
-```
-# Dependencies
-node_modules/
-vendor/
-venv/
-__pycache__/
-.gradle/
-target/
-
-# Environment
-.env
-.env.local
-.env.*.local
-
-# IDE
-.idea/
-.vscode/settings.json
-*.swp
-*.swo
-.DS_Store
-Thumbs.db
-
-# Build output
-dist/
-build/
-out/
-*.min.js
-*.min.css
-
-# Logs
-*.log
-npm-debug.log*
-
-# OS
-.DS_Store
-Thumbs.db
-```
-
-### MUST Commit
-```
-.env.example           # Template with placeholder values
-.editorconfig          # Consistent formatting across IDEs
-.prettierrc            # Formatter config
-.eslintrc.*            # Linter config
-tsconfig.json          # TypeScript config
-docker-compose.yml     # Dev environment
-Makefile / Taskfile    # Standard commands
-```
-
----
-
-## The Git Health Check
-
-Before pushing:
-- [ ] All commits follow Conventional Commits format
-- [ ] No fixup commits (squash them)
-- [ ] Branch is rebased on latest main
-- [ ] CI passes locally (lint, test, build)
-- [ ] No secrets in any commit (check with `git log -p | grep -i "password\|secret\|key"`)
-- [ ] No merge commits in feature branch (rebase instead)
+# Git Workflow - Clean History, Atomic Commits
+
+Your git log is a changelog. If it reads like gibberish, your team is lost.
+
+## GIT-001: Commit Message Format (Conventional Commits Enforced)
+
+1. Use Conventional Commits for every commit: `<type>(<scope>): <description>`.
+2. Use the optional body to explain WHY, not WHAT.
+3. Use the optional footer for breaking changes and issue references.
+4. Use only the strict types set: `feat` for new feature, `fix` for bug fix, `refactor` for code restructuring with no behavior change, `docs` for documentation only, `test` for adding or fixing tests, `chore` for build, CI, config, or dependencies, `perf` for performance improvement, `style` for formatting and semicolons with no logic change, and `ci` for CI/CD changes.
+5. Type is mandatory. No commits without a type prefix.
+6. Scope is required for module or feature changes. Use the module or feature name.
+7. Description must use imperative mood: "add", not "added" or "adds".
+8. Keep the subject line at max 72 characters.
+9. Body explains WHY; the diff shows what.
+10. Reject banned commit messages: `fix bug`, `updates`, `WIP`, `asdf`, `misc changes`, `working now`, `final fix`, and `fix fix fix`.
+
+## GIT-002: Branching Model and Merge Strategy
+
+1. Keep `main` production-ready; its purpose is production-ready code, and its merge strategy is merge commit or squash according to project policy.
+2. Use `develop` as an integration branch only when the project uses GitFlow; its purpose is integration.
+3. Name feature branches with the pattern `<type>/<ticket-id>-<short-description>`.
+4. Example branch names include `feat/AUTH-123-jwt-refresh`, `fix/PAY-456-checkout-race-condition`, `refactor/USER-789-extract-validation`, and `chore/INFRA-101-upgrade-node-20`.
+5. Branch from `main`, or from `develop` when using GitFlow.
+6. Keep branches short-lived, max 2-3 days.
+7. Rebase on `main` before creating a PR; do not merge main into your branch.
+8. Delete the branch after merge.
+
+## GIT-003: Pull Request Standards
+
+1. Keep PR size reviewable: small is 1-100 lines changed and ideal because it is easy to review; medium is 100-300 and acceptable, split if possible; large is 300-500 and needs justification; massive is 500+ and must be split into smaller PRs. Treat these thresholds as the PR size verdict.
+2. Split a PR when it touches more than 5 files across different modules; it is doing too much.
+3. PR descriptions must follow the PR Description Template: What, Why, How, Testing, and Screenshots when the change affects UI.
+4. What gives a brief description of what the PR does.
+5. Why explains why the change is needed and links to the issue or ticket.
+6. How gives the high-level approach and mentions non-obvious design decisions.
+7. Testing lists unit tests, integration tests when applicable, and manual testing steps.
+8. Every PR needs at least 1 approval, author resolves all comments before merge, CI must pass lint, test, and build, no `// TODO` appears without a linked issue, and production code contains no `console.log` debugging statements.
+
+## GIT-004: Commit Atomicity
+
+1. Each commit must be a complete, working unit.
+2. Reject banned sequences where a feature commit is followed by fix imports, fix typos, or other fix-up commits needed to make the previous commit work.
+3. Prefer one complete working commit for a cohesive module, such as model, service, controller, and tests for user registration.
+4. Split into logical chunks only when each chunk compiles and passes tests independently.
+5. Every commit on `main` should compile, pass lint, and pass tests.
+6. Use interactive rebase (`git rebase -i`) to squash fix-up commits before merging.
+
+## GIT-005: .gitignore Standards
+
+1. Ignore dependency and cache directories: `node_modules/`, `vendor/`, `venv/`, `__pycache__/`, `.gradle/`, and `target/`.
+2. Ignore environment files: `.env`, `.env.local`, and `.env.*.local`.
+3. Ignore IDE and OS artifacts: `.idea/`, `.vscode/settings.json`, `*.swp`, `*.swo`, `.DS_Store`, and `Thumbs.db`.
+4. Ignore build output: `dist/`, `build/`, `out/`, `*.min.js`, and `*.min.css`.
+5. Ignore logs: `*.log` and `npm-debug.log*`.
+6. Commit configuration templates and formatter or linter config: `.env.example`, `.editorconfig`, `.prettierrc`, `.eslintrc.*`, and `tsconfig.json`.
+7. Commit standard development commands and environments when they are part of the project contract: `docker-compose.yml`, `Makefile`, or `Taskfile`.
+
+## GIT-006: Git Health Check
+
+1. Before pushing, verify all commits follow Conventional Commits format.
+2. Before pushing, verify there are no fixup commits; squash them.
+3. Before pushing, verify the branch is rebased on latest main.
+4. Before pushing, verify CI passes locally: lint, test, and build.
+5. Before pushing, verify there are no secrets in any commit; check with `git log -p | grep -i "password\|secret\|key"`.
+6. Before pushing, verify there are no merge commits in the feature branch; rebase instead.

package/.agent-context/rules/microservices.md

@@ -1,43 +1,44 @@
-# Service Boundary Rule
-
-Do not ask for or force "monolith vs microservices" as an init default. Do not start with microservices by fashion, fear, or habit. The agent must infer the right topology from the user brief, repo evidence, team/runtime constraints, and live official docs when technology choices matter.
-
-## Monolith Boundary
-
-Use a single deployable system when:
-
-- one team or one delivery stream owns most changes
-- feature boundaries can stay clear inside one repo/process
-- synchronous data consistency is more valuable than distributed autonomy
-- observability, CI/CD, and operational maturity are still forming
-
-Hard rules:
-
-- Keep feature/domain boundaries explicit.
-- Do not let one giant shared module become the real architecture.
-- Keep contracts clear between modules.
-- Refactor toward cleaner seams before extracting services.
+---
+id_prefix: SVC
+domain: microservices
+priority: medium
+scope: backend
+applies_to:
+  - backend
+  - fullstack
+keywords:
+  - microservices
+  - svc
+  - monolith
+  - contracts
+---
 
-## Service Split Boundary
-
-Split a service only when current evidence justifies the operational cost.
-
-Valid split signals:
-
-- independent deploy cadence is already painful
-- one domain has materially different scale, latency, security, or compliance needs
-- ownership boundaries are stable and repeated coupling is causing delivery risk
-- failure isolation is a real product or business requirement
-- the service contract and data ownership can be documented before extraction
-
-Hard rules:
-
-- Each service owns its data boundary.
-- Public service contracts must be documented before implementation or extraction.
-- Cross-service calls need timeout, retry, idempotency, observability, and recovery behavior.
-- Independent services must not use shared tables as their integration contract; communicate through documented APIs, events, or async workflows owned by the source domain.
-- Avoid synchronous call chains that turn services into a distributed monolith.
-- Critical cross-service mutations should prefer local transactions plus outbox, saga, choreography, orchestration, or compensating actions over two-phase commit by default.
-- Prefer incremental extraction over rewrites.
+# Service Boundary Rule
 
-If the evidence is unclear, document the uncertainty and keep the topology agent-recommended instead of pretending an offline default is correct.
+The agent must infer the right topology from the user brief, repo evidence, team/runtime constraints, and live official docs when technology choices matter.
+
+## SVC-001: Monolith Boundary
+
+1. Do not ask for or force "monolith vs microservices" as an init default.
+2. Do not start with microservices by fashion, fear, or habit.
+3. Use a single deployable system when one team or one delivery stream owns most changes.
+4. Use a single deployable system when feature boundaries can stay clear inside one repo/process.
+5. Use a single deployable system when synchronous data consistency is more valuable than distributed autonomy.
+6. Use a single deployable system when observability, CI/CD, and operational maturity are still forming.
+7. Keep feature/domain boundaries explicit.
+8. Do not let one giant shared module become the real architecture.
+9. Keep contracts clear between modules.
+10. Refactor toward cleaner seams before extracting services.
+
+## SVC-002: Service Split Boundary and Hard Rules
+
+1. Split a service only when current evidence justifies the operational cost.
+2. Valid split signals include independent deploy cadence that is already painful; materially different scale, latency, security, or compliance needs in one domain; stable ownership boundaries plus repeated coupling causing delivery risk; failure isolation as a real product or business requirement; and service contract plus data ownership documentation before extraction.
+3. Hard rules: each service owns its data boundary.
+4. Public service contracts must be documented before implementation or extraction.
+5. Cross-service calls need timeout, retry, idempotency, observability, and recovery behavior.
+6. Independent services must not use shared tables as their integration contract; communicate through documented APIs, events, or async workflows owned by the source domain.
+7. Avoid synchronous call chains that turn services into a distributed monolith.
+8. Critical cross-service mutations should prefer local transactions plus outbox, saga, choreography, orchestration, or compensating actions over two-phase commit by default.
+9. Prefer incremental extraction over rewrites.
+10. If the evidence is unclear, document the uncertainty and keep the topology agent-recommended instead of pretending an offline default is correct.

package/.agent-context/rules/naming-conv.md

@@ -1,11 +1,32 @@
+---
+id_prefix: NAME
+domain: naming-conv
+priority: medium
+scope: all-tasks
+applies_to:
+  - backend
+  - frontend
+  - fullstack
+keywords:
+  - naming-conv
+  - name
+  - naming
+  - comments
+  - intent
+  - conventions
+---
+
 # Naming Boundary
 
 Use the target language and framework conventions. Do not invent a naming style from this repo.
 
-Reject only these common LLM bad habits:
-- vague names that hide meaning, such as `data`, `result`, `item`, `thing`, `temp`, `handle`, or `process` when a precise domain name exists
-- names that require reading the implementation to understand the value
-- mixed file or directory naming styles inside the same feature without a framework reason
-- booleans, units, and side-effect functions whose names hide what they represent or change
+## NAME-001: Naming and Comment Rules
 
-Prefer names that explain domain intent, user action, state, and boundary responsibility.
+1. Prefer names that explain domain intent, user action, state, and boundary responsibility.
+2. Reject these common LLM bad habits: vague names that hide meaning, such as `data`, `result`, `item`, `thing`, `temp`, `handle`, or `process` when a precise domain name exists.
+3. Reject names that require reading the implementation to understand the value.
+4. Keep file and directory naming styles consistent inside the same feature unless a framework reason requires mixed styles.
+5. Reject booleans, units, and side-effect functions whose names hide what they represent or change.
+6. Inline comments must explain why, not what.
+7. Put a one-line rationale near non-obvious choices that deserve explanation, such as retry strategy, index column order, denormalized field, intentional swallow with named recovery, or magic constant tied to an external system.
+8. Treat comments that paraphrase the code as noise.

package/.agent-context/rules/performance.md

@@ -1,14 +1,36 @@
-# Performance Boundary
+---
+id_prefix: PERF
+domain: performance
+priority: medium
+scope: all-tasks
+applies_to:
+  - backend
+  - frontend
+  - fullstack
+keywords:
+  - performance
+  - perf
+  - caching
+  - bottleneck
+  - runtime
+  - payload
+---
 
-Do not over-optimize by habit. Do reject obvious scale and runtime failures.
+# Performance Boundary
 
-Performance is a decision input, not a blanket veto against modern libraries, motion, richer UI, or maintained tooling. Compare the real cost of the dependency or implementation against the cost of custom code, lost accessibility, weaker UX, duplicated maintenance, and slower delivery.
+Performance is a decision input, not a blanket veto against modern libraries, motion, richer UI, or maintained tooling.
 
-Hard rejections:
-- repeated network, database, filesystem, or model calls inside loops without batching, limits, or caching rationale
-- unbounded reads, renders, exports, or searches when the data can grow
-- shipping large client/runtime payloads without a reason, split point, or loading strategy
-- synchronous blocking work in request, UI, worker, or async paths where it can stall the product
-- caches without invalidation, expiry, ownership, and staleness trade-offs
+## PERF-001: Hard Performance Rejections and Caching
 
-When performance matters, measure the real bottleneck, change the smallest useful thing, and verify the result. Do not downshift product quality, UI ambition, or library fit from performance fear alone; name the concrete budget, bottleneck, device limit, or runtime evidence.
+1. Do not over-optimize by habit.
+2. Reject obvious scale and runtime failures.
+3. Compare the real cost of the dependency or implementation against the cost of custom code, lost accessibility, weaker UX, duplicated maintenance, and slower delivery.
+4. Reject repeated network, database, filesystem, or model calls inside loops without batching, limits, or caching rationale.
+5. Reject unbounded reads, renders, exports, or searches when the data can grow.
+6. Reject shipping large client/runtime payloads without a reason, split point, or loading strategy.
+7. Reject synchronous blocking work in request, UI, worker, or async paths where it can stall the product.
+8. Reject caches without invalidation, expiry, ownership, and staleness trade-offs.
+9. When performance matters, measure the real bottleneck, change the smallest useful thing, and verify the result.
+10. Do not downshift product quality, UI ambition, or library fit from performance fear alone; name the concrete budget, bottleneck, device limit, or runtime evidence.
+11. Treat caching as a tier decision before a technology decision: prefer browser, CDN, or HTTP cache layers when data is shared and public; prefer in-process caches for hot per-instance data; reach for distributed caches such as Redis or Memcached only when shared mutable state across instances is the actual requirement.
+12. Record cache-aside, write-through, or write-behind shape, invalidation strategy, and stampede prevention such as request coalescing or stale-while-revalidate when the cache fronts an expensive backend.

package/.agent-context/rules/realtime.md

@@ -1,14 +1,31 @@
+---
+id_prefix: RT
+domain: realtime
+priority: medium
+scope: backend
+applies_to:
+  - backend
+  - fullstack
+keywords:
+  - realtime
+  - rt
+  - transport
+  - streaming
+  - connection
+  - delivery
+---
+
 # Realtime Boundary
 
 Use realtime only when the user experience needs live state, collaboration, streaming progress, notifications, or low-latency feedback. Do not add sockets by habit.
 
-Hard rules:
-- choose the transport from product needs and current official docs: polling, server-sent events, WebSockets, WebRTC, managed realtime, or queue-backed push
-- authenticate every connection or subscription at a trusted boundary
-- validate every inbound message and keep message contracts typed
-- keep business logic out of transport callbacks
-- define reconnect, heartbeat, backpressure, rate-limit, and abuse behavior
-- plan horizontal scaling before relying on in-memory connection state
-- document ordering, delivery guarantees, offline behavior, and failure recovery
+## RT-001: Hard Realtime Transport and Delivery Rules
 
-If realtime infrastructure is unresolved, the LLM must recommend the smallest current project-fit option instead of assuming WebSockets.
+1. Choose the transport from product needs and current official docs: polling, server-sent events, WebSockets, WebRTC, managed realtime, or queue-backed push.
+2. Authenticate every connection or subscription at a trusted boundary.
+3. Validate every inbound message and keep message contracts typed.
+4. Keep business logic out of transport callbacks.
+5. Define reconnect, heartbeat, backpressure, rate-limit, and abuse behavior.
+6. Plan horizontal scaling before relying on in-memory connection state.
+7. Document ordering, delivery guarantees, offline behavior, and failure recovery.
+8. If realtime infrastructure is unresolved, recommend the smallest current project-fit option instead of assuming WebSockets.

package/.agent-context/rules/security.md

@@ -1,25 +1,45 @@
+---
+id_prefix: SEC
+domain: security
+priority: critical
+scope: all-tasks
+applies_to:
+  - backend
+  - frontend
+  - fullstack
+keywords:
+  - security
+  - sec
+  - boundary
+  - hard
+  - rules
+  - zero-trust
+---
+
 # Security Boundary
 
 Use the security model and libraries already present in the project. If security tooling is unresolved, the LLM must recommend current, maintained options from official docs and OWASP-aligned guidance before implementation.
 
-Hard rules:
-- validate and normalize all data crossing a trust boundary
-- never interpolate untrusted input into queries, shell commands, file paths, templates, logs, or HTML
-- never commit secrets, tokens, credentials, private keys, or production identifiers
-- never invent custom crypto, session, token, or password handling when maintained standards exist
-- enforce authorization at the server or trusted boundary, not only in UI state
-- return safe client-facing errors and keep sensitive detail in protected logs
-- document auth, permission, data exposure, rate-limit, and abuse assumptions before changing sensitive flows
-- apply least privilege to service accounts, API tokens, database users, background jobs, and operator/admin actions
-- retrieve secrets through environment, runtime secret injection, or the project's secret manager; do not store static secrets in source or plaintext config
-- keep `.env` and local secret files covered by `.gitignore`; commit only safe examples such as `.env.example`
-- treat transport encryption, secure cookies, and trusted proxy boundaries as deployment assumptions that must be documented when sensitive traffic is involved
+## SEC-001: Hard rules
+
+1. validate and normalize all data crossing a trust boundary
+2. never interpolate untrusted input into queries, shell commands, file paths, templates, logs, or HTML
+3. never commit secrets, tokens, credentials, private keys, or production identifiers
+4. never invent custom crypto, session, token, or password handling when maintained standards exist
+5. enforce authorization at the server or trusted boundary, not only in UI state
+6. return safe client-facing errors and keep sensitive detail in protected logs
+7. document auth, permission, data exposure, rate-limit, and abuse assumptions before changing sensitive flows
+8. apply least privilege to service accounts, API tokens, database users, background jobs, and operator/admin actions
+9. retrieve secrets through environment, runtime secret injection, or the project's secret manager; do not store static secrets in source or plaintext config
+10. keep `.env` and local secret files covered by `.gitignore`; commit only safe examples such as `.env.example`
+11. treat transport encryption, secure cookies, and trusted proxy boundaries as deployment assumptions that must be documented when sensitive traffic is involved
+12. when a public surface exists, record explicit decisions for: CORS allow-list (not `*` for credentialed requests), security headers (CSP, HSTS, `X-Content-Type-Options`, `Referrer-Policy`, `Permissions-Policy`), JWT pitfalls (algorithm pinning, expiration, refresh rotation, storage location), webhook signature verification with timing-safe compare, SSRF defense (egress allow-list or URL validation) when the server fetches user-supplied URLs, and per-resource authorization (not role-only) when records have owners
 
-Zero-trust API input rules:
-- Treat body, query, params, headers, cookies, uploaded files, webhook payloads, and background job payloads as untrusted until validated.
-- Validate and normalize input at the outer boundary before it reaches service, use-case, repository, or domain logic.
-- Services should receive typed, already-validated values and still enforce domain invariants for security-sensitive rules.
-- Sanitization must match the sink: SQL, shell, file path, log, HTML, template, and URL contexts need different protections.
-- Authorization must be resource-aware when data ownership matters. Prefer row, tenant, account, organization, or resource-level checks over role-only checks for sensitive records.
+## SEC-002: Zero-trust API input rules
 
-For high-risk changes, check current framework security docs and record the relevant source or assumption in the implementation notes.
+1. Treat body, query, params, headers, cookies, uploaded files, webhook payloads, and background job payloads as untrusted until validated.
+2. Validate and normalize input at the outer boundary before it reaches service, use-case, repository, or domain logic.
+3. Services should receive typed, already-validated values and still enforce domain invariants for security-sensitive rules.
+4. Sanitization must match the sink: SQL, shell, file path, log, HTML, template, and URL contexts need different protections.
+5. Authorization must be resource-aware when data ownership matters. Prefer row, tenant, account, organization, or resource-level checks over role-only checks for sensitive records.
+6. For high-risk changes, check current framework security docs and record the relevant source or assumption in the implementation notes.

package/.agent-context/rules/testing.md

@@ -1,21 +1,42 @@
+---
+id_prefix: TEST
+domain: testing
+priority: high
+scope: all-tasks
+applies_to:
+  - backend
+  - frontend
+  - fullstack
+keywords:
+  - testing
+  - test
+  - behavior
+  - contract
+  - failure
+  - boundaries
+---
+
 # Testing Boundary
 
-Use the test runner and style already present in the repo. If no test setup exists, the LLM must recommend a current, lightweight, project-fit setup from official docs before adding one.
+Use the test runner and style already present in the repo.
 
-Test what can break:
-- business rules, validation, authorization, state transitions, and error paths
-- public APIs, UI flows, integration boundaries, and data contracts touched by the change
-- regressions around bugs being fixed
-- critical accessibility or responsive behavior when UI is in scope
+## TEST-001: Test Scope
 
-Backend/API test rules:
-- API tests must cover request validation, authorization boundaries, success responses, documented error shapes, pagination defaults, and empty states for touched endpoints.
-- Sensitive mutations such as payments, orders, status changes, inventory adjustments, and account/security changes must include duplicate-submit or retry tests when idempotency is required.
-- Data-access changes must include evidence for query shape, transaction behavior, rollback or recovery paths, and N+1 prevention when relational reads are touched.
-- Event or worker changes must test retry, duplicate-message handling, dead-letter or recovery behavior, and outbox relay semantics when those paths exist.
-- Distributed consistency changes must test the local transaction, publish/retry behavior, and compensating action or recovery path rather than only the happy path.
-- Tests should make the API contract obvious from the fixture names, inputs, and expected response shape.
+1. If no test setup exists, recommend a current, lightweight, project-fit setup from official docs before adding one.
+2. Test what can break: business rules, validation, authorization, state transitions, and error paths.
+3. Test public APIs, UI flows, integration boundaries, and data contracts touched by the change.
+4. Test regressions around bugs being fixed.
+5. Test critical accessibility or responsive behavior when UI is in scope.
+6. Do not test framework internals, third-party library behavior, private implementation trivia, or snapshots that only freeze noise.
+7. Tests should describe behavior, keep setup readable, and mock only at real boundaries such as network, filesystem, clock, database, or external services.
 
-Do not test framework internals, third-party library behavior, private implementation trivia, or snapshots that only freeze noise.
+## TEST-002: Backend and API Test Rules
 
-Tests should describe behavior, keep setup readable, and mock only at real boundaries such as network, filesystem, clock, database, or external services.
+1. API tests must cover request validation, authorization boundaries, success responses, documented error shapes, pagination defaults, and empty states for touched endpoints.
+2. Sensitive mutations such as payments, orders, status changes, inventory adjustments, and account/security changes must include duplicate-submit or retry tests when idempotency is required.
+3. Data-access changes must include evidence for query shape, transaction behavior, rollback or recovery paths, and N+1 prevention when relational reads are touched.
+4. Event or worker changes must test retry, duplicate-message handling, dead-letter or recovery behavior, and outbox relay semantics when those paths exist.
+5. Distributed consistency changes must test the local transaction, publish/retry behavior, and compensating action or recovery path rather than only the happy path.
+6. Tests should make the API contract obvious from the fixture names, inputs, and expected response shape.
+7. Tests must exercise the failure paths the code claims to handle, not only the happy path.
+8. Prefer property-based or generated-input tests for invariants such as validation, ordering, and idempotency; prefer explicit failure-injection tests for retry and recovery code; prefer contract tests at service boundaries when consumer and producer ownership is split.