@ryuenn3123/agentic-senior-core 3.0.50 → 4.0.0

package/.agent-context/review-checklists/pr-checklist.md

@@ -6,6 +6,7 @@ Run this before declaring a task done. Apply only the sections relevant to the c
 
 - [ ] The agent read `AGENTS.md` and the smallest relevant rule set.
 - [ ] For non-trivial coding, review, planning, or governance work, the agent produced a Bootstrap Receipt with loaded files, selected rules, skipped rules, unreachable files, and validation plan before implementation output.
+- [ ] Risky actions used the AGENTS.md Bounded Reflection block with valid rule IDs, one-line rationale, and no copied rule prose or hidden chain-of-thought.
 - [ ] Existing project context came from real files, docs, package metadata, and changed code, not folder name alone.
 - [ ] Runtime, framework, library, topology, and design choices are explicit user constraints or agent recommendations from current evidence.
 - [ ] No offline default stack, blueprint, vendor, or visual style was treated as authoritative.

package/.agent-context/rules/api-docs.md

@@ -1,56 +1,75 @@
-# API and Public Contract Boundary
-
-## Documentation as Hard Rule (Boundary-Aware)
-
-If a change affects an API, CLI command, exported library behavior, schema, event, or integration contract, update the matching docs in the same change.
-
-## Public README Boundary
-
-Root `README.md` is required for every fresh or existing project. This includes private projects, because a future maintainer still needs a clear public and developer entrypoint.
+---
+id_prefix: API
+domain: api-docs
+priority: high
+scope: backend
+applies_to:
+  - backend
+  - fullstack
+keywords:
+  - api-docs
+  - api
+  - contract
+  - documentation
+  - readme
+  - writing
+---
 
-README content must be safe for outside readers and useful for developers. It must explain what the project is, who it is for, how to set it up, how to run the main workflow, how to configure it, and where deeper docs live when those topics apply.
-
-Keep README overview-level. Do not make it the canonical governance source. Do not put secrets, private agent notes, hidden reasoning, backlog chatter, raw architecture debate, or internal policy dumps in it.
+# API and Public Contract Boundary
 
-Choose README sections from project evidence. Do not force a fixed template when a section does not apply. For private/internal projects, keep the same clear style but omit private URLs, credentials, customer names, and internal-only operational details that do not belong in repo docs.
+## API-001: Documentation as Hard Rule (Boundary-Aware)
 
-## Documentation Growth Model
+1. If a change affects an API, CLI command, exported library behavior, schema, event, or integration contract, update the matching docs in the same change.
 
-Documentation must evolve with the project. When behavior, setup, architecture, public contracts, data shape, deployment, or validation changes, update README and the matching docs in the same change.
+## API-002: Public README Boundary
 
-When `docs/` exists, keep `docs/doc-index.md` as the compact routing map for humans and agents. It should list active docs, their purpose, read triggers, status, and last update. It must not duplicate requirements, architecture, or API contracts.
+1. Root `README.md` is required for every fresh or existing project, including private projects, because a future maintainer still needs a clear public and developer entrypoint.
+2. README content must be safe for outside readers and useful for developers.
+3. README content must explain what the project is, who it is for, how to set it up, how to run the main workflow, how to configure it, and where deeper docs live when those topics apply.
+4. Keep README overview-level. Do not make it the canonical governance source. Do not put secrets, private agent notes, hidden reasoning, backlog chatter, raw architecture debate, or internal policy dumps in it.
+5. Choose README sections from project evidence. Do not force a fixed template when a section does not apply.
+6. For private/internal projects, keep the same clear style but omit private URLs, credentials, customer names, and internal-only operational details that do not belong in repo docs.
 
-Start compact, then split only when a topic earns its own file. Good split signals are: the section is long, the workflow is owned separately, the content is referenced often, or the topic needs step-by-step care such as hardware setup, deployment, testing validation, operations, or troubleshooting.
+## API-003: Documentation Growth Model
 
