@ryuenn3123/agentic-senior-core 3.0.50 → 4.0.1

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.

package/.agent-context/rules/docker-runtime.md

@@ -1,47 +1,70 @@
+---
+id_prefix: DOCK
+domain: docker-runtime
+priority: high
+scope: infra
+applies_to:
+  - backend
+  - frontend
+  - fullstack
+keywords:
+  - docker-runtime
+  - dock
+  - docker
+  - runtime
+---
+
 # Docker Runtime Strategy (Dynamic Generation Required)
 
 Use this rule when Docker is enabled in project context.
 
-## 0. Latest Official Docker Guidance First
-- Before generating or changing Dockerfiles, Compose files, or container runbooks, verify the latest official Docker documentation first.
-- Use official Docker sources such as [Docker Compose Quickstart](https://docs.docker.com/compose/gettingstarted/), [Compose file reference](https://docs.docker.com/reference/compose-file/), and [Dockerfile best practices](https://docs.docker.com/build/building/best-practices/).
-- Use current `docker compose` workflows and `compose.yaml`. Do not default to legacy `docker-compose` commands or stale file naming unless backward compatibility is a stated project requirement.
-- Do not add the top-level Compose `version` field by default. The current Compose reference treats it as obsolete. Use it only when a compatibility requirement is explicit and documented.
-- Use the latest stable compatible Docker base image, package-manager flow, and Compose syntax first. If the latest compatible path fails, step down intentionally and document the exact reason for the fallback.
-
-## 1. Dynamic Generation Only
-- Do not copy generic Docker templates blindly.
-- Generate Docker assets based on actual stack, package manager, and runtime dependencies in the repository.
-- Re-evaluate Docker instructions when dependencies, build tools, or runtime assumptions change.
-- Use the latest stable compatible dependency line first. If an older dependency or base image must be pinned, explain the runtime or compatibility constraint that forced it.
-
-## 2. Separate Development and Production Lanes
-- Development lane and production lane are separate concerns.
-- Development lane priorities: fast rebuild, hot reload support, debugger-friendly startup, local volume strategy.
-- Production lane priorities: minimal image size, reproducible build, non-root runtime, strict startup command.
-
-## 3. Selection Means Asset Materialization
-- If Docker is selected for development, create or refine `.dockerignore`, development Dockerfile stage(s), `compose.yaml`, and a runbook before claiming the setup is complete.
-- If Docker is selected for production, create or refine production Dockerfile stage(s), `compose.prod.yaml` or a documented production Compose override, health checks or startup checks, exposed ports, and a deployment runbook before claiming the setup is complete.
-- If Docker is selected for both lanes, keep development and production assets separate enough that hot reload, bind mounts, debug tooling, and production runtime hardening cannot blur into one unsafe path.
-- If the user asks to author files without commands, write the assets and documented commands, but do not execute Docker build, Compose, or registry commands.
-
-## 4. Security and Supply Chain
-- Use minimal trusted base images with explicit versions.
-- Use multi-stage builds for production images when possible.
-- Avoid baking secrets into image layers.
-- Keep runtime image free from build-only tooling.
-- Use fresh base-image validation with `docker build --pull` and use `--no-cache` when a clean dependency refresh is required.
-- Keep a `.dockerignore` strategy in mind so build contexts stay small and do not leak unnecessary files into the image.
-
-## 5. Operational Clarity
-- Docker instructions must document expected entrypoint and exposed ports.
-- Local development command and production deployment command must be explicit.
-- If Docker is not selected for the project, do not force containerization tasks.
-- If Compose is used, document which file is the primary entrypoint, which services are dev-only versus production-facing, and why the chosen layout matches the current Docker docs rather than a legacy blog pattern.
-
-## 6. Review Requirements
-- Verify the generated Docker workflow matches selected runtime environment (Linux/WSL, Windows, macOS).
-- Verify development and production instructions are not mixed into one unsafe image path.
-- Ensure API and service health checks are compatible with container startup behavior.
-- When Docker choices depend on official docs or release behavior, cite the Docker source and verification date in the generated docs or explanation so the next update can refresh them safely.
+## DOCK-001: Latest Official Docker Guidance First
+
+1. Before generating or changing Dockerfiles, Compose files, or container runbooks, verify the latest official Docker documentation first.
+2. Use official Docker sources such as [Docker Compose Quickstart](https://docs.docker.com/compose/gettingstarted/), [Compose file reference](https://docs.docker.com/reference/compose-file/), and [Dockerfile best practices](https://docs.docker.com/build/building/best-practices/).
+3. Use current `docker compose` workflows and `compose.yaml`. Do not default to legacy `docker-compose` commands or stale file naming unless backward compatibility is a stated project requirement.
+4. Do not add the top-level Compose `version` field by default. The current Compose reference treats it as obsolete. Use it only when a compatibility requirement is explicit and documented.
+5. Use the latest stable compatible Docker base image, package-manager flow, and Compose syntax first. If the latest compatible path fails, step down intentionally and document the exact reason for the fallback.
+
+## DOCK-002: Dynamic Generation Only
+
+1. Do not copy generic Docker templates blindly.
+2. Generate Docker assets based on actual stack, package manager, and runtime dependencies in the repository.
+3. Re-evaluate Docker instructions when dependencies, build tools, or runtime assumptions change.
+4. Use the latest stable compatible dependency line first. If an older dependency or base image must be pinned, explain the runtime or compatibility constraint that forced it.
+
+## DOCK-003: Separate Development and Production Lanes
+
+1. Development lane and production lane are separate concerns.
+2. Development lane priorities: fast rebuild, hot reload support, debugger-friendly startup, local volume strategy.
+3. Production lane priorities: minimal image size, reproducible build, non-root runtime, strict startup command.
+
+## DOCK-004: Selection Means Asset Materialization
+
+1. If Docker is selected for development, create or refine `.dockerignore`, development Dockerfile stage(s), `compose.yaml`, and a runbook before claiming the setup is complete.
+2. If Docker is selected for production, create or refine production Dockerfile stage(s), `compose.prod.yaml` or a documented production Compose override, health checks or startup checks, exposed ports, and a deployment runbook before claiming the setup is complete.
+3. If Docker is selected for both lanes, keep development and production assets separate enough that hot reload, bind mounts, debug tooling, and production runtime hardening cannot blur into one unsafe path.
+4. If the user asks to author files without commands, write the assets and documented commands, but do not execute Docker build, Compose, or registry commands.
+
+## DOCK-005: Security and Supply Chain
+
+1. Use minimal trusted base images with explicit versions.
+2. Use multi-stage builds for production images when possible.
+3. Avoid baking secrets into image layers.
+4. Keep runtime image free from build-only tooling.
+5. Use fresh base-image validation with `docker build --pull` and use `--no-cache` when a clean dependency refresh is required.
+6. Keep a `.dockerignore` strategy in mind so build contexts stay small and do not leak unnecessary files into the image.
+
+## DOCK-006: Operational Clarity
+
+1. Docker instructions must document expected entrypoint and exposed ports.
+2. Local development command and production deployment command must be explicit.
+3. If Docker is not selected for the project, do not force containerization tasks.
+4. If Compose is used, document which file is the primary entrypoint, which services are dev-only versus production-facing, and why the chosen layout matches the current Docker docs rather than a legacy blog pattern.
+
+## DOCK-007: Review Requirements
+
+1. Verify the generated Docker workflow matches selected runtime environment (Linux/WSL, Windows, macOS).
+2. Verify development and production instructions are not mixed into one unsafe image path.
+3. Ensure API and service health checks are compatible with container startup behavior.
+4. When Docker choices depend on official docs or release behavior, cite the Docker source and verification date in the generated docs or explanation so the next update can refresh them safely.

package/.agent-context/rules/efficiency-vs-hype.md

@@ -1,24 +1,45 @@
-# Dependency and Tooling Boundary
+---
+id_prefix: DEP
+domain: efficiency-vs-hype
+priority: medium
+scope: all-tasks
+applies_to:
+  - backend
+  - frontend
+  - fullstack
+keywords:
+  - efficiency-vs-hype
+  - dep
+  - dependency
+  - latest-compatible-first
+---
 
-## Latest-Compatible-First Rule
+# Dependency and Tooling Boundary
 
-The LLM may choose modern libraries and tooling when they fit the project. This rule does not prefer "no library", "always add a library", or any fixed dependency set.
+## DEP-001: Latest-Compatible-First Rule
 
-New dependencies are allowed when they create a better practical tradeoff than custom implementation. The decision should be based on whether the dependency meaningfully improves efficiency, shortens delivery time, improves correctness, reduces maintenance burden, unlocks a stronger user experience, or avoids unnecessary in-house code.
+1. The LLM may choose modern libraries and tooling when they fit the project.
+2. This rule does not prefer "no library", "always add a library", or any fixed dependency set.
+3. New dependencies are allowed when they create a better practical tradeoff than custom implementation.
+4. The decision should be based on whether the dependency meaningfully improves efficiency, shortens delivery time, improves correctness, reduces maintenance burden, unlocks a stronger user experience, or avoids unnecessary in-house code.
+5. Do not treat dependency avoidance as an engineering virtue by itself.
+6. A small, maintained, well-scoped library can be the simpler and safer choice than custom code, especially for accessibility primitives, animation, gestures, data visualization, parsing, protocol handling, security-sensitive helpers, or browser/runtime capabilities with tricky edge cases.
 
-Do not treat dependency avoidance as an engineering virtue by itself. A small, maintained, well-scoped library can be the simpler and safer choice than custom code, especially for accessibility primitives, animation, gestures, data visualization, parsing, protocol handling, security-sensitive helpers, or browser/runtime capabilities with tricky edge cases.
+## DEP-002: Before adding or recommending a dependency
 
-Before adding or recommending a dependency:
-- check current official docs, release notes, and setup guidance when the ecosystem decision matters
-- choose the latest stable compatible dependency version unless a project constraint blocks it
-- use the official scaffolder or setup command when it creates the current supported project shape
-- do not hand-assemble fresh framework projects by habit when the official setup flow gives safer current defaults; document the reason when manual assembly is better
-- Only step down to an older dependency version after documenting the exact compatibility, runtime, platform, or ecosystem reason.
-- explain why the dependency is a better tradeoff than local implementation for the current task
-- avoid packages that are stale, thinly maintained, too heavy for the job, or added only because they are popular
-- keep dependency boundaries replaceable when the library would spread through many files
-- do not reject a dependency only because it adds a package; reject it only when the project-fit, security, maintenance, compatibility, bundle/runtime, or ownership tradeoff is worse than the alternative
+1. check current official docs, release notes, and setup guidance when the ecosystem decision matters
+2. choose the latest stable compatible dependency version unless a project constraint blocks it
+3. use the official scaffolder or setup command when it creates the current supported project shape
+4. do not hand-assemble fresh framework projects by habit when the official setup flow gives safer current defaults; document the reason when manual assembly is better
+5. Only step down to an older dependency version after documenting the exact compatibility, runtime, platform, or ecosystem reason.
+6. explain why the dependency is a better tradeoff than local implementation for the current task
+7. avoid packages that are stale, thinly maintained, too heavy for the job, or added only because they are popular
+8. keep dependency boundaries replaceable when the library would spread through many files
+9. do not reject a dependency only because it adds a package; reject it only when the project-fit, security, maintenance, compatibility, bundle/runtime, or ownership tradeoff is worse than the alternative
 
-Reject offline dependency decisions, outdated tutorial versions, trend choices, dependency avoidance choices, and performance-fear choices that are not grounded in the current repo, brief, and delivery tradeoffs.
+## DEP-003: Framework and offline decision boundaries
 
-Reject framework autopilot, not frameworks. Next.js, Vite, Astro, React Router, SvelteKit, Laravel, plain HTML, and other runtimes are candidates, not defaults or forbidden choices. If the user did not constrain the stack, compare at least the strongest fit and one plausible alternative before implementation, then choose the technology that removes bottlenecks for this project.
+1. Reject offline dependency decisions, outdated tutorial versions, trend choices, dependency avoidance choices, and performance-fear choices that are not grounded in the current repo, brief, and delivery tradeoffs.
+2. Reject framework autopilot, not frameworks.
+3. Next.js, Vite, Astro, React Router, SvelteKit, Laravel, plain HTML, and other runtimes are candidates, not defaults or forbidden choices.
+4. If the user did not constrain the stack, compare at least the strongest fit and one plausible alternative before implementation, then choose the technology that removes bottlenecks for this project.

package/.agent-context/rules/error-handling.md

@@ -1,22 +1,41 @@
+---
+id_prefix: ERR
+domain: error-handling
+priority: high
+scope: all-tasks
+applies_to:
+  - backend
+  - frontend
+  - fullstack
+keywords:
+  - error-handling
+  - err
+  - error
+  - handling
+  - boundary
+  - reject
+---
+
 # Error Handling Boundary
 
 Use the target language and framework's normal error model. Do not invent a custom exception architecture from this repo.
 
-Reject these failure patterns:
-- swallowed errors
-- generic errors that erase the domain cause
-- client-facing leaks of stack traces, secrets, SQL, infrastructure details, or provider internals
-- retries without transient-failure evidence, limits, backoff, and a clear final outcome
-- logs that say only "something failed" without action, target, actor, or trace context
+## ERR-001: Reject these failure patterns
+
+1. swallowed errors
+2. generic errors that erase the domain cause
+3. client-facing leaks of stack traces, secrets, SQL, infrastructure details, or provider internals
+4. retries without transient-failure evidence, limits, backoff, and a clear final outcome
+5. logs that say only "something failed" without action, target, actor, or trace context
 
-Backend API error rules:
-- Use the framework's normal centralized error boundary or middleware for HTTP/API responses.
-- Do not return raw exception messages, stack traces, SQL, provider payloads, file paths, secrets, or infrastructure details to callers.
-- Public API errors must use a stable JSON shape with at least `code` and `message`; include `details` only when the data is safe, documented, and useful to the caller. HTTP APIs may use an RFC 9457 Problem Details-style shape when it fits the project contract.
-- Domain and validation errors should keep machine-readable codes so tests, clients, and operators can distinguish expected failures from defects.
-- API boundary errors should include a safe correlation or trace identifier when observability exists, while protected logs keep the internal exception, actor, target, and trace context.
-- Distributed systems should preserve trace context across ingress and egress using the project's tracing standard, such as W3C Trace Context or OpenTelemetry propagation.
-- Prefer structured logging (key/value or JSON) over free-text strings, record at least one business metric per non-trivial operation alongside system metrics, and propagate correlation/trace IDs across async, queue, and worker boundaries.
-- Distinguish error reporting from error recovery. For calls to unreliable upstreams, record the recovery strategy: retry with backoff and jitter, circuit-breaker thresholds and reset behavior, fallback path (cached value, default, degraded mode), and partial-failure semantics for batch operations (per-item success/failure rather than all-or-nothing). "Catch and log" is reporting, not recovery.
+## ERR-002: Backend API error rules
 
-At boundaries, validate early, return safe user-facing errors, and keep machine-readable error context for operators and callers.
+1. Use the framework's normal centralized error boundary or middleware for HTTP/API responses.
+2. Do not return raw exception messages, stack traces, SQL, provider payloads, file paths, secrets, or infrastructure details to callers.
+3. Public API errors must use a stable JSON shape with at least `code` and `message`; include `details` only when the data is safe, documented, and useful to the caller. HTTP APIs may use an RFC 9457 Problem Details-style shape when it fits the project contract.
+4. Domain and validation errors should keep machine-readable codes so tests, clients, and operators can distinguish expected failures from defects.
+5. API boundary errors should include a safe correlation or trace identifier when observability exists, while protected logs keep the internal exception, actor, target, and trace context.
+6. Distributed systems should preserve trace context across ingress and egress using the project's tracing standard, such as W3C Trace Context or OpenTelemetry propagation.
+7. Prefer structured logging (key/value or JSON) over free-text strings, record at least one business metric per non-trivial operation alongside system metrics, and propagate correlation/trace IDs across async, queue, and worker boundaries.
+8. Distinguish error reporting from error recovery. For calls to unreliable upstreams, record the recovery strategy: retry with backoff and jitter, circuit-breaker thresholds and reset behavior, fallback path (cached value, default, degraded mode), and partial-failure semantics for batch operations (per-item success/failure rather than all-or-nothing). "Catch and log" is reporting, not recovery.
+9. At boundaries, validate early, return safe user-facing errors, and keep machine-readable error context for operators and callers.