-Use PRD, SRS, technical design, and ERD as conditional docs, not default boilerplate. PRD covers product intent and roadmap ownership. SRS covers contractual or complex acceptance criteria. Technical design covers architecture under pressure. ERD stays inside `docs/database-schema.md` unless the data model is large or relationship-heavy.
+1. Documentation must evolve with the project.
+2. When behavior, setup, architecture, public contracts, data shape, deployment, or validation changes, update README and the matching docs in the same change.
+3. When `docs/` exists, keep `docs/doc-index.md` as the compact routing map for humans and agents. It should list active docs, their purpose, read triggers, status, and last update.
+4. `docs/doc-index.md` must not duplicate requirements, architecture, or API contracts.
+5. Start compact, then split only when a topic earns its own file.
+6. Good split signals are: the section is long, the workflow is owned separately, the content is referenced often, or the topic needs step-by-step care such as hardware setup, deployment, testing validation, operations, or troubleshooting.
+7. Use PRD, SRS, technical design, and ERD as conditional docs, not default boilerplate. PRD covers product intent and roadmap ownership; SRS covers contractual or complex acceptance criteria; technical design covers architecture under pressure; ERD stays inside `docs/database-schema.md` unless the data model is large or relationship-heavy.
 
-## Contract Rules
+## API-004: Public Contract Rules
 
-- Document the public surface before or alongside implementation.
-- Machine-readable API contracts should use the current project standard. If unresolved, the LLM must recommend a current maintained option from official docs.
-- HTTP APIs should prefer OpenAPI 3.1 when no stronger project standard exists.
-- Choose transport (REST, GraphQL, tRPC, gRPC, SSE, WebSocket) and shape (resource-oriented vs action/command-oriented) from domain evidence, not by habit. When the domain has verbs such as cancel, refund, dispatch, approve, or retry, prefer command endpoints over awkward `PATCH` shoehorns and record at least one alternative transport considered.
-- Treat HTTP as a behavioral contract, not just a shape. Document `ETag` and conditional requests for cacheable reads, `Cache-Control` and `Vary` when shared caches apply, rate-limit headers (`RateLimit-*` or `X-RateLimit-*`) with `Retry-After` when rate limiting exists, and require an `Idempotency-Key` request header on unsafe non-idempotent mutations.
-- List endpoints must document pagination, limits, filtering, sorting, and empty-state behavior.
-- Sensitive mutation endpoints must document idempotency behavior, retry safety, duplicate-submit handling, and any required idempotency key or request fingerprint.
-- Public error contracts must document stable machine-readable codes and any RFC 9457 Problem Details-style fields the project exposes, including safe trace or correlation identifiers when present.
-- Async, webhook, and event contracts must document idempotency, retry, ordering, dead-letter or recovery behavior, and duplicate-message handling.
-- Event APIs should define producer, consumer, payload, versioning, retry, and failure behavior.
-- CLI/library public behavior must update README, help text, changelog, or docs as appropriate.
-- Do not write "see code" as the contract.
-- Do not expose generic `object` or `any` contract shapes when the boundary can be typed.
-- Public error shapes must be safe, stable, and documented.
+1. Document the public surface before or alongside implementation.
+2. Machine-readable API contracts should use the current project standard. If unresolved, the LLM must recommend a current maintained option from official docs.
+3. HTTP APIs should prefer OpenAPI 3.1 when no stronger project standard exists.
+4. Choose transport (REST, GraphQL, tRPC, gRPC, SSE, WebSocket) and shape (resource-oriented vs action/command-oriented) from domain evidence, not by habit.
+5. When the domain has verbs such as cancel, refund, dispatch, approve, or retry, prefer command endpoints over awkward `PATCH` shoehorns and record at least one alternative transport considered.
+6. Treat HTTP as a behavioral contract, not just a shape.
+7. Document `ETag` and conditional requests for cacheable reads, `Cache-Control` and `Vary` when shared caches apply, rate-limit headers (`RateLimit-*` or `X-RateLimit-*`) with `Retry-After` when rate limiting exists, and require an `Idempotency-Key` request header on unsafe non-idempotent mutations.
+8. List endpoints must document pagination, limits, filtering, sorting, and empty-state behavior.
 
-## Human Writing Standard (Mandatory)
+## API-005: Boundary Contract Details
 
-This applies to documentation, release notes, onboarding text, review summaries, and agent-facing explanations.
-API docs and README updates are included in this scope.
+1. Sensitive mutation endpoints must document idempotency behavior, retry safety, duplicate-submit handling, and any required idempotency key or request fingerprint.
+2. Public error contracts must document stable machine-readable codes and any RFC 9457 Problem Details-style fields the project exposes, including safe trace or correlation identifiers when present.
+3. Async, webhook, and event contracts must document idempotency, retry, ordering, dead-letter or recovery behavior, and duplicate-message handling.
+4. Event APIs should define producer, consumer, payload, versioning, retry, and failure behavior.
+5. CLI/library public behavior must update README, help text, changelog, or docs as appropriate.
+6. Do not write "see code" as the contract.
+7. Do not expose generic `object` or `any` contract shapes when the boundary can be typed.
+8. Public error shapes must be safe, stable, and documented.
 
-### Language Default
+## API-006: Human Writing Standard (Mandatory)
 
-Write formal project docs in English by default, even when the user prompt is in another language. Use another documentation language only when the user explicitly asks for it or when existing project docs already establish that language.
+1. This applies to documentation, release notes, onboarding text, review summaries, and agent-facing explanations.
+2. API docs and README updates are included in this scope.
+3. Write formal project docs in English by default, even when the user prompt is in another language.
+4. Use another documentation language only when the user explicitly asks for it or when existing project docs already establish that language.
 
-### Style Baseline
+## API-007: Style Baseline
 
 1. Write for native English speakers.
 2. Target an 8th-grade reading level.
@@ -59,7 +78,7 @@ Write formal project docs in English by default, even when the user prompt is in
 5. Sound confident, practical, and conversational.
 6. State the main point first, then supporting detail.
 
-### Required Behavior
+## API-008: Required Writing Behavior
 
 1. Explain decisions the way a competent coworker would explain them out loud.
 2. Cut unnecessary words and remove filler.
@@ -67,27 +86,24 @@ Write formal project docs in English by default, even when the user prompt is in
 4. Rewrite and reorder content when flow is weak.
 5. Keep explanations short by default; expand only when complexity requires it.
 
-### Scope Severity and Merge Behavior
+## API-009: Scope Severity and Merge Behavior
 
 1. Scope style guidance controls readability and consistency.
 2. Style baseline findings are advisory by default and must not block endpoint-change commits that already include accurate docs/spec updates.
 3. Hard blockers remain contract failures: missing same-commit docs sync, incorrect schema, missing required responses, or factual inaccuracies.
 4. If style polish is still needed, open a follow-up task instead of delaying the contract update.
 
-### Non-Negotiables
+## API-010: Non-Negotiables
 
 1. No emoji in formal artifacts.
 2. Avoid AI cliches and buzzwords: delve, leverage, robust, utilize, seamless.
 3. Avoid inflated, academic, or performative language.
 4. Avoid padding, hedging, and redundant phrasing.
 
-### Critical Controls
+## API-011: Critical Controls and Final Check
 
 1. Any claim about quality, performance, or reliability must include a measurable source and timestamp.
 2. Expand acronyms on first use, then use terms consistently.
 3. Separate facts from assumptions explicitly.
 4. End major explanations with a clear next action.
-
-### Final Check
-
-Read the text out loud before shipping. If it sounds robotic, rewrite it.
+5. Read the text out loud before shipping. If it sounds robotic, rewrite it.

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

@@ -1,39 +1,54 @@
+---
+id_prefix: ARCH
+domain: architecture
+priority: critical
+scope: all-tasks
+applies_to:
+  - backend
+  - frontend
+  - fullstack
+keywords:
+  - architecture
+  - arch
+  - separation
+  - concerns
+  - structure
+  - universal
+---
+
 # Architecture - Separation of Concerns and Structure
 
 > If a service imports transport concerns or raw persistence concerns directly, the architecture is already drifting.
 
-## Universal Backend Principles (Mandatory)
-
-These principles are mandatory for backend and shared core modules.
-
-- No clever hacks.
-- No premature abstraction.
-- Readability over brevity.
-- Keep transport, application, domain, and infrastructure concerns separated.
-- Favor explicit module boundaries over hidden cross-layer shortcuts.
-- Health endpoints distinguish liveness (the process is alive), readiness (the process can serve traffic), and startup (initialization complete) where the runtime supports it. A `200 OK` that does not check critical dependencies is not a readiness signal.
-
-## Complexity Budget (Mandatory)
-
-Prefer the smallest clear implementation that fully preserves behavior, safety, and maintainability.
-
-- If two implementations are equivalent in behavior and quality, choose the one with fewer moving parts.
-- Remove code that does not carry behavior, safety, clarity, maintainability, or test value.
-- Prefer direct logic over extra wrappers, layers, classes, config, or state when the abstraction does not reduce real complexity.
-- Keep validation, error handling, fallback paths, accessibility, tests, security boundaries, and observability when they protect real behavior.
-- Run a final simplification pass before completion.
-- Run a domain-fit pass on public contracts before completion: if endpoint names, payload fields, error codes, table names, or event types could be renamed to another domain without changing shape, the contract is too generic; revise to express the actual domain verbs and invariants. This is the backend equivalent of the design rename test.
-- Do not optimize for line count alone.
-- Do not replace clear code with clever, dense, or surprising code.
-- Do not remove safeguards just because the happy path works.
-
-## Universal SOP Baseline (Mandatory)
-
-The `.agent-context/rules/` directory is the default guidance source for implementation and review.
-
-- Backend and frontend mindset checks are both required when a task spans API and UI boundaries.
-- Security and testing are non-negotiable baseline requirements.
-- Hard block before coding:
+## ARCH-001: Universal Backend Principles (Mandatory)
+
+1. These principles are mandatory for backend and shared core modules.
+2. No clever hacks.
+3. No premature abstraction.
+4. Readability over brevity.
+5. Keep transport, application, domain, and infrastructure concerns separated.
+6. Favor explicit module boundaries over hidden cross-layer shortcuts.
+7. Health endpoints distinguish liveness (the process is alive), readiness (the process can serve traffic), and startup (initialization complete) where the runtime supports it. A `200 OK` that does not check critical dependencies is not a readiness signal.
+
+## ARCH-002: Complexity Budget (Mandatory)
+
+1. Prefer the smallest clear implementation that fully preserves behavior, safety, and maintainability.
+2. If two implementations are equivalent in behavior and quality, choose the one with fewer moving parts.
+3. Remove code that does not carry behavior, safety, clarity, maintainability, or test value.
+4. Prefer direct logic over extra wrappers, layers, classes, config, or state when the abstraction does not reduce real complexity.
+5. Keep validation, error handling, fallback paths, accessibility, tests, security boundaries, and observability when they protect real behavior.
+6. Run a final simplification pass before completion.
+7. Run a domain-fit pass on public contracts before completion: if endpoint names, payload fields, error codes, table names, or event types could be renamed to another domain without changing shape, the contract is too generic; revise to express the actual domain verbs and invariants. This is the backend equivalent of the design rename test (see [REF:FE-004]).
+8. Do not optimize for line count alone.
+9. Do not replace clear code with clever, dense, or surprising code.
+10. Do not remove safeguards just because the happy path works.
+
+## ARCH-003: Universal SOP Baseline (Mandatory)
+
+1. The `.agent-context/rules/` directory is the default guidance source for implementation and review.
+2. Backend and frontend mindset checks are both required when a task spans API and UI boundaries.
+3. Security and testing are non-negotiable baseline requirements.
+4. Hard block before coding:
   - Root `README.md` must exist for every fresh or existing project and read as a public and developer entrypoint, not an internal agent note.
   - `docs/doc-index.md` must exist whenever `docs/` exists. It is a compact read-routing map, not a replacement for project docs.
   - `docs/project-brief.md` must exist.
@@ -42,91 +57,89 @@ The `.agent-context/rules/` directory is the default guidance source for impleme
   - If the project uses persistent data, `docs/database-schema.md` must exist.
   - If the project exposes API or web application flows, `docs/api-contract.md` must exist.
   - For UI scope, `docs/DESIGN.md` and `docs/design-intent.json` must exist.
-- Required docs coverage must include a public and developer README entrypoint, feature plan, architecture rationale, public contracts, data model when relevant, UI/design when relevant, security assumptions, testing strategy, delivery flow, and next validation actions.
-- If required project context docs are missing, stop implementation and bootstrap docs before writing application code.
-- Bootstrap flow: analyze the real repo plus the latest user prompt before authoring those docs.
-- Bootstrap docs must be adaptive and project-specific. Do not create generic placeholder templates.
-- When context is incomplete, separate confirmed facts from assumptions, add an `Assumptions to Validate` section, and end with the next validation action.
-- Keep docs current with project changes. Update README and the matching docs whenever setup, runtime, architecture, public contracts, data shape, UI scope, deployment, or validation flow changes.
-- Control docs file count. Keep the baseline compact, then add topic files only when a subject is stable, too long for README/core docs, or belongs to a distinct workflow such as hardware setup, deployment, testing validation, operations, or troubleshooting.
-
-## Documentation Read Routing and Conditional Specs
-
-Use `README.md` for human orientation, then use `docs/doc-index.md` to choose the smallest relevant read set. Do not broad-read every Markdown file in `docs/` by default.
-
-- Read `docs/project-brief.md`, `docs/architecture-decision-record.md`, and `docs/flow-overview.md` for broad planning, new features, or architecture changes.
-- Read `docs/api-contract.md` only when API, CLI, firmware endpoint, web flow, event, or library contract behavior is in scope.
-- Read `docs/database-schema.md` only when persistence, migrations, data shape, or query behavior is in scope.
-- Read `docs/DESIGN.md` and `docs/design-intent.json` only for UI, UX, frontend, layout, component, or visual work.
-- Add `docs/prd.md` only when there is product-roadmap, user-story, metrics, product-owner, or feature-flag ownership that would otherwise bloat the project brief.
-- Add `docs/srs.md` only for contractual, regulated, multi-stakeholder, or acceptance-criteria-heavy projects. Do not create both PRD and SRS unless those owners and purposes are distinct.
-- Add `docs/technical-design.md` only for non-trivial architecture decisions, major refactors, cross-cutting behavior, or system interactions that outgrow the ADR and flow overview.
-- Keep ERD inside `docs/database-schema.md` for small and medium schemas. Add a separate ERD file only when relationship complexity makes the schema doc hard to scan.
-
-## Rules as Guardian (Cross-Session Consistency)
-
-- Session handoff must include active architecture contract summary.
-- Contract summary must include explicit user constraints, runtime/architecture decision status, active project docs, and the core patterns currently evidenced by the repo.
-- Detect drift before changing runtime choices, topology, public contracts, or core patterns.
-- Direction changes require explicit user confirmation before applying changes.
-- When confirmation is provided, record the rationale in session notes or PR context.
-
-## Invisible State Management with Explain-on-Demand
-
-- Default responses must avoid unnecessary state-file internals.
-- State internals are exposed only on explicit user request.
-- Diagnostic mode explains relevant state decisions when needed.
-- Keep default explanations concise and outcome-first.
-
-## Single Source of Truth and Lazy Rule Loading
-
-- Canonical rule source is AGENTS.md.
-- Native adapter entry files stay thin and must import the canonical source.
-- Load global domain rules lazily based on touched scope.
-- Do not create or load stack-specific governance adapters as the baseline.
-- Runtime or framework evidence can clarify implementation details, but it must not replace the global architecture, security, data, API, error, event, and testing boundaries.
-- Keep rule-loading output deterministic for init and release validation.
-
-## Architecture Decision Boundary
-
-Do not force a default architecture label before the repo, delivery model, and boundary evidence are clear.
-
-Do not split into distributed services without evidence. Do not keep everything in one process by habit either.
-
-Service separation only makes sense when multiple signals are true, such as:
-
-- frequent deploy conflicts across domains
-- clear scale mismatch between domains
-- separate team ownership causing repeated coupling pain
-- hard fault-isolation requirements
-- already-stable contracts and data boundaries
-
-## Layer Boundaries (Mandatory)
-
-- Transport or controller layer: parse input, validate shape, enforce auth at the edge, return protocol responses. No business policy, no raw SQL, no external workflow orchestration.
-- Application or service layer: business rules, orchestration, transactions, and use-case flow. No request or response objects, no UI formatting, no raw transport dependencies.
-- Domain layer: pure business invariants, calculations, value objects, and policies. No framework, network, database, or file-system coupling.
-- Infrastructure or repository layer: database, queue, cache, file system, and external API adapters. No business policy hidden in queries or adapters.
-
-## Dependency Direction
-
-- Dependencies flow inward: transport to application to domain.
-- Infrastructure depends inward through interfaces or well-defined ports.
-- Domain must not depend on infrastructure.
-- Application must not depend on transport details.
-
-## Project Structure and File Size Discipline
-
-- Group code by feature or domain, not by one giant technical folder per type.
-- Backend feature modules use `src/modules/<feature>/...` when the repo has no stronger existing convention.
-- Frontend feature modules use `src/features/<feature>/...` when the repo has no stronger existing convention.
-- Cross-cutting utilities belong in explicit shared locations, not scattered feature internals.
-- Files above roughly 1000 lines are a refactor trigger, not a success signal.
-- Preserve one clear public entrypoint per module when helpful, but move implementation into smaller focused files.
-- Keep code compact because the design is understood, not because safeguards were removed.
-
-## Module Communication
-
-- Import through a module's public API instead of reaching into internal files.
-- Keep contracts explicit at boundaries between modules.
-- If a new developer cannot find the full flow of a feature in one clear area, the structure is too diffuse.
+5. Required docs coverage must include a public and developer README entrypoint, feature plan, architecture rationale, public contracts, data model when relevant, UI/design when relevant, security assumptions, testing strategy, delivery flow, and next validation actions.
+6. If required project context docs are missing, stop implementation and bootstrap docs before writing application code.
+7. Bootstrap flow: analyze the real repo plus the latest user prompt before authoring those docs.
+8. Bootstrap docs must be adaptive and project-specific. Do not create generic placeholder templates.
+9. When context is incomplete, separate confirmed facts from assumptions, add an `Assumptions to Validate` section, and end with the next validation action.
+10. Keep docs current with project changes. Update README and the matching docs whenever setup, runtime, architecture, public contracts, data shape, UI scope, deployment, or validation flow changes.
+11. Control docs file count. Keep the baseline compact, then add topic files only when a subject is stable, too long for README/core docs, or belongs to a distinct workflow such as hardware setup, deployment, testing validation, operations, or troubleshooting.
+
+## ARCH-004: Documentation Read Routing and Conditional Specs
+
+1. Use `README.md` for human orientation, then use `docs/doc-index.md` to choose the smallest relevant read set.
+2. Do not broad-read every Markdown file in `docs/` by default.
+3. Read `docs/project-brief.md`, `docs/architecture-decision-record.md`, and `docs/flow-overview.md` for broad planning, new features, or architecture changes.
+4. Read `docs/api-contract.md` only when API, CLI, firmware endpoint, web flow, event, or library contract behavior is in scope.
+5. Read `docs/database-schema.md` only when persistence, migrations, data shape, or query behavior is in scope.
+6. Read `docs/DESIGN.md` and `docs/design-intent.json` only for UI, UX, frontend, layout, component, or visual work.
+7. Add `docs/prd.md` only when there is product-roadmap, user-story, metrics, product-owner, or feature-flag ownership that would otherwise bloat the project brief.
+8. Add `docs/srs.md` only for contractual, regulated, multi-stakeholder, or acceptance-criteria-heavy projects. Do not create both PRD and SRS unless those owners and purposes are distinct.
+9. Add `docs/technical-design.md` only for non-trivial architecture decisions, major refactors, cross-cutting behavior, or system interactions that outgrow the ADR and flow overview.
+10. Keep ERD inside `docs/database-schema.md` for small and medium schemas. Add a separate ERD file only when relationship complexity makes the schema doc hard to scan.
+
+## ARCH-005: Rules as Guardian (Cross-Session Consistency)
+
+1. Session handoff must include active architecture contract summary.
+2. Contract summary must include explicit user constraints, runtime/architecture decision status, active project docs, and the core patterns currently evidenced by the repo.
+3. Detect drift before changing runtime choices, topology, public contracts, or core patterns.
+4. Direction changes require explicit user confirmation before applying changes.
+5. When confirmation is provided, record the rationale in session notes or PR context.
+
+## ARCH-006: Invisible State Management with Explain-on-Demand
+
+1. Default responses must avoid unnecessary state-file internals.
+2. State internals are exposed only on explicit user request.
+3. Diagnostic mode explains relevant state decisions when needed.
+4. Keep default explanations concise and outcome-first.
+
+## ARCH-007: Single Source of Truth and Lazy Rule Loading
+
+1. Canonical rule source is AGENTS.md.
+2. Native adapter entry files stay thin and must import the canonical source.
+3. Load global domain rules lazily based on touched scope.
+4. Do not create or load stack-specific governance adapters as the baseline.
+5. Runtime or framework evidence can clarify implementation details, but it must not replace the global architecture, security, data, API, error, event, and testing boundaries.
+6. Keep rule-loading output deterministic for init and release validation.
+
+## ARCH-008: Architecture Decision Boundary
+
+1. Do not force a default architecture label before the repo, delivery model, and boundary evidence are clear.
+2. Do not split into distributed services without evidence.
+3. Do not keep everything in one process by habit either.
+4. Service separation only makes sense when multiple signals are true, such as:
+5. frequent deploy conflicts across domains
+6. clear scale mismatch between domains
+7. separate team ownership causing repeated coupling pain
+8. hard fault-isolation requirements
+9. already-stable contracts and data boundaries
+
+## ARCH-009: Layer Boundaries (Mandatory)
+
+1. Transport or controller layer: parse input, validate shape, enforce auth at the edge, return protocol responses. No business policy, no raw SQL, no external workflow orchestration.
+2. Application or service layer: business rules, orchestration, transactions, and use-case flow. No request or response objects, no UI formatting, no raw transport dependencies.
+3. Domain layer: pure business invariants, calculations, value objects, and policies. No framework, network, database, or file-system coupling.
+4. Infrastructure or repository layer: database, queue, cache, file system, and external API adapters. No business policy hidden in queries or adapters.
+
+## ARCH-010: Dependency Direction
+
+1. Dependencies flow inward: transport to application to domain.
+2. Infrastructure depends inward through interfaces or well-defined ports.
+3. Domain must not depend on infrastructure.
+4. Application must not depend on transport details.
+
+## ARCH-011: Project Structure and File Size Discipline
+
+1. Group code by feature or domain, not by one giant technical folder per type.
+2. Backend feature modules use `src/modules/<feature>/...` when the repo has no stronger existing convention.
+3. Frontend feature modules use `src/features/<feature>/...` when the repo has no stronger existing convention.
+4. Cross-cutting utilities belong in explicit shared locations, not scattered feature internals.
+5. Files above roughly 1000 lines are a refactor trigger, not a success signal.
+6. Preserve one clear public entrypoint per module when helpful, but move implementation into smaller focused files.
+7. Keep code compact because the design is understood, not because safeguards were removed.
+
+## ARCH-012: Module Communication
+
+1. Import through a module's public API instead of reaching into internal files.
+2. Keep contracts explicit at boundaries between modules.
+3. If a new developer cannot find the full flow of a feature in one clear area, the structure is too diffuse.

package/.agent-context/rules/database-design.md

@@ -1,24 +1,42 @@
+---
+id_prefix: DATA
+domain: database-design
+priority: high
+scope: data
+applies_to:
+  - backend
+  - fullstack
+keywords:
+  - database-design
+  - data
+  - design
+  - boundary
+  - reject
+  - these
+---
+
 # Data Design Boundary
 
 Use the data store, ORM, migration tool, and query style already chosen by the project. If unresolved, the LLM must recommend a current fit from requirements, repo evidence, and official docs before implementation.
 
-Reject these bad habits:
-- schema changes without a migration, rollback or recovery note, and data-safety plan
-- duplicated facts or derived values without a sync strategy and rationale
-- unbounded reads or missing pagination on growable datasets
-- missing indexes or access-path planning for frequent filters, joins, lookups, search, or ordering
-- raw query construction that bypasses safe parameterization
-- destructive data changes without backup, migration, or deployment sequencing notes
+## DATA-001: Reject these bad habits
+
+1. schema changes without a migration, rollback or recovery note, and data-safety plan
+2. duplicated facts or derived values without a sync strategy and rationale
+3. unbounded reads or missing pagination on growable datasets
+4. missing indexes or access-path planning for frequent filters, joins, lookups, search, or ordering
+5. raw query construction that bypasses safe parameterization
+6. destructive data changes without backup, migration, or deployment sequencing notes
 
-Backend data access rules:
-- Relational reads must avoid N+1 query patterns. Use eager loading, joins, batching, or explicit query-shape rationale based on the project's ORM or database driver.
-- List endpoints and exports must paginate, limit, stream, or otherwise bound growable datasets by default.
-- Use cursor pagination for large or frequently changing datasets when the project contract allows it; offset pagination is acceptable for small, stable, explicitly bounded collections.
-- Define maximum page size, payload size, and export limits so list responses cannot exhaust memory or connection pools.
-- Mutations that write more than one table, aggregate, queue, or external consistency boundary must run inside a transaction or document the compensating recovery path.
-- Repository and data-access layers own persistence mechanics. They must not hide business policy that belongs in application or domain logic.
-- Index design follows read patterns, not column lists. Prefer composite indexes with selectivity-correct column order (equality before range), partial indexes for soft-delete or status-filtered tables, and covering indexes when a hot read can be satisfied without a heap fetch. Record the read pattern that justifies each non-trivial index.
-- Record explicit decisions for delete semantics (hard delete, soft delete, append-only audit), tenant isolation (none, row-level with `tenant_id` plus row-level security, schema-per-tenant), and normalize-vs-denormalize trade-off for read-heavy or sparse data. Default to the simplest fit, but make the choice explicit in data docs rather than letting it become a side effect of the first migration.
-- Cross-domain persistence must respect ownership boundaries. Independent services must not share database tables as an integration contract; modular monoliths may share one database only when module ownership and access paths stay explicit.
+## DATA-002: Backend data access rules
 
-Docs must record entity ownership, relationships, constraints, data lifecycle, migration risk, and assumptions to validate.
+1. Relational reads must avoid N+1 query patterns. Use eager loading, joins, batching, or explicit query-shape rationale based on the project's ORM or database driver.
+2. List endpoints and exports must paginate, limit, stream, or otherwise bound growable datasets by default.
+3. Use cursor pagination for large or frequently changing datasets when the project contract allows it; offset pagination is acceptable for small, stable, explicitly bounded collections.
+4. Define maximum page size, payload size, and export limits so list responses cannot exhaust memory or connection pools.
+5. Mutations that write more than one table, aggregate, queue, or external consistency boundary must run inside a transaction or document the compensating recovery path.
+6. Repository and data-access layers own persistence mechanics. They must not hide business policy that belongs in application or domain logic.
+7. Index design follows read patterns, not column lists. Prefer composite indexes with selectivity-correct column order (equality before range), partial indexes for soft-delete or status-filtered tables, and covering indexes when a hot read can be satisfied without a heap fetch. Record the read pattern that justifies each non-trivial index.
+8. Record explicit decisions for delete semantics (hard delete, soft delete, append-only audit), tenant isolation (none, row-level with `tenant_id` plus row-level security, schema-per-tenant), and normalize-vs-denormalize trade-off for read-heavy or sparse data. Default to the simplest fit, but make the choice explicit in data docs rather than letting it become a side effect of the first migration.
+9. Cross-domain persistence must respect ownership boundaries. Independent services must not share database tables as an integration contract; modular monoliths may share one database only when module ownership and access paths stay explicit.
+10. Docs must record entity ownership, relationships, constraints, data lifecycle, migration risk, and assumptions to validate.